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

Revision 2811, 16.8 kB (checked in by jwoithe, 2 years ago)

Cosmetic: "firewire" should be "FireWire?" when used as the bus name.

Similarly to r2802 and r2810, "FireWire?" should be used when referring to
the name of the bus. This patch corrects this throughout the source tree
for completeness. While there are a small number of mostly debug output
strings affected, most of the changes are to comments or developer documents
where they are of little consequence. Thanks to Pander who suggested the
need to look into this on the ffado-devel mailing list.

At least in theory, remaining instances of "firewire" in the source tree
should remain as they are because they refer to case-sensitive identifiers
defined externally (such as the "firewire" jackd backend name).

  • 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.