root/trunk/libffado/src/ffadodevice.h

Revision 581, 9.7 kB (checked in by ppalmers, 15 years ago)

- First attempt at mixer control (still disfunctional)
- moved vendor specific code in bebob/*

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( 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     // the Control::Container functions
291     virtual std::string getName();
292     virtual bool setName( std::string n )
293         { return false; };
294
295
296 protected:
297     std::auto_ptr<ConfigRom>( m_pConfigRom );
298     Ieee1394Service*          m_p1394Service;
299     int                       m_nodeId;
300
301     DECLARE_DEBUG_MODULE;
302 };
303
304 #endif
Note: See TracBrowser for help on using the browser.