root/trunk/libffado/src/ffadodevice.h

Revision 560, 9.6 kB (checked in by ppalmers, 17 years ago)

- Sort the FFADODevice vector on GUID before assigning device id's

This results in the same device id for identical device setups,
independent of the way they are connected or the node numbers they
have been assigned.

- Sanitized debug message reporting a bit
- Cosmetic changes

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