1 /*******************************************************************************
\r
2 * (c) Copyright 2009 Actel Corporation. All rights reserved.
\r
4 * SmartFusion ACE driver public API.
\r
6 * SVN $Revision: 2884 $
\r
7 * SVN $Date: 2010-08-13 16:16:59 +0100 (Fri, 13 Aug 2010) $
\r
10 /*=========================================================================*//**
\r
11 @mainpage SmartFusion Analog Compute Engine driver public API.
\r
13 @section intro_sec Introduction
\r
14 The SmartFusion
\99 microcontroller subsystem (MSS) includes the Analog Compute
\r
15 Engine (ACE) which provides access to the analog capabilities of SmartFusion
\r
16 from the Cortex
\99-M3 microcontroller. This driver provides a set of functions
\r
17 for controlling the MSS ACE as part of a bare metal system where no operating
\r
18 system is available. These drivers can be adapted for use as part of an
\r
19 operating system, but the implementation of the adaptation layer between this
\r
20 driver and the operating system's driver model is outside the scope of this
\r
21 driver. The ACE includes:
\r
22 \95 A Sample Sequencing Engine (SSE) controlling the operations of up to
\r
23 three analog to digital converters (ADC)
\r
24 \95 A Post Processing Engine (PPE) processing the analog inputs samples
\r
25 generated as a result of the SSE operations
\r
26 \95 An interface for controlling Sigma Delta DACs (SDD)
\r
27 \95 An interface for controlling high speed comparators
\r
29 The Sample Sequencing Engine controls the sampling of the various analog
\r
30 inputs based on a predefined sampling sequence without requiring intervention
\r
31 from the Cortex-M3. The sampling sequence is defined using the ACE Configurator
\r
32 provided as part of the MSS Configurator software tool.
\r
33 Available analog inputs are:
\r
34 \95 Active bipolar prescaler inputs (ABPS) allowing to measure voltages within
\r
35 four possible ranges:
\r
41 \95 Temperature inputs
\r
42 \95 Direct ADC inputs allowing to measure a voltage between zero volts and
\r
43 the ADC
\92s reference voltage (VAREF)
\r
44 Please refer to the Analog Front End section of the SmartFusion datasheet for
\r
45 further details about analog inputs.
\r
47 The Post Processing Engine can perform the following operations on the analog
\r
48 input samples generated as a result of the SSE operations:
\r
49 \95 Calibration adjustment
\r
51 \95 Threshold detection
\r
52 \95 DMA transfer of most recent sample result to RAM or FPGA fabric
\r
53 The result of analog input sampling is read from the PPE rather than directly
\r
54 from the ADC. This ensures more accurate sample results thought the factory
\r
55 calibration adjustment performed by the PPE.
\r
56 The PPE can be set to generate interrupts when specific threshold values are
\r
57 reached on analog inputs through the ACE Configurator software tool. These
\r
58 thresholds can also be dynamically adjusted through the ACE driver.
\r
60 The ACE provides an interface to the Sigma Delta DACs included within the
\r
61 Analog Front End (AFE). This interface allows control of the DAC
\92s output
\r
62 value. Dynamic configuration of the DAC is also possible.
\r
64 The ACE provides an interface to the high speed comparators included within
\r
65 the Analog Front End. This interface allows dynamic configuration of the
\r
66 comparators and controlling interrupts based on the comparators
\92 state.
\r
68 @section theory_op Theory of Operation
\r
69 The configuration of the ACE is set though the use of the ACE Configurator
\r
70 included in the SmartFusion MSS Configurator software tool provided as part of
\r
71 the Libero Integrated Design Environment tool suite. The ACE Configurator
\r
72 offers an easy to use graphical method of selecting the configuration of the
\r
73 following ACE characteristics:
\r
74 \95 Analog input channels configuration
\r
75 \95 ADC configuration
\r
76 \95 Analog input channels sampling sequence
\r
77 \95 Filtering applied to analog input samples
\r
78 \95 Threshold flags configuration including hysteresis or state filtering properties
\r
79 \95 Selection of post processing results transferred though DMA
\r
80 \95 Sigma Delta DACs configuration
\r
81 \95 Analog comparators configuration
\r
82 The selected configuration hardware settings, SSE microcode and PPE microcode
\r
83 are stored in the SmartFusion eNVM. This configuration data is used by the
\r
84 system boot to configure the ACE after the system come out of reset and before
\r
85 control is passed to the application. This results in the ACE being fully
\r
86 operational by the time the application starts executing.
\r
87 The ACE Configurator also generates a set of C files containing information
\r
88 about the ACE
\92s configuration. These C files must be copied into the
\r
89 drivers_config/mss_ace folder of you r software project for consumption by the
\r
90 ACE driver. The ACE driver uses the content of these configuration files to
\r
91 interact with the configured ACE hardware.
\r
93 The ACE driver functions are grouped into the following categories:
\r
95 \95 Reading analog input channels values and properties
\r
96 \95 Post Processing Engine flags
\r
97 \95 Conversion functions between sample value and real world units
\r
98 \95 Sample Sequencing Engine control
\r
99 \95 Sample Sequencing Engine Interrupts Control
\r
100 \95 Comparators control
\r
101 \95 Sigma Delta Digital to Analog Converters (SDD) control
\r
102 \95 Direct analog block configuration and usage
\r
106 The ACE driver is initialized through a call to the ACE_init() function. The
\r
107 ACE_init() function must be called before any other ACE driver functions can
\r
108 be called. It initializes the ACE
\92s internal data.
\r
111 Reading analog input channels values and properties
\r
112 The ACE driver allows retrieving the most recent post processed sample value
\r
113 for each analog input. It also allows retrieving the name of the analog input
\r
114 channel assigned in the ACE Configurator and whether the input channel samples
\r
115 a voltage, current or temperature.
\r
116 Each individual analog input channel is identified using a channel handle which
\r
117 is passed as parameter to the ACE input channel driver functions. The channel
\r
118 handles are design specific. The list of channel handles is generated by the
\r
119 ACE Configurator based on the names given to the input signals. The channel
\r
120 handles can be found in the drivers_config\mss_ace\ace_handles.h file. The
\r
121 channel handle can be obtained from the channel name using the ACE_get_channel_handle()
\r
122 function. It is also possible to iterate through all the channels using the
\r
123 ACE_get_first_channel() and ACE_get_next_channel() functions.
\r
125 Reading analog input samples from the post processing engine is done the following function:
\r
126 \95 uint16_t ACE_get_ppe_sample( ace_channel_handle_t channel_handle )
\r
128 Information about an input channel can be retrieved using the following functions:
\r
129 \95 const uint8_t * ACE_get_channel_name( ace_channel_handle_t channel_handle )
\r
130 \95 channel_type_t ACE_get_channel_type( ace_channel_handle_t channel_handle )
\r
133 Post Processing Engine flags
\r
134 The SmartFusion ACE Post Processing Engine (PPE) provides the ability to monitor
\r
135 the state of analog input channels and detect when certain threshold values are
\r
136 crossed. Flags are raised by the PPE when these thresholds are crossed. Interrupts
\r
137 can optionally be generated when flags are raised.
\r
138 The flags are defined using the ACE Configurator software tool. The flag
\92s name,
\r
139 threshold value and hysteresis settings are specified in the ACE Configurator.
\r
140 The ACE Configurator generates microcode based on the selected configuration which
\r
141 is executed at system run time by the PPE. The PPE microcode is loaded into the
\r
142 ACE at chip boot time by the Actel provided system boot code. No ACE driver
\r
143 intervention is required to load up the PPE microcode.
\r
144 The ACE driver allows:
\r
145 \95 Retrieving the current state of the post processing engine flags
\r
146 \95 Assigning a handler function to individual flag assertions
\r
147 \95 Assigning a handler function to flags generated based on the value of a
\r
149 \95 Controlling flag interrupts
\r
150 \95 Dynamically modify a flag
\92s threshold value
\r
151 \95 Dynamically modify a flag
\92s hysteresis
\r
153 Each individual flag is identified using a flag handle which is passed as parameter
\r
154 to the ACE driver functions controlling the flags. The flag handles are design
\r
155 specific. They are defined in the drivers_config\mss_ace\ace_handles.h file which
\r
156 is generated by the ACE Configurator based on the names selected for the signal
\r
157 and flag names. A flag handle can be obtained from the driver using the name of
\r
158 the flag entered in the ACE Configurator software when the flag was created. A
\r
159 flag handle can also be obtained using the functions ACE_get_channel_first_flag()
\r
160 and ACE_get_channel_next_flag() when iterating through the flags associated with
\r
161 an analog input channel. The functions available for retrieving flag handles are:
\r
162 \95 ace_flag_handle_t ACE_get_flag_handle (const uint8_t *p_sz_full_flag_name)
\r
163 \95 ace_flag_handle_t ACE_get_channel_first_flag (ace_channel_handle_t channel_handle, uint16_t *iterator)
\r
164 \95 ace_flag_handle_t ACE_get_channel_next_flag (ace_channel_handle_t channel_handle, uint16_t *iterator)
\r
166 The current status of a flag can be polled using the following function:
\r
167 \95 int32_t ACE_get_flag_status (ace_flag_handle_t flag_handle)
\r
169 Interrupt handlers can be registered with the ACE driver to handle individual
\r
170 flags. These interrupt handlers will be called by the ACE driver when a specific
\r
171 flag is raised. The flag interrupt control functions are:
\r
172 \95 void ACE_register_flag_isr (ace_flag_handle_t flag_handle, flag_isr_t flag_isr)
\r
173 \95 void ACE_enable_flag_irq (ace_flag_handle_t flag_handle)
\r
174 \95 void ACE_disable_flag_irq (ace_flag_handle_t flag_handle)
\r
175 \95 void ACE_clear_flag_irq (ace_flag_handle_t flag_handle)
\r
177 Interrupt handlers can be registered with the ACE driver to handle all flags
\r
178 associated with one specific analog input channel. These interrupt handlers will
\r
179 be called by the ACE driver when one of the flags, generated based on the state of
\r
180 the specified analog input channel, is raised. The channel flag interrupt control
\r
182 \95 void ACE_register_channel_flags_isr (ace_channel_handle_t channel_handle, channel_flag_isr_t channel_flag_isr)
\r
183 \95 void ACE_enable_channel_flags_irq (ace_channel_handle_t channel_handle)
\r
184 \95 void ACE_disable_channel_flags_irq (ace_channel_handle_t channel_handle)
\r
185 \95 void ACE_clear_channel_flags_irq (ace_channel_handle_t channel_handle)
\r
187 A single global interrupt handler can be registered with the ACE driver. The global
\r
188 flag interrupt handler function will be called by the ACE driver when any of the
\r
189 interrupt enabled flag is raised. The handle of the flag causing the interrupt and
\r
190 the handle of the associated analog input channel is passed as parameter to the
\r
191 registered global flag handler.
\r
192 \95 void ACE_register_global_flags_isr (global_flag_isr_t global_flag_isr)
\r
194 The configuration of a flag can be dynamically modified using the following functions:
\r
195 \95 void ACE_set_flag_threshold (ace_flag_handle_t flag_handle, uint16_t new_threshold)
\r
196 \95 void ACE_set_flag_hysteresis (ace_flag_handle_t flag_handle, uint16_t adc_hysteresis)
\r
197 \95 void ACE_set_channel_hysteresis (ace_channel_handle_t channel_handle, uint16_t adc_hysteresis)
\r
198 \95 void ACE_set_flag_assertion( ace_flag_handle_t flag_handle, uint16_t assertion_value )
\r
199 \95 void ACE_set_flag_deassertion( ace_flag_handle_t flag_handle, uint16_t assertion_value )
\r
201 Information about a flag can be retrieved using the following functions once
\r
202 the flag handle is known:
\r
203 \95 const uint8_t * ACE_get_flag_name (ace_flag_handle_t flag_handle)
\r
204 \95 ace_channel_handle_t ACE_get_flag_channel (ace_flag_handle_t flag_handle)
\r
207 Conversion to and from real world units
\r
208 The ACE driver provides a set of conversion functions to convert sample values
\r
209 read from the post processing engine into real world units:
\r
213 \95 Degrees Celsius
\r
214 \95 Degrees Fahrenheit
\r
215 Conversion functions are also available to convert from real world units into
\r
216 PPE sample values. These functions are typically used for dynamically adjusting
\r
217 flags threshold values.
\r
220 Sample Sequencing Engine control
\r
221 The ACE driver provides a set of functions for dynamically controlling the
\r
222 Sample Sequencing Engine. These functions are only required for managing multiple
\r
223 sampling sequences. The use of these functions is not required for most applications
\r
224 since the SSE is already configured and running by the time the application starts.
\r
227 Sample Sequencing Engine Interrupts Control
\r
228 The ACE driver provides a set of functions for managing interrupts generated by
\r
229 the Sample Sequencing Engine. These functions allow enabling, disabling and clearing
\r
230 interrupt defined as part of the sampling sequence. These functions also allow
\r
231 controlling interrupts generated by the ADCs.
\r
234 Comparators control
\r
235 The ACE driver provides a set of functions for managing interrupts generated based
\r
236 on the change of state of the high speed comparators. Functions are also provided
\r
237 to dynamically modify the comparators configuration.
\r
240 Sigma Delta Digital to Analog Converters (SDD) control
\r
241 The ACE driver provides functions for controlling the output value of the Sigma
\r
242 Delta DACs (SDD). Functions are also provided for dynamically adjusting the
\r
243 configuration of the SDDs.
\r
245 *//*=========================================================================*/
\r
246 #ifndef __MSS_ACE_H_
\r
247 #define __MSS_ACE_H_
\r
249 #include <stdint.h>
\r
255 #include "ace_handles.h"
\r
257 /*-------------------------------------------------------------------------*//**
\r
258 Analog to Digital Converter channel IDs.
\r
259 This enumeration is used to identify the ADC's analog inputs. It caters for up
\r
260 to three ADCs/Analog Modules as can be found on the larger parts of the
\r
261 SmartFusion family. The channel ID numbering is designed to allow easy
\r
262 extraction of the ADC number and also the individual ADC input number by simple
\r
263 shifting and masking. This enumeration is used as parameter to the
\r
264 ACE_get_input_channel_handle() function retrieving the channel handle associated
\r
265 with a specific analog input signal.
\r
269 ADC0_1P5V = 0, /*!< Analog Module 0, 1.5V/GND */
\r
270 ABPS0 = 1, /*!< Analog Module 0, Quad0 Active Bipolar Pre-Scaler input 1 */
\r
271 ABPS1 = 2, /*!< Analog Module 0, Quad0 Active Bipolar Pre-Scaler input 2 */
\r
272 CM0 = 3, /*!< Analog Module 0, Quad0 Current Monitor Block */
\r
273 TM0 = 4, /*!< Analog Module 0, Quad0 Temperature Monitor Block */
\r
274 ABPS2 = 5, /*!< Analog Module 0, Quad1 Active Bipolar Pre-Scaler input 1 */
\r
275 ABPS3 = 6, /*!< Analog Module 0, Quad1 Active Bipolar Pre-Scaler input 2 */
\r
276 CM1 = 7, /*!< Analog Module 0, Quad1 Current Monitor Block */
\r
277 TM1 = 8, /*!< Analog Module 0, Quad1 Temperature Monitor Block */
\r
278 ADC0 = 9, /*!< Analog Module 0 Direct Input 0 */
\r
279 ADC1 = 10, /*!< Analog Module 0 Direct Input 1 */
\r
280 ADC2 = 11, /*!< Analog Module 0 Direct Input 2 */
\r
281 ADC3 = 12, /*!< Analog Module 0 Direct Input 3 */
\r
282 SDD0_IN = 15, /*!< Analog Module 0 Sigma-Delta DAC output */
\r
284 ADC1_1P5V = 16, /*!< Analog Module 1, 1.5V/GND */
\r
285 ABPS4 = 17, /*!< Analog Module 1, Quad0 Active Bipolar Pre-Scaler input 1 */
\r
286 ABPS5 = 18, /*!< Analog Module 1, Quad0 Active Bipolar Pre-Scaler input 2 */
\r
287 CM2 = 19, /*!< Analog Module 1, Quad0 Current Monitor Block */
\r
288 TM2 = 20, /*!< Analog Module 1, Quad0 Temperature Monitor Block */
\r
289 ABPS6 = 21, /*!< Analog Module 1, Quad1 Active Bipolar Pre-Scaler input 1 */
\r
290 ABPS7 = 22, /*!< Analog Module 1, Quad1 Active Bipolar Pre-Scaler input 2 */
\r
291 CM3 = 23, /*!< Analog Module 1, Quad1 Current Monitor Block */
\r
292 TM3 = 24, /*!< Analog Module 1, Quad1 Temperature Monitor Block */
\r
293 ADC4 = 25, /*!< Analog Module 1 Direct Input 0 */
\r
294 ADC5 = 26, /*!< Analog Module 1 Direct Input 1 */
\r
295 ADC6 = 27, /*!< Analog Module 1 Direct Input 2 */
\r
296 ADC7 = 28, /*!< Analog Module 1 Direct Input 3 */
\r
297 SDD1_IN = 31, /*!< Analog Module 1 Sigma-Delta DAC output */
\r
299 ADC2_1P5V = 32, /*!< Analog Module 2, 1.5V/GND */
\r
300 ABPS8 = 33, /*!< Analog Module 2, Quad0 Active Bipolar Pre-Scaler input 1 */
\r
301 ABPS9 = 34, /*!< Analog Module 2, Quad0 Active Bipolar Pre-Scaler input 2 */
\r
302 CM4 = 35, /*!< Analog Module 2, Quad0 Current Monitor Block */
\r
303 TM4 = 36, /*!< Analog Module 2, Quad0 Temperature Monitor Block */
\r
304 ABPS10 = 37, /*!< Analog Module 2, Quad1 Active Bipolar Pre-Scaler input 1 */
\r
305 ABPS11 = 38, /*!< Analog Module 2, Quad1 Active Bipolar Pre-Scaler input 2 */
\r
306 CM5 = 39, /*!< Analog Module 2, Quad1 Current Monitor Block */
\r
307 TM5 = 40, /*!< Analog Module 2, Quad1 Temperature Monitor Block */
\r
308 ADC8 = 41, /*!< Analog Module 2 Direct Input 0 */
\r
309 ADC9 = 42, /*!< Analog Module 2 Direct Input 1 */
\r
310 ADC10 = 43, /*!< Analog Module 2 Direct Input 2 */
\r
311 ADC11 = 44, /*!< Analog Module 2 Direct Input 3 */
\r
312 SDD2_IN = 47, /*!< Analog Module 2 Sigma-Delta DAC output */
\r
313 INVALID_CHANNEL = 255 /*!< Used to indicate errors */
\r
314 } adc_channel_id_t;
\r
317 /*-------------------------------------------------------------------------*//**
\r
318 The ACE_init() function initializes the SmartFusion MSS ACE driver. It
\r
319 initializes the ACE driver
\92s internal data structures. The ACE_init() function
\r
320 must be called before any other MSS ACE driver functions can be called.
\r
322 void ACE_init( void );
\r
325 /*==============================================================================
\r
326 ============== Direct Analog Block Configuration and Usage ====================
\r
327 =============================================================================*/
\r
329 /*=========================================================================*//**
\r
330 @defgroup group1 Direct Analog Block Configuration and Usage
\r
331 These functions are intended for using the SmartFusion analog block hardware
\r
332 without relying on the Sampling Sequence Engine or Post Processing engine.
\r
334 *//*=========================================================================*/
\r
336 /*-------------------------------------------------------------------------*//**
\r
337 The ACE_start_adc() function initiates the sampling of the analog input
\r
338 channel identified by the channel_id parameter. This function is provided for
\r
339 test purposes. It must not be used while the Sample Sequencing Engine is
\r
343 The channel_id parameter identifies the analog input channel to sample.
\r
346 This function does not return a value.
\r
350 adc_channel_id_t channel_id
\r
353 /*-------------------------------------------------------------------------*//**
\r
354 The ACE_get_adc_result () function reads the result of the last input channel
\r
355 sampling performed by the ADC identified as parameter.
\r
358 The adc_id parameter identifies which of the possible three ADC to read the
\r
359 sample result from.
\r
362 The ACE_start_adc_sync() function returns the ADC result from the ADC
\r
363 specified as parameter.
\r
365 uint16_t ACE_get_adc_result
\r
372 /*==============================================================================
\r
373 =========== Sigma Delta Digital to Analog Converters (SDD) Control ============
\r
374 =============================================================================*/
\r
375 /*=========================================================================*//**
\r
376 @defgroup group2 Sigma Delta Digital to Analog Converters (SDD) Control
\r
377 The following functions are used to control the Sigma Delta DACs included
\r
378 within the SmartFusion analog block.
\r
380 *//*=========================================================================*/
\r
382 /*-------------------------------------------------------------------------*//**
\r
383 The sdd_id_t enumeration is used to identify the Sigma Delta DACs to the SDD
\r
384 control functions, ACE_configure_sdd(), ACE_enable_sdd(), ACE_disable_sdd()
\r
385 and ACE_set_sdd_value(). There is one SDD per analog module.
\r
389 SDD0_OUT = 0, /*!< Analog Module 0 Sigma Delta DAC */
\r
390 SDD1_OUT = 1, /*!< Analog Module 1 Sigma Delta DAC */
\r
391 SDD2_OUT = 2, /*!< Analog Module 2 Sigma Delta DAC */
\r
395 /*-------------------------------------------------------------------------*//**
\r
396 The sdd_resolution_t enumeration is used as a parameter to the
\r
397 ACE_configure_sdd() function to specify DAC resolution of the Sigma Delta DAC.
\r
404 } sdd_resolution_t;
\r
406 /*-------------------------------------------------------------------------*//**
\r
407 These constant definitions are used as an argument to the ACE_configure_sdd()
\r
408 function to specify operating mode of the Sigma Delta DAC.
\r
410 #define SDD_CURRENT_MODE 1
\r
411 #define SDD_VOLTAGE_MODE 0
\r
412 #define SDD_RETURN_TO_ZERO 0
\r
413 #define SDD_NON_RTZ 2
\r
415 /*-------------------------------------------------------------------------*//**
\r
416 The sdd_update_method_t enumeration is used as a parameter to the
\r
417 ACE_configure_sdd() function to specify individual or synchronous updating of
\r
418 the Sigma Delta DACs.
\r
422 INDIVIDUAL_UPDATE = 0,
\r
424 } sdd_update_method_t;
\r
426 /*-------------------------------------------------------------------------*//**
\r
427 The ACE_configure_sdd() function is used to configure the operating mode of
\r
428 the Sigma Delta DAC (SDD) specified as parameter. It allows selecting whether the
\r
429 SDD will output a voltage or a current. A current between 0 and 256uA is
\r
430 generated in current mode. A voltage between 0 and 2.56V is generated in
\r
432 This function also allows selecting whether Return To Zero (RTZ) mode is
\r
433 enabled or not. Enabling Return To Zero mode improves linearity of the SDD
\r
434 output at the detriment of accuracy. This mode should be used if linearity is
\r
435 more important than accuracy.
\r
436 A call to this function is not required if relying on the configuration
\r
437 selected in the ACE configurator being loaded after reset by the system boot.
\r
440 The sdd_id parameter specifies which Sigma Delta DAC is configured by this
\r
441 function. Allowed values are:
\r
447 The resolution parameter specifies the desired resolution of the Sigma Delta DAC.
\r
448 Allowed values are:
\r
454 The mode parameter specifies the operating mode of the Sigma Delta DAC. It
\r
455 specifies whether a current or voltage should be generated and whether
\r
456 Return to Zero mode should be used. It is a logical OR of the following
\r
460 - SDD_RETURN_TO_ZERO
\r
464 The sync_update parameter specifies whether the SDD output will be updated
\r
465 individually though a call to ACE_set_sdd_value() or synchronously with one
\r
466 or more other SDD outputs via a call to ACE_set_sdd_value_sync().
\r
474 SDD_VOLTAGE_MODE | SDD_RETURN_TO_ZERO,
\r
479 void ACE_configure_sdd
\r
482 sdd_resolution_t resolution,
\r
484 sdd_update_method_t sync_update
\r
487 /*-------------------------------------------------------------------------*//**
\r
488 The ACE_enable_sdd() function is used to enable a Sigma Delta DAC.
\r
491 The sdd_id parameter specifies the Sigma Delta DAC to enable.
\r
493 void ACE_enable_sdd
\r
498 /*-------------------------------------------------------------------------*//**
\r
499 The ACE_disable_sdd() function is used to disable a Sigma Delta DAC.
\r
502 The sdd_id parameter specifies the Sigma Delta DAC to disable.
\r
504 void ACE_disable_sdd
\r
509 /*-------------------------------------------------------------------------*//**
\r
510 The ACE_set_sdd_value() function is used to set the value of the output of
\r
511 a Sigma Delta DAC. It uses the ACE's phase accumulator to generate the one bit
\r
512 input bit stream into the SDD which will in turn define the voltage or
\r
513 current generated at the SDD output.
\r
514 The SDD output is proportional to the sdd_value passed to this function taking
\r
515 the SDD resolution into account. A maximum voltage of 2.56V or a maximum
\r
516 current of 256uA will be generated when the sdd_value is set the maximum value
\r
517 allowed by the SDD resolution
\r
520 The sdd_id parameter specifies which Sigma Delta DAC is being set.
\r
523 The sdd_value parameter specifies the value of the Sigma Delta DAC output.
\r
524 It is a fraction of SDD resolution. The voltage/current value generated from
\r
525 the sdd_value paramenter can be determined using the following equation where
\r
526 sdd_resolution is the resolution of the SDD as set through function
\r
527 ACE_configure_sdd() and sdd_rangSDD configuration:
\r
528 sdd_output = (sdd_value / sdd_resolution) * sdd_range
\r
530 void ACE_set_sdd_value
\r
537 /*-------------------------------------------------------------------------*//**
\r
538 This constant definition is used as an argument to the ACE_set_sdd_value_sync()
\r
539 function to specify that the output value of SDD0, or SDD1, or SDD2 should not
\r
542 #define SDD_NO_UPDATE 0xFFFFFFFF
\r
544 /*-------------------------------------------------------------------------*//**
\r
545 The ACE_set_sdd_value_sync() function is used to synchronize the update of
\r
546 multiple Sigma Delta DAC outputs.
\r
549 The sdd0_value parameter specifies the value that will be used to set the
\r
551 The define SDD_NO_UPDATE can be used to specify that the output value of
\r
552 SDD0 should not be modified.
\r
555 The sdd1_value parameter specifies the value that will be used to set the
\r
557 The define SDD_NO_UPDATE can be used to specify that the output value of
\r
558 SDD1 should not be modified.
\r
561 The sdd2_value parameter specifies the value that will be used to set the
\r
563 The define SDD_NO_UPDATE can be used to specify that the output value of
\r
564 SDD2 should not be modified.
\r
566 For example the code below will change the output value of SDD0 and SDD2 so
\r
567 that the voltage/current generate by SDD0 and ADD2 will change at the same
\r
568 time. This function call will not affect the output value of SDD1.
\r
570 uint32_t sdd0_value = 0x1234;
\r
571 uint32_t sdd2_value = 0x5678;
\r
572 ACE_set_sdd_value_sync( sdd0_value, SDD_NO_UPDATE, sdd2_value );
\r
576 void ACE_set_sdd_value_sync
\r
578 uint32_t sdd0_value,
\r
579 uint32_t sdd1_value,
\r
580 uint32_t sdd2_value
\r
585 /*==============================================================================
\r
586 ============ Reading Samples from post processing engine (PPE) ================
\r
587 =============================================================================*/
\r
588 /*=========================================================================*//**
\r
589 @defgroup group9 Reading Analog Input Channels Values and Properties
\r
590 The following functions are used to access analog input channels properties
\r
591 and sampled values.
\r
593 *//*=========================================================================*/
\r
595 /*-------------------------------------------------------------------------*//**
\r
596 This constant returned by the ACE_get_flag_channel(), ACE_get_channel_handle()
\r
597 and ACE_get_input_channel_handle() functions when the driver can
\92t find a
\r
598 valid handle for the ADC input channel.
\r
600 #define INVALID_CHANNEL_HANDLE NB_OF_ACE_CHANNEL_HANDLES
\r
602 /*-------------------------------------------------------------------------*//**
\r
603 The ACE_get_channel_handle() function returns the channel handle associated
\r
604 with an analog input channel name. The retrieved channel handle will be
\r
605 subsequently used as parameter to function ACE_get_ppe_sample() used to read
\r
606 the most recent post processed sample for the analog input identified through
\r
607 the channel/service name passed as argument to this function.
\r
609 @param p_sz_channel_name
\r
610 The p_sz_channel_name parameter is a zero-terminated string containing the
\r
611 name of the channel/service as entered in the ACE configurator.
\r
614 This function returns a channel handle. This channel handle is required as
\r
615 parameter to function ACE_get_ppe_sample().
\r
616 It will return INVALID_CHANNEL_HANDLE if the channel/service name is not
\r
620 uint16_t adc_result;
\r
621 ace_channel_handle_t at0;
\r
622 at0 = ACE_get_channel_handle("VoltageMonitorAT0");
\r
623 adc_result = ACE_get_ppe_sample( at0 );
\r
626 ace_channel_handle_t
\r
627 ACE_get_channel_handle
\r
629 const uint8_t * p_sz_channel_name
\r
632 /*-------------------------------------------------------------------------*//**
\r
633 The ACE_get_input_channel_handle() function returns the channel handle for
\r
634 the hardware analog input channel specified as parameter.
\r
637 The channel_id parameter identifies a hardware analog input of the ACE.
\r
640 This function returns a channel handle. This channel handle is required as
\r
641 parameter to other ACE driver functions dealing with analog inputs.
\r
642 It will return INVALID_CHANNEL_HANDLE if the channel ID passed as parameter
\r
645 ace_channel_handle_t
\r
646 ACE_get_input_channel_handle
\r
648 adc_channel_id_t channel_id
\r
651 /*-------------------------------------------------------------------------*//**
\r
652 The ACE_get_ppe_sample() function is used to read the most recent post
\r
653 processed sample for the analog input channel associated with the channel
\r
654 handle passed as parameter.
\r
656 @param channel_handle
\r
657 The channel_handle parameter identifies the analog input channel for which
\r
658 this function will return the most recent ADC conversion result adjusted for
\r
659 calibration and user provided coefficients as provided through the ACE
\r
660 configurator. The available channel handle values can be found in the
\r
661 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
662 channel handle value can also be retrieved through a call to
\r
663 ACE_get_channel_handle() when the name of the channel is known, or by
\r
664 iterating though all analog input channel using the ACE_get_first_channel()
\r
665 and ACE_get_next_channel().
\r
668 This function returns a 16 bit value representing the adjusted value of the
\r
669 ADC conversion result for the analog input channel identified by the channel
\r
670 handle passed as parameter. The return value is actually a 12, 10 or 8 bits
\r
671 number depending on the configuration of the ADC.
\r
674 uint16_t adc_result;
\r
675 ace_channel_handle_t at0;
\r
676 at0 = ACE_get_channel_handle("VoltageMonitorAT0");
\r
677 adc_result = ACE_get_ppe_sample( at0 );
\r
683 ace_channel_handle_t channel_handle
\r
686 /*-------------------------------------------------------------------------*//**
\r
687 The ACE_get_channel_name() function provides the name of the channel
\r
688 associated with the channel handle passed as parameter. The channel name is
\r
689 the name used in the ACE configurator software tool when adding a service to
\r
692 @param channel_handle
\r
693 The channel_handle parameter identifies the analog input channel for which
\r
694 we want to retrieve the channel name. The available channel handle values can
\r
695 be found in the ace_handles.h file located in the ./drivers_config/mss_ace
\r
696 subdirectory. The channel handle value can also be retrieved through a call
\r
697 to ACE_get_channel_handle() when the name of the channel is known, or by
\r
698 iterating though all analog input channel using the ACE_get_first_channel()
\r
699 and ACE_get_next_channel().
\r
702 This function returns a pointer to a zero-terminated string containing the
\r
703 name of the channel. It returns 0 if the channel handle passed as parameter
\r
706 const uint8_t * ACE_get_channel_name
\r
708 ace_channel_handle_t channel_handle
\r
711 /*-------------------------------------------------------------------------*//**
\r
712 The channel_type_t enumeration is used to identify the type of quantity
\r
713 measured by an analog input channel. It is typically used to figure out the
\r
714 type of conversion that must be applied to the ADC value generated from
\r
715 sampling a channel in order to yield real world units such millivolts,
\r
716 milliamps or degrees.
\r
725 /*-------------------------------------------------------------------------*//**
\r
726 The ACE_get_channel_type() function returns the type of input channel of the
\r
727 analog input channel identified by the channel handle passed as parameter.
\r
728 This function allows determining whether the quantity measured through the ADC
\r
729 is a voltage, current or temperature.
\r
731 @param channel_handle
\r
732 The channel_handle parameter identifies one of the analog input channels
\r
733 monitored by the ACE. The available channel handle values can be found in the
\r
734 ace_handles.h file located in the .\drivers_config\mss_ace subdirectory. The
\r
735 channel handle value can also be retrieved through a call to
\r
736 ACE_get_channel_handle() when the name of the channel is known, or by
\r
737 iterating though all analog input channel using the ACE_get_first_channel()
\r
738 and ACE_get_next_channel().
\r
741 This function returns one of the following values to report the type of
\r
742 quantity measure throught the channel:
\r
748 ACE_get_channel_type
\r
750 ace_channel_handle_t channel_handle
\r
753 /*-------------------------------------------------------------------------*//**
\r
754 The ACE_get_channel_count() function returns the total number of configured
\r
755 analog input channels. It is the number of channels available for use as
\r
756 opposed to the theorical number of physical channels supported by the device.
\r
759 The ACE_get_channel_count() function returns the total number of input
\r
760 channels that were configured in the ACE configurator.
\r
761 The ACE_get_channel_count() function returns 0 if no input channels were
\r
766 uint32_t nb_of_channels;
\r
767 ace_channel_handle_t current_channel;
\r
769 nb_of_channels = ACE_get_channel_count();
\r
770 current_channel = ACE_get_first_channel();
\r
772 for (inc = 0; inc < nb_of_channels; ++inc)
\r
774 adc_result = ACE_get_ppe_sample( current_channel );
\r
775 display_value( current_channel, adc_result );
\r
776 current_channel = ACE_get_next_channel( current_channel );
\r
781 ACE_get_channel_count
\r
786 /*-------------------------------------------------------------------------*//**
\r
787 The ACE_get_first_channel() function returns the channel handle of one of the
\r
788 channel controlled by the ACE. This function is used to start iterating though
\r
789 the list of analog input channels handled by the ACE.
\r
792 The ACE_get_first_channel() function returns the first channel handle found
\r
793 in the ACE driver's internal channel handles list or INVALID_CHANNEL_HANDLE
\r
794 if there are no channels defined in the ACE configuration.
\r
798 uint32_t nb_of_channels;
\r
799 ace_channel_handle_t current_channel;
\r
801 nb_of_channels = ACE_get_channel_count();
\r
802 current_channel = ACE_get_first_channel();
\r
804 for (inc = 0; inc < nb_of_channels; ++inc)
\r
806 adc_result = ACE_get_ppe_sample( current_channel );
\r
807 display_value( current_channel, adc_result );
\r
808 current_channel = ACE_get_next_channel( current_channel );
\r
812 ace_channel_handle_t
\r
813 ACE_get_first_channel
\r
818 /*-------------------------------------------------------------------------*//**
\r
819 The ACE_get_next_channel() returns the channel handle of the channel following
\r
820 the one passed as parameter. This function is used to iterate through the list
\r
821 of analog input channels handled by the ACE.
\r
823 @param channel_handle
\r
824 The channel_handle parameter identifies from which channel the driver should
\r
825 look in its channel handle list to return the next channel handle. The
\r
826 channel_handle parameter would typically be the channel handle returned by a
\r
827 call to ACE_get_first_channel() or a previous call to ACE_get_next_channel().
\r
829 The first call to ACE_get_next_channel() would typically use the
\r
830 channel_handle returned by a previous call to ACE_get_first_channel(). The
\r
831 second and subsequent calls to ACE_get_next_channel() would typically use
\r
832 the channel_handle returned by a previous call to ACE_get_next_channel().
\r
835 The ACE_get_next_channel() function returns the channel handle of the channel
\r
836 following the one passed as parameter or INVALID_CHANNEL_HANDLE if the end of
\r
837 the channels list has been reached.
\r
841 uint32_t nb_of_channels;
\r
842 ace_channel_handle_t current_channel;
\r
844 nb_of_channels = ACE_get_channel_count();
\r
845 current_channel = ACE_get_first_channel();
\r
847 for (inc = 0; inc < nb_of_channels; ++inc)
\r
849 adc_result = ACE_get_ppe_sample( current_channel );
\r
850 display_value( current_channel, adc_result );
\r
851 current_channel = ACE_get_next_channel( current_channel );
\r
855 ace_channel_handle_t
\r
856 ACE_get_next_channel
\r
858 ace_channel_handle_t channel_handle
\r
863 /*==============================================================================
\r
864 =============================== SSE Control ==================================
\r
865 =============================================================================*/
\r
866 /*=========================================================================*//**
\r
867 @defgroup group3 Sample Sequencing Engine Control
\r
868 Sample Sequencing Engine control.
\r
870 *//*=========================================================================*/
\r
872 /*-------------------------------------------------------------------------*//**
\r
873 The Sample Sequencing Engine control functions use a parameter of this type as
\r
874 a handle to identify the Sample Sequencing Engine (SSE) sequences configured
\r
875 using the ACE configurator. The ACE_get_sse_seq_handle() function retrieves the
\r
876 handle of the SSE sequence identified by the sequence name passed as parameter.
\r
877 Note: The ACE configurator generates ACE driver configuration files into the
\r
878 .\drivers_config\mss_ace folder of the firmware project. These files
\r
879 contain the details of the SSE sequence handles for your ACE configuration.
\r
880 The ACE driver automatically includes these files when the
\r
881 .\drivers_config\mss_ace folder is present in the firmware project.
\r
883 typedef uint16_t sse_sequence_handle_t;
\r
885 /*-------------------------------------------------------------------------*//**
\r
886 This constant is returned by the ACE_get_sse_seq_handle() function when the
\r
887 driver can
\92t find a valid handle for the Sample Sequencing Engine (SSE) sequence.
\r
889 #define INVALID_SSE_SEQ_HANDLE 0xFFFFu
\r
891 /*-------------------------------------------------------------------------*//**
\r
892 The ACE_get_sse_seq_handle() function retrieves the handle of the Sample
\r
893 Sequencing Engine sequence identified by the sequence name passed as parameter.
\r
894 The sequence handler can then be used as parameter to other SSE sequence control
\r
895 functions to identify the sequence to control.
\r
897 @param p_sz_sequence_name
\r
898 The p_sz_sequence_name parameter is a pointer to a zero-terminated string
\r
899 containing the name of the sampling sequence for which we want to retrieve
\r
903 The ACE_get_sse_seq_handle() function returns the handle used to identify
\r
904 the sequence passed as parameter with other ACE driver sampling sequence
\r
905 control functions. It returns INVALID_SSE_SEQ_HANDLE if the sequence name
\r
906 passed as parameter is not recognized.
\r
909 sse_sequence_handle_t sse_seq_handle;
\r
910 sse_seq_handle = ACE_get_sse_seq_handle("ProcedureA");
\r
911 if ( sse_seq_handle != INVALID_SSE_SEQ_HANDLE )
\r
913 ACE_load_sse( sse_seq_handle );
\r
914 ACE_start_sse( sse_seq_handle );
\r
918 sse_sequence_handle_t
\r
919 ACE_get_sse_seq_handle
\r
921 const uint8_t * p_sz_sequence_name
\r
924 /*-------------------------------------------------------------------------*//**
\r
925 The ACE_load_sse() function loads the ACE Sample Sequencing Engine (SSE) RAM
\r
926 with the microcode implementing the sampling sequence identified by the SSE
\r
927 sequence handler passed as parameter.
\r
930 The sequence parameter is the SSE sequence handler identifying the sampling
\r
931 sequence to load into the ACE SSE. The value for this handler is retrieved
\r
932 through a call to function ACE_get_sse_seq_handle().
\r
936 sse_sequence_handle_t sequence
\r
939 /*-------------------------------------------------------------------------*//**
\r
940 The ACE_start_sse() function causes the Sampling Sequence Engine (SSE) to start
\r
941 executing the sequence identified by the sequence handler passed as parameter.
\r
942 It causes the initiailization part of the sampling sequence to be executed
\r
943 before the loop part of the sequence is started.
\r
944 You must ensure that the sampling sequence has been loaded into the ACE's SSE
\r
945 before calling this function.
\r
948 The sequence parameter is the SSE sequence handler identifying the sampling
\r
949 sequence to load into the ACE SSE. The value for this handler is retrieved
\r
950 through a call to function ACE_get_sse_seq_handle().
\r
954 sse_sequence_handle_t sequence
\r
957 /*-------------------------------------------------------------------------*//**
\r
958 The ACE_restart_sse() function restarts the loop part of the sampling sequence
\r
959 loaded into the ACE's Sampling Sequence Engine (SSE). The sampling sequence
\r
960 will be restarted from the beginning of the sequence but omiting the
\r
961 intialization phase of the sequence.
\r
962 This function would typically be called after stopping the sampling sequence
\r
963 using the ACE_stop_see() function or with non-repeating sequences.
\r
966 The sequence parameter is the SSE sequence handler identifying the sampling
\r
967 sequence to load into the ACE SSE. The value for this handler is retrieved
\r
968 through a call to function ACE_get_sse_seq_handle().
\r
970 void ACE_restart_sse
\r
972 sse_sequence_handle_t sequence
\r
975 /*-------------------------------------------------------------------------*//**
\r
976 The ACE_stop_sse() function stops execution of the Sample Sequencing Engine
\r
977 (SSE) sequence indentified by the sequence handle passed as parameter.
\r
980 The sequence parameter is the SSE sequence handle identifying the sampling
\r
981 sequence to load into the ACE SSE. The value for this handler is retrieved
\r
982 through a call to function ACE_get_sse_seq_handle().
\r
986 sse_sequence_handle_t sequence
\r
989 /*-------------------------------------------------------------------------*//**
\r
990 The ACE_resume_sse() function causes the Sampling Sequencing Engine (SSE)
\r
991 sampling sequence identified by the sequence handle passed as parameter to
\r
992 resume execution. This function is typically used to restart execution of
\r
993 a sequence at the point where it was stopped through a call to ACE_stop_sse().
\r
996 The sequence parameter is the SSE sequence handler identifying the sampling
\r
997 sequence to load into the ACE SSE. The value for this handler is retrieved
\r
998 through a call to function ACE_get_sse_seq_handle().
\r
1000 void ACE_resume_sse
\r
1002 sse_sequence_handle_t sequence
\r
1005 /*-------------------------------------------------------------------------*//**
\r
1006 The ACE_clear_sample_pipeline() function clears the ACE hardware of samples
\r
1007 being processed. It clear the various stages involved in the production of
\r
1008 post processed samples within the ACE hardware. It is intended for use when
\r
1009 switching between sampling sequences and using peripheral DMA. It avoids
\r
1010 receiving stale samples generated as a result of a previous sampling sequence.
\r
1012 The example below shows how this function can be used to ensure that no sample
\r
1013 generated as a result of sampling sequence sequence_a will be generated once
\r
1014 sampling sequence_b is started. Please note that it is important to stop the
\r
1015 SSE using function ACE_stop_sse() before calling ACE_clear_sample_pipeline()
\r
1016 to ensure sequence_a is not restarted after the sample pipeline is cleared.
\r
1018 ACE_stop_sse(sequence_a);
\r
1019 ACE_clear_sample_pipeline();
\r
1020 ACE_start_sse(sequence_b);
\r
1023 The example below shows how to ensure that the first sample read through PDMA
\r
1024 will be from the first channel in the sampling sequence.
\r
1026 ACE_stop_sse(sequence_a);
\r
1027 ACE_clear_sample_pipeline();
\r
1028 ACE_restart_sse(sequence_a);
\r
1032 PDMA_ACE_PPE_DATAOUT,
\r
1033 (uint32_t)g_samples_buffer[g_pdma_buffer_idx],
\r
1034 SAMPLES_BUFFER_SIZE
\r
1038 void ACE_clear_sample_pipeline(void);
\r
1041 /*==============================================================================
\r
1042 ======================== SSE Interrupts Control ===============================
\r
1043 =============================================================================*/
\r
1044 /*=========================================================================*//**
\r
1045 @defgroup group4 Sample Sequencing Engine Interrupts Control
\r
1046 The following functions are used to control interrupts generated from the
\r
1047 ACE's Sample Sequencing Engine. These interrupts would typically be used to
\r
1048 detect when valid data is available from the ADCs controlled by the SSE or to
\r
1049 detect the complete or partial completion of the sampling sequence through the
\r
1050 insertion of SSE program counter general purpose interrupt assertion as part
\r
1053 *//*=========================================================================*/
\r
1055 /*-------------------------------------------------------------------------*//**
\r
1056 The sse_irq_id_t enumeration is used to identify the Sample Sequencing Engine
\r
1057 (SSE) interrupt sources to the SSE interrupt control functions.
\r
1073 ADC0_DATAVALID = 12,
\r
1074 ADC1_DATAVALID = 13,
\r
1075 ADC2_DATAVALID = 14,
\r
1076 ADC0_CALIBRATION_COMPLETE = 15,
\r
1077 ADC1_CALIBRATION_COMPLETE = 16,
\r
1078 ADC2_CALIBRATION_COMPLETE = 17,
\r
1079 ADC0_CALIBRATION_START = 18,
\r
1080 ADC1_CALIBRATION_START = 19,
\r
1081 ADC2_CALIBRATION_START = 20,
\r
1082 NB_OF_SSE_FLAG_IRQS = 21
\r
1085 /*-------------------------------------------------------------------------*//**
\r
1086 The ACE_enable_sse_irq() function enables the Sample Sequencing Engine (SSE)
\r
1087 interrupt source specified as parameter to generate interrupts.
\r
1090 The sse_irq_id parameter identifies the SSE interrupt source controlled by
\r
1093 void ACE_enable_sse_irq
\r
1095 sse_irq_id_t sse_irq_id
\r
1098 /*-------------------------------------------------------------------------*//**
\r
1099 The ACE_disable_sse_irq() function disables the Sample Sequencing Engine
\r
1100 (SSE) interrupt source specified as parameter from generating interrupts.
\r
1103 The sse_irq_id parameter identifies the SSE interrupt source controlled by
\r
1106 void ACE_disable_sse_irq
\r
1108 sse_irq_id_t sse_irq_id
\r
1111 /*-------------------------------------------------------------------------*//**
\r
1112 The ACE_clear_sse_irq() function clears the Sampling Sequencing Engine (SSE)
\r
1113 interrupt specified as parameter.
\r
1116 The sse_irq_id parameter identifies the SSE interrupt source controlled by
\r
1119 void ACE_clear_sse_irq
\r
1121 sse_irq_id_t sse_irq_id
\r
1125 /*==============================================================================
\r
1126 ============================ Comparators Control ==============================
\r
1127 =============================================================================*/
\r
1128 /*=========================================================================*//**
\r
1129 @defgroup group5 Comparators Control
\r
1130 The following functions are used to control the analog comparators included
\r
1131 in the SmartFusion analog block.
\r
1132 The comparator configuration functions can be used to directly configure the
\r
1133 comparators. Their use is only required when the ACE is not configured using
\r
1134 the ACE configurator software tool.
\r
1135 The comparator interrupt control functions are used regardless of the way the
\r
1136 ACE was configured to enable, disable and clear interrupts generated when the
\r
1137 positive input of a comparator rises above or falls below the negative input.
\r
1139 *//*=========================================================================*/
\r
1141 /*-------------------------------------------------------------------------*//**
\r
1142 The comparator_id_t enumeration is used by the comparator control functions
\r
1143 to identify the analog comparators included in the SmartFusion analog block.
\r
1147 CMP0 = 0, /*!< Analog module 0, Quad 0, CMB comparator */
\r
1148 CMP1 = 1, /*!< Analog module 0, Quad 0, TMB comparator */
\r
1149 CMP2 = 2, /*!< Analog module 0, Quad 1, CMB comparator */
\r
1150 CMP3 = 3, /*!< Analog module 0, Quad 1, TMB comparator */
\r
1151 CMP4 = 4, /*!< Analog module 1, Quad 0, CMB comparator */
\r
1152 CMP5 = 5, /*!< Analog module 1, Quad 0, TMB comparator */
\r
1153 CMP6 = 6, /*!< Analog module 1, Quad 1, CMB comparator */
\r
1154 CMP7 = 7, /*!< Analog module 1, Quad 1, TMB comparator */
\r
1155 CMP8 = 8, /*!< Analog module 2, Quad 0, CMB comparator */
\r
1156 CMP9 = 9, /*!< Analog module 2, Quad 0, TMB comparator */
\r
1157 CMP10 = 10, /*!< Analog module 2, Quad 1, CMB comparator */
\r
1158 CMP11 = 11, /*!< Analog module 2, Quad 1, TMB comparator */
\r
1159 NB_OF_COMPARATORS = 12
\r
1160 } comparator_id_t;
\r
1162 /*-------------------------------------------------------------------------*//**
\r
1163 The comp_hysteresis_t enumeration is used by the ACE_set_comp_hysteresis()
\r
1164 function to set the hysteresis of the analog comparators included in the
\r
1165 SmartFusion analog block. This enumeration provides the allowed values of the
\r
1166 hysteresis parameter of the ACE_set_comp_hysteresis() function.
\r
1170 NO_HYSTERESIS = 0,
\r
1171 HYSTERESIS_10_MV = 1,
\r
1172 HYSTERESIS_30_MV = 2,
\r
1173 HYSTERESIS_100_MV = 3,
\r
1174 NB_OF_HYSTERESIS = 4
\r
1175 } comp_hysteresis_t ;
\r
1177 /*-------------------------------------------------------------------------*//**
\r
1178 The comp_reference_t enumeration is used by the ACE_set_comp_reference()
\r
1179 function to select the reference input of the odd numbered analog comparators
\r
1180 included in the SmartFusion analog block. This enumeration provides the allowed
\r
1181 values of the reference parameter of the ACE_set_comp_reference () function.
\r
1185 SDD0_COMP_REF = 0,
\r
1186 SDD1_COMP_REF = 1,
\r
1187 SDD2_COMP_REF = 2,
\r
1188 ADC_IN_COMP_REF = 3,
\r
1189 NB_OF_COMP_REF = 4
\r
1190 } comp_reference_t;
\r
1192 /*-------------------------------------------------------------------------*//**
\r
1193 The ACE_set_comp_reference() function is used to select the reference input
\r
1194 of a temperature monitor block comparator. The reference input of a temperature
\r
1195 monitor can be an ADC direct input or one of the SDD's output.
\r
1198 The comp_id parameter specifies the comparator for which to select the
\r
1199 reference input. Since only temperature monitor block comparators have a
\r
1200 selectable reference input, allowed values are:
\r
1209 The reference parameter specify the signal that will be used as reference
\r
1210 by the comparator. Allowed values are:
\r
1216 void ACE_set_comp_reference
\r
1218 comparator_id_t comp_id,
\r
1219 comp_reference_t reference
\r
1222 /*-------------------------------------------------------------------------*//**
\r
1223 The ACE_set_comp_hysteresis() function is used to set the hysteresis of a
\r
1224 comparator. There are four possible hystereris settings: no hysteresis,
\r
1225 +/-10mV, +/-30mV or +/-100mV.
\r
1228 The comp_id parameter specifies the comparator for which this function will
\r
1229 set the hyteresis.
\r
1232 The hysteresis parameter specifies the hysteresis that will be applied to
\r
1233 the comparator's input. Allowed values are:
\r
1235 - HYSTERESIS_10_MV
\r
1236 - HYSTERESIS_30_MV
\r
1237 - HYSTERESIS_100_MV
\r
1240 void ACE_set_comp_hysteresis
\r
1242 comparator_id_t comp_id,
\r
1243 comp_hysteresis_t hysteresis
\r
1246 /*-------------------------------------------------------------------------*//**
\r
1247 The ACE_enable_comp() function is used to enable the comparator specified as
\r
1251 The comp_id parameter specifies which comparator will be enabled by a call
\r
1254 void ACE_enable_comp
\r
1256 comparator_id_t comp_id
\r
1259 /*-------------------------------------------------------------------------*//**
\r
1260 The ACE_disable_comp() function is used to disable the comparator specified as
\r
1264 The comp_id parameter specifies which comparator will be disabled by a call
\r
1267 void ACE_disable_comp
\r
1269 comparator_id_t comp_id
\r
1272 /*-------------------------------------------------------------------------*//**
\r
1273 The ACE_enable_comp_rise_irq() function is used to enable interrupts to be
\r
1274 generated when the positive input of the comparator specified as parameter
\r
1275 rises above the negative input of the comparator.
\r
1276 The function prototypes for the comparator rise interrupt service routines are:
\r
1277 - void ACE_Comp0_Rise_IRQHandler( void );
\r
1278 - void ACE_Comp1_Rise_IRQHandler( void );
\r
1279 - void ACE_Comp2_Rise_IRQHandler( void );
\r
1280 - void ACE_Comp3_Rise_IRQHandler( void );
\r
1281 - void ACE_Comp4_Rise_IRQHandler( void );
\r
1282 - void ACE_Comp5_Rise_IRQHandler( void );
\r
1283 - void ACE_Comp6_Rise_IRQHandler( void );
\r
1284 - void ACE_Comp7_Rise_IRQHandler( void );
\r
1285 - void ACE_Comp8_Rise_IRQHandler( void );
\r
1286 - void ACE_Comp9_Rise_IRQHandler( void );
\r
1287 - void ACE_Comp10_Rise_IRQHandler( void );
\r
1288 - void ACE_Comp11_Rise_IRQHandler( void );
\r
1291 The comp_id parameter specifies which comparator will be enabled to generate
\r
1292 rising interrupts.
\r
1294 void ACE_enable_comp_rise_irq
\r
1296 comparator_id_t comp_id
\r
1299 /*-------------------------------------------------------------------------*//**
\r
1300 The ACE_disable_comp_rise_irq() function is used to disable interrupts from
\r
1301 being generated when the positive input of the comparator specified as parameter
\r
1302 rises above the negative input of the comparator.
\r
1305 The comp_id parameter specifies which comparator will be disabled from
\r
1306 generating rising interrupts.
\r
1308 void ACE_disable_comp_rise_irq
\r
1310 comparator_id_t comp_id
\r
1313 /*-------------------------------------------------------------------------*//**
\r
1314 The ACE_clear_comp_rise_irq() function is used to clear rise interrupts. This
\r
1315 function is typically called as part of the rise interrupt service routine.
\r
1318 The comp_id parameter specifies the comparator for which to clear the rise
\r
1323 void ACE_Comp1_Rise_IRQHandler( void )
\r
1325 process_rise_irq();
\r
1326 ACE_clear_comp_rise_irq( CMP1 );
\r
1327 NVIC_ClearPendingIRQ( ACE_Comp1_Rise_IRQn );
\r
1331 void ACE_clear_comp_rise_irq
\r
1333 comparator_id_t comp_id
\r
1336 /*-------------------------------------------------------------------------*//**
\r
1337 The ACE_enable_comp_fall_irq() function is used to enable interrupts to be
\r
1338 generated when the positive input of the comparator specified as parameter
\r
1339 falls below the negative input of the comparator.
\r
1340 The function prototypes for the comparator fall interrupt service routines are:
\r
1341 - void ACE_Comp0_Fall_IRQHandler( void );
\r
1342 - void ACE_Comp1_Fall_IRQHandler( void );
\r
1343 - void ACE_Comp2_Fall_IRQHandler( void );
\r
1344 - void ACE_Comp3_Fall_IRQHandler( void );
\r
1345 - void ACE_Comp4_Fall_IRQHandler( void );
\r
1346 - void ACE_Comp5_Fall_IRQHandler( void );
\r
1347 - void ACE_Comp6_Fall_IRQHandler( void );
\r
1348 - void ACE_Comp7_Fall_IRQHandler( void );
\r
1349 - void ACE_Comp8_Fall_IRQHandler( void );
\r
1350 - void ACE_Comp9_Fall_IRQHandler( void );
\r
1351 - void ACE_Comp10_Fall_IRQHandler( void );
\r
1352 - void ACE_Comp11_Fall_IRQHandler( void );
\r
1355 The comp_id parameter specifies which comparator will be enabled to generate
\r
1358 void ACE_enable_comp_fall_irq
\r
1360 comparator_id_t comp_id
\r
1363 /*-------------------------------------------------------------------------*//**
\r
1364 The ACE_disable_comp_fall_irq() function is used to disable interrupts from
\r
1365 being generated when the positive input of the comparator specified as parameter
\r
1366 falls below the negative input of the comparator.
\r
1369 The comp_id parameter specifies which comparator will be disabled from
\r
1370 generating fall interrupts.
\r
1372 void ACE_disable_comp_fall_irq
\r
1374 comparator_id_t comp_id
\r
1377 /*-------------------------------------------------------------------------*//**
\r
1378 The ACE_clear_comp_fall_irq() function is used to clear fall interrupts. This
\r
1379 function is typically called as part of the fall interrupt service routine.
\r
1382 The comp_id parameter specifies the comparator for which to clear the fall
\r
1387 void ACE_Comp1_Fall_IRQHandler( void )
\r
1389 process_fall_irq();
\r
1390 ACE_clear_comp_fall_irq( CMP1 );
\r
1391 NVIC_ClearPendingIRQ( ACE_Comp1_Fall_IRQn );
\r
1395 void ACE_clear_comp_fall_irq
\r
1397 comparator_id_t comp_id
\r
1400 /*-------------------------------------------------------------------------*//**
\r
1401 The ACE_get_comp_status() function returns the current comparator interrupt
\r
1402 status. It returns a 32 bit value indicating which comparators experienced a
\r
1403 fall and/or rise event. These status bits can be cleared using the
\r
1404 ACE_clear_comp_rise_irq() and ACE_clear_comp_fall_irq() functions.
\r
1407 The return value is a 32 bit numnber where bits 0 to 11 indicate which
\r
1408 comparator experienced a fall event and bits 21 to 23 indicate which
\r
1409 comparator experienced a rise event.
\r
1411 uint32_t ACE_get_comp_status( void );
\r
1415 /*==============================================================================
\r
1416 ========================== Controlling Thresholds =============================
\r
1417 =============================================================================*/
\r
1418 /*=========================================================================*//**
\r
1419 @defgroup group8 Controlling Flags Thresholds
\r
1420 The following functions are used to dynamically control Post Processing Engine
\r
1421 (PPE) flags threshholds.
\r
1423 *//*=========================================================================*/
\r
1425 /*-------------------------------------------------------------------------*//**
\r
1426 The ACE_is_hysteresis_flag() function indicates if an hysteresis is applied
\r
1427 to the analog input sample value when determining the state of the flag
\r
1428 identified as parameter.
\r
1430 @param flag_handle
\r
1431 The flag_handle parameter identifies one of the flags generated based on the
\r
1432 value of an analog input channel. The available flag handle values can be
\r
1433 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1434 subdirectory. The flag handle value can also be retrieved through a call to
\r
1435 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1436 though all flags associated with an analog input channel using the
\r
1437 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1440 This function returns the value one if a hysteresis is applied to the channel
\r
1441 sample values as part of determining the state of the flag identified as
\r
1442 parameter. It returns zero if no hysteresis is applied.
\r
1444 uint32_t ACE_is_hysteresis_flag
\r
1446 ace_flag_handle_t flag_handle
\r
1449 /*-------------------------------------------------------------------------*//**
\r
1450 The ACE_is_under_flag() function indicates whether a flag is triggered when the
\r
1451 monitored analog input falls below the flag's threshold level or above the
\r
1452 flag's threshold level.
\r
1454 @param flag_handle
\r
1455 The flag_handle parameter identifies one of the flags generated based on the
\r
1456 value of an analog input channel. The available flag handle values can be
\r
1457 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1458 subdirectory. The flag handle value can also be retrieved through a call to
\r
1459 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1460 though all flags associated with an analog input channel using the
\r
1461 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1464 This function returns the value one if the flag identified as parameter
\r
1465 triggers as a result of the monitored input falling below the flag's
\r
1467 It returns zero if the flag triggers as a result of the monitored input
\r
1468 exceeding the flag's threshold value.
\r
1470 uint32_t ACE_is_under_flag
\r
1472 ace_flag_handle_t flag_handle
\r
1475 /*-------------------------------------------------------------------------*//**
\r
1476 The ACE_set_flag_threshold() function is used to adjust the threshold for a
\r
1477 specific post processing engine generated flag. The flag is identified through
\r
1478 the name selected in the ACE configurator software tool.
\r
1479 This function will set a new flag
\92s threshold value while preserving the
\r
1480 hysteresis specified at configuration time or through a call to
\r
1481 ACE_set_flag_hysteresis(). For example, requesting a 1 volt threshold for an
\r
1482 over flag configured with a 100 millivolts hysteresis will result in the flag
\r
1483 being asserted when the voltage reaches 1.1 volts and deasserted when the
\r
1484 voltage falls below 0.9 volt.
\r
1486 @param flag_handle
\r
1487 The flag_handle parameter identifies one of the flags generated based on the
\r
1488 value of an analog input channel. The available flag handle values can be
\r
1489 found in the ace_handles.h file located in the ./drivers_config/mss_ace
\r
1490 subdirectory. The flag handle value can also be retrieved through a call to
\r
1491 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1492 though all flags associated with an analog input channel using the
\r
1493 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1495 @param new_threshold
\r
1496 The new_threshold parameter specifies the new threshold level that must be
\r
1497 reached in order for the flag to be raised. The value of this parameter is
\r
1498 the sample value resulting from a post processing engine conversion of the
\r
1499 desired analog input threshold level.
\r
1502 The function below sets the threshold of the flag specified as parameter to
\r
1505 void set_threshold_to_1V
\r
1507 ace_flag_handle_t flag_handle
\r
1510 uint16_t new_threshold;
\r
1511 ace_channel_handle_t channel_handle;
\r
1513 channel_handle = ACE_get_flag_channel(flag_handle);
\r
1514 new_threshold = ACE_convert_from_mV(channel_handle, 1000);
\r
1515 ACE_set_flag_threshold(flag_handle, new_threshold);
\r
1519 void ACE_set_flag_threshold
\r
1521 ace_flag_handle_t flag_handle,
\r
1522 uint16_t new_threshold
\r
1525 /*-------------------------------------------------------------------------*//**
\r
1526 The ACE_set_flag_hysteresis() function modifies the hysteresis applied to the
\r
1527 analog input channel sample values used to generate the flag specified as
\r
1530 @param flag_handle
\r
1531 The flag_handle parameter identifies one of the flags generated based on the
\r
1532 value of an analog input channel. The available flag handle values can be
\r
1533 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1534 subdirectory. The flag handle value can also be retrieved through a call to
\r
1535 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1536 though all flags associated with an analog input channel using the
\r
1537 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1539 @param adc_hysteresis
\r
1540 The adc_hysteresis parameter is the value to add and subtract to the
\r
1541 threshold value to obtain the hysteresis high and low limits triggering flag
\r
1542 assertion and deassertion. The adc_hysteresis parameter is a PPE conversion
\r
1546 The example below demonstrates the use of the ACE_set_flag_hysteresis()
\r
1547 function to set a 100mV hysteresis on the OVER_1V flag of the VoltageMonitor
\r
1548 input channel. VoltageMonitor and OVER_1V are names selected in the ACE
\r
1549 configurator for one of the analog inputs and one of the flags associated
\r
1551 The method used to compute the adc_hysteresis value will work for all
\r
1552 input types including ABPS inputs where zero Volts is not equivalent to a
\r
1553 PPE sample value of zero.
\r
1556 ace_channel_handle_t channel_handle;
\r
1557 ace_flag_handle_t flag_handle;
\r
1558 uint16_t adc_hysteresis;
\r
1559 uint16_t upper_limit;
\r
1560 uint16_t lower_limit;
\r
1562 channel_handle = VoltageMonitor;
\r
1563 flag_handle = VoltageMonitor_OVER_1V;
\r
1565 upper_limit = ACE_convert_from_mV(channel_handle, 100);
\r
1566 lower_limit = ACE_convert_from_mV(channel_handle, 0);
\r
1568 if (upper_limit > lower_limit)
\r
1570 adc_hysteresis = upper_limit - lower_limit;
\r
1574 adc_hysteresis = lower_limit - upper_limit;
\r
1577 ACE_set_flag_hysteresis(flag_handle, adc_hysteresis);
\r
1581 ACE_set_flag_hysteresis
\r
1583 ace_flag_handle_t flag_handle,
\r
1584 uint16_t adc_hysteresis
\r
1587 /*-------------------------------------------------------------------------*//**
\r
1588 The ACE_set_flag_assertion() function sets the PPE sample value that must be
\r
1589 reached in order for the flag specified as parameter to become asserted. It is
\r
1590 used in conjunction with the ACE_set_flag_deassertion() function as an
\r
1591 alternative to the ACE_set_flag_threshold() and ACE_set_flag_hysteresis()
\r
1592 functions to set the hysteresis window of an hysteresis flag.
\r
1593 The ACE_set_flag_assertion() and ACE_set_flag_deassertion() functions are
\r
1594 intended to be used where the threshold value is not centered within the
\r
1595 hysteresis window. They allow specifying the actual threshold values at which
\r
1596 the flag will be asserted and deasserted.
\r
1598 @param flag_handle
\r
1599 The flag_handle parameter identifies one of the flags generated based on the
\r
1600 value of an analog input channel. The available flag handle values can be
\r
1601 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1602 subdirectory. The flag handle value can also be retrieved through a call to
\r
1603 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1604 though all flags associated with an analog input channel using the
\r
1605 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1607 @param assertion_value
\r
1608 The assertion_value parameter is the Post Processing Engine sample value that
\r
1609 must be reached for the flag, identified through the flag_handle parameter,
\r
1610 to become asserted. The PPE sample value is always a 12 bits sample value
\r
1611 regardless of the configuration of the ADC used to sample the input channel.
\r
1613 void ACE_set_flag_assertion
\r
1615 ace_flag_handle_t flag_handle,
\r
1616 uint16_t assertion_value
\r
1619 /*-------------------------------------------------------------------------*//**
\r
1620 The ACE_set_flag_deassertion() function sets the PPE sample value that must be
\r
1621 reached in order for the flag specified as parameter to become deasserted. It
\r
1622 is used in conjunction with the ACE_set_flag_assertion() function as an
\r
1623 alternative to the ACE_set_flag_threshold() and ACE_set_flag_hysteresis()
\r
1624 functions to set the hysteresis window of an hysteresis flag.
\r
1625 The ACE_set_flag_assertion() and ACE_set_flag_deassertion() functions are
\r
1626 intended to be used where the threshold value is not centered within the
\r
1627 hysteresis window. They allow specifying the actual threshold values at which
\r
1628 the flag will be asserted and deasserted.
\r
1630 @param flag_handle
\r
1631 The flag_handle parameter identifies one of the flags generated based on the
\r
1632 value of an analog input channel. The available flag handle values can be
\r
1633 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1634 subdirectory. The flag handle value can also be retrieved through a call to
\r
1635 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1636 though all flags associated with an analog input channel using the
\r
1637 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1639 @param assertion_value
\r
1640 The assertion_value parameter is the Post Processing Engine sample value
\r
1641 that must be reached for the flag, identified through the flag_handle
\r
1642 parameter, to become de-asserted. The PPE sample value is always a 12 bits
\r
1643 sample value regardless of the configuration of the ADC used to sample the
\r
1646 void ACE_set_flag_deassertion
\r
1648 ace_flag_handle_t flag_handle,
\r
1649 uint16_t assertion_value
\r
1652 /*-------------------------------------------------------------------------*//**
\r
1653 The ACE_set_channel_hysteresis() function sets the hysteresis applied to
\r
1654 analog input channel sample values when generating flags. It sets the
\r
1655 hysteresis for all flags generated based on the value of the analog input
\r
1656 channel identified by the channel handle passed as first parameter.
\r
1658 @param channel_handle
\r
1659 The channel_handle parameter identifies one of the analog input channels
\r
1660 monitored by the ACE. The available channel handle values can be found in
\r
1661 the ace_handles.h file located in the .\drivers_config\mss_ace subdirectory.
\r
1662 The channel handle value can also be retrieved through a call to
\r
1663 ACE_get_channel_handle() when the name of the channel is known, or by
\r
1664 iterating though all analog input channel using the ACE_get_first_channel()
\r
1665 and ACE_get_next_channel().
\r
1667 @param adc_hysteresis
\r
1668 The adc_hysteresis parameter is the value to add and subtract to the
\r
1669 threshold value to obtain the hysteresis high and low limits triggering flag
\r
1670 assertion and deassertion. The adc_hysteresis parameter is a PPE conversion
\r
1674 ACE_set_channel_hysteresis
\r
1676 ace_channel_handle_t channel_handle,
\r
1677 uint16_t adc_hysteresis
\r
1682 /*-------------------------------------------------------------------------*//**
\r
1686 /*==============================================================================
\r
1687 ================================== Flags ======================================
\r
1688 =============================================================================*/
\r
1689 /*=========================================================================*//**
\r
1690 @defgroup group6 Post Processing Engine Flags
\r
1691 The following functions are used to control interrupts generated by the ACE's
\r
1692 Post Processing Engine (PPE) when monitored inputs rise above or fall below
\r
1693 thresholds specified in the ACE configurator software tool.
\r
1695 *//*=========================================================================*/
\r
1697 /*-------------------------------------------------------------------------*//**
\r
1698 These constant definitions are the return values of the ACE_get_flag_status()
\r
1699 function. They specify the status of the Post Processing Engine (PPE) flag.
\r
1701 #define UNKNOWN_FLAG (int32_t)(-1)
\r
1702 #define FLAG_ASSERTED (int32_t)1
\r
1703 #define FLAG_NOT_ASSERTED (int32_t)0
\r
1705 /*-------------------------------------------------------------------------*//**
\r
1706 This constant is returned by the ACE_get_flag_handle function when the driver
\r
1707 can
\92t find a valid handle for the Post Processing Engine (PPE) flag.
\r
1709 #define INVALID_FLAG_HANDLE NB_OF_ACE_FLAG_HANDLES
\r
1711 /*-------------------------------------------------------------------------*//**
\r
1712 The ACE_get_flag_handle() function returns the handle of the flag identified
\r
1713 by the flag name passed as parameter. The flag handle obtained through this
\r
1714 function is then used as parameter to other flag control functions to identify
\r
1715 which flag is to be controlled by the called function.
\r
1717 @param p_sz_full_flag_name
\r
1718 The p_sz_full_flag_name parameter is a pointer to a zero-terminated string
\r
1719 holding the name of the flag as specified in the ACE configurator. The full
\r
1720 name of a flag contains both the name of the monitored input channel and the
\r
1721 name of the flag generated based the level of that input separated by ":".
\r
1722 For example, the full name for the flag called "CriticalOver" raised when
\r
1723 the input channel called "MainSupply" reaches a critical level would be
\r
1724 named "MainSupply:CriticalOver".
\r
1727 The ACE_get_flag_handle() returns the flag handle associated with the flag
\r
1728 name passed as parameter. It returns INVALID_FLAG_HANDLE when the flag name
\r
1729 is invalid and not recognized by the ACE driver.
\r
1732 ACE_get_flag_handle
\r
1734 const uint8_t * p_sz_full_flag_name
\r
1737 /*-------------------------------------------------------------------------*//**
\r
1738 The ACE_get_flag_status() function returns the current status of the flag
\r
1739 specified as parameter. The flag is identified through the name specified in
\r
1740 the ACE configurator when the flag was created.
\r
1742 @param flag_handle
\r
1743 The flag_handle parameter identifies one of the flags generated based on the
\r
1744 value of an analog input channel. The available flag handle values can be
\r
1745 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1746 subdirectory. The flag handle value can also be retrieved through a call to
\r
1747 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1748 though all flags associated with an analog input channel using the
\r
1749 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1752 The ACE_get_flag_status() function returns one of the following values
\r
1753 depending on the current status of the flag:
\r
1754 - FLAG_ASSERTED if the flag is raised/asserted.
\r
1755 - FLAG_NOT_ASSERTED if the flag is not asserted.
\r
1756 - UNKNOWN_FLAG if the flag name is not recognized by the driver.
\r
1759 ACE_get_flag_status
\r
1761 ace_flag_handle_t flag_handle
\r
1764 /*-------------------------------------------------------------------------*//**
\r
1765 The ACE_enable_channel_flags_irq() function enables all flags generated based
\r
1766 on the value of the analog input channel passed as parameter to generate
\r
1767 interrupts. Flags used to detect that thresholds are crossed by the value
\r
1768 sampled on the analog input channel identified as parameter are enabled to
\r
1769 generate interrupts by this function. It enables flag interrupts both at the
\r
1770 ACE PEE flag and Cortex-M3 interrupt controller levels.
\r
1772 @param channel_handle
\r
1773 The channel_handle parameter identifies one of the analog input channels
\r
1774 monitored by the ACE. The available channel handle values can be found in the
\r
1775 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
1776 channel handle value can also be retrieved through a call to
\r
1777 ACE_get_channel_handle() when the name of the channel is known, or by
\r
1778 iterating though all analog input channel using the ACE_get_first_channel()
\r
1779 and ACE_get_next_channel().
\r
1781 void ACE_enable_channel_flags_irq
\r
1783 ace_channel_handle_t channel_handle
\r
1786 /*-------------------------------------------------------------------------*//**
\r
1787 The ACE_disable_channel_flags_irq() function disables all flags generated
\r
1788 based on the value of the analog input channel passed as parameter to generate
\r
1789 interrupts. Flags used to detect that thresholds are crossed by the value
\r
1790 sampled on the analog input channel identified as parameter are disabled from
\r
1791 generating interrupts by this function. The interrupt is only disabled at the
\r
1792 ACE PPE flag level in order to avoid disabling other cahnnel's flag interrupts
\r
1793 which may happen to use the same ACE threshold interrupt line.
\r
1795 @param channel_handle
\r
1796 The channel_handle parameter identifies one of the analog input channels
\r
1797 monitored by the ACE. The available channel handle values can be found in the
\r
1798 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
1799 channel handle value can also be retrieved through a call to
\r
1800 ACE_get_channel_handle() when the name of the channel is known, or by
\r
1801 iterating though all analog input channel using the ACE_get_first_channel()
\r
1802 and ACE_get_next_channel().
\r
1804 void ACE_disable_channel_flags_irq
\r
1806 ace_channel_handle_t channel_handle
\r
1809 /*-------------------------------------------------------------------------*//**
\r
1810 The ACE_clear_channel_flags_irq() function clears all interrupts generated by
\r
1811 flags associated with the analog input channel passed as parameter. Interrupt
\r
1812 generated by flags used to detect that thresholds are crossed by the value
\r
1813 sampled on the analog input channel identified as parameter are cleared by
\r
1814 this function. This function would typically be used before enabling the flag
\r
1815 interrupts in order to ignore past events.
\r
1817 @param channel_handle
\r
1818 The channel_handle parameter identifies one of the analog input channels
\r
1819 monitored by the ACE. The available channel handle values can be found in the
\r
1820 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
1821 channel handle value can also be retrieved through a call to
\r
1822 ACE_get_channel_handle() when the name of the channel is known, or by
\r
1823 iterating though all analog input channel using the ACE_get_first_channel()
\r
1824 and ACE_get_next_channel().
\r
1826 void ACE_clear_channel_flags_irq
\r
1828 ace_channel_handle_t channel_handle
\r
1831 /*-------------------------------------------------------------------------*//**
\r
1832 The ACE_enable_flag_irq() function enables the ACE post processing engine (PPE)
\r
1833 generated flags specified as parameter to interrupt the Cortex-M3 processor.
\r
1834 It enables flag interrupts both at the ACE PPE flag and Cortex-M3 interrupt
\r
1835 controller levels.
\r
1837 @param flag_handle
\r
1838 The flag_handle parameter identifies one of the flags generated based on the
\r
1839 value of an analog input channel. The available flag handle values can be
\r
1840 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1841 subdirectory. The flag handle value can also be retrieved through a call to
\r
1842 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1843 though all flags associated with an analog input channel using the
\r
1844 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1846 void ACE_enable_flag_irq
\r
1848 ace_flag_handle_t flag_handle
\r
1851 /*-------------------------------------------------------------------------*//**
\r
1852 The ACE_disable_flag_irq() function disables ACE post processing engine (PPE)
\r
1853 generated flags from interrupting the Cortex-M3. The interrupt is only
\r
1854 disabled at the ACE PPE flag level in order to avoid disabling other flags
\r
1855 interrupts which may happen to use the same ACE threshold interrupt line.
\r
1857 @param flag_handle
\r
1858 The flag_handle parameter identifies one of the flags generated based on the
\r
1859 value of an analog input channel. The available flag handle values can be
\r
1860 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1861 subdirectory. The flag handle value can also be retrieved through a call to
\r
1862 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1863 though all flags associated with an analog input channel using the
\r
1864 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1866 void ACE_disable_flag_irq
\r
1868 ace_flag_handle_t flag_handle
\r
1871 /*-------------------------------------------------------------------------*//**
\r
1872 The ACE_clear_flag_irq() function clears the interrupt for the flag specified
\r
1873 as parameter. This function would typically be used before enabling the flag
\r
1874 interrupt in order to ignore past events.
\r
1876 @param flag_handle
\r
1877 The flag_handle parameter identifies one of the flags generated based on the
\r
1878 value of an analog input channel. The available flag handle values can be
\r
1879 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1880 subdirectory. The flag handle value can also be retrieved through a call to
\r
1881 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1882 though all flags associated with an analog input channel using the
\r
1883 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1885 void ACE_clear_flag_irq
\r
1887 ace_flag_handle_t flag_handle
\r
1890 /*-------------------------------------------------------------------------*//**
\r
1891 The ACE_get_flag_name() function returns the name of the flag identified by
\r
1892 the flag handle passed as parameter.
\r
1894 @param flag_handle
\r
1895 The flag_handle parameter identifies one of the flags generated based on the
\r
1896 value of an analog input channel. The available flag handle values can be
\r
1897 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1898 subdirectory. The flag handle value can also be retrieved through a call to
\r
1899 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1900 though all flags associated with an analog input channel using the
\r
1901 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1904 The ACE_get_flag_name() function returns a pointer to a zero-terminated
\r
1905 string containing the name of the flag identified by the flag handle passed
\r
1906 as parameter. It returns 0 if the flag handle passed as parameter is invalid.
\r
1911 ace_flag_handle_t flag_handle
\r
1914 /*-------------------------------------------------------------------------*//**
\r
1915 The ACE_get_flag_channel() function returns the handle of the channel
\r
1916 monitored in order to generate the flag identified by the flag handle passed
\r
1919 @param flag_handle
\r
1920 The flag_handle parameter identifies one of the flags generated based on the
\r
1921 value of an analog input channel. The available flag handle values can be
\r
1922 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
1923 subdirectory. The flag handle value can also be retrieved through a call to
\r
1924 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
1925 though all flags associated with an analog input channel using the
\r
1926 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
1929 The ACE_get_flag_channel() function returns a channel handle identifying the
\r
1930 analog input channel monitored by the flag passed as parameter.
\r
1932 ace_channel_handle_t
\r
1933 ACE_get_flag_channel
\r
1935 ace_flag_handle_t flag_handle
\r
1938 /*-------------------------------------------------------------------------*//**
\r
1939 The ACE_get_channel_flag_count() function returns the total number of flags
\r
1940 associated with the input channel specified by the channel_handle parameter.
\r
1941 It indicates how many flags are generated based on the value of the specified
\r
1942 analog input channel.
\r
1944 @param channel_handle
\r
1945 The channel_handle parameter identifies one of the analog input channels
\r
1946 monitored by the ACE. The available channel handle values can be found in
\r
1947 the ace_handles.h file located in the .\drivers_config\mss_ace subdirectory.
\r
1948 The channel handle value can also be retrieved through a call to
\r
1949 ACE_get_channel_handle() when the name of the channel is known, or by
\r
1950 iterating though all analog input channel using the ACE_get_first_channel()
\r
1951 and ACE_get_next_channel().
\r
1954 The ACE_get_channel_flag_count() function returns the total number of flags
\r
1955 that are generated based on the value of the specified analog input channel.
\r
1956 The ACE_get_channel_flag_count() function returns 0 if no input channels were
\r
1962 uint32_t nb_of_flags;
\r
1963 uint16_t flag_iterator;
\r
1964 ace_flag_handle_t current_flag;
\r
1965 ace_channel_handle_t channel_handle;
\r
1967 nb_of_flags = ACE_get_channel_flag_count(channel_handle);
\r
1968 current_flag = ACE_get_channel_first_flag(channel_handle, &flag_iterator);
\r
1970 for (inc = 0; inc < nb_of_flags; ++inc)
\r
1972 current_flag = ACE_get_channel_next_flag(channel_handle, &flag_iterator);
\r
1973 display_flag_properties(current_flag);
\r
1978 ACE_get_channel_flag_count
\r
1980 ace_channel_handle_t channel_handle
\r
1983 /*-------------------------------------------------------------------------*//**
\r
1984 The ACE_get_channel_first_flag() function retrieves the handle of the first
\r
1985 flag associated with the analog input channel identified by the channel handle
\r
1986 passed as parameter. It also initialises the value of the iterator variable
\r
1987 pointed to by the second function parameter. The iterator can be used
\r
1988 subsequently as a parameter to the ACE_get_channel_next_flag() function to
\r
1989 iterate through all flags associated with the analog input channel.
\r
1991 @param channel_handle
\r
1992 The channel_handle parameter identifies one of the analog input channels
\r
1993 monitored by the ACE. The available channel handle values can be found in the
\r
1994 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory.
\r
1995 The channel handle value can also be retrieved through a call to
\r
1996 ACE_get_channel_handle() when the name of the channel is known, or by
\r
1997 iterating though all analog input channel using the ACE_get_first_channel()
\r
1998 and ACE_get_next_channel().
\r
2001 The iterator parameter is a pointer to a uint16_t iterator variable. The
\r
2002 value of the iterator variable will be set by the ACE_get_channel_first_flag()
\r
2003 functions so that it can be used in subsequent calls to
\r
2004 ACE_get_channel_next_flag() to keep track of the current location in the
\r
2005 list of flags associated with the analog input channel.
\r
2008 The ACE_get_channel_first_flag() function returns a flag handle identifying
\r
2009 one of the flags generated based on the value of the analog input channel
\r
2010 identified by the channel_handle parameter. It returns INVALID_FLAG_HANDLE
\r
2011 if no flags are generated based on the analog input channel input or if the
\r
2012 channel handle is invalid.
\r
2017 uint32_t nb_of_flags;
\r
2018 uint16_t flag_iterator;
\r
2019 ace_flag_handle_t current_flag;
\r
2020 ace_channel_handle_t channel_handle;
\r
2022 nb_of_flags = ACE_get_channel_flag_count(channel_handle);
\r
2023 current_flag = ACE_get_channel_first_flag(channel_handle, &flag_iterator);
\r
2025 for (inc = 0; inc < nb_of_flags; ++inc)
\r
2027 current_flag = ACE_get_channel_next_flag(channel_handle, &flag_iterator);
\r
2028 display_flag_properties(current_flag);
\r
2033 ACE_get_channel_first_flag
\r
2035 ace_channel_handle_t channel_handle,
\r
2036 uint16_t * iterator
\r
2039 /*-------------------------------------------------------------------------*//**
\r
2040 The ACE_get_channel_next_flag() function retrieves the handle of a flag
\r
2041 associated with the analog input channel identified by the channel handle
\r
2042 passed as parameter. The retrieved flag handle is the next one in the driver's
\r
2043 internal flag list based on the iterator parameter.
\r
2045 @param channel_handle
\r
2046 The channel_handle parameter identifies one of the analog input channels
\r
2047 monitored by the ACE. The available channel handle values can be found in the
\r
2048 ace_handles.h file located in the .\drivers_config\mss_ace subdirectory.
\r
2049 The channel handle value can also be retrieved through a call to
\r
2050 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2051 iterating though all analog input channel using the ACE_get_first_channel()
\r
2052 and ACE_get_next_channel().
\r
2055 The iterator parameter is a pointer to a uint16_t iterator variable. The value
\r
2056 of the iterator variable will be set by the ACE_get_channel_first_flag()
\r
2057 functions so that it can be used in subsequent calls to
\r
2058 ACE_get_channel_next_flag() to keep track of the current location in the list
\r
2059 of flags associated with the analog input channel.
\r
2064 uint32_t nb_of_flags;
\r
2065 uint16_t flag_iterator;
\r
2066 ace_flag_handle_t current_flag;
\r
2067 ace_channel_handle_t channel_handle;
\r
2069 nb_of_flags = ACE_get_channel_flag_count(channel_handle);
\r
2070 current_flag = ACE_get_channel_first_flag(channel_handle, &flag_iterator);
\r
2072 for (inc = 0; inc < nb_of_flags; ++inc)
\r
2074 current_flag = ACE_get_channel_next_flag(channel_handle, &flag_iterator);
\r
2075 display_flag_properties(current_flag);
\r
2080 ACE_get_channel_next_flag
\r
2082 ace_channel_handle_t channel_handle,
\r
2083 uint16_t * iterator
\r
2086 /*-------------------------------------------------------------------------*//**
\r
2087 This defines the function prototype that must be followed by MSS ACE Post
\r
2088 Processing Engine (PPE) flag handler functions. These functions are registered
\r
2089 with the ACE driver and associated with a particular flag through the
\r
2090 ACE_register_flag_isr() function. The ACE driver will call the flag handler
\r
2091 function when the associated flag is raised.
\r
2093 Declaring and Implementing PPE Flag Handler Functions
\r
2094 PPE flag handler functions should follow the following prototype:
\r
2095 void my_flag_handler ( ace_flag_handle_t flag_handle );
\r
2096 The actual name of the PPE flag handler is unimportant. You can use any name of
\r
2097 your choice for the PPE flag handler.
\r
2098 The flag_handle parameter passes the handle of the raised flag to the flag
\r
2101 typedef void (*flag_isr_t)( ace_flag_handle_t flag_handle );
\r
2103 /*-------------------------------------------------------------------------*//**
\r
2104 The ACE_register_flag_isr() function is used to register a handler function
\r
2105 with the ACE driver. The registered function will be called by the ACE driver
\r
2106 when the associated flag is raised by the ACE post processing engine.
\r
2108 @param flag_handle
\r
2109 The flag_handle parameter identifies one of the flags generated based on the
\r
2110 value of an analog input channel. The available flag handle values can be
\r
2111 found in the ace_handles.h file located in the .\drivers_config\mss_ace
\r
2112 subdirectory. The flag handle value can also be retrieved through a call to
\r
2113 ACE_get_flag_handle() when the name of the flag is known, or by iterating
\r
2114 though all flags associated with an analog input channel using the
\r
2115 ACE_get_channel_first_flag() and ACE_get_channel_next_flag().
\r
2118 The flag_isr parameter is a pointer to a flag handler function with the
\r
2119 following prototype:
\r
2120 void handler_function_name(ace_flag_handle_t flag_handle)
\r
2121 The flag handler function is called by the ACE driver as part of the relevant
\r
2122 post processing engine flag interrupt service routine. It does not need to
\r
2123 handle flag interrupt clearing as this is done by the ACE driver.
\r
2127 void my_critical_handler( void );
\r
2129 void system_init( void )
\r
2131 ace_flag_handle_t flag_handle;
\r
2133 flag_handle = ACE_get_flag_handle( "MainSupply:CriticalLevel" );
\r
2134 ACE_register_flag_isr( flag_handle, my_critical_handler );
\r
2135 ACE_enable_flag_irq( flag_handle );
\r
2138 void my_critical_handler( ace_flag_handle_t flag_handle )
\r
2140 panic( flag_handle );
\r
2145 void ACE_register_flag_isr
\r
2147 ace_flag_handle_t flag_handle,
\r
2148 flag_isr_t flag_isr
\r
2151 /*-------------------------------------------------------------------------*//**
\r
2152 This defines the function prototype that must be followed by MSS ACE Post
\r
2153 Processing Engine (PPE) channel flag handler functions. These functions are
\r
2154 registered with the ACE driver and associated with a particular ADC input
\r
2155 channel through the ACE_register_channel_flags_isr() function. The ACE driver
\r
2156 will call the channel flags handler function when one of the flags for the
\r
2157 associated ADC input channel is raised.
\r
2159 Declaring and Implementing PPE Channel Flag Handler Functions
\r
2160 PPE channel flag handler functions should follow the following prototype:
\r
2161 void my_channel_flag_handler ( ace_flag_handle_t flag_handle );
\r
2162 The actual name of the PPE channel flag handler is unimportant. You can use
\r
2163 any name of your choice for the PPE channel flag handler. The flag_handle
\r
2164 parameter passes the handle of the raised flag to the channel flag handler
\r
2167 typedef void (*channel_flag_isr_t)( ace_flag_handle_t flag_handle );
\r
2169 /*-------------------------------------------------------------------------*//**
\r
2170 The ACE_register_channel_flags_isr() function is used to register a flag
\r
2171 interrupt handler function with the ACE driver. The registered interrupt
\r
2172 handler will be called by the ACE driver when one of the flag generated based
\r
2173 on the value of the analog input channel identified by the channel handle
\r
2174 passed as parameter is asserted.
\r
2176 @param channel_handle
\r
2177 The channel_handle parameter identifies one of the analog input channels
\r
2178 monitored by the ACE. The available channel handle values can be found in the
\r
2179 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2180 channel handle value can also be retrieved through a call to
\r
2181 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2182 iterating though all analog input channel using the ACE_get_first_channel()
\r
2183 and ACE_get_next_channel().
\r
2185 @param channel_flag_isr
\r
2186 The channel_flag_isr parameter is pointer to a function taking a flag handle
\r
2188 void handler_function_name(ace_flag_handle_t flag_handle)
\r
2189 The flag handler function is called by the ACE driver as part of the relevant
\r
2190 post processing engine flag interrupt service routine. It does not need to
\r
2191 handle flag interrupt clearing as this is done by the ACE driver.
\r
2194 The example below demonstrates the use of the ACE_register_channel_flags_isr()
\r
2195 function in a system where the ACE is configured to have an analog input
\r
2196 channels named "MainSupply" with one flag named "Critical" generated based
\r
2197 on the value of "MainSupply" channel. The names "MainSupply" and "Critical"
\r
2198 were user selected in the ACE configurator.
\r
2200 void main_supply_handler (ace_flag_handle_t flag_handle);
\r
2202 void system_init(void)
\r
2204 ACE_register_channel_flag_isr(MainSupply, main_supply_handler);
\r
2205 ACE_enable_channel_flags_irq(MainSupply);
\r
2208 void main_supply_handler (ace_flag_handle_t flag_handle)
\r
2210 if (MainSupply_Critical == flag_handle)
\r
2212 panic(flag_handle);
\r
2218 void ACE_register_channel_flags_isr
\r
2220 ace_channel_handle_t channel_handle,
\r
2221 channel_flag_isr_t channel_flag_isr
\r
2224 /*-------------------------------------------------------------------------*//**
\r
2225 This defines the function prototype that must be followed by MSS ACE Post
\r
2226 Processing Engine (PPE) global flag handler functions. These functions are
\r
2227 registered with the ACE driver through the ACE_register_global_flags_isr()
\r
2228 function. The ACE driver will call the global flags handler function when any
\r
2229 flag for any ADC input channel is raised.
\r
2231 Declaring and Implementing Global Flag Handler Functions
\r
2232 PPE global flag handler functions should follow the following prototype:
\r
2233 void my_global_flag_handler(
\r
2234 ace_flag_handle_t flag_handle,
\r
2235 ace_channel_handle_t channel_handle
\r
2237 The actual name of the PPE global flag handler is unimportant. You can use any
\r
2238 name of your choice for the PPE global flag handler. The flag_handle parameter
\r
2239 passes the handle of the raised flag to the global flag handler function. The
\r
2240 channel_handle parameter passes the handle of the channel for which the flag
\r
2241 was raised to the global flag handler function.
\r
2244 typedef void (*global_flag_isr_t)( ace_flag_handle_t flag_handle, ace_channel_handle_t channel_handle );
\r
2246 /*-------------------------------------------------------------------------*//**
\r
2247 The ACE_register_global_flags_isr() function is used to register a global
\r
2248 flag handler function with the ACE driver. The registered global handler will
\r
2249 be called when any flag interrupt is generated.
\r
2251 @param global_flag_isr
\r
2252 The global_flag_isr parameter is a pointer to a function taking a flag
\r
2253 handle and channel handle as parameter.
\r
2255 void ACE_register_global_flags_isr
\r
2257 global_flag_isr_t global_flag_isr
\r
2262 /*=========================================================================*//**
\r
2263 @defgroup group11 Conversion Functions
\r
2264 The following functions are used to convert an ADC sample value to a real
\r
2267 *//*=========================================================================*/
\r
2269 /*-------------------------------------------------------------------------*//**
\r
2270 The ACE_convert_adc_input_to_mV() function converts an ADC sample value into
\r
2271 the value in millivolts of the voltage seen at ADC input. It does not account
\r
2272 for prescaling taking place before the ADC hardware input.
\r
2274 @param channel_handle
\r
2275 The channel_handle parameter identifies one of the analog input channels
\r
2276 monitored by the ACE. The available channel handle values can be found in the
\r
2277 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2278 channel handle value can also be retrieved through a call to
\r
2279 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2280 iterating though all analog input channel using the ACE_get_first_channel()
\r
2281 and ACE_get_next_channel().
\r
2283 @param sample_value
\r
2284 The sample_value parameter is the result of an analog to digital conversion.
\r
2287 The ACE_convert_adc_input_to_mV() returns the number of millivolts derived
\r
2288 from the ADC sample value passed as parameter.
\r
2290 uint32_t ACE_convert_adc_input_to_mV
\r
2292 ace_channel_handle_t channel_handle,
\r
2293 uint16_t sample_value
\r
2296 /*-------------------------------------------------------------------------*//**
\r
2297 The ACE_convert_to_mV() function converts a PPE sample value into milli-Volts.
\r
2298 It handles prescaling adjusments based on ACE configuration for ABPS inputs.
\r
2300 @param channel_handle
\r
2301 The channel_handle parameter identifies one of the analog input channels
\r
2302 monitored by the ACE. The available channel handle values can be found in the
\r
2303 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2304 channel handle value can also be retrieved through a call to
\r
2305 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2306 iterating though all analog input channel using the ACE_get_first_channel()
\r
2307 and ACE_get_next_channel().
\r
2309 @param sample_value
\r
2310 The sample_value parameter is the result of an analog to digital conversion.
\r
2313 The ACE_convert_to_mV() returns the number of millivolts derived from the
\r
2314 PPE sample value passed as parameter. The returned value can be either
\r
2315 positive or negative since prescaling is accounted for in the conversion.
\r
2317 int32_t ACE_convert_to_mV
\r
2319 ace_channel_handle_t channel_handle,
\r
2320 uint16_t sample_value
\r
2323 /*-------------------------------------------------------------------------*//**
\r
2324 The ACE_convert_to_mA() function converts a PPE sample value into milli-Amps.
\r
2325 The result of the conversion is only meaningful if the PPE sample value
\r
2326 results from the conversion of a current monitor input.
\r
2328 @param channel_handle
\r
2329 The channel_handle parameter identifies one of the analog input channels
\r
2330 monitored by the ACE. The available channel handle values can be found in the
\r
2331 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2332 channel handle value can also be retrieved through a call to
\r
2333 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2334 iterating though all analog input channel using the ACE_get_first_channel()
\r
2335 and ACE_get_next_channel().
\r
2337 @param sample_value
\r
2338 The sample_value parameter is the result of an analog to digital conversion
\r
2339 of the voltage generated by a current monitor analog block.
\r
2342 The ACE_convert_to_mA() returns the number of milliamps derived from the
\r
2343 PPE sample value passed as parameter.
\r
2345 uint32_t ACE_convert_to_mA
\r
2347 ace_channel_handle_t channel_handle,
\r
2348 uint16_t sample_value
\r
2351 /*-------------------------------------------------------------------------*//**
\r
2352 The ACE_convert_to_Kelvin() function converts a PPE sample value into degrees
\r
2353 Kelvin. The result of the conversion is only meaningful if the PPE sample value
\r
2354 results from the conversion of a temperature monitor input.
\r
2356 @param channel_handle
\r
2357 The channel_handle parameter identifies one of the analog input channels
\r
2358 monitored by the ACE. The available channel handle values can be found in the
\r
2359 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2360 channel handle value can also be retrieved through a call to
\r
2361 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2362 iterating though all analog input channel using the ACE_get_first_channel()
\r
2363 and ACE_get_next_channel().
\r
2365 @param sample_value
\r
2366 The sample_value parameter is the result of an analog to digital conversion
\r
2367 of the voltage generated by a temperature monitor analog block.
\r
2370 The ACE_convert_to_Kelvin() returns the number of degrees Kelvin derived
\r
2371 from the PPE sample value passed as parameter.
\r
2373 uint32_t ACE_convert_to_Kelvin
\r
2375 ace_channel_handle_t channel_handle,
\r
2376 uint16_t sample_value
\r
2379 /*-------------------------------------------------------------------------*//**
\r
2380 The ACE_convert_to_Celsius() function converts a PPE sample value into tenths
\r
2381 of degrees Celsius. The result of the conversion is only meaningful if the PPE
\r
2382 sample value results from the conversion of a temperature monitor input.
\r
2384 @param channel_handle
\r
2385 The channel_handle parameter identifies one of the analog input channels
\r
2386 monitored by the ACE. The available channel handle values can be found in the
\r
2387 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2388 channel handle value can also be retrieved through a call to
\r
2389 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2390 iterating though all analog input channel using the ACE_get_first_channel()
\r
2391 and ACE_get_next_channel().
\r
2393 @param sample_value
\r
2394 The sample_value parameter is the result of an analog to digital conversion
\r
2395 of the voltage generated by a temperature monitor analog block.
\r
2398 The ACE_convert_to_Celsius() returns the number of tenths of degrees Celsius
\r
2399 derived from the PPE sample value passed as parameter.
\r
2401 int32_t ACE_convert_to_Celsius
\r
2403 ace_channel_handle_t channel_handle,
\r
2404 uint16_t sample_value
\r
2407 /*-------------------------------------------------------------------------*//**
\r
2408 The ACE_convert_to_Fahrenheit() function converts a PPE sample value into
\r
2409 degrees Fahrenheit. The result of the conversion is only meaningful if the PPE
\r
2410 sample value results from the conversion of a temperature monitor input.
\r
2412 @param channel_handle
\r
2413 The channel_handle parameter identifies one of the analog input channels
\r
2414 monitored by the ACE. The available channel handle values can be found in the
\r
2415 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2416 channel handle value can also be retrieved through a call to
\r
2417 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2418 iterating though all analog input channel using the ACE_get_first_channel()
\r
2419 and ACE_get_next_channel().
\r
2421 @param sample_value
\r
2422 The sample_value parameter is the result of an analog to digital conversion
\r
2423 of the voltage generated by a temperature monitor analog block.
\r
2426 The ACE_convert_to_Fahrenheit() returns the number of degrees Fahrenheit
\r
2427 derived from the PPE sample value passed as parameter.
\r
2429 int32_t ACE_convert_to_Fahrenheit
\r
2431 ace_channel_handle_t channel_handle,
\r
2432 uint16_t sample_value
\r
2435 /*-------------------------------------------------------------------------*//**
\r
2436 The ACE_convert_mV_to_adc_value() function converts a voltage value given in
\r
2437 milli-Volts into the ADC sample value that would result from sampling this
\r
2438 voltage value on the analog input channel specified as parameter.
\r
2439 This function is intended for use when directly controlling the ADC, not when
\r
2440 using samples read from the PPE. It does not account for prescaling taking
\r
2441 place before the ADC hardware input.
\r
2443 @param channel_handle
\r
2444 The channel_handle parameter identifies one of the analog input channels
\r
2445 monitored by the ACE. The available channel handle values can be found in the
\r
2446 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2447 channel handle value can also be retrieved through a call to
\r
2448 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2449 iterating though all analog input channel using the ACE_get_first_channel()
\r
2450 and ACE_get_next_channel().
\r
2453 The voltage parameter is the milli-Volts voltage value for which we want this
\r
2454 function to return the associated ADC sample result value.
\r
2457 The ACE_convert_mV_to_adc_value() returns the ADC sample value that would be
\r
2458 produced if the analog input channel identified by channel_handle was set to
\r
2459 the voltage value passed as second parameter.
\r
2461 uint16_t ACE_convert_mV_to_adc_value
\r
2463 ace_channel_handle_t channel_handle,
\r
2467 /*-------------------------------------------------------------------------*//**
\r
2468 The ACE_convert_from_mV() function converts a voltage value given in
\r
2469 milli-Volts into the PPE sample value that would result from sampling this
\r
2470 voltage value on the analog input channel specified as parameter.
\r
2471 This function handles prescaling adjusments based on ACE configuration for
\r
2474 @param channel_handle
\r
2475 The channel_handle parameter identifies one of the analog input channels
\r
2476 monitored by the ACE. The available channel handle values can be found in the
\r
2477 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2478 channel handle value can also be retrieved through a call to
\r
2479 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2480 iterating though all analog input channel using the ACE_get_first_channel()
\r
2481 and ACE_get_next_channel().
\r
2484 The voltage parameter is the milli-Volts voltage value for which we want this
\r
2485 function to return the associated PPE sample result value.
\r
2488 The ACE_convert_from_mV() returns the PPE sample value that would be produced
\r
2489 if the analog input channel identified by channel_handle was set to the
\r
2490 voltage value passed as second parameter.
\r
2492 uint16_t ACE_convert_from_mV
\r
2494 ace_channel_handle_t channel_handle,
\r
2498 /*-------------------------------------------------------------------------*//**
\r
2499 The ACE_convert_from_mA() function converts a current value given in
\r
2500 milli-Amps into the PPE sample value that would result from sampling this
\r
2501 current value on the analog input channel specified as parameter.
\r
2502 The result of the conversion is only meaningful if the analog input channel
\r
2503 specified as parameter is configured as a current monitoring channel.
\r
2505 @param channel_handle
\r
2506 The channel_handle parameter identifies one of the analog input channels
\r
2507 monitored by the ACE. The available channel handle values can be found in the
\r
2508 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2509 channel handle value can also be retrieved through a call to
\r
2510 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2511 iterating though all analog input channel using the ACE_get_first_channel()
\r
2512 and ACE_get_next_channel().
\r
2515 The current parameter is the milli-Amps current value for which we want this
\r
2516 function to return the associated PPE sample result value.
\r
2519 The ACE_convert_from_mA() returns the PPE sample value that would be produced
\r
2520 if the analog input channel identified by channel_handle was set to the
\r
2521 current value passed as second parameter.
\r
2523 uint16_t ACE_convert_from_mA
\r
2525 ace_channel_handle_t channel_handle,
\r
2529 /*-------------------------------------------------------------------------*//**
\r
2530 The ACE_convert_from_Kelvin() function converts a temperature value given in
\r
2531 degrees Kelvin into the PPE sample value that would result from sampling this
\r
2532 temperature value on the analog input channel specified as parameter.
\r
2533 The result of the conversion is only meaningful if the analog input channel
\r
2534 specified as parameter is configured as a temperature monitoring channel.
\r
2536 @param channel_handle
\r
2537 The channel_handle parameter identifies one of the analog input channels
\r
2538 monitored by the ACE. The available channel handle values can be found in the
\r
2539 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2540 channel handle value can also be retrieved through a call to
\r
2541 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2542 iterating though all analog input channel using the ACE_get_first_channel()
\r
2543 and ACE_get_next_channel().
\r
2545 @param temperature
\r
2546 The temperature parameter is the degrees Kelvin temperature value for which
\r
2547 we want this function to return the associated PPE sample result value.
\r
2550 The ACE_convert_from_Kelvin() returns the PPE sample value that would be
\r
2551 produced if the analog input channel identified by channel_handle was set to
\r
2552 the temperature value passed as second parameter.
\r
2554 uint16_t ACE_convert_from_Kelvin
\r
2556 ace_channel_handle_t channel_handle,
\r
2557 uint32_t temperature
\r
2560 /*-------------------------------------------------------------------------*//**
\r
2561 The ACE_convert_from_Celsius() function converts a temperature value given in
\r
2562 degrees Celsius into the PPE sample value that would result from sampling this
\r
2563 temperature value on the analog input channel specified as parameter.
\r
2564 The result of the conversion is only meaningful if the analog input channel
\r
2565 specified as parameter is configured as a temperature monitoring channel.
\r
2567 @param channel_handle
\r
2568 The channel_handle parameter identifies one of the analog input channels
\r
2569 monitored by the ACE. The available channel handle values can be found in the
\r
2570 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2571 channel handle value can also be retrieved through a call to
\r
2572 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2573 iterating though all analog input channel using the ACE_get_first_channel()
\r
2574 and ACE_get_next_channel().
\r
2576 @param temperature
\r
2577 The temperature parameter is the degrees Celsius temperature value for which
\r
2578 we want this function to return the associated PPE sample result value.
\r
2581 The ACE_convert_from_Celsius() returns the PPE sample value that would be
\r
2582 produced if the analog input channel identified by channel_handle was set to
\r
2583 the temperature value passed as second parameter.
\r
2585 uint16_t ACE_convert_from_Celsius
\r
2587 ace_channel_handle_t channel_handle,
\r
2588 int32_t temperature
\r
2591 /*-------------------------------------------------------------------------*//**
\r
2592 The ACE_convert_from_Fahrenheit() function converts a temperature value given
\r
2593 in degrees Fahrenheit into the PPE sample value that would result from sampling
\r
2594 this temperature value on the analog input channel specified as parameter.
\r
2595 The result of the conversion is only meaningful if the analog input channel
\r
2596 specified as parameter is configured as a temperature monitoring channel.
\r
2598 @param channel_handle
\r
2599 The channel_handle parameter identifies one of the analog input channels
\r
2600 monitored by the ACE. The available channel handle values can be found in the
\r
2601 ace_handles.h file located in the ./drivers_config/mss_ace subdirectory. The
\r
2602 channel handle value can also be retrieved through a call to
\r
2603 ACE_get_channel_handle() when the name of the channel is known, or by
\r
2604 iterating though all analog input channel using the ACE_get_first_channel()
\r
2605 and ACE_get_next_channel().
\r
2607 @param temperature
\r
2608 The temperature parameter is the degrees Fahrenheit temperature value for
\r
2609 which we want this function to return the associated PPE sample result value.
\r
2612 The ACE_convert_from_Fahrenheit() returns the PPE sample value that would be
\r
2613 produced if the analog input channel identified by channel_handle was set to
\r
2614 the temperature value passed as second parameter.
\r
2616 uint16_t ACE_convert_from_Fahrenheit
\r
2618 ace_channel_handle_t channel_handle,
\r
2619 int32_t temperature
\r
2622 /*-------------------------------------------------------------------------*//**
\r
2623 The ACE_translate_pdma_value() function translates PDMA sampling values,
\r
2624 received from the ACE via PDMA transfers, into input channel ID and PPE
\r
2626 The PDMA sampling values are generated by the ACE as a result of selecting
\r
2627 "Send result to DMA" in the ACE configurator analog input configuration. The
\r
2628 PDMA sampling values can be either raw ADC values, filtered values or the
\r
2629 result of a linear transformation.
\r
2630 The PDMA sampling values are obtained by configuring the PDMA controller to
\r
2631 transfer data from the ACE into a memory buffer. The ACE_translate_pdma_value()
\r
2632 function is used to interpret the content of that memory buffer.
\r
2634 Please note that the translation of PDMA data containing raw ADC values from
\r
2635 ABPS inputs will result in sample values with an unexpected polarity.
\r
2636 The returned sample value will have the opposite polarity to the actual analog
\r
2637 value seen on the ABPS input. This is due to the internal characteristics of
\r
2638 the analog front end that are normally hidden by the PPE processing of ADC raw
\r
2639 samples. The translation of raw ADC values from analog inputs other than ABPS
\r
2640 inputs will result in correct sample values.
\r
2643 The pdma_value parameter is a 32-bit value received from the ACE through a
\r
2644 peripheral DMA transfer.
\r
2647 The channel_id parameter is a pointer to an ADC channel ID variable. It is
\r
2648 used to return the ID of the ADC channel from which the PPE sample value
\r
2649 was generated from. This parameter can be set to zero if retrieving the
\r
2650 channel ID is not required.
\r
2653 The ACE_translate_pdma_value() returns the PPE sample value extracted from
\r
2654 the PDMA sampling value.
\r
2658 uint16_t ppe_value;
\r
2659 uint16_t pdma_value;
\r
2660 adc_channel_id_t channel_id;
\r
2661 ace_channel_handle_t channel_handle;
\r
2663 pdma_value = get_next_pdma_ace_sample();
\r
2664 ppe_value = ACE_translate_pdma_value(pdma_value, &channel_id);
\r
2665 channel_handle = ACE_get_input_channel_handle(channel_id);
\r
2666 if (channel_handle != INVALID_CHANNEL_HANDLE)
\r
2668 display_value(channel_handle, ppe_value);
\r
2673 uint16_t ACE_translate_pdma_value
\r
2675 uint32_t pdma_value,
\r
2676 adc_channel_id_t * channel_id
\r
2681 /*=========================================================================*//**
\r
2682 @defgroup group12 Dynamic Linear Transform Control Functions
\r
2683 The following functions are used to dynamically adjust the linear transform
\r
2684 applied to analog input samples by the post processing engine:
\r
2685 - ACE_get_default_m_factor()
\r
2686 - ACE_get_default_c_offset()
\r
2687 - ACE_set_linear_transform()
\r
2688 The post processing engine performs a linear transform on analog input samples
\r
2689 obtained from the sample sequencing engine. The main purpose of this linear
\r
2690 transform is to apply part specific factory calibration to the analog samples
\r
2691 in order to achieve high accuracy. A second user specified linear transform
\r
2692 can also be optionally applied to the analog samples. This second linear
\r
2693 transform can be used to adjust for board level calibration or application
\r
2694 specific tuning. The functions described in this section apply to the user
\r
2695 defined transform. Factory calibration will not be affected by the use of the
\r
2696 ACE_set_linear_transform() function.
\r
2698 The post processing engine actually only performs one single linear
\r
2699 transform on analog samples. This transform takes into account factory
\r
2700 calibration and the user defined transform. The applied y = m.x + c
\r
2701 transform uses an m factor equal to m1.m2.mext and c offset equal to
\r
2702 (m2.c1.mext) + (c2.mext) where m1 and c1 are the factory calibration factor
\r
2703 and offset; m2 and c2 are the user defined transform factor and offset; and
\r
2704 mext is a factory calibration factor depending on the reference voltage
\r
2705 used by the ADC generating the sample.
\r
2707 *//*=========================================================================*/
\r
2710 /*------------------------------------------------------------------------*//**
\r
2711 The ACE_get_default_m_factor() function retrieves the default value of the m
\r
2712 factor of the user defined linear transform applied by the post processing
\r
2713 engine to analog samples. The user defined linear transform m factor default
\r
2714 value is selected in the ACE configurator tool.
\r
2716 @param channel_handle
\r
2717 The channel_handle parameter identifies one of the analog input channels
\r
2718 monitored by the ACE. The available channel handle values can be found in
\r
2719 the ace_handles.h file located in the .\drivers_config\mss_ace
\r
2720 subdirectory. The channel handle value can also be retrieved through a call
\r
2721 to ACE_get_channel_handle() when the name of the channel is known, or by
\r
2722 iterating though all analog input channel using the ACE_get_first_channel()
\r
2723 and ACE_get_next_channel().
\r
2726 The ACE_get_default_m_factor() function returns the user transform m factor
\r
2727 default value. It is a signed 16-bit number representing a factor in the
\r
2728 range -2 to +1.99993896484375. The value of the m factor is obtained by
\r
2729 multiplying the return value
\92s absolute value by 2-14.
\r
2731 int16_t ACE_get_default_m_factor
\r
2733 ace_channel_handle_t channel_handle
\r
2736 /*------------------------------------------------------------------------*//**
\r
2737 The ACE_get_default_c_offset() function retrieves the default value of the c
\r
2738 offset of the user defined linear transform applied by the post processing
\r
2739 engine to analog samples. The user defined linear transform c offset default
\r
2740 value is selected in the ACE configurator tool.
\r
2742 @param channel_handle
\r
2743 The channel_handle parameter identifies one of the analog input channels
\r
2744 monitored by the ACE. The available channel handle values can be found in
\r
2745 the ace_handles.h file located in the .\drivers_config\mss_ace
\r
2746 subdirectory. The channel handle value can also be retrieved through a call
\r
2747 to ACE_get_channel_handle() when the name of the channel is known, or by
\r
2748 iterating though all analog input channel using the ACE_get_first_channel()
\r
2749 and ACE_get_next_channel().
\r
2752 The ACE_get_default_c_offset() function returns the user linear transform
\92s
\r
2753 c offset default value. It is a signed 16-bit number representing a factor
\r
2754 in the range -2 to +1.99993896484375. The value of the c offset is obtained
\r
2755 by multiplying the return value
\92s absolute value by 2-14.
\r
2757 int16_t ACE_get_default_c_offset
\r
2759 ace_channel_handle_t channel_handle
\r
2762 /*------------------------------------------------------------------------*//**
\r
2763 The ACE_set_linear_transform() function allows adjusting the user defined
\r
2764 linear transform applied to analog input samples by the post processing
\r
2765 engine. The linear transform is of the form y = m.x + b where the m factor
\r
2766 and c offset are in the range -2 to +1.99993896484375.
\r
2768 @param channel_handle
\r
2769 The channel_handle parameter identifies one of the analog input channels
\r
2770 monitored by the ACE. The available channel handle values can be found in
\r
2771 the ace_handles.h file located in the .\drivers_config\mss_ace
\r
2772 subdirectory. The channel handle value can also be retrieved through a call
\r
2773 to ACE_get_channel_handle() when the name of the channel is known, or by
\r
2774 iterating though all analog input channel using the ACE_get_first_channel()
\r
2775 and ACE_get_next_channel().
\r
2778 The m2 parameter specifies the user defined transform
\92s m factor. It is a
\r
2779 signed 16-bit number representing a factor in the range -2 to
\r
2780 +1.99993896484375. The value of the m2 factor is obtained by multiplying the
\r
2781 parameter
\92s absolute value by 2^-14. For example, a value of 0x7000
\r
2782 represents a 1.75 factor and a value of 0xE000 represents a -0.5 factor.
\r
2785 The c2 parameter specifies the user defined transform
\92s c offset. It is a
\r
2786 signed 16-bit number representing an offset in the range -2 to
\r
2787 +1.99993896484375. The value of the c2 offset is obtained by multiplying the
\r
2788 parameter
\92s absolute value by 2^-14. For example, a value of 0x1000 represents
\r
2789 a 0.25 offset and a value of 0xB000 represents a -1.25 offset.
\r
2792 void reset_to_default(ace_channel_handle_t channel_handle)
\r
2797 m = ACE_get_default_m_factor(channel_handle);
\r
2798 c = ACE_get_default_c_offset(channel_handle);
\r
2799 ACE_set_linear_transform(channel_handle, m, c);
\r
2803 void ACE_set_linear_transform
\r
2805 ace_channel_handle_t channel_handle,
\r
2812 #ifdef __cplusplus
\r
2816 #endif /* __MSS_ACE_H_ */
\r
projects / freertos / blob