NAME

Device::Chip::Base::RegisteredI2C - base class for drivers of register-oriented I²C chips

DESCRIPTION

This subclass of Device::Chip provides some handy utility methods to implement a chip driver that supports a chip which (largely) operates on the common pattern of registers; that is, that writes to and reads from the chip are performed on numerically-indexed register locations, holding independent values. This is a common pattern that a lot of I²C chips adhere to.

CONSTANTS

REG_DATA_SIZE

Gives the number of bits of data each register occupies. Normally this value is 8, but sometimes chips like high-resolution ADCs and DACs might work with a larger size like 16 or 24. This value ought to be a multiple of 8.

Overriding this constant to a different value will affect the interpretation of the $len parameter to the register reading and writing methods.

METHODS

The following methods documented in an await expression return Future instances.

read_reg

   $val = await $chip->read_reg( $reg, $len );

Performs a write_then_read I²C transaction, sending the register number as a single byte value, then attempts to read the given number of register slots.

write_reg

   await $chip->write_reg( $reg, $val );

Performs a write I²C transaction, sending the register number as a single byte value followed by the data to write into it.

cached_read_reg

   $val = await $chip->cached_read_reg( $reg, $len );

Implements a cache around the given register location. Returns the last value known to have been read from or written to the register; or reads it from the actual chip if no interaction has yet been made. Once a cache slot has been created for the register by calling this method, the read_reg and write_reg methods will also keep it updated.

This method should be used by chip drivers for interacting with configuration-style registers; that is, registers that the chip itself will treat as simple storage of values. It is not suitable for registers that the chip itself will update.

cached_write_reg

   await $chip->cached_write_reg( $reg, $val );

Optionally writes a new value for the given register location. This method will invoke write_reg except if the register already exists in the cache and already has the given value according to the cache.

This method should be used by chip drivers for interacting with configuration-style registers; that is, registers that the chip itself will treat as simple storage of values. It is not suitable for registers that the chip itself will update.

cached_write_reg_masked

   await $chip->cached_write_reg_masked( $reg, $val, $mask );

Performs a read-modify-write operation to update the given register location. This method will first read the current value of the register for the length of the value and mask. It will then modify this value, taking bits from the value given by $val where the corresponding bit in $mask is set, or leaving them unchanged where the $mask bit is clear. This updated value is then written back.

Both the initial read and the subsequent write operation will pass through the cache as for "cached_read_reg" and "cached_write_reg".

The length of $mask must equal the length of $val. A mask value with all bits set is equivalent to just calling "cached_write_reg". A mask value with all bits clear is equivalent to no update (except that the chip registers may still be read to fill the cache.

This method should be used by chip drivers for interacting with configuration-style registers; that is, registers that the chip itself will treat as simple storage of values. It is not suitable for registers that the chip itself will update.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Device::Chip

perl -MCPAN -e shell
install Device::Chip