Add manual spi mode support.

Add new cmdline option, to be read by spidev transport, along with
supporting code in spi transport. Will enable appliable spi mode,
enabling the userspace driver to take advantage of high speed
spi read & program.

Does not poll SFDP to check for support, but will instead fail
on hardware that does not support higher speeds.

Signed-off-by: Michael Field <michaelfield@google.com>

Author: mfield4

examples/htool.c

@@ -1846,6 +1846,9 @@ static const struct htool_param GLOBAL_FLAGS[] = {
      .default_value = "100",
      .desc = "Interval duration (in microseconds) to wait before checking SPI "
              "device status again when it indicates that the device is busy"},
+    // TODO(michaelfield) : b/346345769 - enable spidev mode auto-detection
+    {HTOOL_FLAG_VALUE, .name = "spidev_mode", .default_value = "single",
+     .desc = "SPI mode toggles (single|dual|quad)."},
     {HTOOL_FLAG_VALUE, .name = "mtddev_path", .default_value = "",
      .desc = "The full MTD path of the RoT mailbox; for example "
              "'/dev/mtd0'. If unspecified, will attempt to detect "

examples/htool_spi.c

@@ -32,13 +32,15 @@ struct libhoth_device* htool_libhoth_spi_device(void) {
 
   int rv;
   const char* spidev_path_str;
+  const char* mode_str;
   uint32_t mailbox_location;
   bool atomic;
   uint32_t spidev_speed_hz;
   uint32_t spidev_device_busy_wait_timeout;
   uint32_t spidev_device_busy_wait_check_interval;
   rv = htool_get_param_string(htool_global_flags(), "spidev_path",
                               &spidev_path_str) ||
+       htool_get_param_string(htool_global_flags(), "spidev_mode", &mode_str) ||
        htool_get_param_u32(htool_global_flags(), "mailbox_location",
                            &mailbox_location) ||
        htool_get_param_bool(htool_global_flags(), "spidev_atomic", &atomic) ||
@@ -54,6 +56,18 @@ struct libhoth_device* htool_libhoth_spi_device(void) {
     return NULL;
   }
 
+  enum libhoth_spi_mode operation_mode;
+  if (!strcmp(mode_str, "single")) {
+    operation_mode = LIBHOTH_SPI_MODE_SINGLE;
+  } else if (!strcmp(mode_str, "dual")) {
+    operation_mode = LIBHOTH_SPI_MODE_DUAL;
+  } else if (!strcmp(mode_str, "quad")) {
+    operation_mode = LIBHOTH_SPI_MODE_QUAD;
+  } else {
+    fprintf(stderr, "Invalid spidev mode: %s\n", mode_str);
+    return NULL;
+  }
+
   if (strlen(spidev_path_str) <= 0) {
     fprintf(stderr, "Invalid spidev path: %s\n", spidev_path_str);
     return NULL;
@@ -78,6 +92,7 @@ struct libhoth_device* htool_libhoth_spi_device(void) {
       .mailbox = mailbox_location,
       .atomic = atomic,
       .speed = spidev_speed_hz,
+      .operation_mode = operation_mode,
       .device_busy_wait_timeout = spidev_device_busy_wait_timeout,
       .device_busy_wait_check_interval = spidev_device_busy_wait_check_interval,
       .timeout_us = timeout_us,

transports/libhoth_spi.c

@@ -35,6 +35,41 @@
 
 #define DID_VID_ADDR 0xD40F00
 
+static uint8_t mode_to_nbits(enum libhoth_spi_mode mode) {
+  switch (mode) {
+    case LIBHOTH_SPI_MODE_DUAL:
+      return 2;
+    case LIBHOTH_SPI_MODE_QUAD:
+      return 4;
+    case LIBHOTH_SPI_MODE_SINGLE:
+    default:
+      return 1;
+  }
+}
+
+static uint8_t mode_to_read_opcode(enum libhoth_spi_mode mode) {
+  switch (mode) {
+    case LIBHOTH_SPI_MODE_DUAL:
+      return SPI_NOR_OPCODE_DUAL_READ;
+    case LIBHOTH_SPI_MODE_QUAD:
+      return SPI_NOR_OPCODE_QUAD_READ;
+    case LIBHOTH_SPI_MODE_SINGLE:
+    default:
+      return SPI_NOR_OPCODE_SLOW_READ;
+  }
+}
+
+static uint8_t mode_to_write_opcode(enum libhoth_spi_mode mode) {
+  switch (mode) {
+    case LIBHOTH_SPI_MODE_QUAD:
+      return SPI_NOR_OPCODE_QUAD_PAGE_PROGRAM;
+    case LIBHOTH_SPI_MODE_SINGLE:
+    case LIBHOTH_SPI_MODE_DUAL:
+    default:
+      return SPI_NOR_OPCODE_PAGE_PROGRAM;
+  }
+}
+
 static int spi_nor_address(uint8_t* buf, uint32_t address,
                            bool address_mode_4b) {
   if (address_mode_4b) {
@@ -128,7 +163,8 @@ static int spi_nor_write_enable(const int fd) {
   return LIBHOTH_OK;
 }
 
-static int spi_nor_write(int fd, bool address_mode_4b, unsigned int address,
+static int spi_nor_write(int fd, bool address_mode_4b,
+                         enum libhoth_spi_mode mode, unsigned int address,
                          const void* data, size_t data_len,
                          uint32_t device_busy_wait_timeout,
                          uint32_t device_busy_wait_check_interval) {
@@ -147,7 +183,7 @@ static int spi_nor_write(int fd, bool address_mode_4b, unsigned int address,
     uint8_t rq_buf[5] = {0};  // 1 for command opcode, 4 (max) for address
 
     // Page Program OPCODE + Address
-    rq_buf[0] = SPI_NOR_OPCODE_PAGE_PROGRAM;
+    rq_buf[0] = mode_to_write_opcode(mode);
     int address_len = spi_nor_address(&rq_buf[1], address, address_mode_4b);
     xfer[0] = (struct spi_ioc_transfer){
         .tx_buf = (unsigned long)rq_buf,
@@ -163,6 +199,11 @@ static int spi_nor_write(int fd, bool address_mode_4b, unsigned int address,
         .len = chunk_send_size,
     };
 
+    if (mode != LIBHOTH_SPI_MODE_SINGLE) {
+      uint8_t nbits = mode_to_nbits(mode);
+      xfer[1].tx_nbits = nbits;
+    }
+
     status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer);
     if (status < 0) {
       return LIBHOTH_ERR_FAIL;
@@ -180,15 +221,16 @@ static int spi_nor_write(int fd, bool address_mode_4b, unsigned int address,
   return LIBHOTH_OK;
 }
 
-static int spi_nor_read(int fd, bool address_mode_4b, unsigned int address,
+static int spi_nor_read(int fd, bool address_mode_4b,
+                        enum libhoth_spi_mode mode, unsigned int address,
                         void* data, size_t data_len) {
   if (fd < 0 || !data || !data_len) return LIBHOTH_ERR_INVALID_PARAMETER;
 
   uint8_t rd_request[5] = {0};
   struct spi_ioc_transfer xfer[2] = {0};
 
   // Read OPCODE and mailbox address
-  rd_request[0] = SPI_NOR_OPCODE_SLOW_READ;
+  rd_request[0] = mode_to_read_opcode(mode);
   int address_len = spi_nor_address(&rd_request[1], address, address_mode_4b);
   xfer[0] = (struct spi_ioc_transfer){
       .tx_buf = (unsigned long)rd_request,
@@ -201,6 +243,11 @@ static int spi_nor_read(int fd, bool address_mode_4b, unsigned int address,
       .len = data_len,
   };
 
+  if (mode != LIBHOTH_SPI_MODE_SINGLE) {
+    uint8_t nbits = mode_to_nbits(mode);
+    xfer[1].rx_nbits = nbits;
+  }
+
   int status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer);
   if (status < 0) {
     return LIBHOTH_ERR_FAIL;
@@ -281,6 +328,7 @@ int libhoth_spi_open(const struct libhoth_spi_device_init_options* options,
   spi_dev->fd = fd;
   spi_dev->mailbox_address = options->mailbox;
   spi_dev->address_mode_4b = true;
+  spi_dev->mode = options->operation_mode;
   spi_dev->device_busy_wait_timeout = options->device_busy_wait_timeout;
   spi_dev->device_busy_wait_check_interval =
       options->device_busy_wait_check_interval;
@@ -311,12 +359,52 @@ int libhoth_spi_open(const struct libhoth_spi_device_init_options* options,
     }
   }
 
-  if (options->mode) {
-    const uint8_t mode = (uint8_t)options->mode;
-    if (ioctl(fd, SPI_IOC_WR_MODE, &mode) < 0) {
+  uint32_t mode = options->mode;
+  if (ioctl(fd, SPI_IOC_RD_MODE32, &spi_dev->original_mode) < 0) {
+    status = LIBHOTH_ERR_FAIL;
+    goto err_out;
+  }
+
+  // TODO(michaelfield): Readback the SFDP and check that quadmode is
+  // supported. If not, then we should fail unless the user explicitly
+  // requested to force quadmode.
+
+  if (options->operation_mode == LIBHOTH_SPI_MODE_QUAD) {
+    // Quadmode spi needs to use 32-bit mode flags
+    mode |= (SPI_TX_QUAD | SPI_RX_QUAD);
+
+    if (ioctl(fd, SPI_IOC_WR_MODE32, &mode) < 0) {
       status = LIBHOTH_ERR_FAIL;
       goto err_out;
     }
+  } else if (options->operation_mode == LIBHOTH_SPI_MODE_DUAL) {
+    // Dualmode spi needs to use 32-bit mode flags
+    mode |= (SPI_TX_DUAL | SPI_RX_DUAL);
+
+    if (ioctl(fd, SPI_IOC_WR_MODE32, &mode) < 0) {
+      status = LIBHOTH_ERR_FAIL;
+      goto err_out;
+    }
+  } else {
+    // Set the mode anyways.
+    // There is a failure mode wherein a bad mode setting will stick.
+    // Even if mode is zero, we still want to write it.
+    if (ioctl(fd, SPI_IOC_WR_MODE32, &mode) < 0) {
+      status = LIBHOTH_ERR_FAIL;
+      goto err_out;
+    }
+  }
+
+  // read back the mode, and verify that it is what we expect.
+  uint32_t read_mode;
+  if (ioctl(fd, SPI_IOC_RD_MODE32, &read_mode) < 0) {
+    status = LIBHOTH_ERR_FAIL;
+    goto err_out;
+  }
+
+  if (read_mode != mode) {
+    status = LIBHOTH_ERR_FAIL;
+    goto err_out;
   }
 
   if (options->speed) {
@@ -353,7 +441,7 @@ int libhoth_spi_send_request(struct libhoth_device* dev, const void* request,
   struct libhoth_spi_device* spi_dev =
       (struct libhoth_spi_device*)dev->user_ctx;
 
-  return spi_nor_write(spi_dev->fd, spi_dev->address_mode_4b,
+  return spi_nor_write(spi_dev->fd, spi_dev->address_mode_4b, spi_dev->mode,
                        spi_dev->mailbox_address, request, request_size,
                        spi_dev->device_busy_wait_timeout,
                        spi_dev->device_busy_wait_check_interval);
@@ -377,7 +465,7 @@ int libhoth_spi_receive_response(struct libhoth_device* dev, void* response,
       (struct libhoth_spi_device*)dev->user_ctx;
 
   // Read Header From Mailbox
-  status = spi_nor_read(spi_dev->fd, spi_dev->address_mode_4b,
+  status = spi_nor_read(spi_dev->fd, spi_dev->address_mode_4b, spi_dev->mode,
                         spi_dev->mailbox_address, response,
                         sizeof(struct hoth_host_response));
   if (status != LIBHOTH_OK) {
@@ -397,7 +485,7 @@ int libhoth_spi_receive_response(struct libhoth_device* dev, void* response,
   if (host_response.data_len > 0) {
     // Read remainder of data based on header length
     uint8_t* const data_start = (uint8_t*)response + total_bytes;
-    status = spi_nor_read(spi_dev->fd, spi_dev->address_mode_4b,
+    status = spi_nor_read(spi_dev->fd, spi_dev->address_mode_4b, spi_dev->mode,
                           spi_dev->mailbox_address + total_bytes, data_start,
                           host_response.data_len);
     if (status != LIBHOTH_OK) {
@@ -467,7 +555,7 @@ int libhoth_spi_send_and_receive_response(struct libhoth_device* dev,
 
   // Page Program OPCODE + Mailbox Address
   uint8_t pp_buf[5] = {0};
-  pp_buf[0] = SPI_NOR_OPCODE_PAGE_PROGRAM;
+  pp_buf[0] = mode_to_write_opcode(spi_dev->mode);
   int address_len = spi_nor_address(&pp_buf[1], address, address_mode_4b);
   xfer[1] = (struct spi_ioc_transfer){
       .tx_buf = (unsigned long)pp_buf,
@@ -481,11 +569,15 @@ int libhoth_spi_send_and_receive_response(struct libhoth_device* dev,
       .cs_change = 1,
   };
 
+  if (spi_dev->mode != LIBHOTH_SPI_MODE_SINGLE) {
+    uint8_t nbits = mode_to_nbits(spi_dev->mode);
+    xfer[2].tx_nbits = nbits;
+  }
   // Wait for status register is handled by the spidev driver.
 
   // Read opcode + Mailbox Address
   uint8_t rd_buf[5] = {0};
-  rd_buf[0] = SPI_NOR_OPCODE_SLOW_READ;
+  rd_buf[0] = mode_to_read_opcode(spi_dev->mode);
   address_len = spi_nor_address(&rd_buf[1], address, address_mode_4b);
   xfer[3] = (struct spi_ioc_transfer){
       .tx_buf = (unsigned long)rd_buf,
@@ -498,6 +590,11 @@ int libhoth_spi_send_and_receive_response(struct libhoth_device* dev,
       .len = max_response_size,
   };
 
+  if (spi_dev->mode != LIBHOTH_SPI_MODE_SINGLE) {
+    uint8_t nbits = mode_to_nbits(spi_dev->mode);
+    xfer[4].rx_nbits = nbits;
+  }
+
   int rc = LIBHOTH_OK;
   int status = ioctl(spi_dev->fd, SPI_IOC_MESSAGE(5), xfer);
   if (status < 0) {
@@ -564,6 +661,12 @@ int libhoth_spi_close(struct libhoth_device* dev) {
 
   struct libhoth_spi_device* spi_dev =
       (struct libhoth_spi_device*)dev->user_ctx;
+  // Mode settings can be sticky! Restore the original mode to ensure any bad
+  // modesetting does not presist across processes.
+  if (ioctl(spi_dev->fd, SPI_IOC_WR_MODE32, &spi_dev->original_mode) < 0) {
+    // We can't do much here, but we should at least close the fd.
+    perror("Failed to restore SPI mode");
+  }
   close(spi_dev->fd);
   free(dev->user_ctx);
   return LIBHOTH_OK;

transports/libhoth_spi.h

@@ -25,6 +25,12 @@ extern "C" {
 
 struct libhoth_device;
 
+enum libhoth_spi_mode {
+  LIBHOTH_SPI_MODE_SINGLE = 0,
+  LIBHOTH_SPI_MODE_DUAL,
+  LIBHOTH_SPI_MODE_QUAD,
+};
+
 struct libhoth_spi_device_init_options {
   // The device filepath to open
   const char* path;
@@ -34,6 +40,7 @@ struct libhoth_spi_device_init_options {
   int mode;
   int speed;
   int atomic;
+  enum libhoth_spi_mode operation_mode;
   uint32_t device_busy_wait_timeout;
   uint32_t device_busy_wait_check_interval;
   uint32_t timeout_us;
@@ -43,6 +50,8 @@ struct libhoth_spi_device {
   int fd;
   unsigned int mailbox_address;
   bool address_mode_4b;
+  enum libhoth_spi_mode mode;
+  uint32_t original_mode;
 
   void* buffered_request;
   size_t buffered_request_size;
@@ -55,7 +64,10 @@ enum {
   SPI_NOR_OPCODE_READ_STATUS = 0x05,
   SPI_NOR_OPCODE_WRITE_ENABLE = 0x06,
   SPI_NOR_OPCODE_PAGE_PROGRAM = 0x02,
+  SPI_NOR_OPCODE_QUAD_PAGE_PROGRAM = 0x38,
   SPI_NOR_OPCODE_SLOW_READ = 0x03,
+  SPI_NOR_OPCODE_DUAL_READ = 0x3B,
+  SPI_NOR_OPCODE_QUAD_READ = 0x6B,
   SPI_NOR_FLASH_PAGE_SIZE = 256,  // in bytes
 };