Updated parameters to the user APIs
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
Change-Id: I9784c5044337c0f558a77d07f5cd4f5c2ef91e89
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