spi: Fix spelling typos and acronyms capitalization

 * @spi: spi_device to register

 *

 * Companion function to spi_alloc_device.  Devices allocated with

 * spi_alloc_device can be added onto the spi bus with this function.

 * spi_alloc_device can be added onto the SPI bus with this function.

 *

 * Return: 0 on success; negative errno on failure

 */

 * spi_res_alloc - allocate a spi resource that is life-cycle managed

 *                 during the processing of a spi_message while using

 *                 spi_transfer_one

 * @spi:     the spi device for which we allocate memory

 * @spi:     the SPI device for which we allocate memory

 * @release: the release code to execute for this resource

 * @size:    size to alloc and return

 * @gfp:     GFP allocation flags

}

/**

 * spi_res_free - free an spi resource

 * spi_res_free - free an SPI resource

 * @res: pointer to the custom data of a resource

 */

static void spi_res_free(void *res)

/**

 * spi_res_add - add a spi_res to the spi_message

 * @message: the spi message

 * @message: the SPI message

 * @res:     the spi_resource

 */

static void spi_res_add(struct spi_message *message, void *res)

}

/**

 * spi_res_release - release all spi resources for this message

 * spi_res_release - release all SPI resources for this message

 * @ctlr:  the @spi_controller

 * @message: the @spi_message

 */

			return -EINVAL;

		/*

		 * If there is unknown effective speed, approximate it

		 * by underestimating with half of the requested hz.

		 * by underestimating with half of the requested Hz.

		 */

		hz = xfer->effective_speed_hz ?: xfer->speed_hz / 2;

		if (!hz)

}

/**

 * __spi_pump_messages - function which processes spi message queue

 * __spi_pump_messages - function which processes SPI message queue

 * @ctlr: controller to process queue for

 * @in_kthread: true if we are in the context of the message pump thread

 *

 * This function checks if there is any spi message in the queue that

 * This function checks if there is any SPI message in the queue that

 * needs processing and if so call out to the driver to initialize hardware

 * and transfer each message.

 *

	unsigned long flags;

	int ret;

	/* Take the IO mutex */

	/* Take the I/O mutex */

	mutex_lock(&ctlr->io_mutex);

	/* Lock queue */

/**

 * spi_queued_transfer - transfer function for queued transfers

 * @spi: spi device which is requesting transfer

 * @msg: spi message which is to handled is queued to driver queue

 * @spi: SPI device which is requesting transfer

 * @msg: SPI message which is to handled is queued to driver queue

 *

 * Return: zero on success, else a negative error code.

 */

 * acpi_spi_count_resources - Count the number of SpiSerialBus resources

 * @adev:	ACPI device

 *

 * Returns the number of SpiSerialBus resources in the ACPI-device's

 * Return: the number of SpiSerialBus resources in the ACPI-device's

 * resource-list; or a negative error code.

 */

