root/trunk/libffado/libffado/ffado.h

Revision 742, 16.5 kB (checked in by ppalmers, 16 years ago)

- Remove some obsolete support files and dirs

- Clean up the license statements in the source files. Everything is

GPL version 3 now.

- Add license and copyright notices to scons scripts

- Clean up some other text files

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