//! external interface of AT91SAM7X ADC peripheral driver /** \file adcext.h */ //---------------------------------------------------------------------------- // A T 9 1 C P U S U P P O R T L I B R A R Y //---------------------------------------------------------------------------- // Name: SYKAM/CPU/AT91/ADC/ADCEXT.H // Purpose: AT91 CPU SUPPORT // Author: hschoettner //---------------------------------------------------------------------------- // 2011-05-19 initial version // 2011-05-25 added message functions AdcMsgUnit & AdcMsgChannel // 2011-07-07 renamed oiSemMsgEnh to oiSemMsgNew in AdcInitUnit prototype // 2011-07-12 added ulMsgChangeMask param to AdcInitUnit prototype // 2011-10-19 added public doxygen documentation // 2011-10-26 added public doxygen documentation //---------------------------------------------------------------------------- // Copyright (c) 2008-2011 Sykam GmbH. All rights reserved. //---------------------------------------------------------------------------- #ifndef SYKAM_CPU_AT91_ADC_ADCEXT_H #define SYKAM_CPU_AT91_ADC_ADCEXT_H 1 // Prototypes //! initialize a unit /** \param ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h) \param ucChannel (unused, set 0) number of the sub-channel for units tree(s) \param oiSemMsgNew (optional, set to NULL as default) OS_ID of pre-initialized (to 0!) semaphore to send/give for matching messages \param usChannelMask (optional, set to 0 as default) triggered channels to take into account for unit semaphore triggering \param ulMsgMask (optional, set to NULL as default) and-mask to include triggered channels' messages for unit semaphore triggering \param ulMsgChangeMask (optional, set to NULL as default) mask to suppress (bit set) same message triggering and to trigger only for a message change \return > 0 for success, == 0 for failure \note - 3 tasks are spanned by this function - message bits are composed of software bits (trigger message bits of adc.h) and filtered hardware bits (refer to AT91SAM7X manual 35.6.6 page 498: ADC_SR) by u32IrqMsg of _SAdcRO Example: merge all channel semaphores to a single unit semaphore you need:
- configure ulMsgMask & ulMsgChangeMask of all required channels (#AdcInitChannel) - select channels to merge: usChannelMask= AT91C_ADC_CHx | AT91C_ADC_CHy | ... - set unit message filter: ulMsgMask= AdcCfgChannel[x].ulMsgMask | AdcCfgChannel[y].ulMsgMask | ... - set unit change mask: ulMsgChangeMask= (0xFFFFFFFF & AdcCfgChannel[x].ulMsgChangeMask) & (0xFFFFFFFF & AdcCfgChannel[y].ulMsgChangeMask) & ... - assign #OS_ID of your pre-initialized (with 0!) semaphore: oiSemMsgNew= ... Manual reference(s):
AT91SAM7X manual 35.6.6 page 498: ADC_SR
*/ UCHAR AdcInitUnit (UCHAR ucUnit, UCHAR ucChannel, OS_ID oiSemMsgNew, USHORT usChannelMask, ULONG ulMsgMask, ULONG ulMsgChangeMask); //! initialize a channel of a previously initialized unit /** \param ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h) \param ucChannel (optional, set to 0 as default) offset to add to channel number in array element of struct _SAdcCfgChannel \param *pSCfgChannel pointer to array of struct _SAdcCfgChannel which contains the channel(s)s configuration \param ucCfgChannelCnt count of channels to configure from array of struct _SAdcCfgChannel \return > 0 for success, == 0 for failure \note - ucChannel specifies here an optional offset [not an absolute index] Example: send/give the specified semaphore for every limit band change to below/above and min/max but for every sampled value when inside the normal band:
- ulMsgMask= #ADC_TRG_NORMAL | #ADC_TRG_MAX | #ADC_TRG_MIN | #ADC_TRG_ABOVE | #ADC_TRG_BELOW - ulMsgChangeMask= #ADC_TRG_MAX | #ADC_TRG_MIN | #ADC_TRG_ABOVE | #ADC_TRG_BELOW Example: send/give the specified semaphore for every sampled value when outside the normal band but for normal band itsself only when changed to it:
- ulMsgMask= #ADC_TRG_NORMAL | #ADC_TRG_MAX | #ADC_TRG_MIN | #ADC_TRG_ABOVE | #ADC_TRG_BELOW - ulMsgChangeMask= #ADC_TRG_NORMAL */ UCHAR AdcInitChannel(UCHAR ucUnit, UCHAR ucChannel, struct _SAdcCfgChannel *pSCfgChannel, UCHAR ucCfgChannelCnt); //! retrieve message counters of a unit /** \param ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h) \param ucChannel (unused, set 0) number of the sub-channel for units tree(s) \param ulMsg message bits to retrieve (refer to AT91SAM7X manual 35.6.6 page 498: ADC_SR and trigger message bits of adc.h) \param usDecrement decrement count (0 for no decrement) for selected message bits (var type's max value #USHRT_MAX just clears the counter(s)) \param u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks) \return summarized count of all selected message bits before decrementing \note - when selecting MORE than ONE message bit, the true summarized count may be higher than the return value which is limited to the return data type's max - message bits are composed of software bits (trigger message bits of adc.h) and filtered hardware bits (refer to AT91SAM7X manual 35.6.6 page 498: ADC_SR) by u32IrqMsg of _SAdcRO \remarks - this function is helpful to determine the reason for the sent/given "news semaphore" when more than one message is masked Manual reference(s):
AT91SAM7X manual 35.6.6 page 498: ADC_SR
*/ USHORT AdcMsgUnit (UCHAR ucUnit, UCHAR ucChannel, ULONG ulMsg, USHORT usDecrement, U16 u16Timeout); //! retrieve message counters of a channel /** \param ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h) \param ucChannel number of the channel \param ulMsg message bits to retrieve count for (refer to AT91SAM7X manual 35.6.6 page 498: ADC_SR and trigger message bits of adc.h) \param usDecrement decrement count (0 for no decrement) for selected message bits (var type's max value #USHRT_MAX just clears the counter(s)) \param u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks) \return summarized count of all selected message bits before decrementing \note - when selecting MORE than ONE message bit, the true summarized count may be higher than the return value which is limited to the return data type's max - message bits are composed of software bits (trigger message bits of adc.h) and filtered hardware bits (refer to AT91SAM7X manual 35.6.6 page 498: ADC_SR) by u32IrqMsg of _SAdcRO \remarks this function is helpful to
- determine the reason for the sent/given "news semaphore" when more than one message is masked before any data retrival using #AdcRx - track count of messages just after a normal data retrival using #AdcRx for easier debugging and verification Manual reference(s):
AT91SAM7X manual 35.6.6 page 498: ADC_SR
*/ USHORT AdcMsgChannel (UCHAR ucUnit, UCHAR ucChannel, ULONG ulMsg, USHORT usDecrement, U16 u16Timeout); //! retrieve (and remove) data of a channel /** \param ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h) \param ucChannel number of the channel \param pvData pointer to data storage (type #ADC_MEMITEMTYPE of adc.h) \param usCount count of data to retrieve (only 1 allowed here) \param u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks) \return > 0 for success, == 0 for failure \note - because the adc driver does NOT buffer data the 2nd retrieve faster than the sample interval u16CycleRxMS of _SAdcRO will fail - for checking data is ready use AdcWait */ USHORT AdcRx (UCHAR ucUnit, UCHAR ucChannel, void *pvData, USHORT usCount, U16 u16Timeout); //! pend for ready data of a channel /** \param ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h) \param ucChannel number of the channel \param u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks) \return > 0 for success, == 0 for failure \note - because the adc driver does NOT buffer data the 2nd retrieve faster than the sample interval u16CycleRxMS of _SAdcRO will fail - checking for data ready may be called faster than the sample interval u16CycleRxMS of _SAdcRO */ UCHAR AdcWait (UCHAR ucUnit, UCHAR ucChannel, U16 u16Timeout); #endif