root/trunk/libffado/src/ffadodevice.h

Revision 623, 10.7 kB (checked in by ppalmers, 17 years ago)

introduce getSyncState

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 class ConfigRom;
34 class Ieee1394Service;
35
36 namespace Streaming {
37     class StreamProcessor;
38 }
39
40 /*!
41 @brief Base class for device support
42
43  This class should be subclassed to implement ffado support
44  for a specific device.
45
46 */
47 class FFADODevice
48     : public Util::OptionContainer,
49       public Control::Container
50 {
51 public:
52     FFADODevice( Ieee1394Service& ieee1394service,
53                  std::auto_ptr< ConfigRom >( configRom ) );
54
55     virtual ~FFADODevice() {};
56
57    
58     /**
59      * @brief Compares the GUID of two FFADODevices
60      *
61      * This function compares the GUID of two FFADODevices and returns true
62      * if the GUID of @ref a is larger than the GUID of @ref b . This is intended
63      * to be used with the STL sort() algorithm.
64      *
65      * Note that GUID's are converted to integers for this.
66      *
67      * @param a pointer to first FFADODevice
68      * @param b pointer to second FFADODevice
69      *
70      * @returns true if the GUID of @ref a is larger than the GUID of @ref b .
71      */
72     static bool compareGUID( FFADODevice *a, FFADODevice *b );
73
74     /// Returns the 1394 service of the FFADO device
75     virtual Ieee1394Service& get1394Service()
76         { return *m_p1394Service; };
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( Ieee1394Service& ,
114                                         std::auto_ptr<ConfigRom>( x ));
115
116     /**
117      * @brief This is called by the DeviceManager to discover & configure the device
118      *
119      * @return true if the device was discovered successfuly
120      */
121     virtual bool discover() = 0;
122
123     /**
124      * @brief Set the samping frequency
125      * @param samplingFrequency
126      * @return true if successful
127      */
128     virtual bool setSamplingFrequency( int samplingFrequency ) = 0;
129     /**
130      * @brief get the samplingfrequency as an integer
131      * @return the sampling frequency as integer
132      */
133     virtual int getSamplingFrequency( ) = 0;
134
135     /**
136      * @brief sync state enum
137      */
138     enum eSyncState {
139         eSS_Unknown=0,
140         eSS_Locked=1,
141         eSS_Unlocked=2,
142     };
143
144     /**
145      * @brief gets the devices current synchronization state
146      * @return the device's sync state
147      */
148     virtual enum eSyncState getSyncState( );
149
150     /**
151      * @brief This is called by the device manager to give the device a unique ID.
152      *
153      * The purpose of this is to allow for unique port naming
154      * in case there are multiple identical devices on the bus.
155      * Some audio API's (e.g. jack) don't work properly when the
156      * port names are not unique.
157      *
158      * Say you have two devices having a port named OutputLeft.
159      * This can cause the streaming
160      * part to present two OutputLeft ports to the audio API,
161      * which won't work. This ID will allow you to construct
162      * the port names as 'dev1_OutputLeft' and 'dev2_OutputLeft'
163      *
164      * @note Currently this is a simple integer that is equal to
165      *       the position of the device in the devicemanager's
166      *       device list. Therefore it is dependant on the order
167      *       in which the devices are detected. The side-effect
168      *       of this is that it is dependant on the bus topology
169      *       and history (e.g. busresets etc). This makes that
170      *       these ID's are not fixed to a specific physical device.
171      *       At some point, we will replaced this with a GUID based
172      *       approach, which is tied to a physical device and is
173      *       bus & time independant.
174      *
175      * @param id
176      * @return true if successful
177      */
178     bool setId(unsigned int id);
179
180     /**
181      * @brief Outputs the device configuration to stderr/stdout [debug helper]
182      *
183      * This function prints out a (detailed) description of the
184      * device detected, and its configuration.
185      */
186     virtual void showDevice();
187
188     /**
189      * @brief Lock the device
190      *
191      * This is called by the streaming layer before we start manipulating
192      * and/or using the device.
193      *
194      * It should implement the mechanisms provided by the device to
195      * make sure that no other controller claims control of the device.
196      *
197      * @return true if successful, false if not
198      */
199     virtual bool lock() = 0;
200
201     /**
202      * @brief Unlock the device
203      *
204      * This is called by the streaming layer after we finish manipulating
205      * and/or using the device.
206      *
207      * It should implement the mechanisms provided by the device to
208      * give up exclusive control of the device.
209      *
210      * @return true if successful, false if not
211      */
212     virtual bool unlock() = 0;
213
214     /**
215      * @brief Enable streaming on all 'started' streams
216      *
217      * Enables the ISO streaming on all streams that are 'started'
218      * using startStreamByIndex. This is useful to control a 'master enable'
219      * function on the device.
220      *
221      * @return true if successful
222      */
223     virtual bool enableStreaming();
224
225     /**
226      * @brief Disable streaming on all streams
227      *
228      * Disables ISO streaming on all streams.
229      * This is useful to control a 'master enable'
230      * function on the device.
231      *
232      * @return true if successful
233      */
234     virtual bool disableStreaming();
235
236     /**
237      * @brief Prepare the device
238      *
239      * This is called by the streaming layer after the configuration
240      * parameters (e.g. sample rate) are set, and before
241      * getStreamProcessor[*] functions are called.
242      *
243      * It should be used to prepare the device's streamprocessors
244      * based upon the device's current configuration. Normally
245      * the streaming layer will not change the device's configuration
246      * after calling this function.
247      *
248      * @return true if successful, false if not
249      */
250     virtual bool prepare() = 0;
251
252     /**
253      * @brief Returns the number of ISO streams implemented/used by this device
254      *
255      * Most likely this is 2 streams, i.e. one transmit stream and one
256      * receive stream. However there are devices that implement more, for
257      * example BeBoB's implement 4 streams:
258      * - 2 audio streams (1 xmit/1 recv)
259      * - 2 sync streams (1 xmit/1 recv), which are an optional sync source
260      *   for the device.
261      *
262      * @note you have to have a StreamProcessor for every stream. I.e.
263      *       getStreamProcessorByIndex(i) should return a valid StreamProcessor
264      *       for i=0 to i=getStreamCount()-1
265      *
266      * @return number of streams available (both transmit and receive)
267      */
268     virtual int getStreamCount() = 0;
269
270     /**
271      * @brief Returns the StreamProcessor object for the stream with index i
272      *
273      * @note a streamprocessor returned by getStreamProcessorByIndex(i)
274      *       cannot be the same object as one returned by
275      *       getStreamProcessorByIndex(j) if i isn't equal to j
276      * @note you cannot have two streamprocessors handling the same ISO
277      *       channel (on the same port)
278      *
279      * @param i : Stream index
280      * @pre @ref i smaller than getStreamCount()
281      * @return a StreamProcessor object if successful, NULL otherwise
282      */
283     virtual Streaming::StreamProcessor *getStreamProcessorByIndex(int i) = 0;
284
285     /**
286      * @brief starts the stream with index i
287      *
288      * This function is called by the streaming layer when this stream should
289      * be started, i.e. the device should start sending data or should be prepared to
290      * be ready to receive data.
291      *
292      * It returns the channel number that was assigned for this stream.
293      * Channel allocation should be done using the allocation functions provided by the
294      * Ieee1394Service object that is passed in the constructor.
295      *
296      * @param i : Stream index
297      * @pre @ref i smaller than getStreamCount()
298      * @return true if successful, false if not
299      */
300     virtual bool startStreamByIndex(int i) = 0;
301
302     /**
303      * @brief stops the stream with index @ref i
304      *
305      * @param i : Stream index
306      * @pre @ref i smaller than getStreamCount()
307      * @return true if successful, false if not
308      */
309     virtual bool stopStreamByIndex(int i) = 0;
310
311     /**
312      * set verbosity level
313      */
314     virtual void setVerboseLevel(int l);
315
316     /**
317      * @brief return the node id of this device
318      *
319      * @return the node id
320      */
321     int getNodeId();
322
323     // the Control::Container functions
324     virtual std::string getName();
325     virtual bool setName( std::string n )
326         { return false; };
327
328
329 protected:
330     std::auto_ptr<ConfigRom>( m_pConfigRom );
331     Ieee1394Service*          m_p1394Service;
332
333     DECLARE_DEBUG_MODULE;
334 };
335
336 #endif
Note: See TracBrowser for help on using the browser.