From 46236ce3de8385f27e3f13a9921abee7e1e0fa57 Mon Sep 17 00:00:00 2001 From: Ryan Date: Fri, 15 Nov 2024 05:00:02 +1100 Subject: [PATCH] [docs] Improve halconf/mcuconf code examples (#24597) --- docs/drivers/audio.md | 88 ++++++++++++++++------------ docs/drivers/i2c.md | 21 ++++--- docs/drivers/serial.md | 114 +++++++++++++++++++++---------------- docs/drivers/spi.md | 25 +++++--- docs/drivers/uart.md | 8 ++- docs/drivers/ws2812.md | 44 +++++++++----- docs/features/backlight.md | 44 +++++++++----- docs/features/ps2_mouse.md | 14 +++-- 8 files changed, 222 insertions(+), 136 deletions(-) diff --git a/docs/drivers/audio.md b/docs/drivers/audio.md index c764c97369a..165e61f0655 100644 --- a/docs/drivers/audio.md +++ b/docs/drivers/audio.md @@ -57,27 +57,32 @@ This driver needs one Timer per enabled/used DAC channel, to trigger conversion; Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8: -```c -//halconf.h: -#define HAL_USE_DAC TRUE -#define HAL_USE_GPT TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_DAC TRUE // [!code focus] +#define HAL_USE_GPT TRUE // [!code focus] + #include_next ``` +```c [mcuconf.h] +#pragma once -```c -// mcuconf.h: #include_next -#undef STM32_DAC_USE_DAC1_CH1 -#define STM32_DAC_USE_DAC1_CH1 TRUE -#undef STM32_DAC_USE_DAC1_CH2 -#define STM32_DAC_USE_DAC1_CH2 TRUE -#undef STM32_GPT_USE_TIM6 -#define STM32_GPT_USE_TIM6 TRUE -#undef STM32_GPT_USE_TIM7 -#define STM32_GPT_USE_TIM7 TRUE -#undef STM32_GPT_USE_TIM8 -#define STM32_GPT_USE_TIM8 TRUE + +#undef STM32_DAC_USE_DAC1_CH1 // [!code focus] +#define STM32_DAC_USE_DAC1_CH1 TRUE // [!code focus] +#undef STM32_DAC_USE_DAC1_CH2 // [!code focus] +#define STM32_DAC_USE_DAC1_CH2 TRUE // [!code focus] +#undef STM32_GPT_USE_TIM6 // [!code focus] +#define STM32_GPT_USE_TIM6 TRUE // [!code focus] +#undef STM32_GPT_USE_TIM7 // [!code focus] +#define STM32_GPT_USE_TIM7 TRUE // [!code focus] +#undef STM32_GPT_USE_TIM8 // [!code focus] +#define STM32_GPT_USE_TIM8 TRUE // [!code focus] ``` +::: ::: tip Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable). @@ -95,23 +100,28 @@ only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; t Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6: -```c -//halconf.h: -#define HAL_USE_DAC TRUE -#define HAL_USE_GPT TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_DAC TRUE // [!code focus] +#define HAL_USE_GPT TRUE // [!code focus] + #include_next ``` +```c [mcuconf.h] +#pragma once -```c -// mcuconf.h: #include_next -#undef STM32_DAC_USE_DAC1_CH1 -#define STM32_DAC_USE_DAC1_CH1 TRUE -#undef STM32_DAC_USE_DAC1_CH2 -#define STM32_DAC_USE_DAC1_CH2 TRUE -#undef STM32_GPT_USE_TIM6 -#define STM32_GPT_USE_TIM6 TRUE + +#undef STM32_DAC_USE_DAC1_CH1 // [!code focus] +#define STM32_DAC_USE_DAC1_CH1 TRUE // [!code focus] +#undef STM32_DAC_USE_DAC1_CH2 // [!code focus] +#define STM32_DAC_USE_DAC1_CH2 TRUE // [!code focus] +#undef STM32_GPT_USE_TIM6 // [!code focus] +#define STM32_GPT_USE_TIM6 TRUE // [!code focus] ``` +::: ### DAC Config @@ -170,19 +180,25 @@ This driver uses the ChibiOS-PWM system to produce a square-wave on specific out The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function. A configuration example for the STM32F103C8 would be: -```c -//halconf.h: -#define HAL_USE_PWM TRUE -#define HAL_USE_PAL TRUE + +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_PWM TRUE // [!code focus] +#define HAL_USE_PAL TRUE // [!code focus] + #include_next ``` +```c [mcuconf.h] +#pragma once -```c -// mcuconf.h: #include_next -#undef STM32_PWM_USE_TIM1 -#define STM32_PWM_USE_TIM1 TRUE + +#undef STM32_PWM_USE_TIM1 // [!code focus] +#define STM32_PWM_USE_TIM1 TRUE // [!code focus] ``` +::: If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions - TIM1_CH1 = PA8 <- alternate0 diff --git a/docs/drivers/i2c.md b/docs/drivers/i2c.md index 10949ed59e0..c806a090c56 100644 --- a/docs/drivers/i2c.md +++ b/docs/drivers/i2c.md @@ -54,18 +54,25 @@ The ATmega16/32U2 does not possess I2C functionality, and so cannot use this dri You'll need to determine which pins can be used for I2C -- a an example, STM32 parts generally have multiple I2C peripherals, labeled I2C1, I2C2, I2C3 etc. -To enable I2C, modify your board's `halconf.h` to enable I2C: +To enable I2C, modify your board's `halconf.h` to enable I2C, then modify your board's `mcuconf.h` to enable the peripheral you've chosen: -```c -#define HAL_USE_I2C TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_I2C TRUE // [!code focus] + +#include_next ``` +```c [mcuconf.h] +#pragma once -Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example: +#include_next -```c -#undef STM32_I2C_USE_I2C2 -#define STM32_I2C_USE_I2C2 TRUE +#undef STM32_I2C_USE_I2C2 // [!code focus] +#define STM32_I2C_USE_I2C2 TRUE // [!code focus] ``` +::: |`mcuconf.h` Setting |Description |Default| |----------------------------|----------------------------------------------------------------------------------|-------| diff --git a/docs/drivers/serial.md b/docs/drivers/serial.md index 75d11bc93bc..dda75f629a2 100644 --- a/docs/drivers/serial.md +++ b/docs/drivers/serial.md @@ -12,8 +12,6 @@ The Serial driver powers the [Split Keyboard](../features/split_keyboard) featur Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards. ::: -
- ## Bitbang This is the Default driver, absence of configuration assumes this driver. It works by [bit banging](https://en.wikipedia.org/wiki/Bit_banging) a GPIO pin using the CPU. It is therefore not as efficient as a dedicated hardware peripheral, which the Half-duplex and Full-duplex drivers use. @@ -53,11 +51,15 @@ SERIAL_DRIVER = bitbang #define SOFT_SERIAL_PIN D0 // or D1, D2, D3, E6 ``` -3. On ARM platforms you must turn on ChibiOS `PAL_USE_CALLBACKS` feature: +3. On ARM platforms you must turn on ChibiOS PAL callbacks: -* In `halconf.h` add the line `#define PAL_USE_CALLBACKS TRUE`. +```c +#pragma once -
+#define PAL_USE_CALLBACKS TRUE // [!code focus] + +#include_next +``` ## USART Half-duplex @@ -117,8 +119,6 @@ For STM32 MCUs several GPIO configuration options can be changed as well. See th 4. Decide either for `SERIAL`, `SIO`, or `PIO` subsystem. See section ["Choosing a driver subsystem"](#choosing-a-driver-subsystem). -
- ## USART Full-duplex Targeting ARM boards based on ChibiOS where communication is offloaded to an USART hardware device. The advantages over bitbanging are fast, accurate timings and reduced CPU usage; therefore it is advised to choose this driver over all others where possible. Due to its internal design Full-duplex is slightly more efficient than the Half-duplex driver, but Full-duplex should be primarily chosen if Half-duplex operation is not supported by the controller's USART peripheral. @@ -179,38 +179,46 @@ For STM32 MCUs several GPIO configuration options, including the ability for `TX 4. Decide either for `SERIAL`, `SIO`, or `PIO` subsystem. See section ["Choosing a driver subsystem"](#choosing-a-driver-subsystem). -
- ## Choosing a driver subsystem ### The `SERIAL` driver The `SERIAL` Subsystem is supported for the majority of ChibiOS MCUs and should be used whenever supported. Follow these steps in order to activate it: -1. In your keyboards `halconf.h` add: +1. Enable the SERIAL subsystem in the ChibiOS HAL. -```c -#define HAL_USE_SERIAL TRUE -``` + Add the following to your keyboard's `halconf.h`, creating it if necessary: -2. In your keyboards `mcuconf.h`: activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. - -Just below `#include_next ` add: + ```c + #pragma once -```c -#include_next + #define HAL_USE_SERIAL TRUE // [!code focus] -#undef STM32_SERIAL_USE_USARTn -#define STM32_SERIAL_USE_USARTn TRUE -``` + #include_next + ``` -Where 'n' matches the peripheral number of your selected USART on the MCU. +2. Activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. -3. In you keyboards `config.h`: override the default USART `SERIAL` driver if you use a USART peripheral that does not belong to the default selected `SD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SD3`. + Add the following to your keyboard's `mcuconf.h`, creating it if necessary: -```c - #define SERIAL_USART_DRIVER SD3 - ``` + ```c + #pragma once + + #include_next + + #undef STM32_SERIAL_USE_USARTn // [!code focus] + #define STM32_SERIAL_USE_USARTn TRUE // [!code focus] + ``` + + Where *n* matches the peripheral number of your selected USART on the MCU. + +3. Override the default USART `SERIAL` driver if you use a USART peripheral that does not belong to the default selected `SD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SD3`. + + Add the following to your keyboard's `config.h`: + + ```c + #define SERIAL_USART_DRIVER SD3 + ``` ### The `SIO` driver @@ -218,31 +226,41 @@ The `SIO` Subsystem was added to ChibiOS with the 21.11 release and is only supp Follow these steps in order to activate it: -1. In your keyboards `halconf.h` add: +1. Enable the SIO subsystem in the ChibiOS HAL. -```c -#define HAL_USE_SIO TRUE -``` + Add the following to your keyboard's `halconf.h`, creating it if necessary: -2. In your keyboards `mcuconf.h:` activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. - -Just below `#include_next ` add: + ```c + #pragma once -```c -#include_next + #define HAL_USE_SIO TRUE // [!code focus] -#undef STM32_SIO_USE_USARTn -#define STM32_SIO_USE_USARTn TRUE -``` + #include_next + ``` -Where 'n' matches the peripheral number of your selected USART on the MCU. +2. Activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. -3. In the keyboard's `config.h` file: override the default USART `SIO` driver if you use a USART peripheral that does not belong to the default selected `SIOD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SIOD3`. + Add the following to your keyboard's `mcuconf.h`, creating it if necessary: + + ```c + #pragma once + + #include_next + + #undef STM32_SIO_USE_USARTn // [!code focus] + #define STM32_SIO_USE_USARTn TRUE // [!code focus] + ``` + + Where *n* matches the peripheral number of your selected USART on the MCU. + +3. Override the default USART `SIO` driver if you use a USART peripheral that does not belong to the default selected `SIOD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SIOD3`. + + Add the following to your keyboard's `config.h`: + + ```c + #define SERIAL_USART_DRIVER SIOD3 + ``` -```c - #define SERIAL_USART_DRIVER SIOD3 - ``` - ### The `PIO` driver The `PIO` subsystem is a Raspberry Pi RP2040 specific implementation, using an integrated PIO peripheral and is therefore only available on this MCU. Because of the flexible nature of PIO peripherals, **any** GPIO pin can be used as a `TX` or `RX` pin. Half-duplex and Full-duplex operation modes are fully supported with this driver. Half-duplex uses the built-in pull-ups and GPIO manipulation of the RP2040 to drive the line high by default, thus an external pull-up resistor **is not required**. @@ -254,8 +272,6 @@ Optionally, the PIO peripheral utilized for split communication can be changed w The Serial PIO program uses 2 state machines, 13 instructions and the complete interrupt handler of the PIO peripheral it is running on. -
- ## Advanced Configuration There are several advanced configuration options that can be defined in your keyboards `config.h` file: @@ -265,9 +281,11 @@ There are several advanced configuration options that can be defined in your key If you're having issues or need a higher baudrate with serial communication, you can change the baudrate which in turn controls the communication speed for serial. You want to lower the baudrate if you experience failed transactions. ```c -#define SELECT_SOFT_SERIAL_SPEED {#} +#define SELECT_SOFT_SERIAL_SPEED n ``` +Where *n* is one of: + | Speed | Bitbang | Half-duplex and Full-duplex | | ----- | -------------------------- | --------------------------- | | `0` | 189000 baud (experimental) | 460800 baud | @@ -287,8 +305,6 @@ This is the default time window in milliseconds in which a successful communicat #define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 ``` -
- ## Troubleshooting If you're having issues withe serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file: diff --git a/docs/drivers/spi.md b/docs/drivers/spi.md index ddc35de8511..43d2a056d5d 100644 --- a/docs/drivers/spi.md +++ b/docs/drivers/spi.md @@ -32,20 +32,27 @@ You may use more than one slave select pin, not just the `SS` pin. This is usefu You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc. -To enable SPI, modify your board's `halconf.h` to enable SPI: +To enable SPI, modify your board's `halconf.h` to enable SPI, then modify your board's `mcuconf.h` to enable the peripheral you've chosen: -```c -#define HAL_USE_SPI TRUE -#define SPI_USE_WAIT TRUE -#define SPI_SELECT_MODE SPI_SELECT_MODE_PAD +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_SPI TRUE // [!code focus] +#define SPI_USE_WAIT TRUE // [!code focus] +#define SPI_SELECT_MODE SPI_SELECT_MODE_PAD // [!code focus] + +#include_next ``` +```c [mcuconf.h] +#pragma once -Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example: +#include_next -```c -#undef STM32_SPI_USE_SPI2 -#define STM32_SPI_USE_SPI2 TRUE +#undef STM32_SPI_USE_SPI2 // [!code focus] +#define STM32_SPI_USE_SPI2 TRUE // [!code focus] ``` +::: Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. diff --git a/docs/drivers/uart.md b/docs/drivers/uart.md index 23f5b3d6e43..7cc68727eec 100644 --- a/docs/drivers/uart.md +++ b/docs/drivers/uart.md @@ -35,8 +35,12 @@ You'll need to determine which pins can be used for UART -- as an example, STM32 To enable UART, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example: ```c -#undef STM32_SERIAL_USE_USART2 -#define STM32_SERIAL_USE_USART2 TRUE +#pragma once + +#include_next + +#undef STM32_SERIAL_USE_USART2 // [!code focus] +#define STM32_SERIAL_USE_USART2 TRUE // [!code focus] ``` Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. diff --git a/docs/drivers/ws2812.md b/docs/drivers/ws2812.md index 61addf1917e..88c096794f2 100644 --- a/docs/drivers/ws2812.md +++ b/docs/drivers/ws2812.md @@ -160,15 +160,23 @@ To configure the DI pin for open drain configuration, add the following to your Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like: -`halconf.h`: -```c -#define HAL_USE_SPI TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_SPI TRUE // [!code focus] + +#include_next ``` -`mcuconf.h`: -```c -#undef STM32_SPI_USE_SPI1 -#define STM32_SPI_USE_SPI1 TRUE +```c [mcuconf.h] +#pragma once + +#include_next + +#undef STM32_SPI_USE_SPI1 // [!code focus] +#define STM32_SPI_USE_SPI1 TRUE // [!code focus] ``` +::: The following `define`s apply only to the `spi` driver: @@ -213,15 +221,23 @@ The following `#define`s apply only to the PIO driver: Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like: -`halconf.h`: -```c -#define HAL_USE_PWM TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_PWM TRUE // [!code focus] + +#include_next ``` -`mcuconf.h`: -```c -#undef STM32_PWM_USE_TIM2 -#define STM32_PWM_USE_TIM2 TRUE +```c [mcuconf.h] +#pragma once + +#include_next + +#undef STM32_PWM_USE_TIM2 // [!code focus] +#define STM32_PWM_USE_TIM2 TRUE // [!code focus] ``` +::: The following `#define`s apply only to the `pwm` driver: diff --git a/docs/features/backlight.md b/docs/features/backlight.md index 94726756fdb..20f84ac6b59 100644 --- a/docs/features/backlight.md +++ b/docs/features/backlight.md @@ -161,15 +161,23 @@ Note that the choice of timer may conflict with the [Audio](audio) feature. Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like: -`halconf.h`: -```c -#define HAL_USE_PWM TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_PWM TRUE // [!code focus] + +#include_next ``` -`mcuconf.h`: -```c -#undef STM32_PWM_USE_TIM4 -#define STM32_PWM_USE_TIM4 TRUE +```c [mcuconf.h] +#pragma once + +#include_next + +#undef STM32_PWM_USE_TIM4 // [!code focus] +#define STM32_PWM_USE_TIM4 TRUE // [!code focus] ``` +::: The following `#define`s apply only to the `pwm` driver: @@ -187,15 +195,23 @@ Refer to the ST datasheet for your particular MCU to determine these values. For Depending on the ChibiOS board configuration, you may need to enable general-purpose timers at the keyboard level. For STM32, this would look like: -`halconf.h`: -```c -#define HAL_USE_GPT TRUE +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_GPT TRUE // [!code focus] + +#include_next ``` -`mcuconf.h`: -```c -#undef STM32_GPT_USE_TIM15 -#define STM32_GPT_USE_TIM15 TRUE +```c [mcuconf.h] +#pragma once + +#include_next + +#undef STM32_GPT_USE_TIM15 // [!code focus] +#define STM32_GPT_USE_TIM15 TRUE // [!code focus] ``` +::: The following `#define`s apply only to the `timer` driver: diff --git a/docs/features/ps2_mouse.md b/docs/features/ps2_mouse.md index 90f4cca8275..52443c3ce29 100644 --- a/docs/features/ps2_mouse.md +++ b/docs/features/ps2_mouse.md @@ -90,18 +90,22 @@ PS2_ENABLE = yes PS2_DRIVER = interrupt ``` -In your keyboard config.h: +In your keyboard `config.h`: ```c #define PS2_CLOCK_PIN A8 #define PS2_DATA_PIN A9 ``` -And in the chibios specifig halconf.h: -```c -#define PAL_USE_CALLBACKS TRUE -``` +And in the ChibiOS specific `halconf.h`: +```c +#pragma once + +#define PAL_USE_CALLBACKS TRUE // [!code focus] + +#include_next +``` ### USART Version {#usart-version}