From 2194a3366e8d3422052f8399c6fa84988da9fc82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20Nohlg=C3=A5rd?= Date: Wed, 19 Jul 2017 17:36:36 +0200 Subject: [PATCH 1/3] kinetis: Update documentation for periph drivers --- cpu/kinetis_common/doc.txt | 264 ++++++++++++++++++------------------- 1 file changed, 125 insertions(+), 139 deletions(-) diff --git a/cpu/kinetis_common/doc.txt b/cpu/kinetis_common/doc.txt index aefacdb6c6..2db10f58ee 100644 --- a/cpu/kinetis_common/doc.txt +++ b/cpu/kinetis_common/doc.txt @@ -1,63 +1,54 @@ /** - * @defgroup cpu_kinetis_common Freescale Kinetis MCU + * @defgroup cpu_kinetis_common NXP Kinetis MCU * @ingroup cpu - * @brief Common Drivers for Freescale Kinetis MCUs + * @brief NXP Kinetis CPU peripheral drivers */ /** * @defgroup cpu_kinetis_common_adc Kinetis ADC * @ingroup cpu_kinetis_common - * @brief ADC driver. + * @brief ADC driver * * ### ADC Configuration Example (for periph_conf.h) ### * - * #define ADC_NUMOF (1U) - * #define ADC_0_EN 1 - * #define ADC_MAX_CHANNELS 1 - * - * // ADC 0 configuration - * #define ADC_0_DEV ADC0 - * #define ADC_0_MODULE_CLOCK CLOCK_CORECLOCK - * #define ADC_0_CHANNELS 1 - * #define ADC_0_CLKEN() (SIM->SCGC6 |= (SIM_SCGC6_ADC0_MASK)) - * #define ADC_0_CLKDIS() (SIM->SCGC6 &= ~(SIM_SCGC6_ADC0_MASK)) - * #define ADC_0_PORT_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTE_MASK)) - * - * #define ADC_0_CH5 11 - * #define ADC_0_CH5_PIN 1 - * #define ADC_0_CH5_PIN_AF 0 - * #define ADC_0_CH5_PORT PORTE + * static const adc_conf_t adc_config[] = { + * { .dev = ADC0, .pin = GPIO_UNDEF , .chan = 0 }, // ADC0_DP0 + * { .dev = ADC0, .pin = GPIO_UNDEF , .chan = 19 }, // ADC0_DM0 + * { .dev = ADC1, .pin = GPIO_UNDEF , .chan = 0 }, // ADC1_DP0 + * { .dev = ADC1, .pin = GPIO_UNDEF , .chan = 19 }, // ADC1_DM0 + * { .dev = ADC0, .pin = GPIO_PIN(PORT_B, 0), .chan = 8 }, // PTB0 + * { .dev = ADC0, .pin = GPIO_PIN(PORT_B, 1), .chan = 9 }, // PTB1 + * { .dev = ADC0, .pin = GPIO_PIN(PORT_C, 1), .chan = 15 }, // PTC1 + * { .dev = ADC0, .pin = GPIO_PIN(PORT_C, 2), .chan = 4 }, // PTC2 + * }; + * #define ADC_NUMOF (sizeof(adc_config) / sizeof(adc_config[0])) */ /** * @defgroup cpu_kinetis_common_cpuid Kinetis CPUID * @ingroup cpu_kinetis_common - * @brief CPUID driver. + * @brief CPUID driver + * + * No configuration is necessary. */ /** * @defgroup cpu_kinetis_common_gpio Kinetis GPIO * @ingroup cpu_kinetis_common - * @brief GPIO driver. + * @brief GPIO driver + * + * The GPIO driver uses the @ref GPIO_PIN(port, pin) macro to declare pins. * * ### GPIO Configuration Example (for periph_conf.h) ### * - * #define GPIO_NUMOF 1 - * #define GPIO_0_EN 0 - * #define GPIO_IRQ_PRIO 1 - * #define ISR_PORT_D isr_portd + * #define GPIO_IRQ_PRIO CPU_DEFAULT_IRQ_PRIO * - * #define GPIO_22_DEV GPIOD - * #define GPIO_22_PORT PORTD - * #define GPIO_22_PIN 1 - * #define GPIO_22_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTD_MASK)) - * #define GPIO_22_IRQ PORTD_IRQn */ /** * @defgroup cpu_kinetis_common_i2c Kinetis I2C * @ingroup cpu_kinetis_common - * @brief I2C driver. + * @brief I2C driver * * ### I2C Configuration Example (for periph_conf.h) ### * @@ -97,7 +88,7 @@ /** * @defgroup cpu_kinetis_common_pwm Kinetis PWM * @ingroup cpu_kinetis_common - * @brief PWM driver. + * @brief PWM driver * * ### PWM Configuration Example (for periph_conf.h) ### * @@ -161,7 +152,7 @@ * @ingroup cpu_kinetis_common * @brief RTC is clocked by a 32.768 kHz clock. * Please note the manual of your MCU or SiP for the - * clock setting for the RTC module. After initilization + * clock setting for the RTC module. After initialization * Time Seconds Register (TSR) increments once a second. * The TSR (also TAR) value will be converted to the stuct tm * and back with the help of stdlib functions that are @@ -175,7 +166,8 @@ * #define RTC_DEV RTC * #define RTC_UNLOCK() (SIM->SCGC6 |= (SIM_SCGC6_RTC_MASK)) * - * Optional settings: + * Optional settings to configure internal load capacitors (see + * reference manual): * * #define RTC_LOAD_CAP_BITS 0 */ @@ -185,126 +177,120 @@ * @ingroup cpu_kinetis_common * @brief Kinetis SPI driver for MCUs with Cortex-M4 core. * - * If necessary, it is possible to define two RIOT SPI buses for - * each Kinetis hardware SPI module by specifying different CTAS - * (timing register number) for the two buses. It is then possible to - * initialize the two RIOT SPI buses with different baud rates or - * polarity settings. - * - * SPI_x_INDEX should be set to the index on the hardware module - * used (SPI0 => 0, SPI1 => 1 etc). spi_acquire and spi_release will - * share the same lock for all SPI buses defined with the same - * SPI_x_INDEX. + * The SPI baud rate and other timings are generated from the bus + * clock via prescalers, the hardware module allows for very + * detailed timing configuration, but a tool exists to generate a + * standard timing configuration for any given module clock frequency. + * The timing configuration tool is found in + * cpu/kinetis_common/dist/calc_spi_scalers * * Finer tuning of timings than the RIOT SPI API is capable of is - * supported by setting macros SPI_0_TCSC_FREQ, SPI_0_TASC_FREQ, - * SPI_0_TDT_FREQ. These macros define the desired maximum frequency - * of the tCSC, tASC, and tDT SPI - * timings (i.e. reciprocal of time). See the reference manual for - * your Kinetis CPU (Chapter: "SPI module, Functional description, - * Module baud rate and clock delay generation") for a description of - * each delay. Set to 0 or leave unset to default to using the same - * delay timing as the baudrate. + * supported by modifying the generated configuration. See the + * reference manual for your Kinetis CPU (Chapter: "SPI module, + * Functional description, Module baud rate and clock delay + * generation") for a description of each delay. + * + * The SPI driver supports using GPIO pins for chip select, as an + * alternative to using hardware chip select. + * The pins specified in spi_config[x].pin_cs[y] are the hardware + * chip select pins, designated SPIx_PCSy in the hardware reference + * documentation. These pins can not be chosen arbitrarily but must + * be selected from the pins which support the SPIx_PCSy function + * in the pin multiplexing table found in the reference manual. + * + * To use a hardware controlled chip select pin, use the SPI_HWCS + * macro instead of GPIO_PIN when calling spi_acquire() in the + * device driver. + * Software managed CS signals can use any GPIO pin, at the cost of + * extra delays in the transfer because of the additional overhead + * of calling gpio_set/clear at every transfer. * * ### SPI Configuration Example (for periph_conf.h): ### * - * // SPI 0 device config - * #define SPI_0_DEV SPI0 - * #define SPI_0_INDEX 0 - * #define SPI_0_CTAS 0 - * #define SPI_0_CLKEN() (SIM->SCGC6 |= (SIM_SCGC6_SPI0_MASK)) - * #define SPI_0_CLKDIS() (SIM->SCGC6 &= ~(SIM_SCGC6_SPI0_MASK)) - * #define SPI_0_IRQ SPI0_IRQn - * #define SPI_0_IRQ_HANDLER isr_spi0 - * #define SPI_0_FREQ (48e6) + * static const uint32_t spi_clk_config[] = { + * // Use cpu/kinetis_common/dist/calc_spi_scalers to + * // generate the timing configuration + * }; * - * // SPI 0 pin configuration - * #define SPI_0_SCK_PORT PORTC - * #define SPI_0_SOUT_PORT PORTC - * #define SPI_0_SIN_PORT PORTC - * #define SPI_0_PCS0_PORT PORTC + * static const spi_conf_t spi_config[] = { + * { + * .dev = SPI0, + * .pin_miso = GPIO_PIN(PORT_D, 3), + * .pin_mosi = GPIO_PIN(PORT_D, 2), + * .pin_clk = GPIO_PIN(PORT_D, 1), + * .pin_cs = { + * GPIO_PIN(PORT_D, 0), + * GPIO_PIN(PORT_D, 4), + * GPIO_PIN(PORT_D, 5), + * GPIO_PIN(PORT_D, 6), + * GPIO_UNDEF + * }, + * .pcr = GPIO_AF_2, + * .simmask = SIM_SCGC6_SPI0_MASK + * }, + * { + * .dev = SPI1, + * .pin_miso = GPIO_PIN(PORT_E, 3), + * .pin_mosi = GPIO_PIN(PORT_E, 1), + * .pin_clk = GPIO_PIN(PORT_E, 2), + * .pin_cs = { + * GPIO_PIN(PORT_E, 4), + * GPIO_UNDEF, + * GPIO_UNDEF, + * GPIO_UNDEF, + * GPIO_UNDEF + * }, + * .pcr = GPIO_AF_2, + * .simmask = SIM_SCGC6_SPI1_MASK + * } + * }; * - * #define SPI_0_SCK_PORT_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTC_MASK)) - * #define SPI_0_SOUT_PORT_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTC_MASK)) - * #define SPI_0_SIN_PORT_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTC_MASK)) - * #define SPI_0_PCS0_PORT_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTC_MASK)) - * - * #define SPI_0_SCK_AF 2 - * #define SPI_0_SOUT_AF 2 - * #define SPI_0_SIN_AF 2 - * #define SPI_0_PCS0_AF 2 - * - * #define SPI_0_PCS0_PIN 4 - * #define SPI_0_SCK_PIN 5 - * #define SPI_0_SOUT_PIN 6 - * #define SPI_0_SIN_PIN 7 - * - * #define SPI_0_PCS0_ACTIVE_LOW 1 - * - * Alternative Configuration Example: - * - * // SPI 0 device config - * #define SPI_0_DEV SPI0 - * #define SPI_0_INDEX 0 - * #define SPI_0_CTAS 0 - * #define SPI_0_CLKEN() (SIM->SCGC6 |= (SIM_SCGC6_SPI0_MASK)) - * #define SPI_0_CLKDIS() (SIM->SCGC6 &= ~(SIM_SCGC6_SPI0_MASK)) - * #define SPI_0_IRQ SPI0_IRQn - * #define SPI_0_IRQ_HANDLER isr_spi0 - * #define SPI_0_FREQ (48e6) - * - * // SPI 0 pin configuration - * #define SPI_0_PORT PORTC - * #define SPI_0_PORT_CLKEN() (SIM->SCGC5 |= (SIM_SCGC5_PORTC_MASK)) - * #define SPI_0_AF 2 - * - * #define SPI_0_PCS0_PIN 4 - * #define SPI_0_SCK_PIN 5 - * #define SPI_0_SOUT_PIN 6 - * #define SPI_0_SIN_PIN 7 - * - * #define SPI_0_PCS0_ACTIVE_LOW 1 - * - * It is possible to use the hardware CS, currently only for the PCS0: - * - * #define KINETIS_SPI_USE_HW_CS 1 + * #define SPI_NUMOF (sizeof(spi_config) / sizeof(spi_config[0])) */ /** * @defgroup cpu_kinetis_common_timer Kinetis Timer * @ingroup cpu_kinetis_common - * @brief Periodic Interrupt Timer (PIT) driver. - * Implementation of riot-os low level timer interface - * for the Kinetis Periodic Interrupt Timer. + * @brief Periodic Interrupt Timer (PIT) and Low-Power Timer (LPTMR) driver. + * * The PIT is a count down timer, in order to use it with riot-os * a count up timer will be simulated. The PIT has four channels, * each two channels are cascaded. The n-1 channel is a prescaler * and the n channel a down counter. In standard configuration * with four channels, two simulated count up timer are possible. * + * To counteract the effects of the asynchronous operation of the + * LPTMR, this driver uses the RTT as a time base which the LPTMR + * is referenced against. This method reduces the timing jitter + * caused by mixing the clock domains of the bus clock used by the + * CPU and the 32kHz reference clock for the LPTMR counter. + * * ### Timer configuration Example (for periph_conf.h) ### * - * #define TIMER_NUMOF (1U) - * #define TIMER_0_EN 1 - * #define TIMER_1_EN 0 - * #define TIMER_IRQ_PRIO 1 - * #define TIMER_BASE PIT - * #define TIMER_MAX_VALUE (0xffffffff) - * #define TIMER_CLOCK CLOCK_CORECLOCK - * #define TIMER_CLKEN() (SIM->SCGC6 |= (SIM_SCGC6_PIT_MASK)) - * - * // Timer 0 configuration - * #define TIMER_0_PRESCALER_CH 0 - * #define TIMER_0_COUNTER_CH 1 - * #define TIMER_0_ISR isr_pit1 - * #define TIMER_0_IRQ_CHAN PIT1_IRQn - * - * // Timer 1 configuration - * #define TIMER_1_PRESCALER_CH 2 - * #define TIMER_1_COUNTER_CH 3 - * #define TIMER_1_ISR isr_pit3 - * #define TIMER_1_IRQ_CHAN PIT3_IRQn + * #define PIT_NUMOF (2U) + * #define PIT_CONFIG { \ + * { \ + * .prescaler_ch = 0, \ + * .count_ch = 1, \ + * }, \ + * { \ + * .prescaler_ch = 2, \ + * .count_ch = 3, \ + * }, \ + * } + * #define LPTMR_NUMOF (1U) + * #define LPTMR_CONFIG { \ + * { \ + * .dev = LPTMR0, \ + * .irqn = LPTMR0_IRQn, \ + * } \ + * } + * #define TIMER_NUMOF ((PIT_NUMOF) + (LPTMR_NUMOF)) * + * #define PIT_BASECLOCK (CLOCK_BUSCLOCK) + * #define PIT_ISR_0 isr_pit1 + * #define PIT_ISR_1 isr_pit3 + * #define LPTMR_ISR_0 isr_lptmr0 */ /** @@ -323,28 +309,28 @@ * static const uart_conf_t uart_config[] = { * { * .dev = UART0, - * .clken = (volatile uint32_t*)(BITBAND_REGADDR(SIM->SCGC4, SIM_SCGC4_UART0_SHIFT)), * .freq = CLOCK_CORECLOCK, * .pin_rx = GPIO_PIN(PORT_A, 14), * .pin_tx = GPIO_PIN(PORT_A, 15), * .pcr_rx = PORT_PCR_MUX(3), * .pcr_tx = PORT_PCR_MUX(3), * .irqn = UART0_RX_TX_IRQn, + * .scgc_addr = &SIM->SCGC4, + * .scgc_bit = SIM_SCGC4_UART0_SHIFT, + * .mode = UART_MODE_8N1, * }, * { * .dev = UART1, - * .clken = (volatile uint32_t*)(BITBAND_REGADDR(SIM->SCGC4, SIM_SCGC4_UART1_SHIFT)), * .freq = CLOCK_CORECLOCK, * .pin_rx = GPIO_PIN(PORT_C, 3), * .pin_tx = GPIO_PIN(PORT_C, 4), * .pcr_rx = PORT_PCR_MUX(3), * .pcr_tx = PORT_PCR_MUX(3), * .irqn = UART1_RX_TX_IRQn, + * .scgc_addr = &SIM->SCGC4, + * .scgc_bit = SIM_SCGC4_UART1_SHIFT, + * .mode = UART_MODE_8N1, * }, * }; * #define UART_NUMOF (sizeof(uart_config) / sizeof(uart_config[0])) - * - * Optional settings: - * - * #define KINETIS_UART_ADVANCED 1 */ From 86ae36b5be5697196b26ee41683924be0862f0d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20Nohlg=C3=A5rd?= Date: Thu, 20 Jul 2017 18:07:29 +0200 Subject: [PATCH 2/3] kinetis: Update documentation page titles --- cpu/k22f/include/cpu_conf.h | 4 ++-- cpu/k60/include/cpu_conf.h | 5 +++-- cpu/k64f/include/cpu_conf.h | 6 +++--- cpu/kw2xd/include/cpu_conf.h | 10 +++++++--- 4 files changed, 15 insertions(+), 10 deletions(-) diff --git a/cpu/k22f/include/cpu_conf.h b/cpu/k22f/include/cpu_conf.h index 167305a367..bee596e01b 100644 --- a/cpu/k22f/include/cpu_conf.h +++ b/cpu/k22f/include/cpu_conf.h @@ -7,10 +7,10 @@ */ /** - * @defgroup cpu_k22f NXP Kinetis K22F MCU + * @defgroup cpu_k22f NXP Kinetis K22F * @ingroup cpu * @brief CPU specific implementations for the NXP Kinetis K22F - * Cortex-M4 MCU. + * Cortex-M4 MCU * @{ * * @file diff --git a/cpu/k60/include/cpu_conf.h b/cpu/k60/include/cpu_conf.h index 2f45720cb6..4399c10f27 100644 --- a/cpu/k60/include/cpu_conf.h +++ b/cpu/k60/include/cpu_conf.h @@ -7,9 +7,10 @@ */ /** - * @defgroup cpu_k60 Freescale Kinetis K60 + * @defgroup cpu_k60 NXP Kinetis K60 * @ingroup cpu - * @brief CPU specific implementations for the Freescale Kinetis K60 + * @brief CPU specific implementations for the NXP Kinetis K60 + * Cortex-M4 MCU * @{ * * @file diff --git a/cpu/k64f/include/cpu_conf.h b/cpu/k64f/include/cpu_conf.h index 22ce06c6b4..88400eb117 100644 --- a/cpu/k64f/include/cpu_conf.h +++ b/cpu/k64f/include/cpu_conf.h @@ -8,10 +8,10 @@ */ /** - * @defgroup cpu_k64f Freescale K64F MCU + * @defgroup cpu_k64f NXP Kinetis K64F * @ingroup cpu - * @brief CPU specific implementations for the Freescale K64F - * Kinetis Cortex-M4 MCU. + * @brief CPU specific implementations for the NXP Kinetis K64F + * Cortex-M4 MCU * @{ * * @file diff --git a/cpu/kw2xd/include/cpu_conf.h b/cpu/kw2xd/include/cpu_conf.h index 25b3fc0b49..b6a2d29f7b 100644 --- a/cpu/kw2xd/include/cpu_conf.h +++ b/cpu/kw2xd/include/cpu_conf.h @@ -8,11 +8,15 @@ */ /** - * @defgroup cpu_kw2xd KW2xD SiP + * @defgroup cpu_kw2xd NXP Kinetis KW2xD * @ingroup cpu - * @brief CPU specific implementations for the NXP/Freescale KW2xD SiP. - * The SiP incorporates a low power 2.4 GHz transceiver and a + * @brief CPU specific implementations for the NXP Kinetis KW2xD SiP + * + * The SiP incorporates a low power 2.4 GHz transceiver, and a * Kinetis Cortex-M4 MCU. + * + * From the register map and functional description it seems + * like the transceiver is a close relative of the NXP MCR20A. * @{ * * @file From cb9e3c13bf4b5b3e7e7aa3a76aa67b8072c1d2d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20Nohlg=C3=A5rd?= Date: Fri, 21 Jul 2017 09:57:27 +0200 Subject: [PATCH 3/3] kinetis: fix capitalization of periph doc headings --- cpu/kinetis_common/doc.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/cpu/kinetis_common/doc.txt b/cpu/kinetis_common/doc.txt index 2db10f58ee..83bb09bf65 100644 --- a/cpu/kinetis_common/doc.txt +++ b/cpu/kinetis_common/doc.txt @@ -9,7 +9,7 @@ * @ingroup cpu_kinetis_common * @brief ADC driver * - * ### ADC Configuration Example (for periph_conf.h) ### + *             ### ADC configuration example (for periph_conf.h) ### * * static const adc_conf_t adc_config[] = { * { .dev = ADC0, .pin = GPIO_UNDEF , .chan = 0 }, // ADC0_DP0 @@ -39,7 +39,7 @@ * * The GPIO driver uses the @ref GPIO_PIN(port, pin) macro to declare pins. * - * ### GPIO Configuration Example (for periph_conf.h) ### + *             ### GPIO configuration example (for periph_conf.h) ### * * #define GPIO_IRQ_PRIO CPU_DEFAULT_IRQ_PRIO * @@ -50,7 +50,7 @@ * @ingroup cpu_kinetis_common * @brief I2C driver * - * ### I2C Configuration Example (for periph_conf.h) ### + *             ### I2C configuration example (for periph_conf.h) ### * * #define I2C_NUMOF (1U) * #define I2C_CLK (48e6) @@ -90,7 +90,7 @@ * @ingroup cpu_kinetis_common * @brief PWM driver * - * ### PWM Configuration Example (for periph_conf.h) ### + *             ### PWM configuration example (for periph_conf.h) ### * * #define PWM_NUMOF (1U) * #define PWM_0_EN 1 @@ -123,7 +123,7 @@ * looks random. Reference Manual recommends to use the RNGA as entropy * source. * - * ### RNGA Configuration Example (for periph_conf.h) ### + *             ### RNGA configuration example (for periph_conf.h) ### * * #define RANDOM_NUMOF (1U) * #define KINETIS_RNGA RNG @@ -139,7 +139,7 @@ * looks random. Reference Manual recommends to use the RNGB as entropy * source. * - * ### RNGB Configuration Example (for periph_conf.h) ### + *             ### RNGB configuration example (for periph_conf.h) ### * * #define RANDOM_NUMOF (1U) * #define KINETIS_RNGB RNG @@ -160,7 +160,7 @@ * The driver supports alarm, it is stored in the * Time Alarm Registers (TAR) and the unit is seconds. * - * ### RTC Configuration Example (for periph_conf.h) ### + *             ### RTC configuration example (for periph_conf.h) ### * * #define RTC_NUMOF (1U) * #define RTC_DEV RTC @@ -205,7 +205,7 @@ * extra delays in the transfer because of the additional overhead * of calling gpio_set/clear at every transfer. * - * ### SPI Configuration Example (for periph_conf.h): ### + *             ### SPI configuration example (for periph_conf.h): ### * * static const uint32_t spi_clk_config[] = { * // Use cpu/kinetis_common/dist/calc_spi_scalers to @@ -265,7 +265,7 @@ * caused by mixing the clock domains of the bus clock used by the * CPU and the 32kHz reference clock for the LPTMR counter. * - * ### Timer configuration Example (for periph_conf.h) ### + *             ### Timer configuration example (for periph_conf.h) ### * * #define PIT_NUMOF (2U) * #define PIT_CONFIG { \ @@ -304,7 +304,7 @@ * using the BRFA field in the UART C4 register. * Currently, only the base TX/RX functionality is available. * - * ### UART configuration Example (for periph_conf.h) ### + *             ### UART configuration example (for periph_conf.h) ### * * static const uart_conf_t uart_config[] = { * {