Updated parameters to the user APIs
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
Change-Id: I9784c5044337c0f558a77d07f5cd4f5c2ef91e89
diff --git a/src/hei_includes.hpp b/src/hei_includes.hpp
index c2675c0..3c29a95 100644
--- a/src/hei_includes.hpp
+++ b/src/hei_includes.hpp
@@ -1,17 +1,27 @@
#pragma once
/**
-@file hei_includes.hpp
-@brief The purpose of this file is to include common headers that will be used
-throughout this library.
-*/
+ * @file hei_includes.hpp
+ * @brief The purpose of this file is to include common headers that will be
+ * used throughout this library.
+ */
// Standard library includes
+#include <stdlib.h>
#include <stdint.h>
#include <vector>
-// External includes
-#include <hei_user_defines.hpp> // For HEI_ASSERT, HEI_INF, and HEI_ERR
+// The user application must define "hei_user_defines.hpp" with the following
+// macros:
+//
+// Tracing (inputs same as printf() from <cstdio>):
+// HEI_INF( ... ) // Generic informational trace
+// HEI_ERR( ... ) // Error path trace
+//
+// Assertion (at a minimum should work like assert() from <cassert>):
+// HEI_ASSERT( expression )
+//
+#include <hei_user_defines.hpp>
// Internal includes
#include <hei_chip.hpp>
diff --git a/src/hei_main.hpp b/src/hei_main.hpp
index b0e5210..21aebd2 100644
--- a/src/hei_main.hpp
+++ b/src/hei_main.hpp
@@ -61,7 +61,7 @@
* - true, the function will delete the previous isolation
* objects for this chip type and reinitialize.
*
- * @return RC_SUCCESS or RC_CDF_INVALID or RC_CDF_INITIALIZED
+ * @return RC_SUCCESS or RC_CHIP_DATA_INVALID or RC_CHIP_DATA_INITIALIZED
*/
inline ReturnCode initialize( void * i_buffer, size_t i_bufferSize,
bool i_forceInit = false )
diff --git a/src/hei_return_code.hpp b/src/hei_return_code.hpp
index ce32468..5d0526e 100644
--- a/src/hei_return_code.hpp
+++ b/src/hei_return_code.hpp
@@ -55,7 +55,7 @@
private:
- const uint32_t iv_rc; ///< return code value
+ uint32_t iv_rc; ///< return code value
};
/** Function returned successfully. */
@@ -71,5 +71,9 @@
/** The given chip type has not been initialized. */
static constexpr ReturnCode RC_CHIP_DATA_MISSING = ReturnCode(0x00000003);
+/** Generic return code indicating something along the hardware register access
+ * path failed and the returned data is undefined and should not be used. */
+static constexpr ReturnCode RC_REG_ACCESS_FAILURE = ReturnCode(0x00000004);
+
} // end namespace libhei
diff --git a/src/hei_user_interface.hpp b/src/hei_user_interface.hpp
index 1d3b5d3..fbfe92c 100644
--- a/src/hei_user_interface.hpp
+++ b/src/hei_user_interface.hpp
@@ -1,40 +1,87 @@
#pragma once
-// The user application must define this header file with the following macros:
-//
-// Tracing (inputs same as printf() from <cstdio>):
-// HEI_INF( ... ) // Generic informational trace
-// HEI_ERR( ... ) // Error path trace
-//
-// Assertion (at a minimum should work like assert() from <cassert>):
-// HEI_ASSERT( expression )
-//
-#include <hei_user_defines.hpp>
+/**
+ * @file hei_user_interface.hpp
+ *
+ * The method for actions like hardware register access will vary per user
+ * application. Therefore, the user application must define all of the APIs
+ * listed below.
+ */
+
+#include <hei_includes.hpp>
namespace libhei
{
/**
- * @brief Perform a hardware read operation.
- * @param i_chip This is a pointer to a user application object that represents
- * the target chip. The isolator does not know anything about this
- * object or how to use it. It is provide by the user application
- * via the Isolator APIs. The user application is responsible for
- * knowing what to do with this parameter.
+ * @brief Performs a hardware register read operation.
+ *
+ * @param i_chip This is a pointer to a user application object that
+ * represents the target chip. It is provided to the isolator
+ * by the user application via the isolator main APIs. The
+ * isolator does not know anything about this object nor how
+ * to use it. The user application is responsible for knowing
+ * what to do with this parameter.
+ *
+ * @param o_buffer Allocated memory space for the returned contents of the
+ * register.
+ *
+ * @param io_bufSize The input parameter is the maximum size of the allocated
+ * o_buffer. The return value is the number of bytes actually
+ * written to the buffer.
+ *
+ * @param i_regType The user application may support different types of
+ * registers. This value is provided to the isolator by the
+ * user application via the Chip Data Files. The user
+ * application is responsible for knowing what to do with this
+ * parameter.
+ *
+ * @param i_address The register address. The values is a 1, 2, 4, or 8 byte
+ * address (right justified), which is provided to the
+ * isolator by the user application via the Chip Data Files.
+ *
+ * @return RC_SUCCESS or RC_REG_ACCESS_FAILURE. Note that in the case of a
+ * failure the user application is responsible for reporting why the
+ * register access failed.
*/
-ReturnCode deviceRead( void * i_chip );
+ReturnCode registerRead( void * i_chip, void * o_buffer, size_t & io_bufSize,
+ uint64_t i_regType, uint64_t i_address );
#ifndef __HEI_READ_ONLY
/**
- * @brief Perform a hardware write operation.
- * @param i_chip This is a pointer to a user application object that represents
- * the target chip. The isolator does not know anything about this
- * object or how to use it. It is provide by the user application
- * via the Isolator APIs. The user application is responsible for
- * knowing what to do with this parameter.
+ * @brief Performs a hardware register write operation.
+ *
+ * @param i_chip This is a pointer to a user application object that
+ * represents the target chip. It is provided to the isolator
+ * by the user application via the isolator main APIs. The
+ * isolator does not know anything about this object nor how
+ * to use it. The user application is responsible for knowing
+ * what to do with this parameter.
+ *
+ * @param i_buffer Allocated memory space containing the register contents to
+ * write to hardware.
+ *
+ * @param io_bufSize The input parameter is the number of byte from i_buffer to
+ * write to the hardware register. The return value is the
+ * actual number of bytes written to the hardware register.
+ *
+ * @param i_regType The user application may support different types of
+ * registers. This value is provided to the isolator by the
+ * user application via the Chip Data Files. The user
+ * application is responsible for knowing what to do with this
+ * parameter.
+ *
+ * @param i_address The register address. The values is a 1, 2, 4, or 8 byte
+ * address (right justified), which is provided to the
+ * isolator by the user application via the Chip Data Files.
+ *
+ * @return RC_SUCCESS or RC_REG_ACCESS_FAILURE. Note that in the case of a
+ * failure the user application is responsible for reporting why the
+ * register access failed.
*/
-ReturnCode deviceWrite( void * i_chip );
+ReturnCode registerWrite( void * i_chip, void * i_buffer, size_t & io_bufSize,
+ uint64_t i_regType, uint64_t i_address );
#endif