int acpi_spi_count_resources(struct acpi_device *adev)

 * @adev: ACPI Device for the spi device

 * @index: Index of the spi resource inside the ACPI Node

 *

 * This should be used to allocate a new spi device from and ACPI Node.

 * The caller is responsible for calling spi_add_device to register the spi device.

 * This should be used to allocate a new SPI device from and ACPI Device node.

 * The caller is responsible for calling spi_add_device to register the SPI device.

 *

 * If ctlr is set to NULL, the Controller for the spi device will be looked up

 * If ctlr is set to NULL, the Controller for the SPI device will be looked up

 * using the resource.

 * If index is set to -1, index is not used.

 * Note: If index is -1, ctlr must be set.

	if (IS_ENABLED(CONFIG_SPI_DYNAMIC))

		mutex_unlock(&ctlr->add_lock);

	/* Release the last reference on the controller if its driver

	/*

	 * Release the last reference on the controller if its driver

	 * has not yet been converted to devm_spi_alloc_master/slave().

	 */

	if (!ctlr->devm_allocated)

	/* All the others need rx_buf/tx_buf also set */

	for (i = 1, offset = maxsize; i < count; offset += maxsize, i++) {

		/* Update rx_buf, tx_buf and dma */

		/* Update rx_buf, tx_buf and DMA */

		if (xfers[i].rx_buf)

			xfers[i].rx_buf += offset;

		if (xfers[i].rx_dma)

/**

 * spi_split_transfers_maxwords - split spi transfers into multiple transfers

 * spi_split_transfers_maxwords - split SPI transfers into multiple transfers

 *                                when an individual transfer exceeds a

 *                                certain number of SPI words

 * @ctlr:     the @spi_controller for this transfer

/*-------------------------------------------------------------------------*/

/* Core methods for SPI controller protocol drivers.  Some of the

/*

 * Core methods for SPI controller protocol drivers. Some of the

 * other core methods are currently defined as inline functions.

 */

 * changes those settings, and must be called from a context that can sleep.

 * Except for SPI_CS_HIGH, which takes effect immediately, the changes take

 * effect the next time the device is selected and data is transferred to

 * or from it.  When this function returns, the spi device is deselected.

 * or from it.  When this function returns, the SPI device is deselected.

 *

 * Note that this call will fail if the protocol driver specifies an option

 * that the underlying controller or its driver does not support.  For

 * spi_async - asynchronous SPI transfer

 * @spi: device with which data will be exchanged

 * @message: describes the data transfers, including completion callback

 * Context: any (irqs may be blocked, etc)

 * Context: any (IRQs may be blocked, etc)

 *

 * This call may be used in_irq and other contexts which can't sleep,

 * as well as from task contexts which can sleep.

 * spi_async_locked - version of spi_async with exclusive bus usage

 * @spi: device with which data will be exchanged

 * @message: describes the data transfers, including completion callback

 * Context: any (irqs may be blocked, etc)

 * Context: any (IRQs may be blocked, etc)

 *

 * This call may be used in_irq and other contexts which can't sleep,

 * as well as from task contexts which can sleep.

/**

 * spi_write_then_read - SPI synchronous write followed by read

 * @spi: device with which data will be exchanged

 * @txbuf: data to be written (need not be dma-safe)

 * @txbuf: data to be written (need not be DMA-safe)

 * @n_tx: size of txbuf, in bytes

 * @rxbuf: buffer into which data will be read (need not be dma-safe)

 * @rxbuf: buffer into which data will be read (need not be DMA-safe)

 * @n_rx: size of rxbuf, in bytes

 * Context: can sleep

 *

 *

 * Parameters to this routine are always copied using a small buffer.

 * Performance-sensitive or bulk transfer code should instead use

 * spi_{async,sync}() calls with dma-safe buffers.

 * spi_{async,sync}() calls with DMA-safe buffers.

 *

 * Return: zero on success, else a negative error code.

 */

	x[0].tx_buf = local_buf;

	x[1].rx_buf = local_buf + n_tx;

	/* Do the i/o */

	/* Do the I/O */

	status = spi_sync(spi, &message);

	if (status == 0)

		memcpy(rxbuf, x[1].rx_buf, n_rx);

/**

 * struct spi_statistics - statistics for spi transfers

 * @syncp:         seqcount to protect members in this struct for per-cpu udate

 * @syncp:         seqcount to protect members in this struct for per-cpu update

 *                 on 32-bit systems

 *

 * @messages:      number of spi-messages handled

 * @bytes_rx:      number of bytes received from device

 *

 * @transfer_bytes_histo:

 *                 transfer bytes histogramm

 *                 transfer bytes histogram

 *

 * @transfers_split_maxsize:

 *                 number of transfers that have been split because of

 *	the device will bind to the named driver and only the named driver.

 *	Do not set directly, because core frees it; use driver_set_override() to

 *	set or clear it.

 * @cs_gpiod: gpio descriptor of the chipselect line (optional, NULL when

 * @cs_gpiod: GPIO descriptor of the chipselect line (optional, NULL when

 *	not using a GPIO line)

 * @word_delay: delay to be inserted between consecutive

 *	words of a transfer

	void			*controller_data;

	char			modalias[SPI_NAME_SIZE];

	const char		*driver_override;

	struct gpio_desc	*cs_gpiod;	/* Chip select gpio desc */

	struct gpio_desc	*cs_gpiod;	/* Chip select GPIO descriptor */

	struct spi_delay	word_delay; /* Inter-word delay */

	/* CS delays */

	struct spi_delay	cs_setup;

	struct spi_statistics __percpu	*pcpu_statistics;

	/*

	 * likely need more hooks for more protocol options affecting how

	 * Likely need more hooks for more protocol options affecting how

	 * the controller talks to each chip, like:

	 *  - memory packing (12 bit samples into low bits, others zeroed)

	 *  - priority

/**

 * struct spi_driver - Host side "protocol" driver

 * @id_table: List of SPI devices supported by this driver

 * @probe: Binds this driver to the spi device.  Drivers can verify

 * @probe: Binds this driver to the SPI device.  Drivers can verify

 *	that the device is actually present, and may need to configure

 *	characteristics (such as bits_per_word) which weren't needed for

 *	the initial configuration done during system setup.

 * @remove: Unbinds this driver from the spi device

 * @remove: Unbinds this driver from the SPI device

 * @shutdown: Standard shutdown callback used during system state

 *	transitions such as powerdown/halt and kexec

 * @driver: SPI device drivers should initialize the name and owner

 * @queued: whether this controller is providing an internal message queue

 * @kworker: pointer to thread struct for message pump

 * @pump_messages: work struct for scheduling work to the message pump

 * @queue_lock: spinlock to syncronise access to message queue

 * @queue_lock: spinlock to synchronise access to message queue

 * @queue: message queue

 * @cur_msg: the currently in-flight message

 * @cur_msg_completion: a completion for the current in-flight message

 * @unprepare_message: undo any work done by prepare_message().

 * @slave_abort: abort the ongoing transfer request on an SPI slave controller

 * @target_abort: abort the ongoing transfer request on an SPI target controller

 * @cs_gpiods: Array of GPIO descs to use as chip select lines; one per CS

 * @cs_gpiods: Array of GPIO descriptors to use as chip select lines; one per CS

 *	number. Any individual value may be NULL for CS lines that

 *	are not GPIOs (driven by the SPI controller itself).

 * @use_gpio_descriptors: Turns on the code in the SPI core to parse and grab

 *	If the driver does not set this, the SPI core takes the snapshot as

 *	close to the driver hand-over as possible.

 * @irq_flags: Interrupt enable state during PTP system timestamping

 * @fallback: fallback to pio if dma transfer return failure with

 * @fallback: fallback to PIO if DMA transfer return failure with

 *	SPI_TRANS_FAIL_NO_START.

 * @queue_empty: signal green light for opportunistically skipping the queue

 *	for spi_sync transfers.

	struct list_head list;

	/* Other than negative (== assign one dynamically), bus_num is fully

	 * board-specific.  usually that simplifies to being SOC-specific.

	 * example:  one SOC has three SPI controllers, numbered 0..2,

	 * and one board's schematics might show it using SPI-2.  software

	/*

	 * Other than negative (== assign one dynamically), bus_num is fully

	 * board-specific. Usually that simplifies to being SoC-specific.

	 * example: one SoC has three SPI controllers, numbered 0..2,

	 * and one board's schematics might show it using SPI-2. Software

	 * would normally use bus_num=2 for that controller.

	 */

	s16			bus_num;

	/* chipselects will be integral to many controllers; some others

	/*

	 * Chipselects will be integral to many controllers; some others

	 * might use board-specific GPIOs.

	 */

	u16			num_chipselect;

	};

	/*

	 * on some hardware transfer / message size may be constrained

	 * the limit may depend on device transfer settings

	 * On some hardware transfer / message size may be constrained

	 * the limit may depend on device transfer settings.

	 */

	size_t (*max_transfer_size)(struct spi_device *spi);

	size_t (*max_message_size)(struct spi_device *spi);

	/* Flag indicating that the SPI bus is locked for exclusive use */

	bool			bus_lock_flag;

	/* Setup mode and clock, etc (spi driver may call many times).

	/*

	 * Setup mode and clock, etc (SPI driver may call many times).

	 *

	 * IMPORTANT:  this may be called when transfers to another

	 * device are active.  DO NOT UPDATE SHARED REGISTERS in ways

	 */

	int (*set_cs_timing)(struct spi_device *spi);

	/* Bidirectional bulk transfers

	/*

	 * Bidirectional bulk transfers

	 *

	 * + The transfer() method may not sleep; its main role is

	 *   just to add the message to the queue.

	 * + For now there's no remove-from-queue operation, or

	 *   any other request management

	 * + To a given spi_device, message queueing is pure fifo

	 * + To a given spi_device, message queueing is pure FIFO

	 *

	 * + The controller's main job is to process its message queue,

	 *   selecting a chip (for masters), then transferring data

	 * + If there are multiple spi_device children, the i/o queue

	 *   arbitration algorithm is unspecified (round robin, fifo,

	 *   arbitration algorithm is unspecified (round robin, FIFO,

	 *   priority, reservations, preemption, etc)

	 *

	 * + Chipselect stays active during the entire message

	const struct spi_controller_mem_ops *mem_ops;

	const struct spi_controller_mem_caps *mem_caps;

	/* gpio chip select */

	/* GPIO chip select */

	struct gpio_desc	**cs_gpiods;

	bool			use_gpio_descriptors;

	s8			unused_native_cs;

			     struct spi_transfer *xfer,

			     size_t progress, bool irqs_off);

/* The spi driver core manages memory for the spi_controller classdev */

/* The SPI driver core manages memory for the spi_controller classdev */

extern struct spi_controller *__spi_alloc_controller(struct device *host,

						unsigned int size, bool slave);

				  void *res);

/**

 * struct spi_res - spi resource management structure

 * struct spi_res - SPI resource management structure

 * @entry:   list entry

 * @release: release code called prior to freeing this resource

 * @data:    extra data allocated for the specific use-case

 *

 * this is based on ideas from devres, but focused on life-cycle

 * management during spi_message processing

 * This is based on ideas from devres, but focused on life-cycle

 * management during spi_message processing.

 */

struct spi_res {

	struct list_head        entry;

 *

 * The spi_messages themselves consist of a series of read+write transfer

 * segments.  Those segments always read the same number of bits as they

 * write; but one or the other is easily ignored by passing a null buffer

 * write; but one or the other is easily ignored by passing a NULL buffer

 * pointer.  (This is unlike most types of I/O API, because SPI hardware

 * is full duplex.)

 *

/**

 * struct spi_transfer - a read/write buffer pair

 * @tx_buf: data to be written (dma-safe memory), or NULL

 * @rx_buf: data to be read (dma-safe memory), or NULL

 * @tx_buf: data to be written (DMA-safe memory), or NULL

 * @rx_buf: data to be read (DMA-safe memory), or NULL

 * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped

 * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped

 * @tx_nbits: number of bits used for writing. If 0 the default

 * @word_delay: inter word delay to be introduced after each word size

 *	(set by bits_per_word) transmission.

 * @effective_speed_hz: the effective SCK-speed that was used to

 *      transfer this transfer. Set to 0 if the spi bus driver does

 *      transfer this transfer. Set to 0 if the SPI bus driver does

 *      not support it.

 * @transfer_list: transfers are sequenced through @spi_message.transfers

 * @tx_sg: Scatterlist for transmit, currently not for client use

 *	transmitting the "pre" word, and the "post" timestamp after receiving

 *	transmit confirmation from the controller for the "post" word.

 * @timestamped: true if the transfer has been timestamped

 * @error: Error status logged by spi controller driver.

 * @error: Error status logged by SPI controller driver.

 *

 * SPI transfers always write the same number of bytes as they read.

 * Protocol drivers should always provide @rx_buf and/or @tx_buf.

 * In some cases, they may also want to provide DMA addresses for

 * the data being transferred; that may reduce overhead, when the

 * underlying driver uses dma.

 * underlying driver uses DMA.

 *

 * If the transmit buffer is null, zeroes will be shifted out

 * while filling @rx_buf.  If the receive buffer is null, the data

 * If the transmit buffer is NULL, zeroes will be shifted out

 * while filling @rx_buf.  If the receive buffer is NULL, the data

 * shifted in will be discarded.  Only "len" bytes shift out (or in).

 * It's an error to try to shift out a partial word.  (For example, by

 * shifting out three bytes with word size of sixteen or twenty bits;

 * Some devices need protocol transactions to be built from a series of

 * spi_message submissions, where the content of one message is determined

 * by the results of previous messages and where the whole transaction

 * ends when the chipselect goes intactive.

 * ends when the chipselect goes inactive.

 *

 * When SPI can transfer in 1x,2x or 4x. It can get this transfer information

 * from device through @tx_nbits and @rx_nbits. In Bi-direction, these

 * and its transfers, ignore them until its completion callback.

 */

struct spi_transfer {

	/* It's ok if tx_buf == rx_buf (right?)

	 * for MicroWire, one buffer must be null

	 * buffers must work with dma_*map_single() calls, unless

	 *   spi_message.is_dma_mapped reports a pre-existing mapping

	/*

	 * It's okay if tx_buf == rx_buf (right?).

	 * For MicroWire, one buffer must be NULL.

	 * Buffers must work with dma_*map_single() calls, unless

	 * spi_message.is_dma_mapped reports a pre-existing mapping.

	 */

	const void	*tx_buf;

	void		*rx_buf;

	unsigned	tx_nbits:3;

	unsigned	rx_nbits:3;

	unsigned	timestamped:1;

#define	SPI_NBITS_SINGLE	0x01 /* 1bit transfer */

#define	SPI_NBITS_DUAL		0x02 /* 2bits transfer */

#define	SPI_NBITS_QUAD		0x04 /* 4bits transfer */

#define	SPI_NBITS_SINGLE	0x01 /* 1-bit transfer */

#define	SPI_NBITS_DUAL		0x02 /* 2-bit transfer */

#define	SPI_NBITS_QUAD		0x04 /* 4-bit transfer */

	u8		bits_per_word;

	struct spi_delay	delay;

	struct spi_delay	cs_change_delay;

 * struct spi_message - one multi-segment SPI transaction

 * @transfers: list of transfer segments in this transaction

 * @spi: SPI device to which the transaction is queued

 * @is_dma_mapped: if true, the caller provided both dma and cpu virtual

 * @is_dma_mapped: if true, the caller provided both DMA and CPU virtual

 *	addresses for each transfer buffer

 * @complete: called to report transaction completions

 * @context: the argument to complete() when it's called

 * @status: zero for success, else negative errno

 * @queue: for use by whichever driver currently owns the message

 * @state: for use by whichever driver currently owns the message

 * @resources: for resource management when the spi message is processed

 * @resources: for resource management when the SPI message is processed

 * @prepared: spi_prepare_message was called for the this message

 *

 * A @spi_message is used to execute an atomic sequence of data transfers,

	/* spi_prepare_message() was called for this message */

	bool			prepared;

	/* REVISIT:  we might want a flag affecting the behavior of the

	/*

	 * REVISIT: we might want a flag affecting the behavior of the

	 * last transfer ... allowing things like "read 16 bit length L"

	 * immediately followed by "read L bytes".  Basically imposing

	 * a specific message scheduling algorithm.

	unsigned		frame_length;

	unsigned		actual_length;

	/* For optional use by whatever driver currently owns the

	/*

	 * For optional use by whatever driver currently owns the

	 * spi_message ...  between calls to spi_async and then later

	 * complete(), that's the spi_controller controller driver.

	 */

	struct list_head	queue;

	void			*state;

	/* List of spi_res reources when the spi message is processed */

	/* List of spi_res resources when the SPI message is processed */

	struct list_head        resources;

};

/**

 * spi_message_init_with_transfers - Initialize spi_message and append transfers

 * @m: spi_message to be initialized

 * @xfers: An array of spi transfers

 * @xfers: An array of SPI transfers

 * @num_xfers: Number of items in the xfer array

 *

 * This function initializes the given spi_message and adds each spi_transfer in

		spi_message_add_tail(&xfers[i], m);

}

/* It's fine to embed message and transaction structures in other data

/*

 * It's fine to embed message and transaction structures in other data

 * structures so long as you don't free them while they're in use.

 */

static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags)

{

	struct spi_message *m;

 *                                 replacements that have occurred

 *                                 so that they can get reverted

 * @release:            some extra release code to get executed prior to

 *                      relasing this structure

 *                      releasing this structure

 * @extradata:          pointer to some extra data if requested or NULL

 * @replaced_transfers: transfers that have been replaced and which need

 *                      to get restored

 * @inserted_transfers: array of spi_transfers of array-size @inserted,

 *                      that have been replacing replaced_transfers

 *

 * note: that @extradata will point to @inserted_transfers[@inserted]

 * Note: that @extradata will point to @inserted_transfers[@inserted]

 * if some extra allocation is requested, so alignment will be the same

 * as for spi_transfers

 * as for spi_transfers.

 */

struct spi_replaced_transfers {

	spi_replaced_release_t release;

/*---------------------------------------------------------------------------*/

/* All these synchronous SPI transfer routines are utilities layered

/*

 * All these synchronous SPI transfer routines are utilities layered

 * over the core async transfer primitive.  Here, "synchronous" means

 * they will sleep uninterruptibly until the async transfer completes.

 */

 *

 * Callable only from contexts that can sleep.

 *

 * Return: the (unsigned) sixteen bit number returned by the device in cpu

 * Return: the (unsigned) sixteen bit number returned by the device in CPU

 * endianness, or else a negative error code.

 */

static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd)

 * As a rule, SPI devices can't be probed.  Instead, board init code

 * provides a table listing the devices which are present, with enough

 * information to bind and set up the device's driver.  There's basic

 * support for nonstatic configurations too; enough to handle adding

 * support for non-static configurations too; enough to handle adding

 * parport adapters, or microcontrollers acting as USB-to-SPI bridges.

 */

 * are active in some dynamic board configuration models.

 */

struct spi_board_info {

	/* The device name and module name are coupled, like platform_bus;

	/*

	 * The device name and module name are coupled, like platform_bus;

	 * "modalias" is normally the driver name.

	 *

	 * platform_data goes to spi_device.dev.platform_data,

	 * controller_data goes to spi_device.controller_data,

	 * irq is copied too

	 * IRQ is copied too.

	 */

	char		modalias[SPI_NAME_SIZE];

	const void	*platform_data;

	u32		max_speed_hz;

	/* bus_num is board specific and matches the bus_num of some

	/*

	 * bus_num is board specific and matches the bus_num of some

	 * spi_controller that will probably be registered later.

	 *

	 * chip_select reflects how this chip is wired to that master;

	u16		bus_num;

	u16		chip_select;

	/* mode becomes spi_device.mode, and is essential for chips

	/*

	 * mode becomes spi_device.mode, and is essential for chips

	 * where the default of SPI_CS_HIGH = 0 is wrong.

	 */

	u32		mode;

	/* ... may need additional spi_device chip config data here.

	/*

	 * ... may need additional spi_device chip config data here.

	 * avoid stuff protocol drivers can set; but include stuff

	 * needed to behave without being bound to a driver:

	 *  - quirks like clock rate mattering when not selected

	{ return 0; }

#endif

/* If you're hotplugging an adapter with devices (parport, usb, etc)

/*

 * If you're hotplugging an adapter with devices (parport, USB, etc)

 * use spi_new_device() to describe each device.  You can also call

 * spi_unregister_device() to start making that device vanish, but

 * normally that would be handled by spi_unregister_controller().

);

/*

 * consider a buffer valid if non-NULL and if it doesn't match the dummy buffer

 * Consider a buffer valid if non-NULL and if it doesn't match the dummy buffer

 * that only exist to work with controllers that have SPI_CONTROLLER_MUST_TX or

 * SPI_CONTROLLER_MUST_RX.

 */