root/branches/ppalmers-streaming/libffado/ffado.h

Revision 730, 15.5 kB (checked in by ppalmers, 16 years ago)

- Remove OSC related code
- create DBus server application
- add "scons debian" target that builds a debian package

  • 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 #define FFADO_BOUNCE_SERVER_VENDORNAME  "FFADO Server"
32 #define FFADO_BOUNCE_SERVER_MODELNAME   "ffado-server"
33
34 #define FFADO_BOUNCE_SERVER_GETXMLDESCRIPTION_CMD
35 #define AVC1394_SUBUNIT_TYPE_FFADO_BOUNCE_SERVER     0x0D
36
37 #define FFADO_API_VERSION 2
38
39 enum ffado_direction {
40     FFADO_CAPTURE  = 0,
41     FFADO_PLAYBACK = 1,
42 };
43
44 typedef struct ffado_handle* ffado_handle_t;
45
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49
50 ffado_handle_t
51 ffado_new_handle( int port );
52
53 int
54 ffado_destroy_handle( ffado_handle_t ffado_handle );
55
56 int
57 ffado_discover_devices( ffado_handle_t ffado_handle, int verbose_level );
58
59 int ffado_node_is_valid_ffado_device(ffado_handle_t fb_handle, int node_id);
60 int ffado_get_nb_devices_on_bus(ffado_handle_t fb_handle);
61
62 int ffado_get_device_node_id(ffado_handle_t fb_handle, int device_nr);
63 int ffado_set_samplerate(ffado_handle_t ffado_handle, int node_id, int samplerate);
64
65 /* ABI stuff */
66 const char*
67 ffado_get_version();
68
69 int
70 ffado_get_api_version();
71
72 /* various function */
73
74 /* workaround: wait usec after each AVC command.
75    will disapear as soon bug is fixed */   
76 void ffado_sleep_after_avc_command( int time );
77
78 #ifdef __cplusplus
79 }
80 #endif
81
82 #endif /* FFADO_H */
83
84 /* ffado_streaming.h
85  *
86  * Specification for the FFADO Streaming API
87  *
88  */
89 #ifndef __FFADO_STREAMING_H__
90 #define __FFADO_STREAMING_H__
91
92 #include <stdlib.h>
93
94 #ifdef __cplusplus
95 extern "C" {
96 #endif
97
98 #define FFADO_STREAMING_MAX_URL_LENGTH 2048
99
100 #define FFADO_IGNORE_CAPTURE         (1<<0)
101 #define FFADO_IGNORE_PLAYBACK     (1<<1)
102
103
104 /* The basic operation of the API is as follows:
105  *
106  * ffado_streaming_init()
107  * ffado_streaming_start()
108  * while(running) {
109  *   retval = ffado_streaming_wait();
110  *   if (retval == -1) {
111  *     ffado_streaming_reset();
112  *     continue;
113  *   }
114  *
115  *   ffado_streaming_transfer_buffers(dev);
116  *
117  *   for(all channels) {
118  *     switch (channel_type) {
119  *     case audio:
120  *       bytesread=ffado_streaming_read(audioinbuffer[channel]);
121  *       byteswritten=ffado_streaming_write(audiooutbuffer[channel]);
122  *     case midi:
123  *       bytesread=ffado_streaming_read(midiinbuffer[channel]);
124  *       byteswritten=ffado_streaming_write(midioutbuffer[channel]);
125  *     }
126  *   }
127  * }
128  * ffado_streaming_stop();
129  * ffado_streaming_finish();
130  *
131  */
132
133 typedef struct _ffado_device ffado_device_t;
134
135 /**
136  * The sample format used by the ffado streaming API
137  */
138
139 typedef unsigned int ffado_sample_t;
140
141
142 typedef unsigned int ffado_nframes_t;
143
144
145 typedef struct ffado_device_info {
146     /* TODO: How is the device specification done? */
147 //    ffado_device_info_location_type location_type;
148 } ffado_device_info_t;
149
150 /**
151  * Structure to pass the options to the ffado streaming code.
152  */
153 typedef struct ffado_options {
154     /* driver related setup */
155     int sample_rate;         /* this is acutally dictated by the device
156                              * you can specify a value here or -1 to autodetect
157                               */
158
159     /* buffer setup */
160     int period_size;     /* one period is the amount of frames that
161                  * has to be sent or received in order for
162                  * a period boundary to be signalled.
163                  * (unit: frames)
164                  */
165     int nb_buffers;    /* the size of the frame buffer (in periods) */
166
167     /* packetizer thread options */
168     int realtime;
169     int packetizer_priority;
170    
171     /* libffado related setup */
172     int node_id;
173     int port;
174    
175     /* direction map */
176     int directions;
177    
178     /* verbosity */
179     int verbose;
180    
181     /* slave mode */
182     int slave_mode;
183    
184     /* snoop mode */
185     int snoop_mode;
186
187 } ffado_options_t;
188
189 /**
190  * The types of streams supported by the API
191  *
192  * A ffado_audio type stream is a stream that consists of successive samples.
193  * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the
194  * 32bit UINT of the read/write buffer.
195  * The wait operation looks at this type of streams only.
196  *
197  * A ffado_midi type stream is a stream of midi bytes. The bytes are 8bit UINT,
198  * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.
199  *
200  */
201 typedef enum {
202     ffado_stream_type_invalid                      =   -1,
203       ffado_stream_type_unknown                      =   0,
204       ffado_stream_type_audio                        =   1,
205       ffado_stream_type_midi                         =   2,
206       ffado_stream_type_control                      =   3,
207 } ffado_streaming_stream_type;
208
209 /**
210  *
211  * Buffer types known to the API
212  *
213  */
214 typedef enum {
215     ffado_buffer_type_per_stream          =   -1, // use this to use the per-stream read functions
216     ffado_buffer_type_int24           =   0,
217     ffado_buffer_type_float            =   1,
218     ffado_buffer_type_midi            =   2,
219 //     ffado_buffer_type_uint32           =   2,
220 //     ffado_buffer_type_double           =   3,
221 //     ...
222 } ffado_streaming_buffer_type;
223
224 /**
225  * Initializes the streaming from/to a FFADO device. A FFADO device
226  * is a virtual device composed of several BeBoB or compatible devices,
227  * linked together in one sync domain.
228  *
229  * This prepares all IEEE1394 related stuff and sets up all buffering.
230  * It elects a sync master if nescessary.
231  *
232  * @param device_info provides a way to specify the virtual device
233  * @param options options regarding buffers, ieee1394 setup, ...
234  *
235  * @return Opaque device handle if successful.  If this is NULL, the
236  * init operation failed.
237  *
238  */
239 ffado_device_t *ffado_streaming_init (ffado_device_info_t *device_info,
240                      ffado_options_t options);
241
242 /**
243  * preparation should be done after setting all per-stream parameters
244  * the way you want them. being buffer data type etc...
245  *
246  * @param dev the ffado device
247  * @return
248  */
249 int ffado_streaming_prepare(ffado_device_t *dev);
250
251
252 /**
253  * Finishes the FFADO streaming. Cleans up all internal data structures
254  * and terminates connections.
255  *
256  * @param dev the ffado device to be closed.
257  */
258 void ffado_streaming_finish(ffado_device_t *dev);
259
260 /**
261  * Returns the amount of capture channels available
262  *
263  * @param dev the ffado device
264  *
265  * @return the number of capture streams present & active on the device.
266  *         can be 0. returns -1 upon error.
267  */
268 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
269
270 /**
271  * Returns the amount of playack channels available
272  *
273  * @param dev the ffado device
274  *
275  * @return the number of playback streams present & active on the device.
276  *         can be 0. returns -1 upon error.
277  */
278 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
279
280 /**
281  * Copies the capture channel name into the specified buffer
282  *
283  * @param dev the ffado device
284  * @param number the stream number
285  * @param buffer the buffer to copy the name into. has to be allocated.
286  * @param buffersize the size of the buffer
287  *
288  * @return the number of characters copied into the buffer
289  */
290 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
291
292 /**
293  * Copies the playback channel name into the specified buffer
294  *
295  * @param dev the ffado device
296  * @param number the stream number
297  * @param buffer the buffer to copy the name into. has to be allocated.
298  * @param buffersize the size of the buffer
299  *
300  * @return the number of characters copied into the buffer
301  */
302 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
303
304 /**
305  * Returns the type of a capture channel
306  *
307  * @param dev the ffado device
308  * @param number the stream number
309  *
310  * @return the channel type
311  */
312 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
313
314 /**
315  * Returns the type of a playback channel
316  *
317  * @param dev the ffado device
318  * @param number the stream number
319  *
320  * @return the channel type
321  */
322 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
323 /*
324  *
325  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
326  * and separately indicate if you want to use a user buffer or a managed buffer.
327  *
328  */
329  
330  
331  
332 /**
333  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
334  * The call to ffado_streaming_transfer_buffers will decode one period of the stream to
335  * this buffer. Make sure it is large enough.
336  *
337  * @param dev the ffado device
338  * @param number the stream number
339  * @param buff a pointer to the sample buffer, make sure it is large enough
340  *             i.e. sizeof(your_sample_type)*period_size
341  * @param t   the type of the buffer. this determines sample type and the decode function used.
342  *
343  * @return -1 on error, 0 on success
344  */
345
346 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
347 int ffado_streaming_set_capture_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
348 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
349
350 /**
351  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
352  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
353  * this buffer to the event buffer.
354  *
355  * @param dev the ffado device
356  * @param number the stream number
357  * @param buff a pointer to the sample buffer
358  * @param t   the type of the buffer. this determines sample type and the decode function used.
359  *
360  * @return -1 on error, 0 on success
361  */
362 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
363 int ffado_streaming_set_playback_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
364 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
365
366
367 /**
368  * preparation should be done after setting all per-stream parameters
369  * the way you want them. being buffer data type etc...
370  *
371  * @param dev
372  * @return
373  */
374  
375 int ffado_streaming_prepare(ffado_device_t *dev);
376
377 /**
378  * Starts the streaming operation. This initiates the connections to the FFADO devices and
379  * starts the packet handling thread(s). This has to be called before any I/O can occur.
380  *
381  * @param dev the ffado device
382  *
383  * @return 0 on success, -1 on failure.
384  */
385 int ffado_streaming_start(ffado_device_t *dev);
386
387 /**
388  * Stops the streaming operation. This closes the connections to the FFADO devices and
389  * stops the packet handling thread(s).
390  *
391  * @param dev the ffado device
392  *
393  * @return 0 on success, -1 on failure.
394  */
395 int ffado_streaming_stop(ffado_device_t *dev);
396
397 /**
398  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
399  * are not nescessarily broken and restored.
400  *
401  * All buffers are reset in the initial state and all data in them is lost.
402  *
403  * @param dev the ffado device
404  *
405  * @return 0 on success, -1 on failure.
406  */
407 int ffado_streaming_reset(ffado_device_t *dev);
408
409 /**
410  * Waits until there is at least one period of data available on all capture connections and
411  * room for one period of data on all playback connections
412  *
413  * @param dev the ffado device
414  *
415  * @return The number of frames ready. -1 when a problem occurred.
416  */
417 int ffado_streaming_wait(ffado_device_t *dev);
418
419 /**
420  * Reads from a specific channel to a supplied buffer.
421  *
422  * @param dev the ffado device
423  * @param number the stream number
424  * @param buffer the buffer to copy the samples into
425  * @param nsamples the number of samples to be read. the buffer has to be big enough for this amount of samples.
426  *
427  * @return the amount of samples actually read. -1 on error (xrun).
428  */
429 int ffado_streaming_read(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples);
430
431 /**
432  * Write to a specific channel from a supplied buffer.
433  *
434  * @param dev the ffado device
435  * @param number the stream number
436  * @param buffer the buffer to copy the samples from
437  * @param nsamples the number of samples to be written.
438  *
439  * @return the amount of samples actually written. -1 on error.
440  */
441 int ffado_streaming_write(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples);
442
443 /**
444  * Transfer & decode the events from the packet buffer to the sample buffers
445  *
446  * This should be called after the wait call returns, before reading/writing the sample buffers
447  * with ffado_streaming_[read|write].
448  *
449  * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the
450  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
451  *
452  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
453  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
454  * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
455  *
456  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
457  * their contents should be valid before calling this function.
458  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
459  * their contents are updated in this function.
460  *
461  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
462  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
463  * to have more control. Don't use both.
464  *
465  * @param dev the ffado device
466  * @return  -1 on error.
467  */
468  
469 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
470
471 /**
472  * Transfer & encode the events from the sample buffers to the packet buffer
473  *
474  * This should be called after the wait call returns, after writing the sample buffers
475  * with ffado_streaming_write.
476  *
477  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
478  * their contents should be valid before calling this function.
479  *
480  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
481  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
482  * to have more control. Don't use both.
483  *
484  * @param dev the ffado device
485  * @return  -1 on error.
486  */
487  
488 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
489
490 /**
491  * Transfer & decode the events from the packet buffer to the sample buffers
492  *
493  * This should be called after the wait call returns, before reading the sample buffers
494  * with ffado_streaming_read.
495  *
496  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
497  * their contents are updated in this function.
498  *
499  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
500  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
501  * to have more control. Don't use both.
502  *
503  * @param dev the ffado device
504  * @return  -1 on error.
505  */
506
507 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
508
509 #ifdef __cplusplus
510 }
511 #endif
512
513 #endif /* FFADO_STREAMING */
Note: See TracBrowser for help on using the browser.