Xenomai API  2.6.5
Data Structures | Functions
Asynchronous acquisition API
Analogy API. » Library API. » Level 1 API
Collaboration diagram for Asynchronous acquisition API:

Data Structures

struct  a4l_cmd_desc
 Structure describing the asynchronous instruction. More...
 

Functions

int a4l_snd_command (a4l_desc_t *dsc, a4l_cmd_t *cmd)
 Send a command to an Analoy device. More...
 
int a4l_snd_cancel (a4l_desc_t *dsc, unsigned int idx_subd)
 Cancel an asynchronous acquisition. More...
 
int a4l_set_bufsize (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long size)
 Change the size of the asynchronous buffer. More...
 
int a4l_get_bufsize (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long *size)
 Get the size of the asynchronous buffer. More...
 
int a4l_mark_bufrw (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long cur, unsigned long *new)
 Update the asynchronous buffer state. More...
 
int a4l_poll (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long ms_timeout)
 Get the available data count. More...
 
int a4l_mmap (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long size, void **ptr)
 Map the asynchronous ring-buffer into a user-space. More...
 

ANALOGY_CMD_xxx

Common command flags definitions

#define A4L_CMD_SIMUL   0x1
 Do not execute the command, just check it.
 
#define A4L_CMD_BULK   0x2
 Perform data recovery / transmission in bulk mode.
 
#define A4L_CMD_WRITE   0x4
 Perform a command which will write data to the device.
 

TRIG_xxx

Command triggers flags definitions

#define TRIG_NONE   0x00000001
 Never trigger.
 
#define TRIG_NOW   0x00000002
 Trigger now + N ns.
 
#define TRIG_FOLLOW   0x00000004
 Trigger on next lower level trig.
 
#define TRIG_TIME   0x00000008
 Trigger at time N ns.
 
#define TRIG_TIMER   0x00000010
 Trigger at rate N ns.
 
#define TRIG_COUNT   0x00000020
 Trigger when count reaches N.
 
#define TRIG_EXT   0x00000040
 Trigger on external signal N.
 
#define TRIG_INT   0x00000080
 Trigger on analogy-internal signal N.
 
#define TRIG_OTHER   0x00000100
 Driver defined trigger.
 
#define TRIG_WAKE_EOS   0x0020
 Wake up on end-of-scan.
 
#define TRIG_ROUND_MASK   0x00030000
 Trigger not implemented yet.
 
#define TRIG_ROUND_NEAREST   0x00000000
 Trigger not implemented yet.
 
#define TRIG_ROUND_DOWN   0x00010000
 Trigger not implemented yet.
 
#define TRIG_ROUND_UP   0x00020000
 Trigger not implemented yet.
 
#define TRIG_ROUND_UP_NEXT   0x00030000
 Trigger not implemented yet.
 

Channel macros

Specific precompilation macros and constants useful for the channels descriptors tab located in the command structure

#define CHAN(a)   ((a) & 0xffff)
 Channel indication macro.
 
#define RNG(a)   (((a) & 0xff) << 16)
 Range definition macro.
 
#define AREF(a)   (((a) & 0xf) << 24)
 Reference definition macro.
 
#define FLAGS(a)   ((a) & CR_FLAGS_MASK)
 Flags definition macro.
 
#define PACK(a, b, c)   (CHAN(a) | RNG(b) | AREF(c))
 Channel + range + reference definition macro.
 
#define PACK_FLAGS(a, b, c, d)   (CHAN(a) | RNG(b) | AREF(c) | FLAGS(d))
 Channel + range + reference + flags definition macro.
 
#define AREF_GROUND   0x00
 Analog reference is analog ground.
 
#define AREF_COMMON   0x01
 Analog reference is analog common.
 
#define AREF_DIFF   0x02
 Analog reference is differential.
 
#define AREF_OTHER   0x03
 Analog reference is undefined.
 

Detailed Description

Function Documentation

int a4l_get_bufsize ( a4l_desc_t *  dsc,
unsigned int  idx_subd,
unsigned long *  size 
)

Get the size of the asynchronous buffer.

During asynchronous acquisition, a ring-buffer enables the transfers from / to user-space. Functions like a4l_read() or a4l_write() recovers / sends data through this intermediate buffer. Please note, there is one ring-buffer per subdevice capable of asynchronous acquisition. By default, each buffer size is set to 64 KB.

Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]idx_subdIndex of the concerned subdevice
[out]sizeBuffer size
Returns
0 on success. Otherwise:
  • -EINVAL is returned if some argument is missing or wrong (Please, type "dmesg" for more info)
  • -EFAULT is returned if a user <-> kernel transfer went wrong

References a4l_descriptor::fd.

int a4l_mark_bufrw ( a4l_desc_t *  dsc,
unsigned int  idx_subd,
unsigned long  cur,
unsigned long *  new 
)

Update the asynchronous buffer state.

