Refactor peripheral/bus/phy APIs (prep for pico/PIO)

- Refactor PHY to be higher-level with a field focus (controller/peripheral address,
  control byte, etc)
  - Phy layer is now device address aware (ACK's automatically) (Hardens
    previously ~implicit design to only support emulating one AVCLAN
    unit per mockingboard build)
- Redesign `phy_active` => `phy_frame_pending` (to allow
  asynchronous/buffered frame reads on pico) and embed within
  Peripheral::read
- Add `deafen` function: like mute, but also ignore incoming messages (i.e.
  don't receive/process at all). Makes `Bus::is_active` always return
  `false`.
- Add debug bus driving functions

Assisted-by: Claude Code (Opus 5)

src/avclan/hal/phy.h

@@ -12,16 +12,16 @@
 #ifdef __cplusplus
 using Read = avclan::detail::Error::Read;
 using Send = avclan::detail::Error::Send;
-using Bit = avclan::detail::Bit;
 extern "C" {
 #else
 typedef enum Read Read;
 typedef enum Send Send;
-typedef enum Bit Bit;
 #endif
 
 // One-time bring-up of the bus hardware. Leaves the bus idle and TX unmuted.
-void phy_init(void);
+//
+// `address` is our device address.
+void phy_init(uint16_t address);
 
 // Mute/unmute device TX. "Muted" means transmission is disabled (RX is
 // unchanged/still allowed)
@@ -30,56 +30,76 @@ void phy_mute(bool mute);
 // Non-mutating (e.g. theoretically const qualified/-able)
 bool phy_is_muted(void);
 
-// True when bus is driven/"dominant" (logical 0)
-bool phy_active(void);
+// True when there is a frame to read. This may reflect current bus state (e.g.
+// a frame can be synchronously read from the bus) or indicate that a buffered
+// frame is available to "read".
+bool phy_frame_pending(void);
 
 // 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.
+// sources with `phy_guard_leave`.
+//  - May be a no-op on a target where contention isn't a concern.
+//  - May acquire a hardware lock to prevent concurrent use
 void phy_guard_enter(void);
 void phy_guard_leave(void);
 
-// Validates an incoming start bit; see avclan::detail::Error::Read.
-//  Invariants:
-//    - Must only be called after positive phy_active() call.
-Read phy_read_startbit(void);
+/* Per-field frame I/O.
+ *
+ * Excluding the header and controller_addr send functions, all other send
+ * functions may have asynchronous implementations (e.g. return before the send
+ * has completed on the bus). Success is indicated by a zero value `Read` or
+ * `Send` enum. Non-zero error codes indicate a synchronously completed send
+ * failure. Otherwise, `phy_send_done` must be called to block until all queued
+ * send's have completed, and may return the error code for a previous (queued)
+ * send failure; a success return value indicates that all queued send's have
+ * finished sending over the bus.
+ *
+ * The read functions are similarly optionally asynchronous, and may return the
+ * results of buffered reads. When this is the case, phy_read_header returns the
+ * relevant error for the entire frame.
+ *
+ * It is invalid to call any later read or send function after getting an
+ * error (e.g. calling `phy_read_data` after `phy_read_length` errored).
+ *
+ * `expect_ack` indicates whether the recipient should be ACK'ing; false for
+ * broadcast frames which don't have a single recipient.
+ *
+ */
+Read phy_read_header(bool *is_unicast);
+Read phy_read_controller_addr(uint16_t *addr);
+Read phy_read_peripheral_addr(uint16_t *addr);
+Read phy_read_control(uint8_t *control);
+Read phy_read_length(uint8_t *length);
+Read phy_read_data(uint8_t *data);
 
-// Acquire the bus and emit a start bit; may return BUSY
-Send phy_send_startbit(void);
+// Send start and broadcast bits. Always synchronous. Returns success or one of
+// these error values: MUTED, BUSY, or LOST_ARBITRATION (if another device
+// overrides our frame with a broadcast).
+Send phy_send_header(bool is_unicast);
 
-/* 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);
+// Send the controller address. Always synchronous. Returns success or
+// LOST_ARBITRATION (a device with a lower device is sending a frame).
+Send phy_send_controller_addr(uint16_t addr);
+Send phy_send_peripheral_addr(uint16_t addr, bool expect_ack);
+Send phy_send_control(uint8_t control, bool expect_ack);
+Send phy_send_length(uint8_t length, bool expect_ack);
+Send phy_send_data(uint8_t data, bool expect_ack);
 
-// 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. 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.
+// Allows asynchronous ports to block until the phy has finished sending the
+// frame. Returns success or the relevant field-specific NAK (e.g. NAK_ADDRESS,
+// etc) or CONTENDED_BUS. `data_index` is only written to for NAK_DATA. A fully
+// synchronous port should always report success.
+Send phy_send_done(uint8_t *data_index);
 
-// Intended for sending parity bits
-void phy_send_bit(Bit bit);
+#ifndef NDEBUG
 
-// 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);
+void phy_set_dominant(void);
+void phy_set_recessive(void);
 
-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);
-
-#if !defined(NDEBUG) && defined(MEASURE_BUS)
+  #ifdef MEASURE_BUS
 // Sample and dump bus bit timing over the serial link (REPL `M`).
 void phy_measure(void);
+  #endif
 #endif
 
 #ifdef __cplusplus