Improve/expand C phy docs

src/avclan/avclan.h

@@ -9,7 +9,6 @@
   #define AVCLAN_ENUM_CLASS class
 
   #include <type_traits>
-  #include <utility>
 
 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,
   };

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 <auto N, std::unsigned_integral T,
@@ -162,7 +162,7 @@ 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<Bit>(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;

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`).

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)