root/trunk/libffado/libffado/ffado.h

Revision 967, 15.8 kB (checked in by ppalmers, 16 years ago)

- first attempt at not causing total havoc when devices are removed from the bus.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 /* ffado.h
2  *
3  * Copyright (C) 2005-2008 by Pieter Palmers
4  * Copyright (C) 2005-2008 by Daniel Wagner
5  *
6  * This file is part of FFADO
7  * FFADO = Free Firewire (pro-)audio drivers for linux
8  *
9  * FFADO is based upon FreeBoB
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 2 of the License, or
14  * (at your option) version 3 of the License.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23  *
24  */
25
26 #ifndef FFADO_H
27 #define FFADO_H
28
29 #define FFADO_MAX_NAME_LEN 256
30
31 #include <stdlib.h>
32
33 #define FFADO_STREAMING_MAX_URL_LENGTH 2048
34
35 #define FFADO_IGNORE_CAPTURE         (1<<0)
36 #define FFADO_IGNORE_PLAYBACK     (1<<1)
37
38 enum ffado_direction {
39     FFADO_CAPTURE  = 0,
40     FFADO_PLAYBACK = 1,
41 };
42
43 typedef struct ffado_handle* ffado_handle_t;
44
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48
49 /* ABI stuff */
50 const char*
51 ffado_get_version();
52
53 int
54 ffado_get_api_version();
55
56 /* various function */
57
58 /* workaround: wait usec after each AVC command.
59    will disapear as soon bug is fixed */   
60 void ffado_sleep_after_avc_command( int time );
61
62
63 /* The basic operation of the API is as follows:
64  *
65  * ffado_streaming_init()
66  * ffado_streaming_start()
67  * while(running) {
68  *   retval = ffado_streaming_wait();
69  *   if (retval == -1) {
70  *     ffado_streaming_reset();
71  *     continue;
72  *   }
73  *
74  *   ffado_streaming_transfer_buffers(dev);
75  *
76  *   for(all channels) {
77  *     switch (channel_type) {
78  *     case audio:
79  *       bytesread=ffado_streaming_read(audioinbuffer[channel]);
80  *       byteswritten=ffado_streaming_write(audiooutbuffer[channel]);
81  *     case midi:
82  *       bytesread=ffado_streaming_read(midiinbuffer[channel]);
83  *       byteswritten=ffado_streaming_write(midioutbuffer[channel]);
84  *     }
85  *   }
86  * }
87  * ffado_streaming_stop();
88  * ffado_streaming_finish();
89  *
90  */
91
92 typedef struct _ffado_device ffado_device_t;
93
94 /**
95  * The sample format used by the ffado streaming API
96  */
97
98 typedef unsigned int ffado_sample_t; // FIXME
99 typedef unsigned int ffado_nframes_t;
100
101 #define FFADO_MAX_SPECSTRING_LENGTH 256
102 #define FFADO_MAX_SPECSTRINGS       64
103 /**
104  * This struct serves to define the devices that should be used by the library
105  * device_spec_strings is an array of pointers that should contain nb_device_spec_strings
106  * valid pointers to strings.
107  *
108  * The spec strings should be null terminated and can be no longer
109  * than FFADO_MAX_SPECSTRINGS.
110  *
111  * nb_device_spec_strings < FFADO_MAX_SPECSTRING_LENGTH
112  * nb_device_spec_strings >= 0
113  *
114  * If nb_device_spec_strings == 0, all busses are scanned for attached devices, and
115  * all found devices that are supported are combined into one large pseudo-device. The
116  * device order is defined by the GUID of the device. Devices with lower GUID's will
117  * be the first ones.
118  *
119  * If multiple device specifications are present, the device order is defined as follows:
120  *  - device(s) that correspond to a spec string with a lower index will be added before
121  *    devices from higher indexes.
122  *  - if a spec string results in multiple devices, they are sorted by GUID unless the
123  *    spec format dictates otherwise.
124  *
125  * The actual meaning of the device specification should be one of the following:
126  * - Format 1: "hw:x[,y[,z]]"
127  *     x = the firewire bus to use ('port' in raw1394 terminology)
128  *         (mandatory)
129  *     y = the node id the device currently has (bus resets might change that, but FFADO
130  *         will track these changes and keep using the device specified on startup)
131  *         (optional)
132  *     z = the stream direction to use.
133  *           0 => capture (record) channels only
134  *           1 => playback channels only
135  *           other/unspecified => both playback and capture
136  *         (optional)
137  *
138  * - Format 2: the device alias as defined in the ffado config file (UNIMPLEMENTED)
139  */
140 typedef struct ffado_device_info {
141     unsigned int nb_device_spec_strings;
142     char **device_spec_strings;
143
144     /* add some extra space to allow for future API extention
145        w/o breaking binary compatibility */
146     int32_t reserved[32];
147 } ffado_device_info_t;
148
149 /**
150  * Structure to pass the options to the ffado streaming code.
151  */
152 typedef struct ffado_options {
153     /* driver related setup */
154     int32_t sample_rate;         /*
155                              * you can specify a value here or -1 to autodetect
156                               */
157
158     /* buffer setup */
159     int32_t period_size;     /* one period is the amount of frames that
160                  * has to be sent or received in order for
161                  * a period boundary to be signalled.
162                  * (unit: frames)
163                  */
164     int32_t nb_buffers;    /* the size of the frame buffer (in periods) */
165
166     /* packetizer thread options */
167     int32_t realtime;
168     int32_t packetizer_priority;
169
170     /* verbosity */
171     int32_t verbose;
172
173     /* slave mode */
174     int32_t slave_mode;
175     /* snoop mode */
176     int32_t snoop_mode;
177
178     /* add some extra space to allow for future API extention
179        w/o breaking binary compatibility */
180     int32_t reserved[24];
181
182 } ffado_options_t;
183
184 /**
185  * The types of streams supported by the API
186  *
187  * A ffado_audio type stream is a stream that consists of successive samples.
188  * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the
189  * 32bit UINT of the read/write buffer.
190  * The wait operation looks at this type of streams only.
191  *
192  * A ffado_midi type stream is a stream of midi bytes. The bytes are 8bit UINT,
193  * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.
194  *
195  * A ffado_control type stream is a stream that provides control information. The
196  * format of this control information is undefined, and the stream should be ignored.
197  *
198  */
199 typedef enum {
200       ffado_stream_type_invalid                      =   -1,
201       ffado_stream_type_unknown                      =   0,
202       ffado_stream_type_audio                        =   1,
203       ffado_stream_type_midi                         =   2,
204       ffado_stream_type_control                      =   3,
205 } ffado_streaming_stream_type;
206
207 /**
208  *
209  * Audio data types known to the API
210  *
211  */
212 typedef enum {
213     ffado_audio_datatype_error           = -1,
214     ffado_audio_datatype_int24           =  0,
215     ffado_audio_datatype_float           =  1,
216 } ffado_streaming_audio_datatype;
217
218 /**
219  *
220  * Wait responses
221  *
222  */
223 typedef enum {
224     ffado_wait_shutdown        = -3,
225     ffado_wait_error           = -2,
226     ffado_wait_xrun            = -1,
227     ffado_wait_ok              =  0,
228 } ffado_wait_response;
229
230 /**
231  * Initializes the streaming from/to a FFADO device. A FFADO device
232  * is a virtual device composed of several BeBoB or compatible devices,
233  * linked together in one sync domain.
234  *
235  * This prepares all IEEE1394 related stuff and sets up all buffering.
236  * It elects a sync master if nescessary.
237  *
238  * @param device_info provides a way to specify the virtual device
239  * @param options options regarding buffers, ieee1394 setup, ...
240  *
241  * @return Opaque device handle if successful.  If this is NULL, the
242  * init operation failed.
243  *
244  */
245 ffado_device_t *ffado_streaming_init(
246                      ffado_device_info_t device_info,
247                      ffado_options_t options);
248
249 /**
250  * preparation should be done after setting all per-stream parameters
251  * the way you want them. being buffer data type etc...
252  *
253  * @param dev the ffado device
254  * @return
255  */
256 int ffado_streaming_prepare(ffado_device_t *dev);
257
258
259 /**
260  * Finishes the FFADO streaming. Cleans up all internal data structures
261  * and terminates connections.
262  *
263  * @param dev the ffado device to be closed.
264  */
265 void ffado_streaming_finish(ffado_device_t *dev);
266
267 /**
268  * Returns the amount of capture channels available
269  *
270  * @param dev the ffado device
271  *
272  * @return the number of capture streams present & active on the device.
273  *         can be 0. returns -1 upon error.
274  */
275 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
276
277 /**
278  * Returns the amount of playack channels available
279  *
280  * @param dev the ffado device
281  *
282  * @return the number of playback streams present & active on the device.
283  *         can be 0. returns -1 upon error.
284  */
285 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
286
287 /**
288  * Copies the capture channel name into the specified buffer
289  *
290  * @param dev the ffado device
291  * @param number the stream number
292  * @param buffer the buffer to copy the name into. has to be allocated.
293  * @param buffersize the size of the buffer
294  *
295  * @return the number of characters copied into the buffer
296  */
297 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
298
299 /**
300  * Copies the playback channel name into the specified buffer
301  *
302  * @param dev the ffado device
303  * @param number the stream number
304  * @param buffer the buffer to copy the name into. has to be allocated.
305  * @param buffersize the size of the buffer
306  *
307  * @return the number of characters copied into the buffer
308  */
309 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
310
311 /**
312  * Returns the type of a capture channel
313  *
314  * @param dev the ffado device
315  * @param number the stream number
316  *
317  * @return the channel type
318  */
319 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
320
321 /**
322  * Returns the type of a playback channel
323  *
324  * @param dev the ffado device
325  * @param number the stream number
326  *
327  * @return the channel type
328  */
329 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
330 /*
331  *
332  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
333  * and separately indicate if you want to use a user buffer or a managed buffer.
334  *
335  */
336
337 /**
338  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
339  * The call to ffado_streaming_transfer_buffers will decode one period of the stream to
340  * this buffer. Make sure it is large enough.
341  *
342  * @param dev the ffado device
343  * @param number the stream number
344  * @param buff a pointer to the sample buffer, make sure it is large enough
345  *             i.e. sizeof(your_sample_type)*period_size
346  * @param t   the type of the buffer. this determines sample type and the decode function used.
347  *
348  * @return -1 on error, 0 on success
349  */
350
351 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
352 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
353
354 /**
355  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
356  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
357  * this buffer to the event buffer.
358  *
359  * @param dev the ffado device
360  * @param number the stream number
361  * @param buff a pointer to the sample buffer
362  * @param t   the type of the buffer. this determines sample type and the decode function used.
363  *
364  * @return -1 on error, 0 on success
365  */
366 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
367 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
368
369 ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype(ffado_device_t *dev);
370 int ffado_streaming_set_audio_datatype(ffado_device_t *dev, ffado_streaming_audio_datatype t);
371
372 /**
373  * preparation should be done after setting all per-stream parameters
374  * the way you want them. being buffer data type etc...
375  *
376  * @param dev
377  * @return
378  */
379  
380 int ffado_streaming_prepare(ffado_device_t *dev);
381
382 /**
383  * Starts the streaming operation. This initiates the connections to the FFADO devices and
384  * starts the packet handling thread(s). This has to be called before any I/O can occur.
385  *
386  * @param dev the ffado device
387  *
388  * @return 0 on success, -1 on failure.
389  */
390 int ffado_streaming_start(ffado_device_t *dev);
391
392 /**
393  * Stops the streaming operation. This closes the connections to the FFADO devices and
394  * stops the packet handling thread(s).
395  *
396  * @param dev the ffado device
397  *
398  * @return 0 on success, -1 on failure.
399  */
400 int ffado_streaming_stop(ffado_device_t *dev);
401
402 /**
403  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
404  * are not nescessarily broken and restored.
405  *
406  * All buffers are reset in the initial state and all data in them is lost.
407  *
408  * @param dev the ffado device
409  *
410  * @return 0 on success, -1 on failure.
411  */
412 int ffado_streaming_reset(ffado_device_t *dev);
413
414 /**
415  * Waits until there is at least one period of data available on all capture connections and
416  * room for one period of data on all playback connections
417  *
418  * @param dev the ffado device
419  *
420  * @return The number of frames ready. -1 when a problem occurred.
421  */
422 ffado_wait_response ffado_streaming_wait(ffado_device_t *dev);
423
424 /**
425  * Transfer & decode the events from the packet buffer to the sample buffers
426  *
427  * This should be called after the wait call returns, before reading/writing the sample buffers
428  * with ffado_streaming_[read|write].
429  *
430  * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the
431  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
432  *
433  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
434  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
435  * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
436  *
437  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
438  * their contents should be valid before calling this function.
439  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
440  * their contents are updated in this function.
441  *
442  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
443  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
444  * to have more control. Don't use both.
445  *
446  * @param dev the ffado device
447  * @return  -1 on error.
448  */
449  
450 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
451
452 /**
453  * Transfer & encode the events from the sample buffers to the packet buffer
454  *
455  * This should be called after the wait call returns, after writing the sample buffers
456  * with ffado_streaming_write.
457  *
458  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
459  * their contents should be valid before calling this function.
460  *
461  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
462  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
463  * to have more control. Don't use both.
464  *
465  * @param dev the ffado device
466  * @return  -1 on error.
467  */
468  
469 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
470
471 /**
472  * Transfer & decode the events from the packet buffer to the sample buffers
473  *
474  * This should be called after the wait call returns, before reading the sample buffers
475  * with ffado_streaming_read.
476  *
477  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
478  * their contents are updated in this function.
479  *
480  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
481  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
482  * to have more control. Don't use both.
483  *
484  * @param dev the ffado device
485  * @return  -1 on error.
486  */
487
488 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
489
490 #ifdef __cplusplus
491 }
492 #endif
493
494 #endif /* FFADO_STREAMING */
Note: See TracBrowser for help on using the browser.