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

The source code of this header can be browsed online.

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

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

See also DRIVER_CLASS_I2C_CTRL.

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

Device drivers of I2C 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 built on top of the present driver API. It requires the controller driver to store an I2C scheduler context object in the device private data.

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

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

An I2C transaction is composed of multiple elementary transfers which perform multiple read or write operations atomically on the bus. A transaction begins implicitly with a START condition and ends with a STOP condition. A RESTART condition is also implicitly generated when the type of successive transfers are different. Successive transfers with the same type are seen as a single transfer on the bus.

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

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

See also CONFIG_DEVICE_I2C_TRANSACTION and struct dev_i2c_ctrl_transaction_rq_s.

Driving a I2C 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 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 an I2C specific bytecode based on the Mutekh Description. A bytecode request comes with a bytecode program containing some synchronous I2C transfer instructions as well as time delay and gpio instructions. Generic bytecode instructions can be used for control. The bytecode can then be used to write some I2C 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 I2C bus by calling the dev_i2c_bytecode_start function. The I2C request scheduler is 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_i2c_bytecode_init helper function may be used to initialize a request from the appropriate resource entries of the slave device.

See also CONFIG_DEVICE_I2C_BYTECODE and struct dev_i2c_ctrl_bytecode_rq_s.

This section describes I2C specific bytecode instructions.

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

The delay given in the register is expressed timer unit.

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

This instruction allows other requests targeting slave on the same i2c bus to be processed. This cannot be used if a transaction has been started until a STOP condition is generated. If a i2c_delay instruction has been executed previously, the bytecode execution will not resume until the delay has elapsed.

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

This instruction acts as i2c_delay followed by i2c_yield.

This instruction acts as i2c_delay followed by i2c_yieldc.

This schedules a transfer on the i2c bus. The third argument is of type dev_i2c_bc_completion_e which indicates how this transfer ends. In the case of the first transfer of the transaction, a start condition is generated on the bus.

When the transaction is split in multiple transfer instructions, the transfer may actually not be performed before the DEV_I2C_BC_STOP instruction. In case of a write instruction, the memory buffer or registers containing the output data must remain valid. In case of a read instruction, the memory buffer or registers used to store the input data may not be updated immediately.

Successive DEV_I2C_BC_CONTINUOUS transfers in different directions are forbidden. If a transfer error is reported by the i2c controller, the bytecode is terminated and the request ends with an error.

These conditional instructions are similar to other read and write instructions. If a NAK condition is detected on the bus, the next instruction is not skipped. When the transfer is successful, the next instruction is skipped. These instructions are usually used with the DEV_I2C_BC_STOP value as third argument. DEV_I2C_BC_CONTINUOUS and DEV_I2C_BC_RESTART are forbidden. DEV_I2C_BC_CONTINUOUS_SYNC and DEV_I2C_BC_RESTART_SYNC are not supported by all controllers.

These instuctions read data to memory and write data from memory. The buffer address and buffer byte length are passed via registers.

These instuctions respectively read and write the specified amount of bytes to virtual registers. 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.

This instruction sets the value of a gpio pin. The CONFIG_DEVICE_I2C_BYTECODE_GPIO token must be defined.

This instruction gets the value of a gpio pin.

This instruction mode the value of a gpio pin.

This macro is declared in device/class/i2c.h source file, line 414.

See also dev_i2c_ctrl_transfer_t.

This macro is declared in device/class/i2c.h source file, line 863.

This macro specifies a DEV_STATIC_RES_DEVCLASS_PARAM i2c entry. This is used in slave device resources as a link to the associated I2C bus controller with the associated slave address.

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

Preprocessor condition: defined( CONFIG_DEVICE_I2C )

This macro is declared in device/class/i2c.h source file, line 884.

Documentation from alternate declaration:

This macro specifies a DEV_STATIC_RES_DEVCLASS_PARAM i2c entry. This is used in slave device resources as a link to the associated I2C bus controller with the associated slave address.

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

Preprocessor condition: not defined( CONFIG_DEVICE_I2C )

This macro is declared in device/class/i2c.h source file, line 874.

This macro specifies a DEV_STATIC_RES_DEVCLASS_PARAM i2c entry. This is used to specified the bitrate of the i2c controller.

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

Preprocessor condition: defined( CONFIG_DEVICE_I2C )

