Diff: MaximInterfaceDevices/DS2465.hpp

Revision:

8:5ea891c7d1a1

Parent:

7:9cd16581b578

--- a/MaximInterfaceDevices/DS2465.hpp	Mon Jul 22 11:44:07 2019 -0500
+++ b/MaximInterfaceDevices/DS2465.hpp	Mon Sep 16 11:13:37 2019 -0500
@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (C) 2017 Maxim Integrated Products, Inc., All Rights Reserved.
+* Copyright (C) Maxim Integrated Products, Inc., All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
@@ -30,8 +30,8 @@
 * ownership rights.
 *******************************************************************************/
 
-#ifndef MaximInterfaceDevices_DS2465
-#define MaximInterfaceDevices_DS2465
+#ifndef MaximInterfaceDevices_DS2465_hpp
+#define MaximInterfaceDevices_DS2465_hpp
 
 #include <MaximInterfaceCore/array_span.hpp>
 #include <MaximInterfaceCore/I2CMaster.hpp>
@@ -41,7 +41,11 @@
 
 namespace MaximInterfaceDevices {
 
-/// Interface to the DS2465 1-Wire master and SHA-256 coprocessor.
+/// @brief Interface to the DS2465 1-Wire master and SHA-256 coprocessor.
+/// @details
+/// Const member functions should not change the settings of the DS2465 or
+/// affect the state of the 1-Wire bus. Read pointer, scratchpad, MAC output
+/// register, and command register on the DS2465 are considered mutable.
 class DS2465 : public Core::OneWireMaster {
 public:
   enum ErrorValue { HardwareError = 1, ArgumentOutOfRangeError };
@@ -173,10 +177,6 @@
     uint_least8_t readByte_;
   };
 
-  // Const member functions should not change the settings of the DS2465 or
-  // affect the state of the 1-Wire bus. Read pointer, scratchpad, MAC output
-  // register, and command register on the DS2465 are considered mutable.
-
   DS2465(Core::Sleep & sleep, Core::I2CMaster & master,
          uint_least8_t address = 0x30)
       : sleep(&sleep), master(&master), address_(address & 0xFE) {}
@@ -190,158 +190,158 @@
   void setAddress(uint_least8_t address) { address_ = address & 0xFE; }
 
   /// Initialize hardware for use.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   initialize(Config config = Config());
 
   /// @brief Write a new configuration to the DS2465.
   /// @param[in] config New configuration to write.
-  MaximInterfaceDevices_EXPORT Core::error_code writeConfig(Config config);
+  MaximInterfaceDevices_EXPORT Core::Result<void> writeConfig(Config config);
 
   /// @brief Write a new port configuration parameter to the DS2465.
   /// @param[in] param Parameter to adjust.
   /// @param[in] val
   /// New parameter value to set. Consult datasheet for value mappings.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   writePortParameter(PortParameter param, int val);
 
   // 1-Wire Master Commands
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code reset();
+  MaximInterfaceDevices_EXPORT virtual Core::Result<void> reset();
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
-  touchBitSetLevel(bool & sendRecvBit, Level afterLevel);
+  MaximInterfaceDevices_EXPORT virtual Core::Result<bool>
+  touchBitSetLevel(bool sendBit, Level afterLevel);
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
-  readByteSetLevel(uint_least8_t & recvByte, Level afterLevel);
+  MaximInterfaceDevices_EXPORT virtual Core::Result<uint_least8_t>
+  readByteSetLevel(Level afterLevel);
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
+  MaximInterfaceDevices_EXPORT virtual Core::Result<void>
   writeByteSetLevel(uint_least8_t sendByte, Level afterLevel);
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
+  MaximInterfaceDevices_EXPORT virtual Core::Result<void>
   readBlock(Core::span<uint_least8_t> recvBuf);
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
+  MaximInterfaceDevices_EXPORT virtual Core::Result<void>
   writeBlock(Core::span<const uint_least8_t> sendBuf);
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
+  MaximInterfaceDevices_EXPORT virtual Core::Result<void>
   setSpeed(Speed newSpeed);
 
   /// @copydoc Core::OneWireMaster::setLevel
   /// @note
   /// The DS2465 only supports enabling strong pullup following a 1-Wire read or
   /// write operation.
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
+  MaximInterfaceDevices_EXPORT virtual Core::Result<void>
   setLevel(Level newLevel);
 
-  MaximInterfaceDevices_EXPORT virtual Core::error_code
-  triplet(TripletData & data);
+  MaximInterfaceDevices_EXPORT virtual Core::Result<TripletData>
+  triplet(bool sendBit);
 
   // DS2465 Coprocessor Commands
 
   /// @brief Read data from an EEPROM memory page.
   /// @param pageNum Page number to read from.
-  /// @param[out] data Data that was read.
-  MaximInterfaceDevices_EXPORT Core::error_code readPage(int pageNum,
-                                                         Page::span data) const;
+  /// @returns Data that was read.
+  MaximInterfaceDevices_EXPORT Core::Result<Page::array>
+  readPage(int pageNum) const;
 
   /// @brief Write data to an EEPROM memory page.
   /// @param pageNum Page number to copy to.
   /// @param data Data to write.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   writePage(int pageNum, Page::const_span data);
 
   /// @brief Write data to an EEPROM memory segment.
   /// @param pageNum Page number to copy to.
   /// @param segmentNum Segment number to copy to.
   /// @param data Data to write.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   writeSegment(int pageNum, int segmentNum, Segment::const_span data);
 
   /// Write data to the secret EEPROM memory page.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   writeMasterSecret(Page::const_span masterSecret);
 
   /// @brief Compute Next Master Secret.
   /// @param data Combined data fields for computation.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   computeNextMasterSecret(AuthenticationData::const_span data);
 
   /// @brief Compute Next Master Secret with page swapping.
   /// @param data Combined data fields for computation.
   /// @param pageNum Page number to swap in.
   /// @param region Region of the page to swap in.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   computeNextMasterSecretWithSwap(AuthenticationData::const_span data,
                                   int pageNum, PageRegion region);
 
   /// @brief Compute Write MAC.
   /// @param data Combined data fields for computation.
