How to leverage Board Files in ChibiOS

Introduction

The board files are a critical component of a ChibiOS-based project. They define how peripherals are connected to the microcontroller and provide information related to key elements that depend on the board in use. This article will discuss what board files are in ChibiOS, their role in a project, and how to generate customized ones.

Board files explained

Board files are platform-dependent source files that handle low-level functionality. They provide some board-specific configurations, the pin and line identifiers and they initialize the whole GPIO memory bank before the user application starts.

Board-specific configurations

Microcontrollers are very flexible and they can work with different levels of voltage as well as different clock sources (internal and external). However to work properly the clock tree and the power management unit needs to be appropriately configured. Some boards can be equipped with special physical layers (PHY) to implement communication stacks such as the USB Low Power Interface (ULPI) or the Ethernet PHY. To work properly, ChibiOS/HAL needs to be aware of these board-dependent configurations and these are provided in the board files.

For instance, the opening code of the SDP-K1 board header file shows the initial definitions related to the low-speed and high-speed external clocks (STM32_LSECLK and STM32_HSECLK), followed by the specification of the MCU voltage and type. These values are internally used to calculate the clock-tree speed and power management limits and ensure that the absolute maximum values specified in the datasheet are not exceeded.

/*
 * Board identifier.
 */
#define BOARD_ADI_EVAL_SDP_CK1Z
#define BOARD_NAME                  "Analog Devices SDP-CK1Z"
/*
 * The board has an ULPI USB PHY.
 */
#define BOARD_OTG2_USES_ULPI
/*
 * Board oscillators-related settings.
 */
#if !defined(STM32_LSECLK)
#define STM32_LSECLK                32768U
#endif
#if !defined(STM32_HSECLK)
#define STM32_HSECLK                8000000U
#endif
/*
 * Board voltages.
 * Required for performance limits calculation.
 */
#define STM32_VDD                   300U
/*
 * MCU type as defined in the ST header.
 */
#define STM32F469xx

IO pin assignments

GPIOs are organized in banks, requiring the use of both a bank identifier (often referred to as Port) and a pin number (often referred to as Pad) to identify a pin. For example, STM32 uses letters for ports (GPIOA, GPIOB, GPIOC, etc.) and numbers for pads (0 to 15), while Atmel SAM still uses letters for ports and numbers for pads but with wider banks (0 to 32).

In ChibiOS, board files offer user-friendly aliases for each Pad, improving code readability and usability. The following shows an example of IO pins assignments in the SDP-K1 board file. Note that not all aliases are custom, and some are assigned by default (e.g. GPIOB_PIN14). Additionally, multiple aliases can be assigned to the same pin.

/*
 * IO pins assignments.
 */
