HAL CORDIC How to Use ¶

group CORDIC_How_To_Use

How to use the CORDIC HAL module driver ¶

Declare a hal_cordic_handle_t handle structure and initialize the CORDIC driver with a CORDIC instance using the HAL_CORDIC_Init() . The CORDIC clock is enabled inside the HAL_CORDIC_Init() if USE_HAL_CORDIC_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.
Configure the low level hardware (CLOCK, NVIC, DMA…):
- Enable the CORDIC clock USE_HAL_CORDIC_CLK_ENABLE_MODEL is not defined or defined to “HAL_CLK_ENABLE_NO”.
- NVIC configuration if you need to use interrupt process
  - Configure the CORDIC interrupt priority using HAL_NVIC_SetPriority().
  - Enable the CORDIC IRQ handler using HAL_NVIC_EnableIRQ().
  - In CORDIC IRQ handler, call HAL_CORDIC_IRQHandler() .
- DMA configuration if you need to use DMA process
  - Enable the GPDMA1 interface clock using HAL_RCC_GPDMA1_EnableClock() ;
  - Configure and enable two DMA channels one for managing data transfer from memory to peripheral (input channel) and another channel for managing data transfer from peripheral to memory (output channel).
  - Associate the initialized DMA handle to the CORDIC DMA handle.
  - Configure the priority and enable the NVIC for the transfer complete interrupt on the two DMA channels by calling the HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ() functions.
Configure the minimal configuration needed for the CORDIC driver by calling HAL_CORDIC_SetConfig() .
- This function configures:
  - Processing functions: Cosine, Sine, Phase, Modulus, Arctangent, Hyperbolic cosine, Hyperbolic sine, Hyperbolic arctangent, Natural log, Square root.
  - Scaling factor: 1 to 2exp(-7).
  - Width of input data: 32 bits input data size (Q1.31 format) or 16 bits input data size (Q1.15 format).
  - Width of output data: 32 bits output data size (Q1.31 format) or 16 bits output data size (Q1.15 format).
  - Number of 32-bit write expected for one calculation: One 32-bits write or Two 32-bit write.
  - Number of 32-bit read expected after one calculation: One 32-bits read or Two 32-bit read.
  - Precision: 1 to 15 cycles for calculation (the more cycles, the better precision).
Operation modes:
- Polling mode operations:
  - Processing API is a blocking function i.e. it processes the data and waits until the RRDY flag is raised in the CORDIC_CSR register indicating that results are available in CORDIC_RDATA. That process is performed in the API by calling the HAL_CORDIC_Calculate() function.
  - HAL_CORDIC_Write() provides a way to give to the CORDIC a data input buffer. That function must be associated with a DMA out mode process or an output buffer in IT mode.
  - HAL_CORDIC_Read() permits to provides an output buffer in polling mode. That function must be associated with a DMA In mode process.
  - HAL_CORDIC_Write() and HAL_CORDIC_Read() cannot be associated together to provide a full polling mode for input and output polling mode.
- Zero-overhead mode operations:
  - Processing API is a blocking function i.e. it writes data to process and read immediately the CORDIC_RDATA register to get the result. Any attempt to read the CORDIC_RDATA register inserts bus wait state until the calculation is completed. That process is performed in the API by calling HAL_CORDIC_CalculateZeroOverhead() .
- Interrupt mode operations:
  - Processing API is not blocking function, an interrupt is generated whenever the RRDY flag is set. The result of calculation is read under interrupt service routine. However it is slower than directly reading the result or polling the flag due to interrupt handling delays. That process is performed by calling HAL_CORDIC_Calculate_IT() .
  - When all the data are written, HAL_CORDIC_WriteDataCpltCallback() is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
    - When all the calculus are done, HAL_CORDIC_CalculateCpltCallback() is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
  - In case of flag error, the HAL_CORDIC_ErrorCallback() callback is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
- DMA mode operations:
  - Processing API is not a blocking function and allows to offload the CPU. If both channels are enabled, the CORDIC can autonomously performs repeated calculations on a buffer of data without any CPU access. That process is performed by calling HAL_CORDIC_Calculate_DMA() function, that function operates with a DMA channel In and a DMA channel out only.
  - The DMA current transfer can be cancelled using the HAL_CORDIC_Abort() or HAL_CORDIC_Abort_IT() functions.
  - When half of all the data are written, HAL_CORDIC_WriteHalfCpltCallback() is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
  - When half of all the results reading is performed, HAL_CORDIC_ReadHalfCpltCallback() is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
  - When all the calculus are done, HAL_CORDIC_CalculateCpltCallback() is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
  - In case of flag error, HAL_CORDIC_ErrorCallback() function is executed. This callback is a weak function and can be overridden by the user or by registering a callback function.
Write and Read operations directly driven by another peripheral (Timer, ADC, DAC, etc) are available through:
- Use of HAL_CORDIC_GetWriteAddress() and HAL_CORDIC_GetReadAddress() functions to get the addresses of the CORDIC_WDATA and CORDIC_RDATA registers according to the user application needs.
- Whatever the process used with the CORDIC driver, the peripheral calls two dedicated functions:
  - HAL_CORDIC_LockWriteAccessForExternPeriph() to indicate that the driver is used and busy (ACTIVE state).
  - HAL_CORDIC_UnlockWriteAccessForExternPeriph() to indicate that the driver is now available (IDLE state).
Call HAL_CORDIC_DeInit() to de-initialize the CORDIC peripheral.
Callback definition in Interrupt or DMA mode:

When the preprocessor directive USE_HAL_CORDIC_REGISTER_CALLBACKS is set to 1, the user can configure dynamically the driver callbacks, via its own method:

Callback name	Default value	Callback registration function
ErrorCallback	HAL_CORDIC_ErrorCallback	HAL_CORDIC_RegisterErrorCallback()
CalculationCpltCallback	HAL_CORDIC_CalculateCpltCallback	HAL_CORDIC_RegisterCalculateCpltCallback()
WriteDataCpltCallback	HAL_CORDIC_WriteDataCpltCallback	HAL_CORDIC_RegisterWriteDataCpltCallback()
AbortCpltCallback	HAL_CORDIC_AbortCpltCallback	HAL_CORDIC_RegisterAbortCpltCallback()
WriteHalfCpltCallback	HAL_CORDIC_WriteHalfCpltCallback	HAL_CORDIC_RegisterWriteHalfCpltCallback()
ReadHalfCpltCallback	HAL_CORDIC_ReadHalfCpltCallback	HAL_CORDIC_RegisterReadHalfCpltCallback()

To unregister a callback, it must be done by registering the default callback.

By default, after the HAL_CORDIC_Init() and when the state is HAL_CORDIC_STATE_INIT , all callbacks are set to the corresponding weak functions.

Callbacks can be registered in HAL_CORDIC_STATE_INIT or HAL_CORDIC_STATE_IDLE states only.

When the preprocessing directive USE_HAL_CORDIC_REGISTER_CALLBACKS is set to 0 or undefined, the callback registration feature is not available and all callbacks are set to the corresponding weak functions.