root/trunk/libffado/src/ffadodevice.h

Revision 967, 13.9 kB (checked in by ppalmers, 16 years ago)

- first attempt at not causing total havoc when devices are removed from the bus.

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