DigitalPort.hpp

Go to the documentation of this file.

/*
 * This file is part of the DUDS project. It is subject to the BSD-style
 * license terms in the LICENSE file found in the top-level directory of this
 * distribution and at https://github.com/jjackowski/duds/blob/master/LICENSE.
 * No part of DUDS, including this file, may be copied, modified, propagated,
 * or distributed except according to the terms contained in the LICENSE file.
 *
 * Copyright (C) 2017  Jeff Jackowski
 */
#ifndef DIGITALPORT_HPP
#define DIGITALPORT_HPP

#include <duds/hardware/interface/DigitalPinCap.hpp>
#include <duds/hardware/interface/DigitalPinAccessBase.hpp>
#include <condition_variable>
#include <memory>
#include <mutex>

namespace duds { namespace hardware { namespace interface {

class DigitalPinAccess;
class DigitalPinSetAccess;

class DigitalPort :
    boost::noncopyable,
    public std::enable_shared_from_this<DigitalPort>
{
    mutable std::mutex block;
    std::condition_variable pinwait;
    friend DigitalPinAccess;
    friend DigitalPinSetAccess;
protected:
    struct PinEntry {
        // add boost::signals2::signal objects for events
        DigitalPinAccessBase *access;
        DigitalPinConfig conf;
        DigitalPinCap cap;
        PinEntry() : access(nullptr) { }
        PinEntry(const DigitalPinCap::Flags capf, std::uint16_t cur) :
            access(nullptr), cap(capf, cur) { }
        operator bool () const {
            return cap.exists();
        }
        void markNonexistent() {
            cap = NonexistentDigitalPin;
            conf = DigitalPinConfig(DigitalPinConfig::ClearAll());
        }
    };
    typedef std::vector<PinEntry>  PinVector;
    PinVector pins;
private:
    unsigned int idOffset;
    int waiting;
    void shutdownAccessRequests();
    bool areAvailable(const unsigned int *reqpins, std::size_t len);
    void waitForAvailability(
        std::unique_lock<std::mutex> &lock,
        const unsigned int * const reqpins,  // global IDs
        const std::size_t len
    );
    void updateAccess(const DigitalPinAccess &oldAcc, DigitalPinAccess *newAcc);
    void updateAccess(
        const DigitalPinSetAccess &oldAcc,
        DigitalPinSetAccess *newAcc
    );
protected:
    DigitalPort(unsigned int numpins, unsigned int firstid);
    void shutdown();

    /* *  UnimplementedError
     * Adds pins to an already constructed port. The pins will be initialized
     * to an unavailable state to avoid use until after the implementation has
     * prepared the pin data for use.
     * @throw PinExists
     */
    //void addPins(unsigned int maxId);
    /* *  UnimplementedError
     * Removes a pin from the port by changing its data to an unavailable state.
     * This function will block until the pin is not being accessed. Then it
     * will change the pin's state to unavailble. It will not change the size
     * of the vector @a pins.
     */
    //void removePin(unsigned int localPinId);

    const DigitalPinConfig &configRef(unsigned int localPinId) const {
        return pins[localPinId].conf;
    }

    std::vector<DigitalPinCap> capabilities(
        const std::vector<unsigned int> &pvec, bool global
    ) const;
    virtual DigitalPinRejectedConfiguration::Reason proposeConfigImpl(
        unsigned int gid,
        DigitalPinConfig &pconf,
        DigitalPinConfig &iconf
    ) const = 0;
    virtual bool proposeConfigImpl(
        const std::vector<unsigned int> &localPinIds,
        std::vector<DigitalPinConfig> &propConf,
        std::vector<DigitalPinConfig> &initConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const = 0;
    virtual bool proposeFullConfigImpl(
        std::vector<DigitalPinConfig> &propConf,
        std::vector<DigitalPinConfig> &initConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const = 0;

    DigitalPinConfig modifyConfig(
        unsigned int globalPinId,
        const DigitalPinConfig &cfg,
        DigitalPinAccessBase::PortData *pdata
    );
    void modifyFullConfig(
        std::vector<DigitalPinConfig> &propConf,
        std::vector<DigitalPinConfig> &initConf,
        DigitalPinAccessBase::PortData *pdata
    );
    void modifyConfig(
        std::vector<DigitalPinConfig> &cfgs,
        DigitalPinAccessBase::PortData *pdata
    );
    void modifyConfig(
        const std::vector<unsigned int> &pvec,
        std::vector<DigitalPinConfig> &cfgs,
        DigitalPinAccessBase::PortData *pdata
    );
    virtual void configurePort(
        unsigned int localPinId,
        const DigitalPinConfig &cfg,
        DigitalPinAccessBase::PortData *pdata
    ) = 0;
    virtual void configurePort(
        const std::vector<DigitalPinConfig> &cfgs,
        DigitalPinAccessBase::PortData *pdata
    ) = 0;

    std::vector<DigitalPinConfig> configuration(
        const std::vector<unsigned int> &pvec, bool global
    ) const;

    std::vector<DigitalPinConfig> configurationImpl() const;
    bool input(unsigned int gid, DigitalPinAccessBase::PortData *pdata);
    std::vector<bool> input(
        const std::vector<unsigned int> &pvec,
        DigitalPinAccessBase::PortData *pdata
    );
    virtual bool inputImpl(
        unsigned int gid,
        DigitalPinAccessBase::PortData *pdata
    ) = 0;
    virtual std::vector<bool> inputImpl(
        const std::vector<unsigned int> &pvec,
        DigitalPinAccessBase::PortData *pdata
    );
    void output(
        unsigned int gid,
        bool state,
        DigitalPinAccessBase::PortData *pdata
    );
    void output(
        const std::vector<unsigned int> &pvec,
        const std::vector<bool> &state,
        DigitalPinAccessBase::PortData *pdata
    );
    virtual void outputImpl(
        unsigned int lid,
        bool state,
        DigitalPinAccessBase::PortData *pdata
    ) = 0;
    virtual void outputImpl(
        const std::vector<unsigned int> &pvec,
        const std::vector<bool> &state,
        DigitalPinAccessBase::PortData *pdata
    );
    virtual void madeAccess(DigitalPinAccess &acc);
    virtual void madeAccess(DigitalPinSetAccess &acc);
    virtual void retiredAccess(const DigitalPinAccess &acc) noexcept;
    virtual void retiredAccess(const DigitalPinSetAccess &acc) noexcept;
    static DigitalPinAccessBase::PortData &portData(
        const DigitalPinAccessBase &acc
    ) {
        return acc.portdata;
    }
    template <typename T>
    static void portDataPtr(const DigitalPinAccessBase &acc, T **ptr) {
        *ptr = (T*)acc.portdata.pointer;
    }

public:
    virtual ~DigitalPort();
    virtual bool simultaneousOperations() const = 0;
    DigitalPinCap capabilities(unsigned int globalPinId) const;
    std::vector<DigitalPinCap> capabilities() const;
    std::vector<DigitalPinCap> capabilities(
        const std::vector<unsigned int> &pvec
    ) const {
        return capabilities(pvec, true);
    }
    std::vector<DigitalPinCap> capabilitiesLocalIds(
        const std::vector<unsigned int> &pvec
    ) const {
        return capabilities(pvec, false);
    }
    DigitalPinConfig configuration(unsigned int globalPinId) const;
    std::vector<DigitalPinConfig> configuration() const;
    std::vector<DigitalPinConfig> configuration(
        const std::vector<unsigned int> &pvec
    ) const {
        return configuration(pvec, true);
    }
    std::vector<DigitalPinConfig> configurationLocalIds(
        const std::vector<unsigned int> &pvec
    ) const {
        return configuration(pvec, false);
    }
    DigitalPinRejectedConfiguration::Reason proposeConfig(
        unsigned int gid,
        DigitalPinConfig &pconf,
        DigitalPinConfig &iconf
    ) const;
    DigitalPinRejectedConfiguration::Reason proposeConfig(
        unsigned int gid,
        DigitalPinConfig &pconf
    ) const {
        // should these parameters really not be const?
        DigitalPinConfig onc = DigitalPinConfig::OperationNoChange;
        return proposeConfig(gid, pconf, onc);
    }
    bool proposeConfig(
        const std::vector<unsigned int> &globalPinIds,
        std::vector<DigitalPinConfig> &propConf,
        std::vector<DigitalPinConfig> &initConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const;
    bool proposeConfigLocalIds(
        const std::vector<unsigned int> &localPinIds,
        std::vector<DigitalPinConfig> &propConf,
        std::vector<DigitalPinConfig> &initConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const;
    // above with current config for initial
    bool proposeConfig(
        const std::vector<unsigned int> &pins,
        std::vector<DigitalPinConfig> &propConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const {
        std::vector<DigitalPinConfig> initConf;
        return proposeConfig(pins, propConf, initConf, insertReason);
    }
    bool proposeConfigLocalIds(
        const std::vector<unsigned int> &pins,
        std::vector<DigitalPinConfig> &propConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const {
        std::vector<DigitalPinConfig> initConf;
        return proposeConfigLocalIds(pins, propConf, initConf, insertReason);
    }
    bool proposeFullConfig(
        std::vector<DigitalPinConfig> &propConf,
        std::vector<DigitalPinConfig> &initConf,
        std::function<void(DigitalPinRejectedConfiguration::Reason)> insertReason
            = std::function<void(DigitalPinRejectedConfiguration::Reason)>()
    ) const;
    /*
    // (index-idOffset) == pin ID to reconfigure
    template <std::size_t N>
    void configure(DigitalPinConfig (&a)[N]);
    typedef std::initializer_list<DigitalPinConfig>  ConfigList;
    void configure(const ConfigList &cfgs, int start = 0);
    void configure(const std::vector<DigitalPinConfig> &cfgs, int start = 0);
    // use DigitalPinConfig with ID as key
    template <class C>
    void configure(const C &cfgs);
    // configure one pin
    void configure(unsigned int id, const DigitalPinConfig &cfg);
    */
    unsigned int offset() const {
        return idOffset;
    }
    unsigned int localId(unsigned int globalId) const {
        return globalId - idOffset;
    }
    std::vector<unsigned int> localIds(
        const std::vector<unsigned int> &globalIds
    ) const;
    unsigned int globalId(unsigned int localId) const {
        return localId + idOffset;
    }
    std::vector<unsigned int> globalIds(
        const std::vector<unsigned int> &localIds
    ) const;
    unsigned int size() const {
        return pins.size();
    }
    bool exists(unsigned int gid) const;
    /*
     * Obtains a DigitalPin object from the port.
     * @param id   The global pin ID to get.

     @todo  REDO this !!!

     */ /*
    std::shared_ptr<DigitalPin> pin(unsigned int id) const {
        std::lock_guard<duds::general::Spinlock> lock(spin);
        return pins.at(localId(id));
    } */
    virtual bool independentConfig(
        unsigned int gid,
        const DigitalPinConfig &newcfg,
        const DigitalPinConfig &initcfg
    ) const = 0;
    virtual bool independentConfig() const = 0;

    void poll();
    // gets input state & records changes
    void pollInput();
    // calls event signals for changed pins
    void pollSignal();

    // ------------- Update docs -------------
    void access(
        const unsigned int *pins,
        const unsigned int len,
        std::unique_ptr<DigitalPinAccess> *acc
    );
    //  gcc probably won't figure out array length for acc
    template <std::size_t Len>
    void access(
        const unsigned int pins[Len],
        std::unique_ptr<DigitalPinAccess> acc[Len]
    ) {
        access(pins, Len, acc);
    }
    std::unique_ptr<DigitalPinAccess> access(const unsigned int pin);
    /*
     * Obtain access objects to use a set of pins.
     *
     * The access objects to all requested pins are either all obtained, or
     * not obtained. If not all the access objects can be obtained, and no
     * exception is thrown, the calling thread will block and attempt to get
     * the access objects later when they might all be available. Barring an
     * exception or destruction of the PinStore, the thread will continue to
     * block until all the access objects are obtained.
     *
     * @param pins  An array of pin id values. All values must be for pins
     *              already in @a store, and values <B>must not</B> be repeated.
     *              The value @a -1 will be skipped over; the corresponding
     *              object in @a acc will be made using the default constructor.
     * @param len   The length of both the @a acc and @a pins arrays.
     * @param acc   A unique pointer to an array of DigitalPinAccess objects.
     * @pre         @a acc contains one of:
     *                 - An allocated array of default constructed unused
     *                   DigitalPinAccess objects of length @a len.
     *                 - An allocated but uninitialized array long enough for
     *                   @a len DigitalPinAccess objects.
     *                 - An allocated array of destructed DigitalPinAccess
     *                   objects of length @a len.
     *                 - An empty unique pointer.
     * @warning     No check is performed to assure any supplied constructed
     *              access object is not already in use. The object's
     *              @ref DigitalPinAccess::havePin() "havePin()" function
     *              @b must return false. If this condition is not met, some
     *              pins may be considered to be in-use as long as the process
     *              continues to run, much like a memory leak.
     * @post        If @a acc was empty, it will be given an array of length
     *              @a len. If it was not empty, the given array will be used.
     *              If a PinDoesNotExist or ObjectDestructedError exception is
     *              thrown, @a acc will not be modified. Any other exception
     *              may be thrown after @a acc is modified.
     * @throw PinDoesNotExist   A requested pin does not exist within this
     *                          port.
     * @throw ObjectDestructedError  The PinStore object was destructed before the
     *                          request could be fullfilled.
     * @throw PinInUse          A pin was requested twice or more; there is a
     *                          repeated value in @a pins. If thrown, @a acc
     *                          may be modified.
     */ /*
    void access(
        const unsigned int *pins,
        const unsigned int len
        std::unique_ptr<DigitalPinAccess[]> &acc,
    ); */
    void access(
        const unsigned int *pins,
        const unsigned int len,
        DigitalPinAccess *acc
    );
    void access(
        const std::vector<unsigned int> &pins,
        DigitalPinAccess *acc
    ) {
        access(&(pins[0]), pins.size(), acc);
    }

    // had trouble with one length; not sure two will work
    template <std::size_t alen, std::size_t plen>
    void access(const unsigned int pins[plen], DigitalPinAccess acc[alen]) {
        static_assert(alen == plen,
            "The arrays must have the same number of objects.");
        access(pins, alen, acc);
    }
    void access(
        const unsigned int *pins,
        const unsigned int len,
        DigitalPinSetAccess &acc
    );
    void access(
        const unsigned int *begin,
        const unsigned int *end,
        DigitalPinSetAccess &acc
    ) {
        access(begin, end - begin, acc);
    }
    void access(
        const std::vector<unsigned int> &pins,
        DigitalPinSetAccess &acc
    ) {
        access(&(pins[0]), pins.size(), acc);
    }
    std::unique_ptr<DigitalPinSetAccess> access(
        const std::vector<unsigned int> &pins
    );
    // Would need forward iterators, not input iterators, to use the iterators
    // instead of vector. Will traverse range at least twice.
    template <class InputIter>
    void access(
        const InputIter &begin,
        const InputIter &end,
        DigitalPinSetAccess &acc
    ) {
        std::vector<unsigned int> pvec(begin, end);
        access(&(pvec[0]), pvec.size(), acc);
    }

    // ------------- Update above docs -------------

    /*
    Todo:
    Maybe have a function to handle polling for events that can be used
    in place of or in addition to interrupts?
    */

};

typedef boost::error_info<struct Info_DigitalPortAffected, const DigitalPort*>
    DigitalPortAffected;

/*

Why is this here?

inline unsigned int DigitalPinAccess::globalId() const {
    return port->globalId(pid);
}
inline const DigitalPinConfig &DigitalPinAccess::config() const noexcept {
    return port()->configRef(pid);
}

inline void DigitalPinAccess::configure(const DigitalPinConfig &conf) {
    port->configure(pid, conf);
}

inline unsigned int DigitalPinSetAccess::globalId(unsigned int pos) const {
    unsigned int lid = pins.at(pos);
    if (lid == -1) {
        return lid;
    } else {
        return port->globalId(lid);
    }
}

*/

} } }

#endif        //  #ifndef DIGITALPORT_HPP