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