SPI resource management framework used while processing a spi_message
via the spi-core.

The basic idea is taken from devres, but as the allocation may happen
fairly frequently, some provisioning (in the form of an unused spi_device
pointer argument to spi_res_alloc) has been made so that at a later stage
we may implement reuse objects allocated earlier avoiding the repeated
allocation by keeping a cache of objects that we can reuse.

This framework can get used for:
* rewriting spi_messages
  * to fullfill alignment requirements of the spi_master HW
  * to fullfill transfer length requirements
    (e.g: transfers need to be less than 64k)
  * consolidate spi_messages with multiple transfers into a single transfer
  when the total transfer length is below a threshold.
* reimplement spi_unmap_buf without explicitly needing to check if it has
  been mapped
Signed-off-by: NMartin Sperl <kernel@martin.sperl.org>
Signed-off-by: NMark Brown <broonie@kernel.org>

On some SPI controllers it is not feasible to transfer arbitrary amount
of data at once.

When the limit on transfer size is a few kilobytes at least it makes
sense to use the SPI hardware rather than reverting to gpio driver.

The protocol drivers need a way to check that they do not sent overly
long messages, though.
Signed-off-by: NMichal Suchanek <hramrach@gmail.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

In the spi_loopback_test driver there is the need to initialize
a spi_message that is filled with values from a static structure.

Applying spi_message_init to such a prefilled structure results in
all the settings getting reset to zero, which is not what we want.
Copying each field of spi_message separately instead always includes
the risk that some new fields have not been implemented in the copying
code.

So here we introduce a version of spi_message_init called
spi_message_init_no_memset that does not fill the structure
with zero first, but only initializes the relevant list_heads.
Signed-off-by: NMartin Sperl <kernel@martin.sperl.org>
Signed-off-by: NMark Brown <broonie@kernel.org>

Uninline spi_unregister_device() in preparation of adding more code to
it. Add kerneldoc documentation while we're at it.
Signed-off-by: NGeert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: NMark Brown <broonie@kernel.org>

Add spi_register_driver helper macro that adds THIS_MODULE to
spi_driver for the registering driver. We rename and modify
the existing spi_register_driver to enable this.
Signed-off-by: NAndrew F. Davis <afd@ti.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

When building docs with make htmldocs, warnings about not having
a description for the return value are reported, i.e:

warning: No description found for return value of 'spi_write'

Fix these by following the kernel-doc conventions explained in
Documentation/kernel-doc-nano-HOWTO.txt.
Signed-off-by: NJavier Martinez Canillas <javier@osg.samsung.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

report transfer sizes as a histogram via the following files:
  /sys/class/spi_master/spi*/statistics/transfer_bytes_histo_*
  /sys/class/spi_master/spi*/spi*.*/statistics/transfer_bytes_histo_*
Signed-off-by: NMartin Sperl <kernel@martin.sperl.org>
Signed-off-by: NMark Brown <broonie@kernel.org>

Fix the following 'make htmldocs' warnings:

  .//include/linux/spi/spi.h:71: warning: No description found for parameter 'lock'
  .//include/linux/spi/spi.h:71: warning: Excess struct/union/enum/typedef member 'clock' description in 'spi_statistics'
Signed-off-by: NGeliang Tang <geliangtang@163.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

