root/trunk/libffado/libffado/ffado.h

Revision 453, 15.6 kB (checked in by ppalmers, 17 years ago)

correct forgotten files in name change

  • 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 //    char xml_location[FFADO_STREAMING_MAX_URL_LENGTH]; // can be an osc url or an XML filename
148 //    ffado_device_info_location_type location_type;
149 } ffado_device_info_t;
150
151 /**
152  * Structure to pass the options to the ffado streaming code.
153  */
154 typedef struct ffado_options {
155     /* driver related setup */
156     int sample_rate;         /* this is acutally dictated by the device
157                              * you can specify a value here or -1 to autodetect
158                               */
159
160     /* buffer setup */
161     int period_size;     /* one period is the amount of frames that
162                  * has to be sent or received in order for
163                  * a period boundary to be signalled.
164                  * (unit: frames)
165                  */
166     int nb_buffers;    /* the size of the frame buffer (in periods) */
167
168     /* packetizer thread options */
169     int realtime;
170     int packetizer_priority;
171    
172     /* libffado related setup */
173     int node_id;
174     int port;
175    
176     /* direction map */
177     int directions;
178    
179     /* verbosity */
180     int verbose;
181    
182     /* slave mode */
183     int slave_mode;
184    
185     /* snoop mode */
186     int snoop_mode;
187
188 } ffado_options_t;
189
190 /**
191  * The types of streams supported by the API
192  *
193  * A ffado_audio type stream is a stream that consists of successive samples.
194  * The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the
195  * 32bit UINT of the read/write buffer.
196  * The wait operation looks at this type of streams only.
197  *
198  * A ffado_midi type stream is a stream of midi bytes. The bytes are 8bit UINT,
199  * aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.
200  *
201  */
202 typedef enum {
203     ffado_stream_type_invalid                      =   -1,
204       ffado_stream_type_unknown                      =   0,
205       ffado_stream_type_audio                        =   1,
206       ffado_stream_type_midi                         =   2,
207       ffado_stream_type_control                      =   3,
208 } ffado_streaming_stream_type;
209
210 /**
211  *
212  * Buffer types known to the API
213  *
214  */
215 typedef enum {
216     ffado_buffer_type_per_stream          =   -1, // use this to use the per-stream read functions
217     ffado_buffer_type_int24           =   0,
218     ffado_buffer_type_float            =   1,
219     ffado_buffer_type_midi            =   2,
220 //     ffado_buffer_type_uint32           =   2,
221 //     ffado_buffer_type_double           =   3,
222 //     ...
223 } ffado_streaming_buffer_type;
224
225 /**
226  * Initializes the streaming from/to a FFADO device. A FFADO device
227  * is a virtual device composed of several BeBoB or compatible devices,
228  * linked together in one sync domain.
229  *
230  * This prepares all IEEE1394 related stuff and sets up all buffering.
231  * It elects a sync master if nescessary.
232  *
233  * @param device_info provides a way to specify the virtual device
234  * @param options options regarding buffers, ieee1394 setup, ...
235  *
236  * @return Opaque device handle if successful.  If this is NULL, the
237  * init operation failed.
238  *
239  */
240 ffado_device_t *ffado_streaming_init (ffado_device_info_t *device_info,
241                      ffado_options_t options);
242
243 /**
244  * preparation should be done after setting all per-stream parameters
245  * the way you want them. being buffer data type etc...
246  *
247  * @param dev the ffado device
248  * @return
249  */
250 int ffado_streaming_prepare(ffado_device_t *dev);
251
252
253 /**
254  * Finishes the FFADO streaming. Cleans up all internal data structures
255  * and terminates connections.
256  *
257  * @param dev the ffado device to be closed.
258  */
259 void ffado_streaming_finish(ffado_device_t *dev);
260
261 /**
262  * Returns the amount of capture channels available
263  *
264  * @param dev the ffado device
265  *
266  * @return the number of capture streams present & active on the device.
267  *         can be 0. returns -1 upon error.
268  */
269 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
270
271 /**
272  * Returns the amount of playack channels available
273  *
274  * @param dev the ffado device
275  *
276  * @return the number of playback streams present & active on the device.
277  *         can be 0. returns -1 upon error.
278  */
279 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
280
281 /**
282  * Copies the capture channel name into the specified buffer
283  *
284  * @param dev the ffado device
285  * @param number the stream number
286  * @param buffer the buffer to copy the name into. has to be allocated.
287  * @param buffersize the size of the buffer
288  *
289  * @return the number of characters copied into the buffer
290  */
291 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
292
293 /**
294  * Copies the playback channel name into the specified buffer
295  *
296  * @param dev the ffado device
297  * @param number the stream number
298  * @param buffer the buffer to copy the name into. has to be allocated.
299  * @param buffersize the size of the buffer
300  *
301  * @return the number of characters copied into the buffer
302  */
303 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
304
305 /**
306  * Returns the type of a capture channel
307  *
308  * @param dev the ffado device
309  * @param number the stream number
310  *
311  * @return the channel type
312  */
313 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
314
315 /**
316  * Returns the type of a playback channel
317  *
318  * @param dev the ffado device
319  * @param number the stream number
320  *
321  * @return the channel type
322  */
323 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
324 /*
325  *
326  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
327  * and separately indicate if you want to use a user buffer or a managed buffer.
328  *
329  */
330  
331  
332  
333 /**
334  * Sets the decode buffer for the stream. This allows for zero-copy decoding.
335  * The call to ffado_streaming_transfer_buffers will decode one period of the stream to
336  * this buffer. Make sure it is large enough.
337  *
338  * @param dev the ffado device
339  * @param number the stream number
340  * @param buff a pointer to the sample buffer, make sure it is large enough
341  *             i.e. sizeof(your_sample_type)*period_size
342  * @param t   the type of the buffer. this determines sample type and the decode function used.
343  *
344  * @return -1 on error, 0 on success
345  */
346
347 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
348 int ffado_streaming_set_capture_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
349 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
350
351 /**
352  * Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events).
353  * The call to ffado_streaming_transfer_buffers will encode one period of the stream from
354  * this buffer to the event buffer.
355  *
356  * @param dev the ffado device
357  * @param number the stream number
358  * @param buff a pointer to the sample buffer
359  * @param t   the type of the buffer. this determines sample type and the decode function used.
360  *
361  * @return -1 on error, 0 on success
362  */
363 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
364 int ffado_streaming_set_playback_buffer_type(ffado_device_t *dev, int i, ffado_streaming_buffer_type t);
365 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
366
367
368 /**
369  * preparation should be done after setting all per-stream parameters
370  * the way you want them. being buffer data type etc...
371  *
372  * @param dev
373  * @return
374  */
375  
376 int ffado_streaming_prepare(ffado_device_t *dev);
377
378 /**
379  * Starts the streaming operation. This initiates the connections to the FFADO devices and
380  * starts the packet handling thread(s). This has to be called before any I/O can occur.
381  *
382  * @param dev the ffado device
383  *
384  * @return 0 on success, -1 on failure.
385  */
386 int ffado_streaming_start(ffado_device_t *dev);
387
388 /**
389  * Stops the streaming operation. This closes the connections to the FFADO devices and
390  * stops the packet handling thread(s).
391  *
392  * @param dev the ffado device
393  *
394  * @return 0 on success, -1 on failure.
395  */
396 int ffado_streaming_stop(ffado_device_t *dev);
397
398 /**
399  * Resets the streaming as if it was stopped and restarted. The difference is that the connections
400  * are not nescessarily broken and restored.
401  *
402  * All buffers are reset in the initial state and all data in them is lost.
403  *
404  * @param dev the ffado device
405  *
406  * @return 0 on success, -1 on failure.
407  */
408 int ffado_streaming_reset(ffado_device_t *dev);
409
410 /**
411  * Waits until there is at least one period of data available on all capture connections and
412  * room for one period of data on all playback connections
413  *
414  * @param dev the ffado device
415  *
416  * @return The number of frames ready. -1 when a problem occurred.
417  */
418 int ffado_streaming_wait(ffado_device_t *dev);
419
420 /**
421  * Reads from a specific channel to a supplied buffer.
422  *
423  * @param dev the ffado device
424  * @param number the stream number
425  * @param buffer the buffer to copy the samples into
426  * @param nsamples the number of samples to be read. the buffer has to be big enough for this amount of samples.
427  *
428  * @return the amount of samples actually read. -1 on error (xrun).
429  */
430 int ffado_streaming_read(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples);
431
432 /**
433  * Write to a specific channel from a supplied buffer.
434  *
435  * @param dev the ffado device
436  * @param number the stream number
437  * @param buffer the buffer to copy the samples from
438  * @param nsamples the number of samples to be written.
439  *
440  * @return the amount of samples actually written. -1 on error.
441  */
442 int ffado_streaming_write(ffado_device_t *dev, int number, ffado_sample_t *buffer, int nsamples);
443
444 /**
445  * Transfer & decode the events from the packet buffer to the sample buffers
446  *
447  * This should be called after the wait call returns, before reading/writing the sample buffers
448  * with ffado_streaming_[read|write].
449  *
450  * The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the
451  * period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).
452  *
453  * The actual decoding work is done in this function and can therefore be omitted in this timing calculation.
454  * Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when
455  * ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).
456  *
457  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
458  * their contents should be valid before calling this function.
459  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
460  * their contents are updated in this function.
461  *
462  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
463  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
464  * to have more control. Don't use both.
465  *
466  * @param dev the ffado device
467  * @return  -1 on error.
468  */
469  
470 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
471
472 /**
473  * Transfer & encode the events from the sample buffers to the packet buffer
474  *
475  * This should be called after the wait call returns, after writing the sample buffers
476  * with ffado_streaming_write.
477  *
478  * If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers
479  * their contents should be valid before calling this function.
480  *
481  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
482  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
483  * to have more control. Don't use both.
484  *
485  * @param dev the ffado device
486  * @return  -1 on error.
487  */
488  
489 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
490
491 /**
492  * Transfer & decode the events from the packet buffer to the sample buffers
493  *
494  * This should be called after the wait call returns, before reading the sample buffers
495  * with ffado_streaming_read.
496  *
497  * If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers
498  * their contents are updated in this function.
499  *
500  * Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use
501  * ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers
502  * to have more control. Don't use both.
503  *
504  * @param dev the ffado device
505  * @return  -1 on error.
506  */
507
508 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
509
510 #ifdef __cplusplus
511 }
512 #endif
513
514 #endif /* FFADO_STREAMING */
Note: See TracBrowser for help on using the browser.