Created initial README.md
Change-Id: Ic799939d918b1b037ece1bc434a4e0abc5a39e97
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a2977f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+openpower-libhei: Hardware Error Isolation for POWER Systems
+============================================================
+
+This library is a common, portable code base for isolating errors reported by
+hardware registers on POWER Systems chips.
+
+The primary consumers (and requirements drivers) will be:
+ * [OpenBMC Hardware Diagnostics](https://github.com/openbmc/openpower-hw-diags)
+ * [POWER Systems Hostboot firmware](https://github.com/open-power/hostboot)
+ * POWER Systems FSP firmware
+
+Core API
+--------
+
+Details TBD.
+
+Integration
+-----------
+
+This library is intended to be integrated into containing user applications as a
+set of source files (either imported, or as a git subtree/submodule).
+
+Details TBD.
+
+User Application Requirements and APIs
+--------------------------------------
+ * The method to access hardware register data will vary per user application.
+ Therefore, this library will declare the hardware access [user APIs], but
+ each containing user application must implement the APIs for their own
+ environment.
+ * This library will not contain data regarding hardware specific information.
+ Instead, that information will be provided by the user application in the
+ form of the [Chip Data Files].
+ * 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].
+ * 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].
+
+[user APIs]: src/hei_user_interface.hpp
+[Chip Data Files]: src/chip_data/CHIP_DATA.md
+
+Environment configuration
+-------------------------
+
+ * `__HEI_READ_ONLY`: When defined, it will ensure any hardware write support
+ is disabled. Note that the Chip Data Files will contain rules for clearing
+ and masking register bits. Both of which will require modifying hardware
+ registers, which is not allowed by user applications like OpenBMC or FSP
+ firmware.
+
+Development Notes
+-----------------
+
+ * The Hostboot and FSP environments only support up to **C++11**. Therefore,
+ this library cannot use anything newer at this time.
+ * Hostboot has a very limited environment. It does not include libc or
+ libstdc++. However, Hostboot has implemented select functions from those
+ libraries as needed. For details, you can reference `src/include/` in the
+ [Hostboot project](https://github.com/open-power/hostboot).
+
diff --git a/sim/hei_sim_main.cpp b/sim/hei_sim_main.cpp
index 035d003..7ddf7b4 100644
--- a/sim/hei_sim_main.cpp
+++ b/sim/hei_sim_main.cpp
@@ -3,7 +3,7 @@
int main()
{
- HEI::Isolator iso;
+ libhei::Isolator iso;
iso.initialize();
diff --git a/sim/hei_trace.hpp b/sim/hei_trace.hpp
deleted file mode 100644
index ebb2a8e..0000000
--- a/sim/hei_trace.hpp
+++ /dev/null
@@ -1,3 +0,0 @@
-#include <stdio.h>
-
-#define HEI_TRAC(...) printf( __VA_ARGS__ ); printf( "\n" );
diff --git a/sim/hei_user_defines.hpp b/sim/hei_user_defines.hpp
new file mode 100644
index 0000000..54c7344
--- /dev/null
+++ b/sim/hei_user_defines.hpp
@@ -0,0 +1,18 @@
+#include <stdio.h>
+#include <assert.h>
+
+#define HEI_INF( ... ) \
+{ \
+ printf( "I> " __VA_ARGS__ ); \
+ printf( "\n" ); \
+}
+
+#define HEI_ERR( ... ) \
+{ \
+ printf( "E> " __VA_ARGS__ ); \
+ printf( "\n" ); \
+}
+
+#define HEI_ASSERT( expression ) \
+ assert( expression );
+
diff --git a/src/chip_data/CHIP_DATA.md b/src/chip_data/CHIP_DATA.md
new file mode 100644
index 0000000..7775b48
--- /dev/null
+++ b/src/chip_data/CHIP_DATA.md
@@ -0,0 +1,4 @@
+Chip Data File definition
+=========================
+
+TBD
diff --git a/src/hei_isolator.cpp b/src/hei_isolator.cpp
index ff58877..fda761f 100644
--- a/src/hei_isolator.cpp
+++ b/src/hei_isolator.cpp
@@ -1,27 +1,27 @@
#include "hei_isolator.hpp"
-namespace HEI
+namespace libhei
{
Isolator::Isolator()
{
- HEI_TRAC( "Isolator::Isolator()" );
+ HEI_INF( "Isolator::Isolator()" );
}
Isolator::~Isolator()
{
- HEI_TRAC( "Isolator::~Isolator()" );
+ HEI_INF( "Isolator::~Isolator()" );
}
void Isolator::initialize()
{
- HEI_TRAC( "Isolator::initialize()" );
+ HEI_INF( "Isolator::initialize()" );
}
void Isolator::isolate()
{
- HEI_TRAC( "Isolator::isolate()" );
+ HEI_INF( "Isolator::isolate()" );
}
-} // end namespace HEI
+} // end namespace libhei
diff --git a/src/hei_isolator.hpp b/src/hei_isolator.hpp
index 09ed43e..483b260 100644
--- a/src/hei_isolator.hpp
+++ b/src/hei_isolator.hpp
@@ -3,7 +3,7 @@
#include "hei_user_interface.hpp"
-namespace HEI
+namespace libhei
{
class Isolator
@@ -22,4 +22,4 @@
}; // end class Isolator
-} // end namespace HEI
+} // end namespace libhei
diff --git a/src/hei_user_interface.hpp b/src/hei_user_interface.hpp
index b7dd092..30e869d 100644
--- a/src/hei_user_interface.hpp
+++ b/src/hei_user_interface.hpp
@@ -1,10 +1,33 @@
#pragma once
-// This header provides access to headers and macros defined by the user
-// application.
-#include <hei_trace.hpp>
+// 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>
-// The rest of this header contains interfaces that the user application must
-// define.
+namespace libhei
+{
+
+/**
+ * @brief Perform a hardware read operation.
+ */
+void deviceRead();
+
+#ifndef __HEI_READ_ONLY
+
+/**
+ * @brief Perform a hardware write operation.
+ */
+void deviceWrite();
+
+#endif
+
+} // end namespace libhei