#define GPIOA_ARD_D1                0U
#define GPIOA_ARD_D0                1U
#define GPIOA_ARD_A0                2U
#define GPIOA_ULPI_D0               3U
#define GPIOA_ARD_A1                4U
#define GPIOA_ULPI_CK               5U
#define GPIOA_ARD_A2                6U
#define GPIOA_ARD_D11               7U
#define GPIOA_PIN8                  8U
#define GPIOA_PIN9                  9U
#define GPIOA_ARD_D6                10U
#define GPIOA_ARD_D5                11U
#define GPIOA_PIN12                 12U
#define GPIOA_SWDIO                 13U
#define GPIOA_SWCLK                 14U
#define GPIOA_ARD_D10               15U
#define GPIOB_ULPI_D1               0U
#define GPIOB_ULPI_D2               1U
#define GPIOB_PIN2                  2U
#define GPIOB_ARD_D13               3U
#define GPIOB_ARD_D12               4U
#define GPIOB_ULPI_D7               5U
#define GPIOB_PIN6                  6U
#define GPIOB_ARD_D14               7U
#define GPIOB_ARD_D15               8U
#define GPIOB_PIN9                  9U
#define GPIOB_ULPI_D3               10U
#define GPIOB_ULPI_D4               11U
#define GPIOB_ULPI_D5               12U
#define GPIOB_ULPI_D6               13U
#define GPIOB_PIN14                 14U
#define GPIOB_ARD_D9                15U
#define GPIOC_ULPI_STP              0U
#define GPIOC_ARD_A3                1U
#define GPIOC_ULPI_DIR              2U
#define GPIOC_ULPI_NXT              3U
#define GPIOC_ARD_A4                4U
#define GPIOC_ARD_A5                5U
#define GPIOC_PIN6                  6U
#define GPIOC_PIN7                  7U
#define GPIOC_PIN8                  8U
#define GPIOC_PIN9                  9U
#define GPIOC_PIN10                 10U
#define GPIOC_PIN11                 11U
#define GPIOC_DAP_VCP_RX            12U
#define GPIOC_PIN13                 13U
#define GPIOC_PIN14                 14U
#define GPIOC_PIN15                 15U
#define GPIOD_PIN0                  0U
#define GPIOD_PIN1                  1U
#define GPIOD_DAP_VCP_TX            2U
#define GPIOD_PIN3                  3U
#define GPIOD_PIN4                  4U
#define GPIOD_PIN5                  5U
#define GPIOD_PIN6                  6U
#define GPIOD_USB_RESET             7U
#define GPIOD_PIN8                  8U
#define GPIOD_PIN9                  9U
#define GPIOD_PIN10                 10U
#define GPIOD_PIN11                 11U
#define GPIOD_ARD_D3                12U
#define GPIOD_PIN13                 13U
#define GPIOD_PIN14                 14U
#define GPIOD_PIN15                 15U
#define GPIOE_PIN0                  0U
#define GPIOE_PIN1                  1U
#define GPIOE_PIN2                  2U
#define GPIOE_PIN3                  3U
#define GPIOE_PIN4                  4U
#define GPIOE_PIN5                  5U
#define GPIOE_PIN6                  6U
#define GPIOE_PIN7                  7U
#define GPIOE_PIN8                  8U
#define GPIOE_PIN9                  9U
#define GPIOE_PIN10                 10U
#define GPIOE_PIN11                 11U
#define GPIOE_PIN12                 12U
#define GPIOE_PIN13                 13U
#define GPIOE_PIN14                 14U
#define GPIOE_PIN15                 15U
#define GPIOF_PIN0                  0U
#define GPIOF_PIN1                  1U
#define GPIOF_PIN2                  2U
#define GPIOF_PIN3                  3U
#define GPIOF_PIN4                  4U
#define GPIOF_PIN5                  5U
#define GPIOF_PIN6                  6U
#define GPIOF_PIN7                  7U
#define GPIOF_PIN8                  8U
#define GPIOF_PIN9                  9U
#define GPIOF_PIN10                 10U
#define GPIOF_PIN11                 11U
#define GPIOF_PIN12                 12U
#define GPIOF_PIN13                 13U
#define GPIOF_PIN14                 14U
#define GPIOF_PIN15                 15U
#define GPIOG_PIN0                  0U
#define GPIOG_PIN1                  1U
#define GPIOG_PIN2                  2U
#define GPIOG_PIN3                  3U
#define GPIOG_PIN4                  4U
#define GPIOG_PIN5                  5U
#define GPIOG_PIN6                  6U
#define GPIOG_ARD_D2                7U
#define GPIOG_PIN8                  8U
#define GPIOG_ARD_D4                9U
#define GPIOG_ARD_D7                10U
#define GPIOG_ARD_D8                11U
#define GPIOG_PIN12                 12U
#define GPIOG_PIN13                 13U
#define GPIOG_PIN14                 14U
#define GPIOG_PIN15                 15U
#define GPIOH_OSC_IN                0U
#define GPIOH_OSC_OUT               1U
#define GPIOH_PIN2                  2U
#define GPIOH_PIN3                  3U
#define GPIOH_PIN4                  4U
#define GPIOH_PIN5                  5U
#define GPIOH_PIN6                  6U
#define GPIOH_PIN7                  7U
#define GPIOH_PIN8                  8U
#define GPIOH_PIN9                  9U
#define GPIOH_PIN10                 10U
#define GPIOH_PIN11                 11U
#define GPIOH_PIN12                 12U
#define GPIOH_PIN13                 13U
#define GPIOH_PIN14                 14U
#define GPIOH_PIN15                 15U
#define GPIOI_PIN0                  0U
#define GPIOI_PIN1                  1U
#define GPIOI_PIN2                  2U
#define GPIOI_PIN3                  3U
#define GPIOI_PIN4                  4U
#define GPIOI_PIN5                  5U
#define GPIOI_PIN6                  6U
#define GPIOI_PIN7                  7U
#define GPIOI_PIN8                  8U
#define GPIOI_PIN9                  9U
#define GPIOI_PIN10                 10U
#define GPIOI_PIN11                 11U
#define GPIOI_PIN12                 12U
#define GPIOI_PIN13                 13U
#define GPIOI_PIN14                 14U
#define GPIOI_PIN15                 15U
#define GPIOJ_PIN0                  0U
#define GPIOJ_PIN1                  1U
#define GPIOJ_PIN2                  2U
#define GPIOJ_PIN3                  3U
#define GPIOJ_PIN4                  4U
#define GPIOJ_PIN5                  5U
#define GPIOJ_PIN6                  6U
#define GPIOJ_PIN7                  7U
#define GPIOJ_PIN8                  8U
#define GPIOJ_PIN9                  9U
#define GPIOJ_PIN10                 10U
#define GPIOJ_PIN11                 11U
#define GPIOJ_PIN12                 12U
#define GPIOJ_PIN13                 13U
#define GPIOJ_PIN14                 14U
#define GPIOJ_PIN15                 15U
#define GPIOK_PIN0                  0U
#define GPIOK_PIN1                  1U
#define GPIOK_PIN2                  2U
#define GPIOK_PIN3                  3U
#define GPIOK_PROCESSOR_STATUS      4U
#define GPIOK_LED_GREEN             5U
#define GPIOK_LED_ORANGE            6U
#define GPIOK_LED_RED               7U
#define GPIOK_PIN8                  8U
#define GPIOK_PIN9                  9U
#define GPIOK_PIN10                 10U
#define GPIOK_PIN11                 11U
#define GPIOK_PIN12                 12U
#define GPIOK_PIN13                 13U
#define GPIOK_PIN14                 14U
#define GPIOK_PIN15                 15U

