 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The ADC Periodic Framework provides a high-level API for signal processing applications. The module configures the ADC/SDADC to sample any of the available channels (using the single-scan mode) at a configurable rate and buffers the data for a configurable number of sampling iterations before notifying the application. The ADC Periodic Framework uses the ADC/SDADC, GPT or AGT and DTC peripherals on a Renesas Synergy™ Microcontroller. A user‑defined callback can be created to process the data each time a new sample is available.
The ADC Periodic Framework defines APIs for opening, closing, starting and stopping the ADC scans. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
ADC Periodic Framework Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| open | g_sf_adc_periodic.p_api->open(g_sf_adc_periodic.p_ctrl, g_sf_adc_periodic.p_cfg);Acquires mutex, then initializes module at the HAL layer. |
| start | g_sf_adc_periodic.p_api->start(g_sf_adc_periodic.p_ctrl);Starts the scan. |
| stop | g_sf_adc_periodic.p_api->stop(g_sf_adc_periodic.p_ctrl);Stops the hardware trigger (timer) from triggering any more ADC scans. |
| close | g_sf_adc_periodic.p_api->close(g_sf_adc_periodic.p_ctrl);Releases channel mutex and closes channel at HAL layer. |
| versionGet | g_sf_adc_periodic.p_api->versionGet(&version);Retrieve the API version using the version pointer. |
Status Return Values
| Name | Description |
|---|---|
| SSP_SUCCESS | API Call Successful. |
| SSP_ERR_UNSUPPORTED | Command not found in the current menu. |
| SSP_ERR_NOT_OPEN | Driver control block not valid. CallSF_ADC_PERIODIC_Open to configure. |
| SSP_ERR_ASSERTION | Version get error- p_version was NULL. |
| SSP_ERR_INTERNAL | An internal ThreadX® error has occurred. This is typically a failure to create/use a mutex or to create an internal thread. |
The ADC Periodic Framework module samples and buffers ADC data. The Framework notifies the application once the configured number of samples are buffered. The ADC Periodic Framework works as follows:
Unless the user stops the scan process, the scan continues to be triggered by the timer (using AGT or GPT) and data will be written into the user buffer, which is treated by the Framework as a circular buffer. The name and length of the buffer are specified via the ISDE configurator.
When selecting the data buffer length in the ADC Periodic Framework configuration, make sure that the buffer length is at least twice the length of the number of samples that will be generated (15 x 2 = 30 in this example). This is because once the user application is notified that the data is available, the Framework will keep buffering in new data at the sample rate. Since the buffer is treated as a circular buffer, you can inadvertently overwrite the data. If the size is not larger than the number of samples generated, the data is overwritten before the application can use it.
The application callback has an index into the appropriate location in the buffer where valid data is present.
This section describes how to include the ADC Periodic Framework Module in an application using the SSP configurator.
To add the ADC Periodic Framework to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the ADC Periodic Framework is g_adc_periodic0. This name can be changed in the associated Properties window.)
ADC Periodic Framework Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_sf_adc_periodic0ADC Periodic Framework on sf_adc_periodic | Threads | New Stack> Driver> Analog> ADC Periodic Framework on sf_adc_periodic |
When the ADC Periodic Framework on sf_adc_periodic is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The ADC Periodic Framework Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the ADC Periodic Framework Module on sf_adc_periodic
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_sf_adc_periodic0 | Module name. |
| Name of the data-buffer to store samples | g_user_buffer | Name of the 16-bit data buffer to store samples. |
| Length of the data-buffer | 128 | Length of the buffer to which data is to be stored. |
| Number of sampling iterations | 10 | Priority of ADC Periodic Framework internal thread. |
| Callback | g_adc_framework_user_callback | User function that will be called once "sample_counts" number of data has been buffered. |
| Name of generated initialization function | sf_adc_periodic_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.
Configuration Settings for the ADC HAL Module on r_adc
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: Enabled | If selected code for parameter checking is included in the build. |
| Name | g_adc0 | Module name. |
| Unit | 0, 1 (S7G2 Only) Default: 0 | Specify the ADC Unit to be used. The S7G2 has two units; 0 and 1. |
| Resolution | 14-Bit (S3A7/S124 Only), 12-Bit, 10-Bit (S7G2) Default: 8-Bit (S7G2 Only) | Specify the conversion resolution for this unit. |
| Alignment | Right, Left Default: Right | Specify the conversion result alignment. |
| Clear after read | Off, On Default: On | Specify if the result register must be automatically cleared after the conversion result is read. Note: If this is enabled, then watching the result register using a debugger always results in a 0. |
| Mode | Single Scan | The ADC Framework preconfigures and locks this field. |
| Channels 0-6 | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Channels 7-10 (S3A7/S124 Only) | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Channels 11-15 (S3A7 Only) | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Channels 16-20 | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Channel 21 (Unit 0 Only) | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Channel 22 (S3A7/S124 Only) | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Channels 23-27 (S3A7 Only) | Unused, Use in Normal/Group A, Use in Group B Default: Unused | In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A. |
| Temperature Sensor | Unused, Use in Normal/Group A, Use in Group B Default: Unused | Temperature sensor use selection for Channel Scan Mask. |
| Voltage Sensor | Unused, Use in Normal/Group A, Use in Group B Default: Unused | Voltage sensor use selection for Channel Scan Mask. |
| Normal/Group A Trigger | ELC Event | The ADC Framework preconfigures and locks this field. |
| Group B Trigger (Valid Only in Group Scan Mode) | ELC Event (The only valid trigger for either group in Group Scan Mode) | The ADC Framework preconfigures and locks this field. |
| Group Priority (Valid only in Group Scan Mode) | Group A cannot interrupt Group B, Group A can interrupt Group B; Group B scan restarts at next trigger, Group A can interrupt Group B; Group B scan restarts immediately, Group A can interrupt Group B; Group B scan restarts immediately and scans continuously Default: Group A cannot interrupt Group B | Do not use with ADC Framework since the mode is locked to Single Scan Mode. |
| Add/Average Count | Disabled, Add two samples, Add three samples, Add four samples, Add sixteen samples, Average two samples, Average four samples Default: Disabled | Specify if addition or averaging needs to be done for any of the channels in this unit. The actual channels are specified by using a channel mask adc_channel_cfg_t::add_mask. |
| Channels 0-27 | Disabled, Enabled Default: Disabled | This field is valid only if adc_cfg_t::add_average_count is enabled. This field determines what channels results are to be averaged or summed. |
| Temperature Sensor | Disabled, Enabled Default: Disabled | Temperature sensor use selection for Addition/Averaging Mask. |
| Voltage Sensor | Disabled, Enabled Default: Disabled | Voltage sensor use selection for Addition/Averaging Mask. |
| Channels 0-2 | Disabled, Enabled Default: Disabled | Determines which of channels 0, 1 and 2 are using the updated sample-and-hold states value specified in adc_channel_cfg_t::sample_hold_states. This field must only be set if it is desired to modify the default sample and hold count value for channels 0, 1 and 2. |
| Sample Hold States (Applies only to the 3 channels selected above) | 24 | Specifies the updated sample-and-hold count for the channel dedicated sample-and-hold circuit. This field is valid only if adc_channel_cfg_t::sample_hold_mask is not 0. Only channels 0, 1 and 2 have dedicated sample and hold circuits. Note: Use this to modify the default number of states (24) for which the value is sampled. Each state is equal to 1/ADCLK time. |
| Callback | NULL | The ADC Framework uses the callback internally. |
| Scan End Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | Scan End Interrupt Priority selection. |
| Scan End Group B Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | Scan End Group B Interrupt Priority selection. |
Configuration Settings for the SDADC HAL Module on r_sdadc(Only for S1JA)
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enable or disable parameter error checking. |
| Name | g_adc0 | Module name. |
| Mode | Single Scan, Continuous Scan Default: Continuous Scan | In single scan mode, all channels are converted once per start trigger, and conversion stops after all enabled channels are scanned. In continuous scan mode, conversion starts after a start trigger, then continues until stopped in software. |
| Resolution | 16 Bit, 24 Bit Default: 24 Bit | Select 24-bit or 16-bit resolution. |
| Alignment | Right, Left Default: Right | Select left or right alignment. |
| Trigger | ELC Hardware Event, Software Default: Software | Select conversion start trigger. Conversion can be started in software, or conversion can be started when a hardware event occurs if the hardware event is linked to the SDADC peripheral using the ELC API. |
| Vref Source | Internal, External Default: Internal | Vref can be sourced internally and output on the SBIAS pin, or Vref can be input from VREFI. |
| Vref Voltage | 0.8 V, 1.0 V, 1.2 V, 1.4 V, 1.6 V, 1.8 V, 2.0 V, 2.2 V, 2.4 V Default: 1.0 V | Select Vref voltage. If Vref is input externally, the voltage on VREFI must match the voltage selected within 3%. |
| Internal Calibration During Open() | Enabled, Disabled Default: Enabled | Calibration is required for all channels configured for differential input. Internal calibration is performed automatically during open for these channels unless it is disabled here. |
| Callback | NULL | Enter the name of the callback function to be called when conversion completes or a scan ends. |
| Conversion End Interrupt Priority | Priority 0 (highest), Priority 1, Priority 2, Priority 3 (lowest - not valid if using ThreadX) Default: Priority 2 | Select the interrupt priority for the conversion end interrupt. [Required] |
| Scan End Interrupt Priority | Priority 0 (highest), Priority 1, Priority 2, Priority 3 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Select the interrupt priority for the scan end interrupt. [Required] |
| Calibration End Interrupt Priority | Priority 0 (highest), Priority 1, Priority 2, Priority 3 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Select the interrupt priority for the calibration end interrupt. [Required] |
Configuration Settings for the AGT HAL Module on r_agt
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables parameter checking. |
| Name | g_timer0 | Module name. |
| Channel | 0 | Physical hardware channel. |
| Mode | Periodic | Warning: One-shot functionality is not available in the GPT hardware, so it is implemented in software by stopping the timer in the ISR called when the period expires. For this reason, ISRs must be enabled for one-shot mode even if the callback is unused. |
| Period Value | 10 | See Timer Period Calculation. |
| Period Unit | Raw Counts, Nanoseconds, Microseconds, Milliseconds, Seconds, Hertz, Kilohertz Default: Microseconds | See Timer Period Calculation. |
| Auto Start | False | Set to true to start the timer after configuring or false to leave the timer stopped until timer_api_t::start is called. |
| Count Source | PCLKB, PCLKB/8, PCLKB/2, LOCO, AGT0 Underflow, AGT0 fSub Default: PCLKB | The clock source for the AGT counter. |
| AGTO Output Enabled | True, False Default: False | Set to true to output the timer signal on a port pin configured for AGT (AGTO pin). Set to false for no output of the timer signal. |
| AGTIO Output Enabled | True, False Default: False | Set to true to output the timer signal on a port pin configured for AGT (AGTIO pin). Set to false for no output of the timer signal. |
| Output Inverted | True, False Default: True | Set to false to start the output signal low. Set to true to start the output signal high. |
| Enable comparator A output pin | True, False Default: False | Enable comparator A output pin selection. |
| Enable comparator B output pin | True, False Default: False | Enable comparator B output pin selection. |
| Callback | NULL | A user callback function can be registered in timer_api_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the timer period elapses. Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system. |
| Underflow Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | Timer interrupt priority. 0 is the highest priority. |
Configuration Settings for the GPT HAL Module on r_gpt
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_timer0 | Module name. |
| Channel | 0 | The ADC Framework preconfigures and locks this field based on channel selected in the ADC Framework. |
| Mode | Periodic | The ADC Framework preconfigures and locks this field. |
| Period Value | 10 | Configure timer period to trigger ADC scans. |
| Period Unit | Raw Counts, Nanoseconds, Microseconds, Milliseconds, Seconds, Hertz, Kilohertz Default: Milliseconds | Configure units of the timer period set above. |
| Duty Cycle Value | 50 | Duty cycle value selection. |
| Duty Cycle Unit | Unit Raw Counts, Unit Percent, Unit Percent x 1000 Default: Unit Raw Counts | Duty cycle unit selection. |
| Auto Start | False | The ADC Framework preconfigures and locks this field. |
| GTIOCA Output Enabled | True, False Default: False | Set to true to output the timer signal on a port pin configured for GPT. Set to false for no output of the timer signal. |
| GTIOCA Stop Level | Pin Level Low, Pin Level High, Pin Level Retained Default: Pin Level Low | Controls output pin level when the timer is stopped. |
| GTIOCB Output Enabled | True, False Default: False | Set to true to output the timer signal on a port pin configured for GPT. Set to false for no output of the timer signal. |
| GTIOCB Stop Level | Pin Level Low, Pin Level High, Pin Level Retained Default: Pin Level Low | Controls output pin level when the timer is stopped. |
| Callback | NULL | The ADC Framework preconfigures and locks this field. |
| Overflow Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | Interrupt priority selection. |
Configuration Settings for the DTC HAL Module on r_dtc Software Activation
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Selects if code for parameter checking is to be included in the build. |
| Software Start | Enabled, Disabled Default: Disabled | Software start selection. |
| Linker section to keep DTC vector table | .ssp_dtc_vector_table | Linker section to keep DTC vector table selection. |
| Name | g_transfer0 | Module name. |
| Mode | Block | Mode selection. |
| Transfer Size | 2 Bytes | Transfer size selection. |
| Destination Address Mode | Incremented | Destination address mode selection. |
| Source Address Mode | Incremented | Source address mode selection. |
| Repeat Area (Unused in Normal Mode | Source | Repeat area selection. |
| Interrupt Frequency | After all transfers have completed | Interrupt frequency selection. |
| Destination Pointer | NULL | Destination pointer selection. |
| Source Pointer | NULL | Source pointer selection. |
| Number of Transfers | 1 | Number of transfers selection. |
| Number of Blocks (Valid only in Block Mode) | 1 | Number of blocks selection. |
| Activation Source (Must enable IRQ) | Software Activation 1 | Activation source selection. |
| Auto Enable | False | Auto enable selection. |
| Callback (Only valid with Software start) | NULL | Callback selection. |
| ELC Software Event Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | ELC Software Event interrupt priority selection. |
To access a channel, ADC channels must be set in the Pins tab of the ISDE. The following table illustrates the method for selecting the pins within the SSP configuration window:
Pin Selection for the ADC HAL Module on r_adc
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| ADC | Pins | Select Peripherals > **Analog: ADC > ADC0\1** > AN_XX |
| SDADC | Pins | Select Peripherals > Analog: SDADC > SDADC0 > AN_XX |
The steps in using the ADC Periodic Framework module on sf_audio_record_adc in a typical application are:
These common steps are illustrated in a typical operational flow diagram in the following figure:
