1 // Copyright 2015-2018 Espressif Systems (Shanghai) PTE LTD
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
18 We can initialize a SPI driver, but we don't talk to the SPI driver itself, we address a device. A device essentially
19 is a combination of SPI port and CS pin, plus some information about the specifics of communication to the device
20 (timing, command/address length etc)
22 The essence of the interface to a device is a set of queues; one per device. The idea is that to send something to a SPI
23 device, you allocate a transaction descriptor. It contains some information about the transfer like the lenghth, address,
24 command etc, plus pointers to transmit and receive buffer. The address of this block gets pushed into the transmit queue.
25 The SPI driver does its magic, and sends and retrieves the data eventually. The data gets written to the receive buffers,
26 if needed the transaction descriptor is modified to indicate returned parameters and the entire thing goes into the return
27 queue, where whatever software initiated the transaction can retrieve it.
29 The entire thing is run from the SPI interrupt handler. If SPI is done transmitting/receiving but nothing is in the queue,
30 it will not clear the SPI interrupt but just disable it. This way, when a new thing is sent, pushing the packet into the send
31 queue and re-enabling the interrupt will trigger the interrupt again, which can then take care of the sending.
37 #include "driver/spi_common.h"
38 #include "driver/spi_master.h"
39 #include "soc/dport_reg.h"
40 #include "soc/spi_periph.h"
41 #include "rom/ets_sys.h"
42 #include "esp_types.h"
45 #include "esp_intr_alloc.h"
49 #include "freertos/FreeRTOS.h"
50 #include "freertos/semphr.h"
51 #include "freertos/xtensa_api.h"
52 #include "freertos/task.h"
53 #include "freertos/ringbuf.h"
55 #include "soc/soc_memory_layout.h"
56 #include "soc/dport_reg.h"
57 #include "rom/lldesc.h"
58 #include "driver/gpio.h"
59 #include "driver/periph_ctrl.h"
60 #include "esp_heap_caps.h"
62 typedef struct spi_device_t spi_device_t;
63 typedef typeof(SPI1.clock) spi_clock_reg_t;
65 #define NO_CS 3 //Number of CS pins per SPI host
67 #ifdef CONFIG_SPI_MASTER_ISR_IN_IRAM
68 #define SPI_MASTER_ISR_ATTR IRAM_ATTR
70 #define SPI_MASTER_ISR_ATTR
73 #ifdef CONFIG_SPI_MASTER_IN_IRAM
74 #define SPI_MASTER_ATTR IRAM_ATTR
76 #define SPI_MASTER_ATTR
80 /// struct to hold private transaction data (like tx and rx buffer for DMA).
82 spi_transaction_t *trans;
83 uint32_t *buffer_to_send; //equals to tx_data, if SPI_TRANS_USE_RXDATA is applied; otherwise if original buffer wasn't in DMA-capable memory, this gets the address of a temporary buffer that is;
84 //otherwise sets to the original buffer or NULL if no buffer is assigned.
85 uint32_t *buffer_to_rcv; // similar to buffer_to_send
89 spi_device_t *device[NO_CS];
92 spi_trans_priv cur_trans_buf;
100 spi_bus_config_t bus_cfg;
101 #ifdef CONFIG_PM_ENABLE
102 esp_pm_lock_handle_t pm_lock;
113 struct spi_device_t {
114 QueueHandle_t trans_queue;
115 QueueHandle_t ret_queue;
116 spi_device_interface_config_t cfg;
117 clock_config_t clk_cfg;
121 static spi_host_t *spihost[3];
124 static const char *SPI_TAG = "spi_master";
125 #define SPI_CHECK(a, str, ret_val, ...) \
127 ESP_LOGE(SPI_TAG,"%s(%d): "str, __FUNCTION__, __LINE__, ##__VA_ARGS__); \
132 static void spi_intr(void *arg);
134 esp_err_t spi_bus_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config, int dma_chan)
136 bool spi_chan_claimed, dma_chan_claimed;
137 esp_err_t ret = ESP_OK;
139 /* ToDo: remove this when we have flash operations cooperating with this */
140 SPI_CHECK(host!=SPI_HOST, "SPI1 is not supported", ESP_ERR_NOT_SUPPORTED);
142 SPI_CHECK(host>=SPI_HOST && host<=VSPI_HOST, "invalid host", ESP_ERR_INVALID_ARG);
143 SPI_CHECK( dma_chan >= 0 && dma_chan <= 2, "invalid dma channel", ESP_ERR_INVALID_ARG );
145 spi_chan_claimed=spicommon_periph_claim(host);
146 SPI_CHECK(spi_chan_claimed, "host already in use", ESP_ERR_INVALID_STATE);
148 if ( dma_chan != 0 ) {
149 dma_chan_claimed=spicommon_dma_chan_claim(dma_chan);
150 if ( !dma_chan_claimed ) {
151 spicommon_periph_free( host );
152 SPI_CHECK(dma_chan_claimed, "dma channel already in use", ESP_ERR_INVALID_STATE);
156 spihost[host]=malloc(sizeof(spi_host_t));
157 if (spihost[host]==NULL) {
158 ret = ESP_ERR_NO_MEM;
161 memset(spihost[host], 0, sizeof(spi_host_t));
162 memcpy( &spihost[host]->bus_cfg, bus_config, sizeof(spi_bus_config_t));
163 #ifdef CONFIG_PM_ENABLE
164 err = esp_pm_lock_create(ESP_PM_APB_FREQ_MAX, 0, "spi_master",
165 &spihost[host]->pm_lock);
170 #endif //CONFIG_PM_ENABLE
172 err = spicommon_bus_initialize_io(host, bus_config, dma_chan, SPICOMMON_BUSFLAG_MASTER|bus_config->flags, &spihost[host]->flags);
178 spihost[host]->dma_chan=dma_chan;
180 spihost[host]->max_transfer_sz = 64;
182 //See how many dma descriptors we need and allocate them
183 int dma_desc_ct=(bus_config->max_transfer_sz+SPI_MAX_DMA_LEN-1)/SPI_MAX_DMA_LEN;
184 if (dma_desc_ct==0) dma_desc_ct=1; //default to 4k when max is not given
185 spihost[host]->max_transfer_sz = dma_desc_ct*SPI_MAX_DMA_LEN;
186 spihost[host]->dmadesc_tx=heap_caps_malloc(sizeof(lldesc_t)*dma_desc_ct, MALLOC_CAP_DMA);
187 spihost[host]->dmadesc_rx=heap_caps_malloc(sizeof(lldesc_t)*dma_desc_ct, MALLOC_CAP_DMA);
188 if (!spihost[host]->dmadesc_tx || !spihost[host]->dmadesc_rx) {
189 ret = ESP_ERR_NO_MEM;
194 int flags = ESP_INTR_FLAG_INTRDISABLED;
195 #ifdef CONFIG_SPI_MASTER_ISR_IN_IRAM
196 flags |= ESP_INTR_FLAG_IRAM;
198 err = esp_intr_alloc(spicommon_irqsource_for_host(host), flags, spi_intr, (void*)spihost[host], &spihost[host]->intr);
203 spihost[host]->hw=spicommon_hw_for_host(host);
205 spihost[host]->cur_cs = NO_CS;
206 spihost[host]->prev_cs = NO_CS;
209 spihost[host]->hw->dma_conf.val|=SPI_OUT_RST|SPI_IN_RST|SPI_AHBM_RST|SPI_AHBM_FIFO_RST;
210 spihost[host]->hw->dma_out_link.start=0;
211 spihost[host]->hw->dma_in_link.start=0;
212 spihost[host]->hw->dma_conf.val&=~(SPI_OUT_RST|SPI_IN_RST|SPI_AHBM_RST|SPI_AHBM_FIFO_RST);
214 spihost[host]->hw->ctrl2.val=0;
216 //master use all 64 bytes of the buffer
217 spihost[host]->hw->user.usr_miso_highpart=0;
218 spihost[host]->hw->user.usr_mosi_highpart=0;
220 //Disable unneeded ints
221 spihost[host]->hw->slave.rd_buf_done=0;
222 spihost[host]->hw->slave.wr_buf_done=0;
223 spihost[host]->hw->slave.rd_sta_done=0;
224 spihost[host]->hw->slave.wr_sta_done=0;
225 spihost[host]->hw->slave.rd_buf_inten=0;
226 spihost[host]->hw->slave.wr_buf_inten=0;
227 spihost[host]->hw->slave.rd_sta_inten=0;
228 spihost[host]->hw->slave.wr_sta_inten=0;
230 //Force a transaction done interrupt. This interrupt won't fire yet because we initialized the SPI interrupt as
231 //disabled. This way, we can just enable the SPI interrupt and the interrupt handler will kick in, handling
232 //any transactions that are queued.
233 spihost[host]->hw->slave.trans_inten=1;
234 spihost[host]->hw->slave.trans_done=1;
240 free(spihost[host]->dmadesc_tx);
241 free(spihost[host]->dmadesc_rx);
242 #ifdef CONFIG_PM_ENABLE
243 if (spihost[host]->pm_lock) {
244 esp_pm_lock_delete(spihost[host]->pm_lock);
249 spicommon_periph_free(host);
250 spicommon_dma_chan_free(dma_chan);
254 esp_err_t spi_bus_free(spi_host_device_t host)
257 SPI_CHECK(host>=SPI_HOST && host<=VSPI_HOST, "invalid host", ESP_ERR_INVALID_ARG);
258 SPI_CHECK(spihost[host]!=NULL, "host not in use", ESP_ERR_INVALID_STATE);
259 for (x=0; x<NO_CS; x++) {
260 SPI_CHECK(spihost[host]->device[x]==NULL, "not all CSses freed", ESP_ERR_INVALID_STATE);
262 spicommon_bus_free_io_cfg(&spihost[host]->bus_cfg);
264 if ( spihost[host]->dma_chan > 0 ) {
265 spicommon_dma_chan_free ( spihost[host]->dma_chan );
267 #ifdef CONFIG_PM_ENABLE
268 esp_pm_lock_delete(spihost[host]->pm_lock);
270 spihost[host]->hw->slave.trans_inten=0;
271 spihost[host]->hw->slave.trans_done=0;
272 esp_intr_free(spihost[host]->intr);
273 spicommon_periph_free(host);
274 free(spihost[host]->dmadesc_tx);
275 free(spihost[host]->dmadesc_rx);
281 void spi_get_timing(bool gpio_is_used, int input_delay_ns, int eff_clk, int* dummy_o, int* cycles_remain_o)
283 const int apbclk_kHz = APB_CLK_FREQ/1000;
284 const int apbclk_n = APB_CLK_FREQ/eff_clk;
285 const int gpio_delay_ns=(gpio_is_used?25:0);
287 //calculate how many apb clocks a period has, the 1 is to compensate in case ``input_delay_ns`` is rounded off.
288 int apb_period_n = (1 + input_delay_ns + gpio_delay_ns)*apbclk_kHz/1000/1000;
289 int dummy_required = apb_period_n/apbclk_n;
292 if (dummy_required > 0) {
293 //due to the clock delay between master and slave, there's a range in which data is random
294 //give MISO a delay if needed to make sure we sample at the time MISO is stable
295 miso_delay = (dummy_required+1)*apbclk_n-apb_period_n-1;
297 //if the dummy is not required, maybe we should also delay half a SPI clock if the data comes too early
298 if (apb_period_n*4 <= apbclk_n) miso_delay = -1;
300 if (dummy_o!=NULL) *dummy_o = dummy_required;
301 if (cycles_remain_o!=NULL) *cycles_remain_o = miso_delay;
302 ESP_LOGD(SPI_TAG,"eff: %d, limit: %dk(/%d), %d dummy, %d delay", eff_clk/1000, apbclk_kHz/(apb_period_n+1), apb_period_n, dummy_required, miso_delay);
305 int spi_get_freq_limit(bool gpio_is_used, int input_delay_ns)
307 const int apbclk_kHz = APB_CLK_FREQ/1000;
308 const int gpio_delay_ns=(gpio_is_used?25:0);
310 //calculate how many apb clocks a period has, the 1 is to compensate in case ``input_delay_ns`` is rounded off.
311 int apb_period_n = (1 + input_delay_ns + gpio_delay_ns)*apbclk_kHz/1000/1000;
312 return APB_CLK_FREQ/(apb_period_n+1);
316 Add a device. This allocates a CS line for the device, allocates memory for the device structure and hooks
317 up the CS pin to whatever is specified.
319 esp_err_t spi_bus_add_device(spi_host_device_t host, const spi_device_interface_config_t *dev_config, spi_device_handle_t *handle)
322 int apbclk=APB_CLK_FREQ;
328 spi_clock_reg_t clk_reg;
329 SPI_CHECK(host>=SPI_HOST && host<=VSPI_HOST, "invalid host", ESP_ERR_INVALID_ARG);
330 SPI_CHECK(spihost[host]!=NULL, "host not initialized", ESP_ERR_INVALID_STATE);
331 SPI_CHECK(dev_config->spics_io_num < 0 || GPIO_IS_VALID_OUTPUT_GPIO(dev_config->spics_io_num), "spics pin invalid", ESP_ERR_INVALID_ARG);
332 SPI_CHECK(dev_config->clock_speed_hz > 0, "invalid sclk speed", ESP_ERR_INVALID_ARG);
333 for (freecs=0; freecs<NO_CS; freecs++) {
334 //See if this slot is free; reserve if it is by putting a dummy pointer in the slot. We use an atomic compare&swap to make this thread-safe.
335 if (__sync_bool_compare_and_swap(&spihost[host]->device[freecs], NULL, (spi_device_t *)1)) break;
337 SPI_CHECK(freecs!=NO_CS, "no free cs pins for host", ESP_ERR_NOT_FOUND);
338 //The hardware looks like it would support this, but actually setting cs_ena_pretrans when transferring in full
339 //duplex mode does absolutely nothing on the ESP32.
340 SPI_CHECK( dev_config->cs_ena_pretrans <= 1 || (dev_config->address_bits == 0 && dev_config->command_bits == 0) ||
341 (dev_config->flags & SPI_DEVICE_HALFDUPLEX), "In full-duplex mode, only support cs pretrans delay = 1 and without address_bits and command_bits", ESP_ERR_INVALID_ARG);
343 duty_cycle = (dev_config->duty_cycle_pos==0? 128: dev_config->duty_cycle_pos);
344 eff_clk = spi_cal_clock(apbclk, dev_config->clock_speed_hz, duty_cycle, (uint32_t*)&clk_reg);
345 int freq_limit = spi_get_freq_limit(!(spihost[host]->flags&SPICOMMON_BUSFLAG_NATIVE_PINS), dev_config->input_delay_ns);
346 //GPIO matrix can only change data at 80Mhz rate, which only allows 40MHz SPI clock.
347 SPI_CHECK(eff_clk <= 40*1000*1000 || spihost[host]->flags&SPICOMMON_BUSFLAG_NATIVE_PINS, "80MHz only supported on iomux pins", ESP_ERR_INVALID_ARG);
348 //Speed >=40MHz over GPIO matrix needs a dummy cycle, but these don't work for full-duplex connections.
349 spi_get_timing(!(spihost[host]->flags&SPICOMMON_BUSFLAG_NATIVE_PINS), dev_config->input_delay_ns, eff_clk, &dummy_required, &miso_delay);
350 SPI_CHECK( dev_config->flags & SPI_DEVICE_HALFDUPLEX || dummy_required == 0 ||
351 dev_config->flags & SPI_DEVICE_NO_DUMMY,
352 "When GPIO matrix is used in full-duplex mode at frequency > %.1fMHz, device cannot read correct data.\n\
353 Please note the SPI can only work at divisors of 80MHz, and the driver always tries to find the closest frequency to your configuration.\n\
354 Specify ``SPI_DEVICE_NO_DUMMY`` to ignore this checking. Then you can output data at higher speed, or read data at your own risk.",
355 ESP_ERR_INVALID_ARG, freq_limit/1000./1000 );
357 //Allocate memory for device
358 spi_device_t *dev=malloc(sizeof(spi_device_t));
359 if (dev==NULL) goto nomem;
360 memset(dev, 0, sizeof(spi_device_t));
361 spihost[host]->device[freecs]=dev;
363 //Allocate queues, set defaults
364 dev->trans_queue=xQueueCreate(dev_config->queue_size, sizeof(spi_trans_priv));
365 dev->ret_queue=xQueueCreate(dev_config->queue_size, sizeof(spi_trans_priv));
366 if (!dev->trans_queue || !dev->ret_queue) goto nomem;
367 dev->host=spihost[host];
369 //We want to save a copy of the dev config in the dev struct.
370 memcpy(&dev->cfg, dev_config, sizeof(spi_device_interface_config_t));
371 dev->cfg.duty_cycle_pos = duty_cycle;
372 // TODO: if we have to change the apb clock among transactions, re-calculate this each time the apb clock lock is acquired.
373 dev->clk_cfg= (clock_config_t) {
375 .dummy_num = dummy_required,
377 .miso_delay = miso_delay,
380 //Set CS pin, CS options
381 if (dev_config->spics_io_num >= 0) {
382 gpio_set_direction(dev_config->spics_io_num, GPIO_MODE_OUTPUT);
383 spicommon_cs_initialize(host, dev_config->spics_io_num, freecs, !(spihost[host]->flags&SPICOMMON_BUSFLAG_NATIVE_PINS));
385 if (dev_config->flags&SPI_DEVICE_CLK_AS_CS) {
386 spihost[host]->hw->pin.master_ck_sel |= (1<<freecs);
388 spihost[host]->hw->pin.master_ck_sel &= (1<<freecs);
390 if (dev_config->flags&SPI_DEVICE_POSITIVE_CS) {
391 spihost[host]->hw->pin.master_cs_pol |= (1<<freecs);
393 spihost[host]->hw->pin.master_cs_pol &= (1<<freecs);
395 spihost[host]->hw->ctrl2.mosi_delay_mode = 0;
396 spihost[host]->hw->ctrl2.mosi_delay_num = 0;
398 ESP_LOGD(SPI_TAG, "SPI%d: New device added to CS%d, effective clock: %dkHz", host, freecs, dev->clk_cfg.eff_clk/1000);
403 if (dev->trans_queue) vQueueDelete(dev->trans_queue);
404 if (dev->ret_queue) vQueueDelete(dev->ret_queue);
407 return ESP_ERR_NO_MEM;
410 esp_err_t spi_bus_remove_device(spi_device_handle_t handle)
413 SPI_CHECK(handle!=NULL, "invalid handle", ESP_ERR_INVALID_ARG);
414 //These checks aren't exhaustive; another thread could sneak in a transaction inbetween. These are only here to
415 //catch design errors and aren't meant to be triggered during normal operation.
416 SPI_CHECK(uxQueueMessagesWaiting(handle->trans_queue)==0, "Have unfinished transactions", ESP_ERR_INVALID_STATE);
417 SPI_CHECK(handle->host->cur_cs == NO_CS || handle->host->device[handle->host->cur_cs]!=handle, "Have unfinished transactions", ESP_ERR_INVALID_STATE);
418 SPI_CHECK(uxQueueMessagesWaiting(handle->ret_queue)==0, "Have unfinished transactions", ESP_ERR_INVALID_STATE);
421 int spics_io_num = handle->cfg.spics_io_num;
422 if (spics_io_num >= 0) spicommon_cs_free_io(spics_io_num);
425 vQueueDelete(handle->trans_queue);
426 vQueueDelete(handle->ret_queue);
427 //Remove device from list of csses and free memory
428 for (x=0; x<NO_CS; x++) {
429 if (handle->host->device[x] == handle){
430 handle->host->device[x]=NULL;
431 if ( x == handle->host->prev_cs ) handle->host->prev_cs = NO_CS;
438 static int spi_freq_for_pre_n(int fapb, int pre, int n) {
439 return (fapb / (pre * n));
442 int spi_cal_clock(int fapb, int hz, int duty_cycle, uint32_t *reg_o)
447 //In hw, n, h and l are 1-64, pre is 1-8K. Value written to register is one lower than used value.
448 if (hz>((fapb/4)*3)) {
449 //Using Fapb directly will give us the best result here.
454 reg.clk_equ_sysclk=1;
457 //For best duty cycle resolution, we want n to be as close to 32 as possible, but
458 //we also need a pre/n combo that gets us as close as possible to the intended freq.
459 //To do this, we bruteforce n and calculate the best pre to go along with that.
460 //If there's a choice between pre/n combos that give the same result, use the one
467 for (n=2; n<=64; n++) { //Start at 2: we need to be able to set h/l so we have at least one high and one low pulse.
468 //Effectively, this does pre=round((fapb/n)/hz).
469 pre=((fapb/n)+(hz/2))/hz;
471 if (pre>8192) pre=8192;
472 errval=abs(spi_freq_for_pre_n(fapb, pre, n)-hz);
473 if (bestn==-1 || errval<=besterr) {
483 //This effectively does round((duty_cycle*n)/256)
484 h=(duty_cycle*n+127)/256;
487 reg.clk_equ_sysclk=0;
489 reg.clkdiv_pre=pre-1;
492 eff_clk=spi_freq_for_pre_n(fapb, pre, n);
494 if ( reg_o != NULL ) *reg_o = reg.val;
499 * Set the spi clock according to pre-calculated register value.
501 static inline void spi_set_clock(spi_dev_t *hw, spi_clock_reg_t reg) {
502 hw->clock.val = reg.val;
505 //This is run in interrupt context and apart from initialization and destruction, this is the only code
506 //touching the host (=spihost[x]) variable. The rest of the data arrives in queues. That is why there are
507 //no muxes in this code.
508 static void SPI_MASTER_ISR_ATTR spi_intr(void *arg)
512 BaseType_t do_yield=pdFALSE;
513 spi_trans_priv *trans_buf=NULL;
514 spi_transaction_t *trans=NULL;
515 spi_host_t *host=(spi_host_t*)arg;
517 //Ignore all but the trans_done int.
518 if (!host->hw->slave.trans_done) return;
520 /*------------ deal with the in-flight transaction -----------------*/
521 if (host->cur_cs != NO_CS) {
522 spi_transaction_t *cur_trans = host->cur_trans_buf.trans;
523 //Okay, transaction is done.
524 if (host->cur_trans_buf.buffer_to_rcv && host->dma_chan == 0 ) {
525 //Need to copy from SPI regs to result buffer.
526 for (int x=0; x < cur_trans->rxlength; x+=32) {
527 //Do a memcpy to get around possible alignment issues in rx_buffer
528 uint32_t word=host->hw->data_buf[x/32];
529 int len=cur_trans->rxlength-x;
531 memcpy(&host->cur_trans_buf.buffer_to_rcv[x/32], &word, (len+7)/8);
534 //Call post-transaction callback, if any
535 if (host->device[host->cur_cs]->cfg.post_cb) host->device[host->cur_cs]->cfg.post_cb(cur_trans);
536 //Return transaction descriptor.
537 xQueueSendFromISR(host->device[host->cur_cs]->ret_queue, &host->cur_trans_buf, &do_yield);
538 host->cur_cs = NO_CS;
540 //Tell common code DMA workaround that our DMA channel is idle. If needed, the code will do a DMA reset.
541 if (host->dma_chan) spicommon_dmaworkaround_idle(host->dma_chan);
543 /*------------ new transaction starts here ------------------*/
544 //ToDo: This is a stupidly simple low-cs-first priority scheme. Make this configurable somehow. - JD
545 for (i=0; i<NO_CS; i++) {
546 if (host->device[i]) {
547 r=xQueueReceiveFromISR(host->device[i]->trans_queue, &host->cur_trans_buf, &do_yield);
548 trans_buf = &host->cur_trans_buf;
549 //Stop looking if we have a transaction to send.
554 //No packet waiting. Disable interrupt.
555 esp_intr_disable(host->intr);
556 #ifdef CONFIG_PM_ENABLE
557 //Release APB frequency lock
558 esp_pm_lock_release(host->pm_lock);
561 host->hw->slave.trans_done=0; //clear int bit
562 //We have a transaction. Send it.
563 spi_device_t *dev=host->device[i];
564 trans = trans_buf->trans;
566 //We should be done with the transmission.
567 assert(host->hw->cmd.usr == 0);
569 //Reconfigure according to device settings, but only if we change CSses.
570 if (i!=host->prev_cs) {
571 spi_set_clock(host->hw, dev->clk_cfg.reg);
572 //Configure bit order
573 host->hw->ctrl.rd_bit_order=(dev->cfg.flags & SPI_DEVICE_RXBIT_LSBFIRST)?1:0;
574 host->hw->ctrl.wr_bit_order=(dev->cfg.flags & SPI_DEVICE_TXBIT_LSBFIRST)?1:0;
577 if (dev->cfg.mode==0) {
578 host->hw->pin.ck_idle_edge=0;
579 host->hw->user.ck_out_edge=0;
580 } else if (dev->cfg.mode==1) {
581 host->hw->pin.ck_idle_edge=0;
582 host->hw->user.ck_out_edge=1;
583 } else if (dev->cfg.mode==2) {
584 host->hw->pin.ck_idle_edge=1;
585 host->hw->user.ck_out_edge=1;
586 } else if (dev->cfg.mode==3) {
587 host->hw->pin.ck_idle_edge=1;
588 host->hw->user.ck_out_edge=0;
590 //Configure misc stuff
591 host->hw->user.doutdin=(dev->cfg.flags & SPI_DEVICE_HALFDUPLEX)?0:1;
592 host->hw->user.sio=(dev->cfg.flags & SPI_DEVICE_3WIRE)?1:0;
594 host->hw->ctrl2.setup_time=dev->cfg.cs_ena_pretrans-1;
595 host->hw->user.cs_setup=dev->cfg.cs_ena_pretrans?1:0;
596 //set hold_time to 0 will not actually append delay to CS
597 //set it to 1 since we do need at least one clock of hold time in most cases
598 host->hw->ctrl2.hold_time=dev->cfg.cs_ena_posttrans;
599 if ( host->hw->ctrl2.hold_time == 0 ) host->hw->ctrl2.hold_time = 1;
600 host->hw->user.cs_hold=1;
603 host->hw->pin.cs0_dis=(i==0)?0:1;
604 host->hw->pin.cs1_dis=(i==1)?0:1;
605 host->hw->pin.cs2_dis=(i==2)?0:1;
608 //Reset SPI peripheral
609 host->hw->dma_conf.val |= SPI_OUT_RST|SPI_IN_RST|SPI_AHBM_RST|SPI_AHBM_FIFO_RST;
610 host->hw->dma_out_link.start=0;
611 host->hw->dma_in_link.start=0;
612 host->hw->dma_conf.val &= ~(SPI_OUT_RST|SPI_IN_RST|SPI_AHBM_RST|SPI_AHBM_FIFO_RST);
613 host->hw->dma_conf.out_data_burst_en=1;
614 host->hw->dma_conf.indscr_burst_en=1;
615 host->hw->dma_conf.outdscr_burst_en=1;
616 //Set up QIO/DIO if needed
617 host->hw->ctrl.val &= ~(SPI_FREAD_DUAL|SPI_FREAD_QUAD|SPI_FREAD_DIO|SPI_FREAD_QIO);
618 host->hw->user.val &= ~(SPI_FWRITE_DUAL|SPI_FWRITE_QUAD|SPI_FWRITE_DIO|SPI_FWRITE_QIO);
619 if (trans->flags & SPI_TRANS_MODE_DIO) {
620 if (trans->flags & SPI_TRANS_MODE_DIOQIO_ADDR) {
621 host->hw->ctrl.fread_dio=1;
622 host->hw->user.fwrite_dio=1;
624 host->hw->ctrl.fread_dual=1;
625 host->hw->user.fwrite_dual=1;
627 host->hw->ctrl.fastrd_mode=1;
628 } else if (trans->flags & SPI_TRANS_MODE_QIO) {
629 if (trans->flags & SPI_TRANS_MODE_DIOQIO_ADDR) {
630 host->hw->ctrl.fread_qio=1;
631 host->hw->user.fwrite_qio=1;
633 host->hw->ctrl.fread_quad=1;
634 host->hw->user.fwrite_quad=1;
636 host->hw->ctrl.fastrd_mode=1;
639 //Fill DMA descriptors
641 if (trans_buf->buffer_to_rcv) {
642 if (host->dma_chan == 0) {
643 //No need to setup anything; we'll copy the result out of the work registers directly later.
645 spicommon_dmaworkaround_transfer_active(host->dma_chan); //mark channel as active
646 spicommon_setup_dma_desc_links(host->dmadesc_rx, ((trans->rxlength+7)/8), (uint8_t*)trans_buf->buffer_to_rcv, true);
647 host->hw->dma_in_link.addr=(int)(&host->dmadesc_rx[0]) & 0xFFFFF;
648 host->hw->dma_in_link.start=1;
650 //when no_dummy is not set and in half-duplex mode, sets the dummy bit if RX phase exist
651 if (((dev->cfg.flags&SPI_DEVICE_NO_DUMMY)==0) && (dev->cfg.flags&SPI_DEVICE_HALFDUPLEX)) {
652 extra_dummy=dev->clk_cfg.dummy_num;
655 //DMA temporary workaround: let RX DMA work somehow to avoid the issue in ESP32 v0/v1 silicon
656 if (host->dma_chan != 0 ) {
657 host->hw->dma_in_link.addr=0;
658 host->hw->dma_in_link.start=1;
663 if (trans_buf->buffer_to_send) {
664 if (host->dma_chan == 0) {
665 //Need to copy data to registers manually
666 for (int x=0; x < trans->length; x+=32) {
667 //Use memcpy to get around alignment issues for txdata
669 memcpy(&word, &trans_buf->buffer_to_send[x/32], 4);
670 host->hw->data_buf[(x/32)]=word;
673 spicommon_dmaworkaround_transfer_active(host->dma_chan); //mark channel as active
674 spicommon_setup_dma_desc_links(host->dmadesc_tx, (trans->length+7)/8, (uint8_t*)trans_buf->buffer_to_send, false);
675 host->hw->dma_out_link.addr=(int)(&host->dmadesc_tx[0]) & 0xFFFFF;
676 host->hw->dma_out_link.start=1;
680 //SPI iface needs to be configured for a delay in some cases.
681 //configure dummy bits
682 host->hw->user.usr_dummy=(dev->cfg.dummy_bits+extra_dummy)?1:0;
683 host->hw->user1.usr_dummy_cyclelen=dev->cfg.dummy_bits+extra_dummy-1;
685 int miso_long_delay = 0;
686 if (dev->clk_cfg.miso_delay<0) {
687 //if the data comes too late, delay half a SPI clock to improve reading
689 host->hw->ctrl2.miso_delay_num = 0;
691 //if the data is so fast that dummy_bit is used, delay some apb clocks to meet the timing
692 host->hw->ctrl2.miso_delay_num = (extra_dummy? dev->clk_cfg.miso_delay: 0);
695 if (dev->cfg.mode==0) {
696 host->hw->ctrl2.miso_delay_mode=miso_long_delay?2:0;
697 } else if (dev->cfg.mode==1) {
698 host->hw->ctrl2.miso_delay_mode=miso_long_delay?1:0;
699 } else if (dev->cfg.mode==2) {
700 host->hw->ctrl2.miso_delay_mode=miso_long_delay?1:0;
701 } else if (dev->cfg.mode==3) {
702 host->hw->ctrl2.miso_delay_mode=miso_long_delay?2:0;
705 host->hw->mosi_dlen.usr_mosi_dbitlen=trans->length-1;
706 if ( dev->cfg.flags & SPI_DEVICE_HALFDUPLEX ) {
707 host->hw->miso_dlen.usr_miso_dbitlen=trans->rxlength-1;
709 //rxlength is not used in full-duplex mode
710 host->hw->miso_dlen.usr_miso_dbitlen=trans->length-1;
713 //Configure bit sizes, load addr and command
716 if (!(dev->cfg.flags & SPI_DEVICE_HALFDUPLEX) && dev->cfg.cs_ena_pretrans != 0) {
717 /* The command and address phase is not compatible with cs_ena_pretrans
718 * in full duplex mode.
723 if (trans->flags & SPI_TRANS_VARIABLE_CMD) {
724 cmdlen = ((spi_transaction_ext_t *)trans)->command_bits;
726 cmdlen = dev->cfg.command_bits;
728 if (trans->flags & SPI_TRANS_VARIABLE_ADDR) {
729 addrlen = ((spi_transaction_ext_t *)trans)->address_bits;
731 addrlen = dev->cfg.address_bits;
735 host->hw->user1.usr_addr_bitlen=addrlen-1;
736 host->hw->user2.usr_command_bitlen=cmdlen-1;
737 host->hw->user.usr_addr=addrlen?1:0;
738 host->hw->user.usr_command=cmdlen?1:0;
740 /* Output command will be sent from bit 7 to 0 of command_value, and
741 * then bit 15 to 8 of the same register field. Shift and swap to send
744 host->hw->user2.usr_command_value = SPI_SWAP_DATA_TX(trans->cmd, cmdlen);
746 // shift the address to MSB of addr (and maybe slv_wr_status) register.
747 // output address will be sent from MSB to LSB of addr register, then comes the MSB to LSB of slv_wr_status register.
749 host->hw->addr = trans->addr >> (addrlen- 32);
750 host->hw->slv_wr_status = trans->addr << (64 - addrlen);
752 host->hw->addr = trans->addr << (32 - addrlen);
755 host->hw->user.usr_mosi=( (!(dev->cfg.flags & SPI_DEVICE_HALFDUPLEX) && trans_buf->buffer_to_rcv) || trans_buf->buffer_to_send)?1:0;
756 host->hw->user.usr_miso=(trans_buf->buffer_to_rcv)?1:0;
758 //Call pre-transmission callback, if any
759 if (dev->cfg.pre_cb) dev->cfg.pre_cb(trans);
763 if (do_yield) portYIELD_FROM_ISR();
767 esp_err_t SPI_MASTER_ATTR spi_device_queue_trans(spi_device_handle_t handle, spi_transaction_t *trans_desc, TickType_t ticks_to_wait)
769 esp_err_t ret = ESP_OK;
771 SPI_CHECK(handle!=NULL, "invalid dev handle", ESP_ERR_INVALID_ARG);
772 //check transmission length
773 SPI_CHECK((trans_desc->flags & SPI_TRANS_USE_RXDATA)==0 ||trans_desc->rxlength <= 32, "rxdata transfer > 32 bits without configured DMA", ESP_ERR_INVALID_ARG);
774 SPI_CHECK((trans_desc->flags & SPI_TRANS_USE_TXDATA)==0 ||trans_desc->length <= 32, "txdata transfer > 32 bits without configured DMA", ESP_ERR_INVALID_ARG);
775 SPI_CHECK(trans_desc->length <= handle->host->max_transfer_sz*8, "txdata transfer > host maximum", ESP_ERR_INVALID_ARG);
776 SPI_CHECK(trans_desc->rxlength <= handle->host->max_transfer_sz*8, "rxdata transfer > host maximum", ESP_ERR_INVALID_ARG);
777 SPI_CHECK((handle->cfg.flags & SPI_DEVICE_HALFDUPLEX) || trans_desc->rxlength <= trans_desc->length, "rx length > tx length in full duplex mode", ESP_ERR_INVALID_ARG);
779 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);
780 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);
781 SPI_CHECK( !(handle->cfg.flags & SPI_DEVICE_HALFDUPLEX) || handle->host->dma_chan == 0 || !(trans_desc->flags & SPI_TRANS_USE_RXDATA || trans_desc->rx_buffer != NULL)
782 || !(trans_desc->flags & SPI_TRANS_USE_TXDATA || trans_desc->tx_buffer!=NULL), "SPI half duplex mode does not support using DMA with both MOSI and MISO phases.", ESP_ERR_INVALID_ARG );
783 //In Full duplex mode, default rxlength to be the same as length, if not filled in.
784 // set rxlength to length is ok, even when rx buffer=NULL
785 if (trans_desc->rxlength==0 && !(handle->cfg.flags & SPI_DEVICE_HALFDUPLEX)) {
786 trans_desc->rxlength=trans_desc->length;
789 spi_trans_priv trans_buf;
790 memset( &trans_buf, 0, sizeof(spi_trans_priv) );
791 trans_buf.trans = trans_desc;
794 if ( trans_desc->flags & SPI_TRANS_USE_RXDATA ) {
795 trans_buf.buffer_to_rcv = (uint32_t*)&trans_desc->rx_data[0];
797 //if not use RXDATA neither rx_buffer, buffer_to_rcv assigned to NULL
798 trans_buf.buffer_to_rcv = trans_desc->rx_buffer;
800 if ( trans_buf.buffer_to_rcv && handle->host->dma_chan && (!esp_ptr_dma_capable( trans_buf.buffer_to_rcv ) || ((int)trans_buf.buffer_to_rcv%4!=0)) ) {
801 //if rxbuf in the desc not DMA-capable, malloc a new one. The rx buffer need to be length of multiples of 32 bits to avoid heap corruption.
802 ESP_LOGV( SPI_TAG, "Allocate RX buffer for DMA" );
803 trans_buf.buffer_to_rcv = heap_caps_malloc((trans_desc->rxlength+31)/8, MALLOC_CAP_DMA);
804 if ( trans_buf.buffer_to_rcv==NULL ) {
805 ret = ESP_ERR_NO_MEM;
810 const uint32_t *txdata;
812 if ( trans_desc->flags & SPI_TRANS_USE_TXDATA ) {
813 txdata = (uint32_t*)&trans_desc->tx_data[0];
815 //if not use TXDATA neither tx_buffer, tx data assigned to NULL
816 txdata = trans_desc->tx_buffer ;
818 if ( txdata && handle->host->dma_chan && !esp_ptr_dma_capable( txdata )) {
819 //if txbuf in the desc not DMA-capable, malloc a new one
820 ESP_LOGV( SPI_TAG, "Allocate TX buffer for DMA" );
821 trans_buf.buffer_to_send = heap_caps_malloc((trans_desc->length+7)/8, MALLOC_CAP_DMA);
822 if ( trans_buf.buffer_to_send==NULL ) {
823 ret = ESP_ERR_NO_MEM;
826 memcpy( trans_buf.buffer_to_send, txdata, (trans_desc->length+7)/8 );
828 // else use the original buffer (forced-conversion) or assign to NULL
829 trans_buf.buffer_to_send = (uint32_t*)txdata;
832 #ifdef CONFIG_PM_ENABLE
833 esp_pm_lock_acquire(handle->host->pm_lock);
835 r=xQueueSend(handle->trans_queue, (void*)&trans_buf, ticks_to_wait);
837 ret = ESP_ERR_TIMEOUT;
838 #ifdef CONFIG_PM_ENABLE
839 //Release APB frequency lock
840 esp_pm_lock_release(handle->host->pm_lock);
844 esp_intr_enable(handle->host->intr);
848 // free malloc-ed buffer (if needed) before return.
849 if ( (void*)trans_buf.buffer_to_rcv != trans_desc->rx_buffer && (void*)trans_buf.buffer_to_rcv != &trans_desc->rx_data[0] ) {
850 free( trans_buf.buffer_to_rcv );
852 if ( (void*)trans_buf.buffer_to_send!= trans_desc->tx_buffer && (void*)trans_buf.buffer_to_send != &trans_desc->tx_data[0] ) {
853 free( trans_buf.buffer_to_send );
855 assert( ret != ESP_OK );
859 esp_err_t SPI_MASTER_ATTR spi_device_get_trans_result(spi_device_handle_t handle, spi_transaction_t **trans_desc, TickType_t ticks_to_wait)
862 spi_trans_priv trans_buf;
864 SPI_CHECK(handle!=NULL, "invalid dev handle", ESP_ERR_INVALID_ARG);
865 r=xQueueReceive(handle->ret_queue, (void*)&trans_buf, ticks_to_wait);
867 // The memory occupied by rx and tx DMA buffer destroyed only when receiving from the queue (transaction finished).
868 // If timeout, wait and retry.
869 // Every on-flight transaction request occupies internal memory as DMA buffer if needed.
870 return ESP_ERR_TIMEOUT;
873 (*trans_desc) = trans_buf.trans;
875 if ( (void*)trans_buf.buffer_to_send != &(*trans_desc)->tx_data[0] && trans_buf.buffer_to_send != (*trans_desc)->tx_buffer ) {
876 free( trans_buf.buffer_to_send );
879 //copy data from temporary DMA-capable buffer back to IRAM buffer and free the temporary one.
880 if ( (void*)trans_buf.buffer_to_rcv != &(*trans_desc)->rx_data[0] && trans_buf.buffer_to_rcv != (*trans_desc)->rx_buffer ) {
881 if ( (*trans_desc)->flags & SPI_TRANS_USE_RXDATA ) {
882 memcpy( (uint8_t*)&(*trans_desc)->rx_data[0], trans_buf.buffer_to_rcv, ((*trans_desc)->rxlength+7)/8 );
884 memcpy( (*trans_desc)->rx_buffer, trans_buf.buffer_to_rcv, ((*trans_desc)->rxlength+7)/8 );
886 free( trans_buf.buffer_to_rcv );
892 //Porcelain to do one blocking transmission.
893 esp_err_t SPI_MASTER_ATTR spi_device_transmit(spi_device_handle_t handle, spi_transaction_t *trans_desc)
896 spi_transaction_t *ret_trans;
897 //ToDo: check if any spi transfers in flight
898 ret=spi_device_queue_trans(handle, trans_desc, portMAX_DELAY);
899 if (ret!=ESP_OK) return ret;
900 ret=spi_device_get_trans_result(handle, &ret_trans, portMAX_DELAY);
901 if (ret!=ESP_OK) return ret;
902 assert(ret_trans==trans_desc);