Updated parameters to the user APIs
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
Change-Id: I9784c5044337c0f558a77d07f5cd4f5c2ef91e89
diff --git a/README.md b/README.md
index 5c75e94..3ec90a8 100644
--- a/README.md
+++ b/README.md
@@ -35,12 +35,12 @@
* Tracing, or logging, methods will vary per user application. Specifically,
FSP and Hostboot firmware utilize specialized macros as a mechanism to save
code image space. Therefore, the user application will need to provide a
- specific header file that defines these macros. Details are included in the
- [user APIs][].
+ specific header file that defines these macros. Details are in the
+ [common includes header][].
* Methods to assert programming bugs will vary per user application. Therefore,
much like tracing, the user application will need to provide a specific
header file that defines macros for assertion. Details are included in the
- [user APIs][].
+ [common includes header][].
Environment configuration
-------------------------
@@ -65,5 +65,6 @@
[POWER Systems Hostboot firmware]: https://github.com/open-power/hostboot
[primary API definitions]: src/hei_main.hpp
[user APIs]: src/hei_user_interface.hpp
+[common includes header]: src/hei_includes.hpp
[Chip Data Files]: src/chip_data/CHIP_DATA.md
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
diff --git a/test/simulator/hei_sim_user_interface.cpp b/test/simulator/hei_sim_user_interface.cpp
new file mode 100644
index 0000000..c3baeb3
--- /dev/null
+++ b/test/simulator/hei_sim_user_interface.cpp
@@ -0,0 +1,59 @@
+#include <hei_user_interface.hpp>
+
+#include <hei_includes.hpp>
+
+namespace libhei
+{
+
+//------------------------------------------------------------------------------
+
+ReturnCode registerRead( void * i_chip, void * o_buffer, size_t & io_bufSize,
+ uint64_t i_regType, uint64_t i_address )
+{
+ ReturnCode rc;
+
+ HEI_ASSERT( nullptr != i_chip );
+ HEI_ASSERT( nullptr != o_buffer );
+ HEI_ASSERT( 0 != io_bufSize );
+
+ switch ( i_regType )
+ {
+ default:
+ rc = RC_REG_ACCESS_FAILURE;
+ HEI_ERR( "registerRead(%p,%p,%lx,%lx,%lx)", i_chip, o_buffer,
+ io_bufSize, i_regType, i_address );
+ }
+
+ return rc;
+}
+
+//------------------------------------------------------------------------------
+
+#ifndef __HEI_READ_ONLY
+
+ReturnCode registerWrite( void * i_chip, void * i_buffer, size_t & io_bufSize,
+ uint64_t i_regType, uint64_t i_address )
+{
+ ReturnCode rc;
+
+ HEI_ASSERT( nullptr != i_chip );
+ HEI_ASSERT( nullptr != i_buffer );
+ HEI_ASSERT( 0 != io_bufSize );
+
+ switch ( i_regType )
+ {
+ default:
+ rc = RC_REG_ACCESS_FAILURE;
+ HEI_ERR( "registerWrite(%p,%p,%lx,%lx,%lx)", i_chip, i_buffer,
+ io_bufSize, i_regType, i_address );
+ }
+
+ return rc;
+}
+
+#endif
+
+//------------------------------------------------------------------------------
+
+} // end namespace libhei
+
diff --git a/test/simulator/meson.build b/test/simulator/meson.build
index b53dce5..d65e286 100644
--- a/test/simulator/meson.build
+++ b/test/simulator/meson.build
@@ -1,5 +1,6 @@
sim_sources = [
'hei_sim_main.cpp',
+ 'hei_sim_user_interface.cpp',
'../../src/isolator/hei_isolator.cpp',
'../../src/register/hei_hardware_register.cpp',
'../../src/util/hei_bit_string.cpp',