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 |
---|