Print this page
10521 Convert iec61883(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/iec61883.7i
+++ new/usr/src/man/man7i/iec61883.7i
1 -'\" te
2 1 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
3 2 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 3 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
5 4 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH IEC61883 7I "Mar 27, 2009"
7 -.SH NAME
8 -iec61883 \- IEC 61883 interfaces
9 -.SH SYNOPSIS
10 -.LP
11 -.nf
12 -#include <sys/av/iec61883.h>
13 -.fi
14 -
15 -.SH DESCRIPTION
16 -.sp
17 -.LP
5 +.Dd July 9, 2018
6 +.Dt IEC61883 7I
7 +.Os
8 +.Sh NAME
9 +.Nm iec61883
10 +.Nd IEC 61883 interfaces
11 +.Sh SYNOPSIS
12 +.In sys/av/iec61883.h
13 +.Sh DESCRIPTION
18 14 The set of interfaces described in this man page can be used to control and
19 15 exchange data with consumer audio/video devices using protocols specified
20 -in\fIIEC 61883 Consumer Electronic Audio/Video Equipment - Digital
21 -Interface\fR, including Common Isochronous Packet (CIP), Connection Management
16 +in
17 +.%T "IIEC 61883 Consumer Electronic Audio/Video Equipment - Digital Interface"
18 +including Common Isochronous Packet (CIP), Connection Management
22 19 Procedures (CMP) and Function Control Protocol (FCP).
23 -.sp
24 -.LP
25 -An \fBiec61883\fR compliant driver exports two device nodes for isochronous and
26 -for asynchronous transactions. See the \fBFILES\fR section of this man page for
27 -the namespace definition.
28 -.SS "Isochronous Transfers"
29 -.sp
30 -.LP
20 +.Pp
21 +An
22 +.Nm
23 +compliant driver exports two device nodes for isochronous and
24 +for asynchronous transactions.
25 +See the
26 +.Sx FILES
27 +section of this man page for the namespace definition.
28 +.Ss "Isochronous Transfers"
31 29 Two methods are provided to receive/transmit isochronous data: using
32 -\fBmmap\fR(2) in combination with \fBioctl\fR(2), and \fBread\fR(2) or
33 -\fBwrite\fR(2).
34 -.SS "Mmap/Ioctl"
35 -.sp
36 -.LP
30 +.Xr mmap 2
31 +in combination with
32 +.Xr ioctl 2 ,
33 +and
34 +.Xr read 2
35 +or
36 +.Xr write 2 .
37 +.Ss "Mmap/Ioctl"
37 38 This method provides better performance and finer-grained control than
38 -read/write, and is a method of choice for most applications. The data buffer is
39 +read/write, and is a method of choice for most applications.
40 +The data buffer is
39 41 mapped into a user process address space, which means no data copying between
40 -the kernel and an application is necessary. Synchronization between user
41 -processes and the driver is performed using \fBioctl\fR(2) commands.
42 -.sp
43 -.LP
42 +the kernel and an application is necessary.
43 +Synchronization between user
44 +processes and the driver is performed using
45 +.Xr ioctl 2
46 +commands.
47 +.Pp
44 48 An application allocates resources for isochronous transfer using
45 -\fBIEC61883_ISOCH_INIT\fR. Then the data buffer can be mapped into the process
46 -space using \fBmmap\fR(2).
47 -.sp
48 -.LP
49 +.Dv IEC61883_ISOCH_INIT .
50 +Then the data buffer can be mapped into the process
51 +space using
52 +.Xr mmap 2 .
53 +.Pp
49 54 A circular data buffer consists of one or more equal size frame buffers
50 55 (further referred to as frames, unless to avoid ambiguity with AV frames).
51 56 Frames are numbered starting with zero and are always transferred sequentially.
52 -Frames consist equal sized packets. Each packet contains a CIP header and one
53 -or more data blocks.
54 -.sp
55 -.LP
57 +Frames consist equal sized packets.
58 +Each packet contains a CIP header and one or more data blocks.
59 +.Pp
56 60 A driver and an application act as a producer and a consumer: producer supplies
57 -\fBfull\fR frames (filled with data) to the consumer, and the producer is not
58 -allowed to access those frames until the consumer claims them \fBempty\fR.
59 -.sp
60 -.LP
61 -A transfer can be initiated and suspended with \fBIEC61883_START\fR and
62 -\fBIEC61883_STOP\fR commands respectively. \fBIEC61883_RECV\fR or
63 -\fBIEC61883_XMIT\fR is used for producer-consumer synchronization.
64 -.SS "Read/Write"
65 -.sp
66 -.LP
67 -Using this method, an application calls \fBread\fR(2) or \fBwrite\fR(2) to
68 -receive or transmit a specified amount of data. Bus-specific overhead, such as
69 -isochronous packet headers, is handled by the driver and is not exposed to
70 -applications. Data returned by \fBread\fR(2) contains CIP headers and data
71 -blocks. Empty packets are not returned by \fBread\fR(2). \fBwrite\fR(2) data
72 -should meet the same requirements.
73 -.sp
74 -.LP
75 -If one or more channels have been allocated since \fBopen\fR(2) (see
76 -\fBIEC61883_ISOCH_INIT\fR), the data is received/transmitted using channel that
77 -was created the last.
78 -.sp
79 -.LP
61 +.Em full
62 +frames (filled with data) to the consumer, and the producer is not
63 +allowed to access those frames until the consumer claims them
64 +.Em empty .
65 +.Pp
66 +A transfer can be initiated and suspended with
67 +.Dv IEC61883_START
68 +and
69 +.Dv IEC61883_STOP
70 +commands respectively.
71 +.Dv IEC61883_RECV
72 +or
73 +.Dv IEC61883_XMIT
74 +is used for producer-consumer synchronization.
75 +.Ss "Read/Write"
76 +Using this method, an application calls
77 +.Xr read 2
78 +or
79 +.Xr write 2
80 +to receive or transmit a specified amount of data.
81 +Bus-specific overhead, such as isochronous packet headers, is handled by the driver
82 +and is not exposed to applications.
83 +Data returned by
84 +.Xr read 2
85 +contains CIP headers and data blocks.
86 +Empty packets are not returned by
87 +.Xr read 2 .
88 +.Xr write 2
89 +data should meet the same requirements.
90 +.Pp
91 +If one or more channels have been allocated since
92 +.Xr open 2
93 +(see
94 +.Dv IEC61883_ISOCH_INIT ) ,
95 +the data is received/transmitted using channel that was created the last.
96 +.Pp
80 97 If no channels were allocated, the driver uses the broadcast channel by default
81 -and allocates the default-size data buffer. During transmit, the first packet's
82 -CIP header is used to auto-detect the data format. If it is one of the formats
83 -supported by the driver, it is properly transmitted (with inserted empty
84 -packets and timestamps).
85 -.sp
86 -.LP
98 +and allocates the default-size data buffer.
99 +During transmit, the first packet's CIP header is used to auto-detect the data format.
100 +If it is one of the formats supported by the driver, it is properly transmitted (with
101 +inserted empty packets and timestamps).
102 +.Pp
87 103 For both methods, if during transmit the driver runs out of data, it transmits
88 104 empty packets containing only a CIP header of the next to be transmitted
89 -packet, as defined in \fIIEC 61883-1\fR.
90 -.SS "Connection Management Procedures"
91 -.sp
92 -.LP
105 +packet, as defined in
106 +.Em IEC 61883-1 .
107 +.Ss "Connection Management Procedures"
93 108 Applications wishing to follow Connection Management Procedures (CMP) in
94 -combination with isochronous transfers should use the \fBioctl\fR(2)
95 -\fBIEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ\fR and
96 -\fBIEC61883_PLUG_REG_CAS\fR commands.
97 -.SS "Asynchronous Transactions"
98 -.sp
99 -.LP
100 -\fBread\fR(2), \fBwrite\fR(2), \fBioctl\fR(2), and \fBpoll\fR(2) can be used
101 -with asynchronous nodes. Asynchronous data exchange between a driver and an
109 +combination with isochronous transfers should use the
110 +.Xr ioctl 2
111 +.Dv IEC61883_PLUG_INIT ,
112 +.Dv IEC61883_PLUG_FINI ,
113 +.Dv IEC61883_PLUG_REG_READ
114 +and
115 +.Dv IEC61883_PLUG_REG_CAS
116 +commands.
117 +.Ss "Asynchronous Transactions"
118 +.Xr read 2 ,
119 +.Xr write 2 ,
120 +.Xr ioctl 2 ,
121 +and
122 +.Xr poll 2
123 +can be used
124 +with asynchronous nodes.
125 +Asynchronous data exchange between a driver and an
102 126 application utilizes a common data structure called asynchronous request (ARQ):
103 -.sp
104 -.in +2
105 -.nf
127 +.Bd -literal -offset 2n
106 128 typedef struct iec61883_arq {
107 129 int arq_type;
108 130 int arq_len;
109 131 union {
110 132 uint32_t quadlet;
111 133 uint64_t octlet;
112 134 uint8_t buf[8];
113 135 } arq_data;
114 136 } iec61883_arq_t;
115 -.fi
116 -.in -2
117 -.sp
118 -
119 -.sp
120 -.LP
121 -\fBarq_type\fR contains \fBARQ\fR type:
122 -.sp
123 -.ne 2
124 -.na
125 -\fB\fBIEC61883_ARQ_FCP_CMD\fR\fR
126 -.ad
127 -.br
128 -.na
129 -\fB\fBIEC61883_ARQ_FCP_RESP\fR\fR
130 -.ad
131 -.sp .6
132 -.RS 4n
133 -\fBFCP\fR command and response frame respectively. Outgoing frames are sent
134 -using \fBwrite\fR(2), incoming frames are received with \fBread\fR(2).
135 -.sp
136 -See \fIIEC 61883-1\fR for the FCP frame structure definition.
137 -.RE
138 -
139 -.sp
140 -.ne 2
141 -.na
142 -\fB\fBIEC61883_ARQ_BUS_RESET\fR\fR
143 -.ad
144 -.sp .6
145 -.RS 4n
146 -Returned by the driver when a bus reset occurs. There is no data associated
147 -with this request type, and \fBarq_len\fR is set to 0.
148 -.RE
149 -
150 -.sp
151 -.LP
152 -If \fBarq_len\fR is 4 or 8, then data should be supplied in
153 -\fBarq_data.quadlet\fR or \fBarq_data.octlet\fR respectively, otherwise up to 8
154 -bytes can be put in \fBarq_data.buf\fR, with the rest of the data following
155 -immediately after.
156 -.SS "write(2)"
157 -.sp
158 -.LP
159 -For a request to be sent to a target, an \fBiec61883_arq_t\fR structure along
160 -with associated data is passed to the driver using \fBwrite\fR(2).
161 -\fBwrite()\fR blocks until the request is completed.
162 -.SS "read(2)"
163 -.sp
164 -.LP
165 -A driver collects incoming ARQs in the internal buffer. Buffer size can be
166 -changed using the \fBioctl\fR(2) command \fBIEC61883_FCP_SET_IBUF_SIZE\fR.
167 -.sp
168 -.LP
169 -Reading an ARQ takes one or two steps depending on data length. An application
170 -first reads \fBsizeof (iec61883_arq_t)\fR bytes: if \fBarq_len\fR is less than
171 -or equal 4, which is usually the case, no additional step is needed. Otherwise,
172 -the remaining \fBarq_len - 4\fR bytes should be read and concatenated.
173 -.sp
174 -.LP
175 -\fBread\fR(2) blocks until the specified amount of data is available, unless
176 -\fBO_NONBLOCK\fR or \fBO_NDELAY\fR flag was set during \fBopen\fR(2), in which
177 -case \fBread\fR(2) returns immediately.
178 -.SS "poll(2)"
179 -.sp
180 -.LP
181 -Applications can \fBpoll\fR(2) asynchronous nodes on the \fBPOLLIN\fR event.
182 -.SS "Bus Reset"
183 -.sp
184 -.LP
137 +.Ed
138 +.Pp
139 +.Fa arq_type
140 +contains
141 +.Sy ARQ
142 +type:
143 +.Pp
144 +.Bl -tag -width " " -compact
145 +.It Dv IEC61883_ARQ_FCP_CMD
146 +.It Dv IEC61883_ARQ_FCP_RESP
147 +.Pp
148 +.Sy FCP
149 +command and response frame respectively.
150 +Outgoing frames are sent using
151 +.Xr write 2 ,
152 +incoming frames are received with
153 +.Xr read 2 .
154 +.Pp
155 +See
156 +.Em IIEC 61883-1
157 +for the FCP frame structure definition.
158 +.Pp
159 +.It Dv IEC61883_ARQ_BUS_RESET
160 +.Pp
161 +Returned by the driver when a bus reset occurs.
162 +There is no data associated with this request type, and \fBarq_len\fR is set to 0.
163 +.El
164 +.Pp
165 +If
166 +.Fa arq_len
167 +is 4 or 8, then data should be supplied in
168 +.Fa arq_data.quadlet
169 +or
170 +.Fa arq_data.octlet
171 +respectively, otherwise up to 8 bytes can be put in
172 +.Fa arq_data.buf ,
173 +with the rest of the data following immediately after.
174 +.Ss "write(2)"
175 +For a request to be sent to a target, an
176 +.Vt iec61883_arq_t
177 +structure along with associated data is passed to the driver using
178 +.Xr write 2 .
179 +.Xr write 2
180 +blocks until the request is completed.
181 +.Ss "read(2)"
182 +A driver collects incoming ARQs in the internal buffer.
183 +Buffer size can be changed using the
184 +.Xr ioctl 2
185 +command
186 +.Vt IEC61883_FCP_SET_IBUF_SIZE .
187 +.Pp
188 +Reading an ARQ takes one or two steps depending on data length.
189 +An application
190 +first reads
191 +.Ql sizeof (iec61883_arq_t)
192 +bytes: if
193 +.Fa arq_len
194 +is less than or equal 4, which is usually the case, no additional step is needed.
195 +Otherwise,
196 +the remaining
197 +.Ql arq_len - 4
198 +bytes should be read and concatenated.
199 +.Pp
200 +.Xr read 2
201 +blocks until the specified amount of data is available, unless
202 +.Dv O_NONBLOCK
203 +or
204 +.Dv O_NDELAY
205 +flag was set during
206 +.Xr open 2 ,
207 +in which case
208 +.Xr read 2
209 +returns immediately.
210 +.Ss "poll(2)"
211 +Applications can
212 +.Xr poll 2
213 +asynchronous nodes on the
214 +.Dv POLLIN
215 +event.
216 +.Ss "Bus Reset"
185 217 In case of a bus reset, the driver notifies an application by generating an
186 -\fBARQ\fR of type \fBIEC61883_ARQ_BUS_RESET\fR.
187 -.sp
188 -.LP
218 +.Sy ARQ
219 +of type
220 +.Dv IEC61883_ARQ_BUS_RESET .
221 +.Pp
189 222 If there were established isochronous connections before bus reset, the driver
190 -attempts to restore all connections as described in \fIIEC 61883\fR and resume
191 -any active transfers that were in progress.
192 -.SH IOCTLS
193 -.sp
194 -.LP
223 +attempts to restore all connections as described in
224 +.Em IEC 61883
225 +and resume any active transfers that were in progress.
226 +.Sh IOCTLS
195 227 The following commands only apply to isochronous nodes:
196 -.sp
197 -.ne 2
198 -.na
199 -\fB\fBIEC61883_ISOCH_INIT\fR\fR
200 -.ad
201 -.sp .6
202 -.RS 4n
228 +.Bl -tag -width " "
229 +.It Dv IEC61883_ISOCH_INIT
230 +.Pp
203 231 This command allocates a data buffer and isochronous resources (if necessary)
204 -for the isochronous transfer. The argument is a pointer to the structure:
205 -.sp
206 -.in +2
207 -.nf
232 +for the isochronous transfer.
233 +The argument is a pointer to the structure:
234 +.Bd -literal -offset 2n
208 235 typedef struct iec61883_isoch_init {
209 - int ii_version; /* interface version */
236 + int ii_version; /* interface version */
210 237 int ii_pkt_size; /* packet size */
211 238 int ii_frame_size; /* packets/frame */
212 239 int ii_frame_cnt; /* # of frames */
213 240 int ii_direction; /* xfer direction */
214 241 int ii_bus_speed; /* bus speed */
215 242 uint64_t ii_channel; /* channel mask */
216 243 int ii_dbs; /* DBS */
217 244 int ii_fn; /* FN */
218 245 int ii_rate_n; /* rate numerator */
219 246 int ii_rate_d; /* rate denominator */
220 247 int ii_ts_mode; /* timestamp mode */
221 248 int ii_flags; /* flags */
222 249 int ii_handle; /* isoch handle */
223 250 int ii_frame_rcnt; /* # of frames */
224 - off_t *ii_mmap_off /* mmap offset */
251 + off_t *ii_mmap_off /* mmap offset */
225 252 int ii_rchannel; /* channel */
226 253 int ii_error; /* error code */
227 254 } iec61883_isoch_init_t;
228 -.fi
229 -.in -2
230 -.sp
231 -
232 -\fBii_version\fR should be set to \fBIEC61883_V1_0\fR.
233 -.sp
234 -The driver attempts to allocate a data buffer consisting of \fBii_frame_cnt\fR
235 -frames, with \fBii_frame_size\fR packets in each frame. Packet size in bytes is
236 -specified by \fBii_pkt_size\fR specifies and should be a multiple of 512 and
237 -compatible with \fBii_bus_speed\fR.
238 -.sp
239 -\fBii_direction\fR can take one of the following values:
240 -.sp
241 -.ne 2
242 -.na
243 -\fB\fBIEC61883_DIR_RECV\fR\fR
244 -.ad
245 -.sp .6
246 -.RS 4n
255 +.Ed
256 +.Pp
257 +.Fa ii_version
258 +should be set to
259 +.Dv IEC61883_V1_0 .
260 +.Pp
261 +The driver attempts to allocate a data buffer consisting of
262 +.Fa ii_frame_cnt
263 +frames, with
264 +.Fa ii_frame_size
265 +packets in each frame.
266 +Packet size in bytes is specified by
267 +.Fa ii_pkt_size
268 +specifies and should be a multiple of 512 and compatible with
269 +.Fa ii_bus_speed .
270 +.Pp
271 +.Fa ii_direction
272 +can take one of the following values:
273 +.Bl -tag -width "IEC61883_DIR_RECV"
274 +.It Dv IEC61883_DIR_RECV
247 275 Receiving isochronous data.
248 -.RE
249 -
250 -.sp
251 -.ne 2
252 -.na
253 -\fB\fBIEC61883_DIR_XMIT\fR\fR
254 -.ad
255 -.sp .6
256 -.RS 4n
276 +.It Dv IEC61883_DIR_XMIT
257 277 Transmitting isochronous data.
258 -.RE
259 -
260 -\fBii_bus_speed\fR chooses bus speed to be used and can be either
261 -\fBIEC61883_S100, IEC61883_S200\fR or \fBIEC61883_S400\fR.
262 -.sp
263 -\fBii_channel\fR is a mask that specifies an isochronous channel number to be
264 -used, with the \fIN\fRth bit representing channel \fIN\fR. When transmitting
265 -data, several bits can be set at a time, in which case the driver chooses one,
266 -for example, \fB0x3FF\fR means a range from 0 to 9. In case of receive, only
267 -one bit can be set.
268 -.sp
269 -\fBii_dbs\fR specifies data block size in quadlets, for example, DBS value for
270 -\fBSD-DVCR\fR is \fB0x78\fR. Refer to \fIIEC 61883\fR for more details on DBS.
271 -.sp
272 -ii_fn specifies fraction number, which defines the number of blocks in which a
273 -source packet is divided. Allowed values are from 0 to 3. Refer to IEC 61883
278 +.El
279 +.Pp
280 +.Fa ii_bus_speed
281 +chooses bus speed to be used and can be either
282 +.Dv IEC61883_S100 ,
283 +.Dv IEC61883_S200
284 +or
285 +.Dv IEC61883_S400 .
286 +.Pp
287 +.Fa ii_channel
288 +is a mask that specifies an isochronous channel number to be
289 +used, with the
290 +.Em N Ns th
291 +bit representing channel
292 +.Em N .
293 +When transmitting data, several bits can be set at a time, in which case the
294 +driver chooses one, for example,
295 +.Sy 0x3FF
296 +means a range from 0 to 9.
297 +In case of receive, only one bit can be set.
298 +.Pp
299 +.Fa ii_dbs
300 +specifies data block size in quadlets, for example, DBS value for
301 +.Dv SD-DVCR
302 +is
303 +.Sy 0x78 .
304 +Refer to
305 +.Em IEC 61883
306 +for more details on DBS.
307 +.Pp
308 +.Fa ii_fn
309 +specifies fraction number, which defines the number of blocks in which a
310 +source packet is divided.
311 +Allowed values are from 0 to 3.
312 +Refer to
313 +.Em IEC 61883
274 314 for more details on FN.
275 -.sp
315 +.Pp
276 316 Data rate expected by the AV device can be lower than the bus speed, in which
277 317 case the driver has to periodically insert empty packets into the data stream
278 -to avoid device buffer overflows. This rate is specified with a fraction N/D,
279 -set by \fBii_rate_n\fR and \fBii_rate_d\fR respectively. Any integer numbers
280 -can be used, or the following predefined constants:
281 -.sp
282 -.ne 2
283 -.na
284 -\fB\fBIEC61883_RATE_N_DV_NTSC IEC61883_RATE_D_DV_NTSC\fR\fR
285 -.ad
286 -.sp .6
287 -.RS 4n
288 -Data rate expected by \fBDV-NTSC\fR devices.
289 -.RE
290 -
291 -.sp
292 -.ne 2
293 -.na
294 -\fB\fBIEC61883_RATE_N_DV_PAL IEC61883_RATE_D_DV_PAL\fR\fR
295 -.ad
296 -.sp .6
297 -.RS 4n
298 -Data rate expected by \fBDV-PAL\fR devices.
299 -.RE
300 -
318 +to avoid device buffer overflows.
319 +This rate is specified with a fraction N/D,
320 +set by
321 +.Fa ii_rate_n
322 +and
323 +.Fa ii_rate_d
324 +respectively.
325 +Any integer numbers can be used, or the following predefined constants:
326 +.Pp
327 +.Bl -tag -width "IEC61883_RATE_N_DV_NTSC" -compact
328 +.It Dv IEC61883_RATE_N_DV_NTSC
329 +.It Dv IEC61883_RATE_D_DV_NTSC
330 +Data rate expected by
331 +.Sy DV-NTSC
332 +devices.
333 +.Pp
334 +.It Dv IEC61883_RATE_N_DV_PAL
335 +.It Dv IEC61883_RATE_D_DV_PAL
336 +Data rate expected by
337 +.Sy DV-PAL
338 +devices.
339 +.El
340 +.Pp
301 341 During data transmission, a timestamp based on the current value of the cycle
302 -timer is usually required. \fBii_ts_mode\fR defines timestamp mode to be used:
303 -.sp
304 -.ne 2
305 -.na
306 -\fB\fBIEC61883_TS_SYT\fR\fR
307 -.ad
308 -.sp .6
309 -.RS 4n
342 +timer is usually required.
343 +.Fa ii_ts_mode
344 +defines timestamp mode to be used:
345 +.Bl -tag -width IEC61883_TS_NONE
346 +.It Dv IEC61883_TS_SYT
310 347 Driver puts a timestamp in the SYT field of the first CIP header of each frame.
311 -.RE
312 -
313 -.sp
314 -.ne 2
315 -.na
316 -\fB\fBIEC61883_TS_NONE\fR\fR
317 -.ad
318 -.sp .6
319 -.RS 4n
348 +.It Dv IEC61883_TS_NONE
320 349 No timestamps.
321 -.RE
322 -
323 -\fBii_dbs, ii_fn, ii_rate_n, ii_rate_d\fR and \fBii_ts_mode\fR are only
324 -required for transmission. In other case these should be set to 0.
325 -.sp
326 -\fBii_flags\fR should be set to 0.
327 -.sp
328 -If command succeeds, \fBii_handle\fR contains a handle that should be used with
329 -other isochronous commands. \fBii_frame_rcnt\fR contains the number of
330 -allocated frames (can be less than \fBii_frame_cnt\fR). \fBii_mmap_off\fR
331 -contains an offset to be used in \fBmmap\fR(2), for example, to map an entire
332 -data receive buffer:
333 -.sp
334 -.in +2
335 -.nf
350 +.El
351 +.Pp
352 +.Fa ii_dbs ,
353 +.Fa ii_fn ,
354 +.Fa ii_rate_n ,
355 +.Fa ii_rate_d
356 +and
357 +.Fa ii_ts_mode
358 +are only required for transmission.
359 +In other case these should be set to 0.
360 +.Pp
361 +.Fa ii_flags
362 +should be set to 0.
363 +.Pp
364 +If command succeeds,
365 +.Fa ii_handle
366 +contains a handle that should be used with other isochronous commands.
367 +.Fa ii_frame_rcnt
368 +contains the number of allocated frames (can be less than
369 +.Fa ii_frame_cnt ) .
370 +.Fa ii_mmap_off
371 +contains an offset to be used in
372 +.Xr mmap 2 ,
373 +for example, to map an entire data receive buffer:
374 +.Bd -literal -offset 2n
336 375 pa = mmap(NULL, init.ii_pkt_size *
337 376 init.ii_frame_size * init.ii_frame_rcnt,
338 377 PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);
339 -.fi
340 -.in -2
341 -.sp
342 -
343 -\fBii_rchannel\fR contains channel number.
344 -.sp
345 -In case of command success, \fBii_error\fR is set to 0; otherwise one of the
346 -following values can be returned:
347 -.sp
348 -.ne 2
349 -.na
350 -\fB\fBIEC61883_ERR_NOMEM\fR\fR
351 -.ad
352 -.sp .6
353 -.RS 4n
378 +.Ed
379 +.Pp
380 +.Fa ii_rchannel
381 +contains channel number.
382 +.Pp
383 +In case of command success,
384 +.Fa ii_error
385 +is set to 0; otherwise one of the following values can be returned:
386 +.Bl -tag -width IEC61883_ERR_NOCHANNEL
387 +.It Dv IEC61883_ERR_NOMEM
354 388 Not enough memory for the data buffer.
355 -.RE
356 -
357 -.sp
358 -.ne 2
359 -.na
360 -\fB\fBIEC61883_ERR_NOCHANNEL\fR\fR
361 -.ad
362 -.sp .6
363 -.RS 4n
389 +.It Dv IEC61883_ERR_NOCHANNEL
364 390 Cannot allocate isochronous channel.
365 -.RE
366 -
367 -.sp
368 -.ne 2
369 -.na
370 -\fB\fBIEC61883_ERR_PKT_SIZE\fR\fR
371 -.ad
372 -.sp .6
373 -.RS 4n
391 +.It Dv IEC61883_ERR_PKT_SIZE
374 392 Packet size is not allowed at this bus speed.
375 -.RE
376 -
377 -.sp
378 -.ne 2
379 -.na
380 -\fB\fBIEC61883_ERR_VERSION\fR\fR
381 -.ad
382 -.sp .6
383 -.RS 4n
393 +.It Dv IEC61883_ERR_VERSION
384 394 Interface version is not supported.
385 -.RE
386 -
387 -.sp
388 -.ne 2
389 -.na
390 -\fB\fBIEC61883_ERR_INVAL\fR\fR
391 -.ad
392 -.sp .6
393 -.RS 4n
395 +.It Dv IEC61883_ERR_INVAL
394 396 One or more the parameters are invalid
395 -.RE
396 -
397 -.sp
398 -.ne 2
399 -.na
400 -\fB\fBIEC61883_ERR_OTHER\fR\fR
401 -.ad
402 -.sp .6
403 -.RS 4n
397 +.It Dv IEC61883_ERR_OTHER
404 398 Unspecified error type.
405 -.RE
406 -
407 -.RE
408 -
409 -.sp
410 -.ne 2
411 -.na
412 -\fB\fBIEC61883_ISOCH_FINI\fR\fR
413 -.ad
414 -.sp .6
415 -.RS 4n
416 -Argument is a handle returned by \fBIEC61883_ISOCH_INIT\fR. This command frees
417 -any resources associated with this handle. There must be no active transfers
399 +.El
400 +.It Dv IEC61883_ISOCH_FINI
401 +.Pp
402 +Argument is a handle returned by
403 +.Dv IEC61883_ISOCH_INIT .
404 +This command frees any resources associated with this handle.
405 +There must be no active transfers
418 406 and the data buffer must be unmapped; otherwise the command fails.
419 -.RE
420 -
421 -.sp
422 -.ne 2
423 -.na
424 -\fB\fBIEC61883_START\fR\fR
425 -.ad
426 -.sp .6
427 -.RS 4n
428 -This command starts an isochronous transfer. The argument is a handle returned
429 -by \fBIEC61883_ISOCH_INIT\fR.
430 -.RE
431 -
432 -.sp
433 -.ne 2
434 -.na
435 -\fB\fBIEC61883_STOP\fR\fR
436 -.ad
437 -.sp .6
438 -.RS 4n
439 -This command stops an isochronous transfer. The argument is a handle returned
440 -by \fBIEC61883_ISOCH_INIT\fR.
441 -.RE
442 -
443 -.sp
444 -.ne 2
445 -.na
446 -\fB\fBIEC61883_RECV\fR\fR
447 -.ad
448 -.sp .6
449 -.RS 4n
450 -This command is used to receive full frames and return empty frames to the
451 -driver. The argument is a pointer to the structure:
452 -.sp
453 -.in +2
454 -.nf
407 +.It Dv IEC61883_START
408 +.Pp
409 +This command starts an isochronous transfer.
410 +The argument is a handle returned
411 +by
412 +.Dv IEC61883_ISOCH_INIT .
413 +.It Dv IEC61883_STOP
414 +.Pp
415 +This command stops an isochronous transfer.
416 +The argument is a handle returned by
417 +.Dv IEC61883_ISOCH_INIT .
418 +.It Dv IEC61883_RECV
419 +.Pp
420 +This command is used to receive full frames and return empty frames to the driver.
421 +The argument is a pointer to the structure:
422 +.Bd -literal -offset 2n
455 423 typedef struct iec61883_recv {
456 - int rx_handle; /* isoch handle */
457 - int rx_flags; /* flags */
458 -iec61883_xfer_t rx_xfer; /* xfer params */
424 + int rx_handle; /* isoch handle */
425 + int rx_flags; /* flags */
426 + iec61883_xfer_t rx_xfer; /* xfer params */
459 427 } iec61883_recv_t;
460 428
461 429 typedef struct iec61883_xfer {
462 430 int xf_empty_idx; /* first empty frame */
463 - int xf_empty_cnt; /* empty frame count */
431 + int xf_empty_cnt; /* empty frame count */
464 432 int xf_full_idx; /* first full frame */
465 433 int xf_full_cnt; /* full frame count */
466 434 int xf_error; /* error */
467 435 } iec61883_xfer_t;
468 -.fi
469 -.in -2
470 -.sp
471 -
472 -\fBrx_flags\fR should be set to 0.
473 -.sp
474 -An application sets \fBxf_empty_idx\fR and \fBxf_empty_cnt\fR to indicate
475 -frames it no longer needs. E.g. if a buffer consists of 6 frames,
476 -\fBxf_empty_idx\fR is 4, \fBxf_empty_cnt\fR is 3 - means that frames 4, 5 and 0
477 -can now be reused by the driver. If there are no empty frames, for example, the
478 -first time this command is called, \fBxf_empty_cnt\fR should be set to 0.
479 -.sp
480 -When the command returns, \fBxf_full_idx\fR and \fBxf_full_cnt\fR specifies the
481 -frames that are full. \fBxf_error\fR is always 0.
482 -.sp
436 +.Ed
437 +.Pp
438 +.Fa rx_flags
439 +should be set to 0.
440 +.Pp
441 +An application sets
442 +.Fa xf_empty_idx
443 +and
444 +.Fa xf_empty_cnt
445 +to indicate frames it no longer needs.
446 +E. g. if a buffer consists of 6 frames,
447 +.Fa xf_empty_idx
448 +is 4,
449 +.Fa xf_empty_cnt
450 +is 3 - means that frames 4, 5 and 0 can now be reused by the driver.
451 +If there are no empty frames, for example, the
452 +first time this command is called,
453 +.Fa xf_empty_cnt
454 +should be set to 0.
455 +.Pp
456 +When the command returns,
457 +.Fa xf_full_idx
458 +and
459 +.Fa xf_full_cnt
460 +specifies the frames that are full.
461 +.Fa xf_error
462 +is always 0.
463 +.Pp
483 464 In general, AV frame boundaries are not aligned with the frame buffer
484 465 boundaries, because the first received packet might not be the first packet of
485 466 an AV frame, and, in contrast with the read/write method, the driver does not
486 467 remove empty CIP packets.
487 -.sp
468 +.Pp
488 469 Applications should detect empty packets by comparing adjacent packets'
489 470 continuity counters (DBC field of the CIP header).
490 -.RE
491 -
492 -.sp
493 -.ne 2
494 -.na
495 -\fB\fBIEC61883_XMIT\fR\fR
496 -.ad
497 -.sp .6
498 -.RS 4n
471 +.It Dv IEC61883_XMIT
472 +.Pp
499 473 This command is used to transmit full frames and get more empty frames from the
500 -driver. The argument is a pointer to the structure:
501 -.sp
502 -.in +2
503 -.nf
474 +driver.
475 +The argument is a pointer to the structure:
476 +.Bd -literal -offset 2n
504 477 typedef struct iec61883_xmit {
505 478 int tx_handle; /* isoch handle */
506 479 int tx_flags; /* flags */
507 480 iec61883_xfer_t tx_xfer; /* xfer params */
508 481 int tx_miss_cnt; /* missed cycles */
509 482 } iec61883_xmit_t;
510 -.fi
511 -.in -2
512 -.sp
513 -
514 -\fBtx_flags\fR should be set to zero.
515 -.sp
516 -The application sets \fBxf_full_idx\fR and \fBxf_full_cnt\fR to specify frames
517 -it wishes to transmit. If there are no frames to transmit (e.g. the first time
518 -this command is called), \fBxf_full_cnt\fR should be set to 0.
519 -.sp
520 -When the command returns, \fBxf_empty_idx\fR and \fBxf_empty_cnt\fR specifies
521 -empty frames which can be to transmit more data. \fBxf_error\fR is always 0.
522 -.sp
523 -\fBtx_miss_cnt\fR contains the number of isochronous cycles missed since last
524 -transfer due to data buffer under run. This can happen when an application does
525 -not supply data fast enough.
526 -.sp
483 +.Ed
484 +.Pp
485 +.Fa tx_flags
486 +should be set to zero.
487 +.Pp
488 +The application sets
489 +.Fa xf_full_idx
490 +and
491 +.Fa xf_full_cnt
492 +to specify frames it wishes to transmit.
493 +If there are no frames to transmit (e. g. the first time this command is called),
494 +.Fa xf_full_cnt
495 +should be set to 0.
496 +.Pp
497 +When the command returns,
498 +.Fa xf_empty_idx
499 +and
500 +.Fa xf_empty_cnt
501 +specifies empty frames which can be to transmit more data.
502 +.Fa xf_error
503 +is always 0.
504 +.Pp
505 +.Fa tx_miss_cnt
506 +contains the number of isochronous cycles missed since last
507 +transfer due to data buffer under run.
508 +This can happen when an application does not supply data fast enough.
527 509 For the purposes of time stamping, the driver considers the first packet in a
528 510 frame buffer to be the first packet of an AV frame.
529 -.RE
530 -
531 -.sp
532 -.ne 2
533 -.na
534 -\fB\fBIEC61883_PLUG_INIT\fR\fR
535 -.ad
536 -.sp .6
537 -.RS 4n
538 -This command returns a handle for the specified plug. The argument is a pointer
511 +.It Dv IEC61883_PLUG_INIT
512 +.Pp
513 +This command returns a handle for the specified plug.
514 +The argument is a pointer
539 515 to the structure:
540 -.sp
541 -.in +2
542 -.nf
516 +.Bd -literal -offset 2n
543 517 typedef struct iec61883_plug_init {
544 518 int pi_ver; /* interface version */
545 519 int pi_loc; /* plug location */
546 520 int pi_type; /* plug type */
547 521 int pi_num; /* plug number */
548 522 int pi_flags; /* flags */
549 523 int pi_handle; /* plug handle */
550 524 int pi_rnum; /* plug number */
551 525 } iec61883_plug_init_t;
552 -.fi
553 -.in -2
554 -.sp
555 -
556 -\fBpi_ver\fR should be set to \fBIEC61883_V1_0\fR.
557 -.sp
558 -\fBpi_loc\fR specifies plug location:
559 -.sp
560 -.ne 2
561 -.na
562 -\fB\fBIEC61883_LOC_LOCAL\fR\fR
563 -.ad
564 -.sp .6
565 -.RS 4n
566 -On the local unit (local plug). A plug control register (PCR) is allocated.
526 +.Ed
527 +.Pp
528 +.Fa pi_ver
529 +should be set to
530 +.Dv IEC61883_V1_0 .
531 +.Pp
532 +.Fa pi_loc
533 +specifies plug location:
534 +.Bl -tag -width IEC61883_LOC_REMOTE
535 +.It Dv IEC61883_LOC_LOCAL
536 +On the local unit (local plug).
537 +A plug control register (PCR) is allocated.
567 538 Command fails if the plug already exists
568 -.RE
569 -
570 -.sp
571 -.ne 2
572 -.na
573 -\fB\fBIEC61883_LOC_REMOTE\fR\fR
574 -.ad
575 -.sp .6
576 -.RS 4n
577 -On the remote unit (remote plug). The plug should exist on the remote unit,
539 +.It Dv IEC61883_LOC_REMOTE
540 +On the remote unit (remote plug).
541 +The plug should exist on the remote unit,
578 542 otherwise the command fails.
579 -.RE
580 -
581 -\fBpi_type\fR specifies isochronous plug type:
582 -.sp
583 -.ne 2
584 -.na
585 -\fB\fBIEC61883_PLUG_IN IEC61883_PLUG_OUT\fR\fR
586 -.ad
587 -.sp .6
588 -.RS 4n
543 +.El
544 +.Pp
545 +.Fa pi_type
546 +specifies isochronous plug type:
547 +.Pp
548 +.Bl -tag -width " " -compact
549 +.It Dv IEC61883_PLUG_IN
550 +.It Dv IEC61883_PLUG_OUT
551 +.Pp
589 552 Input or output plugs.
590 -.RE
591 -
592 -.sp
593 -.ne 2
594 -.na
595 -\fB\fBIEC61883_PLUG_MASTER_IN IEC61883_PLUG_MASTER_OUT\fR\fR
596 -.ad
597 -.sp .6
598 -.RS 4n
599 -Master input or master output plug. These plugs always exist on the local unit.
600 -.RE
601 -
602 -\fBpi_num\fR specifies plug number. This should be 0 for master plugs, and from
603 -0 to 31 for input/output plugs. Alternatively, a special value
604 -\fBIEC61883_PLUG_ANY\fR can be used to let the driver choose a free plug
605 -number, create the plug and return the number in \fBpi_rnum\fR.
606 -.sp
607 -\fBpi_flags\fR should be set to 0.
608 -.sp
609 -If the command succeeds, \fBpi_handle\fR contains a handle that should be used
610 -with other plug commands.
611 -.RE
612 -
613 -.sp
614 -.ne 2
615 -.na
616 -\fB\fBIEC61883_PLUG_FINI\fR\fR
617 -.ad
618 -.sp .6
619 -.RS 4n
620 -Argument is a handle returned by \fBIEC61883_PLUG_INIT\fR. This command frees
621 -any resources associated with this handle, including the PCR.
622 -.RE
623 -
624 -.sp
625 -.ne 2
626 -.na
627 -\fB\fBIEC61883_PLUG_REG_READ\fR\fR
628 -.ad
629 -.sp .6
630 -.RS 4n
631 -Read plug register value. The argument is a pointer to the structure:
632 -.sp
633 -.in +2
634 -.nf
553 +.Pp
554 +.It Dv IEC61883_PLUG_MASTER_IN
555 +.It Dv IEC61883_PLUG_MASTER_OUT
556 +.Pp
557 +Master input or master output plug.
558 +These plugs always exist on the local unit.
559 +.El
560 +.Pp
561 +.Fa pi_num
562 +specifies plug number.
563 +This should be 0 for master plugs, and from 0 to 31 for input/output plugs.
564 +Alternatively, a special value
565 +.Dv IEC61883_PLUG_ANY
566 +can be used to let the driver choose a free plug
567 +number, create the plug and return the number in
568 +.Fa pi_rnum .
569 +.Pp
570 +.Fa pi_flags
571 +should be set to 0.
572 +.Pp
573 +If the command succeeds,
574 +.Fa pi_handle
575 +contains a handle that should be used with other plug commands.
576 +.It Dv IEC61883_PLUG_FINI
577 +.Pp
578 +Argument is a handle returned by
579 +.Dv IEC61883_PLUG_INIT .
580 +This command frees any resources associated with this handle, including the PCR.
581 +.It Dv IEC61883_PLUG_REG_READ
582 +.Pp
583 +Read plug register value.
584 +The argument is a pointer to the structure:
585 +.Bd -literal -offset 2n
635 586 typedef struct iec61883_plug_reg_val {
636 587 int pr_handle; /* plug handle */
637 - uint32_t pr_val; /* register value */
588 + uint32_t pr_val; /* register value */
638 589 } iec61883_plug_reg_val_t;
639 -.fi
640 -.in -2
641 -.sp
642 -
643 -\fBpr_handle\fR is a handle returned by \fBIEC61883_PLUG_INIT\fR. Register
644 -value is returned in \fBpr_val\fR.
645 -.RE
646 -
647 -.sp
648 -.ne 2
649 -.na
650 -\fB\fBIEC61883_PLUG_REG_CAS\fR\fR
651 -.ad
652 -.sp .6
653 -.RS 4n
654 -Atomically compare and swap plug register value. The argument is a pointer to
655 -the structure:
656 -.sp
657 -.in +2
658 -.nf
590 +.Ed
591 +.Pp
592 +.Fa pr_handle
593 +is a handle returned by
594 +.Dv IEC61883_PLUG_INIT .
595 +Register
596 +value is returned in
597 +.Fa pr_val .
598 +.It Dv IEC61883_PLUG_REG_CAS
599 +.Pp
600 +Atomically compare and swap plug register value.
601 +The argument is a pointer to the structure:
602 +.Bd -literal -offset 2n
659 603 typedef struct iec61883_plug_reg_lock {
660 604 int pl_handle; /* plug handle */
661 605 uint32_t pl_arg; /* compare arg */
662 606 uint32_t pl_data; /* write value */
663 607 UINT32_t pl_old; /* original value */
664 608 } iec61883_plug_reg_lock_t;
665 -.fi
666 -.in -2
667 -.sp
668 -
669 -pr_handle is a handle returned by IEC61883_PLUG_INIT.
670 -.sp
671 -Original register value is compared with pl_arg and if they are equal, register
672 -value is replaced with pl_data. In any case, the original value is stored in
673 -pl_old.
674 -.RE
675 -
676 -.sp
677 -.LP
609 +.Ed
610 +.Pp
611 +.Fa pr_handle
612 +is a handle returned by IEC61883_PLUG_INIT.
613 +.Pp
614 +Original register value is compared with
615 +.Fa pl_arg
616 +and if they are equal, register value is replaced with
617 +.Fa pl_data .
618 +In any case, the original value is stored in
619 +.Fa pl_old .
620 +.El
621 +.Pp
678 622 The following commands only apply to asynchronous nodes:
679 -.sp
680 -.ne 2
681 -.na
682 -\fB\fBIEC61883_ARQ_GET_IBUF_SIZE\fR\fR
683 -.ad
684 -.sp .6
685 -.RS 4n
686 -This command returns current incoming ARQ buffer size. The argument is a
687 -pointer to \fBint\fR.
688 -.RE
689 -
690 -.sp
691 -.ne 2
692 -.na
693 -\fB\fBIEC61883_ARQ_SET_IBUF_SIZE\fR\fR
694 -.ad
695 -.sp .6
696 -.RS 4n
697 -This command changes incoming ARQ buffer size. The argument is the new buffer
623 +.Bl -tag -width " "
624 +.It Dv IEC61883_ARQ_GET_IBUF_SIZE
625 +.Pp
626 +This command returns current incoming ARQ buffer size.
627 +The argument is a
628 +pointer to
629 +.Vt int .
630 +.It Dv IEC61883_ARQ_SET_IBUF_SIZE
631 +.Pp
632 +This command changes incoming ARQ buffer size.
633 +The argument is the new buffer
698 634 size in bytes.
699 -.RE
700 -
701 -.SH FILES
702 -.sp
703 -.ne 2
704 -.na
705 -\fB\fB/dev/av/N/async\fR\fR
706 -.ad
707 -.RS 19n
635 +.El
636 +.Sh FILES
637 +.Bl -tag -width /dev/av/N/async
638 +.It Pa /dev/av/N/async
708 639 Device node for asynchronous data
709 -.RE
710 -
711 -.sp
712 -.ne 2
713 -.na
714 -\fB\fB/dev/av/N/isoch\fR\fR
715 -.ad
716 -.RS 19n
640 +.It Pa /dev/av/N/isoch
717 641 Device has been disconnected
718 -.RE
719 -
720 -.SH ERRORS
721 -.sp
722 -.ne 2
723 -.na
724 -\fB\fBEIO\fR\fR
725 -.ad
726 -.RS 10n
642 +.El
643 +.Sh ERRORS
644 +.Bl -tag -width EFAULT
645 +.It Er EIO
727 646 Bus operation failed.
728 -.sp
729 647 DMA failure.
730 -.RE
731 -
732 -.sp
733 -.ne 2
734 -.na
735 -\fB\fBEFAULT\fR\fR
736 -.ad
737 -.RS 10n
738 -\fBioctl\fR(2) argument points to an illegal address.
739 -.RE
740 -
741 -.sp
742 -.ne 2
743 -.na
744 -\fB\fBEINVAL\fR\fR
745 -.ad
746 -.RS 10n
648 +.It Er EFAULT
649 +.Xr ioctl 2
650 +argument points to an illegal address.
651 +.It Er EINVAL
747 652 Invalid argument or argument combination.
748 -.RE
749 -
750 -.sp
751 -.ne 2
752 -.na
753 -\fB\fBENODEV\fR\fR
754 -.ad
755 -.RS 10n
653 +.It Er ENODEV
756 654 Device has been disconnected.
757 -.RE
758 -
759 -.SH ATTRIBUTES
760 -.sp
761 -.LP
762 -See \fBattributes\fR(5) for descriptions of the following attributes:
763 -.sp
764 -
765 -.sp
766 -.TS
767 -box;
768 -c | c
769 -l | l .
770 -ATTRIBUTE TYPE ATTRIBUTE VALUE
771 -_
772 -Architecture All
773 -_
774 -Stability level Committed
775 -.TE
776 -
777 -.SH SEE ALSO
778 -.sp
779 -.LP
780 -\fBioctl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBread\fR(2),
781 -\fBwrite\fR(2), \fBattributes\fR(5), \fBav1394\fR(7D)
782 -.sp
783 -.LP
784 -\fIIEC 61883 Consumer audio/video equipment - Digital interface\fR
785 -.sp
786 -.LP
787 -\fIIEEE Std 1394-1995 Standard for a High Performance Serial Bus\fR
655 +.El
656 +.Sh ARCHITECTURE
657 +All
658 +.Sh INTERFACE STABILITY
659 +Committed
660 +.Sh SEE ALSO
661 +.Xr ioctl 2 ,
662 +.Xr mmap 2 ,
663 +.Xr open 2 ,
664 +.Xr poll 2 ,
665 +.Xr read 2 ,
666 +.Xr write 2 ,
667 +.Xr attributes 5 ,
668 +.Xr av1394 7D
669 +.Rs
670 +.%B IIEC 61883 Consumer audio/video equipment - Digital interface
671 +.Re
672 +.Rs
673 +.%B IEEE Std 1394-1995 Standard for a High Performance Serial Bus
674 +.Re
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX