From 9dbdadb3f640285dfa0386846aadf4365fd24082 Mon Sep 17 00:00:00 2001 From: ladyada Date: Sat, 18 May 2019 14:37:08 -0400 Subject: [PATCH] doxdoxdox --- Adafruit_BusIO_Register.cpp | 89 ++++++++++++++++++++++++++++++++++++- Adafruit_BusIO_Register.h | 10 ++++- Adafruit_I2CDevice.h | 2 +- Adafruit_SPIDevice.h | 1 + 4 files changed, 98 insertions(+), 4 deletions(-) diff --git a/Adafruit_BusIO_Register.cpp b/Adafruit_BusIO_Register.cpp index d46f252..b31ac19 100644 --- a/Adafruit_BusIO_Register.cpp +++ b/Adafruit_BusIO_Register.cpp @@ -1,5 +1,13 @@ #include +/*! + * @brief Create a register we access over an I2C Device (which defines the bus and address) + * @param i2cdevice The I2CDevice to use for underlying I2C access + * @param reg_addr The address pointer value for the I2C/SMBus register, can be 8 or 16 bits + * @param width The width of the register data itself, defaults to 1 byte + * @param bitorder The bit order of the register (used when width is > 1), defaults to LSBFIRST + * @param address_width The width of the register address itself, defaults to 1 byte + */ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, uint16_t reg_addr, uint8_t width, uint8_t bitorder, uint8_t address_width) { _i2cdevice = i2cdevice; @@ -10,6 +18,15 @@ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, _width = width; } +/*! + * @brief Create a register we access over an SPI Device (which defines the bus and CS pin) + * @param spidevice The SPIDevice to use for underlying I2C access + * @param reg_addr The address pointer value for the I2C/SMBus register, can be 8 or 16 bits + * @param type The method we use to read/write data to SPI (which is not as well defined as I2C) + * @param width The width of the register data itself, defaults to 1 byte + * @param bitorder The bit order of the register (used when width is > 1), defaults to LSBFIRST + * @param address_width The width of the register address itself, defaults to 1 byte + */ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_SPIDevice *spidevice, uint16_t reg_addr, Adafruit_BusIO_SPIRegType type, uint8_t width, uint8_t bitorder, uint8_t address_width) { @@ -22,6 +39,17 @@ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_SPIDevice *spidevice, _width = width; } +/*! + * @brief Create a register we access over an I2C or SPI Device. This is a handy function because we + * can pass in NULL for the unused interface, allowing libraries to mass-define all the registers + * @param i2cdevice The I2CDevice to use for underlying I2C access, if NULL we use SPI + * @param spidevice The SPIDevice to use for underlying I2C access, if NULL we use I2C + * @param reg_addr The address pointer value for the I2C/SMBus register, can be 8 or 16 bits + * @param type The method we use to read/write data to SPI (which is not as well defined as I2C) + * @param width The width of the register data itself, defaults to 1 byte + * @param bitorder The bit order of the register (used when width is > 1), defaults to LSBFIRST + * @param address_width The width of the register address itself, defaults to 1 byte + */ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, Adafruit_SPIDevice *spidevice, Adafruit_BusIO_SPIRegType type, uint16_t reg_addr, uint8_t width, uint8_t bitorder, uint8_t address_width) { @@ -35,6 +63,12 @@ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, } +/*! + * @brief Write a buffer of data to the register location + * @param buffer Pointer to data to write + * @param len Number of bytes to write + * @return True on successful write (only really useful for I2C as SPI is uncheckable) + */ bool Adafruit_BusIO_Register::write(uint8_t *buffer, uint8_t len) { uint8_t addrbuffer[2] = {(uint8_t)(_address & 0xFF), (uint8_t)(_address>>8)}; @@ -51,6 +85,12 @@ bool Adafruit_BusIO_Register::write(uint8_t *buffer, uint8_t len) { return false; } +/*! + * @brief Write up to 4 bytes of data to the register location + * @param value Data to write + * @param numbytes How many bytes from 'value' to write + * @return True on successful write (only really useful for I2C as SPI is uncheckable) + */ bool Adafruit_BusIO_Register::write(uint32_t value, uint8_t numbytes) { if (numbytes == 0) { numbytes = _width; @@ -70,7 +110,10 @@ bool Adafruit_BusIO_Register::write(uint32_t value, uint8_t numbytes) { return write(_buffer, numbytes); } -// This does not do any error checking! returns 0xFFFFFFFF on failure +/*! + * @brief Read data from the register location. This does not do any error checking! + * @return Returns 0xFFFFFFFF on failure, value otherwise + */ uint32_t Adafruit_BusIO_Register::read(void) { if (! read(_buffer, _width)) { return -1; @@ -91,6 +134,12 @@ uint32_t Adafruit_BusIO_Register::read(void) { } +/*! + * @brief Read a buffer of data from the register location + * @param buffer Pointer to data to read into + * @param len Number of bytes to read + * @return True on successful write (only really useful for I2C as SPI is uncheckable) + */ bool Adafruit_BusIO_Register::read(uint8_t *buffer, uint8_t len) { uint8_t addrbuffer[2] = {(uint8_t)(_address & 0xFF), (uint8_t)(_address>>8)}; @@ -106,6 +155,11 @@ bool Adafruit_BusIO_Register::read(uint8_t *buffer, uint8_t len) { return false; } +/*! + * @brief Read 2 bytes of data from the register location + * @param value Pointer to uint16_t variable to read into + * @return True on successful write (only really useful for I2C as SPI is uncheckable) + */ bool Adafruit_BusIO_Register::read(uint16_t *value) { if (! read(_buffer, 2)) { return false; @@ -123,6 +177,11 @@ bool Adafruit_BusIO_Register::read(uint16_t *value) { return true; } +/*! + * @brief Read 1 byte of data from the register location + * @param value Pointer to uint8_t variable to read into + * @return True on successful write (only really useful for I2C as SPI is uncheckable) + */ bool Adafruit_BusIO_Register::read(uint8_t *value) { if (! read(_buffer, 1)) { return false; @@ -132,29 +191,52 @@ bool Adafruit_BusIO_Register::read(uint8_t *value) { return true; } +/*! + * @brief Pretty printer for this register + * @param s The Stream to print to, defaults to &Serial + */ void Adafruit_BusIO_Register::print(Stream *s) { uint32_t val = read(); s->print("0x"); s->print(val, HEX); } +/*! + * @brief Pretty printer for this register + * @param s The Stream to print to, defaults to &Serial + */ void Adafruit_BusIO_Register::println(Stream *s) { print(s); s->println(); } +/*! + * @brief Create a slice of the register that we can address without touching other bits + * @param reg The Adafruit_BusIO_Register which defines the bus/register + * @param bits The number of bits wide we are slicing + * @param shift The number of bits that our bit-slice is shifted from LSB + */ Adafruit_BusIO_RegisterBits::Adafruit_BusIO_RegisterBits(Adafruit_BusIO_Register *reg, uint8_t bits, uint8_t shift) { _register = reg; _bits = bits; _shift = shift; } +/*! + * @brief Read 4 bytes of data from the register + * @return data The 4 bytes to read + */ uint32_t Adafruit_BusIO_RegisterBits::read(void) { uint32_t val = _register->read(); val >>= _shift; return val & ((1 << (_bits+1)) - 1); } + +/*! + * @brief Write 4 bytes of data to the register + * @param data The 4 bytes to write + */ void Adafruit_BusIO_RegisterBits::write(uint32_t data) { uint32_t val = _register->read(); @@ -169,3 +251,8 @@ void Adafruit_BusIO_RegisterBits::write(uint32_t data) { _register->write(val, _register->width()); } +/*! + * @brief The width of the register data, helpful for doing calculations + * @returns The data width used when initializing the register + */ +uint8_t Adafruit_BusIO_Register::width(void) { return _width; } diff --git a/Adafruit_BusIO_Register.h b/Adafruit_BusIO_Register.h index 8ae2325..45ae1e1 100644 --- a/Adafruit_BusIO_Register.h +++ b/Adafruit_BusIO_Register.h @@ -10,6 +10,9 @@ typedef enum _Adafruit_BusIO_SPIRegType { ADDRBIT8_HIGH_TOREAD = 0, } Adafruit_BusIO_SPIRegType; +/*! + * @brief The class which defines a device register (a location to read/write data from) + */ class Adafruit_BusIO_Register { public: Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, uint16_t reg_addr, @@ -30,12 +33,11 @@ class Adafruit_BusIO_Register { bool read(uint8_t *buffer, uint8_t len); bool read(uint8_t *value); bool read(uint16_t *value); - bool read(uint32_t *value); uint32_t read(void); bool write(uint8_t *buffer, uint8_t len); bool write(uint32_t value, uint8_t numbytes=0); - uint8_t width(void) { return _width; } + uint8_t width(void); void print(Stream *s=&Serial); void println(Stream *s=&Serial); @@ -49,6 +51,10 @@ class Adafruit_BusIO_Register { uint8_t _buffer[4]; // we wont support anything larger than uint32 for non-buffered read }; + +/*! + * @brief The class which defines a slice of bits from within a device register (a location to read/write data from) + */ class Adafruit_BusIO_RegisterBits { public: Adafruit_BusIO_RegisterBits(Adafruit_BusIO_Register *reg, uint8_t bits, uint8_t shift); diff --git a/Adafruit_I2CDevice.h b/Adafruit_I2CDevice.h index 8a36d84..bdc361a 100644 --- a/Adafruit_I2CDevice.h +++ b/Adafruit_I2CDevice.h @@ -3,7 +3,7 @@ #ifndef Adafruit_I2CDevice_h #define Adafruit_I2CDevice_h - +///< The class which defines how we will talk to this device over I2C class Adafruit_I2CDevice { public: Adafruit_I2CDevice(uint8_t addr, TwoWire *theWire=&Wire); diff --git a/Adafruit_SPIDevice.h b/Adafruit_SPIDevice.h index 36df65d..230acda 100644 --- a/Adafruit_SPIDevice.h +++ b/Adafruit_SPIDevice.h @@ -10,6 +10,7 @@ #define MSBFIRST SPI_MSBFIRST #endif +///< The class which defines how we will talk to this device over SPI class Adafruit_SPIDevice { public: Adafruit_SPIDevice(int8_t cspin,