|
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_t * | a4l_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:
- a4l_buf_prepare_(abs)put() and a4l_buf_commit_(abs)put()
- a4l_buf_prepare_(abs)get() and a4l_buf_commit_(abs)get()
- a4l_buf_put()
- a4l_buf_get()
- a4l_buf_evt().
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:
- If some DMA controller is available, there is no need to make the driver copy the acquired data into the asynchronous buffer, the DMA controller must directly trigger DMA shots into / from the buffer. In that case, a function a4l_buf_prepare_*() must be used so as to set up the DMA transfer and a function a4l_buf_commit_*() has to be called to complete the transfer().
- For DMA controllers which need to work with global counter (the transfered data count since the beginning of the acquisition), the functions a4l_buf_*_abs_*() have been made available.
- If no DMA controller is available, the driver has to perform the copy between the hardware component and the asynchronous buffer. In such cases, the functions a4l_buf_get() and a4l_buf_put() are useful.
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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice 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] subd Subdevice descriptor structure [in] evts Some 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] subd Subdevice descriptor structure [in] bufdata The data buffer to copy into the Analogy buffer [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] count The 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] subd Subdevice descriptor structure [in] bufdata The data buffer to copy into the Analogy buffer [in] count The 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] subd Subdevice descriptor structure
- Returns
- the channel index.
| a4l_cmd_t* a4l_get_cmd | ( | a4l_subd_t * | subd | ) |
Get the current Analogy command descriptor.
- Parameters
-
[in] subd Subdevice descriptor structure
- Returns
- the command descriptor.
