HAL HSP How to Use

group HSP_How_To_Use

How to use the HSP HAL module driver

Usage

1. Declare a hal_hsp_handle_t handle and initialize the HSP driver with an HSP instance by calling HAL_HSP_Init(). The HSP clock is enabled inside HAL_HSP_Init() if USE_HAL_HSP_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.

2. Configure the low-level hardware (CLOCK, NVIC…):

   • Enable the HSP clock if USE_HAL_HSP_CLK_ENABLE_MODEL = HAL_CLK_ENABLE_NO.

   • HSPx pins configuration:

     • Enable the clock for the HSPx GPIOs

     • Configure HSPx pins as alternate function open - drain

   • NVIC configuration if you need to use HSP interrupt process:

     • Either use only the global IRQ line (hsp_it) as follows:

       • Configure the HSP interrupt priority by calling HAL_CORTEX_NVIC_SetPriority().

       • Enable the HSP IRQ handler by calling HAL_CORTEX_NVIC_EnableIRQ().

       • In HSP IRQ handler, call HAL_HSP_IRQHandler()

     • Or use the 3 HSP IRQ lines (hsp_err_it, hsp_evt_it and hsp_fwevt_it) as follows:

       • Configure the 3 HSP interrupts priority by calling HAL_CORTEX_NVIC_SetPriority().

       • Enable the 3 HSP IRQ handlers by calling HAL_CORTEX_NVIC_EnableIRQ().

       • In HSP Error IRQ handler, call HAL_HSP_ERR_IRQHandler(),

       • In HSP Event IRQ handler, call HAL_HSP_EVT_IRQHandler(),

       • In HSP FWEvent IRQ handler, call HAL_HSP_FWEVT_IRQHandler(),

3. Load the Firmware Code part & Data part with HAL_HSP_LoadFirmware(). The Firmware is based on the Firmware Code Part version embedded in the CROM. The Firmwares are delivered through the Middleware HSP Engine.

4. Load Plugin with HAL_HSP_LoadPlugin() (Optional) This step requires one call per Plugin. The Plugins are delivered through the Middleware HSP Engine.

5. Boot the HSP with HAL_HSP_Boot() On success, the handle state is set to HAL_HSP_STATE_RUNNING. The HSP is ready to use.

6. HSP Processing in Accelerator Mode

   • To process a processing function (Accelerator mode), call in order, the following APIs:

     • HAL_HSP_DCMD_WriteCommand(): to send the Processing Function Command ID

     • HAL_HSP_WriteParameter(): to send a parameter value (one call per parameter)

     • HAL_HSP_DCMD_WriteDataPointer(): to send a pointer of buffer (one call per pointer)

     Refer to the HSP Processing Functions User Manual(UM3360) to find all processing functions available for the Accelerator mode.

     The Middleware HSP Engine embeds API for each Processing Function available in Accelerator Mode.

