device/class/spi.h header reference
[Devices support library module]

The source code of this header can be browsed online.

This class enables driving SPI bus controllers. SPI controllers may be used from the application code but are most often used from device drivers of slave SPI devices.

A generic SPI requests scheduler is provided which allows sharing a single SPI bus by multiple slave devices. This has been designed to support concurrence of access from multiple slave drivers.

See also DRIVER_CLASS_SPI_CTRL.

Unlike most driver classes, SPI bus controller drivers are not able to queue more than one request at the same time. They provide the dev_spi_ctrl_transfer_t function which starts a single SPI transfer on the BUS, if not already busy. A deferred struct kroutine_s is scheduled when the transfer is over.

The dev_spi_ctrl_config_t function allows setting the bus speed and modes for the next transfer.

Device drivers of SPI slaves must not use this driver low level API directly as it does not allow sharing the bus with other slaves. The scheduler API described below is builtin on top of the present driver API. It requires the controller driver to store a spi scheduler context object in the device private data for use by libdevice.

This API allows scheduling multiple SPI requests which will be processed once the bus becomes idle. This allows sharing a SPI bus between multiple slave device drivers and the application.

Two types of requests can be scheduled concurrently: single transaction requests and bytecode based requests. Both are covered in the following sections.

A transaction is a single SPI transfer processed by the controller with an optional chip selection during the transfer. The chip select operation may rely either on the bus controller or on a gpio controller. The scheduler will take care of driving the chip select signal when the transfer actually takes place.

A transaction may be started on the SPI bus by calling the dev_spi_transaction_start function. A deferred struct kroutine_s is scheduled when the transaction is over.

When the controller is used from a slave device driver, the dev_drv_spi_transaction_init helper function may be used to initialize a request from the appropriate resource entries of the slave device.

See also CONFIG_DEVICE_SPI_TRANSACTION and struct dev_spi_ctrl_transaction_rq_s.

Driving a SPI slave device often requires many small transactions with some control depending on values read from the slave. Due to the asynchronous nature of the transaction requests API, this may be cumbersome to write a driver which use deferred execution of many small functions between transactions. A blocking C API would be easier to use but is not option as this would imply allocation of a thread stack for each slave device driver.

Moreover, the SPI bus interface being a de facto standard, some slave may have some specific requirements, either yielding or locking the bus for some time between transfers. Sharing the bus between such slaves without relying on specific code requires expressing timing and locking constraints to the scheduler for each transfer.

These issues are addressed by providing a SPI specific bytecode based on the Mutekh generic bytecode. A bytecode request come with a bytecode program containing some synchronous SPI transfer instructions as well as time delay, chip selection and gpio instructions. Generic bytecode instructions can be used for control. The bytecode can then be used to write some SPI macros operations specific to a given slave. A slave device driver may use several different bytecode routines to perform its task.

A bytecode request may be started on the SPI bus by calling the dev_spi_bytecode_start function. The SPI request scheduler designed to handle time delays and switching between scheduled bytecode programs as appropriate. A bytecode requests terminates when its associated bytecode program terminates. A deferred struct kroutine_s is scheduled when this occurs.

When the controller is used from a slave device driver, the dev_drv_spi_bytecode_init helper function may be used to initialize a request from the appropriate resource entries of the slave device.

See also CONFIG_DEVICE_SPI_BYTECODE and struct dev_spi_ctrl_bytecode_rq_s.

This section describes SPI specific bytecode instructions.

This instruction reset the current delay so that the spi_yield instruction will not suspend the execution of the bytecode if there are no other request to process.

This instruction setup a deadline deadline using the dev_timer_value_t pointed at the address in the provided register. The execution of next instructions follows the same semantics as spi_delay.

The deadline is expressed in timer units.

The CONFIG_DEVICE_SPI_BYTECODE_TIMER token must be defined in order to use this instruction.

This instruction setup a delay starting when the instruction is executed. The execution of the bytecode will not be suspended. When a spi_yield or spi_wait instruction is encountered, the execution is suspended if the delay has not elapsed at that time. The CONFIG_DEVICE_SPI_BYTECODE_TIMER token must be defined in order to use this instruction.

The delay given in the register is expressed timer unit.

This instruction fetches the current value of the timer associated with the bytecode virtual machine. The timer value is copied in the dev_timer_value_t pointed at the address in the provided register.

The CONFIG_DEVICE_SPI_BYTECODE_TIMER token must be defined in order to use this instruction.

This conditional instruction skips the next instruction if the timer deadline setup by spi_delay or spi_deadline has not been reached.

This conditional instruction skips the next instruction if the timer deadline pointed by the specified register has not been reached.

This instruction allows other requests targeting slave on the same SPI bus to be processed. The chip select must be in released state when this instruction is executed.

If a spi_delay instruction has been executed previously, the bytecode execution will not resume until the delay has elapsed.

This works like spi_yield but the delay can be canceled by dev_spi_bytecode_wakeup. When the delay is canceled, the next instruction is skipped.

This instruction allows other requests targeting slave on the same SPI bus to be processed. The dev_spi_bytecode_wakeup function must be called in order to resume execution of the bytecode.

This instruction acts as spi_delay followed by spi_yield.

This instruction acts as spi_deadline followed by spi_yield.

This works like spi_yield_delay but the delay can be canceled by dev_spi_bytecode_wakeup.

This works like spi_yield_deadline but the delay can be canceled by dev_spi_bytecode_wakeup.

This instruction instructs the controller to wait before resuming execution of the bytecode. No other request can be serviced on the same bus during the delay. Use spi_yield instead if access of the bus by other devices is allowed.

A previous spi_delay instruction must be used to setup the delay.

This instruction acts as spi_delay followed by spi_wait.

This instruction acts as spi_deadline followed by spi_wait.

This instruction set the SPI word width and the bit order in the struct dev_spi_ctrl_config_s object associated to the request. The width value is a constant between 1 and 32. The order is MSB first when order is 1.

This instruction sets the bit transfer rate in the struct dev_spi_ctrl_config_s object associated to the request. The register must contain the new bitrate value in bits per second.

This instructions transfer up to 16 bytes between some virtual machine registers and a SPI slave. The operands are the source register, the destination register, the transfer byte length and the chip select operation.

Available chip select operations are:

• CS_START, CS_CONTINUE: see DEV_SPI_CS_SET_NOP

• CS_END, CS_PULSE: see DEV_SPI_CS_SET_CLR

The format of data in registers is hardware dependent and needs to be converted by using the pack* and unpack* generic instructions. The transfered bytes are stored in contiguous registers, using at most one register for each group of 4 bytes. The index of the first register used to store the data and the number of bytes are expected as operands.

The spi_wr instruction is similar to spi_swp but discards data read from the slave.

The spi_rd instruction is similar to spi_swp but send padding bytes with the 0xff value.

This instruction reads and writes multiple SPI words using two buffers of bytes. The address of the read buffer is given by the value of the rar register operand and the address of the write buffer is given by the value of the raw register operand. These two registers must be contiguous. The amount of SPI words to transfer is given by the rl register operand.

The last operand specifies the chip select operation:

• CS_START, CS_CONTINUE: see DEV_SPI_CS_SET_NOP

• CS_END, CS_PULSE: see DEV_SPI_CS_SET_CLR

• CS_NOP: see DEV_SPI_CS_NOP_NOP

• CS_DESELECT: see DEV_SPI_CS_CLR_NOP

The spi_wrm instruction is similar to spi_swpm but discards data read from the slave.

The spi_rdm instruction is similar to spi_swpm but send padding bytes with the 0xff value.

The spi_pad instruction is similar to spi_swpm but discards data read from the slave and send padding bytes. Four packed bytes are used as padding pattern.

The spi_cs instruction performs a zero length transfer, only updating the chip select signal as specified.

This instruction sets the value of a gpio pin. The CONFIG_DEVICE_SPI_BYTECODE_GPIO token must be defined. The first operand selects the pin as an index of the dev_spi_ctrl_bytecode_rq_s::gpio_map array.

This instruction gets the value of a gpio pin. The first operand selects the pin as an index of the dev_spi_ctrl_bytecode_rq_s::gpio_map array.

This instruction mode the value of a gpio pin. The first operand selects the pin as an index of the dev_spi_ctrl_bytecode_rq_s::gpio_map array.

