josuah.net | panoramix-labs.fr

cv | links | quotes | ascii | tgtimes | gopher | mail

Style fixes

The coding style for naming and comments differs a lot through the various ports. As you asked to start with naming fixes:

Naming

Hard to change for header files without breaking changes. People using some port would have to update their code.

Easier for source files as we can run make and catch everything here.

Common source files:

Common header files:

Comments

Not breaking anything except ongoing pull requests. Differ from family to family, and someone within families.

1:

/** @brief RTC set Prescaler value.
 *
 * @details The clock needs to be stopped for this to have any effect.
 *
 * @param[in] rtc uint32_t RTC base
 * @param[in] presc uint16_t 12 bit prescaler value.
 */

2:

/*---------------------------------------------------------------------------*/
/** @brief ADC Set the Sample Time for a Single Channel

The sampling time can be selected in ADC clock cycles from 1.5 to 239.5.

@param[in] adc Unsigned int32. ADC block register address base @ref adc_reg_base
@param[in] channel Unsigned int8. ADC Channel integer 0..18 or from @ref
adc_channel
@param[in] time Unsigned int8. Sampling time selection from @ref adc_sample_rg
 * NOTE Common with f1, f2 and f37x
*/

3:

/* Initialization template for the interrupt vector table. This definition is
 * used by the startup code generator (vector.c) to set the initial values for
 * the interrupt handling routines to the chip family specific _isr weak
 * symbols. */

/** @defgroup CM3_nvic_isrdecls_SAM3A User interrupt service routines (ISR) defaults for Atmel SAM3A series
    @ingroup CM3_nvic_isrdecls

    @{*/

4:

/**
 * Set ADC warm up
 * @param[in] adc ADC (use ADCx)
 * @param[in] clocks Clock cycles (1 - 128)
 * @note warm-up-time = (@a clocks / HFPERCLK)
 */

5:

/** Clock division factor
 * @param[in] adc ADC (use ADCx)
 * @param[in] factor Factor (1 - 128)
 * @note output-clock = input-clock / @a factor
 */

6:

/**
 * @defgroup crc_polysize CRC Polynomial size
 * @{
 */

7:

/** @defgroup crc_rev_in CRC Reverse input options
 @{*/

8:

/** @defgroup system_peripheral_addresses System Peripheral Memory Map.
@{*/

9:

/** @brief Called on a failed assertion.
 *
 * Halts execution in an infinite loop. This function never returns.
 *
 * Defined as a weak symbol, so applications can define their own
 * implementation. Usually, a custom implementation of this function should
 * report an error in some way (print a message to a debug console, display,
 * LED, ...) and halt execution or reboot the device. */

Separators

Not always present, more often

1:

/* Scan ------------------------------------------------------------- */

2:

/* Scan --------------------------------------------------------------*/

3:

/* --- ANADIG values -....-------------------------------------------------- */

4:

/* --- ANADIG registers ---------------------------------------------------- */

5:

/*****************************************************************************/
/* Module definitions                                                        */
/*****************************************************************************/

6:

/*---------------------------------------------------------------------------*/

Ifdef guards

Avoid double-inclusion, frequent when there are #include in headers.

(6) generalized would permit to prevent including individual port's declaration directly.

1:

#ifndef LIBOPENCM3_MEMORYMAP_COMMON_H
#define LIBOPENCM3_MEMORYMAP_COMMON_H
...
#endif /* LIBOPENCM3_MEMORYMAP_COMMON_H */

2: (nothing)

3:

#pragma once

4:

#ifndef LM3S_MEMORYMAP_H
#define LM3S_MEMORYMAP_H
...
#endif

5:

#ifndef INCLUDE_LIBOPENCM3_PAC55XX_MEMORYMAP_H_
#define INCLUDE_LIBOPENCM3_PAC55XX_MEMORYMAP_H_
...
#endif /* INCLUDE_LIBOPENCM3_PAC55XX_MEMORYMAP_H_ */

6: Only found in dispatch/* but could be applied to common peripherals as well.

#ifndef LIBOPENCM3_NVIC_H
#error You should not be including this file directly, but <libopencm3/cm3/nvic.h>
#endif