7. HSP Processing in Sequencer Mode

   • Record a processing list

     1. Start the recording:

        • Run the Task HAL_HSP_TASK_SUPERVISOR with HAL_HSP_PRC_SWRequestLowestPriorityTask().

        • Write the Processing List ID with HAL_HSP_WriteParameter() using parameters (HAL_HSP_PARAM_0, pl_id).

        • Send the PROCFG_START command with HAL_HSP_MSGBOX_SendMessage().

     2. Record a processing function:

        • Prepare all parameters with HAL_HSP_WriteParameter() according to the Processing Function User Manual.

          Any buffer address set as parameter must be allocated in the “.HSP_DATA_BRAM” memory region defined in the linker file.

        • Send the Processing Function ID with HAL_HSP_MSGBOX_SendMessage().

     3. Iterate the previous step to record several processing functions.

     4. Stop the recording:

        • Send the PROCFG_END command with HAL_HSP_MSGBOX_SendMessage().

     The MSGBOX command identifiers are defined in the HSP Firmware definitions file provided by the MW HSP Engine.

   • Configure a trigger to run a processing list

     A trigger could be an HSP STREAM Buffer, a peripheral event(such as DMA Transfer Complete)… It must be attached to an HSP Event within the range [1..22].

     To attach a Processing List to an HSP Event, the Processing List ID must match the HSP Event ID.

     • To configure an HSP event with STREAM Buffer as source:

       • Configure the STREAM Buffer [y] with HAL_HSP_STREAM_SetMultiConfig().

       • If needed, enable the Integer-to-Float conversion with HAL_HSP_STREAM_EnableIntToFloat(). This feature applies to all STREAM Buffers.

       • Configure the event [x] by calling HAL_HSP_PRC_SetMultiTaskConfig() with HAL_HSP_EVENT_[x]_STREAM[y] as trigger source.

     • To configure an HSP event with a Trigger Input as source:

       • Configure the Trigger Input [y] with HAL_HSP_TRGIN_SetConfigTriggers().

       • Configure the event [x] by calling HAL_HSP_PRC_SetMultiTaskConfig() with HAL_HSP_EVENT_[x]_TRGIN[y].

     • To configure an HSP event triggered by the CPU (CSEG interface): Configure event [x] by calling HAL_HSP_PRC_SetMultiTaskConfig() with HAL_HSP_EVENT_[x]_CSEG.

     • To configure an HSP event triggered by the Signal Processor Engine itself (HSEG interface): Configure event [x] by calling HAL_HSP_PRC_SetMultiTaskConfig() with HAL_HSP_EVENT_[x]_HSEG.

     In polling mode, the HAL provides these APIs:

     • HAL_HSP_TRGIN_EnableTriggers() to enable the Trigger Input

     • HAL_HSP_TRGIN_DisableTriggers() to disable the Trigger Input

     In interrupt mode, the HAL provides these APIs:

     • HAL_HSP_TRGIN_EnableIT() to enable the Trigger Input

     • HAL_HSP_TRGIN_DisableIT() to disable the Trigger Input

   • Execute a Processing List

     For all Processing List attached to HSP Event (except for CSEG interface), the Hardware will trig the HSP Event and the execution of the Processing List will be scheduled by the Signal Processor Engine.

     • For Processing list triggered by a STREAM Buffer The HAL provides these APIs:

       • HAL_HSP_STREAM_Start() to start all the STREAM Buffers with possibility to select the STREAM Buffer interrupts to enable.

       • HAL_HSP_STREAM_Stop() to stop all the STREAM Buffers and all STREAM interrupts.

       • HAL_HSP_STREAM_IsActiveFlag_Event() to get the STREAM Buffer Empty/Full Flag status (Respectively for RX/TX)

       When a STREAM Buffer event occurs (Empty or Full depending on the buffer direction), use these APIs:

       • Call HAL_HSP_STREAM_WriteBufferData() to write a data to a STREAM Buffer (configured with RX direction)

       • Call HAL_HSP_STREAM_ReadBufferData() to read a data from a STREAM Buffer (configured with TX direction)

       Use HAL_HSP_STREAM_GetDataRegAddress() to get the address of a STREAM Buffer to pass as parameter of a processing function during the record of a processing list.

     • For Processing list triggered by a TRIGGER INPUT signal The execution of the processing list is automatically triggered by the Hardware.

     • For Processing list attached to an HSP Event with CSEG interface:

       • Call HAL_HSP_PRC_SWRequestTask() to send a request.

       • Call HAL_HSP_PRC_PollForEvent() to know if the request is always pending.

     • Lowest Priority processing

       • Call HAL_HSP_PRC_SWRequestLowestPriorityTask() to execute any processing list.

         The processing list will be scheduled and executed with the lowest priority by the Signal Processor Engine.

       • Call HAL_HSP_PRC_GetSWRequestLowestPriorityStatusAndClearFlag() to know if the request is always pending

