register.h

00001 /*!
00002 * \file register.h
00003 * \author  Karthik Rajagopal <krthik@ti.com>
00004 * \version 0.9.1
00005 *
00006 * \section COPYRIGHT
00007 * TEXAS INSTRUMENTS TEXT FILE LICENSE
00008 * Copyright (c) 2018 Texas Instruments Incorporated
00009 * All rights reserved not granted herein.
00010 * Limited License.
00011 * 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.
00012 * 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
00013 * Redistribution and use in binary form, without modification, are permitted provided that the following conditions are met:
00014 * * No reverse engineering, decompilation, or disassembly of this software is permitted with respect to any software provided in binary form.
00015 * * any redistribution and use are licensed by TI for use only with TI Devices.
00016 * * Nothing shall obligate TI to provide you with source code for the software licensed and provided to you in object code.
00017 * If software source code is provided to you, modification and redistribution of the source code are permitted provided that the following conditions are met:
00018 * * any redistribution and use of the source code, including any resulting derivative works, are licensed by TI for use only with TI Devices.
00019 * * 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.
00020 * 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.
00021 * DISCLAIMER.
00022 * 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.
00023 *
00024 * \section DESCRIPTION
00025 * The file contains class descriptions and methods for register control for OPT3101 device
00026 */
00027 
00028 #ifndef REGISTER_H_
00029 #define REGISTER_H_
00030 
00031 #include <stdint.h>
00032 #include "hostController.h "
00033 
00034 
00035 /*! \class OPT3101::deviceRegister
00036 \brief Class that contains positional information for registers in the register map  
00037 
00038 Class that contains positional information for a register in OPT3101 device.
00039 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)
00040 Bits are groups together and are addressed with a name. Registers have names, placed at different segments of the register map.
00041 For eg: tmain (temperature of main temp sensor) of OPT3101 occupies location with address 10 from msb of 23 bits to 12 bits
00042 in other words OPT3101::deviceRegister::address=10 OPT3101::deviceRegister::msb=23 OPT3101::deviceRegister::lsb=12
00043 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
00044 OPT3101::deviceRegister class helps resolve MSB, LSB and ADDRESS fields for a register by its name.  
00045 Using this class gives user a functional name for each register making the register read and write more readable and meaningful. 
00046 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 
00047 they may not end up using both the allocations. The actual usage can be found using OPT3101::deviceRegister::size member <br>
00048 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 
00049 */
00050 namespace OPT3101{
00051 class deviceRegister{
00052     private:
00053         /*!
00054         * \brief Function to resolve actual data to be written before calling writeI2C function
00055         *
00056         * \param[in] value; This resolves the value to number of physical i2c address and register writes based on the MSP, LSB and ADDRESS members.
00057         * \return Nothing
00058         */
00059         void write(int32_t registerData);
00060         /*!
00061         * \brief Function read I2C from the specified address index
00062         * Intended as internal function to perform I2C read for a particular address index for the register
00063         * \param[in] addressIndex 
00064         * \return Nothing
00065         * 
00066         */
00067         uint32_t read(uint8_t addressIndex);
00068         /*!
00069         * \brief Function that invokes I2C read transaction for the register given the address
00070         * Function that invokes I2C transaction for the register given the address
00071         * \param[in] address
00072         * \return value read for the address specified 
00073         * 
00074         */
00075         uint32_t readI2C(uint8_t address);
00076         /*!
00077         * \brief Function that invokes I2C write transaction for the register given the address and the data 
00078         * Function that invokes I2C transaction for the register given the address and data
00079         * \param[in] address
00080         * \param[in] data
00081         * \return Nothing
00082         * 
00083         */
00084         void writeI2C(uint8_t address, uint32_t data);
00085     public:
00086         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
00087         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
00088         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
00089         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.
00090         /*!
00091         * \brief Constructor for class OPT3101::deviceRegister
00092         *  Constructor allocated size to each register instance on construction
00093         * \param[in] size; size (typically 1 or 2 bytes) determines the number of segments that the register is divided in to.
00094         *
00095         */
00096         deviceRegister(uint8_t size);
00097         /*!
00098         * \brief Operator overload for '='.
00099         *
00100         * This makes calling this class simpler. dev.register=value will resolve the register address and value and invoke hostController::writeI2C method 
00101         * With proper implementation of the hostController::writeI2C methods the h/w would receive resolved I2C WRITE commands 
00102         * The write operations are read modify writes to make the system robust
00103         *  A single call of this method could invoke up to 2 I2C READ and 2 I2C WRITE transaction depending on the register
00104         * \param[in] value; value to be set to register
00105         * \return Nothing
00106         * 
00107         */
00108         void operator=(int32_t value);
00109         /*!
00110         * \brief Function called to read the value of register 
00111         *
00112         *  This method provides an abstraction for register to be used seamlessly with code for read register operations. 
00113         *  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
00114         *  A single call of this method could invoke up to 2 I2C READ transaction depending on the register
00115         * \return value; value is reading of register from OPT3101 device
00116         */
00117         uint32_t read();
00118 };
00119 class deviceRegister2{
00120     private:
00121         /*!
00122         * \brief Function to resolve actual data to be written before calling writeI2C function
00123         *
00124         * \param[in] value; This resolves the value to number of physical i2c address and register writes based on the MSP, LSB and ADDRESS members.
00125         * \return Nothing
00126         */
00127         void write(int32_t registerData);
00128         /*!
00129         * \brief Function read I2C from the specified address index
00130         * Intended as internal function to perform I2C read for a particular address index for the register
00131         * \param[in] addressIndex
00132         * \return Nothing
00133         *
00134         */
00135         uint32_t read(uint8_t addressIndex);
00136         /*!
00137         * \brief Function that invokes I2C read transaction for the register given the address
00138         * Function that invokes I2C transaction for the register given the address
00139         * \param[in] address
00140         * \return value read for the address specified
00141         *
00142         */
00143         uint32_t readI2C(uint8_t address);
00144         /*!
00145         * \brief Function that invokes I2C write transaction for the register given the address and the data
00146         * Function that invokes I2C transaction for the register given the address and data
00147         * \param[in] address
00148         * \param[in] data
00149         * \return Nothing
00150         *
00151         */
00152         void writeI2C(uint8_t address, uint32_t data);
00153     public:
00154         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
00155         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
00156         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
00157         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.
00158         /*!
00159         * \brief Constructor for class OPT3101::deviceRegister
00160         *  Constructor allocated size to each register instance on construction
00161         * \param[in] size; size (typically 1 or 2 bytes) determines the number of segments that the register is divided in to.
00162         *
00163         */
00164         deviceRegister2(uint8_t size);
00165         /*!
00166         * \brief Operator overload for '='.
00167         *
00168         * This makes calling this class simpler. dev.register=value will resolve the register address and value and invoke hostController::writeI2C method
00169         * With proper implementation of the hostController::writeI2C methods the h/w would receive resolved I2C WRITE commands
00170         * The write operations are read modify writes to make the system robust
00171         *  A single call of this method could invoke up to 2 I2C READ and 2 I2C WRITE transaction depending on the register
00172         * \param[in] value; value to be set to register
00173         * \return Nothing
00174         *
00175         */
00176         void operator=(int32_t value);
00177         /*!
00178         * \brief Function called to read the value of register
00179         *
00180         *  This method provides an abstraction for register to be used seamlessly with code for read register operations.
00181         *  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
00182         *  A single call of this method could invoke up to 2 I2C READ transaction depending on the register
00183         * \return value; value is reading of register from OPT3101 device
00184         */
00185         uint32_t read();
00186 };
00187 
00188 }
00189 #endif /* REGISTER_HPP_ */
00190