root/trunk/libffado/src/ffadodevice.h

Revision 2803, 15.5 kB (checked in by jwoithe, 1 year ago)

Cosmetic: capitalise "L" in "Linux".

"Linux" is a proper noun so it should start with a capital letter. These
changes are almost all within comments.

This patch was originally proposed by pander on the ffado-devel mailing
list. It has been expanded to cover all similar cases to maintain
consistency throughout the source tree.

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.