root/trunk/libffado/src/ffadodevice.h

Revision 583, 10.3 kB (checked in by ppalmers, 17 years ago)

- Clean up the FFADODevice constructor to remove the nodeid that

can be retrieved from the configrom.

- Implement new method of creating devices: a device is supposed

to implement the createDevice static method that should return
an instance of itself or a subclass of itself. This should ease
support for manufacturer specific customizations since we don't
have to put them into the device manager class.

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