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.
int	a4l_snd_cancel (a4l_desc_t *dsc, unsigned int idx_subd)
	Cancel an asynchronous acquisition.
int	a4l_set_bufsize (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long size)
	Change the size of the asynchronous buffer.
int	a4l_get_bufsize (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long *size)
	Get the size of the asynchronous buffer.
int	a4l_mark_bufrw (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long cur, unsigned long *new)
	Update the asynchronous buffer state.
int	a4l_poll (a4l_desc_t *dsc, unsigned int idx_subd, unsigned long ms_timeout)
	Get the available data count.
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.

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) & 0x03) << 24)
	Reference definition macro.
#define	FLAGS(a)   ((a) & CR_FLAGS_MASK)
	Flags definition macro.
#define	PACK(a, b, c)   (a | RNG(b) | AREF(c))
	Channel + range + reference definition macro.
#define	PACK_FLAGS(a, b, c, d)   (PACK(a, b, 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

a4l_get_bufsize()

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]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	idx_subd	Index of the concerned subdevice
[out]	size	Buffer 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.

a4l_mark_bufrw()

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]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	idx_subd	Index of the concerned subdevice
[in]	cur	Amount of consumed data
[out]	new	Amount 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.

a4l_mmap()

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]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	idx_subd	Index of the concerned subdevice
[in]	size	Size of the buffer to map
[out]	ptr	Address 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.

a4l_poll()

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

Get the available data count.

Parameters

[in]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	idx_subd	Index of the concerned subdevice
[in]	ms_timeout	The 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_poll(), and a4l_descriptor::fd.

Referenced by a4l_async_read(), a4l_async_write(), and a4l_poll().

a4l_set_bufsize()

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]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	idx_subd	Index of the concerned subdevice
[in]	size	New 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.

a4l_snd_cancel()

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]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	idx_subd	Subdevice 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.

a4l_snd_command()

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]	dsc	Device descriptor filled by a4l_open() (and optionally a4l_fill_desc())
[in]	cmd	Command 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.