root/trunk/libffado/src/ffadodevice.h

Revision 2732, 15.5 kB (checked in by jwoithe, 3 years ago)

Fix typos throughout the source tree.

Rectify some long-lived typos in strings throughout the source code. in the
FFADO desktop file. This benefits Debian and possibly others. Patch by
Nicolas Boulenguez for Debian and provided to FFADO by Benoit Delcour via
the ffado-user mailing list.

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 "libutil/PosixMutex.h"
30
31 #include "libcontrol/BasicElements.h"
32
33 #include "libieee1394/vendor_model_ids.h"
34
35 #include <memory>
36 #include <vector>
37 #include <string>
38
39 // Prefer shared_ptr over auto_ptr if it is available
40 #if __cplusplus >= 201103L
41 #define ffado_smartptr std::shared_ptr
42 #else
43 #define ffado_smartptr std::auto_ptr
44 #endif
45
46 class DeviceManager;
47 class ConfigRom;
48 class Ieee1394Service;
49
50 namespace Streaming {
51     class StreamProcessor;
52 }
53
54 namespace Control {
55     class Container;
56 }
57
58 /*!
59 @brief Base class for device support
60
61  This class should be subclassed to implement ffado support
62  for a specific device.
63
64 */
65 class FFADODevice
66     : public Util::OptionContainer,
67       public Control::Container
68 {
69 public:
70     FFADODevice( DeviceManager&, ffado_smartptr< ConfigRom >( configRom ) );
71
72     virtual ~FFADODevice();
73
74     /**
75      * @brief Compares the GUID of two FFADODevices
76      *
77      * This function compares the GUID of two FFADODevices and returns true
78      * if the GUID of a is larger than the GUID of b . This is intended to be
79      * used with the STL sort() algorithm.
80      *
81      * Note that GUID's are converted to integers for this.
82      *
83      * @param a pointer to first FFADODevice
84      * @param b pointer to second FFADODevice
85      *
86      * @returns true if the GUID of a is larger than the GUID of b .
87      */
88     static bool compareGUID( FFADODevice *a, FFADODevice *b );
89
90     /// Returns the 1394 service of the FFADO device
91     virtual Ieee1394Service& get1394Service();
92     /// Returns the ConfigRom object of the device node.
93     virtual ConfigRom& getConfigRom() const;
94
95     /**
96      * @brief Called by DeviceManager to load device model from cache.
97      *
98      * This function is called before discover in order to speed up
99      * system initializing.
100      *
101      * @returns true if device was cached and successfully loaded from cache
102      */
103     virtual bool loadFromCache();
104
105     /**
106      * @brief Called by DeviceManager to allow device driver to save a cache version
107      * of the current configuration.
108      *
109      * @returns true if caching was successful. False doesn't mean an error just,
110      * the driver was unable to store the configuration
111      */
112     virtual bool saveCache();
113
114     /**
115      * @brief Called by DeviceManager to check whether a device requires rediscovery
116      *
117      * This function is called to figure out if the device has to be rediscovered
118      * e.g. after a bus reset where the device internal structure changed.
119      *
120      * @returns true if device requires rediscovery
121      */
122     virtual bool needsRediscovery();
123
124     /**
125      * @brief This is called by the DeviceManager to create an instance of the device
126      *
127      * This function enables the FFADODevice to return a subclass of itself should that
128      * be needed. If we don't do this we'd need to know about the subclasses in the
129      * devicemanager, whilst now we don't.
130      *
131      * The function should return an instance of either the class itself or a subclass
132      * of itself.
133      *
134      * This should be overridden in any subclass.
135      *
136      * @return a new instance of the AvDevice type, NULL when unsuccessful
137      */
138     static FFADODevice * createDevice( ffado_smartptr<ConfigRom>( x ));
139
140     /**
141      * @brief This is called by the DeviceManager to discover & configure the device
142      *
143      * @return true if the device was discovered successfully
144      */
145     virtual bool discover() = 0;
146
147     /**
148      * @brief Set the samping frequency
149      * @param samplingFrequency
150      * @return true if successful
151      */
152     virtual bool setSamplingFrequency( int samplingFrequency ) = 0;
153     /**
154      * @brief get the samplingfrequency as an integer
155      * @return the sampling frequency as integer
156      */
157     virtual int getSamplingFrequency( ) = 0;
158
159     /**
160      * @brief Some devices require to update part of their internal configuration on samplerate change
161      *        Most do not, so set default to false
162      * @param oldSamplingFrequency : to be compared to the actual sampling frequency of the device
163      *        note: next, it is thus assumed that the device was actually set to some new sampling frequency
164      *        (while the client did not yet update its view of the device).
165      *        In some future, it might very well appear that restricting to this single argument is
166      *        unsufficient for some devices, so feel free to adapt accordingly.
167      *
168      * @return true if changes have been performed
169      */
170     virtual bool onSamplerateChange( int oldSamplingFrequency ) { return false; }
171
172     /**
173      * @brief get the supported sampling frequencies
174      * @return a vector containing the supported sampling frequencies
175      */
176     virtual std::vector<int> getSupportedSamplingFrequencies( ) = 0;
177
178     /**
179      * @brief sync state enum
180      */
181     enum eSyncState {
182         eSS_Unknown=0,
183         eSS_Locked=1,
184         eSS_Unlocked=2,
185     };
186
187     /**
188      * @brief gets the devices current synchronization state
189      * @return the device's sync state
190      */
191     virtual enum eSyncState getSyncState( );
192
193     /**
194      * @brief clock source types
195      */
196     enum eClockSourceType {
197         eCT_Invalid,   ///> invalid entry (e.g. on error)
198         eCT_Auto,      ///> automatically select clock source
199         eCT_Internal,  ///> internal sync (unspecified)
200         eCT_1394Bus,   ///> Sync on the 1394 bus clock (e.g. CSP)
201         eCT_SytMatch,  ///> SYT match on incoming audio stream
202         eCT_SytStream, ///> SYT match on incoming sync stream
203         eCT_WordClock, ///> SYT on WordClock input
204         eCT_SPDIF,     ///> SYT on SPDIF input
205         eCT_ADAT,      ///> SYT on ADAT input
206         eCT_TDIF,      ///> SYT on TDIF input
207         eCT_AES,       ///> SYT on AES input
208         eCT_SMPTE,     ///> SMPTE clock
209     };
210
211     /**
212      * @brief convert the clock source type to a C string
213      * @return a C string describing the clock source type
214      */
215     static const char *ClockSourceTypeToString(enum eClockSourceType);
216
217     /**
218      * @brief Clock source identification struct
219      */
220     class ClockSource {
221         public:
222         ClockSource()
223             : type( eCT_Invalid )
224             , id( 0 )
225             , valid( false )
226             , active( false )
227             , locked( true )
228             , slipping( false )
229             , description( "" )
230         {};
231         /// indicates the type of the clock source (e.g. eCT_ADAT)
232         enum eClockSourceType type;
233         /// indicated the id of the clock source (e.g. id=1 => clocksource is ADAT_1)
234         unsigned int id;
235         /// is the clock source valid (i.e. can be selected) at this moment?
236         bool valid;
237         /// is the clock source active at this moment?
238         bool active;
239         /// is the clock source locked?
240         bool locked;
241         /// is the clock source slipping?
242         bool slipping;
243         /// description of the clock struct (optional)
244         std::string description;
245        
246         bool operator==(const ClockSource& x) {
247             return (type == x.type) && (id == x.id);
248         }
249     };
250
251     typedef std::vector< ClockSource > ClockSourceVector;
252     typedef std::vector< ClockSource >::iterator ClockSourceVectorIterator;
253
254     /**
255      * @brief Get the clocksources supported by this device
256      *
257      * This function returns a vector of ClockSource structures that contains
258      * one entry for every clock source supported by the device.
259      *
260      * @returns a vector of ClockSource structures
261      */
262     virtual ClockSourceVector getSupportedClockSources() = 0;
263
264
265     /**
266      * @brief Sets the active clock source of this device
267      *
268      * This function sets the clock source of the device.
269      *
270      * @returns true upon success. false upon failure.
271      */
272     virtual bool setActiveClockSource(ClockSource) = 0;
273
274     /**
275      * @brief Returns the active clock source of this device
276      *
277      * This function returns the active clock source of the device.
278      *
279      * @returns the active ClockSource
280      */
281     virtual ClockSource getActiveClockSource() = 0;
282
283     /**
284      * @brief stream states
285      */
286     enum eStreamingState {
287         eSS_Idle = 0,        ///> not streaming
288         eSS_Sending = 1,     ///> the device is sending a stream
289         eSS_Receiving = 2,   ///> the device is receiving a stream
290         eSS_Both = 3,        ///> the device is sending and receiving a stream
291     };
292
293     /**
294      * @brief gets the devices current synchronization state
295      * @return the device's sync state
296      */
297     virtual enum eStreamingState getStreamingState();
298
299     /**
300      * @brief Outputs the device configuration to stderr/stdout [debug helper]
301      *
302      * This function prints out a (detailed) description of the
303      * device detected, and its configuration.
304      */
305     virtual void showDevice();
306
307     /**
308      * @brief Lock the device
309      *
310      * This is called by the streaming layer before we start manipulating
311      * and/or using the device.
312      *
313      * It should implement the mechanisms provided by the device to
314      * make sure that no other controller claims control of the device.
315      *
316      * @return true if successful, false if not
317      */
318     virtual bool lock() = 0;
319
320     /**
321      * @brief Unlock the device
322      *
323      * This is called by the streaming layer after we finish manipulating
324      * and/or using the device.
325      *
326      * It should implement the mechanisms provided by the device to
327      * give up exclusive control of the device.
328      *
329      * @return true if successful, false if not
330      */
331     virtual bool unlock() = 0;
332
333     /**
334      * @brief Enable streaming on all 'started' streams
335      *
336      * Enables the ISO streaming on all streams that are 'started'
337      * using startStreamByIndex. This is useful to control a 'master enable'
338      * function on the device.
339      *
340      * @return true if successful
341      */
342     virtual bool enableStreaming();
343
344     /**
345      * @brief Disable streaming on all streams
346      *
347      * Disables ISO streaming on all streams.
348      * This is useful to control a 'master enable'
349      * function on the device.
350      *
351      * @return true if successful
352      */
353     virtual bool disableStreaming();
354
355     /**
356      * @brief Prepare the device
357      *
358      * This is called by the streaming layer after the configuration
359      * parameters (e.g. sample rate) are set, and before
360      * getStreamProcessor[*] functions are called.
361      *
362      * It should be used to prepare the device's streamprocessors
363      * based upon the device's current configuration. Normally
364      * the streaming layer will not change the device's configuration
365      * after calling this function.
366      *
367      * @return true if successful, false if not
368      */
369     virtual bool prepare() = 0;
370
371     /**
372      * @brief Performs operations needed to prepare for a stream start
373      *
374      * This is called by the streaming layer just before streaming is
375      * started.  It provides a place where reset activity can be done which
376      * ensures the object is ready to restart streaming even if streaming
377      * has been previously started and stopped.
378      *
379      * @return true if successful, false if not
380      */
381     virtual bool resetForStreaming() { return true; }
382
383     /**
384      * @brief Returns the number of ISO streams implemented/used by this device
385      *
386      * Most likely this is 2 streams, i.e. one transmit stream and one
387      * receive stream. However there are devices that implement more, for
388      * example BeBoB's implement 4 streams:
389      * - 2 audio streams (1 xmit/1 recv)
390      * - 2 sync streams (1 xmit/1 recv), which are an optional sync source
391      *   for the device.
392      *
393      * @note you have to have a StreamProcessor for every stream. I.e.
394      *       getStreamProcessorByIndex(i) should return a valid StreamProcessor
395      *       for i=0 to i=getStreamCount()-1
396      *
397      * @return number of streams available (both transmit and receive)
398      */
399     virtual int getStreamCount() = 0;
400
401     /**
402      * @brief Returns the StreamProcessor object for the stream with index i
403      *
404      * @note a streamprocessor returned by getStreamProcessorByIndex(i)
405      *       cannot be the same object as one returned by
406      *       getStreamProcessorByIndex(j) if i isn't equal to j
407      * @note you cannot have two streamprocessors handling the same ISO
408      *       channel (on the same port)
409      *
410      * @param i : Stream index (i has to be smaller than getStreamCount())
411      * @return a StreamProcessor object if successful, NULL otherwise
412      */
413     virtual Streaming::StreamProcessor *getStreamProcessorByIndex(int i) = 0;
414
415     /**
416      * @brief starts the stream with index i
417      *
418      * This function is called by the streaming layer when this stream should
419      * be started, i.e. the device should start sending data or should be prepared to
420      * be ready to receive data.
421      *
422      * It returns the channel number that was assigned for this stream.
423      * Channel allocation should be done using the allocation functions provided by the
424      * Ieee1394Service object that is passed in the constructor.
425      *
426      * @param i : Stream index (i has to be smaller than getStreamCount())
427      * @return true if successful, false if not
428      */
429     virtual bool startStreamByIndex(int i) = 0;
430
431     /**
432      * @brief stops the stream with index i
433      *
434      * @param i : Stream index (i has to be smaller than getStreamCount())
435      * @return true if successful, false if not
436      */
437     virtual bool stopStreamByIndex(int i) = 0;
438
439     /**
440      * set verbosity level
441      */
442     virtual void setVerboseLevel(int l);
443
444     /**
445      * @brief return the node id of this device
446      *
447      * @return the node id
448      */
449     int getNodeId();
450
451     /**
452      * @brief return the nick name of this device
453      *
454      * @return string containing the name
455      */
456     virtual std::string getNickname();
457
458     /**
459      * @brief set the nick name of this device
460      * @param name new nickname
461      * @return true if successful
462      */
463     virtual bool setNickname(std::string name);
464
465     /**
466      * @brief return whether the nick name of this device can be changed
467      *
468      * @return true if the nick can be changed
469      */
470     virtual bool canChangeNickname();
471
472     /**
473      * @brief handle a bus reset
474      *
475      * Called whenever a bus reset is detected. Handle everything
476      * that has to be done to cope with a bus reset.
477      *
478      */
479     // FIXME: not virtual?
480     void handleBusReset();
481
482     // the Control::Container functions
483     virtual std::string getName();
484     virtual bool setName( std::string n )
485         { return false; };
486
487     DeviceManager& getDeviceManager()
488         {return m_pDeviceManager;};
489 private:
490     ffado_smartptr<ConfigRom>( m_pConfigRom );
491     DeviceManager& m_pDeviceManager;
492     Control::Container* m_genericContainer;
493 protected:
494     DECLARE_DEBUG_MODULE;
495     Util::PosixMutex m_DeviceMutex;
496 };
497
498 #endif
Note: See TracBrowser for help on using the browser.