This macro is declared in device/class/i2c.h source file, line 889.

Documentation from alternate declaration:

This macro specifies a DEV_STATIC_RES_DEVCLASS_PARAM i2c entry. This is used to specified the bitrate of the i2c controller.

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

Preprocessor condition: not defined( CONFIG_DEVICE_I2C )

This macro is declared in device/class/i2c.h source file, line 461.

See also struct driver_i2c_ctrl_s.

This macro is declared in device/class/i2c.h source file, line 309.

This macro is declared in device/class/i2c.h source file, line 308.

This macro is declared in device/class/i2c.h source file, line 307.

This macro is declared in device/class/i2c.h source file, line 306.

This macro is declared in device/class/i2c.h source file, line 311.

This macro is declared in device/class/i2c.h source file, line 310.

This macro is declared in device/class/i2c.h source file, line 312.

This macro is declared in device/class/i2c.h source file, line 269.

This function is declared in device/class/i2c.h source file, line 795.

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

This is available when CONFIG_DEVICE_I2C_BYTECODE is defined.

See also dev_drv_i2c_bytecode_init.

This function is declared in device/class/i2c.h source file, line 753.

This helper function initializes a I2C bytecode request for use in a I2C 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 I2C controller ctrl will be initialized according to the i2c device resource entry of the slave.

In order to use the gpio bytecode instructions, the CONFIG_DEVICE_I2C_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_i2c_request_gpio.

In order to use delay related bytecode instructions, the CONFIG_DEVICE_I2C_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_i2c_timer.

This is available when CONFIG_DEVICE_I2C_BYTECODE is defined.

See also dev_drv_i2c_bytecode_cleanup.

This function is declared in device/class/i2c.h source file, line 682.

This helper function release the device accessor associated with the I2C request context.

This is available when CONFIG_DEVICE_I2C is defined.

See also dev_drv_i2c_ctrl_context_init.

This function is declared in device/class/i2c.h source file, line 668.

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

The dev_i2c_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_I2C is defined.

This function is declared in device/class/i2c.h source file, line 799.

This is available when CONFIG_DEVICE_I2C_TRANSACTION is defined.

This function is declared in device/class/i2c.h source file, line 774.

This helper function initializes a I2C transaction request for use in a I2C 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 I2C controller ctrl will be initialized according to the i2c device resource entry of the slave.

This is available when CONFIG_DEVICE_I2C_TRANSACTION is defined.

See also dev_drv_i2c_transaction_cleanup.

This function is declared in device/class/i2c.h source file, line 722.

This function initializes a I2C bytecode request.

This is available when CONFIG_DEVICE_I2C_BYTECODE is defined.

This function is declared in device/class/i2c.h source file, line 710.

This function schedules a I2C 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.

If the pc parameter is not NULL, the bc_set_pc function is called before starting the bytecode, unless already running.

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

This is available when CONFIG_DEVICE_I2C_BYTECODE is defined.

This function is declared in device/class/i2c.h source file, line 715.

This is available when CONFIG_DEVICE_I2C_BYTECODE is defined.

This struct is declared in device/class/i2c.h source file, line 559.

This struct is the I2C bytecode request structure.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_BYTECODE )

This function is declared in device/class/i2c.h source file, line 590.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_BYTECODE )

This function is declared in device/class/i2c.h source file, line 590.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_BYTECODE )

This function is declared in device/class/i2c.h source file, line 496.

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

Preprocessor condition: defined( CONFIG_DEVICE_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

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

Preprocessor condition: defined( CONFIG_DEVICE_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

This function initializes the given i2c_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_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

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

Preprocessor condition: defined( CONFIG_DEVICE_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

This function initializes the given i2c_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_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

This function initializes the given i2c_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_I2C_REQUEST )

This struct is declared in device/class/i2c.h source file, line 475.

This struct is the I2C scheduler request base structure.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_REQUEST )

This function is declared in device/class/i2c.h source file, line 496.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_REQUEST )

This struct is declared in device/class/i2c.h source file, line 515.

This struct describes the transfer data used by struct dev_i2c_ctrl_transaction_rq_s requests.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_TRANSACTION )

This enum is declared in device/class/i2c.h source file, line 506.

This enum specifies the type of I2C transaction.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_TRANSACTION )

