CanTarget.h

[詳解]

/// @file
/// @brief CANボード単体の通信処理を提供するクラス CanTarget のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_CANTARGET_H
#define AMDAEMON_CANTARGET_H

#include "amdaemon/env.h"
#include "amdaemon/CanDef.h"
#include "amdaemon/CanTargetProperty.h"
#include "amdaemon/CanAck.h"
#include "amdaemon/RequestState.h"
#include "amdaemon/util/traits.h"
#include "amdaemon/util/container.h"

#include <algorithm>
#include <type_traits>
#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_can
/// @{

    // 内部クラスの前方宣言
    class InnerIndexHolder;

    /// @brief CANボード単体の通信処理を提供するクラス。
    /// @see CanPort
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// CanPort クラスのメンバ関数 CanPort#getTarget から取得すること。
    ///
    /// @par 送信すべきでない命令コード
    /// メンバ関数 #send を用いて任意の命令コードをリクエスト可能である。
    /// しかし下記コマンドについてはDaemonプロセスの誤動作を招く恐れがあるため
    /// 送信すべきではない。
    /// @par
    /// - 0xFD : ブートモード遷移
    /// - 0xFE : ファーム更新
    /// - 0x10 : ボードリセット
    /// - 0x83 : 自動送信設定(CAN I/O ボード 837-15257)
    /// @par
    /// ボードリセットと自動送信設定についてはDaemonプロセスが必要に応じて送信する。
    /// @par
    /// ファーム更新は非対応である。ファーム更新を実装する必要がある場合は
    /// AM Daemon サポートに相談すること。
    ///
    /// @par 送信する必要のない命令コード
    /// 下記コマンドについてはDaemonプロセスが自動的に送信して情報を取得済みであるため、
    /// わざわざアプリ側で送信する必要はない。
    /// @par
    /// - 0xF0 : ボード品番取得
    /// - 0xF2 : ファーム情報取得
    /// - 0xF3 : カスタムチップ品番取得
    /// @par
    /// これらの情報はメンバ関数 #getProperty によって取得できる。
    ///
    /// @par エミュレータ環境における動作
    /// エミュレータ環境においては、アクノリッジパケットルールが定義されていれば
    /// その定義通りのアクノリッジパケットを返す。
    /// @par
    /// アクノリッジパケットルールが定義されていない命令コードのうち、
    /// 下記の命令コードについては実ボード動作をエミュレートする。
    /// @par
    /// - 0xF0 : ボード品番取得
    /// - 0xF2 : ファーム情報取得
    /// - 0xF3 : カスタムチップ品番取得
    /// - 0xF4 : エラーレポート
    /// - 0x10 : ボードリセット(直近のエラーレポートのリセットのみ行う)
    /// @par
    /// それ以外の命令コードについては非サポートエラーを返す。
    class CanTarget
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        CanTarget(InnerIndexHolder, InnerIndexHolder);

        // 下記は暗黙の定義を用いる。
        //‾CanTarget() = default;

        /// @brief ボード情報を取得する。
        /// @return ボード情報。
        const CanTargetProperty& getProperty() const;

        /// @brief リクエストパケットの送信を要求する。
        /// @param[in] command 命令コード。
        /// @param[in] data パケットデータ。不要ならば nullptr を指定可能。
        /// @param[in] dataSize
        ///     パケットデータサイズ。
        ///     amdaemon::MaxCanPacketDataSize 以下。データが不要ならば 0 。
        /// @param[in] priority
        ///     パケットのプライオリティ値。 0 以上 amdaemon::MaxCanPacketPriority 以下。
        ///     通常は指定を省略し、既定値 amdaemon::DefaultCanPacketPriority を用いること。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// - 引数 data に nullptr を指定した上で引数 dataSize に 0 以外の値を指定した場合。
        /// - 引数 dataSize に amdaemon::MaxCanPacketDataSize より大きい値を指定した場合。
        /// - 引数 priority に amdaemon::MaxCanPacketPriority より大きい値を指定した場合。
        ///
        /// この関数で任意の命令コードをリクエスト可能であるが、
        /// いくつかの命令コードについては呼び出すべきでない等、注意すべき点がある。
        /// 詳しくは CanTarget クラスの説明を参照すること。
        ///
        /// この関数の呼び出しに成功した場合、
        /// 引数 command と同じ命令コードを持つアクノリッジパケット情報が破棄される。
        /// 過去のアクノリッジパケットを今回のリクエストパケットに対するものと
        /// 誤認しないようにこのような挙動となっている。
        ///
        /// この関数を呼び出す度に要求が内部キューに蓄えられ、順次Daemonプロセスへ送られる。
        /// 複数の要求はまとめられ、最大 16 要求まで一度に送信されるが、
        /// あまりに多くの要求を高頻度で行うと送信が追い付かない可能性がある。
        /// 1 フレームあたり最大でも 8 要求程度に留めること。
        ///
        /// 戻り値の要求状態値は、DaemonプロセスがCANポートへリクエストパケットを送信した
        /// 時点で処理完了状態となり、送信処理の成否を確認できるようになる。
        /// コマンド自体の成否を確認できるわけではないことに注意。
        ///
        /// 個々のコマンドの成否は、メンバ関数 #getAck でアクノリッジパケットを取得可能に
        /// なってから、そのメンバ関数 CanAck#isError を用いて確認すること。
        RequestState send(
            std::uint8_t command,
            const void* data,
            std::size_t dataSize,
            std::uint8_t priority = DefaultCanPacketPriority);

        /// @brief リクエストパケットの送信を要求する。
        /// @param[in] command 命令コード。
        /// @param[in] data パケットデータ。
        /// @param[in] dataSize
        ///     パケットデータサイズ。既定値は SIZE_MAX (std::size_t 型の最大値)。
        ///     この値と data.size() のうち小さい方の値が実際のサイズとして利用される。
        /// @param[in] priority
        ///     パケットのプライオリティ値。 0 以上 amdaemon::MaxCanPacketPriority 以下。
        ///     通常は指定を省略し、既定値 amdaemon::DefaultCanPacketPriority を用いること。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// - 引数 dataSize に amdaemon::MaxCanPacketDataSize より大きい値を指定し、
        ///   かつ引数 data の要素数も amdaemon::MaxCanPacketDataSize より大きい場合。
        /// - 引数 priority に amdaemon::MaxCanPacketPriority より大きい値を指定した場合。
        ///
        /// パケットデータを可変長配列型で指定するオーバロード。
        /// 挙動は
        /// send(std::uint8_t, const void*, std::size_t, std::uint8_t)
        /// オーバロードに準ずる。
        RequestState send(
            std::uint8_t command,
            const std::vector<std::uint8_t>& data,
            std::size_t dataSize = SIZE_MAX,
            std::uint8_t priority = DefaultCanPacketPriority)
        {
            return
                this->send(command, data.data(), std::min(dataSize, data.size()), priority);
        }

        /// @brief リクエストパケットの送信を要求する。
        /// @tparam Data パケットデータ型。後述の要件を満たす型でなければならない。
        /// @param[in] command 命令コード。
        /// @param[in] data パケットデータ。
        /// @param[in] dataSize
        ///     パケットデータサイズ。既定値は sizeof(Data) 。
        ///     この値と sizeof(data) のうち小さい方の値が実際のサイズとして利用される。
        /// @param[in] priority
        ///     パケットのプライオリティ値。 0 以上 amdaemon::MaxCanPacketPriority 以下。
        ///     通常は指定を省略し、既定値 amdaemon::DefaultCanPacketPriority を用いること。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// - 引数 dataSize に amdaemon::MaxCanPacketDataSize より大きい値を指定し、
        ///   かつ sizeof(data) も amdaemon::MaxCanPacketDataSize より大きい場合。
        /// - 引数 priority に amdaemon::MaxCanPacketPriority より大きい値を指定した場合。
        ///
        /// パケットデータを任意のデータ型(固定長配列等)で指定するオーバロード。
        /// 挙動は
        /// send(std::uint8_t, const void*, std::size_t, std::uint8_t)
        /// オーバロードに準ずる。
        ///
        /// 型 Data から参照性を取り除いた型(例えば型 Data が int& ならば int)は
        /// 下記の要件をすべて満たす必要がある。
        ///
        /// - オブジェクト型(スカラ型、配列、クラス＆構造体、共用体のいずれか)である。
        /// - トリビアルコピー可能な型である。
        /// - ポインタ型ではない。
        /// - std::nullptr_t 型ではない。
        ///
        /// 要するに、安全に std::memcpy によるコピーが可能な型である必要がある。
        /// 1つでも満たしていない場合はコンパイルエラーとなる。
        template<class Data>
        auto send(
            std::uint8_t command,
            Data&& data,
            std::size_t dataSize = sizeof(Data),
            std::uint8_t priority = DefaultCanPacketPriority)
            ->
            typename std::enable_if<
                ::amdaemon::util::IsBinaryCopyable<
                    typename std::remove_reference<Data>::type>::value,
                RequestState>::type
        {
            return this->send(command, &data, std::min(dataSize, sizeof(data)), priority);
        }

        /// @brief リクエストパケットの送信を要求する。
        /// @param[in] command 命令コード。
        /// @return 要求状態値。
        ///
        /// パケットデータを持たないコマンド用のオーバロード。
        /// 挙動は
        /// send(std::uint8_t, const void*, std::size_t, std::uint8_t)
        /// オーバロードに準ずる。
        ///
        /// パケットのプライオリティ値は amdaemon::DefaultCanPacketPriority 固定となる。
        RequestState send(std::uint8_t command)
        {
            return this->send(command, nullptr, 0);
        }

        /// @brief 直近の送信要求において指定したパケットデータを取得する。
        /// @param[in] command 対象の命令コード。
        /// @param[out] dataSize パケットデータサイズの設定先。不要ならば nullptr 。
        /// @return パケットデータ。一度も送信要求の開始に成功していない場合は nullptr 。
        /// @see send
        ///
        /// 送信要求の開始にさえ成功していれば、送信処理自体の成否は問わない。
        ///
        /// パケットデータを持たないコマンドを送信要求した場合でも、サイズ 0 のデータが返る。
        /// 一度も送信要求の開始に成功していない場合を除き、 nullptr が返ることはない。
        const void* getLastSentData(
            std::uint8_t command,
            std::size_t* dataSize = nullptr) const;

        /// @brief アクノリッジパケット情報を取得する。
        /// @param[in] command 対象の命令コード。
        /// @return アクノリッジパケット情報。
        ///
        /// 引数 command で指定した命令コードを持つアクノリッジパケットを取得する。
        /// 存在しない場合、戻り値のメンバ関数 CanAck#exists が false を返す。
        ///
        /// この関数が返すアクノリッジパケット情報が更新されるタイミングは次の2通りとなる。
        ///
        /// - メンバ関数 #send (オーバロード含む)の呼び出しに成功した時。
        ///     - 同じ命令コードのアクノリッジパケットが存在する場合に破棄する。
        /// - Core クラスのメンバ関数
        ///   Core#execute 呼び出しによってアクノリッジパケットを新しく受け取った時。
        ///     - 同じ命令コードのアクノリッジパケットが存在する場合は上書きする。
        ///
        /// なお、コマンド処理に失敗した場合、CAN通信の仕様により
        /// エラーレポート取得コマンド(命令コード値は amdaemon::CanErrorReportCommand)の
        /// アクノリッジパケットが返ってくるが、
        /// その情報についてもこの関数の戻り値が内包している。
        /// そのためエラーレポート取得コマンドのアクノリッジパケットを監視する必要はない。
        ///
        /// アクノリッジパケットを返さないコマンドの処理に成功した場合、
        /// 通信仕様通り、この関数がアクノリッジパケット情報を返すことはない。
        /// 処理に失敗した場合は他のコマンドと同じくエラーレポート情報を返す。
        const CanAck& getAck(std::uint8_t command) const;

    private:
        std::size_t _portIndex;     ///< ポート定義インデックス。
        std::size_t _targetIndex;   ///< ターゲット定義インデックス。

    private:
        // コピー禁止
        CanTarget(const CanTarget&);            // 宣言のみ
        CanTarget& operator=(const CanTarget&); // 宣言のみ
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_CANTARGET_H