This macro is declared in device/class/spi.h source file, line 496.

See also dev_spi_ctrl_config_t.

This macro is declared in device/class/spi.h source file, line 616.

See also dev_spi_ctrl_cscfg_t.

This macro is declared in device/class/spi.h source file, line 566.

See also dev_spi_ctrl_transfer_t.

This macro is declared in device/class/spi.h source file, line 986.

This macro specifies a DEV_STATIC_RES_DEVCLASS_PARAM spi entry. This is typically used in slave device resources as a link to the associated SPI bus controller.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: defined( CONFIG_DEVICE_SPI )

This macro is declared in device/class/spi.h source file, line 989.

Documentation from alternate declaration:

This macro specifies a DEV_STATIC_RES_DEVCLASS_PARAM spi entry. This is typically used in slave device resources as a link to the associated SPI bus controller.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: not defined( CONFIG_DEVICE_SPI )

This macro is declared in device/class/spi.h source file, line 631.

This macro is declared in device/class/spi.h source file, line 383.

This function is declared in device/class/spi.h source file, line 965.

This helper function releases the device accessors associated with the SPI slave request.

This is available when CONFIG_DEVICE_SPI_BYTECODE is defined.

See also dev_drv_spi_bytecode_init.

This function is declared in device/class/spi.h source file, line 908.

This helper function initializes a SPI bytecode request for use in a SPI slave device driver. It is usually called from the slave driver initialization function to initialize a request stored in the driver private data. The bc_init function is called with the desc parameter.

The pointer to the SPI controller ctrl will be initialized according to the spi device resource entry of the slave.

If a 'spi-cs-id' entry is present in the device tree, the request is configured to use the chip select feature of the SPI controller. If a 'gpio-cs-id' and a 'gpio' entries are present, the request is configured to use a gpio pin as chip select instead.

In order to use the gpio bytecode instructions, the CONFIG_DEVICE_SPI_BYTECODE_GPIO token must be defined and the gpio parameter must be non-NULL. The pointer to a gpio accessor will be initialized and can then be used to setup the gpio_map and gpio_wmap fields of the request before starting the bytecode. The accessor can later be retrieved again using dev_spi_request_gpio.

When gpios are used either for chip select or from the bytecode, the gpio resource entry of the device must point to a valid gpio device.

In order to use delay related bytecode instructions, the CONFIG_DEVICE_SPI_BYTECODE_TIMER token must be defined and the timer parameter must be non-NULL. The pointer to a timer accessor will be initialized. The accessor can later be retrieved again using dev_spi_timer.

This is available when CONFIG_DEVICE_SPI_BYTECODE is defined.

See also dev_drv_spi_bytecode_cleanup.

This function is declared in device/class/spi.h source file, line 969.

This is available when CONFIG_DEVICE_SPI_TRANSACTION is defined.

This function is declared in device/class/spi.h source file, line 941.

This helper function initializes a SPI transaction request for use in a SPI slave device driver. It is usually called from the slave driver initialization function to initialize a request stored in the driver private data.

The pointer to the SPI controller ctrl will be initialized according to the spi device resource entry of the slave.

If a 'spi-cs-id' entry is present in the device tree, the request is configured to use the chip select feature of the SPI controller. If a 'gpio-cs-id' and a 'gpio' entries are present, the request is configured to use a gpio pin as chip select instead.

If the gpio parameter is not NULL, a pointer to a gpio accessor will be initialized as well.

This is available when CONFIG_DEVICE_SPI_TRANSACTION is defined.

See also dev_drv_spi_transaction_cleanup.

This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/spi.h source file, line 427.

Alternate declarations with same identifier: [1], [2].

This enum is declared in device/class/spi.h source file, line 431.

Alternate declarations with same identifier: [1], [2].

This function is declared in device/class/spi.h source file, line 865.

This function initializes a SPI bytecode request.

This is available when CONFIG_DEVICE_SPI_BYTECODE is defined.

This function is declared in device/class/spi.h source file, line 853.

This function schedules a SPI bytecode request for execution. The kroutine of the request will be called when the bytecode terminates.

This function returns an error only if the bytecode request is already running. All other errors are reported through err field of request by executing the associated kroutine.

