ADuCM302x Device Drivers API Reference Manual  Release 3.1.2.0
Cycle Counting Framework

A framework for monitoring the adjusted and unadjusted cycle counts for ISRs and for APIs. More...

Modules

 Static Configuration
 

Data Structures

struct  ADI_CYCLECOUNT_LOG
 

Macros

#define ADI_CYCLECOUNT_SYSTICKS   (0xFFFFFFu)
 
#define ADI_CYCLECOUNT_INITIAL_STACK_INDEX   (-1)
 
#define ADI_CYCLECOUNT_ISR_EXT_3   1u
 
#define ADI_CYCLECOUNT_ISR_UART   2u
 
#define ADI_CYCLECOUNT_ISR_DMA_UART_TX   3u
 
#define ADI_CYCLECOUNT_ISR_DMA_UART_RX   4u
 
#define ADI_CYCLECOUNT_ISR_TMR_COMMON   5u
 
#define ADI_CYCLECOUNT_ISR_RTC   6u
 
#define ADI_CYCLECOUNT_ISR_SPI   7u
 
#define ADI_CYCLECOUNT_ISR_CRC   8u
 
#define ADI_CYCLECOUNT_ISR_SPORT   9u
 
#define ADI_CYCLECOUNT_ID_COUNT   10u
 
#define ADI_CYCLECOUNT_INITIALIZE()   adi_cyclecount_init()
 
#define ADI_CYCLECOUNT_STORE(id)   adi_cyclecount_store(id)
 
#define ADI_CYCLECOUNT_REPORT()   adi_cyclecount_report()
 
#define ADI_CYCLECOUNT_TOTAL_ID_SZ   (ADI_CYCLECOUNT_ID_COUNT + ADI_CYCLECOUNT_NUMBER_USER_DEFINED_APIS)
 

Typedefs

typedef uint64_t adi_cyclecount_t
 

Enumerations

enum  ADI_CYCLECOUNT_RESULT {
  ADI_CYCLECOUNT_SUCCESS,
  ADI_CYCLECOUNT_ADD_ENTITY_FAILURE,
  ADI_CYCLECOUNT_INVALID_ID,
  ADI_CYCLECOUNT_FAILURE
}
 

Functions

ADI_CYCLECOUNT_RESULT adi_cyclecount_start (void)
 API to be called to start a new cycle counting context. More...
 
ADI_CYCLECOUNT_RESULT adi_cyclecount_stop (void)
 Cycle Count Stop. More...
 
adi_cyclecount_t adi_cyclecount_get (void)
 Read the current number of cycle counts. More...
 
ADI_CYCLECOUNT_RESULT adi_cyclecount_store (uint32_t id)
 Store Cycle Count. More...
 
void adi_cyclecount_init (void)
 API to be called to initialize the cycle counting framework. More...
 
void adi_cyclecount_report (void)
 Generate a cycle count report. More...
 
ADI_CYCLECOUNT_RESULT adi_cyclecount_addEntity (const char *EntityName, uint32_t *pid)
 Add an ISR/API to the cycle counting list. More...
 
void SysTick_Handler (void)
 

Detailed Description

A framework for monitoring the adjusted and unadjusted cycle counts for ISRs and for APIs.

To enable cycle counting

1) Copy the file Include/config/adi_cycle_counting_config.h to your project directory.

2) Set the macro ADI_CYCLECOUNT_ENABLED to '1' in the project's copy of Include/config/adi_cycle_counting_config.h.

3) Enable ISRs and/or APIs for which cycle counts are to be obtained. The configuration macros that control this are also located in adi_cycle_counting_config.h.

Obtaining cycle counts

1) Call ADI_CYCLECOUNT_INITIALIZE() once at the start of the application

2) Call adi_cyclecount_start() at the start of each code block (ISR or API) for which cycles counts are to be obtained.

This will 'push' the cycle counting context stack.

3) Call ADI_CYCLECOUNT_STORE(id) at the end of each ISR/API. This will read and record the cycle count for the specified ID.

