#include <sys/av/iec61883.h>

The set of interfaces described in this man page can be used to control and exchange data with consumer audio/video devices using protocols specified inIEC 61883 Consumer Electronic Audio/Video Equipment - Digital Interface, including Common Isochronous Packet (CIP), Connection Management Procedures (CMP) and Function Control Protocol (FCP).

An iec61883 compliant driver exports two device nodes for isochronous and for asynchronous transactions. See the FILES section of this man page for the namespace definition.

Two methods are provided to receive/transmit isochronous data: using mmap(2) in combination with ioctl(2), and read(2) or write(2).

This method provides better performance and finer-grained control than read/write, and is a method of choice for most applications. The data buffer is mapped into a user process address space, which means no data copying between the kernel and an application is necessary. Synchronization between user processes and the driver is performed using ioctl(2) commands.

An application allocates resources for isochronous transfer using IEC61883_ISOCH_INIT. Then the data buffer can be mapped into the process space using mmap(2).

A circular data buffer consists of one or more equal size frame buffers (further referred to as frames, unless to avoid ambiguity with AV frames). Frames are numbered starting with zero and are always transferred sequentially. Frames consist equal sized packets. Each packet contains a CIP header and one or more data blocks.

A driver and an application act as a producer and a consumer: producer supplies full frames (filled with data) to the consumer, and the producer is not allowed to access those frames until the consumer claims them empty.

A transfer can be initiated and suspended with IEC61883_START and IEC61883_STOP commands respectively. IEC61883_RECV or IEC61883_XMIT is used for producer-consumer synchronization.

Using this method, an application calls read(2) or write(2) to receive or transmit a specified amount of data. Bus-specific overhead, such as isochronous packet headers, is handled by the driver and is not exposed to applications. Data returned by read(2) contains CIP headers and data blocks. Empty packets are not returned by read(2). write(2) data should meet the same requirements.

If one or more channels have been allocated since open(2) (see IEC61883_ISOCH_INIT), the data is received/transmitted using channel that was created the last.

If no channels were allocated, the driver uses the broadcast channel by default and allocates the default-size data buffer. During transmit, the first packet's CIP header is used to auto-detect the data format. If it is one of the formats supported by the driver, it is properly transmitted (with inserted empty packets and timestamps).

For both methods, if during transmit the driver runs out of data, it transmits empty packets containing only a CIP header of the next to be transmitted packet, as defined in IEC 61883-1.

Applications wishing to follow Connection Management Procedures (CMP) in combination with isochronous transfers should use the ioctl(2) IEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ and IEC61883_PLUG_REG_CAS commands.

read(2), write(2), ioctl(2), and poll(2) can be used with asynchronous nodes. Asynchronous data exchange between a driver and an application utilizes a common data structure called asynchronous request (ARQ):

typedef struct iec61883_arq {
 int arq_type;
 int arq_len;
 union {
 uint32_t quadlet;
 uint64_t octlet;
 uint8_t buf[8];
 } arq_data;
} iec61883_arq_t;

arq_type contains ARQ type:

IEC61883_ARQ_FCP_CMD

IEC61883_ARQ_FCP_RESP

IEC61883_ARQ_BUS_RESET

If arq_len is 4 or 8, then data should be supplied in arq_data.quadlet or arq_data.octlet respectively, otherwise up to 8 bytes can be put in arq_data.buf, with the rest of the data following immediately after.

For a request to be sent to a target, an iec61883_arq_t structure along with associated data is passed to the driver using write(2). write() blocks until the request is completed.

A driver collects incoming ARQs in the internal buffer. Buffer size can be changed using the ioctl(2) command IEC61883_FCP_SET_IBUF_SIZE.

Reading an ARQ takes one or two steps depending on data length. An application first reads sizeof (iec61883_arq_t) bytes: if arq_len is less than or equal 4, which is usually the case, no additional step is needed. Otherwise, the remaining arq_len - 4 bytes should be read and concatenated.