-  /// @param[out] mac Computed Write MAC.
-  MaximInterfaceDevices_EXPORT Core::error_code
-  computeWriteMac(WriteMacData::const_span data, Page::span mac) const;
+  /// @returns Computed Write MAC.
+  MaximInterfaceDevices_EXPORT Core::Result<Page::array>
+  computeWriteMac(WriteMacData::const_span data) const;
 
   /// @brief Compute Write MAC.
   /// @param data Combined data fields for computation.
-  MaximInterfaceDevices_EXPORT Core::error_code
-  computeAndTransmitWriteMac(WriteMacData::const_span data) const;
+  MaximInterfaceDevices_EXPORT Core::Result<void>
+  computeAndTransmitWriteMac(WriteMacData::const_span data);
 
   /// @brief Compute Write MAC with page swapping.
   /// @param data Combined data fields for computation.
   /// @param pageNum Page number to swap in.
   /// @param segmentNum Segment number to swap in.
-  /// @param[out] mac Computed Write MAC.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  /// @returns Computed Write MAC.
+  MaximInterfaceDevices_EXPORT Core::Result<Page::array>
   computeWriteMacWithSwap(WriteMacData::const_span data, int pageNum,
-                          int segmentNum, Page::span mac) const;
+                          int segmentNum) const;
 
   /// @brief Compute Write MAC with page swapping.
   /// @param data Combined data fields for computation.
   /// @param pageNum Page number to swap in.
   /// @param segmentNum Segment number to swap in.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   computeAndTransmitWriteMacWithSwap(WriteMacData::const_span data, int pageNum,
-                                     int segmentNum) const;
+                                     int segmentNum);
 
   /// @brief Compute Slave Secret (S-Secret).
   /// @param data Combined data fields for computation.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   computeSlaveSecret(AuthenticationData::const_span data);
 
   /// @brief Compute Slave Secret (S-Secret) with page swapping.
   /// @param data Combined data fields for computation.
   /// @param pageNum Page number to swap in.
   /// @param region Region of the page to swap in.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   computeSlaveSecretWithSwap(AuthenticationData::const_span data, int pageNum,
                              PageRegion region);
 
   /// @brief Compute Authentication MAC.
   /// @param data Combined data fields for computation.
-  /// @param[out] mac Computed Auth MAC.
-  MaximInterfaceDevices_EXPORT Core::error_code
-  computeAuthMac(AuthenticationData::const_span data, Page::span mac) const;
+  /// @returns Computed Auth MAC.
+  MaximInterfaceDevices_EXPORT Core::Result<Page::array>
+  computeAuthMac(AuthenticationData::const_span data) const;
 
   /// @brief Compute Authentication MAC.
   /// @param data Combined data fields for computation.
-  MaximInterfaceDevices_EXPORT Core::error_code
-  computeAndTransmitAuthMac(AuthenticationData::const_span data) const;
+  MaximInterfaceDevices_EXPORT Core::Result<void>
+  computeAndTransmitAuthMac(AuthenticationData::const_span data);
 
   /// @brief Compute Authentication MAC with page swapping.
   /// @param data Combined data fields for computation.
   /// @param pageNum Page number to swap in.
   /// @param region Region of the page to swap in.
-  /// @param[out] mac Computed Auth MAC.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  /// @returns Computed Auth MAC.
+  MaximInterfaceDevices_EXPORT Core::Result<Page::array>
   computeAuthMacWithSwap(AuthenticationData::const_span data, int pageNum,
-                         PageRegion region, Page::span mac) const;
+                         PageRegion region) const;
 
   /// @brief Compute Authentication MAC with page swapping.
   /// @param data Combined data fields for computation.
   /// @param pageNum Page number to swap in.
   /// @param region Region of the page to swap in.