The following instruction is a PAL API that sets a digital output line high. In this specific case, we are setting high the pin PK5 of the SDP-K1.

palSetPad(GPIOK, 5U);

In reality, this pin is connected to the green LED of the SDP-K1. To make the call more user-friendly, we can leverage the board files definitions and use the symbolic alias for PK5 named GPIOK_LED_GREEN.

palSetPad(GPIOK, GPIOK_LED_GREEN);

In some architectures, a single identifier, called Line, can convey both the Port and Pad values. The board files offer a list of Line identifiers for all pins that have a custom alias defined.

/*
 * IO lines assignments.
 */
#define LINE_ARD_D1                 PAL_LINE(GPIOA, 0U)
#define LINE_ARD_D0                 PAL_LINE(GPIOA, 1U)
#define LINE_ARD_A0                 PAL_LINE(GPIOA, 2U)
#define LINE_ULPI_D0                PAL_LINE(GPIOA, 3U)
#define LINE_ARD_A1                 PAL_LINE(GPIOA, 4U)
#define LINE_ULPI_CK                PAL_LINE(GPIOA, 5U)
#define LINE_ARD_A2                 PAL_LINE(GPIOA, 6U)
#define LINE_ARD_D11                PAL_LINE(GPIOA, 7U)
#define LINE_ARD_D6                 PAL_LINE(GPIOA, 10U)
#define LINE_ARD_D5                 PAL_LINE(GPIOA, 11U)
#define LINE_SWDIO                  PAL_LINE(GPIOA, 13U)
#define LINE_SWCLK                  PAL_LINE(GPIOA, 14U)
#define LINE_ARD_D10                PAL_LINE(GPIOA, 15U)
#define LINE_ULPI_D1                PAL_LINE(GPIOB, 0U)
#define LINE_ULPI_D2                PAL_LINE(GPIOB, 1U)
#define LINE_ARD_D13                PAL_LINE(GPIOB, 3U)
#define LINE_ARD_D12                PAL_LINE(GPIOB, 4U)
#define LINE_ULPI_D7                PAL_LINE(GPIOB, 5U)
#define LINE_ARD_D14                PAL_LINE(GPIOB, 7U)
#define LINE_ARD_D15                PAL_LINE(GPIOB, 8U)
#define LINE_ULPI_D3                PAL_LINE(GPIOB, 10U)
#define LINE_ULPI_D4                PAL_LINE(GPIOB, 11U)
#define LINE_ULPI_D5                PAL_LINE(GPIOB, 12U)
#define LINE_ULPI_D6                PAL_LINE(GPIOB, 13U)
#define LINE_ARD_D9                 PAL_LINE(GPIOB, 15U)
#define LINE_ULPI_STP               PAL_LINE(GPIOC, 0U)
#define LINE_ARD_A3                 PAL_LINE(GPIOC, 1U)
#define LINE_ULPI_DIR               PAL_LINE(GPIOC, 2U)
#define LINE_ULPI_NXT               PAL_LINE(GPIOC, 3U)
#define LINE_ARD_A4                 PAL_LINE(GPIOC, 4U)
#define LINE_ARD_A5                 PAL_LINE(GPIOC, 5U)
#define LINE_DAP_VCP_RX             PAL_LINE(GPIOC, 12U)
#define LINE_DAP_VCP_TX             PAL_LINE(GPIOD, 2U)
#define LINE_USB_RESET              PAL_LINE(GPIOD, 7U)
#define LINE_ARD_D3                 PAL_LINE(GPIOD, 12U)
#define LINE_ARD_D2                 PAL_LINE(GPIOG, 7U)
#define LINE_ARD_D4                 PAL_LINE(GPIOG, 9U)
#define LINE_ARD_D7                 PAL_LINE(GPIOG, 10U)
#define LINE_ARD_D8                 PAL_LINE(GPIOG, 11U)
#define LINE_OSC_IN                 PAL_LINE(GPIOH, 0U)
#define LINE_OSC_OUT                PAL_LINE(GPIOH, 1U)
#define LINE_PROCESSOR_STATUS       PAL_LINE(GPIOK, 4U)
#define LINE_LED_GREEN              PAL_LINE(GPIOK, 5U)
#define LINE_LED_ORANGE             PAL_LINE(GPIOK, 6U)
#define LINE_LED_RED                PAL_LINE(GPIOK, 7U)