4) Call adi_cyclecount_stop() also at the end of each ISR/API. This will pop the cycle counting context stack.

5) Call ADI_CYCLECOUNT_REPORT() to print the cycle counts for enabled ISR/API


Adjusted versus Unadjusted cycle counts

Adjusted cycle counts are cycle counts from which any inner nested cycle counting has been subtracted.

Unadjusted cycle counts represent the total elapsed cycle count time including any nested cycle counts that are reported for nested ISRs or nested APIs.

For example, if function foo() is being cycle counted, and foo() is interrupted, the ISR cycle

counts are not included in the adjusted cycle count but they are included in the unadjusted cycle count.

Note
The application must include adi_cyclecount.h to use this framework.
This framework uses Systick for cycle counting. If an application uses Systick then the logic in the Systick ISR contained in this framework would need to be combined with the application's systick logic.
There is no need to call adi_cyclecount_start() and adi_cyclecount_stop() inside of an ISR as long as the ISR uses the ISR_PROLOG() and ISR_EPILOG() macros. The ISR_PROLOG and ISR_EPILOG macros definitions expand into code sequences that include the calls to adi_cyclecount_start() and adi_cyclecount_stop().
Non-ISR code will, however, have to add calls to adi_cyclecount_start() and adi_cyclecount_stop() manually at the beginning and end of the function.

Macro Definition Documentation

◆ ADI_CYCLECOUNT_SYSTICKS

#define ADI_CYCLECOUNT_SYSTICKS   (0xFFFFFFu)

The systick timer is a 24-bit count down timer The initial value can, therefore, be up to 0xFFFFFF The larger the value the fewer interrupts that will be taken and the less impact cycle counting will have on the system

Definition at line 45 of file adi_cyclecount.h.

Referenced by adi_cyclecount_get(), and adi_cyclecount_init().

◆ ADI_CYCLECOUNT_INITIAL_STACK_INDEX

#define ADI_CYCLECOUNT_INITIAL_STACK_INDEX   (-1)

Cycle counting nesting is supported via a cycle counting stack. The initial value of the stack index is one less than the starting stack index (0)

Definition at line 52 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ISR_EXT_3

#define ADI_CYCLECOUNT_ISR_EXT_3   1u

List of cycle counting IDs for the ISRs and APIs that can record cycle counts. Items enumerated here must be aligned with adi_cyclecounting_identifiers

Note that the ID numbering starts at 1. ID==0 is not used. Note that the application can extend this list via static configuration (see adi_cycle_counting_config.h) and via the adi_cyclecount_addEntity() API.Cycle count ID for EXT3 Interrupt Handler.

Definition at line 74 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ISR_UART

#define ADI_CYCLECOUNT_ISR_UART   2u

Cycle count ID for UART Interrupt Handler.

Definition at line 75 of file adi_cyclecount.h.

Referenced by adi_uart_FlushTxChannel().

◆ ADI_CYCLECOUNT_ISR_DMA_UART_TX

#define ADI_CYCLECOUNT_ISR_DMA_UART_TX   3u

Cycle count ID for UART DMA TX Interrupt Handler.

Definition at line 76 of file adi_cyclecount.h.

Referenced by adi_uart_FlushTxChannel().

◆ ADI_CYCLECOUNT_ISR_DMA_UART_RX

#define ADI_CYCLECOUNT_ISR_DMA_UART_RX   4u

Cycle count ID for UART DMA RX Interrupt Handler.

Definition at line 77 of file adi_cyclecount.h.

Referenced by adi_uart_FlushTxChannel().

◆ ADI_CYCLECOUNT_ISR_TMR_COMMON

#define ADI_CYCLECOUNT_ISR_TMR_COMMON   5u

Cycle count ID for Timer Interrupt Handler.

Definition at line 78 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ISR_RTC

#define ADI_CYCLECOUNT_ISR_RTC   6u

Cycle count ID for RTC Interrupt Handler.

