drivers: spi_context: Add comments for context

	},										\

	._ctx_name.num_cs_gpios = DT_PROP_LEN_OR(_node_id, cs_gpios, 0),

/*

 * Checks if a spi config is the same as the one stored in the spi_context

 * The intention of this function is to be used to check if a driver can skip

 * some reconfiguration for a transfer in a fast code path.

 */

static inline bool spi_context_configured(struct spi_context *ctx,

					  const struct spi_config *config)

{

	return !!(ctx->config == config);

}

/* Returns true if the spi configuration stored for this context

 * specifies a slave mode configuration, returns false otherwise

 */

static inline bool spi_context_is_slave(struct spi_context *ctx)

{

	return (ctx->config->operation & SPI_OP_MODE_SLAVE);

}

/*

 * The purpose of the context lock is to synchronize the usage of the driver/hardware.

 * The driver should call this function to claim or wait for ownership of the spi resource.

 * Usually the appropriate time to call this is at the start of the transceive API implementation.

 */

static inline void spi_context_lock(struct spi_context *ctx,

				    bool asynchronous,

				    spi_callback_t callback,

#endif /* CONFIG_SPI_ASYNC */

}

/*

 * This function must be called by a driver which has called spi_context_lock in order

 * to release the ownership of the spi resource.

 * Usually the appropriate time to call this would be at the end of a transfer that was

 * initiated by a transceive API call, except in the case that the SPI_LOCK_ON bit was set

 * in the configuration.

 */

static inline void spi_context_release(struct spi_context *ctx, int status)

{

#ifdef CONFIG_SPI_SLAVE

static inline size_t spi_context_total_tx_len(struct spi_context *ctx);

static inline size_t spi_context_total_rx_len(struct spi_context *ctx);

/* This function essentially is a way for a driver to seamlessly implement both the

 * synchronous transceive API and the asynchronous transceive_async API in the same way.

 *

 * The exact way this function is used may depend on driver implementation, but

 * essentially this will block waiting for a signal from spi_context_complete,

 * unless the transfer is asynchronous, in which case it does nothing in master mode.

 */

static inline int spi_context_wait_for_completion(struct spi_context *ctx)

{

	int status = 0;

	return status;

}

/* For synchronous transfers, this will signal to a thread waiting

 * on spi_context_wait for completion.

 *

 * For asynchronous tranfers, this will call the async callback function

 * with the user data.

 */

static inline void spi_context_complete(struct spi_context *ctx,

					const struct device *dev,

					int status)

#endif /* CONFIG_SPI_ASYNC */

}

/*

 * This function initializes all the chip select GPIOs associated with a spi controller.

 * The context first must be initialized using the SPI_CONTEXT_CS_GPIOS_INITIALIZE macro.

 * This function should be called during the device init sequence so that

 * all the CS lines are configured properly before the first transfer begins.

 * Note: If a controller has native CS control in SPI hardware, they should also be initialized

 * during device init by the driver with hardware-specific code.

 */

static inline int spi_context_cs_configure_all(struct spi_context *ctx)

{

	int ret;

	return 0;

}

/* Helper function to control the GPIO CS, not meant to be used directly by drivers */

static inline void _spi_context_cs_control(struct spi_context *ctx,

					   bool on, bool force_off)

{

	}

}

/* This function should be called by drivers to control the chip select line in master mode

 * in the case of the CS being a GPIO. The de facto usage of the zephyr SPI API expects that the

 * chip select be asserted throughout the entire transfer specified by a transceive call,

 * ie all buffers in a spi_buf_set should be finished before deasserting CS. And usually

 * the deassertion is at the end of the transfer, except in the case that the

 * SPI_HOLD_ON_CS bit was set in the configuration.

 */

static inline void spi_context_cs_control(struct spi_context *ctx, bool on)

{

	_spi_context_cs_control(ctx, on, false);

}

/* Forcefully releases the spi context and removes the owner, allowing taking the lock

 * with spi_context_lock without the previous owner releasing the lock.

 * This is usually used to aid in implementation of the spi_release driver API.

 */

static inline void spi_context_unlock_unconditionally(struct spi_context *ctx)

{

	/* Forcing CS to go to inactive status */

	}

}

/*

 * Helper function for incrementing buffer pointer.

 * Generally not needed to be used directly by drivers.

 * Use spi_context_update_(tx/rx) instead.

 */

static inline void *spi_context_get_next_buf(const struct spi_buf **current,

					     size_t *count,

					     size_t *buf_len,

	return NULL;

}

/*

 * The spi context private api works with the driver by providing code to

 * keep track of how much of the transfer has been completed. The driver

 * calls functions to report when some tx or rx has finished, and the driver

 * then can use the spi context to keep track of how much is left to do.

 */

