root/branches/ppalmers-streaming/src/libstreaming/generic/StreamProcessor.h

/*
 * Copyright (C) 2005-2007 by Pieter Palmers
 *
 * This file is part of FFADO
 * FFADO = Free Firewire (pro-)audio drivers for linux
 *
 * FFADO is based upon FreeBoB.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License version 2.1, as published by the Free Software Foundation;
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301 USA
 */

#ifndef __FFADO_STREAMPROCESSOR__
#define __FFADO_STREAMPROCESSOR__

#include "IsoStream.h"
#include "PortManager.h"

#include "libutil/StreamStatistics.h"
#include "libutil/TimestampedBuffer.h"
#include "libutil/OptionContainer.h"

#include "debugmodule/debugmodule.h"

#include <pthread.h>

namespace Streaming {

    class StreamProcessorManager;
/*!
\brief Class providing a generic interface for Stream Processors

 A stream processor multiplexes or demultiplexes an ISO stream into a
 collection of ports. This class should be subclassed, and the relevant
 functions should be overloaded.

*/
class StreamProcessor : public IsoStream,
                        public PortManager,
                        public Util::TimestampedBufferClient,
                        public Util::OptionContainer
{

    friend class StreamProcessorManager; // FIXME: get rid of this

public:
    ///> the streamprocessor type
    enum eProcessorType {
        ePT_Receive,
        ePT_Transmit
    };
    ///> returns the type of the streamprocessor
    virtual enum eProcessorType getType() { return m_processor_type; };
private:
    // this can only be set by the constructor
    enum eProcessorType m_processor_type;
    // pretty printing
    const char *ePTToString(enum eProcessorType);
protected:
    ///> the state the streamprocessor is in
    enum eProcessorState {
        ePS_Invalid,
        ePS_Created,
        // ePS_WaitingToStop, FIXME: this will be needed for the MOTU's
        ePS_Stopped,
        ePS_WaitingForStream,
        ePS_DryRunning,
        ePS_WaitingForStreamEnable,
        ePS_Running,
        ePS_WaitingForStreamDisable,
    };

    ///> set the SP state to a specific value
    void setState(enum eProcessorState);
    ///> get the SP state
    enum eProcessorState getState() {return m_state;};
private:
    enum eProcessorState m_state;
    // state switching
    enum eProcessorState m_next_state;
    unsigned int m_cycle_to_switch_state;
    bool updateState();
    // pretty printing
    const char *ePSToString(enum eProcessorState);

    bool doStop();
    bool doWaitForRunningStream();
    bool doDryRunning();
    bool doWaitForStreamEnable();
    bool doRunning();
    bool doWaitForStreamDisable();

    bool scheduleStateTransition(enum eProcessorState state, uint64_t time_instant);
    bool waitForState(enum eProcessorState state, unsigned int timeout);

public: //--- state stuff
    bool isRunning()
            {return m_state == ePS_Running;};
    bool isDryRunning()
            {return m_state == ePS_DryRunning;};
    bool isStopped()
            {return m_state == ePS_Stopped;};

    // these schedule and wait for the state transition
    bool startDryRunning(int64_t time_to_start_at);
    bool startRunning(int64_t time_to_start_at);
    bool stopDryRunning(int64_t time_to_stop_at);
    bool stopRunning(int64_t time_to_stop_at);

    // these only schedule the transition
    bool scheduleStartDryRunning(int64_t time_to_start_at);
    bool scheduleStartRunning(int64_t time_to_start_at);
    bool scheduleStopDryRunning(int64_t time_to_stop_at);
    bool scheduleStopRunning(int64_t time_to_stop_at);

    // the main difference between init and prepare is that when prepare is called,
    // the SP is registered to a manager (FIXME: can't it be called by the manager?)
    bool init();
    bool prepare();

public: // constructor/destructor
    StreamProcessor(enum eProcessorType type, int port);
    virtual ~StreamProcessor();

public: // the public receive/transmit functions
    // the transmit interface accepts frames and provides packets
    // implement these for a transmit SP
    // leave default for a receive SP

    // the receive interface accepts packets and provides frames
    // these are implemented by the parent SP
    enum raw1394_iso_disposition
        putPacket(unsigned char *data, unsigned int length,
                  unsigned char channel, unsigned char tag, unsigned char sy,
                  unsigned int cycle, unsigned int dropped);

    enum raw1394_iso_disposition
    getPacket(unsigned char *data, unsigned int *length,
                unsigned char *tag, unsigned char *sy,
                int cycle, unsigned int dropped, unsigned int max_length);

    bool getFrames(unsigned int nbframes, int64_t ts); ///< transfer the buffer contents to the client
    bool putFrames(unsigned int nbframes, int64_t ts); ///< transfer the client contents to the buffer

protected: // the helper receive/transmit functions
    enum eChildReturnValue {
        eCRV_OK,
        eCRV_Invalid,
        eCRV_Packet,
        eCRV_EmptyPacket,
        eCRV_XRun,
        eCRV_Again,
    };
    // to be implemented by the children
    // the following methods are to be implemented by receive SP subclasses
    virtual enum eChildReturnValue processPacketHeader(unsigned char *data, unsigned int length,
                                     unsigned char channel, unsigned char tag,
                                     unsigned char sy, unsigned int cycle,
                                     unsigned int dropped)
        {debugWarning("call not allowed\n"); return eCRV_Invalid;};
    virtual enum eChildReturnValue processPacketData(unsigned char *data, unsigned int length,
                                   unsigned char channel, unsigned char tag,
                                   unsigned char sy, unsigned int cycle,
                                   unsigned int dropped)
        {debugWarning("call not allowed\n"); return eCRV_Invalid;};
    virtual bool processReadBlock(char *data, unsigned int nevents, unsigned int offset)
        {debugWarning("call not allowed\n"); return false;};
    virtual bool provideSilenceBlock(unsigned int nevents, unsigned int offset)
        {debugWarning("call not allowed\n"); return false;};

    // the following methods are to be implemented by transmit SP subclasses
    virtual enum eChildReturnValue generatePacketHeader(unsigned char *data, unsigned int *length,
                                      unsigned char *tag, unsigned char *sy,
                                      int cycle, unsigned int dropped,
                                      unsigned int max_length)
        {debugWarning("call not allowed\n"); return eCRV_Invalid;};
    virtual enum eChildReturnValue generatePacketData(unsigned char *data, unsigned int *length,
                                    unsigned char *tag, unsigned char *sy,
                                    int cycle, unsigned int dropped,
                                    unsigned int max_length)
        {debugWarning("call not allowed\n"); return eCRV_Invalid;};
    virtual enum eChildReturnValue generateSilentPacketHeader(unsigned char *data, unsigned int *length,
                                            unsigned char *tag, unsigned char *sy,
                                            int cycle, unsigned int dropped,
                                            unsigned int max_length)
        {debugWarning("call not allowed\n"); return eCRV_Invalid;};
    virtual enum eChildReturnValue generateSilentPacketData(unsigned char *data, unsigned int *length,
                                          unsigned char *tag, unsigned char *sy,
                                          int cycle, unsigned int dropped,
                                          unsigned int max_length)
        {debugWarning("call not allowed\n"); return eCRV_Invalid;};
    virtual bool processWriteBlock(char *data, unsigned int nevents, unsigned int offset)
        {debugWarning("call not allowed\n"); return false;};
    virtual bool transmitSilenceBlock(char *data, unsigned int nevents, unsigned int offset)
        {debugWarning("call not allowed\n"); return false;};

private:
    bool getFramesDry(unsigned int nbframes, int64_t ts);
    bool getFramesWet(unsigned int nbframes, int64_t ts);
    bool putFramesDry(unsigned int nbframes, int64_t ts);
    bool putFramesWet(unsigned int nbframes, int64_t ts);

    bool transferSilence(unsigned int size);

    // move to private?
    bool xrunOccurred() { return m_in_xrun; };

protected: // FIXME: move to private
    uint64_t m_dropped; /// FIXME:debug
    uint64_t m_last_dropped; /// FIXME:debug
    int m_last_good_cycle; /// FIXME:debug
    uint64_t m_last_timestamp; /// last timestamp (in ticks)
    uint64_t m_last_timestamp2; /// last timestamp (in ticks)
    uint64_t m_last_timestamp_at_period_ticks;

//--- data buffering and accounting
public:
    void getBufferHeadTimestamp ( ffado_timestamp_t *ts, signed int *fc )
        {m_data_buffer->getBufferHeadTimestamp(ts, fc);};
    void getBufferTailTimestamp ( ffado_timestamp_t *ts, signed int *fc )
        {m_data_buffer->getBufferTailTimestamp(ts, fc);};

    void setBufferTailTimestamp ( ffado_timestamp_t new_timestamp )
        {m_data_buffer->setBufferTailTimestamp(new_timestamp);};
    void setBufferHeadTimestamp ( ffado_timestamp_t new_timestamp )
        {m_data_buffer->setBufferHeadTimestamp(new_timestamp);};
protected:
    Util::TimestampedBuffer *m_data_buffer;

protected:
    StreamProcessorManager *m_manager;

    // frame counter & sync stuff
    public:
        /**
         * @brief Can this StreamProcessor handle a transfer of nframes frames?
         *
         * this function indicates if the streamprocessor can handle a transfer of
         * nframes frames. It is used to detect underruns-to-be.
         *
         * @param nframes number of frames
         * @return true if the StreamProcessor can handle this amount of frames
         *         false if it can't
         */
        bool canClientTransferFrames(unsigned int nframes);

        /**
         * @brief drop nframes from the internal buffer
         *
         * this function drops nframes from the internal buffers, without any
         * specification on what frames are dropped. Timestamps are not updated.
         *
         * @param nframes number of frames
         * @return true if the operation was successful
         */
        bool dropFrames(unsigned int nframes);

        /**
         * \brief return the time until the next period boundary should be signaled (in microseconds)
         *
         * Return the time until the next period boundary signal. If this StreamProcessor
         * is the current synchronization source, this function is called to
         * determine when a buffer transfer can be made. When this value is
         * smaller than 0, a period boundary is assumed to be crossed, hence a
         * transfer can be made.
         *
         * \return the time in usecs
         */
        int64_t getTimeUntilNextPeriodSignalUsecs();
        /**
         * \brief return the time of the next period boundary (in microseconds)
         *
         * Returns the time of the next period boundary, in microseconds. The
         * goal of this function is to determine the exact point of the period
         * boundary. This is assumed to be the point at which the buffer transfer should
         * take place, meaning that it can be used as a reference timestamp for transmitting
         * StreamProcessors
         *
         * \return the time in usecs
         */
        uint64_t getTimeAtPeriodUsecs();

        /**
         * \brief return the time of the next period boundary (in internal units)
         *
         * The same as getTimeAtPeriodUsecs() but in internal units.
         *
         * @return the time in internal units
         */
        uint64_t getTimeAtPeriod();

        uint64_t getTimeNow(); // FIXME: should disappear


        /**
         * Returns the sync delay. This is the time a syncsource
         * delays a period signal, e.g. to cope with buffering.
         * @return the sync delay
         */
        int getSyncDelay() {return m_sync_delay;};
        /**
         * sets the sync delay
         * @param d sync delay
         */
        void setSyncDelay(int d) {m_sync_delay = d;};

        /**
         * @brief get the maximal frame latency
         *
         * The maximum frame latency is the maximum time that will elapse
         * between the frame being received by the 1394 stack, and the moment this
         * frame is presented to the StreamProcessor. 
         *
         * For transmit SP's this is the maximum time that a frame is requested by
         * the handler ahead of the time the frame is intended to be transmitted.
         *
         * This is useful to figure out how longer than the actual reception time
         * we have to wait before trying to read the frame from the SP.
         *
         * @return maximal frame latency
         */
        int getMaxFrameLatency();

        float getTicksPerFrame();

        int getLastCycle() {return m_last_cycle;};

        int getBufferFill();

        // Child implementation interface
        /**
        * @brief prepare the child SP
        * @return true if successful, false otherwise
        * @pre the m_manager pointer points to a valid manager
        * @post getEventsPerFrame() returns the correct value
        * @post getEventSize() returns the correct value
        * @post getUpdatePeriod() returns the correct value
        * @post processPacketHeader(...) can be called
        * @post processPacketData(...) can be called
        */
        virtual bool prepareChild() = 0;
        /**
         * @brief get the number of events contained in one frame
         * @return the number of events contained in one frame
         */
        virtual unsigned int getEventsPerFrame() = 0;

        /**
         * @brief get the size of one frame in bytes
         * @return the size of one frame in bytes
         */
        virtual unsigned int getEventSize() = 0;

        /**
         * @brief get the nominal number of frames in a packet
         * @return the nominal number of frames in a packet
         */
        virtual unsigned int getNominalFramesPerPacket() = 0;

    protected:
        float m_ticks_per_frame;
        int m_last_cycle;
        int m_sync_delay;
    private:
        bool m_in_xrun;

protected: // SPM related
    void setManager(StreamProcessorManager *manager) {m_manager=manager;};
    void clearManager() {m_manager=NULL;};

public:
    // debug stuff
    virtual void dumpInfo();
    virtual void setVerboseLevel(int l);
    const char *getStateString()
        {return ePSToString(getState());};
    const char *getTypeString()
        {return ePTToString(getType());};
    StreamStatistics m_PacketStat;
    StreamStatistics m_PeriodStat;
    StreamStatistics m_WakeupStat;
    DECLARE_DEBUG_MODULE;
};

}

#endif /* __FFADO_STREAMPROCESSOR__ */