Leveraging these definitions and the PAL API is it possible to rewrite the previous example in an even more compact way as

palSetLine(LINE_LED_GREEN);

Ports setup

Board files are used in ChibiOS to initialize the ports of the microcontroller after the reset. These files define macros that are specific to the platform being used. For example, the following macros, defined in the SDP-K1 board files, refer to the GPIO register structure of the STM32F469, which is the MCU used on this board:

/*
 * I/O ports initial setup, this configuration is established soon after reset
 * in the initialization code.
 * Please refer to the STM32 Reference Manual for details.
 */
#define PIN_MODE_INPUT(n)           (0U << ((n) * 2U))
#define PIN_MODE_OUTPUT(n)          (1U << ((n) * 2U))
#define PIN_MODE_ALTERNATE(n)       (2U << ((n) * 2U))
#define PIN_MODE_ANALOG(n)          (3U << ((n) * 2U))
#define PIN_ODR_LOW(n)              (0U << (n))
#define PIN_ODR_HIGH(n)             (1U << (n))
#define PIN_OTYPE_PUSHPULL(n)       (0U << (n))
#define PIN_OTYPE_OPENDRAIN(n)      (1U << (n))
#define PIN_OSPEED_VERYLOW(n)       (0U << ((n) * 2U))
#define PIN_OSPEED_LOW(n)           (1U << ((n) * 2U))
#define PIN_OSPEED_MEDIUM(n)        (2U << ((n) * 2U))
#define PIN_OSPEED_HIGH(n)          (3U << ((n) * 2U))
#define PIN_PUPDR_FLOATING(n)       (0U << ((n) * 2U))
#define PIN_PUPDR_PULLUP(n)         (1U << ((n) * 2U))
#define PIN_PUPDR_PULLDOWN(n)       (2U << ((n) * 2U))
#define PIN_AFIO_AF(n, v)           ((v) << (((n) % 8U) * 4U))

These macros are then used to compose and set the value of each register of each GPIO bank. For example, here is the configuration for PortA:

/*
 * GPIOA setup:
 *
 * PA0  - ARD_D1                    (input pullup).
 * PA1  - ARD_D0                    (input pullup).
 * PA2  - ARD_A0                    (input pullup).
 * PA3  - ULPI_D0                   (alternate 10).
 * PA4  - ARD_A1                    (input pullup).
 * PA5  - ULPI_CK                   (alternate 10).
 * PA6  - ARD_A2                    (input pullup).
 * PA7  - ARD_D11                   (alternate 5).
 * PA8  - PIN8                      (input pullup).
 * PA9  - PIN9                      (input pullup).
 * PA10 - ARD_D6                    (input pullup).
 * PA11 - ARD_D5                    (input pullup).
 * PA12 - PIN12                     (input pullup).
 * PA13 - SWDIO                     (alternate 0).
 * PA14 - SWCLK                     (alternate 0).
 * PA15 - ARD_D10                   (output pushpull maximum).
 */
