root/trunk/libffado/README

Revision 2504, 10.9 kB (checked in by jwoithe, 10 years ago)

README: some initial editting of device status information in preparation for the release of FFADO 2.2

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 FFADO v2.x
2 ==========
3
4 The FFADO project aims to provide a free driver implemenation for FireWire
5 (IEEE1394, iLink) based (semi-) professional audio interfaces. The focus of
6 the project are on audio/music production rather than consumer audio. This
7 means that, although we intend to supported all features at some point,
8 consumer features are considered less important. The most obvious example of
9 a consumer feature is AC3/DTS passthrough support, which is unsupported at
10 the moment.
11
12 This package provides the libffado shared library that provides a unified
13 programming interface to configure and use all supported devices. Currently
14 this library is used by the 'firewire' backends of the jack audio connection
15 kit sound server (jackaudio.org). This backend provides audio and midi support,
16 and is available both in jackd and it's multiprocessor variant jackdmp.
17 (note: At the moment there is no support for ALSA nor for pulseaudio.)
18
19 Access to the device internal configuration (e,g, internal mixer) is exposed
20 using the ffado-dbus-server daemon. This daemon exposes the configurable
21 parameters of all detected devices through DBUS. The ffadomixer application in
22 support/mixer presents a GUI to control these parameters (only for officially
23 supported devices).
24
25 Features
26 --------
27 * 24-bit audio input/output (unlimited number of channels)
28 * supports for all samplerates a device supports
29 * MIDI input/output (unlimited number of channels)
30 * Support for S/PDIF and ADAT/SMUX I/O
31 * Internal mixer and device control support for all officially supported
32   devices (NOTE: no support for internal DSP)
33 * Support for device aggregation (limited to devices on the same bus)
34
35 Device Support
36 --------------
37
38 The devices officially supported are:
39 * ESI Quatafire 610
40 * Terratec Producer Phase 88
41 * Focusrite Saffire (original/white)
42 * Focusrite Saffire Pro10
43 * Focusrite Saffire Pro26
44 * Focusrite Saffire Pro14, Pro24, Pro40
45 * Focusrite Saffire Pro24DSP (audio streaming only, DSP control not available)
46 * ECHO AudioFire2, AudioFire4, AudioFire8, AudioFire12
47 * Mackie Onyx Mixer FireWire expansion
48 * RME Fireface 400, RME Fireface 800
49
50 The 'officially supported' label is only given to devices that fullfil the
51 following:
52 * at least one of the developers has the device
53 * the vendor provides development support (access to information)
54 * the device works
55
56 Through reverse-engineering the following devices will also work:
57 * MOTU Traveler
58 * MOTU 828mkII, MOTU Ultralite, MOTU 896HD, MOTU 8pre, MOTU 4pre
59 * Audio only: MOTU Ultralite mk3, MOTU Traveler mk3, MOTU 896mk3, MOTU 828mk3
60 * Audio only, firewire interface only: MOTU Ultralite mk3 hybrid
61 Note:
62 1) The support for these MOTU devices is based on a significant reverse
63    engineering effort.  This means that the developers had no support from
64    the device vendor, and this of course limits the extent to which problems
65    can be solved.  You have been warned.  Please do not buy devices for
66    which support is based upon reverse engineering, nor from vendors that
67    are Linux-hostile (e.g.  MOTU).  Value the support that some vendors
68    provide and buy their stuff.  Check ffado.org for details.  It can't be
69    said enough: currently it is extremely unwise to buy a MOTU device if you
70    intend to use Linux.
71 2) "Audio only" means that FFADO can be used to stream audio to and from the
72    device, control sample rate and clock source.  Control of the mixer
73    and DSP functions is not presently supported.  It is planned but no ETA
74    is available at this stage.
75
76 The FFADO driver is written to provide generic support for all devices it
77 might be able to handle.  This means that most devices based on the BridgeCo
78 BeBoB, the ECHO FireWorks platform or the TC Electronics DICE platform will
79 work, at least to a certain extent.
80
81 Devices for which work is in progress:
82 * RME UFX and UCX firewire devices
83
84 Devices that have been reported to (partially) work with the generic support:
85 * Presonus FireBox
86 * Presonus FirePod / FP10
87 * Alesis io14
88 * TC Konnekt 8, Konnekt 24D, Konnekt Live
89
90 Usupported devices:
91 * Presonus FireStation
92 * Presonus FireStudio (all variants)
93 * Other TC Konnekt devices
94 * Other Alesis devices
95 * Metric Halo devices
96
97 We constantly try to persuade vendors to help us extend our device support.
98
99 Dependencies
100 ------------
101
102 To build libffado you need several libraries. For all libraries a
103 version is provided which is a 'known good' version.  The first few
104 libraries it seems it is not necessary that the version must
105 match. The chances that it works also with an older versions are good:
106
107 libxml++2   (>= 2.6.13)
108
109 These libraries here should be at least the version listed:
110
111 libraw1394  (>= 2.0.7),  https://ieee1394.wiki.kernel.org/
112 libiec61883 (>= 1.1.0),  https://ieee1394.wiki.kernel.org/
113 dbus-1      (>= 1.0),    http://dbus.freedesktop.org
114 dbus-c++    (>= 0),      http://sourceforge.net/apps/mediawiki/dbus-cplusplus/
115 libconfig   (>= 0),      http://www.hyperrealm.com/libconfig/
116
117 Currently only the jackd audio server is supported:
118   jackd (>= 0.109.12), http://jackaudio.org
119
120 While jack1 0.109.12 will work, jack1 >= 0.122.0 or jack2 >= 1.9.9 are
121 recommended if support for jack's setbufsize functionality is desired.
122 [NOTE: at the time of writing, jack1 0.122.0 and jack2 1.9.9 are the
123 development (SVN) versions.]
124
125 Optionally, but recommended is that you install qjackctl:
126
127 qjackctl (>= 0.2.20.10), http://sourceforge.net/projects/qjackctl
128
129 To build the optional ffado device mixer control utility you also require:
130
131 Qt  >= 4.0,            http://qt-project.org/
132 SIP >= 4.7.0,          http://www.riverbankcomputing.co.uk/software/sip/intro
133 PyQt (note below),     http://www.riverbankcomputing.co.uk/software/pyqt/intro
134 dbus-python >= 0.82.0, http://dbus.freedesktop.org/releases/dbus-python/
135
136 The version of PyQt must be chosen to exactly match the version of Qt in use.
137 For Qt 4.x use PyQt 4.x.
138
139 SIP is only required to compile PyQt.  If using a binary package of PyQt
140 SIP should not be needed.
141
142 How to build
143 ------------
144
145 If you want to build the release version you can simply do following:
146
147 $ scons
148 $ scons install
149
150 If you want some debug information (because something seems not
151 to work correctly) you can try to do following:
152
153 $ scons DEBUG=yes
154 $ scons install
155
156 More extended instructions can be found here:
157 http://subversion.ffado.org/wiki/CompilationGuides
158
159 NOTE: In order to build jackd with ffado support, you have
160 to install libffado before you build jackd. The backend to use in jackd is
161 firewire.
162
163 NOTE: the beta versions are distributed with debugging enabled by default.
164
165 DISTRIBUTION PACKAGERS NOTE: Please do not enable support for devices
166 if it is not on by default. If device support for a specific device
167 is not turned on by default by the developers, it means that it is not
168 ready yet. Most of the time it is placeholder code for future devices.
169
170 Running jackd
171 -------------
172
173 The easiest way to run this is using qjackctl. There are only minor
174 differences with the other backends, however you should change some
175 of the default values:
176 - It is recommended to change the 'periods/buffer' field to 3, especially
177   if you use low period sizes (=< 128)
178 - It is recommended to raise the RT priority to 70.
179
180 In order to get it running from the command line, you need to provide some
181 arguments to jackd.
182
183 Run
184
185 $ jackd -d firewire --help
186
187 to see the backend options. You can easily figure out how to set them using
188 the remarks given above (for qjackctl).
189
190 For the other aspects of jackd usage, consult the jackd documentation.
191
192 Here is a sample session (without realtime support enabled):
193
194     $ jackd -d firewire
195     no message buffer overruns
196     jackd 0.111.0
197     Copyright 2001-2005 Paul Davis and others.
198     jackd comes with ABSOLUTELY NO WARRANTY
199     This is free software, and you are welcome to redistribute it
200     under certain conditions; see the file COPYING for details
201    
202     JACK compiled with System V SHM support.
203     loading driver ..
204     3106528665:  (ffado.cpp)[  99] ffado_streaming_init: libffado 1.999.20 built Apr 26 2008 20:26:32
205     libiec61883 warning: Established connection on channel 0.
206     You may need to manually set the channel on the receiving node.
207     libiec61883 warning: Established connection on channel 1.
208     You may need to manually set the channel on the transmitting node.
209
210 (Note: you can safely ignore the libiec61883 warnings, they are normal.)
211
212 An important remark is that for good performance, one should always run jack
213 with the -R flag to enable realtime scheduling for critical threads:
214     $ jackd -R -d firewire
215
216 In case of problems
217 -------------------
218
219 First of all, check whether your problem is in fact a problem, and
220 whether it is a FFADO problem. The magic tool for this is google.
221
222 User support is a rather annoying occupation, especially since it sucks
223 time from developers that are not paid for developing, let alone for doing
224 user support. Please make sure that you have checked the following places:
225     http://www.ffado.org/
226     http://subversion.ffado.org/
227     http://www.google.com/
228       (the terms "ffado-devel" "ffado-user" or "freebob-user" work great)
229 Some might consider this a bit arrogant or "newbie-unfriendly", but personally
230 I (Pieter Palmers) consider this a matter of politeness towards the developers.
231
232 If you have tried to find a solution to your problem, but you couldn't find
233 one or are confused, don't hesitate to ask for help. The preferred way is by
234 signing up to the mailing list as described on http://www.ffado.org/?q=contact.
235
236 Writing a bug report
237 --------------------
238
239 Note that the more effort you put in your bug report, the more effort we
240 will put into helping you.
241
242 Make sure you have compiled a DEBUG=yes version of
243 libffado. If not there is no way we can trace the problem.
244
245 When reporting a problem, please run jackd with the --verbose option,
246 and add the -v6 option to the firewire backend:
247     $ jackd --verbose [...] -d firewire -v6 [...]
248
249     ( [...] = other options )
250
251 This will generate an increadible amount of debug output that should
252 contain what we need to track down the problem. If you have troubles
253 saving the output, try redirecting it to a file:
254
255     $ jackd --verbose -d firewire -v6 2> ffado-jack.log
256
257 this will create a ffado.log file containing the output. Use CTRL-C
258 to exit jack if necessary.
259
260 The distribution contains a tool to gather some information about your
261 system. you can run it as follows:
262
263     $ cd support/tools
264     $ python ffado-diag.py > ffado-diag.log
265
266 It will check your system for basic problems and gather some information
267 regarding your hardware configuration. This will allow us to diagnose
268 your problem faster.
269
270 Once the logs have been created you can create a support ticket at
271 http://subversion.ffado.org/newticket
272
273 Be sure to include the following information:
274 * the log file(s) (zipped/tar.gz'ed and attached)
275 * the device you're trying to use
276 * a description of what went wrong and how to reproduce it. You
277   preferrably try to figure out a sequence of steps that can reliably
278   reproduce the issue on your system. A one-time failure is very difficult
279   to diagnose and/or fix.
280 * the distribution and its version
Note: See TracBrowser for help on using the browser.