Definition at line 79 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ISR_SPI

#define ADI_CYCLECOUNT_ISR_SPI   7u

Cycle count ID for SPI Interrupt Handler.

Definition at line 80 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ISR_CRC

#define ADI_CYCLECOUNT_ISR_CRC   8u

Cycle count ID for CRC Interrupt Handler.

Definition at line 81 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ISR_SPORT

#define ADI_CYCLECOUNT_ISR_SPORT   9u

Cycle count ID for SPORT Interrupt Handler.

Definition at line 82 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_ID_COUNT

#define ADI_CYCLECOUNT_ID_COUNT   10u

Number of cycle count ISRs and APIs. Must be one greater than the last ID.

Definition at line 83 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_INITIALIZE

#define ADI_CYCLECOUNT_INITIALIZE ( )    adi_cyclecount_init()

Cycle counting has to be enabled in the cycle counting configuration file If enabled then cycle counting related macros map to the cycle counting APIs. If not enabled, then the macros maps to a NOPInitialize the cycle counting data structures

Definition at line 113 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_STORE

#define ADI_CYCLECOUNT_STORE (   id)    adi_cyclecount_store(id)

Record the number of cycles for the specified ISR or API

Definition at line 114 of file adi_cyclecount.h.

Referenced by adi_uart_FlushTxChannel().

◆ ADI_CYCLECOUNT_REPORT

#define ADI_CYCLECOUNT_REPORT ( )    adi_cyclecount_report()

Generate a cycle counting report

Definition at line 115 of file adi_cyclecount.h.

◆ ADI_CYCLECOUNT_TOTAL_ID_SZ

#define ADI_CYCLECOUNT_TOTAL_ID_SZ   (ADI_CYCLECOUNT_ID_COUNT + ADI_CYCLECOUNT_NUMBER_USER_DEFINED_APIS)

Total cycle counting 'stack' requirements. It is the sum of the total number of predefined cycle count API/ISR IDs plus the number of user define API/ISR IDs.

Definition at line 85 of file adi_cyclecount.c.

Referenced by adi_cyclecount_init(), adi_cyclecount_report(), and adi_cyclecount_store().

Typedef Documentation

◆ adi_cyclecount_t

typedef uint64_t adi_cyclecount_t

64-bit integer to record cycle counts. Since UINT32_MAX = 4,294,967,296 cycles at 26 MHz this would allow us to record for 165 seconds before the system would wrap around. By moving to a 64-bit integer we can record for 11,248 years.

Definition at line 36 of file adi_cyclecount.h.

Enumeration Type Documentation

◆ ADI_CYCLECOUNT_RESULT

Cycle Count API function return values.

Enumerator
ADI_CYCLECOUNT_SUCCESS 

API completed successfully

ADI_CYCLECOUNT_ADD_ENTITY_FAILURE 

There is not enough space in the cycle counting entity array. Consider increasing the size via the ADI_CYCLECOUNT_NUMBER_USER_DEFINED_APIS static configuration macro

ADI_CYCLECOUNT_INVALID_ID 

The API/ISR ID is invalid.

ADI_CYCLECOUNT_FAILURE 

API did not complete successfully.

Definition at line 57 of file adi_cyclecount.h.

Function Documentation

◆ adi_cyclecount_start()

ADI_CYCLECOUNT_RESULT adi_cyclecount_start ( void  )

API to be called to start a new cycle counting context.

Every entity (ISR or API) for which cycle counts are needed must call this routine at the beginning of the code sequence for which a cycle count is needed.

Returns
ADI_CYCLECOUNT_RESULT
  1. ADI_CYCLECOUNT_SUCCESS Function successfully pushed the cycle context
  2. ADI_CYCLECOUNT_FAILURE Error. Cycle Counting stack overflow.
Note
If adi_cyclecount_start() returns false then the cycle count stack size should
be increased. The macro ADI_CYCLECOUNT_INITIAL_STACK_INDEX controls the stack
size.

Definition at line 195 of file adi_cyclecount.c.

