Descriptor Syscall API

Collaboration diagram for Descriptor Syscall API:

Data Structures
struct	a4l_descriptor
	Structure containing device-information useful to users. More...

Functions
int	a4l_sys_desc (int fd, a4l_desc_t *dsc, int pass)
	Get a descriptor on an attached device. More...

ANALOGY_xxx_DESC
Constants used as argument so as to define the description depth to recover
#define	A4L_BSC_DESC   0x0
	BSC stands for basic descriptor (device data)
#define	A4L_CPLX_DESC   0x1
	CPLX stands for complex descriptor (subdevice + channel + range data)

Detailed Description

Function Documentation

a4l_sys_desc()

int a4l_sys_desc	(	int	fd,
		a4l_desc_t *	dsc,
		int	pass
	)

Get a descriptor on an attached device.

Once the device has been attached, the function a4l_get_desc() retrieves various information on the device (subdevices, channels, ranges, etc.). The function a4l_get_desc() can be called twice:

• The first time, almost all the fields, except sbdata, are set (board_name, nb_subd, idx_read_subd, idx_write_subd, magic, sbsize); the last field , sbdata, is supposed to be a pointer on a buffer, which size is defined by the field sbsize.
• The second time, the buffer pointed by sbdata is filled with data about the subdevices, the channels and the ranges.

Between the two calls, an allocation must be performed in order to recover a buffer large enough to contain all the data. These data are set up according a root-leaf organization (device -> subdevice -> channel -> range). They cannot be accessed directly; specific functions are available so as to retrieve them:

• a4l_get_subdinfo() to get some subdevice's characteristics.
• a4l_get_chaninfo() to get some channel's characteristics.
• a4l_get_rnginfo() to get some range's characteristics.

Parameters

[in]	fd	Driver file descriptor
[out]	dsc	Device descriptor
[in]	pass	Description level to retrieve: A4L_BSC_DESC to get the basic descriptor (notably the size of the data buffer to allocate). A4L_CPLX_DESC to get the complex descriptor, the data buffer is filled with characteristics about the subdevices, the channels and the ranges.

Returns

0 on success. Otherwise:

• -EINVAL is returned if some argument is missing or wrong; the pass argument should be checked; check also the kernel log ("dmesg")
• -EFAULT is returned if a user <-> kernel transfer went wrong
• -ENODEV is returned if the descriptor is incoherent (the device may be unattached)

References A4L_BSC_DESC, and a4l_descriptor::magic.

Referenced by a4l_open().