8. HSP HAL Driver Performance & Monitoring

   • To synchronize the execution of a process list (attached to an event) by the end of another task:

     • When configuring the EVENT, configure the attribute “sync” and select one of the 4 Task Comparator (hal_hsp_event_hal_hsp_prc_task_sync_source_tsync_t)

     • Call HAL_HSP_TCU_StartComparator() to configure and Enable the selected Task Comparator Unit to start the monitoring of the end of a task

   • To reduce BRAM conflict access shared between CPU and HSP:

     • Call HAL_HSP_BRAM_EnableConflictAccessCounter() to enable the Conflict Access Counter

     • Run your processing sequence and call HAL_HSP_BRAM_GetConflictAccessCounter() to get the conflict counter value

     • Call HAL_HSP_BRAM_SetLatency() to change the BRAM Arbitration latency and try to reduce BRAM conflict access

     • Run again your processing sequence and get the conflict counter value

     • Check if the BRAM Arbitration changes reduce the number of conflict access

     • Iterate to find the best BRAM arbitration latency configuration for your application

   • To monitor the HSP with TimeStamp Capture feature:

     • Call HAL_HSP_TSC_SetConfig() to configure the TimeStamp Capture

     • Call HAL_HSP_TSC_Start() by specifying the capture mode to start the TimeStamp Capture

     In polling mode:

     • Call HAL_HSP_TSC_Start() by specifying the capture mode and setting the event and error interrupt parameters to HAL_HSP_IT_NONE

     • Call HAL_HSP_TSC_Stop() to stop the TimeStamp Capture

     • Call HAL_HSP_TSC_IsTimeStampReady() to know if a timestamp data is ready

     • Call HAL_HSP_TSC_GetTimeStamp() to get the last timestamp data

     In interrupt mode:

     • Call HAL_HSP_TSC_Start() by specifying the capture mode and setting the interrupt parameters to HAL_HSP_TSC_IT_DATA_READY and HAL_HSP_TSC_ERR_IT_OVR to start the TimeStamp Capture in interrupt mode

     • Call HAL_HSP_TSC_Stop() to stop the TimeStamp Capture and stop all TSC interrupts

     • When a timestamp data is ready, the TimestampReadyCallback callback is called (either user callback if registered with HAL_HSP_RegisterTSC_TimestampReadyCallback(), otherwise the default weak function is called).

   • To monitor the Signal Processor Engine activity

     • Call HAL_HSP_SNOOP_SetSignals() to observe key signals to ease application tuning.

     For this feature, HSP pins must be configured in Push-Pull mode. To do that:

     • Enable the clock for the HSP GPIOs

     • Configure HSP pins as alternate function

   • To manage the power consumption of HSP blocks call the following APIs:

     • HAL_HSP_SMARTCLOCKING_Enable() to enable the Smart Clocking of some clocks (Default mode)

     • HAL_HSP_SMARTCLOCKING_Disable() to disable the Smart Clocking of some clocks (increase the power consumption)

   • To debug a processing list

     • Call HAL_HSP_BREAK_SetDebugEvents() to select HSP events to freeze the Signal Processor Engine

     • Call HAL_HSP_BREAK_ResumeDebugEvents() to resume the Signal Processor Engine

     • Call HAL_HSP_BREAK_EnableDebugSingleStep() to enable the Single Step Debug mode. This allows to execute one instruction at a time and freeze the Signal Processor Engine after each instruction.

   • To stop sensitive peripheral, call HAL_HSP_BREAK_SetMultiConfigOutput() to configure the HSP Break output (which is interconnected with this peripheral) and select HSP errors considered critical event for the application.

9. Call HAL_HSP_DeInit() to deinitialize the HSP peripheral.

10. Optionally Call HAL_HSP_GetInstance() to retrieve the HSP instance.

11. Callback definition in Interrupt When the compilation define USE_HAL_HSP_REGISTER_CALLBACKS is set to 1, the user can dynamically configure the driver callbacks, via its own method:

Callback value	Default value	Callback registration function
PRC_TaskCpltCallback	HAL_HSP_PRC_TaskCpltCallback()	HAL_HSP_RegisterPRC_TaskCpltCallback()
SPE_FPUSaturationCallback	HAL_HSP_SPE_FPUSaturationCallback()	HAL_HSP_RegisterSPE_FPUSaturationCallback()
SPE_RunStateCallback	HAL_HSP_SPE_RunStateCallback()	HAL_HSP_RegisterSPE_RunStateCallback()
STREAM_BufferEmptyCallback	HAL_HSP_STREAM_BufferEmptyCallback()	HAL_HSP_RegisterSTREAM_BufferEmptyCallback()
STREAM_BufferFullCallback	HAL_HSP_STREAM_BufferFullCallback()	HAL_HSP_RegisterSTREAM_BufferFullCallback()
TCU_TaskStartedCallback	HAL_HSP_TCU_TaskStartedCallback()	HAL_HSP_RegisterTCU_TaskStartedCallback()
TCU_TaskEndedCallback	HAL_HSP_TCU_TaskEndedCallback()	HAL_HSP_RegisterTCU_TaskEndedCallback()
TCU_TaskOverlapCallback	HAL_HSP_TCU_TaskOverlapCallback()	HAL_HSP_RegisterTCU_TaskOverlapCallback()
TSC_TimestampReadyCallback	HAL_HSP_TSC_TimestampReadyCallback()	HAL_HSP_RegisterTSC_TimestampReadyCallback()
ErrorCallback	HAL_HSP_ErrorCallback()	HAL_HSP_RegisterErrorCallback()
ProcessingEventCallback	HAL_HSP_ProcessingEventCallback()	HAL_HSP_RegisterProcessingEventCallback()

To unregister a callback, re-register the corresponding default weak function via the registration function.

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

Callbacks can be registered in handle global_state HAL_HSP_STATE_INIT, HAL_HSP_STATE_READY_TO_BOOT or HAL_HSP_STATE_RUNNING.

When the compilation define USE_HAL_HSP_REGISTER_CALLBACKS is set to 0 or not defined, the callback registration feature is not available and weak callbacks are used, represented by the default value in the table above.

Warning

On failure, the handle state is set to HAL_HSP_STATE_FAULT to prohibit any configuration or processing. HAL_HSP_DeInit() must be called and an HSP Hardware Reset is required with HAL_RCC_HSP<x>_Reset().

Warning

After the call of HAL_HSP_DeInit(), make an HSP Hardware reset with HAL_RCC_HSP<x>_Reset().