◆ adi_cyclecount_stop()

ADI_CYCLECOUNT_RESULT adi_cyclecount_stop ( void  )

Cycle Count Stop.

This function ends an ISR or API context. It should be called at the end of the code sequence for which cycle counting is enabled.

Returns
Success
  1. ADI_CYCLECOUNT_SUCCESS No errors
  2. ADI_CYCLECOUNT_FAILURE There is a adi_cyclecount_start/adi_cyclecount_stop mismatch

Definition at line 224 of file adi_cyclecount.c.

◆ adi_cyclecount_get()

adi_cyclecount_t adi_cyclecount_get ( void  )

Read the current number of cycle counts.

Return the Cycle Counts which are recorded using Systick

Returns
adi_cyclecount_t

Definition at line 166 of file adi_cyclecount.c.

◆ adi_cyclecount_store()

ADI_CYCLECOUNT_RESULT adi_cyclecount_store ( uint32_t  id)

Store Cycle Count.

adi_cyclecount_store will calculate the number of cycles since the last call to adi_cyclecount_start(). The cycle count is then recorded against the API/ISR identified by 'id'

Parameters
[in]idSpecifies the API/ISR that this data belongs to
Returns
ADI_CYCLECOUNT_RESULT
  1. ADI_CYCLECOUNT_SUCCESS Function successfully stored the cycle count
  2. ADI_CYCLECOUNT_ADD_ENTITY_FAILURE Not enough room in the cycle counting enity stack.

Definition at line 330 of file adi_cyclecount.c.

◆ adi_cyclecount_init()

void adi_cyclecount_init ( void  )

API to be called to initialize the cycle counting framework.

The cycle counting framework uses systick. Sysyick is, therefore, initialized. If an application uses Systick then the logic in the Systick ISR contained in this framework would need to be combined with the application's systick logic.

Definition at line 264 of file adi_cyclecount.c.

◆ adi_cyclecount_report()

void adi_cyclecount_report ( void  )

Generate a cycle count report.

The cycle count data will be printed. Output will be sent to either a console I/O window or to the UART, depending on how DEBUG_MESSAGE is configured.

Note
It is not valid to call any other cycle counting API while this API is functioning

Definition at line 394 of file adi_cyclecount.c.

◆ adi_cyclecount_addEntity()

ADI_CYCLECOUNT_RESULT adi_cyclecount_addEntity ( const char *  EntityName,
uint32_t *  pid 
)

Add an ISR/API to the cycle counting list.

Add the application API/ISR entity to the list of API/ISRs for which cycle counts can be obtained. The function will first check to make sure there is enough space in the list. If there is the list ID will be written. If there is not enough space then an error will be returned (and the application would need to increase the size of the list by modifying the macro ADI_CYCLECOUNT_NUMBER_USER_DEFINED_APIS.

Parameters
[in]EntityNameName of the API/ISR for which cycle counts are to be obtained.
[out]pidPointer to the ID for this entity.
Returns
ADI_CYCLECOUNT_RESULT
  1. ADI_CYCLECOUNT_SUCCESS Function successfully pushed the cycle context
  2. ADI_CYCLECOUNT_ADD_ENTITY_FAILURE Not enough room in the cycle counting enity stack.

Definition at line 301 of file adi_cyclecount.c.

◆ SysTick_Handler()

void SysTick_Handler ( void  )

Systick handler. Overrides the weak definition. To avoid replacing the weak definition or other definitions from other modules when cycle counting is disabled, this definition is under the ADI_CYCLECOUNT_ENABLED macro

Definition at line 123 of file adi_cyclecount.c.

Variable Documentation

◆ starting_cycle_count

adi_cyclecount_t starting_cycle_count

The adjusted cycle count

Definition at line 151 of file adi_cyclecount.c.

◆ adjusted_cycle_count

adi_cyclecount_t adjusted_cycle_count

The unadjusted cycle count

Definition at line 152 of file adi_cyclecount.c.