Xenomai API  2.6.5
Buffer management services
Collaboration diagram for Buffer management services:

Functions

int a4l_buf_prepare_absput (a4l_subd_t *subd, unsigned long count)
 Update the absolute count of data sent from the device to the buffer since the start of the acquisition and after the next DMA shot. More...
 
int a4l_buf_commit_absput (a4l_subd_t *subd, unsigned long count)
 Set the absolute count of data which was sent from the device to the buffer since the start of the acquisition and until the last DMA shot. More...
 
int a4l_buf_prepare_put (a4l_subd_t *subd, unsigned long count)
 Set the count of data which is to be sent to the buffer at the next DMA shot. More...
 
int a4l_buf_commit_put (a4l_subd_t *subd, unsigned long count)
 Set the count of data sent to the buffer during the last completed DMA shots. More...
 
int a4l_buf_put (a4l_subd_t *subd, void *bufdata, unsigned long count)
 Copy some data from the device driver to the buffer. More...
 
int a4l_buf_prepare_absget (a4l_subd_t *subd, unsigned long count)
 Update the absolute count of data sent from the buffer to the device since the start of the acquisition and after the next DMA shot. More...
 
int a4l_buf_commit_absget (a4l_subd_t *subd, unsigned long count)
 Set the absolute count of data which was sent from the buffer to the device since the start of the acquisition and until the last DMA shot. More...
 
int a4l_buf_prepare_get (a4l_subd_t *subd, unsigned long count)
 Set the count of data which is to be sent from the buffer to the device at the next DMA shot. More...
 
int a4l_buf_commit_get (a4l_subd_t *subd, unsigned long count)
 Set the count of data sent from the buffer to the device during the last completed DMA shots. More...
 
int a4l_buf_get (a4l_subd_t *subd, void *bufdata, unsigned long count)
 Copy some data from the buffer to the device driver. More...
 
int a4l_buf_evt (a4l_subd_t *subd, unsigned long evts)
 Signal some event(s) to a user-space program involved in some read / write operation. More...
 
unsigned long a4l_buf_count (a4l_subd_t *subd)
 Get the data amount available in the Analogy buffer. More...
 
a4l_cmd_ta4l_get_cmd (a4l_subd_t *subd)
 Get the current Analogy command descriptor. More...
 
int a4l_get_chan (a4l_subd_t *subd)
 Get the channel index according to its type. More...
 

Detailed Description

Buffer management services

The buffer is the key component of the Analogy infrastructure. It manages transfers between the user-space and the Analogy drivers thanks to generic functions which are described hereafter. Thanks to the buffer subsystem, the driver developer does not have to care about the way the user program retrieves or sends data.

To write a classical char driver, the developer has to fill a fops structure so as to provide transfer operations to the user program (read, write, ioctl and mmap if need be).

The Analogy infrastructure manages the whole interface with the userspace; the common read, write, mmap, etc. callbacks are generic Analogy functions. These functions manage (and perform, if need be) tranfers between the user-space and an asynchronous buffer thanks to lockless mechanisms.

Consequently, the developer has to use the proper buffer functions in order to write / read acquired data into / from the asynchronous buffer.

Here are listed the functions:

The functions count might seem high; however, the developer needs a few of them to write a driver. Having so many functions enables to manage any transfer cases:

Function Documentation

int a4l_buf_commit_absget ( a4l_subd_t subd,
unsigned long  count 
)

Set the absolute count of data which was sent from the buffer to the device since the start of the acquisition and until the last DMA shot.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe data count transferred to the device during the last DMA shot plus the data count which have been sent since the beginning of the acquisition
Returns
0 on success, otherwise negative error code.
int a4l_buf_commit_absput ( a4l_subd_t subd,
unsigned long  count 
)

Set the absolute count of data which was sent from the device to the buffer since the start of the acquisition and until the last DMA shot.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe data count transferred to the buffer during the last DMA shot plus the data count which have been sent / retrieved since the beginning of the acquisition
Returns
0 on success, otherwise negative error code.
int a4l_buf_commit_get ( a4l_subd_t subd,
unsigned long  count 
)

