root/trunk/libffado/libffado/ffado.h

Revision 739, 16.5 kB (checked in by ppalmers, 13 years ago)

- Adapt the ffado external API (upgrade to v3)

NEEDS NEW JACK BACKEND

- simplify FFADODevice constructor even more
- implement first framework support for supporting multiple adapters.

currently all firewire adapters are scanned for supported devices unless specified otherwise
however attaching devices to separate adapters is not supported. using multiple adapters at
that are connected together might work.

  • 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-2007 by Pieter Palmers
4  * Copyright (C) 2005-2007 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 library is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU Lesser General Public
13  * License version 2.1, as published by the Free Software Foundation;
14  *
15  * This library is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18  * Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public
21  * License along with this library; if not, write to the Free Software
22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
23  * MA 02110-1301 USA
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  * Buffer types known to the API
210  *
211  */
212 typedef enum {
213     ffado_buffer_type_per_stream      = -1, // use this to use the per-stream read functions
214     ffado_buffer_type_int24           =  0,
215     ffado_buffer_type_float           =  1,
216     ffado_buffer_type_midi            =  2,
217 } ffado_streaming_buffer_type;
218
219 /**
220  * Initializes the streaming from/to a FFADO device. A FFADO device
221  * is a virtual device composed of several BeBoB or compatible devices,
222  * linked together in one sync domain.
223  *
224  * This prepares all IEEE1394 related stuff and sets up all buffering.
225  * It elects a sync master if nescessary.
226  *
227  * @param device_info provides a way to specify the virtual device
228  * @param options options regarding buffers, ieee1394 setup, ...
229  *
230  * @return Opaque device handle if successful.  If this is NULL, the
231  * init operation failed.
232  *
233  */
234 ffado_device_t *ffado_streaming_init(
235                      ffado_device_info_t device_info,
236                      ffado_options_t options);
237
238 /**
239  * preparation should be done after setting all per-stream parameters
240  * the way you want them. being buffer data type etc...
241  *
242  * @param dev the ffado device
243  * @return
244  */
245 int ffado_streaming_prepare(ffado_device_t *dev);
246
247
248 /**
249  * Finishes the FFADO streaming. Cleans up all internal data structures
250  * and terminates connections.
251  *
252  * @param dev the ffado device to be closed.
253  */
254 void ffado_streaming_finish(ffado_device_t *dev);
255
256 /**
257  * Returns the amount of capture channels available
258  *
259  * @param dev the ffado device
260  *
261  * @return the number of capture streams present & active on the device.
262  *         can be 0. returns -1 upon error.
263  */
264 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
265
266 /**
267  * Returns the amount of playack channels available
268  *
269  * @param dev the ffado device
270  *
271  * @return the number of playback streams present & active on the device.
272  *         can be 0. returns -1 upon error.
273  */
274 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
275
276 /**
277  * Copies the capture channel name into the specified buffer
278  *
279  * @param dev the ffado device
280  * @param number the stream number
281  * @param buffer the buffer to copy the name into. has to be allocated.
282  * @param buffersize the size of the buffer
283  *
284  * @return the number of characters copied into the buffer
285  */
286 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
287
288 /**
289  * Copies the playback channel name into the specified buffer
290  *
291  * @param dev the ffado device
292  * @param number the stream number
293  * @param buffer the buffer to copy the name into. has to be allocated.
294  * @param buffersize the size of the buffer
295  *
296  * @return the number of characters copied into the buffer
297  */
298 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
299
300 /**
301  * Returns the type of a capture channel
302  *
303  * @param dev the ffado device
304  * @param number the stream number
305  *
306  * @return the channel type
307  */
308 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
309
310 /**
311  * Returns the type of a playback channel
312  *
313  * @param dev the ffado device
314  * @param number the stream number
315  *
316  * @return the channel type
317  */
318 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
319 /*
320  *
321  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
322  * and separately indicate if you want to use a user buffer or a managed buffer.
323  *
324  */
325
326 /**
327  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
328  * The call to ffado_streaming_transfer_buffers will decode one period of the stream to
329  * this buffer. Make sure it is large enough.
330  *
331  * @param dev the ffado device
332  * @param number the stream number
333  * @param buff a pointer to the sample buffer, make sure it is large enough
334  *             i.e. sizeof(your_sample_type)*period_size
335  * @param t   the type of the buffer. this determines sample type and the decode function used.
336  *
337  * @return -1 on error, 0 on success
338  */
339
340 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
341 int ffado_streaming_set_capture_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
342 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
343
344 /**
345  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
346  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
347  * this buffer to the event buffer.
348  *
349  * @param dev the ffado device
350  * @param number the stream number
351  * @param buff a pointer to the sample buffer
352  * @param t   the type of the buffer. this determines sample type and the decode function used.
353  *
354  * @return -1 on error, 0 on success
355  */
356 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
357 int ffado_streaming_set_playback_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
358 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
359
360
361 /**
362  * preparation should be done after setting all per-stream parameters
363  * the way you want them. being buffer data type etc...
364  *
365  * @param dev
366  * @return
367  */
368  
369 int ffado_streaming_prepare(ffado_device_t *dev);
370
371 /**
372  * Starts the streaming operation. This initiates the connections to the FFADO devices and
373  * starts the packet handling thread(s). This has to be called before any I/O can occur.
374  *
375  * @param dev the ffado device
376  *
377  * @return 0 on success, -1 on failure.
378  */
379 int ffado_streaming_start(ffado_device_t *dev);
380
381 /**
382  * Stops the streaming operation. This closes the connections to the FFADO devices and
383  * stops the packet handling thread(s).
384  *
385  * @param dev the ffado device
386  *
387  * @return 0 on success, -1 on failure.
388  */
389 int ffado_streaming_stop(ffado_device_t *dev);
390
391 /**
392  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
393  * are not nescessarily broken and restored.
394  *
395  * All buffers are reset in the initial state and all data in them is lost.
396  *
397  * @param dev the ffado device
398  *
399  * @return 0 on success, -1 on failure.
400  */
401 int ffado_streaming_reset(ffado_device_t *dev);
402
403 /**
404  * Waits until there is at least one period of data available on all capture connections and
405  * room for one period of data on all playback connections
406  *
407  * @param dev the ffado device
408  *
409  * @return The number of frames ready. -1 when a problem occurred.
410  */
411 int ffado_streaming_wait(ffado_device_t *dev);
412
413 /**
414  * Reads from a specific channel to a supplied buffer.
415  *
416  * @param dev the ffado device
417  * @param number the stream number
418  * @param buffer the buffer to copy the samples into
419  * @param nsamples the number of samples to be read. the buffer has to be big enough for this amount of samples.
420  *
421  * @return the amount of samples actually read. -1 on error (xrun).
422  */
423 int ffado_streaming_read(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples);
424
425 /**
426  * Write to a specific channel from a supplied buffer.
427  *
428  * @param dev the ffado device
429  * @param number the stream number
430  * @param buffer the buffer to copy the samples from
431  * @param nsamples the number of samples to be written.
432  *
433  * @return the amount of samples actually written. -1 on error.
434  */
435 int ffado_streaming_write(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples);
436
437 /**
438  * Transfer & decode the events from the packet buffer to the sample buffers
439  *
440  * This should be called after the wait call returns, before reading/writing the sample buffers
441  * with ffado_streaming_[read|write].
442  *
443  * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the
444  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
445  *
446  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
447  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
448  * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
449  *
450  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
451  * their contents should be valid before calling this function.
452  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
453  * their contents are updated in this function.
454  *
455  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
456  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
457  * to have more control. Don't use both.
458  *
459  * @param dev the ffado device
460  * @return  -1 on error.
461  */
462  
463 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
464
465 /**
466  * Transfer & encode the events from the sample buffers to the packet buffer
467  *
468  * This should be called after the wait call returns, after writing the sample buffers
469  * with ffado_streaming_write.
470  *
471  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
472  * their contents should be valid before calling this function.
473  *
474  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
475  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
476  * to have more control. Don't use both.
477  *
478  * @param dev the ffado device
479  * @return  -1 on error.
480  */
481  
482 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
483
484 /**
485  * Transfer & decode the events from the packet buffer to the sample buffers
486  *
487  * This should be called after the wait call returns, before reading the sample buffers
488  * with ffado_streaming_read.
489  *
490  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
491  * their contents are updated in this function.
492  *
493  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
494  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
495  * to have more control. Don't use both.
496  *
497  * @param dev the ffado device
498  * @return  -1 on error.
499  */
500
501 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
502
503 #ifdef __cplusplus
504 }
505 #endif
506
507 #endif /* FFADO_STREAMING */
Note: See TracBrowser for help on using the browser.