BASIS 2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | List of all members
alicat_basis2::Bus< Port > Class Template Reference

The transaction machine of one serial line, shared by every instrument on it. More...

#include <alicat_basis2_uart_interface.hpp>

Public Member Functions

 Bus (Port &port) noexcept
 Bind to a port; no I/O.
 
 Bus (const Bus &)=delete
 One bus per serial line.
 
Bus & operator= (const Bus &)=delete
 One bus per serial line.
 
Port & GetPort () &noexcept
 
Result< void > ApplyBaud (uint32_t baud) noexcept
 Change the port's speed through the optional hook.
 
Error Submit (const Request &request, const Timing &timing) noexcept
 Start a transaction.
 
PollState Poll () noexcept
 Advance the machine without blocking.
 
Result< Reply > Take () noexcept
 Take the result of a finished transaction.
 
void Abort () noexcept
 Drop the pending transaction and drain the line before the next send.
 
void EnterQuarantine () noexcept
 Drain the line until quiet before the next send (a decoder found the reply unusable).
 
Result< Reply > Execute (const Request &request, const Timing &timing) noexcept
 Run one transaction to the end: wait for the bus, submit, poll, take. Blocks with DelayMs() or spins. A non-blocking result that was never Take()n is dropped (its transaction is over), and the wait for a busy bus is bounded by WaitBoundMs(). A request whose line is not quiet within one line wait (its reply wait without its own duration) ends Busy, unsent; the next request then waits only for the quiet line.
 
uint32_t WaitBoundMs () const noexcept
 The longest Execute() waits for the transaction submitted last to end before it gives up with Busy: the gap and one line wait (a reply wait without the request's own duration) for a quiet line, the request's line time, one reply wait, a quarantine of two, its hold-off, a quiet margin of 2 ms and a slack of 2 ms per phase (four) for a sleep that overshoots.
 
uint32_t StrayLineCount () const noexcept
 
bool StreamingSuspected () const noexcept
 
uint32_t WireViolations () const noexcept
 
BusState State () const noexcept
 
uint8_t DeviceCount () const noexcept
 
void SetDeviceCount (uint8_t count) noexcept
 

Static Public Member Functions

static constexpr bool CanSetBaud () noexcept
 

Detailed Description

template<UartPort Port>
class alicat_basis2::Bus< Port >

The transaction machine of one serial line, shared by every instrument on it.

One transaction at a time ("behavior undefined" otherwise, M p.10): Submit() on a busy bus returns Busy and sends nothing. After a timeout, an overflow, a bad line or a wrong-ID reply the bus waits out the failed request's reply wait and drains the line until it has been quiet for t3.5 + 2 ms before it sends again, so a late reply is never taken for the next answer. A request that never reached the wire (the line did not go quiet) only needs the quiet line. While idle, bytes that arrive are counted as stray lines and never used.

Template Parameters
PortYour class derived from UartInterface<Port>.

Constructor & Destructor Documentation

◆ Bus()

template<UartPort Port>
alicat_basis2::Bus< Port >::Bus ( Port &  port)
inlineexplicitnoexcept

Bind to a port; no I/O.

Parameters
portThe port; it must outlive the bus.

Member Function Documentation

◆ ApplyBaud()

template<UartPort Port>
Result< void > alicat_basis2::Bus< Port >::ApplyBaud ( uint32_t  baud)
noexcept

Change the port's speed through the optional hook.

Parameters
baudThe new speed.
Returns
Ok, Unsupported (no hook) or Bus (the hook failed).

◆ CanSetBaud()

template<UartPort Port>
static constexpr bool alicat_basis2::Bus< Port >::CanSetBaud ( )
inlinestaticconstexprnoexcept
Returns
true when the port has a SetBaud() hook.

◆ DeviceCount()

template<UartPort Port>
uint8_t alicat_basis2::Bus< Port >::DeviceCount ( ) const
inlinenoexcept
Returns
Number of instruments the application declared on this line.

◆ Execute()

template<UartPort Port>
Result< Reply > alicat_basis2::Bus< Port >::Execute ( const Request &  request,
const Timing &  timing 
)
noexcept

Run one transaction to the end: wait for the bus, submit, poll, take. Blocks with DelayMs() or spins. A non-blocking result that was never Take()n is dropped (its transaction is over), and the wait for a busy bus is bounded by WaitBoundMs(). A request whose line is not quiet within one line wait (its reply wait without its own duration) ends Busy, unsent; the next request then waits only for the quiet line.

Parameters
requestThe request.
timingThe timing.
Returns
The reply or the error; always returns within the computed deadlines.

◆ GetPort()

template<UartPort Port>
Port & alicat_basis2::Bus< Port >::GetPort ( ) &
inlinenoexcept
Returns
The port.

◆ Poll()

template<UartPort Port>
PollState alicat_basis2::Bus< Port >::Poll ( )
noexcept

Advance the machine without blocking.

Returns
The state.

◆ SetDeviceCount()

template<UartPort Port>
void alicat_basis2::Bus< Port >::SetDeviceCount ( uint8_t  count)
inlinenoexcept
Parameters
countNumber of instruments on the line; a change of unit ID is refused when it is above one.

◆ State()

template<UartPort Port>
BusState alicat_basis2::Bus< Port >::State ( ) const
inlinenoexcept
Returns
The state of the machine.

◆ StrayLineCount()

template<UartPort Port>
uint32_t alicat_basis2::Bus< Port >::StrayLineCount ( ) const
inlinenoexcept
Returns
Complete lines that arrived while no transaction waited.

◆ StreamingSuspected()

template<UartPort Port>
bool alicat_basis2::Bus< Port >::StreamingSuspected ( ) const
inlinenoexcept
Returns
true when a stray line began with @: a streaming peer (A19).

◆ Submit()

template<UartPort Port>
Error alicat_basis2::Bus< Port >::Submit ( const Request &  request,
const Timing &  timing 
)
noexcept

Start a transaction.

Parameters
requestA request from the factories; its wire bytes are checked once more against the validators.
timingThe line speed and turnaround times.
Returns
Ok; Busy (a transaction or its settling is not over: nothing sent); InvalidArgument (an empty request or a wire violation: counted in WireViolations()).

◆ Take()

template<UartPort Port>
Result< Reply > alicat_basis2::Bus< Port >::Take ( )
noexcept

Take the result of a finished transaction.

Returns
The reply, or why there is none.

◆ WaitBoundMs()

template<UartPort Port>
uint32_t alicat_basis2::Bus< Port >::WaitBoundMs ( ) const
inlinenoexcept

The longest Execute() waits for the transaction submitted last to end before it gives up with Busy: the gap and one line wait (a reply wait without the request's own duration) for a quiet line, the request's line time, one reply wait, a quarantine of two, its hold-off, a quiet margin of 2 ms and a slack of 2 ms per phase (four) for a sleep that overshoots.

Returns
Milliseconds.

◆ WireViolations()

template<UartPort Port>
uint32_t alicat_basis2::Bus< Port >::WireViolations ( ) const
inlinenoexcept
Returns
Requests refused by the wire validator; must stay 0.

The documentation for this class was generated from the following file: