gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2024-11-21 19:09:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Improve halconf/mcuconf code examples (#24597)

Browse Source
This commit is contained in:
Ryan 2024-11-15 05:00:02 +11:00 committed by GitHub
parent a8a47c4011
commit 46236ce3de
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 222 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/drivers/audio.md
View File

@ -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 <halconf.h>
```
```c [mcuconf.h]
#pragma once
```c
// mcuconf.h:
#include_next <mcuconf.h>
#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 <halconf.h>
```
```c [mcuconf.h]
#pragma once
```c
// mcuconf.h:
#include_next <mcuconf.h>
#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 <halconf.h>
```
```c [mcuconf.h]
#pragma once
```c
// mcuconf.h:
#include_next <mcuconf.h>
#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

21
docs/drivers/i2c.md
View File

@ -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 <halconf.h>
```
```c [mcuconf.h]
#pragma once
Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example:
#include_next <mcuconf.h>
```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|
|----------------------------|----------------------------------------------------------------------------------|-------|

76
docs/drivers/serial.md
View File

@ -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.
:::
<hr>
## 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
<hr>
#define PAL_USE_CALLBACKS TRUE // [!code focus]
#include_next <halconf.h>
```
## 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).
<hr>
## 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,34 +179,42 @@ 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).
<hr>
## 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.
Add the following to your keyboard's `halconf.h`, creating it if necessary:
```c
#define HAL_USE_SERIAL TRUE
#pragma once
#define HAL_USE_SERIAL TRUE // [!code focus]
#include_next <halconf.h>
```
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.
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.
Just below `#include_next <mcuconf.h>` add:
Add the following to your keyboard's `mcuconf.h`, creating it if necessary:
```c
#pragma once
#include_next <mcuconf.h>
#undef STM32_SERIAL_USE_USARTn
#define STM32_SERIAL_USE_USARTn TRUE
#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.
Where *n* matches the peripheral number of your selected USART on the MCU.
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`.
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
@ -218,26 +226,36 @@ 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.
Add the following to your keyboard's `halconf.h`, creating it if necessary:
```c
#define HAL_USE_SIO TRUE
#pragma once
#define HAL_USE_SIO TRUE // [!code focus]
#include_next <halconf.h>
```
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.
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.
Just below `#include_next <mcuconf.h>` add:
Add the following to your keyboard's `mcuconf.h`, creating it if necessary:
```c
#pragma once
#include_next <mcuconf.h>
#undef STM32_SIO_USE_USARTn
#define STM32_SIO_USE_USARTn TRUE
#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.
Where *n* matches the peripheral number of your selected USART on the MCU.
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`.
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
@ -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.
<hr>
## 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
```
<hr>
## 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:

25
docs/drivers/spi.md
View File

@ -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 <halconf.h>
```
```c [mcuconf.h]
#pragma once
Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example:
#include_next <mcuconf.h>
```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.

8
docs/drivers/uart.md
View File

@ -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 <mcuconf.h>
#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.

44
docs/drivers/ws2812.md
View File

@ -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 <halconf.h>
```
`mcuconf.h`:
```c
#undef STM32_SPI_USE_SPI1
#define STM32_SPI_USE_SPI1 TRUE
```c [mcuconf.h]
#pragma once
#include_next <mcuconf.h>
#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 <halconf.h>
```
`mcuconf.h`:
```c
#undef STM32_PWM_USE_TIM2
#define STM32_PWM_USE_TIM2 TRUE
```c [mcuconf.h]
#pragma once
#include_next <mcuconf.h>
#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:

44
docs/features/backlight.md
View File

@ -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 <halconf.h>
```
`mcuconf.h`:
```c
#undef STM32_PWM_USE_TIM4
#define STM32_PWM_USE_TIM4 TRUE
```c [mcuconf.h]
#pragma once
#include_next <mcuconf.h>
#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 <halconf.h>
```
`mcuconf.h`:
```c
#undef STM32_GPT_USE_TIM15
#define STM32_GPT_USE_TIM15 TRUE
```c [mcuconf.h]
#pragma once
#include_next <mcuconf.h>
#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:

14
docs/features/ps2_mouse.md
View File

@ -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 <halconf.h>
```
### USART Version {#usart-version}