-  MaximInterfaceDevices_EXPORT Core::error_code
+  MaximInterfaceDevices_EXPORT Core::Result<void>
   computeAndTransmitAuthMacWithSwap(AuthenticationData::const_span data,
-                                    int pageNum, PageRegion region) const;
+                                    int pageNum, PageRegion region);
 
   MaximInterfaceDevices_EXPORT static const Core::error_category &
   errorCategory();
@@ -354,62 +354,73 @@
 
   /// @brief Performs a soft reset on the DS2465.
   /// @note This is not a 1-Wire Reset.
-  Core::error_code resetDevice();
+  Core::Result<void> resetDevice();
 
   /// @brief
-  /// Polls the DS2465 status waiting for the 1-Wire Busy bit (1WB) to be
-  /// cleared.
-  /// @param[out] pStatus Optionally retrive the status byte when 1WB cleared.
-  /// @returns Success or TimeoutError if poll limit reached.
-  Core::error_code pollBusy(uint_least8_t * pStatus = NULL) const;
+  /// Polls the DS2465 status waiting for the 1-Wire Busy bit (1WB) to be cleared.
+  /// @returns Status byte or TimeoutError if poll limit reached.
+  Core::Result<uint_least8_t> pollBusy() const;
 
   /// @brief Ensure that the desired 1-Wire level is set in the configuration.
   /// @param level Desired 1-Wire level.
-  Core::error_code configureLevel(Level level);
+  Core::Result<void> configureLevel(Level level);
 
   /// @note Const since only for internal use.
-  Core::error_code writeMemory(uint_least8_t addr,
-                               Core::span<const uint_least8_t> buf) const;
+  Core::Result<void> writeMemory(uint_least8_t addr,
+                                 Core::span<const uint_least8_t> buf) const;
 
   /// @brief Read memory from the DS2465.
   /// @param addr Address to begin reading from.
   /// @param[out] buf Buffer to hold read data.
-  Core::error_code readMemory(uint_least8_t addr,
-                              Core::span<uint_least8_t> buf) const;
+  Core::Result<void> readMemory(uint_least8_t addr,
+                                Core::span<uint_least8_t> buf) const;
 
   /// @brief Read memory from the DS2465 at the current pointer.
   /// @param[out] buf Buffer to hold read data.
-  Core::error_code readMemory(Core::span<uint_least8_t> buf) const;
+  Core::Result<void> readMemory(Core::span<uint_least8_t> buf) const;
 
   /// Write the last computed MAC to the 1-Wire bus.
-  Core::error_code writeMacBlock() const;
+  Core::Result<void> writeMacBlock();
 
-  Core::error_code computeWriteMac(WriteMacData::const_span data) const;
+  Core::Result<void> doComputeWriteMac(WriteMacData::const_span data) const;
 
-  Core::error_code computeWriteMacWithSwap(WriteMacData::const_span data,
-                                           int pageNum, int segmentNum) const;
+  Core::Result<void> doComputeWriteMacWithSwap(WriteMacData::const_span data,
+                                               int pageNum,
+                                               int segmentNum) const;
 
-  Core::error_code computeAuthMac(AuthenticationData::const_span data) const;
+  Core::Result<void>
+  doComputeAuthMac(AuthenticationData::const_span data) const;
 
-  Core::error_code computeAuthMacWithSwap(AuthenticationData::const_span data,
-                                          int pageNum, PageRegion region) const;
+  Core::Result<void>
+  doComputeAuthMacWithSwap(AuthenticationData::const_span data, int pageNum,
+                           PageRegion region) const;
 
   // Legacy implementations
-  Core::error_code copyScratchpad(bool destSecret, int pageNum, bool notFull,
-                                  int segmentNum);
+  Core::Result<void> copyScratchpad(bool destSecret, int pageNum, bool notFull,
+                                    int segmentNum);
+
+  Core::Result<void> computeNextMasterSecret(bool swap, int pageNum,
+                                             PageRegion region);
 
-  Core::error_code computeNextMasterSecret(bool swap, int pageNum,
-                                           PageRegion region);
+  Core::Result<void> computeWriteMac(bool regwrite, bool swap, int pageNum,
+                                     int segmentNum) const;
+
+  Core::Result<void> computeSlaveSecret(bool swap, int pageNum,
+                                        PageRegion region);
 
-  Core::error_code computeWriteMac(bool regwrite, bool swap, int pageNum,
-                                   int segmentNum) const;
+  Core::Result<void> computeAuthMac(bool swap, int pageNum,
+                                    PageRegion region) const;
+};
+
+} // namespace MaximInterfaceDevices
+namespace MaximInterfaceCore {
 
-  Core::error_code computeSlaveSecret(bool swap, int pageNum,
-                                      PageRegion region);
+template <>
+struct is_error_code_enum<MaximInterfaceDevices::DS2465::ErrorValue>
+    : true_type {};
 
-  Core::error_code computeAuthMac(bool swap, int pageNum,
-                                  PageRegion region) const;
-};
+} // namespace MaximInterfaceCore
+namespace MaximInterfaceDevices {
 
 inline Core::error_code make_error_code(DS2465::ErrorValue e) {
   return Core::error_code(e, DS2465::errorCategory());