diff --git a/src/avclan/avclan.h b/src/avclan/avclan.h index 81fc82d..f9d2c63 100644 --- a/src/avclan/avclan.h +++ b/src/avclan/avclan.h @@ -9,7 +9,6 @@ #define AVCLAN_ENUM_CLASS class #include - #include namespace avclan { @@ -127,7 +126,9 @@ struct Error { #endif // Error enums are ordered such that a lower numeric value corresponds to - // more progress/success before an error occured, with 0 being no errors + // more progress/success before an error occured, with explicitly + // cast/constructed 0 (e.g. `Read{0}` in C++ or `(Read)0` in C) being no + // errors enum AVCLAN_ENUM_CLASS Read : uint8_t { BAD_DATA_PARITY = 0x01, BAD_LENGTH_RANGE, @@ -135,7 +136,7 @@ struct Error { BAD_PERIPHERAL_PARITY, BAD_CONTROLLER_PARITY, BAD_CONTROL_PARITY, - BAD_PARITY, // non-specific bad parity + BAD_PARITY, // generic bad parity has max severity STARTBIT_TOO_SHORT, STARTBIT_TOO_LONG, BAD_STARTBIT, @@ -146,7 +147,7 @@ struct Error { NAK_MESSAGE_LENGTH, NAK_CONTROL, NAK_ADDRESS, - NAK, // non-specific NAK + NAK, // generic NAK has max severity BUSY, MUTED, }; diff --git a/src/avclan/bus.cc b/src/avclan/bus.cc index c2c87b0..3996d1e 100644 --- a/src/avclan/bus.cc +++ b/src/avclan/bus.cc @@ -62,7 +62,7 @@ public: Handle(const Handle &) = delete; Handle(Handle &&) = delete; - bool sendstartbit() { return phy_send_startbit(); }; + Send sendstartbit() { return phy_send_startbit(); }; Read readstartbit() { return phy_read_startbit(); }; template inline Bit Bus::Handle::sendbits<1>(uint8_t bits) { return bit; }; template <> inline Bit Bus::Handle::readbits<8>(uint8_t *bits) { - return static_cast(phy_read_byte(bits)); + return phy_read_byte(bits); }; void Bus::init() { phy_init(); }; @@ -307,7 +307,7 @@ auto Bus::send(const Frame *out, Frame::Print print) -> Send { { // bound handle lifetime auto handle = get(); - if (!handle.sendstartbit()) { + if (handle.sendstartbit() == BUSY) { // Some other device is already driving the bus err.errno = BUSY; goto handle_err; diff --git a/src/avclan/hal/phy.h b/src/avclan/hal/phy.h index 4b634a7..4ee6741 100644 --- a/src/avclan/hal/phy.h +++ b/src/avclan/hal/phy.h @@ -23,17 +23,20 @@ typedef enum Bit Bit; // One-time bring-up of the bus hardware. Leaves the bus idle and TX unmuted. void phy_init(void); -// Mute/unmute device TX. "Muted" means we still listen, we just don't ACK or -// transmit. +// Mute/unmute device TX. "Muted" means transmission is disabled (RX is +// unchanged/still allowed) void phy_mute(bool mute); + +// Non-mutating (e.g. theoretically const qualified/-able) bool phy_is_muted(void); -// True when there is activity on the bus (something is driving it). +// True when bus is driven/"dominant" (logical 0) bool phy_active(void); -// Bus-transaction guard: quiesce the target's other async sources around a bus -// read/send so framing isn't disturbed, then restore them. May be a no-op on a -// target without such contention. +// Bus-transaction guard: quiesce the other async sources (e.g. interrupts) +// so that bus read/send timing isn't disturbed. Re-enable relevant async +// sources with `phy_guard_leave`. May be a no-op on a target where contention +// isn't a concern. void phy_guard_enter(void); void phy_guard_leave(void); @@ -41,31 +44,38 @@ void phy_guard_leave(void); // no bus-timing or hardware-recovery logic. // - phy_read_startbit waits for and validates an incoming start bit, doing // any target-specific bus recovery; see avclan::detail::Error::Read. -// - phy_send_startbit acquires the bus and emits a start bit; returns false -// if the bus was busy. +// - phy_send_startbit acquires the bus and emits a start bit; may return BUSY Read phy_read_startbit(void); -bool phy_send_startbit(void); +Send phy_send_startbit(void); + +/* Returns 0 (`(Send)0`) if the peripheral sent an ACK bit, otherwise returns +NAK. An ACK bit is a cooperative bit, where the sender starts (drives the bus) +for the sync period, and allows the receiver to drive the bus (or not) to +finish a "1" bit. +*/ +Send phy_read_ack(void); +void phy_send_ack(void); // Per-symbol I/O. The send* helpers return the even parity of the bits sent; // the read* helpers return the even parity of the bits read. The _u8/_u16 -// suffixes name the source-operand width; `len` is how many bits (<= width). +// suffixes name the source-operand width. The function implementations need not +// all be separate/independent (e.g. all send functions could be redirect to a +// single phy_send_bits_u16, etc). +// N.B: `len` is the number of bits to send. The +// C++ send/readbits templates are the only consumers and use constraints to +// enforce valid len values, so runtime checks are unnecessary. + +// Intended for sending parity bits void phy_send_bit(Bit bit); -void phy_send_ack(void); - -/* Returns 0 (`(Send)0`) if the peripheral sent an ACK bit, otherwise returns - NAK. An ACK bit is a cooperative bit, where the sender starts (drives the bus) - for the sync period, and allows the receiver to drive the bus (or not) to - finish a "1" bit. -*/ -Send phy_read_ack(void); +// Variants available to minimize unnecessary work for max runtime efficiency Bit phy_send_bits_u8(const uint8_t *bits, int8_t len); Bit phy_send_bits_u16(const uint16_t *bits, int8_t len); Bit phy_send_byte(const uint8_t *byte); -uint8_t phy_read_bits_u8(uint8_t *bits, uint8_t len); -uint8_t phy_read_bits_u16(uint16_t *bits, int8_t len); -uint8_t phy_read_byte(uint8_t *byte); +Bit phy_read_bits_u8(uint8_t *bits, uint8_t len); +Bit phy_read_bits_u16(uint16_t *bits, int8_t len); +Bit phy_read_byte(uint8_t *byte); #ifndef NDEBUG // Sample and dump bus bit timing over the serial link (REPL `M`). diff --git a/src/avclan/target/avr-attiny3216/phy_avr.c b/src/avclan/target/avr-attiny3216/phy_avr.c index f15e3e4..9e79abc 100644 --- a/src/avclan/target/avr-attiny3216/phy_avr.c +++ b/src/avclan/target/avr-attiny3216/phy_avr.c @@ -237,7 +237,7 @@ ISR(TCB0_INT_vect) { } // Read `len` bits on the AVCLAN bus; returns the even parity -uint8_t phy_read_bits_u8(uint8_t *bits, uint8_t len) { +Bit phy_read_bits_u8(uint8_t *bits, uint8_t len) { uint8_t parity; ATOMIC_BLOCK(ATOMIC_RESTORESTATE) { READING_BYTE = 0; @@ -260,11 +260,11 @@ uint8_t phy_read_bits_u8(uint8_t *bits, uint8_t len) { parity = READING_PARITY; } - return (parity & 1); + return (Bit)(parity & 1); } // Read `len` bits on the AVCLAN bus; returns the even parity -uint8_t phy_read_bits_u16(uint16_t *bits, int8_t len) { +Bit phy_read_bits_u16(uint16_t *bits, int8_t len) { uint8_t parity = 0; if (len > 8) { uint8_t over = len - 8; @@ -273,11 +273,11 @@ uint8_t phy_read_bits_u16(uint16_t *bits, int8_t len) { } parity += phy_read_bits_u8((uint8_t *)bits + 0, len); - return (parity & 1); + return (Bit)(parity & 1); } // Read a byte on the AVCLAN bus -uint8_t phy_read_byte(uint8_t *byte) { +Bit phy_read_byte(uint8_t *byte) { uint8_t parity; ATOMIC_BLOCK(ATOMIC_RESTORESTATE) { READING_BYTE = 0; @@ -300,7 +300,7 @@ uint8_t phy_read_byte(uint8_t *byte) { parity = READING_PARITY; } - return (parity & 1); + return (Bit)(parity & 1); } void phy_init() { @@ -384,7 +384,7 @@ Read phy_read_startbit() { // Acquire the bus and emit a start bit. Returns false if another device is // already driving the bus (we can't yet do proper CSMA/CD). -bool phy_send_startbit() { +Send phy_send_startbit() { // wait for free line TCB1.CNT = 0; while (BUS_IS_IDLE) { @@ -407,10 +407,10 @@ bool phy_send_startbit() { // if (TCB1.CNT <= (uint16_t)(AVCLAN_STARTBIT_LOGIC_0 * 0.8)) // return false; // Shouldn't be possible // set_AVC_logic_for(1, AVCLAN_STARTBIT_LOGIC_1); // wait for end of start - return false; + return BUSY; } phy_send_bit(bit_start); - return true; + return (Send)0; } /* Disable non-read related interrupts (USART RX, RTC status tick, mic timer)