When not busy, this function may also set the registers of the virtual machine before starting execution of the bytecode as if the bc_set_pc and bc_set_regs function were used. If the pc parameter is NULL, the pc is not changed.

The kroutine of the request may be executed from within this function. Please read Nested device request completion.

This is available when CONFIG_DEVICE_SPI_BYTECODE is defined.

This function is declared in device/class/spi.h source file, line 858.

This is available when CONFIG_DEVICE_SPI_BYTECODE is defined.

This function is declared in device/class/spi.h source file, line 981.

This function cancels the delay of the current or next spi_yieldc instruction in the bytecode. If this function is called before the next cancelable yield instruction, the instruction will be skipped and no yield will be performed.

This is reset when either a delay is canceled or the request is restarted. This returns an error if the request is not currently running.

This is available when CONFIG_DEVICE_SPI_BYTECODE is defined.

This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/spi.h source file, line 426.

Alternate declarations with same identifier: [1], [2].

This enum is declared in device/class/spi.h source file, line 443.

Alternate declarations with same identifier: [1], [2].

This function is declared in device/class/spi.h source file, line 824.

This helper function release the device accessor associated with the SPI request queue.

This is available when CONFIG_DEVICE_SPI_REQUEST is defined.

See also dev_spi_context_init.

This function is declared in device/class/spi.h source file, line 819.

This helper function initializes a SPI request queue struct for use in a SPI controller device driver. It is usually called from the controller driver initialization function to initialize a queue stored in the driver private context.

The dev_spi_ctrl_context_s::timer accessor is initialized using the device pointed to by the 'timer' device resource entry of the controller, if available.

This is available when CONFIG_DEVICE_SPI_REQUEST is defined.

This struct is declared in device/class/spi.h source file, line 471.

This struct specifies the id and configuration of chip select line associated to a SPI slave.

This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/spi.h source file, line 428.

Alternate declarations with same identifier: [1], [2].

This enum is declared in device/class/spi.h source file, line 457.

This enum specifies how the chip select line associated to a SPI slave is driven on a transfer.

Alternate declarations with same identifier: [1], [2].

See also struct dev_spi_cs_config_s.

This function is declared in device/class/spi.h source file, line 770.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_BYTECODE )

This struct is declared in device/class/spi.h source file, line 736.

This struct is the SPI bytecode request structure.

Fields common to all types of requests are inherited from struct dev_spi_ctrl_rq_s.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_BYTECODE )

This function is declared in device/class/spi.h source file, line 766.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_BYTECODE )

This function is declared in device/class/spi.h source file, line 766.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_BYTECODE )

This struct is declared in device/class/spi.h source file, line 479.

This typedef is declared in device/class/spi.h source file, line 509.

This typedef changes the configuration of the controller. If the controller doesn't support the requested configuration, this function returns -ENOTSUP.

This function ignores the cs_pol field of the configuration.

This typedef function returns -EBUSY if a transfer is currently being processed.

This declaration involves expansion of the DEV_SPI_CTRL_CONFIG macro.

This typedef is declared in device/class/spi.h source file, line 622.

This typedef sets the polarity of the specifed chip select line and drive the line so that the chip is not selected.

This declaration involves expansion of the DEV_SPI_CTRL_CSCFG macro.

This struct is declared in device/class/spi.h source file, line 517.

This struct describes the data buffers used during both struct dev_spi_ctrl_transfer_s and struct dev_spi_ctrl_transaction_rq_s requests.

This function is declared in device/class/spi.h source file, line 695.

This function invokes or schedules execution of the spi_ctrl request callback associated to the request. For use in device drivers.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

This function retrieves a pointer to the request when in the request completion callback routine.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

This function initializes the given spi_ctrl request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

This function initializes the given spi_ctrl request callback. This must be used before submitting the request to a driver.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

This function initializes the given spi_ctrl request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

This function initializes the given spi_ctrl request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This struct is declared in device/class/spi.h source file, line 650.

This struct is the SPI scheduler request base structure.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 695.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_REQUEST )

This function is declared in device/class/spi.h source file, line 723.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_TRANSACTION )

This struct is declared in device/class/spi.h source file, line 706.

This struct is the SPI transaction request structure.

