1 /******************************************************************************
3 * Copyright (C) 2011 - 2014 Xilinx, Inc. All rights reserved.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * Use of the Software is limited solely to applications:
16 * (a) running on a Xilinx device, or
17 * (b) that interact with a Xilinx device through a bus or interconnect.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * XILINX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * Except as contained in this notice, the name of the Xilinx shall not be used
28 * in advertising or otherwise to promote the sale, use or other dealings in
29 * this Software without prior written authorization from Xilinx.
31 ******************************************************************************/
32 /****************************************************************************/
36 * @addtogroup xadcps_v2_2
40 * The XAdcPs driver supports the Xilinx XADC/ADC device.
42 * The XADC/ADC device has the following features:
43 * - 10-bit, 200-KSPS (kilo samples per second)
44 * Analog-to-Digital Converter (ADC)
45 * - Monitoring of on-chip supply voltages and temperature
46 * - 1 dedicated differential analog-input pair and
47 * 16 auxiliary differential analog-input pairs
48 * - Automatic alarms based on user defined limits for the on-chip
49 * supply voltages and temperature
50 * - Automatic Channel Sequencer, programmable averaging, programmable
51 * acquisition time for the external inputs, unipolar or differential
52 * input selection for the external inputs
53 * - Inbuilt Calibration
54 * - Optional interrupt request generation
57 * The user should refer to the hardware device specification for detailed
58 * information about the device.
60 * This header file contains the prototypes of driver functions that can
61 * be used to access the XADC/ADC device.
64 * <b> XADC Channel Sequencer Modes </b>
66 * The XADC Channel Sequencer supports the following operating modes:
68 * - <b> Default </b>: This is the default mode after power up.
69 * In this mode of operation the XADC operates in
70 * a sequence mode, monitoring the on chip sensors:
71 * Temperature, VCCINT, and VCCAUX.
72 * - <b> One pass through sequence </b>: In this mode the XADC
73 * converts the channels enabled in the Sequencer Channel Enable
74 * registers for a single pass and then stops.
75 * - <b> Continuous cycling of sequence </b>: In this mode the XADC
76 * converts the channels enabled in the Sequencer Channel Enable
77 * registers continuously.
78 * - <b> Single channel mode</b>: In this mode the XADC Channel
79 * Sequencer is disabled and the XADC operates in a
80 * Single Channel Mode.
81 * The XADC can operate either in a Continuous or Event
82 * driven sampling mode in the single channel mode.
83 * - <b> Simultaneous Sampling Mode</b>: In this mode the XADC Channel
84 * Sequencer will automatically sequence through eight fixed pairs
85 * of auxiliary analog input channels for simulataneous conversion.
86 * - <b> Independent ADC mode</b>: In this mode the first ADC (A) is used to
87 * is used to implement a fixed monitoring mode similar to the
88 * default mode but the alarm fucntions ar eenabled.
89 * The second ADC (B) is available to be used with external analog
90 * input channels only.
92 * Read the XADC spec for more information about the sequencer modes.
94 * <b> Initialization and Configuration </b>
96 * The device driver enables higher layer software (e.g., an application) to
97 * communicate to the XADC/ADC device.
99 * XAdcPs_CfgInitialize() API is used to initialize the XADC/ADC
100 * device. The user needs to first call the XAdcPs_LookupConfig() API which
101 * returns the Configuration structure pointer which is passed as a parameter to
102 * the XAdcPs_CfgInitialize() API.
107 * The XADC/ADC device supports interrupt driven mode and the default
108 * operation mode is polling mode.
110 * The interrupt mode is available only if hardware is configured to support
113 * This driver does not provide a Interrupt Service Routine (ISR) for the device.
114 * It is the responsibility of the application to provide one if needed. Refer to
115 * the interrupt example provided with this driver for details on using the
116 * device in interrupt mode.
119 * <b> Virtual Memory </b>
121 * This driver supports Virtual Memory. The RTOS is responsible for calculating
122 * the correct device base address in Virtual Memory space.
127 * This driver is not thread safe. Any needs for threads or thread mutual
128 * exclusion must be satisfied by the layer above this driver.
133 * Asserts are used within all Xilinx drivers to enforce constraints on argument
134 * values. Asserts can be turned off on a system-wide basis by defining, at
135 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
136 * is recommended that users leave asserts on during development.
139 * <b> Building the driver </b>
141 * The XAdcPs driver is composed of several source files. This allows the user
142 * to build and link only those parts of the driver that are necessary.
144 * <b> Limitations of the driver </b>
146 * XADC/ADC device can be accessed through the JTAG port and the PLB
147 * interface. The driver implementation does not support the simultaneous access
148 * of the device by both these interfaces. The user has to care of this situation
149 * in the user application code.
155 * MODIFICATION HISTORY:
157 * Ver Who Date Changes
158 * ----- ----- -------- -----------------------------------------------------
159 * 1.00a ssb 12/22/11 First release based on the XPS/AXI xadc driver
160 * 1.01a bss 02/18/13 Modified XAdcPs_SetSeqChEnables,XAdcPs_SetSeqAvgEnables
161 * XAdcPs_SetSeqInputMode and XAdcPs_SetSeqAcqTime APIs
162 * in xadcps.c to fix CR #693371
163 * 1.03a bss 11/01/13 Modified xadcps_hw.h to use correct Register offsets
165 * 2.1 bss 08/05/14 Added declarations for XAdcPs_SetSequencerEvent,
166 * XAdcPs_GetSamplingMode, XAdcPs_SetMuxMode,
167 * XAdcPs_SetPowerdownMode and XAdcPs_GetPowerdownMode
169 * Modified Assert for XAdcPs_SetSingleChParams in
170 * xadcps.c to fix CR #807563.
171 * 2.2 bss 04/27/14 Modified to use correct Device Config base address in
172 * xadcps.c (CR#854437).
173 * ms 01/23/17 Added xil_printf statement in main function for all
174 * examples to ensure that "Successfully ran" and "Failed"
175 * strings are available in all examples. This is a fix
177 * ms 03/17/17 Added readme.txt file in examples folder for doxygen
179 * ms 04/05/17 Modified Comment lines in functions of xadcps
180 * examples to recognize it as documentation block
181 * for doxygen generation.
185 *****************************************************************************/
186 #ifndef XADCPS_H /* Prevent circular inclusions */
187 #define XADCPS_H /* by using protection macros */
193 /***************************** Include Files ********************************/
195 #include "xil_types.h"
196 #include "xil_assert.h"
198 #include "xadcps_hw.h"
200 /************************** Constant Definitions ****************************/
204 * @name Indexes for the different channels.
207 #define XADCPS_CH_TEMP 0x0 /**< On Chip Temperature */
208 #define XADCPS_CH_VCCINT 0x1 /**< VCCINT */
209 #define XADCPS_CH_VCCAUX 0x2 /**< VCCAUX */
210 #define XADCPS_CH_VPVN 0x3 /**< VP/VN Dedicated analog inputs */
211 #define XADCPS_CH_VREFP 0x4 /**< VREFP */
212 #define XADCPS_CH_VREFN 0x5 /**< VREFN */
213 #define XADCPS_CH_VBRAM 0x6 /**< On-chip VBRAM Data Reg, 7 series */
214 #define XADCPS_CH_SUPPLY_CALIB 0x07 /**< Supply Calib Data Reg */
215 #define XADCPS_CH_ADC_CALIB 0x08 /**< ADC Offset Channel Reg */
216 #define XADCPS_CH_GAINERR_CALIB 0x09 /**< Gain Error Channel Reg */
217 #define XADCPS_CH_VCCPINT 0x0D /**< On-chip PS VCCPINT Channel , Zynq */
218 #define XADCPS_CH_VCCPAUX 0x0E /**< On-chip PS VCCPAUX Channel , Zynq */
219 #define XADCPS_CH_VCCPDRO 0x0F /**< On-chip PS VCCPDRO Channel , Zynq */
220 #define XADCPS_CH_AUX_MIN 16 /**< Channel number for 1st Aux Channel */
221 #define XADCPS_CH_AUX_MAX 31 /**< Channel number for Last Aux channel */
227 * @name Indexes for reading the Calibration Coefficient Data.
230 #define XADCPS_CALIB_SUPPLY_COEFF 0 /**< Supply Offset Calib Coefficient */
231 #define XADCPS_CALIB_ADC_COEFF 1 /**< ADC Offset Calib Coefficient */
232 #define XADCPS_CALIB_GAIN_ERROR_COEFF 2 /**< Gain Error Calib Coefficient*/
237 * @name Indexes for reading the Minimum/Maximum Measurement Data.
240 #define XADCPS_MAX_TEMP 0 /**< Maximum Temperature Data */
241 #define XADCPS_MAX_VCCINT 1 /**< Maximum VCCINT Data */
242 #define XADCPS_MAX_VCCAUX 2 /**< Maximum VCCAUX Data */
243 #define XADCPS_MAX_VBRAM 3 /**< Maximum VBRAM Data */
244 #define XADCPS_MIN_TEMP 4 /**< Minimum Temperature Data */
245 #define XADCPS_MIN_VCCINT 5 /**< Minimum VCCINT Data */
246 #define XADCPS_MIN_VCCAUX 6 /**< Minimum VCCAUX Data */
247 #define XADCPS_MIN_VBRAM 7 /**< Minimum VBRAM Data */
248 #define XADCPS_MAX_VCCPINT 8 /**< Maximum VCCPINT Register , Zynq */
249 #define XADCPS_MAX_VCCPAUX 9 /**< Maximum VCCPAUX Register , Zynq */
250 #define XADCPS_MAX_VCCPDRO 0xA /**< Maximum VCCPDRO Register , Zynq */
251 #define XADCPS_MIN_VCCPINT 0xC /**< Minimum VCCPINT Register , Zynq */
252 #define XADCPS_MIN_VCCPAUX 0xD /**< Minimum VCCPAUX Register , Zynq */
253 #define XADCPS_MIN_VCCPDRO 0xE /**< Minimum VCCPDRO Register , Zynq */
259 * @name Alarm Threshold(Limit) Register (ATR) indexes.
262 #define XADCPS_ATR_TEMP_UPPER 0 /**< High user Temperature */
263 #define XADCPS_ATR_VCCINT_UPPER 1 /**< VCCINT high voltage limit register */
264 #define XADCPS_ATR_VCCAUX_UPPER 2 /**< VCCAUX high voltage limit register */
265 #define XADCPS_ATR_OT_UPPER 3 /**< VCCAUX high voltage limit register */
266 #define XADCPS_ATR_TEMP_LOWER 4 /**< Upper Over Temperature limit Reg */
267 #define XADCPS_ATR_VCCINT_LOWER 5 /**< VCCINT high voltage limit register */
268 #define XADCPS_ATR_VCCAUX_LOWER 6 /**< VCCAUX low voltage limit register */
269 #define XADCPS_ATR_OT_LOWER 7 /**< Lower Over Temperature limit */
270 #define XADCPS_ATR_VBRAM_UPPER_ 8 /**< VRBAM Upper Alarm Reg, 7 Series */
271 #define XADCPS_ATR_VCCPINT_UPPER 9 /**< VCCPINT Upper Alarm Reg, Zynq */
272 #define XADCPS_ATR_VCCPAUX_UPPER 0xA /**< VCCPAUX Upper Alarm Reg, Zynq */
273 #define XADCPS_ATR_VCCPDRO_UPPER 0xB /**< VCCPDRO Upper Alarm Reg, Zynq */
274 #define XADCPS_ATR_VBRAM_LOWER 0xC /**< VRBAM Lower Alarm Reg, 7 Series */
275 #define XADCPS_ATR_VCCPINT_LOWER 0xD /**< VCCPINT Lower Alarm Reg , Zynq */
276 #define XADCPS_ATR_VCCPAUX_LOWER 0xE /**< VCCPAUX Lower Alarm Reg , Zynq */
277 #define XADCPS_ATR_VCCPDRO_LOWER 0xF /**< VCCPDRO Lower Alarm Reg , Zynq */
283 * @name Averaging to be done for the channels.
286 #define XADCPS_AVG_0_SAMPLES 0 /**< No Averaging */
287 #define XADCPS_AVG_16_SAMPLES 1 /**< Average 16 samples */
288 #define XADCPS_AVG_64_SAMPLES 2 /**< Average 64 samples */
289 #define XADCPS_AVG_256_SAMPLES 3 /**< Average 256 samples */
295 * @name Channel Sequencer Modes of operation
298 #define XADCPS_SEQ_MODE_SAFE 0 /**< Default Safe Mode */
299 #define XADCPS_SEQ_MODE_ONEPASS 1 /**< Onepass through Sequencer */
300 #define XADCPS_SEQ_MODE_CONTINPASS 2 /**< Continuous Cycling Sequencer */
301 #define XADCPS_SEQ_MODE_SINGCHAN 3 /**< Single channel -No Sequencing */
302 #define XADCPS_SEQ_MODE_SIMUL_SAMPLING 4 /**< Simultaneous sampling */
303 #define XADCPS_SEQ_MODE_INDEPENDENT 8 /**< Independent mode */
310 * @name Power Down Modes
313 #define XADCPS_PD_MODE_NONE 0 /**< No Power Down */
314 #define XADCPS_PD_MODE_ADCB 1 /**< Power Down ADC B */
315 #define XADCPS_PD_MODE_XADC 2 /**< Power Down ADC A and ADC B */
318 /**************************** Type Definitions ******************************/
321 * This typedef contains configuration information for the XADC/ADC
325 u16 DeviceId; /**< Unique ID of device */
326 u32 BaseAddress; /**< Device base address */
331 * The driver's instance data. The user is required to allocate a variable
332 * of this type for every XADC/ADC device in the system. A pointer to
333 * a variable of this type is then passed to the driver API functions.
336 XAdcPs_Config Config; /**< XAdcPs_Config of current device */
337 u32 IsReady; /**< Device is initialized and ready */
341 /***************** Macros (Inline Functions) Definitions ********************/
343 /****************************************************************************/
346 * This macro checks if the XADC device is in Event Sampling mode.
348 * @param InstancePtr is a pointer to the XAdcPs instance.
351 * - TRUE if the device is in Event Sampling Mode.
352 * - FALSE if the device is in Continuous Sampling Mode.
354 * @note C-Style signature:
355 * int XAdcPs_IsEventSamplingMode(XAdcPs *InstancePtr);
357 *****************************************************************************/
358 #define XAdcPs_IsEventSamplingModeSet(InstancePtr) \
359 (((XAdcPs_ReadInternalReg(InstancePtr, \
360 XADCPS_CFR0_OFFSET) & XADCPS_CFR0_EC_MASK) ? \
364 /****************************************************************************/
367 * This macro checks if the XADC device is in External Mux mode.
369 * @param InstancePtr is a pointer to the XAdcPs instance.
372 * - TRUE if the device is in External Mux Mode.
373 * - FALSE if the device is NOT in External Mux Mode.
375 * @note C-Style signature:
376 * int XAdcPs_IsExternalMuxMode(XAdcPs *InstancePtr);
378 *****************************************************************************/
379 #define XAdcPs_IsExternalMuxModeSet(InstancePtr) \
380 (((XAdcPs_ReadInternalReg(InstancePtr, \
381 XADCPS_CFR0_OFFSET) & XADCPS_CFR0_MUX_MASK) ? \
384 /****************************************************************************/
387 * This macro converts XADC Raw Data to Temperature(centigrades).
389 * @param AdcData is the Raw ADC Data from XADC.
391 * @return The Temperature in centigrades.
393 * @note C-Style signature:
394 * float XAdcPs_RawToTemperature(u32 AdcData);
396 *****************************************************************************/
397 #define XAdcPs_RawToTemperature(AdcData) \
398 ((((float)(AdcData)/65536.0f)/0.00198421639f ) - 273.15f)
400 /****************************************************************************/
403 * This macro converts XADC/ADC Raw Data to Voltage(volts).
405 * @param AdcData is the XADC/ADC Raw Data.
407 * @return The Voltage in volts.
409 * @note C-Style signature:
410 * float XAdcPs_RawToVoltage(u32 AdcData);
412 *****************************************************************************/
413 #define XAdcPs_RawToVoltage(AdcData) \
414 ((((float)(AdcData))* (3.0f))/65536.0f)
416 /****************************************************************************/
419 * This macro converts Temperature in centigrades to XADC/ADC Raw Data.
421 * @param Temperature is the Temperature in centigrades to be
422 * converted to XADC/ADC Raw Data.
424 * @return The XADC/ADC Raw Data.
426 * @note C-Style signature:
427 * int XAdcPs_TemperatureToRaw(float Temperature);
429 *****************************************************************************/
430 #define XAdcPs_TemperatureToRaw(Temperature) \
431 ((int)(((Temperature) + 273.15f)*65536.0f*0.00198421639f))
433 /****************************************************************************/
436 * This macro converts Voltage in Volts to XADC/ADC Raw Data.
438 * @param Voltage is the Voltage in volts to be converted to
441 * @return The XADC/ADC Raw Data.
443 * @note C-Style signature:
444 * int XAdcPs_VoltageToRaw(float Voltage);
446 *****************************************************************************/
447 #define XAdcPs_VoltageToRaw(Voltage) \
448 ((int)((Voltage)*65536.0f/3.0f))
451 /****************************************************************************/
454 * This macro is used for writing to the XADC Registers using the
457 * @param InstancePtr is a pointer to the XAdcPs instance.
461 * @note C-Style signature:
462 * void XAdcPs_WriteFifo(XAdcPs *InstancePtr, u32 Data);
464 *****************************************************************************/
465 #define XAdcPs_WriteFifo(InstancePtr, Data) \
466 XAdcPs_WriteReg((InstancePtr)->Config.BaseAddress, \
467 XADCPS_CMDFIFO_OFFSET, Data);
470 /****************************************************************************/
473 * This macro is used for reading from the XADC Registers using the
476 * @param InstancePtr is a pointer to the XAdcPs instance.
478 * @return Data read from the FIFO
480 * @note C-Style signature:
481 * u32 XAdcPs_ReadFifo(XAdcPs *InstancePtr);
483 *****************************************************************************/
484 #define XAdcPs_ReadFifo(InstancePtr) \
485 XAdcPs_ReadReg((InstancePtr)->Config.BaseAddress, \
486 XADCPS_RDFIFO_OFFSET);
489 /************************** Function Prototypes *****************************/
494 * Functions in xadcps_sinit.c
496 XAdcPs_Config *XAdcPs_LookupConfig(u16 DeviceId);
499 * Functions in xadcps.c
501 int XAdcPs_CfgInitialize(XAdcPs *InstancePtr,
502 XAdcPs_Config *ConfigPtr,
506 u32 XAdcPs_GetStatus(XAdcPs *InstancePtr);
508 u32 XAdcPs_GetAlarmOutputStatus(XAdcPs *InstancePtr);
510 void XAdcPs_StartAdcConversion(XAdcPs *InstancePtr);
512 void XAdcPs_Reset(XAdcPs *InstancePtr);
514 u16 XAdcPs_GetAdcData(XAdcPs *InstancePtr, u8 Channel);
516 u16 XAdcPs_GetCalibCoefficient(XAdcPs *InstancePtr, u8 CoeffType);
518 u16 XAdcPs_GetMinMaxMeasurement(XAdcPs *InstancePtr, u8 MeasurementType);
520 void XAdcPs_SetAvg(XAdcPs *InstancePtr, u8 Average);
521 u8 XAdcPs_GetAvg(XAdcPs *InstancePtr);
523 int XAdcPs_SetSingleChParams(XAdcPs *InstancePtr,
525 int IncreaseAcqCycles,
527 int IsDifferentialMode);
530 void XAdcPs_SetAlarmEnables(XAdcPs *InstancePtr, u16 AlmEnableMask);
531 u16 XAdcPs_GetAlarmEnables(XAdcPs *InstancePtr);
533 void XAdcPs_SetCalibEnables(XAdcPs *InstancePtr, u16 Calibration);
534 u16 XAdcPs_GetCalibEnables(XAdcPs *InstancePtr);
536 void XAdcPs_SetSequencerMode(XAdcPs *InstancePtr, u8 SequencerMode);
537 u8 XAdcPs_GetSequencerMode(XAdcPs *InstancePtr);
539 void XAdcPs_SetAdcClkDivisor(XAdcPs *InstancePtr, u8 Divisor);
540 u8 XAdcPs_GetAdcClkDivisor(XAdcPs *InstancePtr);
542 int XAdcPs_SetSeqChEnables(XAdcPs *InstancePtr, u32 ChEnableMask);
543 u32 XAdcPs_GetSeqChEnables(XAdcPs *InstancePtr);
545 int XAdcPs_SetSeqAvgEnables(XAdcPs *InstancePtr, u32 AvgEnableChMask);
546 u32 XAdcPs_GetSeqAvgEnables(XAdcPs *InstancePtr);
548 int XAdcPs_SetSeqInputMode(XAdcPs *InstancePtr, u32 InputModeChMask);
549 u32 XAdcPs_GetSeqInputMode(XAdcPs *InstancePtr);
551 int XAdcPs_SetSeqAcqTime(XAdcPs *InstancePtr, u32 AcqCyclesChMask);
552 u32 XAdcPs_GetSeqAcqTime(XAdcPs *InstancePtr);
554 void XAdcPs_SetAlarmThreshold(XAdcPs *InstancePtr, u8 AlarmThrReg, u16 Value);
555 u16 XAdcPs_GetAlarmThreshold(XAdcPs *InstancePtr, u8 AlarmThrReg);
557 void XAdcPs_EnableUserOverTemp(XAdcPs *InstancePtr);
558 void XAdcPs_DisableUserOverTemp(XAdcPs *InstancePtr);
560 void XAdcPs_SetSequencerEvent(XAdcPs *InstancePtr, int IsEventMode);
562 int XAdcPs_GetSamplingMode(XAdcPs *InstancePtr);
564 void XAdcPs_SetMuxMode(XAdcPs *InstancePtr, int MuxMode, u8 Channel);
566 void XAdcPs_SetPowerdownMode(XAdcPs *InstancePtr, u32 Mode);
568 u32 XAdcPs_GetPowerdownMode(XAdcPs *InstancePtr);
571 * Functions in xadcps_selftest.c
573 int XAdcPs_SelfTest(XAdcPs *InstancePtr);
576 * Functions in xadcps_intr.c
578 void XAdcPs_IntrEnable(XAdcPs *InstancePtr, u32 Mask);
579 void XAdcPs_IntrDisable(XAdcPs *InstancePtr, u32 Mask);
580 u32 XAdcPs_IntrGetEnabled(XAdcPs *InstancePtr);
582 u32 XAdcPs_IntrGetStatus(XAdcPs *InstancePtr);
583 void XAdcPs_IntrClear(XAdcPs *InstancePtr, u32 Mask);
590 #endif /* End of protection macro. */