DS2465.h

00001 /******************************************************************//**
00002 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
00003 *
00004 * Permission is hereby granted, free of charge, to any person obtaining a
00005 * copy of this software and associated documentation files (the "Software"),
00006 * to deal in the Software without restriction, including without limitation
00007 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008 * and/or sell copies of the Software, and to permit persons to whom the
00009 * Software is furnished to do so, subject to the following conditions:
00010 *
00011 * The above copyright notice and this permission notice shall be included
00012 * in all copies or substantial portions of the Software.
00013 *
00014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020 * OTHER DEALINGS IN THE SOFTWARE.
00021 *
00022 * Except as contained in this notice, the name of Maxim Integrated
00023 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00024 * Products, Inc. Branding Policy.
00025 *
00026 * The mere transfer of this software does not imply any licenses
00027 * of trade secrets, proprietary technology, copyrights, patents,
00028 * trademarks, maskwork rights, or any other form of intellectual
00029 * property whatsoever. Maxim Integrated Products, Inc. retains all
00030 * ownership rights.
00031 **********************************************************************/
00032 
00033 #ifndef OneWire_Masters_DS2465
00034 #define OneWire_Masters_DS2465
00035 
00036 #include "Masters/OneWireMaster.h"
00037 #include "Slaves/Authenticators/ISha256MacCoproc.h"
00038 
00039 namespace mbed { class I2C; }
00040 
00041 namespace OneWire
00042 {
00043     /// Interface to the DS2465 1-Wire master and SHA-256 coprocessor.
00044     class DS2465 : public OneWireMaster, public ISha256MacCoproc
00045     {
00046     public:
00047         /// Delay required after writing an EEPROM segment.
00048         static const unsigned int eepromSegmentWriteDelayMs = 10;
00049         /// Delay required after writing an EEPROM page such as the secret memory.
00050         static const unsigned int eepromPageWriteDelayMs = 8 * eepromSegmentWriteDelayMs;
00051         /// Delay required for a SHA computation to complete.
00052         static const unsigned int shaComputationDelayMs = 2;
00053 
00054         /// Page region to use for swapping.
00055         enum PageRegion
00056         {
00057             FullPage = 0x03,
00058             FirstHalf = 0x01,
00059             SecondHalf = 0x02
00060         };
00061 
00062         /// Starting memory addresses.
00063         enum MemoryAddress
00064         {
00065             Scratchpad = 0x00,
00066             CommandReg = 0x60,
00067             StatusReg = 0x61,
00068             ReadDataReg = 0x62,
00069             MacReadoutReg = 0x63,
00070             MemoryProtectionReg = 0x64,
00071             ConfigReg = 0x67,
00072             tRSTL_Reg = 0x68,
00073             tMSP_Reg = 0x69,
00074             tW0L_Reg = 0x6A,
00075             tREC0_Reg = 0x6B,
00076             RWPU_Reg = 0x6C,
00077             tW1L_Reg = 0x6D,
00078             UserMemoryPage0 = 0x80,
00079             UserMemoryPage1 = 0xA0
00080         };
00081 
00082         /// Represents a DS2465 configuration.
00083         class Config
00084         {
00085         public:
00086             /// @{
00087             /// 1-Wire Speed
00088             bool get1WS () const { return m_1WS; }
00089             void set1WS(bool new1WS) { m_1WS = new1WS; }
00090             /// @}
00091 
00092             /// @{
00093             /// Strong Pullup
00094             bool getSPU () const { return m_SPU; }
00095             void setSPU(bool newSPU) { m_SPU = newSPU; }
00096             /// @}
00097 
00098             /// @{
00099             /// 1-Wire Power Down
00100             bool getPDN () const { return m_PDN; }
00101             void setPDN(bool newPDN) { m_PDN = newPDN; }
00102             /// @}
00103 
00104             /// @{
00105             /// Active Pullup
00106             bool getAPU () const { return m_APU; }
00107             void setAPU(bool newAPU) { m_APU = newAPU; }
00108             /// @}
00109 
00110             /// Byte representation that is read from the DS2465.
00111             uint8_t readByte() const;
00112             /// Byte respresentation that is written to the DS2465.
00113             uint8_t writeByte() const;
00114 
00115             /// Reset to the power-on default config.
00116             void reset();
00117             Config() { reset(); }
00118 
00119         private:
00120             bool m_1WS, m_SPU, m_PDN, m_APU;
00121         };
00122 
00123         /// @param I2C_interface Configured I2C communication interface for DS2465.
00124         /// @param I2C_address I2C bus address of the DS2465 in mbed format.
00125         DS2465 (mbed::I2C & I2C_interface, uint8_t I2C_address = 0x30);
00126 
00127         // Const member functions should not change the settings of the DS2465 or affect the state of the 1-Wire bus.
00128         // Read pointer, scratchpad, MAC output register, and command register on the DS2465 are considered mutable.
00129 
00130         /// Performs a soft reset on the DS2465.
00131         /// @note This is not a 1-Wire Reset.
00132         OneWireMaster::CmdResult reset();
00133 
00134         /// Write a new configuration to the DS2465.
00135         /// @param[in] config New configuration to write.
00136         /// @param verify Verify that the configuration was written successfully.
00137         OneWireMaster::CmdResult writeConfig(const Config & config, bool verify);
00138 
00139         /// Read the current DS2465 configuration.
00140         /// @returns The cached current configuration.
00141         Config currentConfig() const { return m_curConfig; }
00142 
00143         // DS2465 Memory Commands
00144 
00145         /// Read memory from the DS2465.
00146         /// @param addr Address to begin reading from.
00147         /// @param[out] buf Buffer to hold read data.
00148         /// @param bufLen Length of buffer, buf, and number of bytes to read.
00149         /// @param skipSetPointer Assume that the read pointer is already set to the correct address.
00150         OneWireMaster::CmdResult readMemory(uint8_t addr, uint8_t * buf, size_t bufLen, bool skipSetPointer = false) const;
00151 
00152         /// Write to SRAM memory on the DS2465.
00153         /// @param addr Address to begin writing to.
00154         /// @param[in] buf Buffer containing the data to write.
00155         /// @param bufLen Length of buffer, buf, and number of bytes to write.
00156         OneWireMaster::CmdResult writeMemory(uint8_t addr, const uint8_t * buf, size_t bufLen) { return cWriteMemory(addr, buf, bufLen); }
00157 
00158         /// Write data to the scratchpad area of the DS2465.
00159         /// @param[in] buf Buffer containing the data to write.
00160         /// @param bufLen Length of buffer, buf, and the number of bytes to write.
00161         OneWireMaster::CmdResult writeScratchpad(const uint8_t * buf, size_t bufLen) const { return cWriteMemory(Scratchpad, buf, bufLen); }
00162 
00163         /// Copy the scratchpad contents to an EEPROM memory page.
00164         /// @param pageNum Page number to copy to.
00165         OneWireMaster::CmdResult copyScratchpadToPage(unsigned int pageNum) { return copyScratchpad(false, pageNum, false, 0); }
00166 
00167         /// Copy the scratchpad contents to an EEPROM memory segment.
00168         /// @param pageNum Page number to copy to.
00169         /// @param segmentNum Segment number to copy to.
00170         OneWireMaster::CmdResult copyScratchpadToSegment(unsigned int pageNum, unsigned int segmentNum) { return copyScratchpad(false, pageNum, true, segmentNum); }
00171 
00172         /// Copy the scratchpad contents to the secret EEPROM memory page.
00173         OneWireMaster::CmdResult copyScratchpadToSecret() { return copyScratchpad(true, 0, false, 0); }
00174 
00175         // 1-Wire Master Commands
00176         virtual OneWireMaster::CmdResult OWInitMaster();
00177         virtual OneWireMaster::CmdResult OWReset();
00178         virtual OneWireMaster::CmdResult OWTouchBitSetLevel(uint8_t & sendRecvBit, OWLevel afterLevel);
00179         virtual OneWireMaster::CmdResult OWReadByteSetLevel(uint8_t & recvByte, OWLevel afterLevel);
00180         virtual OneWireMaster::CmdResult OWWriteByteSetLevel(uint8_t sendByte, OWLevel afterLevel);
00181         virtual OneWireMaster::CmdResult OWReadBlock(uint8_t *recvBuf, size_t recvLen);
00182         virtual OneWireMaster::CmdResult OWWriteBlock(const uint8_t *sendBuf, size_t sendLen);
00183         virtual OneWireMaster::CmdResult OWSetSpeed(OWSpeed newSpeed);
00184         /// @note The DS2465 only supports enabling strong pullup following a 1-Wire read or write operation.
00185         virtual OneWireMaster::CmdResult OWSetLevel (OWLevel newLevel);
00186         virtual OneWireMaster::CmdResult OWTriplet(SearchDirection & searchDirection, uint8_t & sbr, uint8_t & tsb);
00187 
00188         /// Write the last computed MAC to the 1-Wire bus
00189         OneWireMaster::CmdResult OWWriteBlockMac();
00190 
00191         // DS2465 Coprocessor Commands
00192 
00193         /// Compute Next Master Secret with scratchpad data.
00194         OneWireMaster::CmdResult computeNextMasterSecret() { return computeNextMasterSecret(false, 0, FullPage); }
00195 
00196         /// Compute Next Master Secret with page swapping.
00197         /// @param pageNum Page number to swap in.
00198         /// @param region Region of the page to swap in.
00199         OneWireMaster::CmdResult computeNextMasterSecretSwap(unsigned int pageNum, PageRegion region) { return computeNextMasterSecret(true, pageNum, region); }
00200 
00201         /// Compute Write MAC with scratchpad data.
00202         /// @param regwrite True if writing to a register or false if regular memory.
00203         OneWireMaster::CmdResult computeWriteMac(bool regwrite) const { return computeWriteMac(regwrite, false, 0, 0); }
00204 
00205         /// Compute Write MAC with page swapping.
00206         /// @param regwrite True if writing to a register or false if regular memory.
00207         /// @param pageNum Page number to swap in.
00208         /// @param segmentNum Segment number to swap in.
00209         OneWireMaster::CmdResult computeWriteMacSwap(bool regwrite, unsigned int pageNum, unsigned int segmentNum) const { return computeWriteMac(regwrite, true, pageNum, segmentNum); }
00210 
00211         /// Compute Slave Secret (S-Secret) with scratchpad data.
00212         OneWireMaster::CmdResult computeSlaveSecret() { return computeSlaveSecret(false, 0, FullPage); }
00213 
00214         /// Compute Slave Secret (S-Secret) with page swapping.
00215         /// @param pageNum Page number to swap in.
00216         /// @param region Region of the page to swap in.
00217         OneWireMaster::CmdResult computeSlaveSecretSwap(unsigned int pageNum, PageRegion region) { return computeSlaveSecret(true, pageNum, region); }
00218 
00219         /// Compute Authentication MAC with scratchpad data.
00220         OneWireMaster::CmdResult computeAuthMac() const { return computeAuthMac(false, 0, FullPage); }
00221 
00222         /// Compute Authentication MAC with page swapping.
00223         /// @param pageNum Page number to swap in.
00224         /// @param region Region of the page to swap in.
00225         OneWireMaster::CmdResult computeAuthMacSwap(unsigned int pageNum, PageRegion region) const { return computeAuthMac(true, pageNum, region); }
00226 
00227         // ISha256MacCoproc Commands
00228         virtual ISha256MacCoproc::CmdResult setMasterSecret(const Secret & masterSecret);
00229         virtual ISha256MacCoproc::CmdResult computeSlaveSecret(const DevicePage & devicePage, const DeviceScratchpad & deviceScratchpad, const SlaveSecretData & slaveSecretData);
00230         virtual ISha256MacCoproc::CmdResult computeWriteMac(const WriteMacData & writeMacData, Mac & mac) const;
00231         virtual ISha256MacCoproc::CmdResult computeAuthMac(const DevicePage & devicePage, const DeviceScratchpad & challenge, const AuthMacData & authMacData, Mac & mac) const;
00232 
00233     private:
00234         mbed::I2C & m_I2C_interface;
00235         uint8_t m_I2C_address;
00236         Config m_curConfig;
00237 
00238         /// Polls the DS2465 status waiting for the 1-Wire Busy bit (1WB) to be cleared.
00239         /// @param[out] pStatus Optionally retrive the status byte when 1WB cleared.
00240         /// @returns Success or TimeoutError if poll limit reached.
00241         OneWireMaster::CmdResult pollBusy(uint8_t * pStatus = NULL);
00242 
00243         /// Ensure that the desired 1-Wire level is set in the configuration.
00244         /// @param level Desired 1-Wire level.
00245         OneWireMaster::CmdResult configureLevel(OWLevel level);
00246 
00247         /// Const version of writeMemory() for internal use.
00248         OneWireMaster::CmdResult cWriteMemory(uint8_t addr, const uint8_t * buf, size_t bufLen) const;
00249 
00250         // Legacy implementations
00251         OneWireMaster::CmdResult copyScratchpad(bool destSecret, unsigned int pageNum, bool notFull, unsigned int segmentNum);
00252         OneWireMaster::CmdResult computeNextMasterSecret(bool swap, unsigned int pageNum, PageRegion region);
00253         OneWireMaster::CmdResult computeWriteMac(bool regwrite, bool swap, unsigned int pageNum, unsigned int segmentNum) const;
00254         OneWireMaster::CmdResult computeSlaveSecret(bool swap, unsigned int pageNum, PageRegion region);
00255         OneWireMaster::CmdResult computeAuthMac(bool swap, unsigned int pageNum, PageRegion region) const;
00256     };
00257 }
00258 
00259 #endif