/*

 * This function must be called at the start of a transfer by the driver

 * to initialize the spi context fields for tracking the progress.

 */

static inline

void spi_context_buffers_setup(struct spi_context *ctx,

			       const struct spi_buf_set *tx_bufs,

}

/*

 * Note: dfs is the number of bytes needed to store a data frame,

 * while len is the number of data frames sent.

 * Should be called to update the tracking of TX being completed.

 *

 * Parameter "dfs" is the number of bytes needed to store a data frame.

 * Parameter "len" is the number of data frames of TX that were sent.

 */

static ALWAYS_INLINE

void spi_context_update_tx(struct spi_context *ctx, uint8_t dfs, uint32_t len)

	LOG_DBG("tx buf/len %p/%zu", (void *)ctx->tx_buf, ctx->tx_len);

}

/* Returns true if there is still TX buffers left in the spi_buf_set

 * even if they are "null" (nop) buffers.

 */

static ALWAYS_INLINE

bool spi_context_tx_on(struct spi_context *ctx)

{

	return !!(ctx->tx_len);

}

/* Similar to spi_context_tx_on, but only returns true if the current buffer is

 * not a null/NOP placeholder.

 */

static ALWAYS_INLINE

bool spi_context_tx_buf_on(struct spi_context *ctx)

{

}

/*

 * Note: dfs is the number of bytes needed to store a data frame,

 * while len is the number of data frames received.

 * Should be called to update the tracking of RX being completed.

 *

 * @param dfs is the number of bytes needed to store a data frame.

 * @param len is the number of data frames of RX that were received.

 */

static ALWAYS_INLINE

void spi_context_update_rx(struct spi_context *ctx, uint8_t dfs, uint32_t len)

	LOG_DBG("rx buf/len %p/%zu", (void *)ctx->rx_buf, ctx->rx_len);

}

/* Returns true if there is still RX buffers left in the spi_buf_set

 * even if they are "null" (nop) buffers.

 */

static ALWAYS_INLINE

bool spi_context_rx_on(struct spi_context *ctx)

{

	return !!(ctx->rx_len);

}

/* Similar to spi_context_rx_on, but only returns true if the current buffer is

 * not a null/NOP placeholder.

 */

static ALWAYS_INLINE

bool spi_context_rx_buf_on(struct spi_context *ctx)

{

 * Returns the maximum length of a transfer for which all currently active

 * directions have a continuous buffer, i.e. the maximum SPI transfer that

 * can be done with DMA that handles only non-scattered buffers.

 *

 * In other words, returns the length of the smaller of the current RX or current TX buffer.

 * Except if either RX or TX buf length is 0, returns the length of the other.

 * And if both are 0 then will return 0 and should indicate transfer completion.

 */

static inline size_t spi_context_max_continuous_chunk(struct spi_context *ctx)

{

	return MIN(ctx->tx_len, ctx->rx_len);

}

/* Returns the length of the longer of the current RX or current TX buffer. */

static inline size_t spi_context_longest_current_buf(struct spi_context *ctx)

{

	return ctx->tx_len > ctx->rx_len ? ctx->tx_len : ctx->rx_len;

}

/* Helper function, not intended to be used by drivers directly */

static size_t spi_context_count_tx_buf_lens(struct spi_context *ctx, size_t start_index)

{

	size_t n;

	return total_len;

}

/* Helper function, not intended to be used by drivers directly */

static size_t spi_context_count_rx_buf_lens(struct spi_context *ctx, size_t start_index)

{

	size_t n;

}

/* Returns the length of the sum of the remaining TX buffers in the buf set, including

 * the current buffer in the total.

 */

static inline size_t spi_context_total_tx_len(struct spi_context *ctx)

{

	return spi_context_count_tx_buf_lens(ctx, 0);

}

/* Returns the length of the sum of the remaining RX buffers in the buf set, including

 * the current buffer in the total.

 */

static inline size_t spi_context_total_rx_len(struct spi_context *ctx)

{

	return spi_context_count_rx_buf_lens(ctx, 0);

}

/* Similar to spi_context_total_tx_len, except does not count words that have been finished

 * in the current buffer, ie only including what is remaining in the current buffer in the sum.

 */

static inline size_t spi_context_tx_len_left(struct spi_context *ctx)

{

	return ctx->tx_len + spi_context_count_tx_buf_lens(ctx, 1);

}

/* Similar to spi_context_total_rx_len, except does not count words that have been finished

 * in the current buffer, ie only including what is remaining in the current buffer in the sum.

 */

static inline size_t spi_context_rx_len_left(struct spi_context *ctx)

{

	return ctx->rx_len + spi_context_count_rx_buf_lens(ctx, 1);