Buffer management services. More...

Collaboration diagram for Buffer management services:

Functions
int	a4l_buf_prepare_absput (struct a4l_subdevice *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 (struct a4l_subdevice *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 (struct a4l_subdevice *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 (struct a4l_subdevice *subd, unsigned long count)
	Set the count of data sent to the buffer during the last completed DMA shots. More...

int	a4l_buf_put (struct a4l_subdevice subd, void bufdata, unsigned long count)
	Copy some data from the device driver to the buffer. More...

int	a4l_buf_prepare_absget (struct a4l_subdevice *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 (struct a4l_subdevice *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 (struct a4l_subdevice *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 (struct a4l_subdevice *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 (struct a4l_subdevice subd, void bufdata, unsigned long count)
	Copy some data from the buffer to the device driver. More...

int	a4l_buf_evt (struct a4l_subdevice *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 (struct a4l_subdevice *subd)
	Get the data amount available in the Analogy buffer. More...

struct a4l_cmd_desc *	a4l_get_cmd (struct a4l_subdevice *subd)
	Get the current Analogy command descriptor. More...

int	a4l_get_chan (struct a4l_subdevice *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

◆ a4l_buf_commit_absget()

int a4l_buf_commit_absget	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_commit_absput()

int a4l_buf_commit_absput	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_commit_get()

int a4l_buf_commit_get	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_commit_put()

int a4l_buf_commit_put	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_count()

unsigned long a4l_buf_count ( struct a4l_subdevice * 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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_evt()

int a4l_buf_evt	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_get()

int a4l_buf_get	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_prepare_absget()

int a4l_buf_prepare_absget	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_prepare_absput()

int a4l_buf_prepare_absput	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_prepare_get()

int a4l_buf_prepare_get	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_prepare_put()

int a4l_buf_prepare_put	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_buf_put()

int a4l_buf_put	(	struct a4l_subdevice *	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.

References A4L_SUBD_BUSY_NR, a4l_subdevice::buf, and a4l_subdevice::status.

◆ a4l_get_chan()

int a4l_get_chan ( struct a4l_subdevice * subd )

Get the channel index according to its type.

Parameters

[in] subd Subdevice descriptor structure

Returns: the channel index.

References A4L_CHAN_GLOBAL_CHANDESC, a4l_get_cmd(), a4l_subdevice::buf, a4l_subdevice::chan_desc, a4l_cmd_desc::chan_descs, a4l_channels_desc::chans, a4l_channels_desc::mode, a4l_channel::nb_bits, and a4l_cmd_desc::nb_chan.

◆ a4l_get_cmd()

struct a4l_cmd_desc* a4l_get_cmd ( struct a4l_subdevice * subd )

Get the current Analogy command descriptor.

Parameters

[in] subd Subdevice descriptor structure

Returns: the command descriptor.

Referenced by a4l_get_chan().

Functions

Detailed Description

Function Documentation

◆ a4l_buf_commit_absget()

◆ a4l_buf_commit_absput()

◆ a4l_buf_commit_get()

◆ a4l_buf_commit_put()

◆ a4l_buf_count()

◆ a4l_buf_evt()

◆ a4l_buf_get()

◆ a4l_buf_prepare_absget()

◆ a4l_buf_prepare_absput()

◆ a4l_buf_prepare_get()

◆ a4l_buf_prepare_put()

◆ a4l_buf_put()

◆ a4l_get_chan()

◆ a4l_get_cmd()