nuttx/spi: Apply some fixes to SPI Slave documentation
This commit is contained in:
Gustavo Henrique Nihei
Alan Carvalho de Assis
parent
534c058d93
commit
87eb84ad73
|
|
@ -49,7 +49,7 @@
|
|||
*
|
||||
* Description:
|
||||
* Bind the SPI slave device interface to the SPI slave controller
|
||||
* interface and configure the SPI interface. Upon return, the SPI
|
||||
* interface and configure the SPI interface. Upon return, the SPI
|
||||
* slave controller driver is fully operational and ready to perform
|
||||
* transfers.
|
||||
*
|
||||
|
|
@ -62,7 +62,7 @@
|
|||
* If value is below < 0, then it implies LSB first with -nbits
|
||||
*
|
||||
* Returned Value:
|
||||
* none
|
||||
* None.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
||||
|
|
@ -73,14 +73,14 @@
|
|||
*
|
||||
* Description:
|
||||
* Un-bind the SPI slave device interface from the SPI slave controller
|
||||
* interface. Reset the SPI interface and restore the SPI slave
|
||||
* controller driver to its initial state,
|
||||
* interface. Reset the SPI interface and restore the SPI slave
|
||||
* controller driver to its initial state.
|
||||
*
|
||||
* Input Parameters:
|
||||
* sctrlr - SPI slave controller interface instance
|
||||
*
|
||||
* Returned Value:
|
||||
* none
|
||||
* None.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
||||
|
|
@ -90,9 +90,9 @@
|
|||
* Name: SPI_SCTRLR_ENQUEUE
|
||||
*
|
||||
* Description:
|
||||
* Enqueue the next value to be shifted out from the interface. This adds
|
||||
* Enqueue the next value to be shifted out from the interface. This adds
|
||||
* the word the controller driver for a subsequent transfer but has no
|
||||
* effect on any in-process or currently "committed" transfers
|
||||
* effect on any in-process or currently "committed" transfers.
|
||||
*
|
||||
* Input Parameters:
|
||||
* sctrlr - SPI slave controller interface instance
|
||||
|
|
@ -123,7 +123,7 @@
|
|||
* sctrlr - SPI slave controller interface instance
|
||||
*
|
||||
* Returned Value:
|
||||
* true if the output queue is full
|
||||
* true if the output queue is full.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
||||
|
|
@ -133,15 +133,15 @@
|
|||
* Name: SPI_SCTRLR_QFLUSH
|
||||
*
|
||||
* Description:
|
||||
* Discard all saved values in the output queue. On return from this
|
||||
* function the output queue will be empty. Any in-progress or otherwise
|
||||
* Discard all saved values in the output queue. On return from this
|
||||
* function the output queue will be empty. Any in-progress or otherwise
|
||||
* "committed" output values may not be flushed.
|
||||
*
|
||||
* Input Parameters:
|
||||
* sctrlr - SPI slave controller interface instance
|
||||
*
|
||||
* Returned Value:
|
||||
* None
|
||||
* None.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
||||
|
|
@ -177,8 +177,8 @@
|
|||
* sctrlr - SPI slave controller interface instance
|
||||
*
|
||||
* Returned Value:
|
||||
* Number of units of width "nbits" left in the rx queue. If the device
|
||||
* accepted all the data, the return value will be 0
|
||||
* Number of units of width "nbits" left in the RX queue. If the device
|
||||
* accepted all the data, the return value will be 0.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
||||
|
|
@ -196,10 +196,10 @@
|
|||
* selected - True: chip select is low (selected);
|
||||
*
|
||||
* Returned Value:
|
||||
* none
|
||||
* None.
|
||||
*
|
||||
* Assumptions:
|
||||
* May be called from an interrupt handler. Processing should be as
|
||||
* May be called from an interrupt handler. Processing should be as
|
||||
* brief as possible.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
|
@ -213,7 +213,7 @@
|
|||
* This is a SPI device callback that used when the SPI device controller
|
||||
* driver detects any change command/data condition.
|
||||
*
|
||||
* Normally only LCD devices distinguish command and data. For devices
|
||||
* Normally only LCD devices distinguish command and data. For devices
|
||||
* that do not distinguish between command and data, this method may be
|
||||
* a stub.; For devices that do make that distinction, they should treat
|
||||
* all subsequent calls to enqueue() or rece() appropriately for the
|
||||
|
|
@ -224,10 +224,10 @@
|
|||
* data - True: Data is selected
|
||||
*
|
||||
* Returned Value:
|
||||
* none
|
||||
* None.
|
||||
*
|
||||
* Assumptions:
|
||||
* May be called from an interrupt handler. Processing should be as
|
||||
* May be called from an interrupt handler. Processing should be as
|
||||
* brief as possible.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
|
@ -239,13 +239,13 @@
|
|||
*
|
||||
* Description:
|
||||
* This is a SPI device callback that used when the SPI device controller
|
||||
* requires data be shifted out at the next leading clock edge. This
|
||||
* requires data be shifted out at the next leading clock edge. This
|
||||
* is necessary to "prime the pump" so that the SPI controller driver
|
||||
* can keep pace with the shifted-in data.
|
||||
*
|
||||
* The SPI controller driver will prime for both command and data
|
||||
* transfers as determined by a preceding call to the device cmddata()
|
||||
* method. Normally only LCD devices distinguish command and data.
|
||||
* method. Normally only LCD devices distinguish command and data.
|
||||
*
|
||||
* Input Parameters:
|
||||
* sdev - SPI device interface instance
|
||||
|
|
@ -257,7 +257,7 @@
|
|||
*
|
||||
* Assumptions:
|
||||
* May be called from an interrupt handler and the response is usually
|
||||
* time critical.
|
||||
* time-critical.
|
||||
*
|
||||
****************************************************************************/
|
||||
|
||||
|
|
@ -269,7 +269,7 @@
|
|||
* Description:
|
||||
* This is a SPI device callback that used when the SPI device controller
|
||||
* receives a new value shifted in and requires the next value to be
|
||||
* shifted out. Notice that these values my be out of synchronization by
|
||||
* shifted out. Notice that these values my be out of synchronization by
|
||||
* several words.
|
||||
*
|
||||
* Input Parameters:
|
||||
|
|
@ -284,7 +284,7 @@
|
|||
*
|
||||
* Assumptions:
|
||||
* May be called from an interrupt handler and in time-critical
|
||||
* circumstances. A good implementation might just add the newly
|
||||
* circumstances. A good implementation might just add the newly
|
||||
* received word to a queue, post a processing task, and return as
|
||||
* quickly as possible to avoid any data overrun problems.
|
||||
*
|
||||
|
|
@ -298,12 +298,12 @@
|
|||
|
||||
/* There are two interfaces defined for the implementation of SPI slave:
|
||||
*
|
||||
* 1) struct spi_sctrlr_s: Defines one interface between the SPI
|
||||
* slave device and the SPI slave controller hardware. This interface
|
||||
* 1) struct spi_sctrlr_s: Defines one interface between the SPI
|
||||
* slave device and the SPI slave controller hardware. This interface
|
||||
* is implemented by the SPI slave device controller lower-half driver
|
||||
* and is provided to the SPI slave device driver when that driver
|
||||
* is initialized. That SPI slave device initialization function is
|
||||
* unique to the SPI slave implementation. The prototype is probably
|
||||
* is initialized. That SPI slave device initialization function is
|
||||
* unique to the SPI slave implementation. The prototype is probably
|
||||
* something like:
|
||||
*
|
||||
* FAR struct spi_sctrlr_s *xyz_spi_slave_initialize(int port);
|
||||
|
|
@ -315,9 +315,9 @@
|
|||
* appear in a header file associated with the specific SPI slave
|
||||
* implementation.
|
||||
*
|
||||
* 2) struct spi_sdev_s: Defines the second interface between the SPI
|
||||
* slave device and the SPI slave controller hardware. This interface
|
||||
* is implemented by the SPI slave device. The slave device passes this
|
||||
* 2) struct spi_sdev_s: Defines the second interface between the SPI
|
||||
* slave device and the SPI slave controller hardware. This interface
|
||||
* is implemented by the SPI slave device. The slave device passes this
|
||||
* interface to the struct spi_sctrlr_s during initialization
|
||||
* be calling the bind() method of the struct spi_sctrlr_s
|
||||
* interface.
|
||||
|
|
@ -328,22 +328,22 @@
|
|||
* instance of the SPI slave controller interface, struct spi_sctrlr_s.
|
||||
*
|
||||
* 2) Board-specific logic then calls up_dev_initialize() to initialize
|
||||
* the SPI slave device. The board-specific logic passes the instance
|
||||
* the SPI slave device. The board-specific logic passes the instance
|
||||
* of struct spi_sctrlr_s to support the initialization.
|
||||
*
|
||||
* 3) The SPI slave device driver creates and initializes an instance of
|
||||
* struct spi_sdev_s; it passes this instance to the bind() method of
|
||||
* of the SPI slave controller interface.
|
||||
*
|
||||
* 4) The SPI slave controller will (1) call the slaved device's select()
|
||||
* 4) The SPI slave controller will (1) call the slave device's select()
|
||||
* and cmddata() methods to indicate the initial state of the chip select
|
||||
* and any command/data selection, then (2) call the slave device's
|
||||
* getdata() method to get the value that will be shifted out the SPI
|
||||
* clock is detected. The kind of data returned the getdata() method
|
||||
* may be contingent on the current command/data setting reported the
|
||||
* device cmddata() method. The driver may enqueue additional words
|
||||
* to be shifted out at any time by The calling the SPI slave
|
||||
* controller's enqueue() method.
|
||||
* getdata() method to get the value that will be shifted out once the SPI
|
||||
* clock is detected. The kind of data returned by the getdata() method
|
||||
* may be contingent on the current command/data setting reported by the
|
||||
* device cmddata() method. The driver may enqueue additional words
|
||||
* to be shifted out at any time by calling the SPI slave controller's
|
||||
* enqueue() method.
|
||||
*
|
||||
* 5) Upon return from the bind method, the SPI slave controller will be
|
||||
* fully "armed" and ready to begin normal SPI data transfers.
|
||||
|
|
@ -351,21 +351,21 @@
|
|||
* A typical (non-DMA) data transfer proceeds as follows:
|
||||
*
|
||||
* 1) Internally, the SPI slave driver detects that the SPI chip select
|
||||
* has gone low, selecting this device for data transfer. The SPI
|
||||
* slave controller will notify the slave device by called its
|
||||
* has gone low, selecting this device for data transfer. The SPI
|
||||
* slave controller will notify the slave device by calling its
|
||||
* select() method.
|
||||
*
|
||||
* 2) If a change in the command/data state changes any time before,
|
||||
* during, or after the chip is selected, that new command/data state
|
||||
* will reported to the device driver via the cmddata() method.
|
||||
* 2) If the command/data state changes any time before, during, or after the
|
||||
* chip is selected, that new command/data state will be reported to the
|
||||
* device driver via the cmddata() method.
|
||||
*
|
||||
* 3) As the first word is shifted in, the command or data word obtained
|
||||
* by the initial call to getdata() will be shifted out. As soon as
|
||||
* by the initial call to getdata() will be shifted out. As soon as
|
||||
* the clock is detected, the SPI controller driver will call the
|
||||
* getdata() method again to get a default second word to be shifted
|
||||
* out. NOTES: (1) the SPI slave device has only one word in bit
|
||||
* out. NOTES: (1) the SPI slave device has only one word in bit
|
||||
* times to provide this value! (2) The SPI device probably cannot
|
||||
* really output anything meaning until it receives a decodes the
|
||||
* really output anything meaningful until it receives and decodes the
|
||||
* first word received from the master.
|
||||
*
|
||||
* 4) When the first word from the master is shifted in, the SPI
|
||||
|
|
@ -377,8 +377,8 @@
|
|||
* data from the SPI device to the master, the SPI device driver
|
||||
* should call the controller's enqueue() method to provide the next
|
||||
* value(s) to be shifted out. If the SPI device responds with this
|
||||
* value before clocking begins for the next word, that that value
|
||||
* will be used. Otherwise, the value obtained from getdata() in
|
||||
* value before clocking begins for the next word, then that value
|
||||
* will be used. Otherwise, the value obtained from getdata() in
|
||||
* step 3 will be shifted out.
|
||||
*
|
||||
* 5) The SPI device's receive() method will be called in a similar
|
||||
|
|
@ -387,9 +387,9 @@
|
|||
* For the case of bi-directional data transfer or of a uni-directional
|
||||
* transfer of data from the SPI device to the master, the SPI device
|
||||
* driver can call the enqueue() methods as it has new data to be shifted
|
||||
* out. The goal of the SPI device driver for this kind of transfer is
|
||||
* out. The goal of the SPI device driver for this kind of transfer is
|
||||
* to supply valid output data at such a rate that data underruns do not
|
||||
* occur. In the event of a data underrun, the SPI slave controller
|
||||
* occur. In the event of a data underrun, the SPI slave controller
|
||||
* driver will fallback to the default output value obtained from the
|
||||
* last getdata() call.
|
||||
*
|
||||
|
|
@ -407,14 +407,14 @@
|
|||
* the SPI device driver.
|
||||
*
|
||||
* 6) The activity of 5) will continue until the master raises the chip
|
||||
* select signal. In that case, the SPI slave controller driver will
|
||||
* again call the SPI device's select() method. At this point, the SPI
|
||||
* controller driver may have several words enqueued. It will not
|
||||
* select signal. In that case, the SPI slave controller driver will
|
||||
* again call the SPI device's select() method. At this point, the SPI
|
||||
* controller driver may have several words enqueued. It will not
|
||||
* discard these unless the SPI device driver calls the qflush()
|
||||
* method.
|
||||
*
|
||||
* Some master side implementations may simply tie the chip select signal
|
||||
* to ground if there are no other devices on the SPI bus. In that case,
|
||||
* to ground if there are no other devices on the SPI bus. In that case,
|
||||
* the initial indication of chip selected will be the only call to the
|
||||
* select() method that is made.
|
||||
*
|
||||
|
|
@ -426,42 +426,42 @@
|
|||
*
|
||||
* A typical DMA data transfer processes as follows:
|
||||
* To be provided -- I do not have a design in mind to support DMA on the
|
||||
* Slave side. The design might be very complex because:
|
||||
* Slave side. The design might be very complex because:
|
||||
*
|
||||
* 1) You need DMA buffers of fixed size, but you cannot know the size of a
|
||||
* transfer in advance, it could be much larger than your buffer or much
|
||||
* smaller. The DMA would fail in either case.
|
||||
* smaller. The DMA would fail in either case.
|
||||
*
|
||||
* 2) You cannot setup the DMA before the transfer. In most SPI protocols,
|
||||
* 2) You cannot setup the DMA before the transfer. In most SPI protocols,
|
||||
* the first word send is a command to read or write something following
|
||||
* by a sequence of transfers to implement the write. So you have very,
|
||||
* by a sequence of transfers to implement the write. So you have very,
|
||||
* very limited time window to setup the correct DMA to respond to the
|
||||
* command. I am not certain that it can be done reliably.
|
||||
* command. I am not certain that it can be done reliably.
|
||||
*
|
||||
* Inserting dummy words into the protocol between the first command word
|
||||
* and the remaining data transfer could allow time to set up the DMA.
|
||||
*
|
||||
* 3) I mentioned that you do not know the size of the transfer in advance.
|
||||
* If you set up the DMA to terminate to soon, then you lose the last part
|
||||
* of the transfer. If you set the DMA up to be too large, then you will
|
||||
* get no indication when the transfer completes.
|
||||
* If you set up the DMA to terminate too soon, then you lose the last
|
||||
* part of the transfer. If you set the DMA up to be too large, then you
|
||||
* will get no indication when the transfer completes.
|
||||
*
|
||||
* The chip select going high would be one possibility to detect the end
|
||||
* of a transfer. You could cancel a DMA in progress if the CS changes,
|
||||
* but I do not know if that would work. If there is only one device on
|
||||
* of a transfer. You could cancel a DMA in progress if the CS changes,
|
||||
* but I do not know if that would work. If there is only one device on
|
||||
* the SPI bus, then most board designs will save a pin and simply tie CS
|
||||
* to ground. So the CS is not always a reliable indicator of when the
|
||||
* to ground. So the CS is not always a reliable indicator of when the
|
||||
* transfer completes.
|
||||
*
|
||||
* 4) The option is to use a timer but that would really slow down the
|
||||
* transfers if each DMA has to end with a timeout. It would be faster
|
||||
* non-DMA transfers.
|
||||
* 4) Another option is to use a timer but that would really slow down the
|
||||
* transfers if each DMA has to end with a timeout. It would be faster
|
||||
* to perform non-DMA transfers.
|
||||
*
|
||||
* If the device as a very restricted protocol, like just register reads
|
||||
* and writes, then it might possible to implement DMA. However, that
|
||||
* If the device has a very restricted protocol, like just register reads
|
||||
* and writes, then it might be possible to implement DMA. However, that
|
||||
* solution would not be general and probably not an appropriate part of
|
||||
* a general OS. But if the interface is unpredictable, such as reading/
|
||||
* variable amounts of data from FLASH, there is more risk. A general
|
||||
* a general OS. But if the interface is unpredictable, such as reading
|
||||
* variable amounts of data from FLASH, there is more risk. A general
|
||||
* solution might not be possible.
|
||||
*/
|
||||
|
||||
|
|
@ -491,8 +491,8 @@ struct spi_sctrlrops_s
|
|||
CODE size_t (*qpoll)(FAR struct spi_sctrlr_s *sctrlr);
|
||||
};
|
||||
|
||||
/* SPI slave controller private data. This structure only defines the
|
||||
* initial fields of the structure visible to the SPI device driver. The
|
||||
/* SPI slave controller private data. This structure only defines the
|
||||
* initial fields of the structure visible to the SPI device driver. The
|
||||
* specific implementation may add additional, device specific fields after
|
||||
* the vtable structure pointer.
|
||||
*/
|
||||
|
|
@ -516,8 +516,8 @@ struct spi_sdevops_s
|
|||
FAR const void *data, size_t nwords);
|
||||
};
|
||||
|
||||
/* SPI slave device private data. This structure only defines the initial
|
||||
* fields of the structure visible to the SPI slave controller driver. The
|
||||
/* SPI slave device private data. This structure only defines the initial
|
||||
* fields of the structure visible to the SPI slave controller driver. The
|
||||
* specific implementation may add additional, device specific fields after
|
||||
* the vtable structure pointer.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue