Created primary API wrappers for the Isolator class
This is an attempt to abstract the internal workings of the isolator
class from the user application.
Change-Id: Ic898b202da6a0ddb368411c11218ca019d1f23fd
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
diff --git a/src/hei_main.hpp b/src/hei_main.hpp
new file mode 100644
index 0000000..241b625
--- /dev/null
+++ b/src/hei_main.hpp
@@ -0,0 +1,103 @@
+/**
+ * @file hei_main.hpp
+ *
+ * These are the primary APIs for Hardware Error Isolation (aka the isolator).
+ * The intended flow is to:
+ *
+ * - Call initialize() for each necessary Chip Data File.
+ *
+ * - Call isolate() for each chip that needs error isolation.
+ *
+ * - Once isolation is no longer needed, call uninitialize() to free up
+ * resources used for isolation.
+ *
+ * Note that initialize() allocates many objects used for isolation and keeps
+ * them in memory. Its purpose is to avoid initializing the objects each time
+ * isolation is required. The data provided by the Chip Data Files is static.
+ * So reinitializing would be a waste of time, unless for some reason the Chip
+ * Data Files themselves are updated, which would require reinitialization
+ * anyway. Of course, leaving the object in memory chews up resources. So, some
+ * users may need to weigh performance vs. memory usage.
+ */
+
+#pragma once
+
+#include <hei_includes.hpp>
+#include <hei_isolation_data.hpp>
+#include <isolator/hei_isolator.hpp>
+
+namespace libhei
+{
+
+/**
+ * @brief Initializes all isolation objects based on data from the given Chip
+ * Data File.
+ *
+ * This function only takes one Chip Data File at a time. Therefore, the
+ * user application must call this function for each Chip Data File required
+ * for isolation.
+ *
+ * Storage and management of the Chip Data Files will vary per user application.
+ * Therefore, the user application is responsible for loading the Chip Data
+ * Files into memory as needed, and providing the location and size of the data.
+ *
+ * Once this function returns, the Chip Data File is no longer needed in memory.
+ *
+ * Details of the Chip Data File format can be found in CHIP_DATA.md.
+ *
+ * @param i_buffer A pointer to the buffer containing a single Chip
+ * Data File.
+ *
+ * @param i_bufferSize The size (in bytes) of the target Chip Data File.
+ *
+ * @param i_forceInit It is possible the user application could call this
+ * function for a chip type that has already been
+ * initialized. This is useful if for some reason the Chip
+ * Data File for a specific chip type has been updated. If
+ * this function is called and a chip type has already been
+ * initialized:
+ * - false (default), the function will return
+ * RC_CDF_INITIALIZED and exit.
+ * - 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
+ */
+inline ReturnCode initialize( void * i_buffer, size_t i_bufferSize,
+ bool i_forceInit = false )
+{
+ return Isolator::getSingleton().initialize( i_buffer, i_bufferSize,
+ i_forceInit );
+}
+
+/**
+ * @brief Deletes all internal isolation objects that were created by
+ * initialize().
+ */
+inline void uninitialize()
+{
+ Isolator::getSingleton().uninitialize();
+}
+
+/**
+ * @brief Isolates all active hardware errors found on the given chip.
+ *
+ * This functions requires initialize() to be called with the Chip Data File
+ * corresponding to the given chip type.
+ *
+ * @param o_isoData This parameter will contain a reference to the target chip
+ * and its chip type. The rest of the data in the object will
+ * be flushed and then repopulated with a list of all active
+ * hardware errors on this chip, the contents of any
+ * registers associated with the active errors, and any
+ * other data that can be useful for debug.
+ *
+ * @return RC_SUCCESS or RC_CHIP_DATA_MISSING
+ */
+inline ReturnCode isolate( IsolationData & o_isoData )
+{
+ return Isolator::getSingleton().isolate( o_isoData );
+}
+
+} // end namespace libhei
+