Debian Codegraph @

src/iec61883.h

raw
1 /*
2 * libiec61883/iec61883.h - Linux IEEE 1394 streaming media library.
3 * Copyright (C) 2004 Kristian Hogsberg, Dan Dennedy, and Dan Maas.
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 */
19
20 #ifndef _IEC61883_H
21 #define _IEC61883_H
22
23 #include <libraw1394/raw1394.h>
24 #include <endian.h>
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 enum iec61883_datarate {
31 IEC61883_DATARATE_100 = 0,
32 IEC61883_DATARATE_200,
33 IEC61883_DATARATE_400
34 };
35
36 /*******************************************************************************
37 * Audio and Music Data Transport Protocol
38 **/
39
40 enum iec61883_amdtp_format {
41 IEC61883_AMDTP_FORMAT_RAW,
42 IEC61883_AMDTP_FORMAT_IEC958_PCM,
43 IEC61883_AMDTP_FORMAT_IEC958_AC3
44 };
45
46 enum iec61883_cip_mode {
47 IEC61883_MODE_BLOCKING_EMPTY,
48 IEC61883_MODE_BLOCKING_NODATA,
49 IEC61883_MODE_NON_BLOCKING,
50 };
51
52 enum iec61883_amdtp_sample_format {
53 IEC61883_AMDTP_INPUT_NA = -1,
54 IEC61883_AMDTP_INPUT_LE16 = 0,
55 IEC61883_AMDTP_INPUT_BE16,
56 IEC61883_AMDTP_INPUT_LE20,
57 IEC61883_AMDTP_INPUT_BE20,
58 IEC61883_AMDTP_INPUT_LE24,
59 IEC61883_AMDTP_INPUT_BE24
60 };
61
62 #define IEC61883_FDF_SFC_32KHZ 0x00
63 #define IEC61883_FDF_SFC_44K1HZ 0x01
64 #define IEC61883_FDF_SFC_48KHZ 0x02
65 #define IEC61883_FDF_SFC_88K2HZ 0x03
66 #define IEC61883_FDF_SFC_96KHZ 0x04
67 #define IEC61883_FDF_SFC_176K4HZ 0x05
68 #define IEC61883_FDF_SFC_192KHZ 0x06
69
70 typedef struct iec61883_amdtp* iec61883_amdtp_t;
71
72 /**
73 * iec61883_amdtp_recv_t - AMDTP receive callback function prototype
74 * @data: pointer to the buffer containing audio data
75 * @nsamples: the number of samples in the buffer
76 * @dimension: the number of audio channels
77 * @rate: sampling frequency
78 * @format: one of enum iec61883_amdtp_format
79 * @sample_format: one of enum iec61883_amdtp_sample_format
80 * @callback_data: the opaque pointer you supplied in the init function
81 *
82 * The buffer contains consumer-ready 16bit raw PCM if it is in that format.
83 * Otherwise, the data consists of quadlets containing only one sample with
84 * any necessary padding minus the label if pcm, otherwise, for IEC958
85 * audio data, the header remains intact.
86 *
87 * Returns:
88 * 0 for success or -1 for failure
89 */
90 typedef int
91 (*iec61883_amdtp_recv_t) (iec61883_amdtp_t amdtp, unsigned char *data, int nsamples,
92 unsigned int dbc, unsigned int dropped, void *callback_data);
93
94 typedef int
95 (*iec61883_amdtp_xmit_t) (iec61883_amdtp_t amdtp, unsigned char *data, int nevents,
96 unsigned int dbc, unsigned int dropped, void *callback_data);
97
98 /**
99 * iec61883_amdtp_xmit_init - setup transmission of AMDTP
100 * @handle: the libraw1394 handle to use for all operations
101 * @rate: one of enum iec61883_datarate
102 * @format: one of enum iec61883_amdtp_format to describe audio data format
103 * @sample_format: one of enum iec61883_amdtp_sample_format
104 * @mode: one of iec61883_cip_mode
105 * @dimension: the number of audio channels
106 * @get_data: a function pointer to your callback routine
107 * @callback_data: an opaque pointer to provide to your callback function
108 *
109 * AMDTP = Audio and Music Data Transport Protocol
110 *
111 * Returns:
112 * A pointer to an iec61883_amdtp object upon success or NULL on failure.
113 **/
114 iec61883_amdtp_t
115 iec61883_amdtp_xmit_init(raw1394handle_t handle,
116 int rate, int format, int sample_format, int mode, int dimension,
117 iec61883_amdtp_xmit_t get_data, void *callback_data);
118
119 /**
120 * iec61883_amdtp_recv_init - setup reception of AMDTP
121 * @handle: the libraw1394 handle to use for all operations
122 * @put_data: a function pointer to your callback routine
123 * @callback_data: an opaque pointer to provide to your callback function
124 *
125 * Returns:
126 * A pointer to an iec61883_amdtp object upon success or NULL on failure.
127 **/
128 iec61883_amdtp_t
129 iec61883_amdtp_recv_init(raw1394handle_t handle,
130 iec61883_amdtp_recv_t put_data, void *callback_data);
131
132 /**
133 * iec61883_amdtp_xmit_start - start transmission of AMDTP
134 * @amdtp: pointer to iec61883_amdtp object
135 * @channel: the isochronous channel number to use
136 **/
137 int
138 iec61883_amdtp_xmit_start(iec61883_amdtp_t amdtp, int channel);
139
140 /**
141 * iec61883_amdtp_xmit_stop - stop transmission of AMDTP
142 * @amdtp: pointer to iec61883_amdtp object
143 **/
144 void
145 iec61883_amdtp_xmit_stop(iec61883_amdtp_t amdtp);
146
147 /**
148 * iec61883_amdtp_recv_start - start reception of AMDTP
149 * @amdtp: pointer to iec61883_amdtp object
150 * @channel: the isochronous channel number to use
151 **/
152 int
153 iec61883_amdtp_recv_start(iec61883_amdtp_t amdtp, int channel);
154
155 /**
156 * iec61883_amdtp_recv_stop - stop reception of AMDTP
157 * @amdtp: pointer to iec61883_amdtp object
158 **/
159 void
160 iec61883_amdtp_recv_stop(iec61883_amdtp_t amdtp);
161
162 /**
163 * iec61883_amdtp_close - destroy an amdtp object
164 * @amdtp: pointer to iec61883_amdtp object
165 **/
166 void
167 iec61883_amdtp_close(iec61883_amdtp_t amdtp);
168
169 /**
170 * iec61883_amdtp_get_buffers - get the size of the buffer
171 * @amdtp: pointer to iec61883_amdtp object
172 **/
173 unsigned int
174 iec61883_amdtp_get_buffers(iec61883_amdtp_t amdtp);
175
176 /**
177 * iec61883_amdtp_set_buffers - set the size of the buffer
178 * @amdtp: pointer to iec61883_amdtp object
179 * @packets: the size of the buffer in packets
180 *
181 * This is an advanced option that can only be set after initialization and
182 * before reception or transmission.
183 **/
184 void
185 iec61883_amdtp_set_buffers(iec61883_amdtp_t amdtp, unsigned int packets);
186
187 /**
188 * iec61883_amdtp_get_prebuffers - get the size of the pre-transmission buffer
189 * @amdtp: pointer to iec61883_amdtp object
190 **/
191 unsigned int
192 iec61883_amdtp_get_prebuffers(iec61883_amdtp_t amdtp);
193
194 /**
195 * iec61883_amdtp_set_prebuffers - set the size of the pre-transmission buffer
196 * @amdtp: pointer to iec61883_amdtp object
197 * @packets: the size of the buffer in packets
198 *
199 * This is an advanced option that can only be set after initialization and
200 * before reception or transmission.
201 **/
202 void
203 iec61883_amdtp_set_prebuffers(iec61883_amdtp_t amdtp, unsigned int packets);
204
205 /**
206 * iec61883_amdtp_get_irq_interval - get the interrupt rate
207 * @amdtp: pointer to iec61883_amdtp object
208 **/
209 unsigned int
210 iec61883_amdtp_get_irq_interval(iec61883_amdtp_t amdtp);
211
212 /**
213 * iec61883_amdtp_set_irq_interval - set the interrupt rate
214 * @amdtp: pointer to iec61883_amdtp object
215 * @packets: the size of the interval in packets
216 *
217 * This is an advanced option that can only be set after initialization and
218 * before reception or transmission.
219 **/
220 void
221 iec61883_amdtp_set_irq_interval(iec61883_amdtp_t amdtp, unsigned int packets);
222
223 /**
224 * iec61883_amdtp_get_synch - get behavior on close
225 * @amdtp: pointer to iec61883_amdtp object
226 *
227 * If synch is not zero, then when stopping reception all packets in
228 * raw1394 buffers are flushed and invoking your callback function and when
229 * stopping transmission all packets in the raw1394 buffers are sent before
230 * the close function returns.
231 **/
232 int
233 iec61883_amdtp_get_synch(iec61883_amdtp_t amdtp);
234
235 /**
236 * iec61883_amdtp_set_synch - set behavior on close
237 * @amdtp: pointer to iec61883_amdtp object
238 * @synch: 1 if you want sync behaviour, 0 otherwise
239 *
240 * If synch is not zero, then when stopping reception all packets in
241 * raw1394 buffers are flushed and invoking your callback function and when
242 * stopping transmission all packets in the raw1394 buffers are sent before
243 * the close function returns.
244 **/
245 void
246 iec61883_amdtp_set_synch(iec61883_amdtp_t amdtp, int synch);
247
248 /**
249 * iec61883_amdtp_get_speed - get data rate for transmission
250 * @amdtp: pointer to iec61883_amdtp object
251 *
252 * Returns:
253 * one of enum raw1394_iso_speed (S100, S200, or S400)
254 **/
255 int
256 iec61883_amdtp_get_speed(iec61883_amdtp_t amdtp);
257
258 /**
259 * iec61883_amdtp_set_speed - set data rate for transmission
260 * @amdtp: pointer to iec61883_amdtp object
261 * @speed: one of enum raw1394_iso_speed (S100, S200, or S400)
262 **/
263 void
264 iec61883_amdtp_set_speed(iec61883_amdtp_t amdtp, int speed);
265
266 /**
267 * iec61883_amdtp_get_dropped - get the total number of dropped packets
268 * @amdtp: pointer to iec61883_amdtp object
269 *
270 * Returns:
271 * The total number of dropped packets since starting transmission or reception.
272 **/
273 unsigned int
274 iec61883_amdtp_get_dropped(iec61883_amdtp_t amdtp);
275
276 /**
277 * iec61883_amdtp_get_callback_data - get the callback data you supplied
278 * @amdtp: pointer to iec61883_amdtp object
279 *
280 * This function is useful in bus reset callback routines because only
281 * the libraw1394 handle is available, and libiec61883 uses the userdata
282 * field of the libraw1394 handle.
283 *
284 * Returns:
285 * An opaque pointer to whatever you supplied when you called init.
286 **/
287 void *
288 iec61883_amdtp_get_callback_data(iec61883_amdtp_t amdtp);
289
290 /**
291 * iec61883_amdtp_get_dimension - get the AMDTP dimension
292 * @amdtp: pointer to iec61883_amdtp object
293 *
294 * This function is useful in your callbacks.
295 *
296 * Returns:
297 * The numeric value of the current dimension.
298 **/
299 int
300 iec61883_amdtp_get_dimension(iec61883_amdtp_t amdtp);
301
302 /**
303 * iec61883_amdtp_get_rate - get the AMDTP sampling frequency
304 * @amdtp: pointer to iec61883_amdtp object
305 *
306 * This function is useful in your callbacks.
307 *
308 * Returns:
309 * The numeric value of the sampling frequency.
310 **/
311 int
312 iec61883_amdtp_get_rate(iec61883_amdtp_t amdtp);
313
314 /**
315 * iec61883_amdtp_get_format - get the AMDTP data format
316 * @amdtp: pointer to iec61883_amdtp object
317 *
318 * This function is useful in your callbacks.
319 *
320 * Returns:
321 * One of enum iec61883_amdtp_format.
322 **/
323 enum iec61883_amdtp_format
324 iec61883_amdtp_get_format(iec61883_amdtp_t amdtp);
325
326 /**
327 * iec61883_amdtp_get_sample_format - get the AMDTP sample format
328 * @amdtp: pointer to iec61883_amdtp object
329 *
330 * This function is useful in your callbacks.
331 *
332 * Returns:
333 * One of enum iec61883_amdtp_sample_format.
334 **/
335 enum iec61883_amdtp_sample_format
336 iec61883_amdtp_get_sample_format(iec61883_amdtp_t amdtp);
337
338
339
340 /*******************************************************************************
341 * DV Digital Video
342 **/
343
344 typedef struct iec61883_dv* iec61883_dv_t;
345
346 typedef int
347 (*iec61883_dv_recv_t)(unsigned char *data, int len, unsigned int dropped,
348 void *callback_data);
349
350 typedef int
351 (*iec61883_dv_xmit_t)(unsigned char *data, int n_dif_blocks,
352 unsigned int dropped, void *callback_data);
353
354 /**
355 * iec61883_dv_recv_init - setup reception of a DV stream
356 * @handle: the libraw1394 handle to use for all operations
357 * @put_data: a function pointer to your reception callback routine
358 * @callback_data: an opaque data pointer to provide to your callback function
359 *
360 * Returns:
361 * A pointer to an iec61883_dv object upon success or NULL on failure.
362 **/
363 iec61883_dv_t
364 iec61883_dv_recv_init(raw1394handle_t handle,
365 iec61883_dv_recv_t put_data,
366 void *callback_data);
367
368 /**
369 * iec61883_dv_xmit_init - setup transmission of a DV stream
370 * @handle: the libraw1394 handle to use for all operations
371 * @is_pal: set to non-zero if transmitting a PAL stream (applies to transmission only)
372 * @get_data: a function pointer to your transmission callback routine
373 * @callback_data: an opaque data pointer to provide to your callback function
374 *
375 * Returns:
376 * A pointer to an iec61883_dv object upon success or NULL on failure.
377 **/
378 iec61883_dv_t
379 iec61883_dv_xmit_init(raw1394handle_t handle, int is_pal,
380 iec61883_dv_xmit_t get_data,
381 void *callback_data);
382
383 /**
384 * iec61883_dv_recv_start - start receiving a DV stream
385 * @dv: pointer to iec61883_dv object
386 * @channel: the isochronous channel number
387 *
388 * Returns:
389 * 0 for success or -1 for failure
390 **/
391 int
392 iec61883_dv_recv_start(iec61883_dv_t dv, int channel);
393
394 /**
395 * iec61883_dv_xmit_start - start transmitting a DV stream
396 * @dv: pointer to iec61883_dv object
397 * @channel: the isochronous channel number
398 *
399 * Returns:
400 * 0 for success or -1 for failure
401 **/
402 int
403 iec61883_dv_xmit_start(iec61883_dv_t dv, int channel);
404
405 /**
406 * iec61883_dv_recv_stop - stop reception of a DV stream
407 * @dv: pointer to iec61883_dv ojbect
408 **/
409 void
410 iec61883_dv_recv_stop(iec61883_dv_t dv);
411
412 /**
413 * iec61883_dv_xmit_stop - stop transmission of a DV stream
414 * @dv: pointer to iec61883_dv object
415 **/
416 void
417 iec61883_dv_xmit_stop(iec61883_dv_t dv);
418
419 /**
420 * iec61883_dv_close - stop reception or transmission and destroy iec61883_dv object
421 * @dv: pointer to iec61883_dv object
422 **/
423 void
424 iec61883_dv_close(iec61883_dv_t dv);
425
426 /**
427 * iec61883_dv_get_buffers - get the size of the buffer
428 * @dv: pointer to iec61883_dv object
429 **/
430 unsigned int
431 iec61883_dv_get_buffers(iec61883_dv_t dv);
432
433 /**
434 * iec61883_dv_set_buffers - set the size of the buffer
435 * @dv: pointer to iec61883_dv object
436 * @packets: the size of the buffer in packets
437 *
438 * This is an advanced option that can only be set after initialization and
439 * before reception or transmission.
440 **/
441 void
442 iec61883_dv_set_buffers(iec61883_dv_t dv, unsigned int packets);
443
444 /**
445 * iec61883_dv_get_prebuffers - get the size of the pre-transmission buffer
446 * @dv: pointer to iec61883_dv object
447 **/
448 unsigned int
449 iec61883_dv_get_prebuffers(iec61883_dv_t dv);
450
451 /**
452 * iec61883_dv_set_prebuffers - set the size of the pre-transmission buffer
453 * @dv: pointer to iec61883_dv object
454 * @packets: the size of the buffer in packets
455 *
456 * This is an advanced option that can only be set after initialization and
457 * before reception or transmission.
458 **/
459 void
460 iec61883_dv_set_prebuffers(iec61883_dv_t dv, unsigned int packets);
461
462 /**
463 * iec61883_dv_get_irq_interval - get the interrupt rate
464 * @dv: pointer to iec61883_dv object
465 **/
466 unsigned int
467 iec61883_dv_get_irq_interval(iec61883_dv_t dv);
468
469 /**
470 * iec61883_dv_set_irq_interval - set the interrupt rate
471 * @dv: pointer to iec61883_dv object
472 * @packets: the size of the interval in packets
473 *
474 * This is an advanced option that can only be set after initialization and
475 * before reception or transmission.
476 **/
477 void
478 iec61883_dv_set_irq_interval(iec61883_dv_t dv, unsigned int packets);
479
480 /**
481 * iec61883_dv_get_synch - get behavior on close
482 * @dv: pointer to iec61883_dv object
483 *
484 * If synch is not zero, then when stopping reception all packets in
485 * raw1394 buffers are flushed and invoking your callback function and when
486 * stopping transmission all packets in the raw1394 buffers are sent before
487 * the close function returns.
488 **/
489 int
490 iec61883_dv_get_synch(iec61883_dv_t dv);
491
492 /**
493 * iec61883_dv_set_synch - set behavior on close
494 * @dv: pointer to iec61883_dv object
495 * @synch: 1 if you want sync behaviour, 0 otherwise
496 *
497 * If synch is not zero, then when stopping reception all packets in
498 * raw1394 buffers are flushed and invoking your callback function and when
499 * stopping transmission all packets in the raw1394 buffers are sent before
500 * the close function returns.
501 **/
502 void
503 iec61883_dv_set_synch(iec61883_dv_t dv, int synch);
504
505 /**
506 * iec61883_dv_get_speed - get data rate for transmission
507 * @dv: pointer to iec61883_dv object
508 *
509 * Returns:
510 * one of enum raw1394_iso_speed (S100, S200, or S400)
511 **/
512 int
513 iec61883_dv_get_speed(iec61883_dv_t dv);
514
515 /**
516 * iec61883_dv_set_speed - set data rate for transmission
517 * @dv: pointer to iec61883_dv object
518 * @speed: one of enum raw1394_iso_speed (S100, S200, or S400)
519 **/
520 void
521 iec61883_dv_set_speed(iec61883_dv_t dv, int speed);
522
523 /**
524 * iec61883_dv_get_dropped - get the total number of dropped packets
525 * @dv: pointer to iec61883_dv object
526 *
527 * Returns:
528 * The total number of dropped packets since starting transmission or reception.
529 **/
530 unsigned int
531 iec61883_dv_get_dropped(iec61883_dv_t dv);
532
533 /**
534 * iec61883_dv_get_callback_data - get the callback data you supplied
535 * @dv: pointer to iec61883_dv object
536 *
537 * This function is useful in bus reset callback routines because only
538 * the libraw1394 handle is available, and libiec61883 uses the userdata
539 * field of the libraw1394 handle.
540 *
541 * Returns:
542 * An opaque pointer to whatever you supplied when you called init.
543 **/
544 void *
545 iec61883_dv_get_callback_data(iec61883_dv_t dv);
546
547
548 /*******************************************************************************
549 * The DV frame interface
550 **/
551
552 typedef struct iec61883_dv_fb* iec61883_dv_fb_t;
553
554 typedef int
555 (*iec61883_dv_fb_recv_t)(unsigned char *data, int len, int complete,
556 void *callback_data);
557
558 /**
559 * iec61883_dv_fb_init - setup reception of DV frames
560 * @handle: raw1394 handle.
561 * @put_data: your callback function.
562 * @callback_data: an opaque pointer you can send to your callback.
563 *
564 * This provides a frame-oriented instead of stream-oriented interface as
565 * compared to iec61883_dv_init(). This means that starts at the beginning of a
566 * frame, and all data is frame-aligned. Your callback function
567 * will receive a complete DV frame even if packets are dropped.
568 * The callback parameter @complete indicates if a full frame is received.
569 *
570 * Returns:
571 * A pointer to an iec61883_dv_fb object upon success or NULL on failure.
572 **/
573 iec61883_dv_fb_t
574 iec61883_dv_fb_init (raw1394handle_t handle,
575 iec61883_dv_fb_recv_t put_data,
576 void *callback_data);
577
578 /**
579 * iec61883_dv_fb_get_dv - get the parent iec61883_dv object
580 * @dvfb: pointer to iec61883_dv_fb object
581 *
582 * Returns:
583 * A pointer to an iec61883_dv object upon success or NULL on failure.
584 **/
585
586 iec61883_dv_t
587 iec61883_dv_fb_get_dv(iec61883_dv_fb_t dvfb);
588
589 /**
590 * iec61883_dv_fb_start - start receiving DV frames
591 * @dvfb: pointer to iec61883_dv_fb object
592 * @channel: the isochronous channel number
593 *
594 * Returns:
595 * 0 for success or -1 for failure
596 **/
597 int
598 iec61883_dv_fb_start(iec61883_dv_fb_t dvfb, int channel);
599
600 /**
601 * iec61883_dv_fb_stop - stop receiving DV frames
602 * @dvfb: pointer to iec61883_dv_fb object
603 **/
604 void
605 iec61883_dv_fb_stop(iec61883_dv_fb_t dvfb);
606
607 /**
608 * iec61883_dv_fb_close - stop receiving DV frames and destroy iec61883_dv_fb object
609 * @dvfb: pointer to iec61883_dv_fb object
610 **/
611 void
612 iec61883_dv_fb_close(iec61883_dv_fb_t dvfb);
613
614 /**
615 * iec61883_dv_fb_get_incomplete - get the total number of incomplete frames
616 * @dvfb: point to the iec61883_dv_fb object
617 *
618 * Returns:
619 * The total number of incomplete frames due to dropped packets since starting
620 * reception.
621 **/
622 unsigned int
623 iec61883_dv_fb_get_incomplete(iec61883_dv_fb_t dvfb);
624
625 /**
626 * iec61883_dv_fb_get_callback_data - get the callback data you supplied
627 * @dvfb: pointer to iec61883_dv_fb object
628 *
629 * This function is useful in bus reset callback routines because only
630 * the libraw1394 handle is available, and libiec61883 uses the userdata
631 * field of the libraw1394 handle.
632 *
633 * Returns:
634 * An opaque pointer to whatever you supplied when you called init.
635 **/
636 void *
637 iec61883_dv_fb_get_callback_data(iec61883_dv_fb_t dvfb);
638
639
640 /*******************************************************************************
641 * MPEG-2 Transport Stream
642 **/
643
644 /* MPEG2 Time Shift Flag - not currently used anywhere */
645 #define IEC61883_FDF_MPEG2_TSF 0x01
646
647 /* size of a MPEG-2 Transport Stream packet */
648 #define IEC61883_MPEG2_TSP_SIZE 188
649
650 typedef struct iec61883_mpeg2* iec61883_mpeg2_t;
651
652 typedef int
653 (*iec61883_mpeg2_recv_t)(unsigned char *data, int len, unsigned int dropped,
654 void *callback_data);
655
656 typedef int
657 (*iec61883_mpeg2_xmit_t)(unsigned char *data, int n_packets,
658 unsigned int dropped, void *callback_data);
659
660 /**
661 * iec61883_mpeg2_recv_init - setup reception of MPEG2-TS
662 * @handle: the libraw1394 handle to use for all operations
663 * @put_data: a function pointer to your callback routine
664 * @callback_data: an opaque pointer to provide to your callback function
665 *
666 * Returns:
667 * A pointer to an iec61883_mpeg2 object upon success or NULL for failure.
668 **/
669 iec61883_mpeg2_t
670 iec61883_mpeg2_recv_init(raw1394handle_t handle,
671 iec61883_mpeg2_recv_t put_data,
672 void *callback_data);
673
674 /**
675 * iec61883_mpeg2_xmit_init - setup transmission of MPEG2-TS
676 * @handle: the libraw1394 handle to use for all operations
677 * @get_data: a function pointer to your callback routine
678 * @callback_data: an opaque pointer to provide to your callback function
679 *
680 * Returns:
681 * A pointer to an iec61883_mpeg2 object upon success or NULL for failure.
682 **/
683 iec61883_mpeg2_t
684 iec61883_mpeg2_xmit_init(raw1394handle_t handle,
685 iec61883_mpeg2_xmit_t get_data,
686 void *callback_data);
687
688 /**
689 * iec61883_mpeg2_recv_start - start receiving MPEG2-TS
690 * @mpeg2: pointer to iec61883_mpeg2 object
691 * @channel: isochronous channel number
692 *
693 * Returns:
694 * 0 for success or -1 for failure
695 **/
696 int
697 iec61883_mpeg2_recv_start(iec61883_mpeg2_t mpeg2, int channel);
698
699 /**
700 * iec61883_mpeg2_xmit_start - start transmitting MPEG2-TS
701 * @mpeg2: pointer to iec61883_mpeg2 object
702 * @pid: the program ID of the transport stream to select
703 * @channel: isochronous channel number
704 *
705 * Returns:
706 * 0 for success or -1 for failure
707 **/
708 int
709 iec61883_mpeg2_xmit_start(iec61883_mpeg2_t mpeg2, int pid, int channel);
710
711 /**
712 * iec61883_mpeg2_recv_stop - stop receiving MPEG2-TS
713 * @mpeg2: pointer to the iec61883_mpeg2 object
714 **/
715 void
716 iec61883_mpeg2_recv_stop(iec61883_mpeg2_t mpeg2);
717
718 /**
719 * iec61883_mpeg2_xmit_stop - stop transmitting MPEG2-TS
720 * @mpeg2: pointer to the iec61883_mpeg2 object
721 **/
722 void
723 iec61883_mpeg2_xmit_stop(iec61883_mpeg2_t mpeg2);
724
725 /**
726 * iec61883_mpeg2_close - stop receiving or transmitting and destroy iec61883_mpeg2 object
727 * @mpeg2: pointer to iec61883_mpeg2 object
728 **/
729 void
730 iec61883_mpeg2_close(iec61883_mpeg2_t mpeg2);
731
732 /**
733 * iec61883_mpeg2_get_buffers - get the size of the raw1394 buffer
734 * @mpeg2: pointer to iec61883_mpeg2 object
735 **/
736 unsigned int
737 iec61883_mpeg2_get_buffers(iec61883_mpeg2_t mpeg2);
738
739 /**
740 * iec61883_mpeg2_set_buffers - set the size of the raw1394 buffer
741 * @mpeg2: pointer to iec61883_mpeg2 object
742 * @packets: the size of the buffer in packets
743 *
744 * This is an advanced option that can only be set after initialization and
745 * before reception or transmission.
746 **/
747 void
748 iec61883_mpeg2_set_buffers(iec61883_mpeg2_t mpeg2, unsigned int packets);
749
750 /**
751 * iec61883_mpeg2_get_prebuffers - get the size of the pre-transmission buffer
752 * @mpeg2: pointer to iec61883_mpeg2 object
753 **/
754 unsigned int
755 iec61883_mpeg2_get_prebuffers(iec61883_mpeg2_t mpeg2);
756
757 /**
758 * iec61883_mpeg2_set_prebuffers - set the size of the pre-transmission buffer
759 * @mpeg2: pointer to iec61883_mpeg2 object
760 * @packets: the size of the buffer in packets
761 *
762 * This is an advanced option that can only be set after initialization and
763 * before reception or transmission.
764 **/
765 void
766 iec61883_mpeg2_set_prebuffers(iec61883_mpeg2_t mpeg2, unsigned int packets);
767
768 /**
769 * iec61883_mpeg2_get_irq_interval - get the interrupt rate
770 * @mpeg2: pointer to iec61883_mpeg2 object
771 **/
772 unsigned int
773 iec61883_mpeg2_get_irq_interval(iec61883_mpeg2_t mpeg2);
774
775 /**
776 * iec61883_mpeg2_set_irq_interval - set the interrupt rate
777 * @mpeg2: pointer to iec61883_mpeg2 object
778 * @packets: the size of the interval in packets
779 *
780 * This is an advanced option that can only be set after initialization and
781 * before reception or transmission.
782 **/
783 void
784 iec61883_mpeg2_set_irq_interval(iec61883_mpeg2_t mpeg2, unsigned int packets);
785
786 /**
787 * iec61883_mpeg2_get_synch - get behavior on close
788 * @mpeg2: pointer to iec61883_mpeg2 object
789 *
790 * If synch is not zero, then when stopping reception all packets in
791 * raw1394 buffers are flushed and invoking your callback function and when
792 * stopping transmission all packets in the raw1394 buffers are sent before
793 * the close function returns.
794 **/
795 int
796 iec61883_mpeg2_get_synch(iec61883_mpeg2_t mpeg2);
797
798 /**
799 * iec61883_mpeg2_set_synch - set behavior on close
800 * @mpeg2: pointer to iec61883_mpeg2 object
801 * @synch: 1 if you want sync behaviour, 0 otherwise
802 *
803 * If synch is not zero, then when stopping reception all packets in
804 * raw1394 buffers are flushed and invoking your callback function and when
805 * stopping transmission all packets in the raw1394 buffers are sent before
806 * the close function returns.
807 **/
808 void
809 iec61883_mpeg2_set_synch(iec61883_mpeg2_t mpeg2, int synch);
810
811 /**
812 * iec61883_mpeg2_get_speed - get data rate for transmission
813 * @mpeg2: pointer to iec61883_mpeg2 object
814 *
815 * Returns:
816 * one of enum raw1394_iso_speed (S100, S200, or S400)
817 **/
818 int
819 iec61883_mpeg2_get_speed(iec61883_mpeg2_t mpeg2);
820
821 /**
822 * iec61883_mpeg2_set_speed - set data rate for transmission
823 * @mpeg2: pointer to iec61883_mepg2 object
824 * @speed: one of enum raw1394_iso_speed (S100, S200, or S400)
825 **/
826 void
827 iec61883_mpeg2_set_speed(iec61883_mpeg2_t mpeg2, int speed);
828
829 /**
830 * iec61883_mpeg2_get_dropped - get the total number of dropped packets
831 * @mpeg2: pointer to iec61883_mpeg2 object
832 *
833 * Returns:
834 * The total number of dropped packets since starting transmission or reception.
835 **/
836 unsigned int
837 iec61883_mpeg2_get_dropped(iec61883_mpeg2_t mpeg2);
838
839 /**
840 * iec61883_mpeg2_get_callback_data - get the callback data you supplied
841 * @mpeg2: pointer to iec61883_mpeg2 object
842 *
843 * This function is useful in bus reset callback routines because only
844 * the libraw1394 handle is available, and libiec61883 uses the userdata
845 * field of the libraw1394 handle.
846 *
847 * Returns:
848 * An opaque pointer to whatever you supplied when you called init.
849 **/
850 void *
851 iec61883_mpeg2_get_callback_data(iec61883_mpeg2_t mpeg2);
852
853
854 /*******************************************************************************
855 * Connection Management Procedures
856 **/
857
858 enum iec61883_pcr_overhead_id {
859 IEC61883_OVERHEAD_512 = 0,
860 IEC61883_OVERHEAD_32,
861 IEC61883_OVERHEAD_64,
862 IEC61883_OVERHEAD_96,
863 IEC61883_OVERHEAD_128,
864 IEC61883_OVERHEAD_160,
865 IEC61883_OVERHEAD_192,
866 IEC61883_OVERHEAD_224,
867 IEC61883_OVERHEAD_256,
868 IEC61883_OVERHEAD_288,
869 IEC61883_OVERHEAD_320,
870 IEC61883_OVERHEAD_352,
871 IEC61883_OVERHEAD_384,
872 IEC61883_OVERHEAD_416,
873 IEC61883_OVERHEAD_448,
874 IEC61883_OVERHEAD_480
875 };
876
877 /**
878 * iec61883_cmp_calc_bandwidth - calculate bandwidth allocation units
879 * @handle: a libraw1394 handle
880 * @output: the node id of the transmitter
881 * @plug: the index of the output plug
882 * @speed: if >= 0 then override the data rate factor
883 *
884 * Uses parameters of the output plug control register of the transmitter to
885 * calculate what its bandwidth requirements are. Parameters inlude payload,
886 * overhead_id, and data rate (optionally @speed).
887 *
888 * Returns:
889 * bandwidth allocation units or -1 on failure
890 **/
891 int
892 iec61883_cmp_calc_bandwidth (raw1394handle_t handle, nodeid_t output, int plug,
893 int speed);
894
895 /**
896 * iec61883_cmp_connect - establish or overlay connection automatically
897 * @handle: a libraw1394 handle
898 * @output: node id of the transmitter
899 * @oplug: the output plug to use. If -1, find the first online plug, and
900 * upon return, contains the plug number used.
901 * @input: node id of the receiver
902 * @iplug: the input plug to use. If -1, find the first online plug, and
903 * upon return, contains the plug number used.
904 * @bandwidth: an input/output parameter. As an input this is a boolean that
905 * indicates whether to perform bandwidth allocation. Supply 0 to skip bandwidth
906 * allocation; any other value permits it. Upon return, actual bandwidth allocation
907 * units allocated are returned, which you supply to the disconnect routine.
908 *
909 * This is a high level function that attempts to be as smart as possible, but
910 * it gives point-to-point connections higher priority over broadcast connections.
911 * It can automatically handle situations where either @input and/or @output does
912 * not implement plug control registers. However, if one node implements plug
913 * registers it assumes the other node has some sort of manual channel selection
914 * (i.e., through software or a control panel).
915 *
916 * Returns:
917 * It returns the isochronous channel number selected or -1 if the function has
918 * failed for any reason.
919 **/
920 int
921 iec61883_cmp_connect (raw1394handle_t handle, nodeid_t output, int *oplug,
922 nodeid_t input, int *iplug, int *bandwidth);
923
924 /**
925 * iec61883_cmp_reconnect - reestablish or overlay connection after a bus reset
926 * @handle: a libraw1394 handle
927 * @output: node id of the transmitter
928 * @oplug: the output plug to use. If -1, find the first online plug, and
929 * upon return, contains the plug number used.
930 * @input: node id of the receiver
931 * @iplug: the input plug to use. If -1, find the first online plug, and
932 * upon return, contains the plug number used.
933 * @bandwidth: an input/output parameter. As an input this is a boolean that
934 * indicates whether to perform bandwidth allocation. Supply 0 to skip bandwidth
935 * allocation; any other value permits it. Upon return, actual bandwidth allocation
936 * units allocated are returned, which you supply to the disconnect routine.
937 * @channel: the channel number on which to reconnect, if possible
938 *
939 * This is a high level function that attempts to be as smart as possible, but
940 * it gives point-to-point connections higher priority over broadcast connections.
941 * It can automatically handle situations where either @input and/or @output does
942 * not implement plug control registers. However, if one node implements plug
943 * registers it assumes the other node has some sort of manual channel selection
944 * (i.e., through software or a control panel).
945 *
946 * This function is useful in bus reset situations where it would be nice to
947 * reconfigure the transmission or reception if the channel does not need to
948 * change.
949 *
950 * Returns:
951 * It returns the isochronous channel number selected or -1 if the function has
952 * failed for any reason.
953 **/
954 int
955 iec61883_cmp_reconnect (raw1394handle_t handle, nodeid_t output, int *oplug,
956 nodeid_t input, int *iplug, int *bandwidth, int channel);
957
958 /**
959 * iec61883_cmp_disconnect - break connection automatically
960 * @handle: a libraw1394 handle
961 * @output: node id of the transmitter
962 * @oplug: the output plug to use, or -1 to find the first online plug.
963 * @input: node id of the receiver
964 * @iplug: the input plug to use, or -1 to find the first online plug.
965 * @channel: the isochronous channel in use
966 * @bandwidth: the number of bandwidth allocation units to release when needed
967 *
968 * This high level connection management function automatically locates the
969 * appropriate plug on @output and @input based upon the channel number. It
970 * gracefully handles when node plugs exist on @output and/or @input. When there
971 * are no more point-to-point connections on output plug, then the channel and
972 * bandwidth are released.
973 *
974 * Returns:
975 * 0 on success or -1 on failure
976 **/
977 int
978 iec61883_cmp_disconnect (raw1394handle_t handle, nodeid_t output, int oplug,
979 nodeid_t input, int iplug, unsigned int channel, unsigned int bandwidth);
980
981 /**
982 * iec61883_cmp_normalize_output - make IRM channels available consistent with plug
983 * @handle: a libraw1394 handle
984 * @node: node id of the transmitter
985 *
986 * Loops over every output plug on the node, and if it has a point-to-point or
987 * broadcast connection, then make sure the channel is allocated with the
988 * isochronous resource manager. This is used to help provide bus sanity and prevent
989 * a channel from being used on a subsequent connection that might really already be
990 * in usage!
991 *
992 * Returns:
993 * 0 on success or -1 ojn failure
994 **/
995 int
996 iec61883_cmp_normalize_output (raw1394handle_t handle, nodeid_t node);
997
998 /*
999 * The following CMP functions are lower level routines used by the above
1000 * connection procedures exposed here in case the above procedures do not fit
1001 * your use cases.
1002 */
1003 int
1004 iec61883_cmp_create_p2p (raw1394handle_t handle,
1005 nodeid_t output_node, int output_plug,
1006 nodeid_t input_node, int input_plug,
1007 unsigned int channel, unsigned int speed);
1008
1009 int
1010 iec61883_cmp_create_p2p_output (raw1394handle_t handle,
1011 nodeid_t output_node, int output_plug,
1012 unsigned int channel, unsigned int speed);
1013
1014 int
1015 iec61883_cmp_create_p2p_input (raw1394handle_t handle,
1016 nodeid_t input_node, int input_plug,
1017 unsigned int channel);
1018
1019 int
1020 iec61883_cmp_create_bcast (raw1394handle_t handle,
1021 nodeid_t output_node, int output_plug,
1022 nodeid_t input_node, int input_plug,
1023 unsigned int channel, unsigned int speed);
1024
1025 int
1026 iec61883_cmp_create_bcast_output (raw1394handle_t handle,
1027 nodeid_t output_node, int output_plug,
1028 unsigned int channel, unsigned int speed);
1029
1030 int
1031 iec61883_cmp_create_bcast_input (raw1394handle_t handle,
1032 nodeid_t input_node, int input_plug,
1033 unsigned int channel);
1034
1035 int
1036 iec61883_cmp_overlay_p2p (raw1394handle_t handle,
1037 nodeid_t output_node, int output_plug,
1038 nodeid_t input_node, int input_plug);
1039
1040 int
1041 iec61883_cmp_overlay_p2p_output (raw1394handle_t handle,
1042 nodeid_t output_node, int output_plug);
1043
1044 int
1045 iec61883_cmp_overlay_p2p_input (raw1394handle_t handle,
1046 nodeid_t input_node, int input_plug);
1047
1048 int
1049 iec61883_cmp_overlay_bcast (raw1394handle_t handle,
1050 nodeid_t output_node, int output_plug,
1051 nodeid_t input_node, int input_plug);
1052
1053 /**
1054 * iec61883_plug_impr_init - Initialise hosting of local input plug registers.
1055 * @h: A raw1394 handle.
1056 * @data_rate: an enum iec61883_datarate
1057 *
1058 * Initially, no plugs are available; call iec61883_plug_add_ipcr() to add
1059 * plugs.
1060 *
1061 * Returns:
1062 * 0 for success, -EINVAL if data_rate is invalid, or or -1 (errno) on
1063 * libraw1394 failure.
1064 **/
1065 int
1066 iec61883_plug_impr_init (raw1394handle_t h, unsigned int data_rate);
1067
1068 /**
1069 * ice61883_plug_impr_clear - Set the number of input plugs to zero.
1070 * @h: A raw1394 handle.
1071 **/
1072 void
1073 iec61883_plug_impr_clear (raw1394handle_t h);
1074
1075 /**
1076 * iec61883_plug_impr_close - Stop hosting local input plugs.
1077 * @h: A raw1394 handle.
1078 *
1079 * Returns:
1080 * 0 for success, -1 (errno) on error.
1081 **/
1082 int
1083 iec61883_plug_impr_close (raw1394handle_t h);
1084
1085 /**
1086 * iec61883_plug_add_ipcr - Add a local input plug.
1087 * @h: A raw1394 handle.
1088 * @online: The initial state of the plug: online (1) or not (0).
1089 *
1090 * You must call iec61883_plug_impr_init() before this.
1091 *
1092 * Returns:
1093 * plug number (>=0) on sucess or -EINVAL if online is not 0 or 1,
1094 * -ENOSPC if maximum plugs reached, or -EPERM if iec61883_plug_impr_init()
1095 * not called.
1096 **/
1097 int
1098 iec61883_plug_ipcr_add (raw1394handle_t h, unsigned int online);
1099
1100 /**
1101 * iec61883_plug_ompr_init - Initialise hosting of local output plug registers.
1102 * @h: A raw1394 handle
1103 * @data_rate: one of enum iec61883_datarate
1104 * @bcast_channel: the broacast channel base (0 - 63)
1105 *
1106 * Initially, no plugs are available; call iec61883_plug_add_opcr() to add
1107 * plugs.
1108 *
1109 * Returns:
1110 * 0 for success, -EINVAL if data_rate or bcast_channel is invalid,
1111 * or or -1 (errno) on libraw1394 failure.
1112 **/
1113 int
1114 iec61883_plug_ompr_init (raw1394handle_t h, unsigned int data_rate,
1115 unsigned int bcast_channel);
1116
1117 /**
1118 * ice61883_plug_ompr_clear - Set the number of output plugs to zero.
1119 * @h: A raw1394 handle.
1120 **/
1121 void
1122 iec61883_plug_ompr_clear (raw1394handle_t h);
1123
1124 /**
1125 * iec61883_plug_ompr_close - Stop hosting local output plugs.
1126 * @h: A raw1394 handle.
1127 *
1128 * Returns:
1129 * 0 for success, -1 (errno) on error.
1130 **/
1131 int
1132 iec61883_plug_ompr_close (raw1394handle_t h);
1133
1134 /**
1135 * iec61883_plug_add_opcr - Add a local output plug.
1136 * @h: A raw1394 handle.
1137 * @online: The initial state of the plug: online (1) or not (0).
1138 * @overhead_id: one of enum iec61883_pcr_overhead_id.
1139 * @payload: the maximum number of quadlets per packet.
1140 *
1141 * You must call iec61883_plug_ompr_init() before this.
1142 *
1143 * Returns:
1144 * plug number (>=0) on sucess, -EINVAL if online is not 0 or 1 or
1145 * if overhead_id or payload are out of range, -ENOSPC if maximum plugs
1146 * reached, or -EPERM if iec61883_plug_ompr_init() not called.
1147 **/
1148 int
1149 iec61883_plug_opcr_add (raw1394handle_t h, unsigned int online,
1150 unsigned int overhead_id, unsigned int payload);
1151
1152
1153 #ifdef __cplusplus
1154 }
1155 #endif
1156
1157 #endif /* _IEC61883_H */