#define VAL_GPIOA_MODER             (PIN_MODE_INPUT(GPIOA_ARD_D1) |         \
                                     PIN_MODE_INPUT(GPIOA_ARD_D0) |         \
                                     PIN_MODE_INPUT(GPIOA_ARD_A0) |         \
                                     PIN_MODE_ALTERNATE(GPIOA_ULPI_D0) |    \
                                     PIN_MODE_INPUT(GPIOA_ARD_A1) |         \
                                     PIN_MODE_ALTERNATE(GPIOA_ULPI_CK) |    \
                                     PIN_MODE_INPUT(GPIOA_ARD_A2) |         \
                                     PIN_MODE_ALTERNATE(GPIOA_ARD_D11) |    \
                                     PIN_MODE_INPUT(GPIOA_PIN8) |           \
                                     PIN_MODE_INPUT(GPIOA_PIN9) |           \
                                     PIN_MODE_INPUT(GPIOA_ARD_D6) |         \
                                     PIN_MODE_INPUT(GPIOA_ARD_D5) |         \
                                     PIN_MODE_INPUT(GPIOA_PIN12) |          \
                                     PIN_MODE_ALTERNATE(GPIOA_SWDIO) |      \
                                     PIN_MODE_ALTERNATE(GPIOA_SWCLK) |      \
                                     PIN_MODE_OUTPUT(GPIOA_ARD_D10))
#define VAL_GPIOA_OTYPER            (PIN_OTYPE_PUSHPULL(GPIOA_ARD_D1) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_D0) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_A0) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ULPI_D0) |    \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_A1) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ULPI_CK) |    \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_A2) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_D11) |    \
                                     PIN_OTYPE_PUSHPULL(GPIOA_PIN8) |       \
                                     PIN_OTYPE_PUSHPULL(GPIOA_PIN9) |       \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_D6) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_D5) |     \
                                     PIN_OTYPE_PUSHPULL(GPIOA_PIN12) |      \
                                     PIN_OTYPE_PUSHPULL(GPIOA_SWDIO) |      \
                                     PIN_OTYPE_PUSHPULL(GPIOA_SWCLK) |      \
                                     PIN_OTYPE_PUSHPULL(GPIOA_ARD_D10))
#define VAL_GPIOA_OSPEEDR           (PIN_OSPEED_HIGH(GPIOA_ARD_D1) |        \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_D0) |        \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_A0) |        \
                                     PIN_OSPEED_HIGH(GPIOA_ULPI_D0) |       \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_A1) |        \
                                     PIN_OSPEED_HIGH(GPIOA_ULPI_CK) |       \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_A2) |        \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_D11) |       \
                                     PIN_OSPEED_HIGH(GPIOA_PIN8) |          \
                                     PIN_OSPEED_HIGH(GPIOA_PIN9) |          \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_D6) |        \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_D5) |        \
                                     PIN_OSPEED_HIGH(GPIOA_PIN12) |         \
                                     PIN_OSPEED_HIGH(GPIOA_SWDIO) |         \
                                     PIN_OSPEED_HIGH(GPIOA_SWCLK) |         \
                                     PIN_OSPEED_HIGH(GPIOA_ARD_D10))
#define VAL_GPIOA_PUPDR             (PIN_PUPDR_PULLUP(GPIOA_ARD_D1) |       \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_D0) |       \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_A0) |       \
                                     PIN_PUPDR_FLOATING(GPIOA_ULPI_D0) |    \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_A1) |       \
                                     PIN_PUPDR_FLOATING(GPIOA_ULPI_CK) |    \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_A2) |       \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_D11) |      \
                                     PIN_PUPDR_PULLUP(GPIOA_PIN8) |         \
                                     PIN_PUPDR_PULLUP(GPIOA_PIN9) |         \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_D6) |       \
                                     PIN_PUPDR_PULLUP(GPIOA_ARD_D5) |       \
                                     PIN_PUPDR_PULLUP(GPIOA_PIN12) |        \
                                     PIN_PUPDR_PULLUP(GPIOA_SWDIO) |        \
                                     PIN_PUPDR_PULLDOWN(GPIOA_SWCLK) |      \
                                     PIN_PUPDR_FLOATING(GPIOA_ARD_D10))
#define VAL_GPIOA_ODR               (PIN_ODR_HIGH(GPIOA_ARD_D1) |           \
                                     PIN_ODR_HIGH(GPIOA_ARD_D0) |           \
                                     PIN_ODR_HIGH(GPIOA_ARD_A0) |           \
                                     PIN_ODR_HIGH(GPIOA_ULPI_D0) |          \
                                     PIN_ODR_HIGH(GPIOA_ARD_A1) |           \
                                     PIN_ODR_HIGH(GPIOA_ULPI_CK) |          \
                                     PIN_ODR_HIGH(GPIOA_ARD_A2) |           \
                                     PIN_ODR_HIGH(GPIOA_ARD_D11) |          \
                                     PIN_ODR_HIGH(GPIOA_PIN8) |             \
                                     PIN_ODR_HIGH(GPIOA_PIN9) |             \
                                     PIN_ODR_HIGH(GPIOA_ARD_D6) |           \
                                     PIN_ODR_HIGH(GPIOA_ARD_D5) |           \
                                     PIN_ODR_HIGH(GPIOA_PIN12) |            \
                                     PIN_ODR_HIGH(GPIOA_SWDIO) |            \
                                     PIN_ODR_HIGH(GPIOA_SWCLK) |            \
                                     PIN_ODR_HIGH(GPIOA_ARD_D10))
