mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
doc(spi master): documents updated for several limitations.
This commit is contained in:
parent
0cb14f1648
commit
2554f61f05
@ -53,14 +53,28 @@ A transaction on the SPI bus consists of five phases, any of which may be skippe
|
||||
|
||||
* The command phase. In this phase, a command (0-16 bit) is clocked out.
|
||||
* The address phase. In this phase, an address (0-64 bit) is clocked out.
|
||||
* The read phase. The slave sends data to the master.
|
||||
* The write phase. The master sends data to the slave.
|
||||
* The dummy phase. The phase is configurable, used to meet the timing requirements.
|
||||
* The read phase. The slave sends data to the master.
|
||||
|
||||
In full duplex, the read and write phases are combined, causing the SPI host to read and
|
||||
write data simultaneously.
|
||||
write data simultaneously. The total transaction length is decided by
|
||||
``dev_conf.command_bits + dev_conf.address_bits + trans_conf.length``, while the ``trans_conf.rx_length``
|
||||
only determins length of data received into the buffer.
|
||||
|
||||
In half duplex, the length of write phase and read phase are decided by ``trans_conf.length`` and
|
||||
``trans_conf.rx_length`` respectively. ** Note that a half duplex transaction with both a read and
|
||||
write phase is not supported when using DMA. ** If such transaction is needed, you have to use one
|
||||
of the alternative solutions:
|
||||
1. use full-duplex mode instead.
|
||||
2. disable the DMA by set the last parameter to 0 in bus initialization function just as belows:
|
||||
``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);``
|
||||
|
||||
this may prohibit you from transmitting and receiving data longer than 32 bytes.
|
||||
3. try to use command and address field to replace the write phase.
|
||||
|
||||
The command and address phase are optional in that not every SPI device will need to be sent a command
|
||||
and/or address. Tis is reflected in the device configuration: when the ``command_bits`` or ``data_bits``
|
||||
and/or address. This is reflected in the device configuration: when the ``command_bits`` or ``address_bits``
|
||||
fields are set to zero, no command or address phase is done.
|
||||
|
||||
Something similar is true for the read and write phase: not every transaction needs both data to be written
|
||||
@ -93,9 +107,12 @@ Transaction data
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Normally, data to be transferred to or from a device will be read from or written to a chunk of memory
|
||||
indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. The SPI driver
|
||||
may decide to use DMA for transfers, so these buffers should be allocated in DMA-capable memory using
|
||||
``pvPortMallocCaps(size, MALLOC_CAP_DMA)``.
|
||||
indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure.
|
||||
When DMA is enabled for transfers, these buffers are highly recommended to meet the requirements as belows:
|
||||
1. allocated in DMA-capable memory using ``pvPortMallocCaps(size, MALLOC_CAP_DMA)``;
|
||||
2. 32-bit aligned (start from the boundary and have length of multiples of 4 bytes).
|
||||
If these requirements are not satisfied, efficiency of the transaction will suffer due to the allocation and
|
||||
memcpy of temporary buffers.
|
||||
|
||||
Sometimes, the amount of data is very small making it less than optimal allocating a separate buffer
|
||||
for it. If the data to be transferred is 32 bits or less, it can be stored in the transaction struct
|
||||
@ -107,7 +124,7 @@ as ``tx_data`` and ``rx_data``.
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Display graphics on the ILI9341-based 320x240 LCD: :example:`peripherals/spi_master`.
|
||||
Display graphics on the 320x240 LCD of WROVER-Kits: :example:`peripherals/spi_master`.
|
||||
|
||||
|
||||
API Reference - SPI Common
|
||||
|
Loading…
Reference in New Issue
Block a user