read(2) blocks until the specified amount of data is available, unless O_NONBLOCK or O_NDELAY flag was set during open(2), in which caseread(2) returns immediately.

Applications can poll(2) asynchronous nodes on the POLLIN event.

In case of a bus reset, the driver notifies an application by generating an ARQ of type IEC61883_ARQ_BUS_RESET.

If there were established isochronous connections before bus reset, the driver attempts to restore all connections as described in IEC 61883 and resume any active transfers that were in progress.

The following commands only apply to isochronous nodes:

IEC61883_ISOCH_INIT

typedef struct iec61883_isoch_init {
 int ii_version; /* interface version */
 int ii_pkt_size; /* packet size */
 int ii_frame_size; /* packets/frame */
 int ii_frame_cnt; /* # of frames */
 int ii_direction; /* xfer direction */
 int ii_bus_speed; /* bus speed */
 uint64_t ii_channel; /* channel mask */
 int ii_dbs; /* DBS */
 int ii_fn; /* FN */
 int ii_rate_n; /* rate numerator */
 int ii_rate_d; /* rate denominator */
 int ii_ts_mode; /* timestamp mode */
 int ii_flags; /* flags */
 int ii_handle; /* isoch handle */
 int ii_frame_rcnt; /* # of frames */
 off_t *ii_mmap_off /* mmap offset */
 int ii_rchannel; /* channel */
 int ii_error; /* error code */
} iec61883_isoch_init_t;

pa = mmap(NULL, init.ii_pkt_size *
 init.ii_frame_size * init.ii_frame_rcnt,
 PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);

IEC61883_ISOCH_FINI

IEC61883_START

IEC61883_STOP

IEC61883_RECV

typedef struct iec61883_recv {
 int rx_handle; /* isoch handle */
 int rx_flags; /* flags */
iec61883_xfer_t rx_xfer; /* xfer params */
} iec61883_recv_t;

typedef struct iec61883_xfer {
 int xf_empty_idx; /* first empty frame */
 int xf_empty_cnt; /* empty frame count */
 int xf_full_idx; /* first full frame */
 int xf_full_cnt; /* full frame count */
 int xf_error; /* error */
} iec61883_xfer_t;

IEC61883_XMIT

typedef struct iec61883_xmit {
 int tx_handle; /* isoch handle */
 int tx_flags; /* flags */
 iec61883_xfer_t tx_xfer; /* xfer params */
 int tx_miss_cnt; /* missed cycles */
 } iec61883_xmit_t;

IEC61883_PLUG_INIT

typedef struct iec61883_plug_init {
 int pi_ver; /* interface version */
 int pi_loc; /* plug location */
 int pi_type; /* plug type */
 int pi_num; /* plug number */
 int pi_flags; /* flags */
 int pi_handle; /* plug handle */
 int pi_rnum; /* plug number */
 } iec61883_plug_init_t;

IEC61883_PLUG_FINI

IEC61883_PLUG_REG_READ

typedef struct iec61883_plug_reg_val {
 int pr_handle; /* plug handle */
 uint32_t pr_val; /* register value */
} iec61883_plug_reg_val_t;

IEC61883_PLUG_REG_CAS

typedef struct iec61883_plug_reg_lock {
 int pl_handle; /* plug handle */
 uint32_t pl_arg; /* compare arg */
 uint32_t pl_data; /* write value */
 UINT32_t pl_old; /* original value */
} iec61883_plug_reg_lock_t;

The following commands only apply to asynchronous nodes:

IEC61883_ARQ_GET_IBUF_SIZE

IEC61883_ARQ_SET_IBUF_SIZE

/dev/av/N/async

/dev/av/N/isoch

EIO

EFAULT

EINVAL

ENODEV

See attributes(5) for descriptions of the following attributes:

ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5), av1394(7D)

IEC 61883 Consumer audio/video equipment - Digital interface

IEEE Std 1394-1995 Standard for a High Performance Serial Bus