From 2b54119b78cc298da72aea76373d086b271a1b52 Mon Sep 17 00:00:00 2001 From: Karl Palsson Date: Fri, 18 Oct 2019 22:38:16 +0000 Subject: [PATCH] cm3: scs: drop all duplicate information Keeps the best version of the documentation. Fixes: https://github.com/libopencm3/libopencm3/pull/269 --- include/libopencm3/cm3/dwt.h | 55 ++++++++-- include/libopencm3/cm3/scb.h | 5 + include/libopencm3/cm3/scs.h | 179 +------------------------------ include/libopencm3/cm3/systick.h | 122 ++++++++++++++++----- 4 files changed, 150 insertions(+), 211 deletions(-) diff --git a/include/libopencm3/cm3/dwt.h b/include/libopencm3/cm3/dwt.h index 2718afa7..4b7d24ce 100644 --- a/include/libopencm3/cm3/dwt.h +++ b/include/libopencm3/cm3/dwt.h @@ -20,25 +20,63 @@ #ifndef LIBOPENCM3_CM3_DWT_H #define LIBOPENCM3_CM3_DWT_H -/** - * @defgroup cm_fpb Cortex-M Flash Patch and Breakpoint (FPB) unit - * @ingroup CM3_defines - * @{ - */ - #include #include +/** + * @defgroup cm_dwt Cortex-M Data Watch and Trace unit. + * @ingroup CM3_defines + * System Control Space (SCS) => Data Watchpoint and Trace (DWT). + * See "ARMv7-M Architecture Reference Manual" + * and "ARMv6-M Architecture Reference Manual" + * The DWT is an optional debug unit that provides watchpoints, data tracing, + * and system profiling for the processor. + * @{ + */ + /*****************************************************************************/ /* Register definitions */ /*****************************************************************************/ +/** DWT Control register + * Purpose Provides configuration and status information for the DWT block, and + * used to control features of the block + * Usage constraints: There are no usage constraints. + * Configurations Always implemented. + */ #define DWT_CTRL MMIO32(DWT_BASE + 0x00) /* Those defined only on ARMv7 and above */ #if defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7EM__) +/** + * DWT_CYCCNT register + * Cycle Count Register (Shows or sets the value of the processor cycle + * counter, CYCCNT) + * When enabled, CYCCNT increments on each processor clock cycle. On overflow, + * CYCCNT wraps to zero. + * + * Purpose Shows or sets the value of the processor cycle counter, CYCCNT. + * Usage constraints: The DWT unit suspends CYCCNT counting when the processor + * is in Debug state. + * Configurations Implemented: only when DWT_CTRL.NOCYCCNT is RAZ, see Control + * register, DWT_CTRL. + * When DWT_CTRL.NOCYCCNT is RAO no cycle counter is implemented and this + * register is UNK/SBZP. +*/ #define DWT_CYCCNT MMIO32(DWT_BASE + 0x04) + +/** DWT_CPICNT register + * Purpose Counts additional cycles required to execute multi-cycle + * instructions and instruction fetch stalls. + * Usage constraints: The counter initializes to 0 when software enables its + * counter overflow event by + * setting the DWT_CTRL.CPIEVTENA bit to 1. + * Configurations Implemented: only when DWT_CTRL.NOPRFCNT is RAZ, see Control + * register, DWT_CTRL. + * If DWT_CTRL.NOPRFCNT is RAO, indicating that the implementation does not + * include the profiling counters, this register is UNK/SBZP. + */ #define DWT_CPICNT MMIO32(DWT_BASE + 0x08) #define DWT_EXCCNT MMIO32(DWT_BASE + 0x0C) #define DWT_SLEEPCNT MMIO32(DWT_BASE + 0x10) @@ -99,6 +137,11 @@ #define DWT_CTRL_POSTPRESET_SHIFT 1 #define DWT_CTRL_POSTPRESET (0x0F << DWT_CTRL_POSTPRESET_SHIFT) +/** + * CYCCNTENA Enables the Cycle counter. + * 0 = Disabled, 1 = Enabled + * This bit is UNK/SBZP if the NOCYCCNT bit is RAO. + */ #define DWT_CTRL_CYCCNTENA (1 << 0) #endif /* defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7EM__) */ diff --git a/include/libopencm3/cm3/scb.h b/include/libopencm3/cm3/scb.h index 11075527..4b3e4f77 100644 --- a/include/libopencm3/cm3/scb.h +++ b/include/libopencm3/cm3/scb.h @@ -24,6 +24,11 @@ /** * @defgroup cm_scb Cortex-M System Control Block * @ingroup CM3_defines + * + * The System Control Block is a section of the System Control Space. + * Other members of the SCS are, for instance, DWT, ITM, SYSTICKK. + * The exact details of the SCB are defined in the "Architecture Reference + * Manual" for either ARMv7-M or ARMV6-m. * @{ */ #include diff --git a/include/libopencm3/cm3/scs.h b/include/libopencm3/cm3/scs.h index 791d13f2..0af4424e 100644 --- a/include/libopencm3/cm3/scs.h +++ b/include/libopencm3/cm3/scs.h @@ -21,13 +21,6 @@ #ifndef LIBOPENCM3_CM3_SCS_H #define LIBOPENCM3_CM3_SCS_H -/* - * All the definition hereafter are generic for CortexMx ARMv7-M - * See ARM document "ARMv7-M Architecture Reference Manual" for more details. - * See also ARM document "ARM Compiler toolchain Developing Software for ARM - * Processors" for details on System Timer/SysTick. - */ - /** * @defgroup cm_scs Cortex-M System Control Space * @ingroup CM3_defines @@ -42,6 +35,9 @@ * - a Nested Vectored Interrupt Controller (NVIC) * - a Protected Memory System Architecture (PMSA) * - system debug. + * + * Most portions of the SCS are covered by their own header files, eg + * systick.h, dwt.h, scb.h, itm.h, fpb.h * @{ */ @@ -149,180 +145,11 @@ /* Bits 3:1 - Reserved */ #define SCS_DEMCR_VC_CORERESET (1 << 0) -/* - * System Control Space (SCS) => System timer register support in the SCS. - * To configure SysTick, load the interval required between SysTick events to - * the SysTick Reload Value register. The timer interrupt, or COUNTFLAG bit in - * the SysTick Control and Status register, is activated on the transition from - * 1 to 0, therefore it activates every n+1 clock ticks. If you require a - * period of 100, write 99 to the SysTick Reload Value register. The SysTick - * Reload Value register supports values between 0x1 and 0x00FFFFFF. - * - * If you want to use SysTick to generate an event at a timed interval, for - * example 1ms, you can use the SysTick Calibration Value Register to scale - * your value for the Reload register. The SysTick Calibration Value Register - * is a read-only register that contains the number of pulses for a period of - * 10ms, in the TENMS field, bits[23:0]. - * - * This register also has a SKEW bit. Bit[30] == 1 indicates that the - * calibration for 10ms in the TENMS section is not exactly 10ms due to clock - * frequency. Bit[31] == 1 indicates that the reference clock is not provided. - */ -/* - * SysTick Control and Status Register (CSR). - * Purpose Controls the system timer and provides status data. - * Usage constraints: There are no usage constraints. - * Configurations Always implemented. -*/ -#define SCS_SYST_CSR MMIO32(SCS_BASE + 0x10) - -/* SysTick Reload Value Register (CVR). - * Purpose Reads or clears the current counter value. - * Usage constraints: - * - Any write to the register clears the register to zero. - * - The counter does not provide read-modify-write protection. - * - Unsupported bits are read as zero - * Configurations Always implemented. - */ -#define CM_SCS_SYST_RVR MMIO32(SCS_BASE + 0x14) - -/* SysTick Current Value Register (RVR). - * Purpose Holds the reload value of the SYST_CVR. - * Usage constraints There are no usage constraints. - * Configurations Always implemented. - */ -#define CM_SCS_SYST_CVR MMIO32(SCS_BASE + 0x18) - -/* - * SysTick Calibration value Register(Read Only) (CALIB) - * Purpose Reads the calibration value and parameters for SysTick. - * Usage constraints: There are no usage constraints. - * Configurations Always implemented. - */ -#define CM_SCS_SYST_CALIB MMIO32(SCS_BASE + 0x1C) - -/* --- SCS_SYST_CSR values ----------------------------------------------- */ -/* Counter is operating. */ -#define SCS_SYST_CSR_ENABLE (BIT0) -/* Count to 0 changes the SysTick exception status to pending. */ -#define SCS_SYST_CSR_TICKINT (BIT1) -/* SysTick uses the processor clock. */ -#define SCS_SYST_CSR_CLKSOURCE (BIT2) -/* - * Indicates whether the counter has counted to 0 since the last read of this - * register: - * 0 = Timer has not counted to 0 - * 1 = Timer has counted to 0. - */ -#define SCS_SYST_CSR_COUNTFLAG (BIT16) - -/* --- CM_SCS_SYST_RVR values ---------------------------------------------- */ -/* Bit 0 to 23 => RELOAD The value to load into the SYST_CVR when the counter - * reaches 0. - */ -/* Bit 24 to 31 are Reserved */ - -/* --- CM_SCS_SYST_CVR values ---------------------------------------------- */ -/* Bit0 to 31 => Reads or clears the current counter value. */ - -/* --- CM_SCS_SYST_CALIB values -------------------------------------------- */ -/* - * Bit0 to 23 => TENMS Optionally, holds a reload value to be used for 10ms - * (100Hz) timing, subject to system clock skew errors. If this field is zero, - * the calibration value is not known. - */ -#define SCS_SYST_SYST_CALIB_TENMS_MASK (BIT24-1) - -/* - * Bit30 => SKEW Indicates whether the 10ms calibration value is exact: - * 0 = 10ms calibration value is exact. - * 1 = 10ms calibration value is inexact, because of the clock frequency - */ -#define SCS_SYST_SYST_CALIB_VALUE_INEXACT (BIT30) -/* - * Bit31 => NOREF Indicates whether the IMPLEMENTATION DEFINED reference clock - * is implemented: - * 0 = The reference clock is implemented. - * 1 = The reference clock is not implemented. - * When this bit is 1, the CLKSOURCE bit of the SYST_CSR register is forced to - * 1 and cannot be cleared to 0. - */ -#define SCS_SYST_SYST_CALIB_REF_NOT_IMPLEMENTED (BIT31) - -/* - * System Control Space (SCS) => Data Watchpoint and Trace (DWT). - * See "ARMv7-M Architecture Reference Manual" - * (https://github.com/libopencm3/libopencm3-archive/blob/master/arm/ - * ARMv7-M_ARM.pdf) - * The DWT is an optional debug unit that provides watchpoints, data tracing, - * and system profiling for the processor. - */ -/* - * DWT Control register - * Purpose Provides configuration and status information for the DWT block, and - * used to control features of the block - * Usage constraints: There are no usage constraints. - * Configurations Always implemented. - */ -#define SCS_DWT_CTRL MMIO32(DWT_BASE + 0x00) -/* - * DWT_CYCCNT register - * Cycle Count Register (Shows or sets the value of the processor cycle - * counter, CYCCNT) - * When enabled, CYCCNT increments on each processor clock cycle. On overflow, - * CYCCNT wraps to zero. - * - * Purpose Shows or sets the value of the processor cycle counter, CYCCNT. - * Usage constraints: The DWT unit suspends CYCCNT counting when the processor - * is in Debug state. - * Configurations Implemented: only when DWT_CTRL.NOCYCCNT is RAZ, see Control - * register, DWT_CTRL. - * When DWT_CTRL.NOCYCCNT is RAO no cycle counter is implemented and this - * register is UNK/SBZP. -*/ -#define SCS_DWT_CYCCNT MMIO32(DWT_BASE + 0x04) - -/* DWT_CPICNT register - * Purpose Counts additional cycles required to execute multi-cycle - * instructions and instruction fetch stalls. - * Usage constraints: The counter initializes to 0 when software enables its - * counter overflow event by - * setting the DWT_CTRL.CPIEVTENA bit to 1. - * Configurations Implemented: only when DWT_CTRL.NOPRFCNT is RAZ, see Control - * register, DWT_CTRL. - * If DWT_CTRL.NOPRFCNT is RAO, indicating that the implementation does not - * include the profiling counters, this register is UNK/SBZP. - */ -#define SCS_DWT_CPICNT MMIO32(DWT_BASE + 0x08) - -/* DWT_EXCCNT register */ -#define SCS_DWT_EXCCNT MMIO32(DWT_BASE + 0x0C) - -/* DWT_EXCCNT register */ -#define SCS_DWT_SLEEPCNT MMIO32(DWT_BASE + 0x10) - -/* DWT_EXCCNT register */ -#define SCS_DWT_LSUCNT MMIO32(DWT_BASE + 0x14) - -/* DWT_EXCCNT register */ -#define SCS_DWT_FOLDCNT MMIO32(DWT_BASE + 0x18) - -/* DWT_PCSR register */ -#define SCS_DWT_PCSR MMIO32(DWT_BASE + 0x18) - /* CoreSight Lock Status Register for this peripheral */ #define SCS_DWT_LSR MMIO32(SCS_DWT_BASE + 0xFB4) /* CoreSight Lock Access Register for this peripheral */ #define SCS_DWT_LAR MMIO32(SCS_DWT_BASE + 0xFB0) -/* --- SCS_DWT_CTRL values ------------------------------------------------- */ -/* - * Enables CYCCNT: - * 0 = Disabled, 1 = Enabled - * This bit is UNK/SBZP if the NOCYCCNT bit is RAO. - */ -#define SCS_DWT_CTRL_CYCCNTENA (BIT0) - /**@}*/ #endif diff --git a/include/libopencm3/cm3/systick.h b/include/libopencm3/cm3/systick.h index 0f620bf0..15639469 100644 --- a/include/libopencm3/cm3/systick.h +++ b/include/libopencm3/cm3/systick.h @@ -29,15 +29,27 @@ * * @date 19 August 2012 * + * System Control Space (SCS) => System timer register support in the SCS. + * To configure SysTick, load the interval required between SysTick events to + * the SysTick Reload Value register. The timer interrupt, or COUNTFLAG bit in + * the SysTick Control and Status register, is activated on the transition from + * 1 to 0, therefore it activates every n+1 clock ticks. If you require a + * period of 100, write 99 to the SysTick Reload Value register. The SysTick + * Reload Value register supports values between 0x1 and 0x00FFFFFF. + * + * If you want to use SysTick to generate an event at a timed interval, for + * example 1ms, you can use the SysTick Calibration Value Register to scale + * your value for the Reload register. The SysTick Calibration Value Register + * is a read-only register that contains the number of pulses for a period of + * 10ms, in the TENMS field, bits[23:0]. + * + * This register also has a SKEW bit. Bit[30] == 1 indicates that the + * calibration for 10ms in the TENMS section is not exactly 10ms due to clock + * frequency. Bit[31] == 1 indicates that the reference clock is not provided. + * * LGPL License Terms @ref lgpl_license */ -/** - * @note this file has been not following the register naming scheme, the - * correct names defined, and the old ones stay there for compatibility with - * old software (will be deprecated in the future) - */ - /**@{*/ #ifndef LIBOPENCM3_SYSTICK_H @@ -46,28 +58,54 @@ #include #include -/* --- SYSTICK registers --------------------------------------------------- */ - -/* Control and status register (STK_CTRL) */ +/** SysTick Control and Status Register (CSR). + * Controls the system timer and provides status data. + * Usage constraints: There are no usage constraints. + * Configurations Always implemented. + */ #define STK_CSR MMIO32(SYS_TICK_BASE + 0x00) -/* reload value register (STK_LOAD) */ +/** SysTick Reload Value Register (RVR). + * Reads or clears the value that will be loaded to the counter. + * Usage constraints: + * - Any write to the register clears the register to zero. + * - The counter does not provide read-modify-write protection. + * - Unsupported bits are read as zero + * Configurations Always implemented. + */ #define STK_RVR MMIO32(SYS_TICK_BASE + 0x04) -/* current value register (STK_VAL) */ +/** SysTick Current Value Register (CVR). + * Holds the current value of the counter. + * Usage constraints: There are no usage constraints. + * Configurations Always implemented. + */ #define STK_CVR MMIO32(SYS_TICK_BASE + 0x08) -/* calibration value register (STK_CALIB) */ +/** SysTick Calibration Value Register(Read Only) (CALIB) + * Reads the calibration value and parameters for SysTick. + * Usage constraints: There are no usage constraints. + * Configurations Always implemented. + */ #define STK_CALIB MMIO32(SYS_TICK_BASE + 0x0C) -/* --- STK_CSR values ------------------------------------------------------ */ -/* Bits [31:17] Reserved, must be kept cleared. */ -/* COUNTFLAG: */ +/** @defgroup STK_CSR_VALUES STK_CSR Values + * @{ + */ +/** COUNTFLAG + * Indicates whether the counter has counted to 0 since the last read of this + * register: + * 0 = Timer has not counted to 0 + * 1 = Timer has counted to 0. + */ #define STK_CSR_COUNTFLAG (1 << 16) -/* Bits [15:3] Reserved, must be kept cleared. */ -/* CLKSOURCE: Clock source selection */ #define STK_CSR_CLKSOURCE_LSB 2 +/** CLKSOURCE: Clock source selection + * for 0, SysTick uses the IMPLEMENTATION DEFINED external reference clock. + * for 1, SysTick uses the processor clock. + * If no external clock is provided, this bit reads as 1 and ignores writes. + */ #define STK_CSR_CLKSOURCE (1 << STK_CSR_CLKSOURCE_LSB) /** @defgroup systick_clksource Clock source selection @@ -83,31 +121,57 @@ #endif /**@}*/ -/* TICKINT: SysTick exception request enable */ +/** TICKINT: SysTick exception request enable */ #define STK_CSR_TICKINT (1 << 1) -/* ENABLE: Counter enable */ +/** ENABLE: Counter enable */ #define STK_CSR_ENABLE (1 << 0) +/**@}*/ -/* --- STK_RVR values ------------------------------------------------------ */ -/* Bits [31:24] Reserved, must be kept cleared. */ -/* RELOAD[23:0]: RELOAD value */ +/** @defgroup STK_RVR_VALUES STK_RVR Values + * @{ + */ +/** RELOAD[23:0]: RELOAD value */ #define STK_RVR_RELOAD 0x00FFFFFF +/**@}*/ -/* --- STK_CVR values ------------------------------------------------------ */ -/* Bits [31:24] Reserved, must be kept cleared. */ -/* CURRENT[23:0]: Current counter value */ + +/** @defgroup STK_RVR_VALUES STK_RVR Values + * @{ + */ +/** CURRENT[23:0]: Current counter value */ #define STK_CVR_CURRENT 0x00FFFFFF +/**@}*/ -/* --- STK_CALIB values ---------------------------------------------------- */ -/* NOREF: NOREF flag */ +/** @defgroup STK_CALIB_VALUES STK_CALIB Values + * @{ + */ +/** NOREF: NOREF flag + * Bit31 => NOREF Indicates whether the IMPLEMENTATION DEFINED reference clock + * is implemented: + * 0 = The reference clock is implemented. + * 1 = The reference clock is not implemented. + * When this bit is 1, the CLKSOURCE bit of the SYST_CSR register is forced to + * 1 and cannot be cleared to 0. + */ #define STK_CALIB_NOREF (1 << 31) -/* SKEW: SKEW flag */ + +/** SKEW: SKEW flag + * Bit30 => SKEW Indicates whether the 10ms calibration value is exact: + * 0 = 10ms calibration value is exact. + * 1 = 10ms calibration value is inexact, because of the clock frequency + */ #define STK_CALIB_SKEW (1 << 30) + /* Bits [29:24] Reserved, must be kept cleared. */ -/* TENMS[23:0]: Calibration value */ +/** TENMS Calibration value for 10ms. + * Bit0 to 23 => TENMS Optionally, holds a reload value to be used for 10ms + * (100Hz) timing, subject to system clock skew errors. If this field is zero, + * the calibration value is not known. + */ #define STK_CALIB_TENMS 0x00FFFFFF +/**@}*/ /* --- Function Prototypes ------------------------------------------------- */