1iec61883(7I) Ioctl Requests iec61883(7I)
2
6 iec61883 - IEC 61883 interfaces
7
9 #include <sys/av/iec61883.h>
10
13 The set of interfaces described in this man page can be used to control
14 and exchange data with consumer audio/video devices using protocols
15 specified inIEC 61883 Consumer Electronic Audio/Video Equipment - Digi‐
16 tal Interface, including Common Isochronous Packet (CIP), Connection
17 Management Procedures (CMP) and Function Control Protocol (FCP).
18 An iec61883 compliant driver exports two device nodes for isochronous
21 and for asynchronous transactions. See the FILES section of this man
22 page for the namespace definition.
23 Isochronous Transfers
25 Two methods are provided to receive/transmit isochronous data: using
26 mmap(2) in combination with ioctl(2), and read(2) or write(2).
27 Mmap/Ioctl
29 This method provides better performance and finer-grained control than
30 read/write, and is a method of choice for most applications. The data
31 buffer is mapped into a user process address space, which means no data
32 copying between the kernel and an application is necessary. Synchro‐
33 nization between user processes and the driver is performed using
34 ioctl(2) commands.
35 An application allocates resources for isochronous transfer using
38 IEC61883_ISOCH_INIT. Then the data buffer can be mapped into the
39 process space using mmap(2).
40 A circular data buffer consists of one or more equal size frame buffers
43 (further referred to as frames, unless to avoid ambiguity with AV
44 frames). Frames are numbered starting with zero and are always trans‐
45 ferred sequentially. Frames consist equal sized packets. Each packet
46 contains a CIP header and one or more data blocks.
47 A driver and an application act as a producer and a consumer: producer
50 supplies full frames (filled with data) to the consumer, and the pro‐
51 ducer is not allowed to access those frames until the consumer claims
52 them empty.
53 A transfer can be initiated and suspended with IEC61883_START and
56 IEC61883_STOP commands respectively. IEC61883_RECV or IEC61883_XMIT is
57 used for producer-consumer synchronization.
58 Read/Write
60 Using this method, an application calls read(2) or write(2) to receive
61 or transmit a specified amount of data. Bus-specific overhead, such as
62 isochronous packet headers, is handled by the driver and is not exposed
63 to applications. Data returned by read(2) contains CIP headers and data
64 blocks. Empty packets are not returned by read(2). write(2) data should
65 meet the same requirements.
66 If one or more channels have been allocated since open(2) (see
69 IEC61883_ISOCH_INIT), the data is received/transmitted using channel
70 that was created the last.
71 If no channels were allocated, the driver uses the broadcast channel by
74 default and allocates the default-size data buffer. During transmit,
75 the first packet's CIP header is used to auto-detect the data format.
76 If it is one of the formats supported by the driver, it is properly
77 transmitted (with inserted empty packets and timestamps).
78 For both methods, if during transmit the driver runs out of data, it
81 transmits empty packets containing only a CIP header of the next to be
82 transmitted packet, as defined in IEC 61883-1.
83 Connection Management Procedures
85 Applications wishing to follow Connection Management Procedures (CMP)
86 in combination with isochronous transfers should use the ioctl(2)
87 IEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ and
88 IEC61883_PLUG_REG_CAS commands.
89 Asynchronous Transactions
91 read(2), write(2), ioctl(2), and poll(2) can be used with asynchronous
92 nodes. Asynchronous data exchange between a driver and an application
93 utilizes a common data structure called asynchronous request (ARQ):
94 typedef struct iec61883_arq {
96 int arq_type;
97 int arq_len;
98 union {
99 uint32_t quadlet;
100 uint64_t octlet;
101 uint8_t buf[8];
102 } arq_data;
103 } iec61883_arq_t;
104 arq_type contains ARQ type:
109 IEC61883_ARQ_FCP_CMD
111 IEC61883_ARQ_FCP_RESP
112 FCP command and response frame respectively. Outgoing frames are
114 sent using write(2), incoming frames are received with read(2).
115 See IEC 61883-1 for the FCP frame structure definition.
117 IEC61883_ARQ_BUS_RESET
120 Returned by the driver when a bus reset occurs. There is no data
122 associated with this request type, and arq_len is set to 0.
123 If arq_len is 4 or 8, then data should be supplied in arq_data.quadlet
127 or arq_data.octlet respectively, otherwise up to 8 bytes can be put in
128 arq_data.buf, with the rest of the data following immediately after.
129 write(2)
131 For a request to be sent to a target, an iec61883_arq_t structure along
132 with associated data is passed to the driver using write(2). write()
133 blocks until the request is completed.
134 read(2)
136 A driver collects incoming ARQs in the internal buffer. Buffer size can
137 be changed using the ioctl(2) command IEC61883_FCP_SET_IBUF_SIZE.
138 Reading an ARQ takes one or two steps depending on data length. An
141 application first reads sizeof (iec61883_arq_t) bytes: if arq_len is
142 less than or equal 4, which is usually the case, no additional step is
143 needed. Otherwise, the remaining arq_len - 4 bytes should be read and
144 concatenated.
145 read(2) blocks until the specified amount of data is available, unless
148 O_NONBLOCK or O_NDELAY flag was set during open(2), in which
149 caseread(2) returns immediately.
150 poll(2)
152 Applications can poll(2) asynchronous nodes on the POLLIN event.
153 Bus Reset
155 In case of a bus reset, the driver notifies an application by generat‐
156 ing an ARQ of type IEC61883_ARQ_BUS_RESET.
157 If there were established isochronous connections before bus reset, the
160 driver attempts to restore all connections as described in IEC 61883
161 and resume any active transfers that were in progress.
162
164 The following commands only apply to isochronous nodes:
165 IEC61883_ISOCH_INIT
167 This command allocates a data buffer and isochronous resources (if
169 necessary) for the isochronous transfer. The argument is a pointer
170 to the structure:
171 typedef struct iec61883_isoch_init {
173 int ii_version; /* interface version */
174 int ii_pkt_size; /* packet size */
175 int ii_frame_size; /* packets/frame */
176 int ii_frame_cnt; /* # of frames */
177 int ii_direction; /* xfer direction */
178 int ii_bus_speed; /* bus speed */
179 uint64_t ii_channel; /* channel mask */
180 int ii_dbs; /* DBS */
181 int ii_fn; /* FN */
182 int ii_rate_n; /* rate numerator */
183 int ii_rate_d; /* rate denominator */
184 int ii_ts_mode; /* timestamp mode */
185 int ii_flags; /* flags */
186 int ii_handle; /* isoch handle */
187 int ii_frame_rcnt; /* # of frames */
188 off_t *ii_mmap_off /* mmap offset */
189 int ii_rchannel; /* channel */
190 int ii_error; /* error code */
191 } iec61883_isoch_init_t;
192 ii_version should be set to IEC61883_V1_0.
195 The driver attempts to allocate a data buffer consisting of
197 ii_frame_cnt frames, with ii_frame_size packets in each frame.
198 Packet size in bytes is specified by ii_pkt_size specifies and
199 should be a multiple of 512 and compatible with ii_bus_speed.
200 ii_direction can take one of the following values:
202 IEC61883_DIR_RECV
204 Receiving isochronous data.
206 IEC61883_DIR_XMIT
209 Transmitting isochronous data.
211 ii_bus_speed chooses bus speed to be used and can be either
213 IEC61883_S100, IEC61883_S200 or IEC61883_S400.
214 ii_channel is a mask that specifies an isochronous channel number
216 to be used, with the Nth bit representing channel N. When transmit‐
217 ting data, several bits can be set at a time, in which case the
218 driver chooses one, for example, 0x3FF means a range from 0 to 9.
219 In case of receive, only one bit can be set.
220 ii_dbs specifies data block size in quadlets, for example, DBS
222 value for SD-DVCR is 0x78. Refer to IEC 61883 for more details on
223 DBS.
224 ii_fn specifies fraction number, which defines the number of blocks
226 in which a source packet is divided. Allowed values are from 0 to
227 3. Refer to IEC 61883 for more details on FN.
228 Data rate expected by the AV device can be lower than the bus
230 speed, in which case the driver has to periodically insert empty
231 packets into the data stream to avoid device buffer overflows. This
232 rate is specified with a fraction N/D, set by ii_rate_n and
233 ii_rate_d respectively. Any integer numbers can be used, or the
234 following predefined constants:
235 IEC61883_RATE_N_DV_NTSC IEC61883_RATE_D_DV_NTSC
237 Data rate expected by DV-NTSC devices.
239 IEC61883_RATE_N_DV_PAL IEC61883_RATE_D_DV_PAL
242 Data rate expected by DV-PAL devices.
244 During data transmission, a timestamp based on the current value of
246 the cycle timer is usually required. ii_ts_mode defines timestamp
247 mode to be used:
248 IEC61883_TS_SYT
250 Driver puts a timestamp in the SYT field of the first CIP
252 header of each frame.
253 IEC61883_TS_NONE
256 No timestamps.
258 ii_dbs, ii_fn, ii_rate_n, ii_rate_d and ii_ts_mode are only
260 required for transmission. In other case these should be set to 0.
261 ii_flags should be set to 0.
263 If command succeeds, ii_handle contains a handle that should be
265 used with other isochronous commands. ii_frame_rcnt contains the
266 number of allocated frames (can be less than ii_frame_cnt).
267 ii_mmap_off contains an offset to be used in mmap(2), for example,
268 to map an entire data receive buffer:
269 pa = mmap(NULL, init.ii_pkt_size *
271 init.ii_frame_size * init.ii_frame_rcnt,
272 PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);
273 ii_rchannel contains channel number.
276 In case of command success, ii_error is set to 0; otherwise one of
278 the following values can be returned:
279 IEC61883_ERR_NOMEM
281 Not enough memory for the data buffer.
283 IEC61883_ERR_NOCHANNEL
286 Cannot allocate isochronous channel.
288 IEC61883_ERR_PKT_SIZE
291 Packet size is not allowed at this bus speed.
293 IEC61883_ERR_VERSION
296 Interface version is not supported.
298 IEC61883_ERR_INVAL
301 One or more the parameters are invalid
303 IEC61883_ERR_OTHER
306 Unspecified error type.
308 IEC61883_ISOCH_FINI
312 Argument is a handle returned by IEC61883_ISOCH_INIT. This command
314 frees any resources associated with this handle. There must be no
315 active transfers and the data buffer must be unmapped; otherwise
316 the command fails.
317 IEC61883_START
320 This command starts an isochronous transfer. The argument is a han‐
322 dle returned by IEC61883_ISOCH_INIT.
323 IEC61883_STOP
326 This command stops an isochronous transfer. The argument is a han‐
328 dle returned by IEC61883_ISOCH_INIT.
329 IEC61883_RECV
332 This command is used to receive full frames and return empty frames
334 to the driver. The argument is a pointer to the structure:
335 typedef struct iec61883_recv {
337 int rx_handle; /* isoch handle */
338 int rx_flags; /* flags */
339 iec61883_xfer_t rx_xfer; /* xfer params */
340 } iec61883_recv_t;
341 typedef struct iec61883_xfer {
343 int xf_empty_idx; /* first empty frame */
344 int xf_empty_cnt; /* empty frame count */
345 int xf_full_idx; /* first full frame */
346 int xf_full_cnt; /* full frame count */
347 int xf_error; /* error */
348 } iec61883_xfer_t;
349 rx_flags should be set to 0.
352 An application sets xf_empty_idx and xf_empty_cnt to indicate
354 frames it no longer needs. E.g. if a buffer consists of 6 frames,
355 xf_empty_idx is 4, xf_empty_cnt is 3 - means that frames 4, 5 and 0
356 can now be reused by the driver. If there are no empty frames, for
357 example, the first time this command is called, xf_empty_cnt should
358 be set to 0.
359 When the command returns, xf_full_idx and xf_full_cnt specifies the
361 frames that are full. xf_error is always 0.
362 In general, AV frame boundaries are not aligned with the frame buf‐
364 fer boundaries, because the first received packet might not be the
365 first packet of an AV frame, and, in contrast with the read/write
366 method, the driver does not remove empty CIP packets.
367 Applications should detect empty packets by comparing adjacent
369 packets' continuity counters (DBC field of the CIP header).
370 IEC61883_XMIT
373 This command is used to transmit full frames and get more empty
375 frames from the driver. The argument is a pointer to the structure:
376 typedef struct iec61883_xmit {
378 int tx_handle; /* isoch handle */
379 int tx_flags; /* flags */
380 iec61883_xfer_t tx_xfer; /* xfer params */
381 int tx_miss_cnt; /* missed cycles */
382 } iec61883_xmit_t;
383 tx_flags should be set to zero.
386 The application sets xf_full_idx and xf_full_cnt to specify frames
388 it wishes to transmit. If there are no frames to transmit (e.g. the
389 first time this command is called), xf_full_cnt should be set to 0.
390 When the command returns, xf_empty_idx and xf_empty_cnt specifies
392 empty frames which can be to transmit more data. xf_error is always
393 0.
394 tx_miss_cnt contains the number of isochronous cycles missed since
396 last transfer due to data buffer under run. This can happen when an
397 application does not supply data fast enough.
398 For the purposes of time stamping, the driver considers the first
400 packet in a frame buffer to be the first packet of an AV frame.
401 IEC61883_PLUG_INIT
404 This command returns a handle for the specified plug. The argument
406 is a pointer to the structure:
407 typedef struct iec61883_plug_init {
409 int pi_ver; /* interface version */
410 int pi_loc; /* plug location */
411 int pi_type; /* plug type */
412 int pi_num; /* plug number */
413 int pi_flags; /* flags */
414 int pi_handle; /* plug handle */
415 int pi_rnum; /* plug number */
416 } iec61883_plug_init_t;
417 pi_ver should be set to IEC61883_V1_0.
420 pi_loc specifies plug location:
422 IEC61883_LOC_LOCAL
424 On the local unit (local plug). A plug control register (PCR)
426 is allocated. Command fails if the plug already exists
427 IEC61883_LOC_REMOTE
430 On the remote unit (remote plug). The plug should exist on the
432 remote unit, otherwise the command fails.
433 pi_type specifies isochronous plug type:
435 IEC61883_PLUG_IN IEC61883_PLUG_OUT
437 Input or output plugs.
439 IEC61883_PLUG_MASTER_IN IEC61883_PLUG_MASTER_OUT
442 Master input or master output plug. These plugs always exist on
444 the local unit.
445 pi_num specifies plug number. This should be 0 for master plugs,
447 and from 0 to 31 for input/output plugs. Alternatively, a special
448 value IEC61883_PLUG_ANY can be used to let the driver choose a free
449 plug number, create the plug and return the number in pi_rnum.
450 pi_flags should be set to 0.
452 If the command succeeds, pi_handle contains a handle that should be
454 used with other plug commands.
455 IEC61883_PLUG_FINI
458 Argument is a handle returned by IEC61883_PLUG_INIT. This command
460 frees any resources associated with this handle, including the PCR.
461 IEC61883_PLUG_REG_READ
464 Read plug register value. The argument is a pointer to the struc‐
466 ture:
467 typedef struct iec61883_plug_reg_val {
469 int pr_handle; /* plug handle */
470 uint32_t pr_val; /* register value */
471 } iec61883_plug_reg_val_t;
472 pr_handle is a handle returned by IEC61883_PLUG_INIT. Register
475 value is returned in pr_val.
476 IEC61883_PLUG_REG_CAS
479 Atomically compare and swap plug register value. The argument is a
481 pointer to the structure:
482 typedef struct iec61883_plug_reg_lock {
484 int pl_handle; /* plug handle */
485 uint32_t pl_arg; /* compare arg */
486 uint32_t pl_data; /* write value */
487 UINT32_t pl_old; /* original value */
488 } iec61883_plug_reg_lock_t;
489 pr_handle is a handle returned by IEC61883_PLUG_INIT.
492 Original register value is compared with pl_arg and if they are
494 equal, register value is replaced with pl_data. In any case, the
495 original value is stored in pl_old.
496 The following commands only apply to asynchronous nodes:
500 IEC61883_ARQ_GET_IBUF_SIZE
502 This command returns current incoming ARQ buffer size. The argument
504 is a pointer to int.
505 IEC61883_ARQ_SET_IBUF_SIZE
508 This command changes incoming ARQ buffer size. The argument is the
510 new buffer size in bytes.
511
514 /dev/av/N/async Device node for asynchronous data
515 /dev/av/N/isoch Device has been disconnected
518
521 EIO Bus operation failed.
522 DMA failure.
524 EFAULT ioctl(2) argument points to an illegal address.
527 EINVAL Invalid argument or argument combination.
530 ENODEV Device has been disconnected.
533
536 See attributes(5) for descriptions of the following attributes:
537 ┌────────────────────┬──────────────────────────────────────┐
542 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
543 ├────────────────────┼──────────────────────────────────────┤
544 │Architecture │All │
545 ├────────────────────┼──────────────────────────────────────┤
546 │Stability level │Committed │
547 └────────────────────┴──────────────────────────────────────┘
548
550 ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
551 av1394(7D)
552 IEC 61883 Consumer audio/video equipment - Digital interface
555 IEEE Std 1394-1995 Standard for a High Performance Serial Bus
558SunOS 5.11 27 Mar 2009 iec61883(7I)