/* NXP QN908x specific information for the `periph` drivers */ /** @defgroup cpu_qn908x NXP QN908x @ingroup cpu @brief NXP QN908x BLE-enabled Cortex-M4F MCU specific implementation The NXP QN908x family of chips such as the QN9080 feature a Cortex-M4F, Bluetooth Low Energy, USB 2.0 and in some SKUs like the QN9080SIP NFC as well. The CPU is designed to be ultra-low-power and high-performance, allowing applications with small battery capacity. It includes an optional DC-DC and LDO, low power sleep timers, I2C, SPI, ADC, SPIFI and several other peripherals. @defgroup cpu_qn908x_cpuid NXP QN908x CPUID @ingroup cpu_qn908x @brief NXP QN908x CPUID driver No configuration is necessary. The CPUID value is based on the factory assigned default Bluetooth address in the read-only flash section which may not be the Bluetooth address used by the Bluetooth module if a different one was programmed there. @defgroup cpu_qn908x_gpio NXP QN908x GPIO @ingroup cpu_qn908x @brief NXP QN908x GPIO driver The GPIO driver uses the @ref GPIO_PIN(port, pin) macro to declare pins. No configuration is necessary. @defgroup cpu_qn908x_adc NXP QN908x ADC - Analog to Digital converter @ingroup cpu_qn908x @brief NXP QN908x ADC driver This ADC is a differential sigma-delta ADC. There are 9 external signals named ADC0 to ADC7 and ADC_VREFI that can be connected to specific external GPIO pins. There are several combinations of measurements possible with the ADC module using these external signals as well as some internal signals, but not every combination is a possible input pair to the ADC. The ADC block runs at either 4 MHz or 32 KHz from the high speed or low speed clock sources respective. An additional divisor is available to select some intermediate clock values. However, this is not the sample rate, since a single sample from @ref adc_sample() requires multiple internal samples which are then filtered and decimated by the hardware, giving about 128 slower sample rate than the selected clock. Each board-defined ADC line is configured with a single integer value which is the logic or of the following values: - The differential pair of signals among the options in @ref qn908x_adc_channel_t, - For those channels that use the "Vinn" signal, a value selecting the Vinn signal in @ref qn908x_adc_vinn_t, - The reference voltage "Vref" that the ADC will use for its full range selected with @ref qn908x_adc_vref_t, - The ADC input gain as selected by @ref qn908x_adc_gain_t, which will multiply the differential input by a factor between 0.5 and 2, and - An optional gain flag @ref ADC_VREF_GAIN_X15. - An optional PGA enabled flag @ref ADC_PGA_ENABLE. The hardware resolution of the ADC data is always 23-bits signed, but smaller resolutions can be requested which will result in a smaller output value. An internal temperature sensor is available and connected to the ADC when selecting @ref ADC_CHANNEL_TEMP as the channel. In this case the returned value is still a number that represents the temperature dependent voltage level of the internal signal which then needs to be converted to a temperature by the application using calibration parameters. When using the internal temperature sensor, the 1.2V bandgap Vref is recommended with a Vinn of 1/2 Vref since the measured voltage is about 800 mV at room temperature. A special microvolts (ADC_RES_UV) resolution value for @ref adc_res_t is supported when using the internal 1.2 V bandgap as the reference voltage, in which case @ref adc_sample will return the measured value in microvolts as a signed integer, with a max range of +/- 1.8 V when using the x1.5 Vref multiplier. This special resolution mode takes into account the factory calibration of the internal reference voltage for more accurate readings. In any other case, the return value is a signed integer with as many bits as resolution requested not including the sign bit. Note that the return value may be a negative when measuring a negative differential voltage between the plus and minus side of the input. For example, if 8-bit resolution is requested for an ADC line where the channel connects the - side to Vinn configured as Vss, a maximum value of 255 can be returned when the + side level is as high as the Vref signal. However, a negative value of -255 is also possible if Vinn is configured as Vref and the + side level is as low as Vss. ### ADC configuration example (for periph_conf.h) ### @code static const adc_conf_t adc_config[] = { /* Pin A11 to Vss, 1.8v Vref. */ ADC_CHANNEL_ADC7_VINN | ADC_VREF_GAIN_X15, /* Pin A10 to A11, 1.2V Vref. */ ADC_CHANNEL_ADC6_ADC7, /* Temperature (in V) over to 0.6 V, 1.2 V Vref. */ ADC_CHANNEL_TEMP | ADC_VINN_VREF_2, /* Internal "battery monitor", Vcc/4 to Vss, 1.2V Vref. */ ADC_CHANNEL_VCC4_VINN | ADC_VINN_AVSS, }; #define ADC_NUMOF ARRAY_SIZE(adc_config) #define QN908X_ADC_CLOCK ADC_CLOCK_500K @endcode @defgroup cpu_qn908x_i2c NXP QN908x I2C @ingroup cpu_qn908x @brief NXP QN908x I2C driver There are several FLEXCOMM interfaces in this chip, but only two of these support I2C (FLEXCOMM1 and FLEXCOMM2) which are mapped as I2C0 and I2C1, respectively. A single FLEXCOMM interface can only be used for one of the I2C, UART or SPI interfaces, so for example USART1 and I2C0 can't be used at the same time since they are both the same FLEXCOMM1 interface. ### I2C configuration example (for periph_conf.h) ### static const i2c_conf_t i2c_config[] = { { .dev = I2C0, .pin_scl = GPIO_PIN(PORT_A, 6), // or A8, A12, A20 .pin_sda = GPIO_PIN(PORT_A, 7), // or A9, A13, A21 .speed = I2C_SPEED_FAST, }, { .dev = I2C1, .pin_scl = GPIO_PIN(PORT_A, 2), // or A5, A23, A27 .pin_sda = GPIO_PIN(PORT_A, 3), // or A4, A22, A26 .speed = I2C_SPEED_FAST, }, }; #define I2C_NUMOF ARRAY_SIZE(i2c_config) @defgroup cpu_qn908x_spi NXP QN908x Serial Peripheral Interface (SPI) @ingroup cpu_qn908x @brief NXP QN908x timer driver Two of the FLEXCOMM interfaces in this chip can be used as SPI interfaces named SPI0 and SPI1, which correspond to FLEXCOMM2 and FLEXCOMM3. Note that FLEXCOMM2 (SPI0) is also shared with the I2C peripheral I2C1 and both can't be used at the same time. The SPI flexcomm clock is directly driven from the AHB bus, so its clock is limited by the core CPU clock and the AHB divisor on the higher side with an optional frequency divider of up to 65536 to generate lower clock frequencies. Multiple peripherals can be connected to the same SPI bus, using different CS pins, with a maximum of 4 hardware CS peripherals per bus and any number of software CS peripherals. This driver uses the [OSHA SPI Signal Names]( https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/) and while it only implements the Controller mode, the hardware is capable of operating in Peripheral mode as well so we use the COPI/CIPO names. ### SPI configuration example (for periph_conf.h) ### The following example uses only one hardware CS (number 0) and leaves the rest unused. Check the user manual for the full list of CS pins available. When configuring the CS line on a driver, you should pass a @ref SPI_HWCS to use the hardware CS mode defined in this configuration. To use any other GPIO as a CS line selected by software it is also possible to pass a @ref GPIO_PIN pin. @code static const spi_conf_t spi_config[] = { { .dev = SPI0, .cipo_pin = GPIO_PIN(PORT_A, 5), .copi_pin = GPIO_PIN(PORT_A, 4), .clk_pin = GPIO_PIN(PORT_A, 30), .cs_pin = { GPIO_PIN(PORT_A, 3), /* Use as SPI_HWCS(0) */ GPIO_UNDEF, GPIO_UNDEF, GPIO_UNDEF }, }, }; @endcode @defgroup cpu_qn908x_timer NXP QN908x Standard counter/timers (CTIMER) @ingroup cpu_qn908x @brief NXP QN908x timer driver The QN908x have 4 standard counter/timers (CTIMER). These timers allow to count clock cycles from the APB clock with a 32-bit prescaler, effectively dividing the APB clock frequency by a configurable number up to 2^32, allowing a great range of timer frequencies selected at runtime. Each timer has 4 independent channels to match against which can generate an interrupt. TODO: These CTIMERs and the SCT timers can both be used as PWM as well, with different set of capabilities. Boards should be able to split these CTIMER and SCT blocks between pwm and timer functions. ### Timer configuration example (for periph_conf.h) ### #define TIMER_NUMOF 4 @defgroup cpu_qn908x_rtc NXP QN908x Real-Time-Clock (RTC) @ingroup cpu_qn908x @brief NXP QN908x RTC driver The RTC block in the QN908x can be driven by the external 32.768 kHz crystal or by the internal 32 kHz RCO oscillator clock, whichever is selected as the `CLK_32K` clock source. The RTC has an internal "second counter" calibrated depending on the frequency of the clock source selected at the time the RTC clock is initialized by calling @ref rtc_init. The RTC function in this cpu doesn't have a match against a target value to generate an interrupt like the timer peripheral, instead, the alarm function in the rtc.h interface is implemented by an interrupt generated every second which checks the target value in software. Keep in mind that while the RTC can operate while the cpu is the power-down 0 mode, using the alarm functionality during that time means that the cpu will wake up every second for a brief moment, potentially impacting the power consumption. No RTC-specific configuration is necessary. @defgroup cpu_qn908x_uart NXP QN908x UART @ingroup cpu_qn908x @brief NXP QN908x UART driver There are several FLEXCOMM interfaces in this chip, but only two of these support UART (FLEXCOMM0 and FLEXCOMM1). The default UART mode is 8n1 and can be changed with the uart_mode() function. If only RX or only TX is desired, the other pin can be set to GPIO_UNDEF. ### UART configuration example (for periph_conf.h) ### static const uart_conf_t uart_config[] = { { .dev = USART0, .rx_pin = GPIO_PIN(PORT_A, 17), // or A5 .tx_pin = GPIO_PIN(PORT_A, 16), // or A4 }, { .dev = USART1, .rx_pin = GPIO_PIN(PORT_A, 9), // or A13 .tx_pin = GPIO_PIN(PORT_A, 8), // or A12 }, }; #define UART_NUMOF ARRAY_SIZE(uart_config) @defgroup cpu_qn908x_wdt NXP QN908x Watchdog timer (WDT) @ingroup cpu_qn908x @brief NXP QN908x Watchdog timer (WDT) The Watchdog timer in the NXP QN908x starts disabled on reset: the clock bit `CLK_WDT_EN` is enabled in the `CLK_EN` register on reset so the timer is running but the interrupt and reset functions are disabled. However, after the read-only bootloader ROM in the QN908x transfer the control flow to the user application (the RIOT kernel) the Watchdog is enabled with a timeout of 10 seconds. If your board does not include the `periph_wdt` module, the Watchdog will be disabled at `cpu_init()` time and there's no configuration necessary. However, if your board or application does include it, the Watchdog will be left configured with the 10 second timeout set by the Bootloader and you need to call `wdt_setup_reboot()` or `wdt_setup_reboot_with_callback()` within the first 10 seconds. The WDT block supports different clock sources which would be configured by the board since they depend on whether the optional crystals are populated in your board. Nevertheless, the millisecond values passed to `wdt_setup_reboot*` are internally converted to clock ticks using the clock configured at the time the function was called. `wdt_setup_reboot*()` can be called multiple times to change the WDT parameters or after changing the WDT clock source, but in any case `wdt_start()` must be called after it to start the WDT operation. Once the WDT triggers, it is not possible to avoid the device reboot and calling wdt_kick() from the WDT callback (if any) or after the callback was called will not have any effect. Note that, however, if the WDT callback returns before the configured CONFIG_WDT_WARNING_PERIOD the CPU will continue executing the code before the WDT interrupt occurred. If this is not desired, an infinite loop at the end of the WDT callback, after the safety operations have been performed is advisable. */