488 lines
22 KiB
C++
488 lines
22 KiB
C++
/*!
|
|
* \file utils/sequencer.h
|
|
* \brief
|
|
* A terminal-like device communication automation tool
|
|
*
|
|
* \copyright Copyright (C) 2021 Christos Choutouridis <christos@choutouridis.net>
|
|
*
|
|
* <dl class=\"section copyright\"><dt>License</dt><dd>
|
|
* The MIT License (MIT)
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in all
|
|
* copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
* SOFTWARE.
|
|
* </dd></dl>
|
|
*/
|
|
|
|
#ifndef TBX_UTILS_SEQUENCER_H_
|
|
#define TBX_UTILS_SEQUENCER_H_
|
|
|
|
|
|
#include <core/core.h>
|
|
#include <core/crtp.h>
|
|
#include <cont/range.h>
|
|
|
|
#include <ctime>
|
|
#include <array>
|
|
#include <string_view>
|
|
#include <type_traits>
|
|
#include <utility>
|
|
#include <tuple>
|
|
|
|
namespace tbx {
|
|
|
|
/*!
|
|
* \class sequencer
|
|
* \brief
|
|
* A CRTP base class to provide the sequencer functionality.
|
|
*
|
|
* Sequencer is a script engine with receive/transmit functionalities based on predicates. It has:
|
|
* - A program counter like variable named \c step.
|
|
* - \c step actions like NEXT, GOTO exit with status etc...
|
|
* - Input data match predicates to trigger those actions.
|
|
* - Input data handlers to trigger external functionality on predicate match
|
|
* - Output data handlers to "edit" data before transmiting them
|
|
* - A small predicate set provided to the user. (starts_with, ends_with, contains).
|
|
*
|
|
* Sequencer can automate communication with a terminal-like device such as AT-command modems, can
|
|
* be used to implement communication protocols, or even small http servers.
|
|
*
|
|
* It can operate based on a script array and handle the outgoing commands and incoming responses.
|
|
* The user can create matching rules on received data and hook handlers and actions on them.
|
|
*
|
|
* The derived class (implementation) has to provide:
|
|
* 1) size_t get(Data_t* data);
|
|
* This function return 0 or a number of Data_t items. The data points to buffer for the input data.
|
|
*
|
|
* 3) size_t contents_ (Data_t* data);
|
|
* This function return 0 or a number of Data_t items without removing them from the implementer's container
|
|
* The data points to buffer for the input data.
|
|
*
|
|
* 2) size_t put(const Data_t* data, size_t n);
|
|
* This function sends to implementation the data pointed by \c data witch have size \c n.
|
|
*
|
|
* 4) clock_t clock();
|
|
* This function return a number to be used as time. The units of this function may be arbitrary but they
|
|
* match the units in \c record_t::timeout field.
|
|
*
|
|
* \tparam Impl_t The type of derived class
|
|
* \tparam Data_t The char-like stream item type. Usually \c char
|
|
* \tparam N The size of the sequence buffer to temporary store each line from get().
|
|
*
|
|
* \note
|
|
* We need access to derived class container to sneaky get a range of the data beside
|
|
* the normal data flow, in order to implement the \see control_t::DETECT operation.
|
|
*/
|
|
template <typename Impl_t, typename Data_t, size_t N>
|
|
class sequencer {
|
|
_CRTP_IMPL(Impl_t);
|
|
|
|
//! \name Public types
|
|
//! @{
|
|
public:
|
|
using value_type = Data_t;
|
|
using pointer_type = Data_t*;
|
|
using size_type = size_t;
|
|
using string_view = std::basic_string_view<Data_t>;
|
|
|
|
/*!
|
|
* The sequencer engine status. A variable of this type is returned by
|
|
* \see action_().
|
|
*/
|
|
enum class seq_status_t {
|
|
CONTINUE, //!< Means we keep looping
|
|
EXIT //!< Means, we exit with status the one indicated by \c action_t of the \c record_t
|
|
};
|
|
|
|
//! \enum control_t
|
|
//! \brief The control type of the script entry.
|
|
enum class control_t {
|
|
NOP, //!< No command, dont send or expect anything, used for delays
|
|
SEND, //!< Send data to implementation through put()
|
|
EXPECT, //!< Expects data from implementation via get()
|
|
OR_EXPECT, //!< Expects data from implementation via get() in conjunction with previous EXPECT
|
|
DETECT, //!< Detects data into rx buffer without receiving them via contents()
|
|
OR_DETECT //!< Detects data into rx buffer without receiving them via contents() in conjunction with
|
|
//!< previous DETECT
|
|
|
|
//! \note
|
|
//! The \c DETECT extra incoming channel serve the purpose of sneak into receive
|
|
//! buffer and check for data without getting them. This is useful when the receive driver
|
|
//! is buffered with a delimiter and we seek for data that don't follow the delimiter pattern.
|
|
//!
|
|
//! For example:
|
|
//! A modem sends responses with '\n' termination but for some "special" command it opens a cursor
|
|
//! lets say ">$ " without '\n' at the end.
|
|
};
|
|
|
|
//! \enum action_t
|
|
//! \brief
|
|
//! Possible response actions for the sequencer. This is the
|
|
//! equivalent of changing the program counter of the sequencer
|
|
//! and is composed by a type and a value.
|
|
//!
|
|
struct action_t {
|
|
enum {
|
|
NO =0, //!< Do not change sequencer's step
|
|
NEXT, //!< Go to next sequencer step. In case of EXPECT/DETECT block of records
|
|
//!< skip the entire block of EXPECT[, OR_EXPECT[, OR_EXPECT ...]] and go
|
|
//!< to the next (non OR_*) control record.
|
|
GOTO, //!< Manually sets the step counter to the number of the \c step member.
|
|
EXIT, //!< Instruct for an exit returning the action.value as status
|
|
} type;
|
|
size_t value; //!< Used by \c GOTO to indicate the next sequencer's step.
|
|
};
|
|
|
|
static constexpr action_t no_action = {action_t::NO, 0};
|
|
static constexpr action_t next = {action_t::NEXT, 0};
|
|
|
|
template <size_t GOTO>
|
|
static constexpr action_t go_to = {action_t::GOTO, static_cast<size_t>(GOTO)};
|
|
|
|
static constexpr action_t exit_ok = {action_t::EXIT, 0};
|
|
static constexpr action_t exit_error = {action_t::EXIT, static_cast<size_t>(-1)};
|
|
template <size_t Status>
|
|
static constexpr action_t exit = {action_t::EXIT, static_cast<size_t>(Status)};
|
|
|
|
/*!
|
|
* Match binary predicate function pointer type.
|
|
* Expects two string views and return a boolean.
|
|
* It is used by EXPECT/DETECT blocks to trigger their {handler, action} pair.
|
|
*/
|
|
using match_ft = bool (*) (const string_view haystack, const string_view needle);
|
|
|
|
/*!
|
|
* Send/Receive handler function pointer type.
|
|
* Expects a pointer to buffer and a size and returns status.
|
|
* It is used on predicate match on EXPECT/DETECT blocks, or as data wrapper on SEND blocks.
|
|
*/
|
|
using handler_ft = void (*) (const Data_t*, size_t);
|
|
|
|
/*!
|
|
* \struct record_t
|
|
* \brief
|
|
* Describes the sequencer's script record entry (line).
|
|
*/
|
|
struct record_t {
|
|
control_t control; //!< The control type of the entry
|
|
string_view token; //!< String view to token data. [MUST BE null terminated].
|
|
//!< This is passed as 2nd argument to match predicate on EXPECT/DETECT, or as
|
|
//! {data, size} pair to SEND handler and put_().
|
|
//!< If unused set it to ""
|
|
match_ft match; //!< Match predicate to used in EXPECT/DETECT blocks
|
|
//!< If unused set it to nullptr
|
|
handler_ft handler; //!< The handler to called if the match is successful, or before put_()
|
|
//!< If unused set it to nullptr
|
|
action_t action; //!< Indicates the step manipulation if the match is successful or after NOP and put_()
|
|
clock_t timeout; //!< Timeout in CPU time
|
|
};
|
|
|
|
/*!
|
|
* \struct script_t
|
|
* \brief
|
|
* Describes the sequencer's script.
|
|
*
|
|
* The user can create arrays as the example bellow to act as a script.
|
|
* \code
|
|
* Seq s;
|
|
* const Seq::script_t<4> script = {{
|
|
* {Seq::control_t::NOP, "", Seq::nil, Seq::nil, {Seq::action_t::GOTO, 1}, 1000},
|
|
*
|
|
* {Seq::control_t::SEND, "ATE0\r\n", Seq::nil, Seq::nil, {Seq::action_t::NEXT, 0}, 0},
|
|
* {Seq::control_t::EXPECT, "OK\r\n", Seq::ends_with, Seq::nil, {Seq::action_t::EXIT_OK, 0}, 1000},
|
|
* {Seq::control_t::OR_EXPECT, "ERROR", Seq::contains, Seq::nil, {Seq::action_t::EXIT_ERROR, 0}, 0}
|
|
* }};
|
|
* s.run(script);
|
|
* \endcode
|
|
*/
|
|
template <size_t Nrecords>
|
|
using script_t = std::array<record_t, Nrecords>;
|
|
|
|
|
|
/*!
|
|
* \brief
|
|
* Check if the \c stream1 is equal to \c stream2
|
|
* \param stream1 The stream in witch we search [The input buffer]
|
|
* \param stream2 What we search [The record's token]
|
|
* \return True on success, false otherwise
|
|
*/
|
|
static constexpr auto equals = [](const string_view stream1, const string_view stream2) -> bool {
|
|
return (stream1 == stream2);
|
|
};
|
|
|
|
/*!
|
|
* \brief
|
|
* Check if the \c stream starts with the \c prefix
|
|
* \param stream The stream in witch we search [The input buffer]
|
|
* \param prefix What we search [The record's token]
|
|
* \return True on success, false otherwise
|
|
*/
|
|
static constexpr auto starts_with = [](const string_view stream, const string_view prefix) -> bool {
|
|
return (stream.rfind(prefix, 0) != string_view::npos);
|
|
};
|
|
|
|
/*!
|
|
* \brief
|
|
* Check if the \c stream ends with the \c postfix
|
|
* \param stream The stream in witch we search [The input buffer]
|
|
* \param postfix What we search [The record's token]
|
|
* \return True on success, false otherwise
|
|
*/
|
|
static constexpr auto ends_with = [](const string_view stream, const string_view postfix) -> bool {
|
|
if (stream.size() < postfix.size())
|
|
return false;
|
|
return (
|
|
stream.compare(
|
|
stream.size() - postfix.size(),
|
|
postfix.size(),
|
|
postfix) == 0
|
|
);
|
|
};
|
|
|
|
/*!
|
|
* \brief
|
|
* Check if the \c haystack contains the \c needle
|
|
* \param haystack The stream in witch we search [The input buffer]
|
|
* \param needle What we search [The record's token]
|
|
* \return True on success, false otherwise
|
|
*/
|
|
static constexpr auto contains = [](const string_view haystack, const string_view needle) -> bool {
|
|
return (haystack.find(needle) != string_view::npos);
|
|
};
|
|
|
|
//! Always false predicate
|
|
static constexpr auto always_true = [](const string_view s1, const string_view s2) -> bool {
|
|
(void)s1; (void)s2;
|
|
return true;
|
|
};
|
|
|
|
//! Always false predicate
|
|
static constexpr auto always_false = [](const string_view s1, const string_view s2) -> bool {
|
|
(void)s1; (void)s2;
|
|
return false;
|
|
};
|
|
|
|
//! Empty predicate or handler
|
|
static constexpr auto nil = nullptr;
|
|
//! @}
|
|
|
|
|
|
|
|
//! \name Object lifetime
|
|
//!@{
|
|
protected:
|
|
~sequencer () = default; //!< \brief Allow destructor from derived only
|
|
constexpr sequencer () noexcept = default; //!< \brief A default constructor from derived only
|
|
sequencer(const sequencer&) = delete; //!< No copies
|
|
sequencer& operator= (const sequencer&) = delete; //!< No copy assignments
|
|
//!@}
|
|
|
|
//! \name Sequencer interface requirements for implementer
|
|
//! @{
|
|
private:
|
|
size_t get_ (Data_t* data) { return impl().get (data); }
|
|
size_t contents_ (Data_t* data) { return impl().contents(data); }
|
|
size_t put_ (const Data_t* data, size_t n) { return impl().put (data, n); }
|
|
clock_t clock_ () { return impl().clock(); }
|
|
//! @}
|
|
|
|
//! \name Private functionality
|
|
//! @{
|
|
private:
|
|
|
|
/*!
|
|
* Check if there is a handler and call it
|
|
* \param handler The handler to check
|
|
* \param buffer String view to buffer to pass to handler
|
|
* \return True if handler is called
|
|
*/
|
|
constexpr bool handle_ (handler_ft handler, const string_view buffer = string_view{}) {
|
|
if (handler != nullptr) {
|
|
handler (buffer.begin(), buffer.size());
|
|
return true;
|
|
}
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* \brief
|
|
* Return the new sequencer's step value and the sequencer's loop status as pair.
|
|
*
|
|
* \param script Reference to entire script.
|
|
* \param step The current step
|
|
* \return new step - status pair
|
|
*/
|
|
template <size_t Steps>
|
|
constexpr std::pair<size_t, seq_status_t> action_ (const script_t<Steps>& script, size_t step) {
|
|
control_t skip_while{};
|
|
size_t s;
|
|
|
|
switch (script[step].action.type) {
|
|
default:
|
|
case action_t::NO: return std::make_pair(step, seq_status_t::CONTINUE);
|
|
case action_t::NEXT:
|
|
switch (script[step].control) {
|
|
case control_t::NOP: return std::make_pair(++step, seq_status_t::CONTINUE);
|
|
case control_t::SEND: return std::make_pair(++step, seq_status_t::CONTINUE);
|
|
case control_t::EXPECT:
|
|
case control_t::OR_EXPECT: skip_while = control_t::OR_EXPECT; break;
|
|
case control_t::DETECT:
|
|
case control_t::OR_DETECT: skip_while = control_t::OR_DETECT; break;
|
|
}
|
|
s = step;
|
|
while (script[++s].control == skip_while)
|
|
;
|
|
return std::make_pair(s, seq_status_t::CONTINUE);
|
|
case action_t::GOTO: return std::make_pair(script[step].action.value, seq_status_t::CONTINUE);
|
|
case action_t::EXIT: return std::make_pair(script[step].action.value, seq_status_t::EXIT);
|
|
|
|
}
|
|
}
|
|
|
|
//! @}
|
|
|
|
|
|
public:
|
|
|
|
//! \return The buffer size of the sequencer
|
|
constexpr size_t size() const { return N; }
|
|
|
|
/*!
|
|
* \brief
|
|
* A static functionality to provide access to sequencer's inner matching mechanism.
|
|
* Checks the \c buffer against \c handle and calls its action if needed.
|
|
*
|
|
* \param buffer The buffer to check (1st parameter to match)
|
|
* \param token String view to check against buffer (2nd parameter to match)
|
|
* \param handler Function pointer to match predicate to use
|
|
* \param handle Reference to handle to call on match
|
|
*
|
|
* \return True on match, false otherwise
|
|
*/
|
|
constexpr bool check_handle (const string_view buffer, const string_view token, match_ft match, handler_ft handle) {
|
|
if (match != nullptr && match(buffer, token))
|
|
return handle_ (handle, buffer);
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* \brief
|
|
* Run the script array
|
|
*
|
|
* The main sequencer functionality. It starts with the first entry of the array.
|
|
*
|
|
* - If the record is \c NOP it executes the action after the timeout.
|
|
* \c NOP uses {\c action_t, \c timeout}.
|
|
* - If the record is \c SEND passes the token to handler (if any), then to put_() and executes the action after that.
|
|
* \c SEND uses {\c token, \c handler, \c action_t}
|
|
* - If the record is \c EXCEPT it continuously try to receive data using \see get_()
|
|
* * If no data until timeout, exit with failure
|
|
* * On data reception for this record AND for each OR_EXPECT that follows, calls the match predicate
|
|
* by passing the received data and token.
|
|
* On predicate match
|
|
* - Calls the handler if there is one
|
|
* - Executes the action. No farther EXPECT, OR_EXPECT, ... checks are made.
|
|
* - If the record is \c DETECT it continuously try to receive data using \see contents_()
|
|
* * If no data until timeout, exit with failure
|
|
* * On data reception for this record AND for each OR_DETECT that follows, calls the match predicate
|
|
* by passing the received data and token.
|
|
* On predicate match
|
|
* - Calls the handler if there is one
|
|
* - Executes the action. No farther DETECT, OR_DETECT, ... checks are made.
|
|
*
|
|
* \tparam Steps The number of records of the script
|
|
*
|
|
* \param script Reference to script to run
|
|
* \return The status of entire operation as described above
|
|
* \arg 0 Success
|
|
* \arg (size_t)-1 Failure
|
|
* \arg other Arbitrary return status
|
|
*/
|
|
template <size_t Steps>
|
|
size_t run (const script_t<Steps>& script) {
|
|
Data_t buffer[N];
|
|
size_t resp_size;
|
|
|
|
size_t step =0, p_step =0;
|
|
clock_t mark = clock_();
|
|
|
|
seq_status_t status{seq_status_t::CONTINUE}; do {
|
|
const record_t& record = script[step]; // get reference ot current line
|
|
|
|
if (step != p_step) { // renew time marker in each step
|
|
p_step = step;
|
|
mark = clock_();
|
|
}
|
|
switch (record.control) {
|
|
default:
|
|
case control_t::NOP:
|
|
if ((clock_() - mark) >= record.timeout)
|
|
std::tie(step, status) = action_ (script, step);
|
|
break;
|
|
|
|
case control_t::SEND:
|
|
if (record.handler != nullptr)
|
|
record.handler(record.token.data(), record.token.size());
|
|
if (put_(record.token.data(), record.token.size()) != record.token.size())
|
|
return exit_error.value;
|
|
std::tie(step, status) = action_ (script, step);
|
|
break;
|
|
|
|
case control_t::EXPECT:
|
|
case control_t::OR_EXPECT:
|
|
resp_size = get_(buffer);
|
|
if (resp_size) {
|
|
size_t s = step ; do{
|
|
if (script[s].match != nullptr && script[s].match({buffer, resp_size}, script[s].token)) {
|
|
handle_ (script[s].handler, {buffer, resp_size});
|
|
std::tie(step, status) = action_ (script, s);
|
|
break;
|
|
}
|
|
} while (script[++s].control == control_t::OR_EXPECT);
|
|
}
|
|
if (record.timeout && (clock_() - mark) >= record.timeout)
|
|
return exit_error.value;
|
|
break;
|
|
|
|
case control_t::DETECT:
|
|
case control_t::OR_DETECT:
|
|
resp_size = contents_(buffer);
|
|
if (resp_size) {
|
|
size_t s = step ; do {
|
|
if (script[s].match != nullptr && script[s].match({buffer, resp_size}, script[s].token)) {
|
|
handle_ (script[s].handler, {buffer, resp_size});
|
|
std::tie(step, status) = action_ (script, s);
|
|
break;
|
|
}
|
|
} while (script[++s].control == control_t::OR_DETECT);
|
|
}
|
|
if (record.timeout && (clock_() - mark) >= record.timeout)
|
|
return exit_error.value;
|
|
break;
|
|
|
|
} // switch (record.control)
|
|
|
|
} while ( status == seq_status_t::CONTINUE);
|
|
|
|
return step; // step here is set by action_ as the return status
|
|
}
|
|
};
|
|
|
|
|
|
}
|
|
#endif /* TBX_UTILS_SEQUENCER_H_ */
|