#define VAL_GPIOA_AFRL              (PIN_AFIO_AF(GPIOA_ARD_D1, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_ARD_D0, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_ARD_A0, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_ULPI_D0, 10U) |      \
                                     PIN_AFIO_AF(GPIOA_ARD_A1, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_ULPI_CK, 10U) |      \
                                     PIN_AFIO_AF(GPIOA_ARD_A2, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_ARD_D11, 5U))
#define VAL_GPIOA_AFRH              (PIN_AFIO_AF(GPIOA_PIN8, 0U) |          \
                                     PIN_AFIO_AF(GPIOA_PIN9, 0U) |          \
                                     PIN_AFIO_AF(GPIOA_ARD_D6, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_ARD_D5, 0U) |        \
                                     PIN_AFIO_AF(GPIOA_PIN12, 0U) |         \
                                     PIN_AFIO_AF(GPIOA_SWDIO, 0U) |         \
                                     PIN_AFIO_AF(GPIOA_SWCLK, 0U) |         \
                                     PIN_AFIO_AF(GPIOA_ARD_D10, 0U))

These constants are then used in the __early_init hook, that ChibiOS makes available right after the power-on reset before the stack initialization and the jump into the main.

static void stm32_gpio_init(void) {
  /* Enabling GPIO-related clocks, the mask comes from the
     registry header file.*/
  rccResetAHB1(STM32_GPIO_EN_MASK);
  rccEnableAHB1(STM32_GPIO_EN_MASK, true);
  /* Initializing all the defined GPIO ports.*/
#if STM32_HAS_GPIOA
  gpio_init(GPIOA, &gpio_default_config.PAData);
#endif
#if STM32_HAS_GPIOB
  gpio_init(GPIOB, &gpio_default_config.PBData);
#endif
#if STM32_HAS_GPIOC
  gpio_init(GPIOC, &gpio_default_config.PCData);
#endif
#if STM32_HAS_GPIOD
  gpio_init(GPIOD, &gpio_default_config.PDData);
#endif
#if STM32_HAS_GPIOE
  gpio_init(GPIOE, &gpio_default_config.PEData);
#endif
#if STM32_HAS_GPIOF
  gpio_init(GPIOF, &gpio_default_config.PFData);
#endif
#if STM32_HAS_GPIOG
  gpio_init(GPIOG, &gpio_default_config.PGData);
#endif
#if STM32_HAS_GPIOH
  gpio_init(GPIOH, &gpio_default_config.PHData);
#endif
#if STM32_HAS_GPIOI
  gpio_init(GPIOI, &gpio_default_config.PIData);
#endif
#if STM32_HAS_GPIOJ
  gpio_init(GPIOJ, &gpio_default_config.PJData);
#endif
#if STM32_HAS_GPIOK
  gpio_init(GPIOK, &gpio_default_config.PKData);
#endif
}
/*===========================================================================*/
/* Driver interrupt handlers.                                                */
/*===========================================================================*/
/*===========================================================================*/
/* Driver exported functions.                                                */
/*===========================================================================*/
/**
 * @brief   Early initialization code.
 * @details GPIO ports and system clocks are initialized before everything
 *          else.
 */
void __early_init(void) {
  stm32_gpio_init();
  stm32_clock_init();
}

It is important to note that for certain architectures, initializing the GPIOs may need to be deferred to a later stage. To achieve this, one can move the initialization process to the boardInit function, which is called by halInit from the main application. The boardInit function is defined in the board file but is typically left empty for the STM32 architecture.

/**
 * @brief   Board-specific initialization code.
 * @note    You can add your board-specific code here.
 */
void boardInit(void) {
}

Additional hooks

The board files also contain the definition of additional hooks that are required by some HAL drivers and are specific to the board. For instance, there may be hooks related to MMC card detection that depends on how the cardholder is connected to the GPIOs. These hooks are guarded by preprocessor switches, so if the driver is disabled in the halconf.h file, they are removed during compilation.

#if HAL_USE_SDC || defined(__DOXYGEN__)
/**
 * @brief   SDC card detection.
 */
bool sdc_lld_is_card_inserted(SDCDriver *sdcp) {
  (void)sdcp;
  /* CHTODO: Fill the implementation.*/
  return true;
}
/**
 * @brief   SDC card write protection detection.
 */
