root/trunk/libffado/src/ffadodevice.h

Revision 864, 13.6 kB (checked in by ppalmers, 16 years ago)

update license to GPLv2 or GPLv3 instead of GPLv2 or any later version. Update copyrights to reflect the new year

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