Tidy up adjustable ws2812 timing (#15299)

docs/ws2812_driver.md

@@ -49,6 +49,19 @@ WS2812_DRIVER = bitbang
 
 !> This driver is not hardware accelerated and may not be performant on heavily loaded systems.
 
+#### Adjusting bit timings
+
+The WS2812 LED communication topology depends on a serialized timed window. Different versions of the addressable LEDs have differing requirements for the timing parameters, for instance, of the SK6812.
+You can tune these parameters through the definition of the following macros:
+
+| Macro               |Default                                     | AVR                | ARM                |
+|---------------------|--------------------------------------------|--------------------|--------------------|
+|`WS2812_TIMING       |`1250`                                      | :heavy_check_mark: | :heavy_check_mark: |
+|`WS2812_T0H`         |`350`                                       | :heavy_check_mark: | :heavy_check_mark: |
+|`WS2812_T0L`         |`WS2812_TIMING - WS2812_T0H`                |                    | :heavy_check_mark: |
+|`WS2812_T1H`         |`900`                                       | :heavy_check_mark: | :heavy_check_mark: |
+|`WS2812_T1L`         |`WS2812_TIMING - WS2812_T1L`                |                    | :heavy_check_mark: |
+
 ### I2C
 Targeting boards where WS2812 support is offloaded to a 2nd MCU. Currently the driver is limited to AVR given the known consumers are ps2avrGB/BMC. To configure it, add this to your rules.mk:
 
@@ -62,23 +75,6 @@ Configure the hardware via your config.h:
 #define WS2812_TIMEOUT 100 // default: 100
 ```
 
-##### Adjusting bit timings (ChibiOS only)
-
-The WS2812 LED communication topology depends on a serialized timed window, lasting typically 1250ns in total, where a bit is interpreted as either 0 or 1 depending on for how much time the `RGB_DI` pin voltage is kept high and how much time it is kept low. The WS2812 datasheet specifies quantities defined as `T0H`, `T0L`, `T1H`, `T1L` (respectively, typically 350ns, 900ns, 900ns and 350ns); a bit is interpreted as zero if the voltage on the control pin is held high for `T0H` and then `T0L`, and the bit is interpreted as one if the voltage is held high for `T1H` and then low for `T1L`. Additionally, there is also a RESET time parameter whereby an LED color is reset if the voltage control pin is kept low for more than that parameter; in WS2812 that amount is 6000 nanoseconds.
-
-The WS2812 "bit-banged" ChibiOS driver does just that, in a simple way. It defines these values and governs the `RGB_DI` pin according to these times. There are, however, other LED parts that work in a communication topology similar to this but with different timing parameters; such is the case, for instance, of the SK6812. In order to better support such LEDs whilst keeping the WS2812 driver applicable, QMK allows you to tune these parameters through the definition macros:
-
-| Macro               |Default                                     |
-|---------------------|--------------------------------------------|
-|`WS2812_TIMING       |`1250`                                      |
-|`WS2812_T0H`         |`350`                                       |
-|`WS2812_T0L`         |`WS2812_TIMING - WS2812_T0H`                |
-|`WS2812_T1H`         |`900`                                       |
-|`WS2812_T1L`         |`WS2812_TIMING - WS2812_T1L`                |
-|`WS2812_RES`         |`6000`                                      |
-
-It must be noted, however, that this tuning is only available for the ARM family of microprocessors (since it's ChibiOS-dependent) and not available for PWM and SPI drivers -- so if you intend to use this be aware it will only work with the "bit-banged" driver which is knowingly slower and can possibly throttle the microcontroller if too many LEDs are used.
-
 ### SPI
 Targeting STM32 boards where WS2812 support is offloaded to an SPI hardware device. The advantage is that the use of DMA offloads processing of the WS2812 protocol from the MCU. `RGB_DI_PIN` for this driver is the configured SPI MOSI pin. Due to the nature of repurposing SPI to drive the LEDs, the other SPI pins, MISO and SCK, **must** remain unused. To configure it, add this to your rules.mk:
 

drivers/ws2812.h

@@ -17,11 +17,41 @@
 
 #include "quantum/color.h"
 
+/*
+ * The WS2812 datasheets define T1H 900ns, T0H 350ns, T1L 350ns, T0L 900ns. Hence, by default, these
+ * are chosen to be conservative and avoid problems rather than for maximum throughput; in the code,
+ * this is done by default using a WS2812_TIMING parameter that accounts for the whole window (1250ns)
+ * and defining T1H and T0H; T1L and T0L are obtained by subtracting their low counterparts from the window.
+ *
+ * However, there are certain "WS2812"-like LEDs, like the SK6812s, which work in a similar
+ * communication topology but use different timings for the window and the T1L, T1H, T0L and T0H.
+ * This means that, albeit the same driver being applicable, the timings must be adapted.
+ */
+
+#ifndef WS2812_TIMING
+#    define WS2812_TIMING 1250
+#endif
+
+#ifndef WS2812_T1H
+#    define WS2812_T1H 900  // Width of a 1 bit in ns
+#endif
+
+#ifndef WS2812_T1L
+#    define WS2812_T1L (WS2812_TIMING - WS2812_T1H)  // Width of a 1 bit in ns
+#endif
+
+#ifndef WS2812_T0H
+#    define WS2812_T0H 350  // Width of a 0 bit in ns
+#endif
+
+#ifndef WS2812_T0L
+#    define WS2812_T0L (WS2812_TIMING - WS2812_T0H)  // Width of a 0 bit in ns
+#endif
+
 /*
  * Older WS2812s can handle a reset time (TRST) of 50us, but recent
  * component revisions require a minimum of 280us.
  */
-
 #if !defined(WS2812_TRST_US)
 #    define WS2812_TRST_US 280
 #endif

platforms/avr/drivers/ws2812.c

@@ -52,20 +52,15 @@ void ws2812_setleds(LED_TYPE *ledarray, uint16_t number_of_leds) {
   using the fast 800kHz clockless WS2811/2812 protocol.
 */
 
-// Timing in ns
-#define w_zeropulse 350
-#define w_onepulse 900
-#define w_totalperiod 1250
-
 // Fixed cycles used by the inner loop
 #define w_fixedlow 2
 #define w_fixedhigh 4
 #define w_fixedtotal 8
 
 // Insert NOPs to match the timing, if possible
-#define w_zerocycles (((F_CPU / 1000) * w_zeropulse) / 1000000)
-#define w_onecycles (((F_CPU / 1000) * w_onepulse + 500000) / 1000000)
-#define w_totalcycles (((F_CPU / 1000) * w_totalperiod + 500000) / 1000000)
+#define w_zerocycles (((F_CPU / 1000) * WS2812_T0H) / 1000000)
+#define w_onecycles (((F_CPU / 1000) * WS2812_T1H + 500000) / 1000000)
+#define w_totalcycles (((F_CPU / 1000) * WS2812_TIMING + 500000) / 1000000)
 
 // w1_nops - nops between rising edge and falling edge - low
 #if w_zerocycles >= w_fixedlow

platforms/chibios/drivers/ws2812.c

@@ -22,6 +22,12 @@
 #    define WS2812_OUTPUT_MODE PAL_MODE_OUTPUT_OPENDRAIN
 #endif
 
+// The reset gap can be 6000 ns, but depending on the LED strip it may have to be increased
+// to values like 600000 ns. If it is too small, the pixels will show nothing most of the time.
+#ifndef WS2812_RES
+#    define WS2812_RES (1000 * WS2812_TRST_US)  // Width of the low gap between bits to cause a frame to latch
+#endif
+
 #define NUMBER_NOPS 6
 #define CYCLES_PER_SEC (CPU_CLOCK / NUMBER_NOPS * NOP_FUDGE)
 #define NS_PER_SEC (1000000000L)  // Note that this has to be SIGNED since we want to be able to check for negative values of derivatives
@@ -40,36 +46,6 @@
         }                                           \
     } while (0)
 
-/* The WS2812 datasheets define T1H 900ns, T0H 350ns, T1L 350ns, T0L 900ns. Hence, by default, these are chosen to be conservative and avoid problems rather than for maximum throughput; in the code, this is done by default using a WS2812_TIMING parameter that accounts for the whole window (1250ns) and defining T1H and T0H; T1L and T0L are obtained by subtracting their low counterparts from the window.
-However, there are certain "WS2812"-like LEDs, like the SK6812s, which work in a similar communication topology but use different timings for the window and the T1L, T1H, T0L and T0H. This means that, albeit the same driver being applicable, the timings must be adapted. The following defines are done such that the adjustment of these timings can be done in the keyboard's config.h; if nothing is said, the defines default to the WS2812 ones.
-*/
-
-#ifndef WS2812_TIMING
-#    define WS2812_TIMING 1250
-#endif
-
-#ifndef WS2812_T1H
-#    define WS2812_T1H 900  // Width of a 1 bit in ns
-#endif
-
-#ifndef WS2812_T1L
-#    define WS2812_T1L (WS2812_TIMING - WS2812_T1H)  // Width of a 1 bit in ns
-#endif
-
-#ifndef WS2812_T0H
-#    define WS2812_T0H 350  // Width of a 0 bit in ns
-#endif
-
-#ifndef WS2812_T0L
-#    define WS2812_T0L (WS2812_TIMING - WS2812_T0H)  // Width of a 0 bit in ns
-#endif
-
-// The reset gap can be 6000 ns, but depending on the LED strip it may have to be increased
-// to values like 600000 ns. If it is too small, the pixels will show nothing most of the time.
-#ifndef WS2812_RES
-#    define WS2812_RES (1000 * WS2812_TRST_US)  // Width of the low gap between bits to cause a frame to latch
-#endif
-
 void sendByte(uint8_t byte) {
     // WS2812 protocol wants most significant bits first
     for (unsigned char bit = 0; bit < 8; bit++) {

platforms/chibios/drivers/ws2812_pwm.c

@@ -71,7 +71,7 @@
  * Calculate the number of zeroes to add at the end assuming 1.25 uS/bit:
  */
 #define WS2812_COLOR_BITS (WS2812_CHANNELS * 8)
-#define WS2812_RESET_BIT_N (1000 * WS2812_TRST_US / 1250)
+#define WS2812_RESET_BIT_N (1000 * WS2812_TRST_US / WS2812_TIMING)
 #define WS2812_COLOR_BIT_N (RGBLED_NUM * WS2812_COLOR_BITS)    /**< Number of data bits */
 #define WS2812_BIT_N (WS2812_COLOR_BIT_N + WS2812_RESET_BIT_N) /**< Total number of bits in a frame */
 

platforms/chibios/drivers/ws2812_spi.c

@@ -77,7 +77,7 @@
 #endif
 #define BYTES_FOR_LED (BYTES_FOR_LED_BYTE * WS2812_CHANNELS)
 #define DATA_SIZE (BYTES_FOR_LED * RGBLED_NUM)
-#define RESET_SIZE (1000 * WS2812_TRST_US / (2 * 1250))
+#define RESET_SIZE (1000 * WS2812_TRST_US / (2 * WS2812_TIMING))
 #define PREAMBLE_SIZE 4
 
 static uint8_t txbuf[PREAMBLE_SIZE + DATA_SIZE + RESET_SIZE] = {0};