This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 87eb84ad73dc05a86d254b1bdbc185f3103e94f0 Author: Gustavo Henrique Nihei <[email protected]> AuthorDate: Wed May 5 15:28:17 2021 -0300 nuttx/spi: Apply some fixes to SPI Slave documentation --- include/nuttx/spi/slave.h | 152 +++++++++++++++++++++++----------------------- 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/include/nuttx/spi/slave.h b/include/nuttx/spi/slave.h index 3f8b70b..ee3121e 100644 --- a/include/nuttx/spi/slave.h +++ b/include/nuttx/spi/slave.h @@ -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. */
