adcext.h File Reference

external interface of AT91SAM7X ADC peripheral driver More...


Functions

UCHAR AdcInitUnit (UCHAR ucUnit, UCHAR ucChannel, OS_ID oiSemMsgNew, USHORT usChannelMask, ULONG ulMsgMask, ULONG ulMsgChangeMask)
 initialize a unit
UCHAR AdcInitChannel (UCHAR ucUnit, UCHAR ucChannel, struct _SAdcCfgChannel *pSCfgChannel, UCHAR ucCfgChannelCnt)
 initialize a channel of a previously initialized unit
USHORT AdcMsgUnit (UCHAR ucUnit, UCHAR ucChannel, ULONG ulMsg, USHORT usDecrement, U16 u16Timeout)
 retrieve message counters of a unit
USHORT AdcMsgChannel (UCHAR ucUnit, UCHAR ucChannel, ULONG ulMsg, USHORT usDecrement, U16 u16Timeout)
 retrieve message counters of a channel
USHORT AdcRx (UCHAR ucUnit, UCHAR ucChannel, void *pvData, USHORT usCount, U16 u16Timeout)
 retrieve (and remove) data of a channel
UCHAR AdcWait (UCHAR ucUnit, UCHAR ucChannel, U16 u16Timeout)
 pend for ready data of a channel

Detailed Description

external interface of AT91SAM7X ADC peripheral driver

Function Documentation

UCHAR AdcInitChannel ( UCHAR  ucUnit,
UCHAR  ucChannel,
struct _SAdcCfgChannel *  pSCfgChannel,
UCHAR  ucCfgChannelCnt 
)

initialize a channel of a previously initialized unit

Parameters:
ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h)
ucChannel (optional, set to 0 as default) offset to add to channel number in array element of struct _SAdcCfgChannel
*pSCfgChannel pointer to array of struct _SAdcCfgChannel which contains the channel(s)s configuration
ucCfgChannelCnt count of channels to configure from array of struct _SAdcCfgChannel
Returns:
> 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:

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:

UCHAR AdcInitUnit ( UCHAR  ucUnit,
UCHAR  ucChannel,
OS_ID  oiSemMsgNew,
USHORT  usChannelMask,
ULONG  ulMsgMask,
ULONG  ulMsgChangeMask 
)

initialize a unit

Parameters:
ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h)
ucChannel (unused, set 0) number of the sub-channel for units tree(s)
oiSemMsgNew (optional, set to NULL as default) OS_ID of pre-initialized (to 0!) semaphore to send/give for matching messages
usChannelMask (optional, set to 0 as default) triggered channels to take into account for unit semaphore triggering
ulMsgMask (optional, set to NULL as default) and-mask to include triggered channels' messages for unit semaphore triggering
ulMsgChangeMask (optional, set to NULL as default) mask to suppress (bit set) same message triggering and to trigger only for a message change
Returns:
> 0 for success, == 0 for failure
Note:
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

USHORT AdcMsgChannel ( UCHAR  ucUnit,
UCHAR  ucChannel,
ULONG  ulMsg,
USHORT  usDecrement,
U16  u16Timeout 
)

retrieve message counters of a channel

Parameters:
ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h)
ucChannel number of the channel
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)
usDecrement decrement count (0 for no decrement) for selected message bits (var type's max value USHRT_MAX just clears the counter(s))
u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks)
Returns:
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 AdcMsgUnit ( UCHAR  ucUnit,
UCHAR  ucChannel,
ULONG  ulMsg,
USHORT  usDecrement,
U16  u16Timeout 
)

retrieve message counters of a unit

Parameters:
ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h)
ucChannel (unused, set 0) number of the sub-channel for units tree(s)
ulMsg message bits to retrieve (refer to AT91SAM7X manual 35.6.6 page 498: ADC_SR and trigger message bits of adc.h)
usDecrement decrement count (0 for no decrement) for selected message bits (var type's max value USHRT_MAX just clears the counter(s))
u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks)
Returns:
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 AdcRx ( UCHAR  ucUnit,
UCHAR  ucChannel,
void *  pvData,
USHORT  usCount,
U16  u16Timeout 
)

retrieve (and remove) data of a channel

Parameters:
ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h)
ucChannel number of the channel
pvData pointer to data storage (type ADC_MEMITEMTYPE of adc.h)
usCount count of data to retrieve (only 1 allowed here)
u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks)
Returns:
> 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

UCHAR AdcWait ( UCHAR  ucUnit,
UCHAR  ucChannel,
U16  u16Timeout 
)

pend for ready data of a channel

Parameters:
ucUnit number of the unit (descriptor array index [not the hardware index] of adcdev.h)
ucChannel number of the channel
u16Timeout maximum cpu-load free resource pending time before any resource claim is canceled by the rtos (in ticks)
Returns:
> 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

Generated on Wed Jun 27 12:29:31 2012 for AT91SAM7X Framework by  doxygen 1.5.7.1