Ted Grosch / Mbed OS Nucleo_TOF_I2C_OS5

New Version with OS5

register.h@0:62b846b3988a, 2020-10-25 (annotated)

Committer:
tgrosch
Date:
Sun Oct 25 00:58:24 2020 +0000
Revision:
0:62b846b3988a
First successful compile.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
tgrosch 0:62b846b3988a 1 /*!
tgrosch 0:62b846b3988a 2 * \file register.h
tgrosch 0:62b846b3988a 3 * \author Karthik Rajagopal <krthik@ti.com>
tgrosch 0:62b846b3988a 4 * \version 0.9.1
tgrosch 0:62b846b3988a 5 *
tgrosch 0:62b846b3988a 6 * \section COPYRIGHT
tgrosch 0:62b846b3988a 7 * TEXAS INSTRUMENTS TEXT FILE LICENSE
tgrosch 0:62b846b3988a 8 * Copyright (c) 2018 Texas Instruments Incorporated
tgrosch 0:62b846b3988a 9 * All rights reserved not granted herein.
tgrosch 0:62b846b3988a 10 * Limited License.
tgrosch 0:62b846b3988a 11 * Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive license under copyrights and patents it now or hereafter owns or controls to make, have made, use, import, offer to sell and sell ("Utilize") this software subject to the terms herein. With respect to the foregoing patent license, such license is granted solely to the extent that any such patent is necessary to Utilize the software alone. The patent license shall not apply to any combinations which include this software, other than combinations with devices manufactured by or for TI ("TI Devices"). No hardware patent is licensed hereunder.
tgrosch 0:62b846b3988a 12 * Redistributions must preserve existing copyright notices and reproduce this license (including the above copyright notice and the disclaimer and (if applicable) source code license limitations below) in the documentation and/or other materials provided with the distribution
tgrosch 0:62b846b3988a 13 * Redistribution and use in binary form, without modification, are permitted provided that the following conditions are met:
tgrosch 0:62b846b3988a 14 * * No reverse engineering, decompilation, or disassembly of this software is permitted with respect to any software provided in binary form.
tgrosch 0:62b846b3988a 15 * * any redistribution and use are licensed by TI for use only with TI Devices.
tgrosch 0:62b846b3988a 16 * * Nothing shall obligate TI to provide you with source code for the software licensed and provided to you in object code.
tgrosch 0:62b846b3988a 17 * If software source code is provided to you, modification and redistribution of the source code are permitted provided that the following conditions are met:
tgrosch 0:62b846b3988a 18 * * any redistribution and use of the source code, including any resulting derivative works, are licensed by TI for use only with TI Devices.
tgrosch 0:62b846b3988a 19 * * any redistribution and use of any object code compiled from the source code and any resulting derivative works, are licensed by TI for use only with TI Devices.
tgrosch 0:62b846b3988a 20 * Neither the name of Texas Instruments Incorporated nor the names of its suppliers may be used to endorse or promote products derived from this software without specific prior written permission.
tgrosch 0:62b846b3988a 21 * DISCLAIMER.
tgrosch 0:62b846b3988a 22 * THIS SOFTWARE IS PROVIDED BY TI AND TI'S LICENSORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TI AND TI'S LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
tgrosch 0:62b846b3988a 23 *
tgrosch 0:62b846b3988a 24 * \section DESCRIPTION
tgrosch 0:62b846b3988a 25 * The file contains class descriptions and methods for register control for OPT3101 device
tgrosch 0:62b846b3988a 26 */
tgrosch 0:62b846b3988a 27
tgrosch 0:62b846b3988a 28 #ifndef REGISTER_H_
tgrosch 0:62b846b3988a 29 #define REGISTER_H_
tgrosch 0:62b846b3988a 30
tgrosch 0:62b846b3988a 31 #include <stdint.h>
tgrosch 0:62b846b3988a 32 #include "hostController.h"
tgrosch 0:62b846b3988a 33
tgrosch 0:62b846b3988a 34
tgrosch 0:62b846b3988a 35 /*! \class OPT3101::deviceRegister
tgrosch 0:62b846b3988a 36 \brief Class that contains positional information for registers in the register map
tgrosch 0:62b846b3988a 37
tgrosch 0:62b846b3988a 38 Class that contains positional information for a register in OPT3101 device.
tgrosch 0:62b846b3988a 39 OPT3101 has 256 registers each 24 bits wide (OPT3101::deviceRegister::msb of 23 and OPT3101::deviceRegister::lsb of 0 with OPT3101::deviceRegister::address varying from 0 to 255)
tgrosch 0:62b846b3988a 40 Bits are groups together and are addressed with a name. Registers have names, placed at different segments of the register map.
tgrosch 0:62b846b3988a 41 For eg: tmain (temperature of main temp sensor) of OPT3101 occupies location with address 10 from msb of 23 bits to 12 bits
tgrosch 0:62b846b3988a 42 in other words OPT3101::deviceRegister::address=10 OPT3101::deviceRegister::msb=23 OPT3101::deviceRegister::lsb=12
tgrosch 0:62b846b3988a 43 This class helps resolve programmers to read and write I2C to OPT3101 device by writing program code with higher level of abstraction with register names rather than dealing with positions of registers
tgrosch 0:62b846b3988a 44 OPT3101::deviceRegister class helps resolve MSB, LSB and ADDRESS fields for a register by its name.
tgrosch 0:62b846b3988a 45 Using this class gives user a functional name for each register making the register read and write more readable and meaningful.
tgrosch 0:62b846b3988a 46 In case of OPT3101 device there are some registers which span across 2 address positions, hence the OPT3101::deviceRegister::address, OPT3101::deviceRegister::msb and OPT3101::deviceRegister::lsb have 2 allocations each. In most register cases
tgrosch 0:62b846b3988a 47 they may not end up using both the allocations. The actual usage can be found using OPT3101::deviceRegister::size member <br>
tgrosch 0:62b846b3988a 48 Example of register which has more than 1 address is OPT3101::registers::amplitude_min_thr which spans across register 0x10 from bits 23:16 and 0x11 from bites 23:16
tgrosch 0:62b846b3988a 49 */
tgrosch 0:62b846b3988a 50 namespace OPT3101{
tgrosch 0:62b846b3988a 51 class deviceRegister{
tgrosch 0:62b846b3988a 52 private:
tgrosch 0:62b846b3988a 53 /*!
tgrosch 0:62b846b3988a 54 * \brief Function to resolve actual data to be written before calling writeI2C function
tgrosch 0:62b846b3988a 55 *
tgrosch 0:62b846b3988a 56 * \param[in] value; This resolves the value to number of physical i2c address and register writes based on the MSP, LSB and ADDRESS members.
tgrosch 0:62b846b3988a 57 * \return Nothing
tgrosch 0:62b846b3988a 58 */
tgrosch 0:62b846b3988a 59 void write(int32_t registerData);
tgrosch 0:62b846b3988a 60 /*!
tgrosch 0:62b846b3988a 61 * \brief Function read I2C from the specified address index
tgrosch 0:62b846b3988a 62 * Intended as internal function to perform I2C read for a particular address index for the register
tgrosch 0:62b846b3988a 63 * \param[in] addressIndex
tgrosch 0:62b846b3988a 64 * \return Nothing
tgrosch 0:62b846b3988a 65 *
tgrosch 0:62b846b3988a 66 */
tgrosch 0:62b846b3988a 67 uint32_t read(uint8_t addressIndex);
tgrosch 0:62b846b3988a 68 /*!
tgrosch 0:62b846b3988a 69 * \brief Function that invokes I2C read transaction for the register given the address
tgrosch 0:62b846b3988a 70 * Function that invokes I2C transaction for the register given the address
tgrosch 0:62b846b3988a 71 * \param[in] address
tgrosch 0:62b846b3988a 72 * \return value read for the address specified
tgrosch 0:62b846b3988a 73 *
tgrosch 0:62b846b3988a 74 */
tgrosch 0:62b846b3988a 75 uint32_t readI2C(uint8_t address);
tgrosch 0:62b846b3988a 76 /*!
tgrosch 0:62b846b3988a 77 * \brief Function that invokes I2C write transaction for the register given the address and the data
tgrosch 0:62b846b3988a 78 * Function that invokes I2C transaction for the register given the address and data
tgrosch 0:62b846b3988a 79 * \param[in] address
tgrosch 0:62b846b3988a 80 * \param[in] data
tgrosch 0:62b846b3988a 81 * \return Nothing
tgrosch 0:62b846b3988a 82 *
tgrosch 0:62b846b3988a 83 */
tgrosch 0:62b846b3988a 84 void writeI2C(uint8_t address, uint32_t data);
tgrosch 0:62b846b3988a 85 public:
tgrosch 0:62b846b3988a 86 uint8_t msb[1]; ///< This is the MSB position of this register. The register occupies the OPT3101::deviceRegister::address from OPT3101::deviceRegister::msb to OPT3101::deviceRegister::lsb
tgrosch 0:62b846b3988a 87 uint8_t lsb[1]; ///< This is the LSB position of this register. The register occupies the OPT3101::deviceRegister::address from OPT3101::deviceRegister::msb to OPT3101::deviceRegister::lsb
tgrosch 0:62b846b3988a 88 uint8_t address[1]; ///< This is the ADDRESS of this register. The register occupies the OPT3101::deviceRegister::address from OPT3101::deviceRegister::msb to OPT3101::deviceRegister::lsb
tgrosch 0:62b846b3988a 89 uint8_t size; ///< This specifies how many ADDRESS does this register span across. For eg: There are registers which span multiple address locations in chunks.
tgrosch 0:62b846b3988a 90 /*!
tgrosch 0:62b846b3988a 91 * \brief Constructor for class OPT3101::deviceRegister
tgrosch 0:62b846b3988a 92 * Constructor allocated size to each register instance on construction
tgrosch 0:62b846b3988a 93 * \param[in] size; size (typically 1 or 2 bytes) determines the number of segments that the register is divided in to.
tgrosch 0:62b846b3988a 94 *
tgrosch 0:62b846b3988a 95 */
tgrosch 0:62b846b3988a 96 deviceRegister(uint8_t size);
tgrosch 0:62b846b3988a 97 /*!
tgrosch 0:62b846b3988a 98 * \brief Operator overload for '='.
tgrosch 0:62b846b3988a 99 *
tgrosch 0:62b846b3988a 100 * This makes calling this class simpler. dev.register=value will resolve the register address and value and invoke hostController::writeI2C method
tgrosch 0:62b846b3988a 101 * With proper implementation of the hostController::writeI2C methods the h/w would receive resolved I2C WRITE commands
tgrosch 0:62b846b3988a 102 * The write operations are read modify writes to make the system robust
tgrosch 0:62b846b3988a 103 * A single call of this method could invoke up to 2 I2C READ and 2 I2C WRITE transaction depending on the register
tgrosch 0:62b846b3988a 104 * \param[in] value; value to be set to register
tgrosch 0:62b846b3988a 105 * \return Nothing
tgrosch 0:62b846b3988a 106 *
tgrosch 0:62b846b3988a 107 */
tgrosch 0:62b846b3988a 108 void operator=(int32_t value);
tgrosch 0:62b846b3988a 109 /*!
tgrosch 0:62b846b3988a 110 * \brief Function called to read the value of register
tgrosch 0:62b846b3988a 111 *
tgrosch 0:62b846b3988a 112 * This method provides an abstraction for register to be used seamlessly with code for read register operations.
tgrosch 0:62b846b3988a 113 * hostController::readI2C method is invoked with OPT3101::deviceRegister::address fields and the resulting register value is combined as per the register positional information and reported as a uint32_t number
tgrosch 0:62b846b3988a 114 * A single call of this method could invoke up to 2 I2C READ transaction depending on the register
tgrosch 0:62b846b3988a 115 * \return value; value is reading of register from OPT3101 device
tgrosch 0:62b846b3988a 116 */
tgrosch 0:62b846b3988a 117 uint32_t read();
tgrosch 0:62b846b3988a 118 };
tgrosch 0:62b846b3988a 119 class deviceRegister2{
tgrosch 0:62b846b3988a 120 private:
tgrosch 0:62b846b3988a 121 /*!
tgrosch 0:62b846b3988a 122 * \brief Function to resolve actual data to be written before calling writeI2C function
tgrosch 0:62b846b3988a 123 *
tgrosch 0:62b846b3988a 124 * \param[in] value; This resolves the value to number of physical i2c address and register writes based on the MSP, LSB and ADDRESS members.
tgrosch 0:62b846b3988a 125 * \return Nothing
tgrosch 0:62b846b3988a 126 */
tgrosch 0:62b846b3988a 127 void write(int32_t registerData);
tgrosch 0:62b846b3988a 128 /*!
tgrosch 0:62b846b3988a 129 * \brief Function read I2C from the specified address index
tgrosch 0:62b846b3988a 130 * Intended as internal function to perform I2C read for a particular address index for the register
tgrosch 0:62b846b3988a 131 * \param[in] addressIndex
tgrosch 0:62b846b3988a 132 * \return Nothing
tgrosch 0:62b846b3988a 133 *
tgrosch 0:62b846b3988a 134 */
tgrosch 0:62b846b3988a 135 uint32_t read(uint8_t addressIndex);
tgrosch 0:62b846b3988a 136 /*!
tgrosch 0:62b846b3988a 137 * \brief Function that invokes I2C read transaction for the register given the address
tgrosch 0:62b846b3988a 138 * Function that invokes I2C transaction for the register given the address
tgrosch 0:62b846b3988a 139 * \param[in] address
tgrosch 0:62b846b3988a 140 * \return value read for the address specified
tgrosch 0:62b846b3988a 141 *
tgrosch 0:62b846b3988a 142 */
tgrosch 0:62b846b3988a 143 uint32_t readI2C(uint8_t address);
tgrosch 0:62b846b3988a 144 /*!
tgrosch 0:62b846b3988a 145 * \brief Function that invokes I2C write transaction for the register given the address and the data
tgrosch 0:62b846b3988a 146 * Function that invokes I2C transaction for the register given the address and data
tgrosch 0:62b846b3988a 147 * \param[in] address
tgrosch 0:62b846b3988a 148 * \param[in] data
tgrosch 0:62b846b3988a 149 * \return Nothing
tgrosch 0:62b846b3988a 150 *
tgrosch 0:62b846b3988a 151 */
tgrosch 0:62b846b3988a 152 void writeI2C(uint8_t address, uint32_t data);
tgrosch 0:62b846b3988a 153 public:
tgrosch 0:62b846b3988a 154 uint8_t msb[2]; ///< This is the MSB position of this register. The register occupies the OPT3101::deviceRegister::address from OPT3101::deviceRegister::msb to OPT3101::deviceRegister::lsb
tgrosch 0:62b846b3988a 155 uint8_t lsb[2]; ///< This is the LSB position of this register. The register occupies the OPT3101::deviceRegister::address from OPT3101::deviceRegister::msb to OPT3101::deviceRegister::lsb
tgrosch 0:62b846b3988a 156 uint8_t address[2]; ///< This is the ADDRESS of this register. The register occupies the OPT3101::deviceRegister::address from OPT3101::deviceRegister::msb to OPT3101::deviceRegister::lsb
tgrosch 0:62b846b3988a 157 uint8_t size; ///< This specifies how many ADDRESS does this register span across. For eg: There are registers which span multiple address locations in chunks.
tgrosch 0:62b846b3988a 158 /*!
tgrosch 0:62b846b3988a 159 * \brief Constructor for class OPT3101::deviceRegister
tgrosch 0:62b846b3988a 160 * Constructor allocated size to each register instance on construction
tgrosch 0:62b846b3988a 161 * \param[in] size; size (typically 1 or 2 bytes) determines the number of segments that the register is divided in to.
tgrosch 0:62b846b3988a 162 *
tgrosch 0:62b846b3988a 163 */
tgrosch 0:62b846b3988a 164 deviceRegister2(uint8_t size);
tgrosch 0:62b846b3988a 165 /*!
tgrosch 0:62b846b3988a 166 * \brief Operator overload for '='.
tgrosch 0:62b846b3988a 167 *
tgrosch 0:62b846b3988a 168 * This makes calling this class simpler. dev.register=value will resolve the register address and value and invoke hostController::writeI2C method
tgrosch 0:62b846b3988a 169 * With proper implementation of the hostController::writeI2C methods the h/w would receive resolved I2C WRITE commands
tgrosch 0:62b846b3988a 170 * The write operations are read modify writes to make the system robust
tgrosch 0:62b846b3988a 171 * A single call of this method could invoke up to 2 I2C READ and 2 I2C WRITE transaction depending on the register
tgrosch 0:62b846b3988a 172 * \param[in] value; value to be set to register
tgrosch 0:62b846b3988a 173 * \return Nothing
tgrosch 0:62b846b3988a 174 *
tgrosch 0:62b846b3988a 175 */
tgrosch 0:62b846b3988a 176 void operator=(int32_t value);
tgrosch 0:62b846b3988a 177 /*!
tgrosch 0:62b846b3988a 178 * \brief Function called to read the value of register
tgrosch 0:62b846b3988a 179 *
tgrosch 0:62b846b3988a 180 * This method provides an abstraction for register to be used seamlessly with code for read register operations.
tgrosch 0:62b846b3988a 181 * hostController::readI2C method is invoked with OPT3101::deviceRegister::address fields and the resulting register value is combined as per the register positional information and reported as a uint32_t number
tgrosch 0:62b846b3988a 182 * A single call of this method could invoke up to 2 I2C READ transaction depending on the register
tgrosch 0:62b846b3988a 183 * \return value; value is reading of register from OPT3101 device
tgrosch 0:62b846b3988a 184 */
tgrosch 0:62b846b3988a 185 uint32_t read();
tgrosch 0:62b846b3988a 186 };
tgrosch 0:62b846b3988a 187
tgrosch 0:62b846b3988a 188 }
tgrosch 0:62b846b3988a 189 #endif /* REGISTER_HPP_ */
tgrosch 0:62b846b3988a 190