async_call: ashet.io.i2c.Execute
Documentation
Performs a sequence of I²C operations on the bus without interruption.
This function allows to ping devices, read or write data from/to the devices.
The operations are performed first-to-last without interruption. If an operation fails, the sequence will be aborted.
Lore:
This function was introduced instead of separate read and write functions, as it's sometimes necessary for certain I²C ICs (like EEPROMs) to have "atomic" read-after-write operations.
As both a singular read and a singular write can be expressed as a batch of one operation, this is the only available function on the I²C bus.
**Example:** Typical I²C EEPROMs have an internally maintained "memory cursor" which is advanced for every read operation. All write operations will update the cursor also for read operations.
This means that in an OS context, where scheduling can interrupt our process, performing a split "update cursor" write operation and "read data" read operation can be interrupted by another process also scheduling writes in between. This means that after we've set up our memory cursor to the desired address another process would change that before we read and we'll read data from the wrong memory location.
To prevent such a situation, this batch interface was introduced.
Inputs
bus: io.i2c.Bussequence: []io.i2c.OperationA mutable sequence of I²C operations. Will be processed first-to-last and the pointed
Operations will be changed during their execution.
Outputs
count: usizeThe number of successfully processed elements from
sequence.On success, the call returns exactly the length of the sequence, otherwise it returns the index of the element that failed.
Errors
InvalidHandleInvalidAddressAn operation in the
sequencecontained an invalid address.EmptyOperationAn operation that isn't
pingwas trying to process zero bytes.ExecutionFailedAn error happened during processing. Read
sequence[].errorto see which operations failed.