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

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

First round of cleanup:
- make Ports auto-register to a PortManager?
- remove the different 'signal' types, everything is now period-signaled.
- removed obsolete streaming test programs

  • 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_int24           =  0,
214     ffado_buffer_type_float           =  1,
215     ffado_buffer_type_midi            =  2,
216 } ffado_streaming_buffer_type;
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_set_capture_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
341 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
342
343 /**
344  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
345  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
346  * this buffer to the event buffer.
347  *
348  * @param dev the ffado device
349  * @param number the stream number
350  * @param buff a pointer to the sample buffer
351  * @param t   the type of the buffer. this determines sample type and the decode function used.
352  *
353  * @return -1 on error, 0 on success
354  */
355 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
356 int ffado_streaming_set_playback_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
357 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
358
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.