From 5eb8eb385599ee459655516e10ca168309e5a5e0 Mon Sep 17 00:00:00 2001 From: Jeroen Domburg Date: Tue, 10 Jan 2017 14:41:12 +0800 Subject: [PATCH] SPI master: rename transaction flags from SPI_* to SPI_TRANS_*, like the documentation says. Also add some explanation about the SPI signals in the documentation --- components/driver/include/driver/spi_master.h | 10 +++---- components/driver/spi_master.c | 28 +++++++++---------- docs/api/spi_master.rst | 21 ++++++++++---- examples/26_spi_master/main/spi_master.c | 4 +-- 4 files changed, 37 insertions(+), 26 deletions(-) diff --git a/components/driver/include/driver/spi_master.h b/components/driver/include/driver/spi_master.h index 4dd8738ad..ea901b992 100644 --- a/components/driver/include/driver/spi_master.h +++ b/components/driver/include/driver/spi_master.h @@ -86,11 +86,11 @@ typedef struct { } spi_device_interface_config_t; -#define SPI_MODE_DIO (1<<0) ///< Transmit/receive data in 2-bit mode -#define SPI_MODE_QIO (1<<1) ///< Transmit/receive data in 4-bit mode -#define SPI_MODE_DIOQIO_ADDR (1<<2) ///< Also transmit address in mode selected by SPI_MODE_DIO/SPI_MODE_QIO -#define SPI_USE_RXDATA (1<<2) ///< Receive into rx_data member of spi_transaction_t instead into memory at rx_buffer. -#define SPI_USE_TXDATA (1<<3) ///< Transmit tx_data member of spi_transaction_t instead of data at tx_buffer. Do not set tx_buffer when using this. +#define SPI_TRANS_MODE_DIO (1<<0) ///< Transmit/receive data in 2-bit mode +#define SPI_TRANS_MODE_QIO (1<<1) ///< Transmit/receive data in 4-bit mode +#define SPI_TRANS_MODE_DIOQIO_ADDR (1<<2) ///< Also transmit address in mode selected by SPI_MODE_DIO/SPI_MODE_QIO +#define SPI_TRANS_USE_RXDATA (1<<2) ///< Receive into rx_data member of spi_transaction_t instead into memory at rx_buffer. +#define SPI_TRANS_USE_TXDATA (1<<3) ///< Transmit tx_data member of spi_transaction_t instead of data at tx_buffer. Do not set tx_buffer when using this. /** * This structure describes one SPI transaction diff --git a/components/driver/spi_master.c b/components/driver/spi_master.c index fd4c5b2e2..1f1ea1ef0 100644 --- a/components/driver/spi_master.c +++ b/components/driver/spi_master.c @@ -452,10 +452,10 @@ static void IRAM_ATTR spi_intr(void *arg) if (host->cur_trans) { //Okay, transaction is done. - if ((host->cur_trans->rx_buffer || (host->cur_trans->flags & SPI_USE_RXDATA)) && host->cur_trans->rxlength<=THRESH_DMA_TRANS) { + if ((host->cur_trans->rx_buffer || (host->cur_trans->flags & SPI_TRANS_USE_RXDATA)) && host->cur_trans->rxlength<=THRESH_DMA_TRANS) { //Need to copy from SPI regs to result buffer. uint32_t *data; - if (host->cur_trans->flags & SPI_USE_RXDATA) { + if (host->cur_trans->flags & SPI_TRANS_USE_RXDATA) { data=(uint32_t*)&host->cur_trans->rx_data[0]; } else { data=(uint32_t*)host->cur_trans->rx_buffer; @@ -557,8 +557,8 @@ static void IRAM_ATTR spi_intr(void *arg) //QIO/DIO host->hw->ctrl.val &= ~(SPI_FREAD_DUAL|SPI_FREAD_QUAD|SPI_FREAD_DIO|SPI_FREAD_QIO); host->hw->user.val &= ~(SPI_FWRITE_DUAL|SPI_FWRITE_QUAD|SPI_FWRITE_DIO|SPI_FWRITE_QIO); - if (trans->flags & SPI_MODE_DIO) { - if (trans->flags & SPI_MODE_DIOQIO_ADDR) { + if (trans->flags & SPI_TRANS_MODE_DIO) { + if (trans->flags & SPI_TRANS_MODE_DIOQIO_ADDR) { host->hw->ctrl.fread_dio=1; host->hw->user.fwrite_dio=1; } else { @@ -566,8 +566,8 @@ static void IRAM_ATTR spi_intr(void *arg) host->hw->user.fwrite_dual=1; } host->hw->ctrl.fastrd_mode=1; - } else if (trans->flags & SPI_MODE_QIO) { - if (trans->flags & SPI_MODE_DIOQIO_ADDR) { + } else if (trans->flags & SPI_TRANS_MODE_QIO) { + if (trans->flags & SPI_TRANS_MODE_DIOQIO_ADDR) { host->hw->ctrl.fread_qio=1; host->hw->user.fwrite_qio=1; } else { @@ -579,9 +579,9 @@ static void IRAM_ATTR spi_intr(void *arg) //Fill DMA descriptors - if (trans->rx_buffer || (trans->flags & SPI_USE_RXDATA)) { + if (trans->rx_buffer || (trans->flags & SPI_TRANS_USE_RXDATA)) { uint32_t *data; - if (trans->flags & SPI_USE_RXDATA) { + if (trans->flags & SPI_TRANS_USE_RXDATA) { data=(uint32_t *)&trans->rx_data[0]; } else { data=trans->rx_buffer; @@ -604,9 +604,9 @@ static void IRAM_ATTR spi_intr(void *arg) host->hw->user.usr_miso=0; } - if (trans->tx_buffer || (trans->flags & SPI_USE_TXDATA)) { + if (trans->tx_buffer || (trans->flags & SPI_TRANS_USE_TXDATA)) { uint32_t *data; - if (trans->flags & SPI_USE_TXDATA) { + if (trans->flags & SPI_TRANS_USE_TXDATA) { data=(uint32_t *)&trans->tx_data[0]; } else { data=(uint32_t *)trans->tx_buffer; @@ -657,10 +657,10 @@ esp_err_t spi_device_queue_trans(spi_device_handle_t handle, spi_transaction_t * { BaseType_t r; SPI_CHECK(handle!=NULL, "invalid dev handle", ESP_ERR_INVALID_ARG); - SPI_CHECK((trans_desc->flags & SPI_USE_RXDATA)==0 ||trans_desc->length <= 32, "rxdata transfer > 32bytes", ESP_ERR_INVALID_ARG); - SPI_CHECK((trans_desc->flags & SPI_USE_TXDATA)==0 ||trans_desc->length <= 32, "txdata transfer > 32bytes", ESP_ERR_INVALID_ARG); - SPI_CHECK(!((trans_desc->flags & (SPI_MODE_DIO|SPI_MODE_QIO)) && (handle->cfg.flags & SPI_DEVICE_3WIRE)), "incompatible iface params", ESP_ERR_INVALID_ARG); - SPI_CHECK(!((trans_desc->flags & (SPI_MODE_DIO|SPI_MODE_QIO)) && (!(handle->cfg.flags & SPI_DEVICE_HALFDUPLEX))), "incompatible iface params", ESP_ERR_INVALID_ARG); + SPI_CHECK((trans_desc->flags & SPI_TRANS_USE_RXDATA)==0 ||trans_desc->length <= 32, "rxdata transfer > 32bytes", ESP_ERR_INVALID_ARG); + SPI_CHECK((trans_desc->flags & SPI_TRANS_USE_TXDATA)==0 ||trans_desc->length <= 32, "txdata transfer > 32bytes", ESP_ERR_INVALID_ARG); + SPI_CHECK(!((trans_desc->flags & (SPI_TRANS_MODE_DIO|SPI_TRANS_MODE_QIO)) && (handle->cfg.flags & SPI_DEVICE_3WIRE)), "incompatible iface params", ESP_ERR_INVALID_ARG); + SPI_CHECK(!((trans_desc->flags & (SPI_TRANS_MODE_DIO|SPI_TRANS_MODE_QIO)) && (!(handle->cfg.flags & SPI_DEVICE_HALFDUPLEX))), "incompatible iface params", ESP_ERR_INVALID_ARG); r=xQueueSend(handle->trans_queue, (void*)&trans_desc, ticks_to_wait); if (!r) return ESP_ERR_TIMEOUT; esp_intr_enable(handle->host->intr); diff --git a/docs/api/spi_master.rst b/docs/api/spi_master.rst index 99f2f6a7c..4d7693c07 100644 --- a/docs/api/spi_master.rst +++ b/docs/api/spi_master.rst @@ -29,6 +29,17 @@ The spi_master driver uses the following terms: * Bus: The SPI bus, common to all SPI devices connected to one host. In general the bus consists of the spid, spiq, spiclk and optionally spiwp and spihd signals. The SPI slaves are connected to these signals in parallel. + + - spiq - Also known as MISO, this is the input of the serial stream into the ESP32 + + - spid - Also known as MOSI, this is the output of the serial stream from the ESP32 + + - spiclk - Clock signal. Each data bit is clocked out or in on the positive or negative edge of this signal + + - spiwp - Write Protect signal. Only used for 4-bit (qio/qout) transactions. + + - spihd - Hold signal. Only used for 4-bit (qio/qout) transactions. + * Device: A SPI slave. Each SPI slave has its own chip select (CS) line, which is made active when a transmission to/from the SPI slave occurs. * Transaction: One instance of CS going active, data transfer from and/or to a device happening, and @@ -113,11 +124,11 @@ Macros .. doxygendefine:: SPI_DEVICE_HALFDUPLEX .. doxygendefine:: SPI_DEVICE_CLK_AS_CS -.. doxygendefine:: SPI_MODE_DIO -.. doxygendefine:: SPI_MODE_QIO -.. doxygendefine:: SPI_MODE_DIOQIO_ADDR -.. doxygendefine:: SPI_USE_RXDATA -.. doxygendefine:: SPI_USE_TXDATA +.. doxygendefine:: SPI_TRANS_MODE_DIO +.. doxygendefine:: SPI_TRANS_MODE_QIO +.. doxygendefine:: SPI_TRANS_MODE_DIOQIO_ADDR +.. doxygendefine:: SPI_TRANS_USE_RXDATA +.. doxygendefine:: SPI_TRANS_USE_TXDATA Type Definitions ^^^^^^^^^^^^^^^^ diff --git a/examples/26_spi_master/main/spi_master.c b/examples/26_spi_master/main/spi_master.c index 1cdbf72ad..2013dfd9c 100644 --- a/examples/26_spi_master/main/spi_master.c +++ b/examples/26_spi_master/main/spi_master.c @@ -168,7 +168,7 @@ void send_line(spi_device_handle_t spi, int ypos, uint16_t *line) trans[x].length=8*4; trans[x].user=(void*)1; } - trans[x].flags=SPI_USE_TXDATA; + trans[x].flags=SPI_TRANS_USE_TXDATA; } trans[0].tx_data[0]=0x2A; //Column Address Set trans[1].tx_data[0]=0; //Start Col High @@ -183,7 +183,7 @@ void send_line(spi_device_handle_t spi, int ypos, uint16_t *line) trans[4].tx_data[0]=0x2C; //memory write trans[5].tx_buffer=line; //finally send the line data trans[5].length=320*2*8; //Data length, in bits - trans[5].flags=0; //undo SPI_USE_TXDATA flag + trans[5].flags=0; //undo SPI_TRANS_USE_TXDATA flag //Queue all transactions. for (x=0; x<6; x++) {