bool sdc_lld_is_write_protected(SDCDriver *sdcp) {
  (void)sdcp;
  /* CHTODO: Fill the implementation.*/
  return false;
}
#endif /* HAL_USE_SDC */
#if HAL_USE_MMC_SPI || defined(__DOXYGEN__)
/**
 * @brief   MMC_SPI card detection.
 */
bool mmc_lld_is_card_inserted(MMCDriver *mmcp) {
  (void)mmcp;
  /* CHTODO: Fill the implementation.*/
  return true;
}
/**
 * @brief   MMC_SPI card write protection detection.
 */
bool mmc_lld_is_write_protected(MMCDriver *mmcp) {
  (void)mmcp;
  /* CHTODO: Fill the implementation.*/
  return false;
}
#endif

Integration of the Board files

To understand how the board files are linked to the project, we need to look at the contents of the package. It includes a header file and a source file, named board.h and board.c, respectively. The code we showed earlier is actually contained within these files. Additionally, there is a board.mk file that adds board.c to the list of C sources (ALLCSRC) and the board file directory to the list of include folders (ALLINC).

# List of all the board related files.
BOARDSRC = $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z/board.c
# Required include directories
BOARDINC = $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z
# Shared variables
ALLCSRC += $(BOARDSRC)
ALLINC  += $(BOARDINC)

Finally, we have an optional configuration folder that is used to automatically generate these three files (board.h, board.c and board.mk) but that we are going to look into later in this article.

The linkage to our board files is done in the makefile of our project in the sources and paths section

##############################################################################
# Project, target, sources and paths
#
# Define project name here
PROJECT = ch
# Target settings.
MCU  = cortex-m4
# Imported source files and paths.
CHIBIOS  := ../../chibios2111
CONFDIR  := ./cfg
BUILDDIR := ./build
DEPDIR   := ./.dep
# Licensing files.
include $(CHIBIOS)/os/license/license.mk
# Startup files.
include $(CHIBIOS)/os/common/startup/ARMCMx/compilers/GCC/mk/startup_stm32f4xx.mk
# HAL-OSAL files (optional).
include $(CHIBIOS)/os/hal/hal.mk
include $(CHIBIOS)/os/hal/ports/STM32/STM32F4xx/platform.mk
include $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z/board.mk
include $(CHIBIOS)/os/hal/osal/rt-nil/osal.mk
# RTOS files (optional).
include $(CHIBIOS)/os/rt/rt.mk
include $(CHIBIOS)/os/common/ports/ARMv7-M/compilers/GCC/mk/port.mk
# Auto-build files in ./source recursively.
include $(CHIBIOS)/tools/mk/autobuild.mk
# Other files (optional).

More specifically the following line is what we are looking for

include $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z/board.mk

This line includes the board files we just discussed in our project. Note that these board files are part of the ChibiOS release and any change to them may be lost if we update ChibiStudio or simply share the project with someone that uses an official release of ChibiOS.

Custom board files

Generating custom board files

The easiest way to create custom board files is to copy the board file folder of a board similar to ours. If the folder we copied contains a subfolder named cfg, then it means that a configurator is available for the MCU in use and we may use it to automatically generate new board files. If the configurator is not available one has to manually edit the board files.

Sticking to the SDP-K1, this board comes with an STM32F469. ChibiOS provides a configurator for this MCU family, and the board folder we copied includes a cfg subfolder with an XML file named board.chcfg.

The board file configurator of the SDP-K1

This file fully describes our board, and we can use the Eclipse XML editor to select configurations for various fields that will be used when generating the board files. These configuration files are MCU-dependent and, typically, the important things to set are

  1. the MCU equipped on the board
  2. the clock speed and voltage of the MCU
  3. the configuration of each pin of each port under the ports field.
The board files configurator for the STM32F469

Note that many of these fields are drop-down menus such as the pinX Mode field that depends on the underlying HW and hence on the template in use.

Once the XML is fine-tuned we can generate our board files: when the file board.chcfg is highlighted in the project explorer, ChibiStudio will show a new dropdown menu named Configuration. We just need to open it and choose to Generate Files from Configuration data. If the procedure is successful we will see an output in the Console window.

Adding custom board files to our project

