Merge pull request #42 from loopj/multi-target

Add native support for multiple chained targets

Author: loopj

include/joybus/bus.h

@@ -115,8 +115,11 @@ struct joybus {
   /** The frequency of the bus, in Hz. */
   uint32_t freq;
 
-  /** The target device attached to this Joybus instance, if any. */
-  struct joybus_target *target;
+  /** The targets attached to this Joybus instance, in attachment order. */
+  struct joybus_target *targets;
+
+  /** The target that claimed the command being received, if any. */
+  struct joybus_target *active_target;
 
   uint8_t command_buffer[JOYBUS_BLOCK_SIZE];
   uint8_t response_buffer[JOYBUS_BLOCK_SIZE];
@@ -192,17 +195,16 @@ int joybus_transfer_sync(struct joybus *bus, const uint8_t *write_buf, uint8_t w
 /**
  * Attach a target to handle commands received in target mode.
  *
+ * A bus accepts more than one target. Each command is offered to the attached
+ * targets in attachment order, so a target attached earlier takes priority
+ * over those attached after it. Attaching a target that is already attached
+ * has no effect.
+ *
  * @param bus the Joybus instance to use
  * @param target the target to attach
  * @return 0 on success, a negative joybus_error on failure
  */
-static inline int joybus_attach_target(struct joybus *bus, struct joybus_target *target)
-{
-  bus->target      = target;
-  target->attached = true;
-
-  return 0;
-}
+int joybus_attach_target(struct joybus *bus, struct joybus_target *target);
 
 /**
  * Detach a target from the bus.
@@ -211,12 +213,44 @@ static inline int joybus_attach_target(struct joybus *bus, struct joybus_target
  * @param target the target to detach
  * @return 0 on success, a negative joybus_error on failure
  */
-static inline int joybus_detach_target(struct joybus *bus, struct joybus_target *target)
-{
-  bus->target      = NULL;
-  target->attached = false;
+int joybus_detach_target(struct joybus *bus, struct joybus_target *target);
 
-  return 0;
+/**
+ * Offer a received command byte to the targets attached to the bus.
+ *
+ * Called by backends in target mode as each command byte arrives. The first
+ * byte of a command is offered to each attached target in attachment order
+ * until one claims it by returning anything other than -JOYBUS_ERR_NOT_SUPPORTED.
+ * Every later byte of the command goes to that target alone.
+ *
+ * @param bus the Joybus instance that received the byte
+ * @param command the command buffer
+ * @param byte_idx the index of the byte that was just received
+ * @param send_response a callback function to send the response
+ * @param user_data user data to pass to the response callback
+ * @return positive number of bytes still expected, 0 if no more bytes expected, a negative joybus_error on failure.
+ *   -JOYBUS_ERR_NOT_SUPPORTED if no target claimed the command
+ */
+static inline int joybus_byte_received(struct joybus *bus, const uint8_t *command, uint8_t byte_idx,
+                                       joybus_target_response_cb send_response, void *user_data)
+{
+  // Later bytes go straight to the target that claimed the command
+  if (byte_idx > 1)
+    return joybus_target_byte_received(bus->active_target, command, byte_idx, send_response, user_data);
+
+  // Offer the first byte to each target in attachment order until one claims the command
+  for (struct joybus_target *target = bus->targets; target; target = target->next) {
+    int rc = joybus_target_byte_received(target, command, byte_idx, send_response, user_data);
+    if (rc == -JOYBUS_ERR_NOT_SUPPORTED)
+      continue;
+
+    bus->active_target = target;
+    return rc;
+  }
+
+  // No target claimed the command
+  bus->active_target = NULL;
+  return -JOYBUS_ERR_NOT_SUPPORTED;
 }
 
 // Context for a blocking Joybus operation

include/joybus/target.h

@@ -26,6 +26,22 @@
  * at a ::joybus_target_api table, and attach it to a bus with
  * joybus_attach_target().
  *
+ * A bus accepts more than one target. Each command is offered to the attached
+ * targets in attachment order, and the first one that accepts it handles that
+ * command to the end. This places the following contract on a target:
+ *
+ * - A target decides on the first byte of a command. Returning
+ *   -JOYBUS_ERR_NOT_SUPPORTED from the handler for the first byte declines the
+ *   command, and the byte is then offered to the next target. Any other return
+ *   claims the command, and the target receives every later byte of it. A
+ *   target cannot claim a command later.
+ * - Declining has no side effects. A declined first byte must store nothing
+ *   and send nothing, since another target may go on to handle the command.
+ * - Once a command is claimed, -JOYBUS_ERR_NOT_SUPPORTED from a later byte is
+ *   an error in a command the target owns, and the bus returns to idle.
+ * - On the first byte, "not my opcode" and "my opcode, refused" are the same
+ *   return, so a target cannot distinguish them.
+ *
  * @{
  */
 
@@ -63,7 +79,8 @@ struct joybus_target_api {
    * @param byte_idx the index of the byte that was just received
    * @param send_response a callback function to send the response
    * @param user_data user data to pass to the response callback
-   * @return positive number of bytes still expected, 0 if no more bytes expected, a negative joybus_error on failure
+   * @return positive number of bytes still expected, 0 if no more bytes expected, a negative joybus_error on failure.
+   *   -JOYBUS_ERR_NOT_SUPPORTED on the first byte declines the command, see the target contract above
    */
   int (*byte_received)(struct joybus_target *target, const uint8_t *command, uint8_t byte_idx,
                        joybus_target_response_cb send_response, void *user_data);
@@ -78,10 +95,16 @@ struct joybus_target {
 
   /// Whether the target is currently attached to a bus
   bool attached;
+
+  /// The next target attached to the same bus, in attachment order
+  struct joybus_target *next;
 };
 
 /**
- * Handle a received command byte for a Joybus target.
+ * Handle a received command byte for a single Joybus target.
+ *
+ * Backends do not call this directly. They call joybus_byte_received(), which
+ * offers the command to each target attached to the bus.
  *
  * @param target the target to handle the command
  * @param command the command buffer

libjoybus.slcc

@@ -18,6 +18,7 @@ include:
   - path: include
 
 source:
+  - path: src/bus.c
   - path: src/checksum.c
   - path: src/backend/gecko_sdk/joybus.c
   - path: src/host/common.c

src/backend/README.md

@@ -21,7 +21,8 @@ int joybus_mybackend_init(struct joybus_mybackend *mybackend_bus, struct joybus_
   struct joybus *bus = JOYBUS(mybackend_bus);
   bus->api           = &mybackend_api;
   bus->freq          = config.freq;
-  bus->target        = NULL;
+  bus->targets       = NULL;
+  bus->active_target = NULL;
 
   // Rest of initialization code...
 
@@ -59,14 +60,29 @@ The turnaround times between transmitting and receiving data are also critical.
 
 - When enabled, target mode should await bus idle before receiving a command. The bus is idle once the line has been continuously high for 100us (`JOYBUS_BUS_IDLE_US`)
 - A falling edge on the bus indicates the start of a command
-- Received bytes are streamed to the target: `joybus_target_byte_received` should be called as soon as possible after each complete byte is received
+- Received bytes are streamed to the targets: `joybus_byte_received` should be called as soon as possible after each complete byte is received. It offers the first byte of a command to each attached target in attachment order, and routes every later byte to the target that claimed the command
 - After the first byte is received, if more bytes are expected, they should be received contiguously, otherwise wait for the next command (await bus idle) - timeout mechanism can be determined by the backend (per bit, per byte, etc)
-- If a byte is received and there is no registered target, ignore it and wait for the next command (await bus idle)
-- If the registered target does not recognize the command's opcode, ignore it and wait for the next command (await bus idle)
-- The registered target can call the `joybus_target_response_cb` at any time to signal to the backend that response bytes are available
+- If `joybus_byte_received` returns an error, including when no target is attached or no attached target recognizes the command's opcode, ignore the command and wait for the next command (await bus idle)
+- The target handling a command can call the `joybus_target_response_cb` at any time to signal to the backend that response bytes are available
 - Since the `joybus_target_response_cb` can be called before the last byte, we can use this as an opportunity to begin pre-encoding the response while waiting for the remaining bytes to be clocked in
 - Once the final byte of a command is received, we must begin clocking out the response IMMEDIATELY (OEM devices turn around in 3.1 - 4.4us, or 6.6 - 7.0us for a GBA cable, see below for measured OEM timings)
 
+## Reducing Turnaround
+
+The hard deadline in both modes is the turnaround between the last bit of a command and the first bit of the reply. These are the techniques the existing backends use to meet it.
+
+- Stream command bytes to the target as they arrive. `joybus_byte_received` is called once per byte rather than once per command, so a target can recognize a command from its opcode and call `joybus_target_response_cb` before the final byte has been clocked in. Every technique below depends on the backend holding the response before the command ends.
+- Pre-encode the response into the wire format while the remaining bits arrive. The gecko backend encodes the first one or two bytes in `prepare_write` and encodes each later byte from the transmit DMA interrupt, so encoding never blocks the wire.
+- Arm the transmitter early and gate it, so starting the reply costs a single write. The gecko backend starts its transmit DMA with the peripheral request disabled (`REQDIS_SET`) and releases it with `REQDIS_CLR` once the last byte lands. The rp2xxx backend starts its transmit DMA as soon as the response arrives, which fills the PIO transmit FIFO while the state machine is still in its receive loop, then switches with a single `jmp`.
+- Start transmitting before the whole response is encoded. The esp32 backend writes the first symbol of the first byte, starts the transmitter immediately, and fills the remaining symbols behind the hardware as it reads them.
+- Arm the receiver before the reply can arrive, never in response to a transmit-complete interrupt. The esp32 backend arms RX before it transmits and captures the command, the stop bit, and the reply as one continuous capture, then decodes the reply from a fixed symbol offset. This removes interrupt latency from the path and works regardless of MCU clock speed.
+- Let the hardware perform the turnaround where the peripheral allows it. The rp2xxx host PIO program sends the stop bit, fires its interrupt, and falls straight into its receive loop, so no CPU work sits between the end of the command and being ready to sample the reply.
+- Fire the byte-received interrupt early and decode underneath the bits still arriving. The esp32 backend sets the RMT receive limit a symbol or two short of a full byte, folds in each bit as its symbol commits, and busy-waits only for the last one. Interrupt latency is hidden behind the tail of the byte instead of being added after it.
+- Do setup work while the bus is idle. The esp32 backend resets its transmit pointer when it enters receive mode, keeping that work off the critical path.
+- Keep the hot path out of flash. The esp32 backend marks its encode, decode, and interrupt handlers `IRAM_ATTR`. Running the target handler and checksum from flash measurably slows the reply on parts that fetch instructions from external flash.
+
+Replying faster than an OEM device has no known benefit. The esp32 backend enforces a floor (`TARGET_REPLY_FLOOR_NS`) so it never replies much sooner than the measured OEM turnaround below.
+
 ## Checklist
 
 When implementing a new backend, the following requirements are considered the bare minimum:

src/backend/esp32/joybus.c

@@ -368,7 +368,7 @@ static inline IRAM_ATTR void target_byte_received(struct joybus *bus)
   data->read_count++;
 
   // Call the target handler to prepare a response if needed
-  int rc = joybus_target_byte_received(bus->target, data->read_buf, data->read_count, handle_command_response, bus);
+  int rc = joybus_byte_received(bus, data->read_buf, data->read_count, handle_command_response, bus);
   if (rc == 0) {
     // No more bytes expected
     if (data->write_len > 0) {
@@ -717,7 +717,8 @@ int joybus_esp32_init(struct joybus_esp32 *esp32_bus, struct joybus_esp32_config
   // Save the bus API and common configuration
   struct joybus *bus = JOYBUS(esp32_bus);
   bus->api           = &esp32_api;
-  bus->target        = NULL;
+  bus->targets       = NULL;
+  bus->active_target = NULL;
   bus->freq          = config.freq;
 
   // Save the ESP32-specific configuration and initialize state

src/backend/gecko_sdk/joybus.c

@@ -294,7 +294,7 @@ static bool ldma_rx_handler(unsigned int chan, unsigned int iteration, void *use
     data->rx_current_buffer ^= 1;
 
     // Handle the received byte
-    int rc = joybus_target_byte_received(bus->target, data->read_buf, iteration, handle_command_response, bus);
+    int rc = joybus_byte_received(bus, data->read_buf, iteration, handle_command_response, bus);
     if (rc == 0) {
       // No more bytes expected
       // Start the response transfer if there is one
@@ -697,7 +697,8 @@ int joybus_gecko_init(struct joybus_gecko *gecko_bus, struct joybus_gecko_config
   struct joybus *bus = JOYBUS(gecko_bus);
   bus->api           = &gecko_api;
   bus->freq          = config.freq;
-  bus->target        = NULL;
+  bus->targets       = NULL;
+  bus->active_target = NULL;
 
   // Save the joybus configuration
   struct joybus_gecko_data *data = &gecko_bus->data;

src/backend/rp2xxx/joybus.c

@@ -219,7 +219,7 @@ static inline void target_byte_received(struct joybus *bus)
   data->read_count++;
 
   // Call the target handler to prepare a response if needed
-  int rc = joybus_target_byte_received(bus->target, data->read_buf, data->read_count, handle_command_response, bus);
+  int rc = joybus_byte_received(bus, data->read_buf, data->read_count, handle_command_response, bus);
   if (rc == 0) {
     // No more bytes expected, start transmitting the response
     pio_sm_exec(data->pio, data->pio_sm,
@@ -402,7 +402,8 @@ int joybus_rp2xxx_init(struct joybus_rp2xxx *rp2xxx_bus, struct joybus_rp2xxx_co
   struct joybus *bus = JOYBUS(rp2xxx_bus);
   bus->api           = &rp2xxx_api;
   bus->freq          = config.freq;
-  bus->target        = NULL;
+  bus->targets       = NULL;
+  bus->active_target = NULL;
 
   // Save the joybus configuration
   struct joybus_rp2xxx_data *data = &rp2xxx_bus->data;

src/bus.c

@@ -1,5 +1,42 @@
 #include <joybus/bus.h>
 
+int joybus_attach_target(struct joybus *bus, struct joybus_target *target)
+{
+  if (target->attached)
+    return 0;
+
+  // Append the target after those already attached, so earlier targets keep priority
+  struct joybus_target **tail = &bus->targets;
+  while (*tail)
+    tail = &(*tail)->next;
+
+  target->next     = NULL;
+  *tail            = target;
+  target->attached = true;
+
+  return 0;
+}
+
+int joybus_detach_target(struct joybus *bus, struct joybus_target *target)
+{
+  // Unlink the target from the list of attached targets
+  for (struct joybus_target **link = &bus->targets; *link; link = &(*link)->next) {
+    if (*link != target)
+      continue;
+
+    *link            = target->next;
+    target->next     = NULL;
+    target->attached = false;
+    break;
+  }
+
+  // Stop delivering the command in progress to a target that is no longer attached
+  if (bus->active_target == target)
+    bus->active_target = NULL;
+
+  return 0;
+}
+
 void joybus_sync_cb(struct joybus *bus, int status, void *user_data)
 {
   struct joybus_sync_ctx *ctx = (struct joybus_sync_ctx *)user_data;

test/CMakeLists.txt

@@ -23,6 +23,9 @@ endfunction()
 # Checksum tests
 add_libjoybus_test(test_checksum test_checksum.c)
 
+# Bus target attachment and command dispatch tests
+add_libjoybus_test(test_bus test_bus.c)
+
 # GameCube controller target tests
 add_libjoybus_test(test_gcn_controller target/test_gcn_controller.c)