Fields common to all types of requests are inherited from struct dev_spi_ctrl_rq_s.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_TRANSACTION )

This function is declared in device/class/spi.h source file, line 719.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_TRANSACTION )

This function is declared in device/class/spi.h source file, line 719.

Preprocessor condition: defined( CONFIG_DEVICE_SPI_TRANSACTION )

This struct is declared in device/class/spi.h source file, line 544.

This struct contains the SPI transfer request which may be started by calling the dev_spi_ctrl_transfer_t function of the driver.

See also SPI driver API.

This typedef is declared in device/class/spi.h source file, line 592.

This typedef starts an SPI transfer. A single spi data transfer can be started at the same time. This is the low level transfer function of the SPI device class. The dev_spi_transaction_start and dev_spi_bytecode_start functions are able to schedule requests for several SPI slaves on the same bus.

All fields of the transfer object except pvdata, err and accessor must be properly initialized before calling this function. The transfer will fail with -EBUSY if an other transfer is currently being processed.

The count field may be 0 if only the chip select operation needs to be performed.

The kroutine_exec function will be called on tr->kr when the transfer ends. This can happen before this function returns. The err field indicates the error status of the transfer.

The kroutine of the transfer may be executed from within this function. Please read Nested device request completion.

This declaration involves expansion of the DEV_SPI_CTRL_TRANSFER macro.

This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/spi.h source file, line 425.

Alternate declarations with same identifier: [1], [2].

This enum is declared in device/class/spi.h source file, line 437.

Alternate declarations with same identifier: [1], [2].

This function is declared in device/class/spi.h source file, line 959.

This function returns an accessor to the gpio device of the request.

This is available when CONFIG_DEVICE_SPI_BYTECODE_GPIO is defined.

This function is declared in device/class/spi.h source file, line 951.

This function returns an accessor to the timer associated with the spi controller of the request.

This is available when CONFIG_DEVICE_SPI_BYTECODE_TIMER is defined.

This function is declared in device/class/spi.h source file, line 916.

This function initializes a SPI transaction request.

This is available when CONFIG_DEVICE_SPI_TRANSACTION is defined.

This function is declared in device/class/spi.h source file, line 834.

This function schedules a SPI single transaction request for execution. The kroutine of the request will be called when the transaction is over.

The kroutine of the request may be executed from within this function. Please read Nested device request completion.

This is available when CONFIG_DEVICE_SPI_TRANSACTION is defined.

This function is declared in device/class/spi.h source file, line 607.

Synchronous spi wait function. This function uses the scheduler API to put the current context in wait state waiting for the given bytecode request to terminate.

This is available when CONFIG_MUTEK_CONTEXT_SCHED and CONFIG_DEVICE_SPI_BYTECODE are both defined.

This function is declared in device/class/spi.h source file, line 614.

Synchronous spi wait function. This function uses the scheduler API to put the current context in wait state waiting for the given transaction request to terminate.

This is available when CONFIG_MUTEK_CONTEXT_SCHED and CONFIG_DEVICE_SPI_TRANSACTION are both defined.

This function is declared in device/class/spi.h source file, line 599.

This helper function performs a SPI transfert as defined in tr and waits for end of transfert.

This is available when CONFIG_DEVICE_SPI and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 53 in device/class/spi.h source file, line 630.

This function returns a pointer to the public context stored in the device private data. This is used by the libdevice generic code of the class, not relevant for all classes.

This struct is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 21 in device/class/spi.h source file, line 630.

This struct is the device accessor object type for the spi_ctrl device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_SPI_CTRL, struct device_accessor_s and Device accessor.

This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 42 in device/class/spi.h source file, line 630.

This function casts a spi_ctrl device accessor to a generic device accessor

This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 35 in device/class/spi.h source file, line 630.

This function casts a generic device accessor to a spi_ctrl device accessor

This struct is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 6 in device/class/spi.h source file, line 630.

This struct is the driver API descriptor for the spi_ctrl device class.

See also DRIVER_CLASS_SPI_CTRL and struct driver_class_s.

This struct is declared in device/class/spi.h source file, line 779.

This struct is the SPI scheduler queue contained in private data of the SPI bus controller device.

This struct is for internal use only.