As said before, the board files are part of the ChibiOS folder and any change to them may be lost if we update ChibiStudio or simply share the project with someone that uses an official release of ChibiOS. If we are set to create our own custom board files we may want to add them directly to our project. So a course of action would be to generate a set of board files directly in our project and then amend the makefile to point to ours instead of those from ChibiOS. To do so I followed the following steps

  1. Right-click on the project, choose New->Folder
  2. In the newly open windows choose a name and press finish. Note that you cannot use “board” as it is already in use so in my case I placed a dummy name for now
  3. Copy the cfg folder from board to your newly created folder (copy and paste would do fine)
  4. Remove the board link and eventually rename your folder
  5. Edit your board.chcfg and generate your board files as explained in the previous paragraph

At this point, we need to adjust a few references in the makefiles. Let us start with the newly generated board.mk file. As I did not change the board_id field, mine looks like this:

 # List of all the board related files.
BOARDSRC = $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z/board.c
# Required include directories
BOARDINC = $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z
# Shared variables
ALLCSRC += $(BOARDSRC)
ALLINC  += $(BOARDINC)

But the paths in the makefile are completely wrong as they still reference the ChibiOS folder. In my case, my project structure looks like this:

--RT-STM32F469I-EVAL-SDP-CK1Z-MyProject   - Project root
  +--board/                               - Board folder
  |  +--cfg/                              - Board configurators
  |  |  +--board.chcfg                    - Board descriptors
  |  |  +--board.fmpp                     - Board freemarkes script
  |  |  +--board.c                        - Board source file
  |  |  +--board.h                        - Board header file
  |  |  +--board.mk                       - The file we are editing
  +--cfg/                                 - Project configurations
  |  +--chconf.h                          - RT configuration file
  |  +--halconf.h                         - HAL configuration file
  |  +--mcuconf.h                         - STM32F4xx configuration file
  +--os/                                  - Link to the ChibiOS/os folder
  +--main.c                               - main.c
  +--Makefile                             - makefile
  +--readme.txt                           - readme

The goal is to update the board.mk file to accurately reflect the path of board.c relative to the makefile, as well as the relative path of the board folder. To achieve this, the following changes will be made to the board.mk file.

# List of all the board related files.
BOARDSRC = ./board/board.c
# Required include directories
BOARDINC = ./board
# Shared variables
ALLCSRC += $(BOARDSRC)
ALLINC  += $(BOARDINC)

Finally, we want to open the makefile of our project and point to this file. We hence want to change this line

include $(CHIBIOS)/os/hal/boards/ADI_EVAL_SDP_CK1Z/board.mk

into

include ./board/board.mk

so, after the changes, our sources and path section will look like this:

##############################################################################
# Project, target, sources and paths
#
# Define project name here
PROJECT = ch
# Target settings.
MCU  = cortex-m4
# Imported source files and paths.
CHIBIOS  := ../../chibios2111
CONFDIR  := ./cfg
BUILDDIR := ./build
DEPDIR   := ./.dep
# Licensing files.
include $(CHIBIOS)/os/license/license.mk
# Startup files.
include $(CHIBIOS)/os/common/startup/ARMCMx/compilers/GCC/mk/startup_stm32f4xx.mk
# HAL-OSAL files (optional).
include $(CHIBIOS)/os/hal/hal.mk
include $(CHIBIOS)/os/hal/ports/STM32/STM32F4xx/platform.mk
include ./board/board.mk
include $(CHIBIOS)/os/hal/osal/rt-nil/osal.mk
# RTOS files (optional).
include $(CHIBIOS)/os/rt/rt.mk
include $(CHIBIOS)/os/common/ports/ARMv7-M/compilers/GCC/mk/port.mk
# Auto-build files in ./source recursively.
include $(CHIBIOS)/tools/mk/autobuild.mk
# Other files (optional).
include $(CHIBIOS)/os/test/test.mk
include $(CHIBIOS)/test/rt/rt_test.mk
include $(CHIBIOS)/test/oslib/oslib_test.mk
# Define linker script file here
LDSCRIPT= $(STARTUPLD)/STM32F469xI.ld

Now that we have made changes to the makefile, we can build our project and continue working on it. It’s important to note that if we make additional changes to the board configurator and regenerate the board files, we will need to update the board.mk file again. This is because the configurator will overwrite our changes to the board.mk, so we need to make sure they reflect the correct paths for our project.

Conclusions

In conclusion, creating custom board files is an essential part of using the ChibiOS/HAL. It allows you to define the hardware-specific details of your custom development board, such as the pin configurations, clock speeds, and other settings. By following the steps outlined in this article, you can create custom board files for your specific microcontroller and board configuration. These files can be generated using the built-in configurator or manually edited, and then linked to your project via the makefiles. Custom board files ensure that your code is optimized for your hardware, and ultimately lead to a more efficient GPIO initialization during the startup phase.

Be the first to reply at How to leverage Board Files in ChibiOS

Leave a Reply