root/branches/api-cleanup/libffado/ffado.h

Revision 816, 15.6 kB (checked in by ppalmers, 14 years ago)

remove support for per-port datatypes. It's too much hassle and it doesn't add enough value.
It also prevents thorough performance optimizations, especially for larger channel counts (e.g. SSE based).

Audio ports are now either all float or all int24. This can be specified by the ffado_streaming_set_audio_datatype
API function before the streaming is prepared. Hence we can still support the direct conversion to the
clients datatype when demuxing the packets.

  • 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 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 3 of the License, or
14  * (at your option) any later version.
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  * Initializes the streaming from/to a FFADO device. A FFADO device
220  * is a virtual device composed of several BeBoB or compatible devices,
221  * linked together in one sync domain.
222  *
223  * This prepares all IEEE1394 related stuff and sets up all buffering.
224  * It elects a sync master if nescessary.
225  *
226  * @param device_info provides a way to specify the virtual device
227  * @param options options regarding buffers, ieee1394 setup, ...
228  *
229  * @return Opaque device handle if successful.  If this is NULL, the
230  * init operation failed.
231  *
232  */
233 ffado_device_t *ffado_streaming_init(
234                      ffado_device_info_t device_info,
235                      ffado_options_t options);
236
237 /**
238  * preparation should be done after setting all per-stream parameters
239  * the way you want them. being buffer data type etc...
240  *
241  * @param dev the ffado device
242  * @return
243  */
244 int ffado_streaming_prepare(ffado_device_t *dev);
245
246
247 /**
248  * Finishes the FFADO streaming. Cleans up all internal data structures
249  * and terminates connections.
250  *
251  * @param dev the ffado device to be closed.
252  */
253 void ffado_streaming_finish(ffado_device_t *dev);
254
255 /**
256  * Returns the amount of capture channels available
257  *
258  * @param dev the ffado device
259  *
260  * @return the number of capture streams present & active on the device.
261  *         can be 0. returns -1 upon error.
262  */
263 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
264
265 /**
266  * Returns the amount of playack channels available
267  *
268  * @param dev the ffado device
269  *
270  * @return the number of playback streams present & active on the device.
271  *         can be 0. returns -1 upon error.
272  */
273 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
274
275 /**
276  * Copies the capture channel name into the specified buffer
277  *
278  * @param dev the ffado device
279  * @param number the stream number
280  * @param buffer the buffer to copy the name into. has to be allocated.
281  * @param buffersize the size of the buffer
282  *
283  * @return the number of characters copied into the buffer
284  */
285 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
286
287 /**
288  * Copies the playback 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_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
298
299 /**
300  * Returns the type of a capture channel
301  *
302  * @param dev the ffado device
303  * @param number the stream number
304  *
305  * @return the channel type
306  */
307 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
308
309 /**
310  * Returns the type of a playback channel
311  *
312  * @param dev the ffado device
313  * @param number the stream number
314  *
315  * @return the channel type
316  */
317 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
318 /*
319  *
320  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
321  * and separately indicate if you want to use a user buffer or a managed buffer.
322  *
323  */
324
325 /**
326  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
327  * The call to ffado_streaming_transfer_buffers will decode one period of the stream to
328  * this buffer. Make sure it is large enough.
329  *
330  * @param dev the ffado device
331  * @param number the stream number
332  * @param buff a pointer to the sample buffer, make sure it is large enough
333  *             i.e. sizeof(your_sample_type)*period_size
334  * @param t   the type of the buffer. this determines sample type and the decode function used.
335  *
336  * @return -1 on error, 0 on success
337  */
338
339 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
340 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
341
342 /**
343  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
344  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
345  * this buffer to the event buffer.
346  *
347  * @param dev the ffado device
348  * @param number the stream number
349  * @param buff a pointer to the sample buffer
350  * @param t   the type of the buffer. this determines sample type and the decode function used.
351  *
352  * @return -1 on error, 0 on success
353  */
354 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
355 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
356
357 ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype(ffado_device_t *dev);
358 int ffado_streaming_set_audio_datatype(ffado_device_t *dev, ffado_streaming_audio_datatype t);
359
360 /**
361  * preparation should be done after setting all per-stream parameters
362  * the way you want them. being buffer data type etc...
363  *
364  * @param dev
365  * @return
366  */
367  
368 int ffado_streaming_prepare(ffado_device_t *dev);
369
370 /**
371  * Starts the streaming operation. This initiates the connections to the FFADO devices and
372  * starts the packet handling thread(s). This has to be called before any I/O can occur.
373  *
374  * @param dev the ffado device
375  *
376  * @return 0 on success, -1 on failure.
377  */
378 int ffado_streaming_start(ffado_device_t *dev);
379
380 /**
381  * Stops the streaming operation. This closes the connections to the FFADO devices and
382  * stops the packet handling thread(s).
383  *
384  * @param dev the ffado device
385  *
386  * @return 0 on success, -1 on failure.
387  */
388 int ffado_streaming_stop(ffado_device_t *dev);
389
390 /**
391  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
392  * are not nescessarily broken and restored.
393  *
394  * All buffers are reset in the initial state and all data in them is lost.
395  *
396  * @param dev the ffado device
397  *
398  * @return 0 on success, -1 on failure.
399  */
400 int ffado_streaming_reset(ffado_device_t *dev);
401
402 /**
403  * Waits until there is at least one period of data available on all capture connections and
404  * room for one period of data on all playback connections
405  *
406  * @param dev the ffado device
407  *
408  * @return The number of frames ready. -1 when a problem occurred.
409  */
410 int ffado_streaming_wait(ffado_device_t *dev);
411
412 /**
413  * Transfer & decode the events from the packet buffer to the sample buffers
414  *
415  * This should be called after the wait call returns, before reading/writing the sample buffers
416  * with ffado_streaming_[read|write].
417  *
418  * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the
419  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
420  *
421  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
422  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
423  * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
424  *
425  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
426  * their contents should be valid before calling this function.
427  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
428  * their contents are updated in this function.
429  *
430  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
431  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
432  * to have more control. Don't use both.
433  *
434  * @param dev the ffado device
435  * @return  -1 on error.
436  */
437  
438 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
439
440 /**
441  * Transfer & encode the events from the sample buffers to the packet buffer
442  *
443  * This should be called after the wait call returns, after writing the sample buffers
444  * with ffado_streaming_write.
445  *
446  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
447  * their contents should be valid before calling this function.
448  *
449  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
450  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
451  * to have more control. Don't use both.
452  *
453  * @param dev the ffado device
454  * @return  -1 on error.
455  */
456  
457 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
458
459 /**
460  * Transfer & decode the events from the packet buffer to the sample buffers
461  *
462  * This should be called after the wait call returns, before reading the sample buffers
463  * with ffado_streaming_read.
464  *
465  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
466  * their contents are updated in this function.
467  *
468  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
469  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
470  * to have more control. Don't use both.
471  *
472  * @param dev the ffado device
473  * @return  -1 on error.
474  */
475
476 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
477
478 #ifdef __cplusplus
479 }
480 #endif
481
482 #endif /* FFADO_STREAMING */
Note: See TracBrowser for help on using the browser.