libffado/src/ffadodevice.h

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