1 IEC61883(7I) Ioctl Requests IEC61883(7I)
2
3
4
5 NAME
6 iec61883 - IEC 61883 interfaces
7
8 SYNOPSIS
9 #include <sys/av/iec61883.h>
10
11
12 DESCRIPTION
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 -
16 Digital Interface, including Common Isochronous Packet (CIP),
17 Connection Management Procedures (CMP) and Function Control Protocol
18 (FCP).
19
20
21 An iec61883 compliant driver exports two device nodes for isochronous
22 and for asynchronous transactions. See the FILES section of this man
23 page for the namespace definition.
24
25 Isochronous Transfers
26 Two methods are provided to receive/transmit isochronous data: using
27 mmap(2) in combination with ioctl(2), and read(2) or write(2).
28
29 Mmap/Ioctl
30 This method provides better performance and finer-grained control than
31 read/write, and is a method of choice for most applications. The data
32 buffer is mapped into a user process address space, which means no data
33 copying between the kernel and an application is necessary.
34 Synchronization between user processes and the driver is performed
35 using ioctl(2) commands.
36
37
38 An application allocates resources for isochronous transfer using
39 IEC61883_ISOCH_INIT. Then the data buffer can be mapped into the
40 process space using mmap(2).
41
42
43 A circular data buffer consists of one or more equal size frame buffers
44 (further referred to as frames, unless to avoid ambiguity with AV
45 frames). Frames are numbered starting with zero and are always
46 transferred sequentially. Frames consist equal sized packets. Each
47 packet contains a CIP header and one or more data blocks.
48
49
50 A driver and an application act as a producer and a consumer: producer
51 supplies full frames (filled with data) to the consumer, and the
52 producer is not allowed to access those frames until the consumer
53 claims them empty.
54
55
56 A transfer can be initiated and suspended with IEC61883_START and
57 IEC61883_STOP commands respectively. IEC61883_RECV or IEC61883_XMIT is
58 used for producer-consumer synchronization.
59
60 Read/Write
61 Using this method, an application calls read(2) or write(2) to receive
62 or transmit a specified amount of data. Bus-specific overhead, such as
63 isochronous packet headers, is handled by the driver and is not exposed
64 to applications. Data returned by read(2) contains CIP headers and data
65 blocks. Empty packets are not returned by read(2). write(2) data should
66 meet the same requirements.
67
68
69 If one or more channels have been allocated since open(2) (see
70 IEC61883_ISOCH_INIT), the data is received/transmitted using channel
71 that was created the last.
72
73
74 If no channels were allocated, the driver uses the broadcast channel by
75 default and allocates the default-size data buffer. During transmit,
76 the first packet's CIP header is used to auto-detect the data format.
77 If it is one of the formats supported by the driver, it is properly
78 transmitted (with inserted empty packets and timestamps).
79
80
81 For both methods, if during transmit the driver runs out of data, it
82 transmits empty packets containing only a CIP header of the next to be
83 transmitted packet, as defined in IEC 61883-1.
84
85 Connection Management Procedures
86 Applications wishing to follow Connection Management Procedures (CMP)
87 in combination with isochronous transfers should use the ioctl(2)
88 IEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ and
89 IEC61883_PLUG_REG_CAS commands.
90
91 Asynchronous Transactions
92 read(2), write(2), ioctl(2), and poll(2) can be used with asynchronous
93 nodes. Asynchronous data exchange between a driver and an application
94 utilizes a common data structure called asynchronous request (ARQ):
95
96 typedef struct iec61883_arq {
97 int arq_type;
98 int arq_len;
99 union {
100 uint32_t quadlet;
101 uint64_t octlet;
102 uint8_t buf[8];
103 } arq_data;
104 } iec61883_arq_t;
105
106
107
108
109 arq_type contains ARQ type:
110
111 IEC61883_ARQ_FCP_CMD
112 IEC61883_ARQ_FCP_RESP
113
114 FCP command and response frame respectively. Outgoing frames are
115 sent using write(2), incoming frames are received with read(2).
116
117 See IEC 61883-1 for the FCP frame structure definition.
118
119
120 IEC61883_ARQ_BUS_RESET
121
122 Returned by the driver when a bus reset occurs. There is no data
123 associated with this request type, and arq_len is set to 0.
124
125
126
127 If arq_len is 4 or 8, then data should be supplied in arq_data.quadlet
128 or arq_data.octlet respectively, otherwise up to 8 bytes can be put in
129 arq_data.buf, with the rest of the data following immediately after.
130
131 write(2)
132 For a request to be sent to a target, an iec61883_arq_t structure along
133 with associated data is passed to the driver using write(2). write()
134 blocks until the request is completed.
135
136 read(2)
137 A driver collects incoming ARQs in the internal buffer. Buffer size can
138 be changed using the ioctl(2) command IEC61883_FCP_SET_IBUF_SIZE.
139
140
141 Reading an ARQ takes one or two steps depending on data length. An
142 application first reads sizeof (iec61883_arq_t) bytes: if arq_len is
143 less than or equal 4, which is usually the case, no additional step is
144 needed. Otherwise, the remaining arq_len - 4 bytes should be read and
145 concatenated.
146
147
148 read(2) blocks until the specified amount of data is available, unless
149 O_NONBLOCK or O_NDELAY flag was set during open(2), in which case
150 read(2) returns immediately.
151
152 poll(2)
153 Applications can poll(2) asynchronous nodes on the POLLIN event.
154
155 Bus Reset
156 In case of a bus reset, the driver notifies an application by
157 generating an ARQ of type IEC61883_ARQ_BUS_RESET.
158
159
160 If there were established isochronous connections before bus reset, the
161 driver attempts to restore all connections as described in IEC 61883
162 and resume any active transfers that were in progress.
163
164 IOCTLS
165 The following commands only apply to isochronous nodes:
166
167 IEC61883_ISOCH_INIT
168
169 This command allocates a data buffer and isochronous resources (if
170 necessary) for the isochronous transfer. The argument is a pointer
171 to the structure:
172
173 typedef struct iec61883_isoch_init {
174 int ii_version; /* interface version */
175 int ii_pkt_size; /* packet size */
176 int ii_frame_size; /* packets/frame */
177 int ii_frame_cnt; /* # of frames */
178 int ii_direction; /* xfer direction */
179 int ii_bus_speed; /* bus speed */
180 uint64_t ii_channel; /* channel mask */
181 int ii_dbs; /* DBS */
182 int ii_fn; /* FN */
183 int ii_rate_n; /* rate numerator */
184 int ii_rate_d; /* rate denominator */
185 int ii_ts_mode; /* timestamp mode */
186 int ii_flags; /* flags */
187 int ii_handle; /* isoch handle */
188 int ii_frame_rcnt; /* # of frames */
189 off_t *ii_mmap_off /* mmap offset */
190 int ii_rchannel; /* channel */
191 int ii_error; /* error code */
192 } iec61883_isoch_init_t;
193
194
195 ii_version should be set to IEC61883_V1_0.
196
197 The driver attempts to allocate a data buffer consisting of
198 ii_frame_cnt frames, with ii_frame_size packets in each frame.
199 Packet size in bytes is specified by ii_pkt_size specifies and
200 should be a multiple of 512 and compatible with ii_bus_speed.
201
202 ii_direction can take one of the following values:
203
204 IEC61883_DIR_RECV
205
206 Receiving isochronous data.
207
208
209 IEC61883_DIR_XMIT
210
211 Transmitting isochronous data.
212
213 ii_bus_speed chooses bus speed to be used and can be either
214 IEC61883_S100, IEC61883_S200 or IEC61883_S400.
215
216 ii_channel is a mask that specifies an isochronous channel number
217 to be used, with the Nth bit representing channel N. When
218 transmitting data, several bits can be set at a time, in which case
219 the driver chooses one, for example, 0x3FF means a range from 0 to
220 9. In case of receive, only one bit can be set.
221
222 ii_dbs specifies data block size in quadlets, for example, DBS
223 value for SD-DVCR is 0x78. Refer to IEC 61883 for more details on
224 DBS.
225
226 ii_fn specifies fraction number, which defines the number of blocks
227 in which a source packet is divided. Allowed values are from 0 to
228 3. Refer to IEC 61883 for more details on FN.
229
230 Data rate expected by the AV device can be lower than the bus
231 speed, in which case the driver has to periodically insert empty
232 packets into the data stream to avoid device buffer overflows. This
233 rate is specified with a fraction N/D, set by ii_rate_n and
234 ii_rate_d respectively. Any integer numbers can be used, or the
235 following predefined constants:
236
237 IEC61883_RATE_N_DV_NTSC IEC61883_RATE_D_DV_NTSC
238
239 Data rate expected by DV-NTSC devices.
240
241
242 IEC61883_RATE_N_DV_PAL IEC61883_RATE_D_DV_PAL
243
244 Data rate expected by DV-PAL devices.
245
246 During data transmission, a timestamp based on the current value of
247 the cycle timer is usually required. ii_ts_mode defines timestamp
248 mode to be used:
249
250 IEC61883_TS_SYT
251
252 Driver puts a timestamp in the SYT field of the first CIP
253 header of each frame.
254
255
256 IEC61883_TS_NONE
257
258 No timestamps.
259
260 ii_dbs, ii_fn, ii_rate_n, ii_rate_d and ii_ts_mode are only
261 required for transmission. In other case these should be set to 0.
262
263 ii_flags should be set to 0.
264
265 If command succeeds, ii_handle contains a handle that should be
266 used with other isochronous commands. ii_frame_rcnt contains the
267 number of allocated frames (can be less than ii_frame_cnt).
268 ii_mmap_off contains an offset to be used in mmap(2), for example,
269 to map an entire data receive buffer:
270
271 pa = mmap(NULL, init.ii_pkt_size *
272 init.ii_frame_size * init.ii_frame_rcnt,
273 PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);
274
275
276 ii_rchannel contains channel number.
277
278 In case of command success, ii_error is set to 0; otherwise one of
279 the following values can be returned:
280
281 IEC61883_ERR_NOMEM
282
283 Not enough memory for the data buffer.
284
285
286 IEC61883_ERR_NOCHANNEL
287
288 Cannot allocate isochronous channel.
289
290
291 IEC61883_ERR_PKT_SIZE
292
293 Packet size is not allowed at this bus speed.
294
295
296 IEC61883_ERR_VERSION
297
298 Interface version is not supported.
299
300
301 IEC61883_ERR_INVAL
302
303 One or more the parameters are invalid
304
305
306 IEC61883_ERR_OTHER
307
308 Unspecified error type.
309
310
311
312 IEC61883_ISOCH_FINI
313
314 Argument is a handle returned by IEC61883_ISOCH_INIT. This command
315 frees any resources associated with this handle. There must be no
316 active transfers and the data buffer must be unmapped; otherwise
317 the command fails.
318
319
320 IEC61883_START
321
322 This command starts an isochronous transfer. The argument is a
323 handle returned by IEC61883_ISOCH_INIT.
324
325
326 IEC61883_STOP
327
328 This command stops an isochronous transfer. The argument is a
329 handle returned by IEC61883_ISOCH_INIT.
330
331
332 IEC61883_RECV
333
334 This command is used to receive full frames and return empty frames
335 to the driver. The argument is a pointer to the structure:
336
337 typedef struct iec61883_recv {
338 int rx_handle; /* isoch handle */
339 int rx_flags; /* flags */
340 iec61883_xfer_t rx_xfer; /* xfer params */
341 } iec61883_recv_t;
342
343 typedef struct iec61883_xfer {
344 int xf_empty_idx; /* first empty frame */
345 int xf_empty_cnt; /* empty frame count */
346 int xf_full_idx; /* first full frame */
347 int xf_full_cnt; /* full frame count */
348 int xf_error; /* error */
349 } iec61883_xfer_t;
350
351
352 rx_flags should be set to 0.
353
354 An application sets xf_empty_idx and xf_empty_cnt to indicate
355 frames it no longer needs. E.g. if a buffer consists of 6 frames,
356 xf_empty_idx is 4, xf_empty_cnt is 3 - means that frames 4, 5 and 0
357 can now be reused by the driver. If there are no empty frames, for
358 example, the first time this command is called, xf_empty_cnt should
359 be set to 0.
360
361 When the command returns, xf_full_idx and xf_full_cnt specifies the
362 frames that are full. xf_error is always 0.
363
364 In general, AV frame boundaries are not aligned with the frame
365 buffer boundaries, because the first received packet might not be
366 the first packet of an AV frame, and, in contrast with the
367 read/write method, the driver does not remove empty CIP packets.
368
369 Applications should detect empty packets by comparing adjacent
370 packets' continuity counters (DBC field of the CIP header).
371
372
373 IEC61883_XMIT
374
375 This command is used to transmit full frames and get more empty
376 frames from the driver. The argument is a pointer to the structure:
377
378 typedef struct iec61883_xmit {
379 int tx_handle; /* isoch handle */
380 int tx_flags; /* flags */
381 iec61883_xfer_t tx_xfer; /* xfer params */
382 int tx_miss_cnt; /* missed cycles */
383 } iec61883_xmit_t;
384
385
386 tx_flags should be set to zero.
387
388 The application sets xf_full_idx and xf_full_cnt to specify frames
389 it wishes to transmit. If there are no frames to transmit (e.g. the
390 first time this command is called), xf_full_cnt should be set to 0.
391
392 When the command returns, xf_empty_idx and xf_empty_cnt specifies
393 empty frames which can be to transmit more data. xf_error is always
394 0.
395
396 tx_miss_cnt contains the number of isochronous cycles missed since
397 last transfer due to data buffer under run. This can happen when an
398 application does not supply data fast enough.
399
400 For the purposes of time stamping, the driver considers the first
401 packet in a frame buffer to be the first packet of an AV frame.
402
403
404 IEC61883_PLUG_INIT
405
406 This command returns a handle for the specified plug. The argument
407 is a pointer to the structure:
408
409 typedef struct iec61883_plug_init {
410 int pi_ver; /* interface version */
411 int pi_loc; /* plug location */
412 int pi_type; /* plug type */
413 int pi_num; /* plug number */
414 int pi_flags; /* flags */
415 int pi_handle; /* plug handle */
416 int pi_rnum; /* plug number */
417 } iec61883_plug_init_t;
418
419
420 pi_ver should be set to IEC61883_V1_0.
421
422 pi_loc specifies plug location:
423
424 IEC61883_LOC_LOCAL
425
426 On the local unit (local plug). A plug control register (PCR)
427 is allocated. Command fails if the plug already exists
428
429
430 IEC61883_LOC_REMOTE
431
432 On the remote unit (remote plug). The plug should exist on the
433 remote unit, otherwise the command fails.
434
435 pi_type specifies isochronous plug type:
436
437 IEC61883_PLUG_IN IEC61883_PLUG_OUT
438
439 Input or output plugs.
440
441
442 IEC61883_PLUG_MASTER_IN IEC61883_PLUG_MASTER_OUT
443
444 Master input or master output plug. These plugs always exist on
445 the local unit.
446
447 pi_num specifies plug number. This should be 0 for master plugs,
448 and from 0 to 31 for input/output plugs. Alternatively, a special
449 value IEC61883_PLUG_ANY can be used to let the driver choose a free
450 plug number, create the plug and return the number in pi_rnum.
451
452 pi_flags should be set to 0.
453
454 If the command succeeds, pi_handle contains a handle that should be
455 used with other plug commands.
456
457
458 IEC61883_PLUG_FINI
459
460 Argument is a handle returned by IEC61883_PLUG_INIT. This command
461 frees any resources associated with this handle, including the PCR.
462
463
464 IEC61883_PLUG_REG_READ
465
466 Read plug register value. The argument is a pointer to the
467 structure:
468
469 typedef struct iec61883_plug_reg_val {
470 int pr_handle; /* plug handle */
471 uint32_t pr_val; /* register value */
472 } iec61883_plug_reg_val_t;
473
474
475 pr_handle is a handle returned by IEC61883_PLUG_INIT. Register
476 value is returned in pr_val.
477
478
479 IEC61883_PLUG_REG_CAS
480
481 Atomically compare and swap plug register value. The argument is a
482 pointer to the structure:
483
484 typedef struct iec61883_plug_reg_lock {
485 int pl_handle; /* plug handle */
486 uint32_t pl_arg; /* compare arg */
487 uint32_t pl_data; /* write value */
488 UINT32_t pl_old; /* original value */
489 } iec61883_plug_reg_lock_t;
490
491
492 pr_handle is a handle returned by IEC61883_PLUG_INIT.
493
494 Original register value is compared with pl_arg and if they are
495 equal, register value is replaced with pl_data. In any case, the
496 original value is stored in pl_old.
497
498
499
500 The following commands only apply to asynchronous nodes:
501
502 IEC61883_ARQ_GET_IBUF_SIZE
503
504 This command returns current incoming ARQ buffer size. The argument
505 is a pointer to int.
506
507
508 IEC61883_ARQ_SET_IBUF_SIZE
509
510 This command changes incoming ARQ buffer size. The argument is the
511 new buffer size in bytes.
512
513
514 FILES
515 /dev/av/N/async
516 Device node for asynchronous data
517
518
519 /dev/av/N/isoch
520 Device has been disconnected
521
522
523 ERRORS
524 EIO
525 Bus operation failed.
526
527 DMA failure.
528
529
530 EFAULT
531 ioctl(2) argument points to an illegal address.
532
533
534 EINVAL
535 Invalid argument or argument combination.
536
537
538 ENODEV
539 Device has been disconnected.
540
541
542 ATTRIBUTES
543 See attributes(5) for descriptions of the following attributes:
544
545
546
547
548 +----------------+-----------------+
549 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
550 +----------------+-----------------+
551 |Architecture | All |
552 +----------------+-----------------+
553 |Stability level | Committed |
554 +----------------+-----------------+
555
556 SEE ALSO
557 ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
558 av1394(7D)
559
560
561 IEC 61883 Consumer audio/video equipment - Digital interface
562
563
564 IEEE Std 1394-1995 Standard for a High Performance Serial Bus
565
566
567
568 March 27, 2009 IEC61883(7I)
|
1 IEC61883(7I) Ioctl Requests IEC61883(7I)
2
3 NAME
4 iec61883 - IEC 61883 interfaces
5
6 SYNOPSIS
7 #include <sys/av/iec61883.h>
8
9 DESCRIPTION
10 The set of interfaces described in this man page can be used to control
11 and exchange data with consumer audio/video devices using protocols
12 specified in IIEC 61883 Consumer Electronic Audio/Video Equipment -
13 Digital Interface including Common Isochronous Packet (CIP), Connection
14 Management Procedures (CMP) and Function Control Protocol (FCP).
15
16 An iec61883 compliant driver exports two device nodes for isochronous and
17 for asynchronous transactions. See the FILES section of this man page
18 for the namespace definition.
19
20 Isochronous Transfers
21 Two methods are provided to receive/transmit isochronous data: using
22 mmap(2) in combination with ioctl(2), and read(2) or write(2).
23
24 Mmap/Ioctl
25 This method provides better performance and finer-grained control than
26 read/write, and is a method of choice for most applications. The data
27 buffer is mapped into a user process address space, which means no data
28 copying between the kernel and an application is necessary.
29 Synchronization between user processes and the driver is performed using
30 ioctl(2) commands.
31
32 An application allocates resources for isochronous transfer using
33 IEC61883_ISOCH_INIT. Then the data buffer can be mapped into the process
34 space using mmap(2).
35
36 A circular data buffer consists of one or more equal size frame buffers
37 (further referred to as frames, unless to avoid ambiguity with AV
38 frames). Frames are numbered starting with zero and are always
39 transferred sequentially. Frames consist equal sized packets. Each
40 packet contains a CIP header and one or more data blocks.
41
42 A driver and an application act as a producer and a consumer: producer
43 supplies full frames (filled with data) to the consumer, and the producer
44 is not allowed to access those frames until the consumer claims them
45 empty.
46
47 A transfer can be initiated and suspended with IEC61883_START and
48 IEC61883_STOP commands respectively. IEC61883_RECV or IEC61883_XMIT is
49 used for producer-consumer synchronization.
50
51 Read/Write
52 Using this method, an application calls read(2) or write(2) to receive or
53 transmit a specified amount of data. Bus-specific overhead, such as
54 isochronous packet headers, is handled by the driver and is not exposed
55 to applications. Data returned by read(2) contains CIP headers and data
56 blocks. Empty packets are not returned by read(2). write(2) data should
57 meet the same requirements.
58
59 If one or more channels have been allocated since open(2) (see
60 IEC61883_ISOCH_INIT), the data is received/transmitted using channel that
61 was created the last.
62
63 If no channels were allocated, the driver uses the broadcast channel by
64 default and allocates the default-size data buffer. During transmit, the
65 first packet's CIP header is used to auto-detect the data format. If it
66 is one of the formats supported by the driver, it is properly transmitted
67 (with inserted empty packets and timestamps).
68
69 For both methods, if during transmit the driver runs out of data, it
70 transmits empty packets containing only a CIP header of the next to be
71 transmitted packet, as defined in IEC 61883-1.
72
73 Connection Management Procedures
74 Applications wishing to follow Connection Management Procedures (CMP) in
75 combination with isochronous transfers should use the ioctl(2)
76 IEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ and
77 IEC61883_PLUG_REG_CAS commands.
78
79 Asynchronous Transactions
80 read(2), write(2), ioctl(2), and poll(2) can be used with asynchronous
81 nodes. Asynchronous data exchange between a driver and an application
82 utilizes a common data structure called asynchronous request (ARQ):
83
84 typedef struct iec61883_arq {
85 int arq_type;
86 int arq_len;
87 union {
88 uint32_t quadlet;
89 uint64_t octlet;
90 uint8_t buf[8];
91 } arq_data;
92 } iec61883_arq_t;
93
94 arq_type contains ARQ type:
95
96 IEC61883_ARQ_FCP_CMD
97 IEC61883_ARQ_FCP_RESP
98
99 FCP command and response frame respectively. Outgoing frames are sent
100 using write(2), incoming frames are received with read(2).
101
102 See IIEC 61883-1 for the FCP frame structure definition.
103
104 IEC61883_ARQ_BUS_RESET
105
106 Returned by the driver when a bus reset occurs. There is no data
107 associated with this request type, and arq_len is set to 0.
108
109 If arq_len is 4 or 8, then data should be supplied in arq_data.quadlet or
110 arq_data.octlet respectively, otherwise up to 8 bytes can be put in
111 arq_data.buf, with the rest of the data following immediately after.
112
113 write(2)
114 For a request to be sent to a target, an iec61883_arq_t structure along
115 with associated data is passed to the driver using write(2). write(2)
116 blocks until the request is completed.
117
118 read(2)
119 A driver collects incoming ARQs in the internal buffer. Buffer size can
120 be changed using the ioctl(2) command IEC61883_FCP_SET_IBUF_SIZE.
121
122 Reading an ARQ takes one or two steps depending on data length. An
123 application first reads `sizeof (iec61883_arq_t)' bytes: if arq_len is
124 less than or equal 4, which is usually the case, no additional step is
125 needed. Otherwise, the remaining `arq_len - 4' bytes should be read and
126 concatenated.
127
128 read(2) blocks until the specified amount of data is available, unless
129 O_NONBLOCK or O_NDELAY flag was set during open(2), in which case read(2)
130 returns immediately.
131
132 poll(2)
133 Applications can poll(2) asynchronous nodes on the POLLIN event.
134
135 Bus Reset
136 In case of a bus reset, the driver notifies an application by generating
137 an ARQ of type IEC61883_ARQ_BUS_RESET.
138
139 If there were established isochronous connections before bus reset, the
140 driver attempts to restore all connections as described in IEC 61883 and
141 resume any active transfers that were in progress.
142
143 IOCTLS
144 The following commands only apply to isochronous nodes:
145
146 IEC61883_ISOCH_INIT
147
148 This command allocates a data buffer and isochronous resources (if
149 necessary) for the isochronous transfer. The argument is a pointer to
150 the structure:
151
152 typedef struct iec61883_isoch_init {
153 int ii_version; /* interface version */
154 int ii_pkt_size; /* packet size */
155 int ii_frame_size; /* packets/frame */
156 int ii_frame_cnt; /* # of frames */
157 int ii_direction; /* xfer direction */
158 int ii_bus_speed; /* bus speed */
159 uint64_t ii_channel; /* channel mask */
160 int ii_dbs; /* DBS */
161 int ii_fn; /* FN */
162 int ii_rate_n; /* rate numerator */
163 int ii_rate_d; /* rate denominator */
164 int ii_ts_mode; /* timestamp mode */
165 int ii_flags; /* flags */
166 int ii_handle; /* isoch handle */
167 int ii_frame_rcnt; /* # of frames */
168 off_t *ii_mmap_off /* mmap offset */
169 int ii_rchannel; /* channel */
170 int ii_error; /* error code */
171 } iec61883_isoch_init_t;
172
173 ii_version should be set to IEC61883_V1_0.
174
175 The driver attempts to allocate a data buffer consisting of
176 ii_frame_cnt frames, with ii_frame_size packets in each frame. Packet
177 size in bytes is specified by ii_pkt_size specifies and should be a
178 multiple of 512 and compatible with ii_bus_speed.
179
180 ii_direction can take one of the following values:
181
182 IEC61883_DIR_RECV Receiving isochronous data.
183
184 IEC61883_DIR_XMIT Transmitting isochronous data.
185
186 ii_bus_speed chooses bus speed to be used and can be either
187 IEC61883_S100, IEC61883_S200 or IEC61883_S400.
188
189 ii_channel is a mask that specifies an isochronous channel number to
190 be used, with the Nth bit representing channel N. When transmitting
191 data, several bits can be set at a time, in which case the driver
192 chooses one, for example, 0x3FF means a range from 0 to 9. In case of
193 receive, only one bit can be set.
194
195 ii_dbs specifies data block size in quadlets, for example, DBS value
196 for SD-DVCR is 0x78. Refer to IEC 61883 for more details on DBS.
197
198 ii_fn specifies fraction number, which defines the number of blocks in
199 which a source packet is divided. Allowed values are from 0 to 3.
200 Refer to IEC 61883 for more details on FN.
201
202 Data rate expected by the AV device can be lower than the bus speed,
203 in which case the driver has to periodically insert empty packets into
204 the data stream to avoid device buffer overflows. This rate is
205 specified with a fraction N/D, set by ii_rate_n and ii_rate_d
206 respectively. Any integer numbers can be used, or the following
207 predefined constants:
208
209 IEC61883_RATE_N_DV_NTSC
210 IEC61883_RATE_D_DV_NTSC Data rate expected by DV-NTSC devices.
211
212 IEC61883_RATE_N_DV_PAL
213 IEC61883_RATE_D_DV_PAL Data rate expected by DV-PAL devices.
214
215 During data transmission, a timestamp based on the current value of
216 the cycle timer is usually required. ii_ts_mode defines timestamp
217 mode to be used:
218
219 IEC61883_TS_SYT Driver puts a timestamp in the SYT field of the
220 first CIP header of each frame.
221
222 IEC61883_TS_NONE No timestamps.
223
224 ii_dbs, ii_fn, ii_rate_n, ii_rate_d and ii_ts_mode are only required
225 for transmission. In other case these should be set to 0.
226
227 ii_flags should be set to 0.
228
229 If command succeeds, ii_handle contains a handle that should be used
230 with other isochronous commands. ii_frame_rcnt contains the number of
231 allocated frames (can be less than ii_frame_cnt). ii_mmap_off
232 contains an offset to be used in mmap(2), for example, to map an
233 entire data receive buffer:
234
235 pa = mmap(NULL, init.ii_pkt_size *
236 init.ii_frame_size * init.ii_frame_rcnt,
237 PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);
238
239 ii_rchannel contains channel number.
240
241 In case of command success, ii_error is set to 0; otherwise one of the
242 following values can be returned:
243
244 IEC61883_ERR_NOMEM Not enough memory for the data buffer.
245
246 IEC61883_ERR_NOCHANNEL Cannot allocate isochronous channel.
247
248 IEC61883_ERR_PKT_SIZE Packet size is not allowed at this bus speed.
249
250 IEC61883_ERR_VERSION Interface version is not supported.
251
252 IEC61883_ERR_INVAL One or more the parameters are invalid
253
254 IEC61883_ERR_OTHER Unspecified error type.
255
256 IEC61883_ISOCH_FINI
257
258 Argument is a handle returned by IEC61883_ISOCH_INIT. This command
259 frees any resources associated with this handle. There must be no
260 active transfers and the data buffer must be unmapped; otherwise the
261 command fails.
262
263 IEC61883_START
264
265 This command starts an isochronous transfer. The argument is a handle
266 returned by IEC61883_ISOCH_INIT.
267
268 IEC61883_STOP
269
270 This command stops an isochronous transfer. The argument is a handle
271 returned by IEC61883_ISOCH_INIT.
272
273 IEC61883_RECV
274
275 This command is used to receive full frames and return empty frames to
276 the driver. The argument is a pointer to the structure:
277
278 typedef struct iec61883_recv {
279 int rx_handle; /* isoch handle */
280 int rx_flags; /* flags */
281 iec61883_xfer_t rx_xfer; /* xfer params */
282 } iec61883_recv_t;
283
284 typedef struct iec61883_xfer {
285 int xf_empty_idx; /* first empty frame */
286 int xf_empty_cnt; /* empty frame count */
287 int xf_full_idx; /* first full frame */
288 int xf_full_cnt; /* full frame count */
289 int xf_error; /* error */
290 } iec61883_xfer_t;
291
292 rx_flags should be set to 0.
293
294 An application sets xf_empty_idx and xf_empty_cnt to indicate frames
295 it no longer needs. E. g. if a buffer consists of 6 frames,
296 xf_empty_idx is 4, xf_empty_cnt is 3 - means that frames 4, 5 and 0
297 can now be reused by the driver. If there are no empty frames, for
298 example, the first time this command is called, xf_empty_cnt should be
299 set to 0.
300
301 When the command returns, xf_full_idx and xf_full_cnt specifies the
302 frames that are full. xf_error is always 0.
303
304 In general, AV frame boundaries are not aligned with the frame buffer
305 boundaries, because the first received packet might not be the first
306 packet of an AV frame, and, in contrast with the read/write method,
307 the driver does not remove empty CIP packets.
308
309 Applications should detect empty packets by comparing adjacent
310 packets' continuity counters (DBC field of the CIP header).
311
312 IEC61883_XMIT
313
314 This command is used to transmit full frames and get more empty frames
315 from the driver. The argument is a pointer to the structure:
316
317 typedef struct iec61883_xmit {
318 int tx_handle; /* isoch handle */
319 int tx_flags; /* flags */
320 iec61883_xfer_t tx_xfer; /* xfer params */
321 int tx_miss_cnt; /* missed cycles */
322 } iec61883_xmit_t;
323
324 tx_flags should be set to zero.
325
326 The application sets xf_full_idx and xf_full_cnt to specify frames it
327 wishes to transmit. If there are no frames to transmit (e. g. the
328 first time this command is called), xf_full_cnt should be set to 0.
329
330 When the command returns, xf_empty_idx and xf_empty_cnt specifies
331 empty frames which can be to transmit more data. xf_error is always
332 0.
333
334 tx_miss_cnt contains the number of isochronous cycles missed since
335 last transfer due to data buffer under run. This can happen when an
336 application does not supply data fast enough. For the purposes of
337 time stamping, the driver considers the first packet in a frame buffer
338 to be the first packet of an AV frame.
339
340 IEC61883_PLUG_INIT
341
342 This command returns a handle for the specified plug. The argument is
343 a pointer to the structure:
344
345 typedef struct iec61883_plug_init {
346 int pi_ver; /* interface version */
347 int pi_loc; /* plug location */
348 int pi_type; /* plug type */
349 int pi_num; /* plug number */
350 int pi_flags; /* flags */
351 int pi_handle; /* plug handle */
352 int pi_rnum; /* plug number */
353 } iec61883_plug_init_t;
354
355 pi_ver should be set to IEC61883_V1_0.
356
357 pi_loc specifies plug location:
358
359 IEC61883_LOC_LOCAL On the local unit (local plug). A plug control
360 register (PCR) is allocated. Command fails if
361 the plug already exists
362
363 IEC61883_LOC_REMOTE On the remote unit (remote plug). The plug
364 should exist on the remote unit, otherwise the
365 command fails.
366
367 pi_type specifies isochronous plug type:
368
369 IEC61883_PLUG_IN
370 IEC61883_PLUG_OUT
371
372 Input or output plugs.
373
374 IEC61883_PLUG_MASTER_IN
375 IEC61883_PLUG_MASTER_OUT
376
377 Master input or master output plug. These plugs always exist on
378 the local unit.
379
380 pi_num specifies plug number. This should be 0 for master plugs, and
381 from 0 to 31 for input/output plugs. Alternatively, a special value
382 IEC61883_PLUG_ANY can be used to let the driver choose a free plug
383 number, create the plug and return the number in pi_rnum.
384
385 pi_flags should be set to 0.
386
387 If the command succeeds, pi_handle contains a handle that should be
388 used with other plug commands.
389
390 IEC61883_PLUG_FINI
391
392 Argument is a handle returned by IEC61883_PLUG_INIT. This command
393 frees any resources associated with this handle, including the PCR.
394
395 IEC61883_PLUG_REG_READ
396
397 Read plug register value. The argument is a pointer to the structure:
398
399 typedef struct iec61883_plug_reg_val {
400 int pr_handle; /* plug handle */
401 uint32_t pr_val; /* register value */
402 } iec61883_plug_reg_val_t;
403
404 pr_handle is a handle returned by IEC61883_PLUG_INIT. Register value
405 is returned in pr_val.
406
407 IEC61883_PLUG_REG_CAS
408
409 Atomically compare and swap plug register value. The argument is a
410 pointer to the structure:
411
412 typedef struct iec61883_plug_reg_lock {
413 int pl_handle; /* plug handle */
414 uint32_t pl_arg; /* compare arg */
415 uint32_t pl_data; /* write value */
416 UINT32_t pl_old; /* original value */
417 } iec61883_plug_reg_lock_t;
418
419 pr_handle is a handle returned by IEC61883_PLUG_INIT.
420
421 Original register value is compared with pl_arg and if they are equal,
422 register value is replaced with pl_data. In any case, the original
423 value is stored in pl_old.
424
425 The following commands only apply to asynchronous nodes:
426
427 IEC61883_ARQ_GET_IBUF_SIZE
428
429 This command returns current incoming ARQ buffer size. The argument
430 is a pointer to int.
431
432 IEC61883_ARQ_SET_IBUF_SIZE
433
434 This command changes incoming ARQ buffer size. The argument is the
435 new buffer size in bytes.
436
437 FILES
438 /dev/av/N/async Device node for asynchronous data
439
440 /dev/av/N/isoch Device has been disconnected
441
442 ERRORS
443 EIO Bus operation failed. DMA failure.
444
445 EFAULT ioctl(2) argument points to an illegal address.
446
447 EINVAL Invalid argument or argument combination.
448
449 ENODEV Device has been disconnected.
450
451 ARCHITECTURE
452 All
453
454 INTERFACE STABILITY
455 Committed
456
457 SEE ALSO
458 ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
459 av1394(7D)
460
461 IIEC 61883 Consumer audio/video equipment - Digital interface.
462
463 IEEE Std 1394-1995 Standard for a High Performance Serial Bus.
464
465 illumos July 9, 2018 illumos
|