Set the count of data sent from the buffer to the device during the last completed DMA shots.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe amount of data transferred
Returns
0 on success, otherwise negative error code.
int a4l_buf_commit_put ( a4l_subd_t subd,
unsigned long  count 
)

Set the count of data sent to the buffer during the last completed DMA shots.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe amount of data transferred
Returns
0 on success, otherwise negative error code.
unsigned long a4l_buf_count ( a4l_subd_t subd)

Get the data amount available in the Analogy buffer.

Parameters
[in]subdSubdevice descriptor structure
Returns
the amount of data available in the Analogy buffer.
int a4l_buf_evt ( a4l_subd_t subd,
unsigned long  evts 
)

Signal some event(s) to a user-space program involved in some read / write operation.

The function a4l_buf_evt() is useful in many cases:

  • To wake-up a process waiting for some data to read.
  • To wake-up a process waiting for some data to write.
  • To notify the user-process an error has occured during the acquistion.
Parameters
[in]subdSubdevice descriptor structure
[in]evtsSome specific event to notify:
  • A4L_BUF_ERROR to indicate some error has occured during the transfer
  • A4L_BUF_EOA to indicate the acquisition is complete (this event is automatically set, it should not be used).
Returns
0 on success, otherwise negative error code.
int a4l_buf_get ( a4l_subd_t subd,
void *  bufdata,
unsigned long  count 
)

Copy some data from the buffer to the device driver.

The function a4l_buf_get() must copy data coming from the Analogy buffer to some acquisition device. This ring-buffer is an intermediate area between the device driver and the user-space program, which is supposed to provide the data to send to the device.

Parameters
[in]subdSubdevice descriptor structure
[in]bufdataThe data buffer to copy into the Analogy buffer
[in]countThe amount of data to copy
Returns
0 on success, otherwise negative error code.
int a4l_buf_prepare_absget ( a4l_subd_t subd,
unsigned long  count 
)

Update the absolute count of data sent from the buffer to the device since the start of the acquisition and after the next DMA shot.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(absg)et() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe data count to be transferred during the next DMA shot plus the data count which have been copied since the start of the acquisition
Returns
0 on success, otherwise negative error code.
int a4l_buf_prepare_absput ( a4l_subd_t subd,
unsigned long  count 
)

Update the absolute count of data sent from the device to the buffer since the start of the acquisition and after the next DMA shot.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(absg)et() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe data count to be transferred during the next DMA shot plus the data count which have been copied since the start of the acquisition
Returns
0 on success, otherwise negative error code.
int a4l_buf_prepare_get ( a4l_subd_t subd,
unsigned long  count 
)

Set the count of data which is to be sent from the buffer to the device at the next DMA shot.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe data count to be transferred
Returns
0 on success, otherwise negative error code.
int a4l_buf_prepare_put ( a4l_subd_t subd,
unsigned long  count 
)

Set the count of data which is to be sent to the buffer at the next DMA shot.

The functions a4l_buf_prepare_(abs)put(), a4l_buf_commit_(abs)put(), a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get() have been made available for DMA transfers. In such situations, no data copy is needed between the Analogy buffer and the device as some DMA controller is in charge of performing data shots from / to the Analogy buffer. However, some pointers still have to be updated so as to monitor the tranfers.

Parameters
[in]subdSubdevice descriptor structure
[in]countThe data count to be transferred
Returns
0 on success, otherwise negative error code.
int a4l_buf_put ( a4l_subd_t subd,
void *  bufdata,
unsigned long  count 
)

Copy some data from the device driver to the buffer.

The function a4l_buf_put() must copy data coming from some acquisition device to the Analogy buffer. This ring-buffer is an intermediate area between the device driver and the user-space program, which is supposed to recover the acquired data.

Parameters
[in]subdSubdevice descriptor structure
[in]bufdataThe data buffer to copy into the Analogy buffer
[in]countThe amount of data to copy
Returns
0 on success, otherwise negative error code.
int a4l_get_chan ( a4l_subd_t subd)

Get the channel index according to its type.

Parameters
[in]subdSubdevice descriptor structure
Returns
the channel index.
a4l_cmd_t* a4l_get_cmd ( a4l_subd_t subd)

Get the current Analogy command descriptor.

Parameters
[in]subdSubdevice descriptor structure
Returns
the command descriptor.