TRBaseDriver.h

Go to the documentation of this file.

/* This file is part of the Transient Recorder Framework.
 * It is subject to the license terms in the LICENSE.txt file found in the
 * top-level directory of this distribution and at
 * https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html. No part
 * of the Transient Recorder Framework, including this file, may be copied,
 * modified, propagated, or distributed except according to the terms
 * contained in the LICENSE.txt file.
 */

#ifndef TRANSREC_BASE_DRIVER_H
#define TRANSREC_BASE_DRIVER_H

#include <stddef.h>

#include <vector>

#include <epicsEvent.h>
#include <epicsMutex.h>
#include <epicsTime.h>
#include <epicsMemory.h>

#include <asynPortDriver.h>

#include "TRArmInfo.h"
#include "TRBaseConfig.h"
#include "TRBurstMetaInfo.h"
#include "TRChannelDataSubmit.h"
#include "TRChannelsDriver.h"
#include "TRConfigParam.h"
#include "TRNonCopyable.h"
#include "TRTimeArrayDriver.h"

class TRBaseDriver : public asynPortDriver,
    private TRNonCopyable
{
    template <typename, typename>
    friend class TRConfigParam;
    
    friend class TRChannelsDriver;
    friend class TRChannelDataSubmit;

public:
    TRBaseDriver (TRBaseConfig const &cfg);
    
    template <typename ValueType, typename EffectiveValueType>
    inline void initConfigParam (TRConfigParam<ValueType, EffectiveValueType> &param,
        char const *base_name, EffectiveValueType invalid_value = EffectiveValueType())
    {
        param.init(this, base_name, invalid_value, false);
    }
    
    template <typename ValueType, typename EffectiveValueType>
    inline void initInternalParam (TRConfigParam<ValueType, EffectiveValueType> &param,
        char const *base_name, EffectiveValueType invalid_value = EffectiveValueType())
    {
        param.init(this, base_name, invalid_value, true);
    }
    
    void completeInit ();
    
    inline TRChannelsDriver & getChannelsDriver ()
    {
        return *m_channels_driver;
    }
    
    void setDigitizerName (char const *name);
    
    double getRequestedSampleRate ();
    
    void setAchievableSampleRate (double value);
    
    inline int getNumBurstsSnapshot ()
    {
        return m_param_num_bursts.getSnapshot();
    }
    
    inline int getNumPostSamplesSnapshot ()
    {
        return m_param_num_post_samples.getSnapshot();
    }
    
    inline int getNumPrePostSamplesSnapshot ()
    {
        return m_param_num_pre_post_samples.getSnapshot();
    }
    
    inline double getRequestedSampleRateSnapshot ()
    {
        return m_param_requested_sample_rate.getSnapshot();
    }
    
    inline double getAchievableSampleRateSnapshot ()
    {
        return m_param_achievable_sample_rate.getSnapshot();
    }
    
    void requestDisarmingFromDriver ();
    
    void publishBurstMetaInfo (TRBurstMetaInfo const &info);
    
    void maybeSleepForTesting ();
    
    bool isArmed ();
    
protected:
    virtual TRChannelsDriver * createChannelsDriver ();
    
    virtual void requestedSampleRateChanged ();
    
    virtual bool waitForPreconditions ();
    
    virtual bool checkSettings (TRArmInfo &arm_info) = 0;
    
    virtual bool startAcquisition (bool overflow) = 0;

    virtual bool readBurst ();

    virtual bool checkOverflow (bool *had_overflow, int *num_buffer_bursts);
    
    virtual bool processBurstData ();
    
    virtual void interruptReading ();
    
    virtual void stopAcquisition () = 0;
    
    virtual void onDisarmed ();
    
public:
    virtual asynStatus writeInt32 (asynUser *pasynUser, epicsInt32 value);
    
    virtual asynStatus writeFloat64 (asynUser *pasynUser, epicsFloat64 value);
    
private:
    // Enumeration of asyn parameters of this class, excluding
    // those managed by TRConfigParam.
    enum Params {
        ARM_REQUEST,
        ARM_STATE,
        EFFECTIVE_SAMPLE_RATE,
        BURST_ID,
        BURST_TIME_BURST,
        BURST_TIME_READ,
        BURST_TIME_PROCESS,
        SLEEP_AFTER_BURST,
        DIGITIZER_NAME,
        TIME_ARRAY_UNIT_INV,
        NUM_BASE_ASYN_PARAMS
    };

    // Possible arm states
    enum ArmState {
        ArmStateDisarm,
        ArmStatePostTrigger,
        ArmStatePrePostTrigger,
        ArmStateBusy,
        ArmStateError
    };
    
private:
    // Number of channels supported (as passed to constructor).
    int m_num_channels;
    
    // Whether the driver supports pre-samples.
    bool m_supports_pre_samples;
    
    // Whether copies of submitted NDArrays are kept in the TRChannelsDriver
    // (initial value only used by TRChannelsDriver constructor).
    bool m_update_arrays;

    // Flag whether completeInit has been called.
    bool m_init_completed;
    
    // Whether we allow data to be submitted.
    bool m_allowing_data;
    
    // Parameters remembered for the TRChannelsDriver constructor.
    int m_max_ad_buffers;
    size_t m_max_ad_memory;
    
    // Total number of configuration parameters.
    int m_num_config_params;

    // Array of framework-managed asyn params' indices
    int m_asyn_params[NUM_BASE_ASYN_PARAMS];

    // Every config parameter is added to this list.
    std::vector<TRConfigParamBase *> m_config_params;
    
    // List of asyn parameter IDs which are not allowed to be modified.
    std::vector<int> m_protected_params;

    // Base configuration perameters.
    // NOTE: Update NumBaseConfigParams below on every change!
    // There doesn't seem to be a nice way to avoid having to manually
    // maintain the parameter count, so long as the parameters are
    // defined like this as members of the class.
    TRConfigParam<int, double> m_param_num_bursts;
    TRConfigParam<int, double> m_param_num_post_samples;
    TRConfigParam<int, double> m_param_num_pre_post_samples;
    TRConfigParam<double>      m_param_requested_sample_rate;
    TRConfigParam<double>      m_param_achievable_sample_rate;
    static int const NumBaseConfigParams = 5;
    
    // Arm state maintained internally.
    ArmState m_arm_state;
    
    // A simplified armed state useful for drivers.
    bool m_armed;
    
    // When arming, the requested arm state (ArmStatePostTrigger or ArmStatePrePostTrigger).
    ArmState m_requested_arm_state;

    // This flag is set to true when disarming is requested.
    bool m_disarm_requested;
    
    // This flag indicates whether a new arming has been requested
    // during an existing arming, that is we need to re-start arming
    // after disarming.
    ArmState m_requested_rearm_state;
    
    // This flag indicates whether we are inside the read loop.
    bool m_in_read_loop;
    
    // Sample rate for display (time array and NDArrray attributes).
    // This is set during arming to the value provided by checkSettings.
    double m_rate_for_display;
    
    // This event is raised from handleArmRequest to the
    // read_thread in order to start the arming.
    epicsEvent m_start_arming_event;
    
    // This event is raised from handleArmRequest to the
    // read_thread to allow disarming to proceed after an error,
    // and also to allow the default readBurst to wait until
    // disarming is requested.
    epicsEvent m_disarm_requested_event;
    
    // AreaDetector port for the channel data.
    epics_auto_ptr<TRChannelsDriver> m_channels_driver;
    
    // Asyn port for the time array.
    TRTimeArrayDriver m_time_array_driver;

private:
    // Add this parameter index to m_protected_params.
    void addProtectedParam (int param);
    
    // Cheks is a parameter is allowed to be written and prints an error if not.
    bool checkProtectedParamWrite (int param);
    
    // Called from writeInt32 when ARM_REQUEST is being written.
    asynStatus handleArmRequest (int armRequest);
    
    // Starts arming, must be currently locked and in ArmStateDisarm.
    void startArming (ArmState requested_arm_state);
    
    // Requests disarming, must be currently locked and not in ArmStateDisarm.
    void requestDisarming (ArmState requested_rearm_state);
    
    // Waits until disarming is reqested.
    void waitUntilDisarming ();
    
    // Read thread.
    static void readThreadTrampoline (void *obj);
    void readThread ();
    
    // One iteration of the read thread (one arming and disarming).
    void readThreadIteration ();
    
    // Set effective-value parameters, during arming.
    void setEffectiveParams ();
    
    // Clear effective-value parameters, during disarming.
    void clearEffectiveParams ();
    
    // Calls the given function on all configuration parameters.
    void processConfigParams (void (TRConfigParamBase::*func) ());
    
    // Sets m_arm_state and updates the asyn parameter.
    void setArmState (ArmState armState);
    
    // Reads the m_stop_requested, locking and unlocking the port.
    bool checkDisarmRequestedUnlocked ();
    
    // Check basic settings before proceeding with arming.
    bool checkBasicSettings ();
    
    // Check values provided by checkSettings in TRArmInfo.
    bool checkArmInfo (TRArmInfo const &arm_info);
    
    // Sets up the time array based on snapshot settings and m_rate_for_display.
    void setupTimeArray (TRArmInfo const &arm_info);
};

#endif