When the mapping of the asynchronous ring-buffer (thanks to a4l_mmap() is disabled, common read / write syscalls have to be used. In input case, a4l_read() must be used for:

  • the retrieval of the acquired data.
  • the notification to the Analogy layer that the acquired data have been consumed, then the area in the ring-buffer which was containing becomes available. In output case, a4l_write() must be called to:
  • send some data to the Analogy layer.
  • signal the Analogy layer that a chunk of data in the ring-buffer must be used by the driver.

In mmap configuration, these features are provided by unique function named a4l_mark_bufrw(). In input case, a4l_mark_bufrw() can :

  • recover the count of data newly available in the ring-buffer.
  • notify the Analogy layer how many bytes have been consumed. In output case, a4l_mark_bufrw() can:
  • recover the count of data available for writing.
  • notify Analogy that some bytes have been written.
Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]idx_subdIndex of the concerned subdevice
[in]curAmount of consumed data
[out]newAmount of available data
Returns
0 on success. Otherwise:
  • -EINVAL is returned if some argument is missing or wrong; the descriptor and the new pointer should be checked; check also the kernel log ("dmesg")
  • -EFAULT is returned if a user <-> kernel transfer went wrong

References a4l_descriptor::fd.

int a4l_mmap ( a4l_desc_t *  dsc,
unsigned int  idx_subd,
unsigned long  size,
void **  ptr 
)

Map the asynchronous ring-buffer into a user-space.

Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]idx_subdIndex of the concerned subdevice
[in]sizeSize of the buffer to map
[out]ptrAddress of the pointer containing the assigned address on return
Returns
0 on success. Otherwise:
  • -EINVAL is returned if some argument is missing or wrong, the descriptor and the pointer should be checked; check also the kernel log
  • -EPERM is returned if the function is called in an RT context or if the buffer to resize is mapped in user-space (Please, type "dmesg" for more info)
  • -EFAULT is returned if a user <-> kernel transfer went wrong
  • -EBUSY is returned if the buffer is already mapped in user-space

References a4l_descriptor::fd.

int a4l_poll ( a4l_desc_t *  dsc,
unsigned int  idx_subd,
unsigned long  ms_timeout 
)

Get the available data count.

Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]idx_subdIndex of the concerned subdevice
[in]ms_timeoutThe number of miliseconds to wait for some data to be available. Passing A4L_INFINITE causes the caller to block indefinitely until some data is available. Passing A4L_NONBLOCK causes the function to return immediately without waiting for any available data
Returns
the available data count. Otherwise:
  • -EINVAL is returned if some argument is missing or wrong (Please, type "dmesg" for more info)
  • -EFAULT is returned if a user <-> kernel transfer went wrong
  • -EINTR is returned if calling task has been unblocked by a signal

References a4l_descriptor::fd.

Referenced by a4l_async_read(), and a4l_async_write().

int a4l_set_bufsize ( a4l_desc_t *  dsc,
unsigned int  idx_subd,
unsigned long  size 
)

Change the size of the asynchronous buffer.

During asynchronous acquisition, a ring-buffer enables the transfers from / to user-space. Functions like a4l_read() or a4l_write() recovers / sends data through this intermediate buffer. The function a4l_set_bufsize() can change the size of the ring-buffer. Please note, there is one ring-buffer per subdevice capable of asynchronous acquisition. By default, each buffer size is set to 64 KB.

Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]idx_subdIndex of the concerned subdevice
[in]sizeNew buffer size, the maximal tolerated value is 16MB (A4L_BUF_MAXSIZE)
Returns
0 on success. Otherwise:
  • -EINVAL is returned if the analogy descriptor is not correct or if some argument is missing or wrong (Please, type "dmesg" for more info)
  • -EPERM is returned if the function is called in an RT context or if the buffer to resize is mapped in user-space (Please, type "dmesg" for more info)
  • -EFAULT is returned if a user <-> kernel transfer went wrong
  • -EBUSY is returned if the selected subdevice is already processing an asynchronous operation
  • -ENOMEM is returned if the system is out of memory

References a4l_sys_bufcfg(), and a4l_descriptor::fd.

int a4l_snd_cancel ( a4l_desc_t *  dsc,
unsigned int  idx_subd 
)

Cancel an asynchronous acquisition.

The function a4l_snd_cancel() is devoted to stop an asynchronous acquisition configured thanks to an Analogy command.

Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]idx_subdSubdevice index
Returns
0 on success. Otherwise:
  • -EINVAL is returned if some argument is missing or wrong (Please, type "dmesg" for more info)
  • -EIO is returned if the selected subdevice does not support asynchronous operation

References a4l_descriptor::fd.

int a4l_snd_command ( a4l_desc_t *  dsc,
a4l_cmd_t *  cmd 
)

Send a command to an Analoy device.

The function a4l_snd_command() triggers asynchronous acquisition.

Parameters
[in]dscDevice descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]cmdCommand structure
Returns
0 on success. Otherwise:
  • -EINVAL is returned if some argument is missing or wrong (Please, type "dmesg" for more info)
  • -ENOMEM is returned if the system is out of memory
  • -EFAULT is returned if a user <-> kernel transfer went wrong
  • -EIO is returned if the selected subdevice cannot handle command
  • -EBUSY is returned if the selected subdevice is already processing an asynchronous operation

References a4l_descriptor::fd.