Print this page
10521 Convert iec61883(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/iec61883.7i.man.txt
+++ new/usr/src/man/man7i/iec61883.7i.man.txt
1 1 IEC61883(7I) Ioctl Requests IEC61883(7I)
2 2
3 -
4 -
5 3 NAME
6 - iec61883 - IEC 61883 interfaces
4 + iec61883 - IEC 61883 interfaces
7 5
8 6 SYNOPSIS
9 - #include <sys/av/iec61883.h>
7 + #include <sys/av/iec61883.h>
10 8
11 -
12 9 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).
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).
19 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.
20 19
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 20 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).
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).
28 23
29 24 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.
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.
36 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).
37 35
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).
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 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.
42 46
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.
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.
48 50
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 51 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.
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.
67 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.
68 62
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.
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).
72 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.
73 72
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 73 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.
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.
90 78
91 79 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):
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):
95 83
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;
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;
105 93
94 + arq_type contains ARQ type:
106 95
96 + IEC61883_ARQ_FCP_CMD
97 + IEC61883_ARQ_FCP_RESP
107 98
99 + FCP command and response frame respectively. Outgoing frames are sent
100 + using write(2), incoming frames are received with read(2).
108 101
109 - arq_type contains ARQ type:
102 + See IIEC 61883-1 for the FCP frame structure definition.
110 103
111 - IEC61883_ARQ_FCP_CMD
112 - IEC61883_ARQ_FCP_RESP
104 + IEC61883_ARQ_BUS_RESET
113 105
114 - FCP command and response frame respectively. Outgoing frames are
115 - sent using write(2), incoming frames are received with read(2).
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.
116 108
117 - See IEC 61883-1 for the FCP frame structure definition.
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.
118 112
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 113 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.
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.
135 117
136 118 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.
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.
139 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.
140 127
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.
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.
146 131
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 132 poll(2)
153 - Applications can poll(2) asynchronous nodes on the POLLIN event.
133 + Applications can poll(2) asynchronous nodes on the POLLIN event.
154 134
155 135 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.
136 + In case of a bus reset, the driver notifies an application by generating
137 + an ARQ of type IEC61883_ARQ_BUS_RESET.
158 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.
159 142
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 143 IOCTLS
165 - The following commands only apply to isochronous nodes:
144 + The following commands only apply to isochronous nodes:
166 145
167 - IEC61883_ISOCH_INIT
146 + IEC61883_ISOCH_INIT
168 147
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:
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:
172 151
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;
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;
193 172
173 + ii_version should be set to IEC61883_V1_0.
194 174
195 - ii_version should be set to IEC61883_V1_0.
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.
196 179
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.
180 + ii_direction can take one of the following values:
201 181
202 - ii_direction can take one of the following values:
182 + IEC61883_DIR_RECV Receiving isochronous data.
203 183
204 - IEC61883_DIR_RECV
184 + IEC61883_DIR_XMIT Transmitting isochronous data.
205 185
206 - Receiving isochronous data.
186 + ii_bus_speed chooses bus speed to be used and can be either
187 + IEC61883_S100, IEC61883_S200 or IEC61883_S400.
207 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.
208 194
209 - IEC61883_DIR_XMIT
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.
210 197
211 - Transmitting isochronous data.
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.
212 201
213 - ii_bus_speed chooses bus speed to be used and can be either
214 - IEC61883_S100, IEC61883_S200 or IEC61883_S400.
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:
215 208
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.
209 + IEC61883_RATE_N_DV_NTSC
210 + IEC61883_RATE_D_DV_NTSC Data rate expected by DV-NTSC devices.
221 211
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.
212 + IEC61883_RATE_N_DV_PAL
213 + IEC61883_RATE_D_DV_PAL Data rate expected by DV-PAL devices.
225 214
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.
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:
229 218
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:
219 + IEC61883_TS_SYT Driver puts a timestamp in the SYT field of the
220 + first CIP header of each frame.
236 221
237 - IEC61883_RATE_N_DV_NTSC IEC61883_RATE_D_DV_NTSC
222 + IEC61883_TS_NONE No timestamps.
238 223
239 - Data rate expected by DV-NTSC devices.
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.
240 226
227 + ii_flags should be set to 0.
241 228
242 - IEC61883_RATE_N_DV_PAL IEC61883_RATE_D_DV_PAL
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:
243 234
244 - Data rate expected by DV-PAL devices.
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);
245 238
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:
239 + ii_rchannel contains channel number.
249 240
250 - IEC61883_TS_SYT
241 + In case of command success, ii_error is set to 0; otherwise one of the
242 + following values can be returned:
251 243
252 - Driver puts a timestamp in the SYT field of the first CIP
253 - header of each frame.
244 + IEC61883_ERR_NOMEM Not enough memory for the data buffer.
254 245
246 + IEC61883_ERR_NOCHANNEL Cannot allocate isochronous channel.
255 247
256 - IEC61883_TS_NONE
248 + IEC61883_ERR_PKT_SIZE Packet size is not allowed at this bus speed.
257 249
258 - No timestamps.
250 + IEC61883_ERR_VERSION Interface version is not supported.
259 251
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.
252 + IEC61883_ERR_INVAL One or more the parameters are invalid
262 253
263 - ii_flags should be set to 0.
254 + IEC61883_ERR_OTHER Unspecified error type.
264 255
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:
256 + IEC61883_ISOCH_FINI
270 257
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);
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.
274 262
263 + IEC61883_START
275 264
276 - ii_rchannel contains channel number.
265 + This command starts an isochronous transfer. The argument is a handle
266 + returned by IEC61883_ISOCH_INIT.
277 267
278 - In case of command success, ii_error is set to 0; otherwise one of
279 - the following values can be returned:
268 + IEC61883_STOP
280 269
281 - IEC61883_ERR_NOMEM
270 + This command stops an isochronous transfer. The argument is a handle
271 + returned by IEC61883_ISOCH_INIT.
282 272
283 - Not enough memory for the data buffer.
273 + IEC61883_RECV
284 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:
285 277
286 - IEC61883_ERR_NOCHANNEL
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;
287 283
288 - Cannot allocate isochronous channel.
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;
289 291
292 + rx_flags should be set to 0.
290 293
291 - IEC61883_ERR_PKT_SIZE
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.
292 300
293 - Packet size is not allowed at this bus speed.
301 + When the command returns, xf_full_idx and xf_full_cnt specifies the
302 + frames that are full. xf_error is always 0.
294 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.
295 308
296 - IEC61883_ERR_VERSION
309 + Applications should detect empty packets by comparing adjacent
310 + packets' continuity counters (DBC field of the CIP header).
297 311
298 - Interface version is not supported.
312 + IEC61883_XMIT
299 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:
300 316
301 - IEC61883_ERR_INVAL
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;
302 323
303 - One or more the parameters are invalid
324 + tx_flags should be set to zero.
304 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.
305 329
306 - IEC61883_ERR_OTHER
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.
307 333
308 - Unspecified error type.
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.
309 339
340 + IEC61883_PLUG_INIT
310 341
342 + This command returns a handle for the specified plug. The argument is
343 + a pointer to the structure:
311 344
312 - IEC61883_ISOCH_FINI
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;
313 354
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.
355 + pi_ver should be set to IEC61883_V1_0.
318 356
357 + pi_loc specifies plug location:
319 358
320 - IEC61883_START
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
321 362
322 - This command starts an isochronous transfer. The argument is a
323 - handle returned by IEC61883_ISOCH_INIT.
363 + IEC61883_LOC_REMOTE On the remote unit (remote plug). The plug
364 + should exist on the remote unit, otherwise the
365 + command fails.
324 366
367 + pi_type specifies isochronous plug type:
325 368
326 - IEC61883_STOP
369 + IEC61883_PLUG_IN
370 + IEC61883_PLUG_OUT
327 371
328 - This command stops an isochronous transfer. The argument is a
329 - handle returned by IEC61883_ISOCH_INIT.
372 + Input or output plugs.
330 373
374 + IEC61883_PLUG_MASTER_IN
375 + IEC61883_PLUG_MASTER_OUT
331 376
332 - IEC61883_RECV
377 + Master input or master output plug. These plugs always exist on
378 + the local unit.
333 379
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:
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.
336 384
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;
385 + pi_flags should be set to 0.
342 386
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;
387 + If the command succeeds, pi_handle contains a handle that should be
388 + used with other plug commands.
350 389
390 + IEC61883_PLUG_FINI
351 391
352 - rx_flags should be set to 0.
392 + Argument is a handle returned by IEC61883_PLUG_INIT. This command
393 + frees any resources associated with this handle, including the PCR.
353 394
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.
395 + IEC61883_PLUG_REG_READ
360 396
361 - When the command returns, xf_full_idx and xf_full_cnt specifies the
362 - frames that are full. xf_error is always 0.
397 + Read plug register value. The argument is a pointer to the structure:
363 398
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.
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;
368 403
369 - Applications should detect empty packets by comparing adjacent
370 - packets' continuity counters (DBC field of the CIP header).
404 + pr_handle is a handle returned by IEC61883_PLUG_INIT. Register value
405 + is returned in pr_val.
371 406
407 + IEC61883_PLUG_REG_CAS
372 408
373 - IEC61883_XMIT
409 + Atomically compare and swap plug register value. The argument is a
410 + pointer to the structure:
374 411
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:
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;
377 418
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;
419 + pr_handle is a handle returned by IEC61883_PLUG_INIT.
384 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.
385 424
386 - tx_flags should be set to zero.
425 + The following commands only apply to asynchronous nodes:
387 426
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.
427 + IEC61883_ARQ_GET_IBUF_SIZE
391 428
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.
429 + This command returns current incoming ARQ buffer size. The argument
430 + is a pointer to int.
395 431
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.
432 + IEC61883_ARQ_SET_IBUF_SIZE
399 433
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.
434 + This command changes incoming ARQ buffer size. The argument is the
435 + new buffer size in bytes.
402 436
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 437 FILES
515 - /dev/av/N/async
516 - Device node for asynchronous data
438 + /dev/av/N/async Device node for asynchronous data
517 439
440 + /dev/av/N/isoch Device has been disconnected
518 441
519 - /dev/av/N/isoch
520 - Device has been disconnected
521 -
522 -
523 442 ERRORS
524 - EIO
525 - Bus operation failed.
443 + EIO Bus operation failed. DMA failure.
526 444
527 - DMA failure.
445 + EFAULT ioctl(2) argument points to an illegal address.
528 446
447 + EINVAL Invalid argument or argument combination.
529 448
530 - EFAULT
531 - ioctl(2) argument points to an illegal address.
449 + ENODEV Device has been disconnected.
532 450
451 +ARCHITECTURE
452 + All
533 453
534 - EINVAL
535 - Invalid argument or argument combination.
454 +INTERFACE STABILITY
455 + Committed
536 456
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 457 SEE ALSO
557 - ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
558 - av1394(7D)
458 + ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
459 + av1394(7D)
559 460
461 + IIEC 61883 Consumer audio/video equipment - Digital interface.
560 462
561 - IEC 61883 Consumer audio/video equipment - Digital interface
463 + IEEE Std 1394-1995 Standard for a High Performance Serial Bus.
562 464
563 -
564 - IEEE Std 1394-1995 Standard for a High Performance Serial Bus
565 -
566 -
567 -
568 - March 27, 2009 IEC61883(7I)
465 +illumos July 9, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX