root/trunk/libffado/src/ffadodevice.h

Revision 739, 13.2 kB (checked in by ppalmers, 13 years ago)

- Adapt the ffado external API (upgrade to v3)

NEEDS NEW JACK BACKEND

- simplify FFADODevice constructor even more
- implement first framework support for supporting multiple adapters.

currently all firewire adapters are scanned for supported devices unless specified otherwise
however attaching devices to separate adapters is not supported. using multiple adapters at
that are connected together might work.

Line 
1 /*
2  * Copyright (C) 2005-2007 by Daniel Wagner
3  * Copyright (C) 2005-2007 by Pieter Palmers
4  *
5  * This file is part of FFADO
6  * FFADO = Free Firewire (pro-)audio drivers for linux
7  *
8  * FFADO is based upon FreeBoB
9  *
10  * This library is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU Lesser General Public
12  * License version 2.1, as published by the Free Software Foundation;
13  *
14  * This library is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17  * Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with this library; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
22  * MA 02110-1301 USA
23  */
24
25 #ifndef FFADODEVICE_H
26 #define FFADODEVICE_H
27
28 #include "libutil/OptionContainer.h"
29 #include "libcontrol/BasicElements.h"
30
31 #include "libieee1394/vendor_model_ids.h"
32
33 #include <vector>
34 #include <string>
35
36 class ConfigRom;
37 class Ieee1394Service;
38
39 namespace Streaming {
40     class StreamProcessor;
41 }
42
43 /*!
44 @brief Base class for device support
45
46  This class should be subclassed to implement ffado support
47  for a specific device.
48
49 */
50 class FFADODevice
51     : public Util::OptionContainer,
52       public Control::Container
53 {
54 public:
55     FFADODevice( std::auto_ptr< ConfigRom >( configRom ) );
56
57     virtual ~FFADODevice();
58
59     /**
60      * @brief Compares the GUID of two FFADODevices
61      *
62      * This function compares the GUID of two FFADODevices and returns true
63      * if the GUID of @ref a is larger than the GUID of @ref b . This is intended
64      * to be used with the STL sort() algorithm.
65      *
66      * Note that GUID's are converted to integers for this.
67      *
68      * @param a pointer to first FFADODevice
69      * @param b pointer to second FFADODevice
70      *
71      * @returns true if the GUID of @ref a is larger than the GUID of @ref b .
72      */
73     static bool compareGUID( FFADODevice *a, FFADODevice *b );
74
75     /// Returns the 1394 service of the FFADO device
76     virtual Ieee1394Service& get1394Service();
77     /// Returns the ConfigRom object of the device node.
78     virtual ConfigRom& getConfigRom() const;
79
80     /**
81      * @brief Called by DeviceManager to load device model from cache.
82      *
83      * This function is called before discover in order to speed up
84      * system initializing.
85      *
86      * @returns true if device was cached and successfully loaded from cache
87      */
88     virtual bool loadFromCache();
89
90     /**
91      * @brief Called by DeviceManager to allow device driver to save a cache version
92      * of the current configuration.
93      *
94      * @returns true if caching was successful. False doesn't mean an error just,
95      * the driver was unable to store the configuration
96      */
97     virtual bool saveCache();
98
99     /**
100      * @brief This is called by the DeviceManager to create an instance of the device
101      *
102      * This function enables the FFADODevice to return a subclass of itself should that
103      * be needed. If we don't do this we'd need to know about the subclasses in the
104      * devicemanager, whilst now we don't.
105      *
106      * The function should return an instance of either the class itself or a subclass
107      * of itself.
108      *
109      * This should be overridden in any subclass.
110      *
111      * @return a new instance of the AvDevice type, NULL when unsuccessful
112      */
113     static FFADODevice * createDevice( std::auto_ptr<ConfigRom>( x ));
114
115     /**
116      * @brief This is called by the DeviceManager to discover & configure the device
117      *
118      * @return true if the device was discovered successfuly
119      */
120     virtual bool discover() = 0;
121
122     /**
123      * @brief Set the samping frequency
124      * @param samplingFrequency
125      * @return true if successful
126      */
127     virtual bool setSamplingFrequency( int samplingFrequency ) = 0;
128     /**
129      * @brief get the samplingfrequency as an integer
130      * @return the sampling frequency as integer
131      */
132     virtual int getSamplingFrequency( ) = 0;
133
134     /**
135      * @brief sync state enum
136      */
137     enum eSyncState {
138         eSS_Unknown=0,
139         eSS_Locked=1,
140         eSS_Unlocked=2,
141     };
142
143     /**
144      * @brief gets the devices current synchronization state
145      * @return the device's sync state
146      */
147     virtual enum eSyncState getSyncState( );
148
149     /**
150      * @brief clock source types
151      */
152     enum eClockSourceType {
153         eCT_Invalid,   ///> invalid entry (e.g. on error)
154         eCT_Internal,  ///> internal sync (unspecified)
155         eCT_1394Bus,   ///> Sync on the 1394 bus clock (e.g. CSP)
156         eCT_SytMatch,  ///> SYT match on incoming audio stream
157         eCT_SytStream, ///> SYT match on incoming sync stream
158         eCT_WordClock, ///> SYT on WordClock input
159         eCT_SPDIF,     ///> SYT on SPDIF input
160         eCT_ADAT,      ///> SYT on ADAT input
161         eCT_TDIF,      ///> SYT on TDIF input
162         eCT_AES,       ///> SYT on AES input
163     };
164
165     /**
166      * @brief convert the clock source type to a C string
167      * @return a C string describing the clock source type
168      */
169     static const char *ClockSourceTypeToString(enum eClockSourceType);
170
171     /**
172      * @brief Clock source identification struct
173      */
174     struct sClockSource {
175         sClockSource()
176             : type( eCT_Invalid )
177             , id( 0 )
178             , valid( false )
179             , active( false )
180             , description( "" )
181         {}
182         /// indicates the type of the clock source (e.g. eCT_ADAT)
183         enum eClockSourceType type;
184         /// indicated the id of the clock source (e.g. id=1 => clocksource is ADAT_1)
185         unsigned int id;
186         /// is the clock source valid at this moment?
187         bool valid;
188         /// is the clock source active at this moment?
189         bool active;
190         /// description of the clock struct (optional)
191         std::string description;
192     };
193     typedef struct sClockSource ClockSource;
194
195     typedef std::vector< ClockSource > ClockSourceVector;
196     typedef std::vector< ClockSource >::iterator ClockSourceVectorIterator;
197
198     /**
199      * @brief Get the clocksources supported by this device
200      *
201      * This function returns a vector of ClockSource structures that contains
202      * one entry for every clock source supported by the device.
203      *
204      * @returns a vector of ClockSource structures
205      */
206     virtual ClockSourceVector getSupportedClockSources() = 0;
207
208
209     /**
210      * @brief Sets the active clock source of this device
211      *
212      * This function sets the clock source of the device.
213      *
214      * @returns true upon success. false upon failure.
215      */
216     virtual bool setActiveClockSource(ClockSource) = 0;
217
218     /**
219      * @brief Returns the active clock source of this device
220      *
221      * This function returns the active clock source of the device.
222      *
223      * @returns the active ClockSource
224      */
225     virtual ClockSource getActiveClockSource() = 0;
226
227     /**
228      * @brief This is called by the device manager to give the device a unique ID.
229      *
230      * The purpose of this is to allow for unique port naming
231      * in case there are multiple identical devices on the bus.
232      * Some audio API's (e.g. jack) don't work properly when the
233      * port names are not unique.
234      *
235      * Say you have two devices having a port named OutputLeft.
236      * This can cause the streaming
237      * part to present two OutputLeft ports to the audio API,
238      * which won't work. This ID will allow you to construct
239      * the port names as 'dev1_OutputLeft' and 'dev2_OutputLeft'
240      *
241      * @note Currently this is a simple integer that is equal to
242      *       the position of the device in the devicemanager's
243      *       device list. Therefore it is dependant on the order
244      *       in which the devices are detected. The side-effect
245      *       of this is that it is dependant on the bus topology
246      *       and history (e.g. busresets etc). This makes that
247      *       these ID's are not fixed to a specific physical device.
248      *       At some point, we will replaced this with a GUID based
249      *       approach, which is tied to a physical device and is
250      *       bus & time independant.
251      *
252      * @param id
253      * @return true if successful
254      */
255     bool setId(unsigned int id);
256
257     /**
258      * @brief Outputs the device configuration to stderr/stdout [debug helper]
259      *
260      * This function prints out a (detailed) description of the
261      * device detected, and its configuration.
262      */
263     virtual void showDevice();
264
265     /**
266      * @brief Lock the device
267      *
268      * This is called by the streaming layer before we start manipulating
269      * and/or using the device.
270      *
271      * It should implement the mechanisms provided by the device to
272      * make sure that no other controller claims control of the device.
273      *
274      * @return true if successful, false if not
275      */
276     virtual bool lock() = 0;
277
278     /**
279      * @brief Unlock the device
280      *
281      * This is called by the streaming layer after we finish manipulating
282      * and/or using the device.
283      *
284      * It should implement the mechanisms provided by the device to
285      * give up exclusive control of the device.
286      *
287      * @return true if successful, false if not
288      */
289     virtual bool unlock() = 0;
290
291     /**
292      * @brief Enable streaming on all 'started' streams
293      *
294      * Enables the ISO streaming on all streams that are 'started'
295      * using startStreamByIndex. This is useful to control a 'master enable'
296      * function on the device.
297      *
298      * @return true if successful
299      */
300     virtual bool enableStreaming();
301
302     /**
303      * @brief Disable streaming on all streams
304      *
305      * Disables ISO streaming on all streams.
306      * This is useful to control a 'master enable'
307      * function on the device.
308      *
309      * @return true if successful
310      */
311     virtual bool disableStreaming();
312
313     /**
314      * @brief Prepare the device
315      *
316      * This is called by the streaming layer after the configuration
317      * parameters (e.g. sample rate) are set, and before
318      * getStreamProcessor[*] functions are called.
319      *
320      * It should be used to prepare the device's streamprocessors
321      * based upon the device's current configuration. Normally
322      * the streaming layer will not change the device's configuration
323      * after calling this function.
324      *
325      * @return true if successful, false if not
326      */
327     virtual bool prepare() = 0;
328
329     /**
330      * @brief Returns the number of ISO streams implemented/used by this device
331      *
332      * Most likely this is 2 streams, i.e. one transmit stream and one
333      * receive stream. However there are devices that implement more, for
334      * example BeBoB's implement 4 streams:
335      * - 2 audio streams (1 xmit/1 recv)
336      * - 2 sync streams (1 xmit/1 recv), which are an optional sync source
337      *   for the device.
338      *
339      * @note you have to have a StreamProcessor for every stream. I.e.
340      *       getStreamProcessorByIndex(i) should return a valid StreamProcessor
341      *       for i=0 to i=getStreamCount()-1
342      *
343      * @return number of streams available (both transmit and receive)
344      */
345     virtual int getStreamCount() = 0;
346
347     /**
348      * @brief Returns the StreamProcessor object for the stream with index i
349      *
350      * @note a streamprocessor returned by getStreamProcessorByIndex(i)
351      *       cannot be the same object as one returned by
352      *       getStreamProcessorByIndex(j) if i isn't equal to j
353      * @note you cannot have two streamprocessors handling the same ISO
354      *       channel (on the same port)
355      *
356      * @param i : Stream index
357      * @pre @ref i smaller than getStreamCount()
358      * @return a StreamProcessor object if successful, NULL otherwise
359      */
360     virtual Streaming::StreamProcessor *getStreamProcessorByIndex(int i) = 0;
361
362     /**
363      * @brief starts the stream with index i
364      *
365      * This function is called by the streaming layer when this stream should
366      * be started, i.e. the device should start sending data or should be prepared to
367      * be ready to receive data.
368      *
369      * It returns the channel number that was assigned for this stream.
370      * Channel allocation should be done using the allocation functions provided by the
371      * Ieee1394Service object that is passed in the constructor.
372      *
373      * @param i : Stream index
374      * @pre @ref i smaller than getStreamCount()
375      * @return true if successful, false if not
376      */
377     virtual bool startStreamByIndex(int i) = 0;
378
379     /**
380      * @brief stops the stream with index @ref i
381      *
382      * @param i : Stream index
383      * @pre @ref i smaller than getStreamCount()
384      * @return true if successful, false if not
385      */
386     virtual bool stopStreamByIndex(int i) = 0;
387
388     /**
389      * set verbosity level
390      */
391     virtual void setVerboseLevel(int l);
392
393     /**
394      * @brief return the node id of this device
395      *
396      * @return the node id
397      */
398     int getNodeId();
399
400     /**
401      * @brief handle a bus reset
402      *
403      * Called whenever a bus reset is detected. Handle everything
404      * that has to be done to cope with a bus reset.
405      *
406      */
407     void handleBusReset();
408
409     // the Control::Container functions
410     virtual std::string getName();
411     virtual bool setName( std::string n )
412         { return false; };
413
414
415 private:
416     std::auto_ptr<ConfigRom>( m_pConfigRom );
417 protected:
418     DECLARE_DEBUG_MODULE;
419 };
420
421 #endif
Note: See TracBrowser for help on using the browser.