This struct is declared in device/class/i2c.h source file, line 529.

This struct is the I2C transaction request structure.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_TRANSACTION )

This function is declared in device/class/i2c.h source file, line 549.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_TRANSACTION )

This function is declared in device/class/i2c.h source file, line 549.

Preprocessor condition: defined( CONFIG_DEVICE_I2C_TRANSACTION )

This struct is declared in device/class/i2c.h source file, line 380.

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

See also I2C controller driver API.

This typedef is declared in device/class/i2c.h source file, line 453.

This typedef starts an I2C transfer. A single I2C transfer can be started at a time. This is a low level transfer function of the I2C device class.

The dev_i2c_ctrl_transfer_s::type field defines the kind of the transfer (read or write) and indicates how it must end. The I2C controller generates a START condition at the beginning of every transaction.

There are three ways of ending a transfer: continuous, stop and restart. An I2c transaction is defined as a transfer ending with a stop condition optionally preceded by some other continuous or restart transfers. Consecutive continuous transfers of different types are not supported.

In the case where the transfer generates an error, the transaction is aborted, the bus is released and the internal state of the driver is reset. The following error codes may be reported:

• -EBUSY Another transfer is currently being processed.

• -EHOSTUNREACH Got a NACK after a slave address.

• -EAGAIN Got a NACK after some data byte.

• -EIO Unexpected I/O error.

• -ENOTSUP The read restart operation is not supported by the controller.

All fields of the transfer object except pvdata and error must be properly initialized before calling this function.

A transfer with a null size has an undefined behavior.

The kroutine_exec function will be called when the transfer ends. The kroutine of the request may be executed from within this function. Please read Nested device request completion.

This declaration involves expansion of the DEV_I2C_CTRL_TRANSFER macro.

This enum is declared in device/class/i2c.h source file, line 317.

This enum specifies the operation performed by an I2C struct dev_i2c_ctrl_transfer_s.

This function is declared in device/class/i2c.h source file, line 790.

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

This is available when CONFIG_DEVICE_I2C_BYTECODE_GPIO is defined.

This function is declared in device/class/i2c.h source file, line 783.

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

This is available when CONFIG_DEVICE_I2C_BYTECODE_TIMER is defined.

This function is declared in device/class/i2c.h source file, line 760.

This function initializes a I2C transaction request.

This is available when CONFIG_DEVICE_I2C_TRANSACTION is defined.

This function is declared in device/class/i2c.h source file, line 692.

This function schedules a I2C 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_I2C_TRANSACTION is defined.

This function is declared in device/class/i2c.h source file, line 826.

Synchronous i2c 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_I2C_BYTECODE are both defined.

This function is declared in device/class/i2c.h source file, line 818.

Synchronous i2c 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_I2C_TRANSACTION are both defined.

This function is declared in device/class/i2c.h source file, line 811.

This function cancels the delay of the current or next i2c_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_I2C_BYTECODE is defined.

This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 51 in device/class/i2c.h source file, line 459.

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 19 in device/class/i2c.h source file, line 459.

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

See also DRIVER_CLASS_I2C_CTRL, struct device_accessor_s and Device accessor.

This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 40 in device/class/i2c.h source file, line 459.

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

This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 33 in device/class/i2c.h source file, line 459.

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

This function is declared in device/class/i2c.h source file, line 843.

This is available when CONFIG_DEVICE_I2C and CONFIG_DEVICE_RESOURCE_ALLOC are both defined.

This function is declared in device/class/i2c.h source file, line 857.

This is available when CONFIG_DEVICE_I2C and CONFIG_DEVICE_RESOURCE_ALLOC are both defined.

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

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

See also DRIVER_CLASS_I2C_CTRL and struct driver_class_s.

This function is declared in device/class/i2c.h source file, line 672.

This is available when CONFIG_DEVICE_I2C is defined.

This function is for internal use only.

See also dev_drv_i2c_ctrl_context_cleanup.

This function is declared in device/class/i2c.h source file, line 648.

This is available when CONFIG_DEVICE_I2C is defined.

This function is for internal use only.

See also dev_drv_i2c_ctrl_context_init.

This struct is declared in device/class/i2c.h source file, line 600.

This struct is the I2C scheduler context contained in private data of the I2C bus controller device.

This struct is for internal use only.