root/trunk/libffado/libffado/ffado.h.in

Revision 2087, 16.8 kB (checked in by jwoithe, 9 years ago)

define FFADO_API_VERSION publically so users of libffado can check the API version at compile time, making it easier to maintain a code base which can compile against older API versions if necessary.

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