per spi-master statistics accessible as:
  /sys/class/spi_master/spi*/statistics/*

per spi-device statistics accessible via:
  /sys/class/spi_master/spi*/spi*.*/statistics/*

The following statistics are exposed as separate "files" inside
these directories:
* messages              number of spi_messages
* transfers             number of spi_transfers
* bytes                 number of bytes transferred
* bytes_rx              number of bytes transmitted
* bytes_tx              number of bytes received
* errors                number of errors encounterd
* timedout              number of messages that have timed out
* spi_async             number of spi_messages submitted using spi_async
* spi_sync              number of spi_messages submitted using spi_sync
* spi_sync_immediate    number of spi_messages submitted using spi_sync,
                        that are handled immediately without a context switch
                        to the spi_pump worker-thread
Signed-off-by: NMartin Sperl <kernel@martin.sperl.org>
Signed-off-by: NMark Brown <broonie@kernel.org>

If a driver doesn't implement the master->handle_err() callback and an
SPI transfer fails, the kernel will crash with a NULL pointer
dereference:

    Unable to handle kernel NULL pointer dereference at virtual address 00000000
    pgd = c0003000
    [00000000] *pgd=80000040004003, *pmd=00000000
    Internal error: Oops: 80000206 [#1] SMP ARM
    Modules linked in:
    CPU: 1 PID: 1 Comm: swapper/0 Not tainted 4.0.0-rc7-koelsch-05861-g1fc9fdd4add4f783 #1046
    Hardware name: Generic R8A7791 (Flattened Device Tree)
    task: eec359c0 ti: eec54000 task.ti: eec54000
    PC is at 0x0
    LR is at spi_transfer_one_message+0x1cc/0x1f0

Make the master->handle_err() callback optional to avoid the crash.

Also fix a spelling mistake in the callback documentation while we're at
it.

Fixes: b716c4ff ("spi: introduce master->handle_err() callback")
Signed-off-by: NGeert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: NMark Brown <broonie@kernel.org>

All SPI drivers have been converted from legacy suspend/resume callbacks to
dev_pm_ops. So we can finally remove support for legacy PM from the SPI
core.

Since there aren't any special bus specific things to do during
suspend/resume and since the PM core will automatically fallback directly to
using the device's PM ops if no bus PM ops are specified there is no need to
have any special SPI bus PM ops.
Signed-off-by: NLars-Peter Clausen <lars@metafoo.de>
Signed-off-by: NMark Brown <broonie@kernel.org>

This callback would be useful to handle an error that occurs in the generic
implementation of transfer_one_message(). The good candidate for this is to
drain FIFO and / or to terminate DMA transfers when timeout happened.
Signed-off-by: NAndy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

alway -> always
Signed-off-by: NMarcin Bis <marcin@bis.org.pl>
Signed-off-by: NMark Brown <broonie@kernel.org>

Signed-off-by: NJarkko Nikula <jarkko.nikula@linux.intel.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

If we are using the standard SPI message pump (which all drivers should be
transitioning over to) then special case the message enqueue and instead of
starting the worker thread to push messages to the hardware do so in the
context of the caller if the controller is idle. This avoids a context
switch in the common case where the controller has a single user in a
single thread, for short PIO transfers there may be no need to context
switch away from the calling context to complete the transfer.

The code is a bit more complex than is desirable in part due to the need
to handle drivers not using the standard queue and in part due to handling
the various combinations of bus locking and asynchronous submission in
interrupt context.

It is still suboptimal since it will still wake the message pump for each
transfer in order to schedule idling of the hardware and if multiple
contexts are using the controller simultaneously a caller may end up
pumping a message for some random other thread rather than for itself,
and if the thread ends up deferring due to another context idling the
hardware then it will just busy wait.  It can, however, have the benefit
of aggregating power up and down of the hardware when a caller performs
a series of transfers back to back without any need for the use of
spi_async().
Signed-off-by: NMark Brown <broonie@kernel.org>

This adds the function spi_transfer_is_last() which can be used by
drivers to know whether a given transfer is the last one in the
current message.
Signed-off-by: NBeniamino Galvani <b.galvani@gmail.com>
Signed-off-by: NMark Brown <broonie@kernel.org>

These are all arguments or fields that got added without updating the
kerneldoc comments.
Signed-off-by: NThierry Reding <treding@nvidia.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

This patch fix spelling typo in Documentation/DocBook.
It is because .html and .xml files are generated by make htmldocs,
I have to fix a typo within the source files.
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJiri Kosina <jkosina@suse.cz>

We cannot unconditionally use dma_map_single() to map data for use with
SPI since transfers may exceed a page and virtual addresses may not be
provided with physically contiguous pages. Further, addresses allocated
using vmalloc() need to be mapped differently to other addresses.

Currently only the MXS driver handles all this, a few drivers do handle
the possibility that buffers may not be physically contiguous which is
the main potential problem but many don't even do that. Factoring this
out into the core will make it easier for drivers to do a good job so if
the driver is using the core DMA code then generate a scatterlist
instead of mapping to a single address so do that.

This code is mainly based on a combination of the existing code in the MXS
and PXA2xx drivers. In future we should be able to extend it to allow the
core to concatenate adjacent transfers if they are compatible, improving
performance.

Currently for simplicity clients are not allowed to use the scatterlist
when they do DMA mapping, in the future the existing single address
mappings will be replaced with use of the scatterlist most likely as
part of pre-verifying transfers.

This change makes it mandatory to use scatterlists when using the core DMA
mapping so update the s3c64xx driver to do this when used with dmaengine.
Doing so makes the code more ugly but it is expected that the old s3c-dma
code can be removed very soon.
Signed-off-by: NMark Brown <broonie@linaro.org>

It is fairly common for SPI devices to require that one or both transfer
directions is always active. Currently drivers open code this in various
ways with varying degrees of efficiency. Start factoring this out by
providing flags SPI_MASTER_MUST_TX and SPI_MASTER_MUST_RX. These will cause
the core to provide buffers for the requested direction if none are
specified in the underlying transfer.

Currently this is fairly inefficient since we actually allocate a data
buffer which may get large, support for mapping transfers using a
scatterlist will allow us to avoid this for DMA based transfers.
Signed-off-by: NMark Brown <broonie@linaro.org>

The process of DMA mapping buffers for SPI transfers does not vary between
devices so in order to save duplication of code in drivers this can be
factored out into the core, allowing it to be integrated with the work that
is being done on factoring out the common elements from the data path
including more sharing of dmaengine code.

In order to use this masters need to provide a can_dma() operation and while
the hardware is prepared they should ensure that DMA channels are provided
in tx_dma and rx_dma. The core will then ensure that the buffers are mapped
for DMA prior to calling transfer_one_message().

Currently the cleanup on error is not complete, this needs to be improved.
Signed-off-by: NMark Brown <broonie@linaro.org>

The transfer_one_message callback handles messages, not transfers.
Signed-off-by: NBaruch Siach <baruch@tkos.co.il>
Signed-off-by: NMark Brown <broonie@linaro.org>

Explicitly note the transfer_one and transfer_one_message are mutually
exclusive, to make the text a little more newcomers friendly.
Signed-off-by: NBaruch Siach <baruch@tkos.co.il>
Signed-off-by: NMark Brown <broonie@linaro.org>

The documentation for spi_master.set_cs() says:

    assert or deassert chip select, true to assert

i.e. its "enable" parameter uses assertion-level logic.

This does not match the implementation of spi_set_cs(), which calls
spi_master.set_cs() with the wanted logic level of the chip select line,
which depends on the polarity of the chip select signal.

Correct the documentation to match the implementation.
Signed-off-by: NGeert Uytterhoeven <geert+renesas@linux-m68k.org>
Signed-off-by: NMark Brown <broonie@linaro.org>

Signed-off-by: NGeert Uytterhoeven <geert+renesas@linux-m68k.org>
Signed-off-by: NMark Brown <broonie@linaro.org>

spi_write_then_read() takes a "void *" for rxbuf, so there's no need to
cast the buffer pointer to "u8 *".
Signed-off-by: NGeert Uytterhoeven <geert+renesas@linux-m68k.org>
Signed-off-by: NMark Brown <broonie@linaro.org>

Trent Piepho observed that since the current realistic maximum number of
data lines is four we can pack the spi_transfer struct more efficiently
if we use a bitfield for the number of bits, allowing the fields to fit
in a single byte along with cs_change.

If space becomes an issue further optimiation is possible by only using
the constants and packing the values chosen for them.
Reported-by: NTrent Piepho <tpiepho@gmail.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

Now that spi_device->mode is a u16, the chip_select, bits_per_mode,
and mode fields pack poorly, taking 8 bytes:  four data and four
padding.  By moving (u8)bits_per_word up one position, to after
(u8)chip_select, they pack better and only use 4 bytes.
Signed-off-by: NTrent Piepho <tpiepho@gmail.com>
Reviewed-by: NSourav Poddar <sourav.poddar@ti.com>
Tested-by: Sourav Poddar <sourav.poddar@ti.com>g
Signed-off-by: NMark Brown <broonie@linaro.org>

The loops which SPI controller drivers use to process the list of transfers
in a spi_message are typically very similar and have some error prone areas
such as the handling of /CS. Help simplify drivers by factoring this code
out into the core - if drivers provide a transfer_one() function instead
of a transfer_one_message() function the core will handle processing at the
message level.

/CS can be controlled by either setting cs_gpio or providing a set_cs
function. If this is not possible for hardware reasons then both can be
omitted and the driver should continue to implement manual /CS handling.

This is a first step in refactoring and it is expected that there will be
further enhancements, for example factoring out of the mapping of transfers
for DMA and the initiation and completion of interrupt driven transfers.
Signed-off-by: NMark Brown <broonie@linaro.org>

Many SPI drivers perform setup and tear down on every message, usually
doing things like DMA mapping the message. Provide hooks for them to use
to provide such operations.

This is of limited value for drivers that implement transfer_one_message()
but will be of much greater utility with future factoring out of standard
implementations of that function.
Signed-off-by: NMark Brown <broonie@linaro.org>

This patch adds a new spi_w8r16be() helper, which is similar to spi_w8r16()
except that it converts the read data word from big endian to native endianness
before returning it. The reason for introducing this new helper is that for SPI
slave devices it is quite common that the read 16 bit data word is in big
endian. So users of spi_w8r16() have to convert the result to native endianness
manually. A second reason is that in this case the endianness of the return
value of spi_w8r16() depends on its sign. If it is negative (i.e. a error code)
it is already in native endianness, if it is positive it is in big endian. The
sparse code checker doesn't like this kind of mixed endianness and special
annotations are necessary to keep it quiet (E.g. casting to be16 using __force).
Doing the conversion to native endianness in the helper function does not
require such annotations since we are not mixing different endiannesses in the
same variable.
Signed-off-by: NLars-Peter Clausen <lars@metafoo.de>
Signed-off-by: NMark Brown <broonie@linaro.org>

Help simplify the cleanup code for SPI master drivers by providing a
managed master registration function, ensuring that the master is
automatically unregistered whenever the device is unbound.
Signed-off-by: NMark Brown <broonie@linaro.org>

fix the previous patch some mistake below:
1. DT in slave node, use "spi-tx-nbits = <1/2/4>" in place of using
   "spi-tx-dual, spi-tx-quad" directly, same to rx. So correct the
   previous way to get the property in @of_register_spi_devices().
2. Change the value of transfer bit macro(SPI_NBITS_SINGLE, SPI_NBITS_DUAL
   SPI_NBITS_QUAD) to 0x01, 0x02 and 0x04 to match the actual wires.
3. Add the following check
   (1)keep the tx_nbits and rx_nbits in spi_transfer is not beyond the
      single, dual and quad.
   (2)keep tx_nbits and rx_nbits are contained by @spi_device->mode
      example: if @spi_device->mode = DUAL, then tx/rx_nbits can not be set
               to QUAD(SPI_NBITS_QUAD)
   (3)if "@spi_device->mode & SPI_3WIRE", then tx/rx_nbits should be in
      single(SPI_NBITS_SINGLE)
Signed-off-by: Nwangyuhang <wangyuhang2014@gmail.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

On a 64-bit platform, ~0UL fills 64-bits, which causes SPI_BIT_MASK(32)
not to fit into 32 bits. This causes a warning when the result is assigned
to a 32-bit variable. Use ~0U instead to prevent this. This fixes:

drivers/spi/spi-gpio.c: In function 'spi_gpio_probe':
drivers/spi/spi-gpio.c:446:2: warning: large integer implicitly truncated to unsigned type [-Woverflow]
Reported-by: Nkbuild test robot <fengguang.wu@intel.com>
Signed-off-by: NStephen Warren <swarren@nvidia.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

Most SPI drivers that implement runtime PM support use identical code to
do so: they acquire a runtime PM lock in prepare_transfer_hardware() and
then they release it in unprepare_transfer_hardware(). The variations in
this are mostly missing error checking and the choice to use autosuspend.

Since these runtime PM calls are normally the only thing in the prepare
and unprepare callbacks and the autosuspend API transparently does the
right thing on devices with autosuspend disabled factor all of this out
into the core with a flag to enable the behaviour.
Signed-off-by: NMark Brown <broonie@linaro.org>
Reviewed-by: NStephen Warren <swarren@nvidia.com>
Acked-by: NLinus Walleij <linus.walleij@linaro.org>

Make spi core calculate the message length while
populating the other transfer parameters.

Usecase, driver can use it to populate framelength filed in their
controller.
Signed-off-by: NSourav Poddar <sourav.poddar@ti.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

Allow drivers to avoid implementing their own checks for simple rates by
specifying the limits in the master structure.
Signed-off-by: NMark Brown <broonie@linaro.org>

SPI_BPW_RANGE_MASK is intended to work by calculating two masks; one
representing support for all bits up-to-and-including the "max" supported
value, and one representing support for all bits up-to-but-not-including
the "min" supported value, and then taking the difference between the
two, resulting in a mask representing support for all bits between
(inclusive) the min and max values.

However, the second mask ended up representing all bits up-to-and-
including rather up-to-but-not-including. Fix this bug.
Signed-off-by: NStephen Warren <swarren@nvidia.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

The parameters to SPI_BPW_RANGE_MASK() are in the range 1..32. If 32 is
used as a parameter, part of the expression is "1 << 32". Since 32 is >=
the size of the type in use, such a shift is undefined behaviour. Add
macro SPI_BIT_MASK to Implement a special case and thus avoid undefined
behaviour. Use this new macro rather than BIT() when implementing
SPI_BPW_RANGE_MASK().

This fixes build warnings such as:
drivers/spi/spi-gpio.c:446:2: warning: left shift count >= width of type [enabled by default]

SPI_BPW_MASK() already avoids this, since its parameter is also in range
1..32, yet it only shifts by up to one less than the input parameter.
Reported-by: NFengguang Wu <fengguang.wu@intel.com>
Signed-off-by: NStephen Warren <swarren@nvidia.com>
Signed-off-by: NMark Brown <broonie@linaro.org>

Introduce two macros to make setting up spi_master.bits_per_word_mask
easier, and avoid mistakes like writing BIT(n) instead of BIT(n - 1).

SPI_BPW_MASK is for a single supported value of bits_per_word_mask.

SPI_BPW_RANGE_MASK represents a contiguous set of bit lengths.
Signed-off-by: NStephen Warren <swarren@wwwdotorg.org>
Signed-off-by: NMark Brown <broonie@opensource.wolfsonmicro.com>