Documentation updates for hei_user_defines.hpp
Change-Id: I86e4f6fa2d26c6aa36e30a46823ff3f7b6742bfc
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
diff --git a/README.md b/README.md
index d377aa1..3320980 100644
--- a/README.md
+++ b/README.md
@@ -17,30 +17,21 @@
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.
+This library can be integrated into a user application's source (either
+imported, or as a git subtree/submodule) or built as static library.
User Application Requirements and APIs
--------------------------------------
- * The method to access hardware register data will vary per user application.
+ * The process 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.
+ each 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 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
- [common includes header][].
+ * Tracing, or logging, methods will vary per user application. Therefore, this
+ library will declare the tracing/logging [user APIs][], but each user
+ application must implement the APIs for their own environment.
Environment configuration
-------------------------
@@ -54,17 +45,32 @@
Development Notes
-----------------
- * The Hostboot environment only support up to **C++14**. Therefore, this
+ * The Hostboot environment only supports up to **C++14**. 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
[POWER Systems Hostboot firmware][].
+Building
+--------
+
+For a standard OpenBMC release build, you want something like:
+```
+meson setup -Dtests=disabled <build_dir>
+ninja -C <build_dir>
+ninja -C <build_dir> install
+```
+
+For a test / debug build, a typical configuration is:
+```
+meson setup -Dtests=enabled <build_dir>
+meson test -C <build_dir>
+```
+
[OpenBMC Hardware Diagnostics]: https://github.com/openbmc/openpower-hw-diags
[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 ac56493..61791f4 100644
--- a/src/hei_includes.hpp
+++ b/src/hei_includes.hpp
@@ -13,17 +13,6 @@
#include <map>
#include <vector>
-// 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)
-//
-
// Internal includes
#include <hei_chip.hpp>
#include <hei_types.hpp>
diff --git a/src/hei_user_interface.hpp b/src/hei_user_interface.hpp
index d880ef4..17bccb1 100644
--- a/src/hei_user_interface.hpp
+++ b/src/hei_user_interface.hpp
@@ -3,44 +3,9 @@
/**
* @file hei_user_interface.hpp
*
- * The method for actions like hardware register access will vary per user
+ * The process for actions like hardware register access will vary per user
* application. Therefore, the user application must define all of the APIs
- * listed below.
- *
- * 1. ReturnCode libhei::registerRead(const Chip& i_chip, void* o_buffer,
- * size_t& io_bufSize, uint64_t i_regType,
- * uint64_t i_address);
- *
- * 2. ReturnCode libhei::registerWrite(const Chip& i_chip, void* i_buffer,
- * size_t& io_bufSize, uint64_t i_regType,
- * uint64_t i_address);
- *
- * 3. void libhei::hei_inf(...)
- * 4. void libhei::hei_err(...)
- *
- * Example user application implementation of hei_inf(...) and hei_err(...)
- *
- * void hei_inf(char* format, ...)
- * {
- * va_list args;
- *
- * printf("I> ");
- * va_start(args, format);
- * vprintf(format, args);
- * va_end(args);
- * printf("\n");
- * }
- *
- * void hei_err(char* format, ...)
- * {
- * va_list args;
- *
- * printf("E> ");
- * va_start(args, format);
- * vprintf(format, args);
- * va_end(args);
- * printf("\n");
- * }
+ * declared in this header file.
*/
#include <stdlib.h>
@@ -116,12 +81,42 @@
bool registerWrite(const Chip& i_chip, void* i_buffer, size_t& io_bufSize,
uint64_t i_regType, uint64_t i_address);
-// used by HEI_INF macro in this library
-void hei_inf(char* format, ...); // implemented in user application
-
-// used by HEI_ERR macro in this library
-void hei_err(char* format, ...); // implemented in user application
-
#endif
+/**
+ * @brief Prints an informational trace/log.
+ *
+ * This is similar to printing a single line of text to stdout. Example
+ * implementation:
+ * void hei_inf(char* format, ...)
+ * {
+ * va_list args;
+ * va_start(args, format);
+ * vfprintf(stdout, format, args);
+ * va_end(args);
+ * fprintf(stdout, "\n");
+ * }
+ *
+ * @param i_format The string format and variatic arguments.
+ */
+void hei_inf(char* i_format, ...);
+
+/**
+ * @brief Prints an error trace/log.
+ *
+ * This is similar to printing a single line of text to stderr. Example
+ * implementation:
+ * void hei_inf(char* format, ...)
+ * {
+ * va_list args;
+ * va_start(args, format);
+ * vfprintf(stderr, format, args);
+ * va_end(args);
+ * fprintf(stderr, "\n");
+ * }
+ *
+ * @param i_format The string format and variatic arguments.
+ */
+void hei_err(char* i_format, ...);
+
} // end namespace libhei
diff --git a/test/hei_user_defines.cpp b/test/hei_user_defines.cpp
deleted file mode 100644
index f6e39f0..0000000
--- a/test/hei_user_defines.cpp
+++ /dev/null
@@ -1,30 +0,0 @@
-#include <assert.h>
-#include <stdarg.h>
-#include <stdio.h>
-
-namespace libhei
-{
-
-void hei_inf(char* format, ...)
-{
- va_list args;
-
- printf("I> ");
- va_start(args, format);
- vprintf(format, args);
- va_end(args);
- printf("\n");
-}
-
-void hei_err(char* format, ...)
-{
- va_list args;
-
- printf("E> ");
- va_start(args, format);
- vprintf(format, args);
- va_end(args);
- printf("\n");
-}
-
-} // namespace libhei
diff --git a/test/meson.build b/test/meson.build
index 209bad3..642b827 100644
--- a/test/meson.build
+++ b/test/meson.build
@@ -3,7 +3,7 @@
# supporting files that need compiled/linked
test_src = ['../src/util/hei_bit_string.cpp',
- 'hei_user_defines.cpp']
+ 'sim_tracing.cpp']
# build g-test framework unit tests
gtests = [
diff --git a/test/sim_tracing.cpp b/test/sim_tracing.cpp
new file mode 100644
index 0000000..f3ac008
--- /dev/null
+++ b/test/sim_tracing.cpp
@@ -0,0 +1,29 @@
+#include <stdarg.h>
+#include <stdio.h>
+
+namespace libhei
+{
+
+// prints a single line to stdout
+void hei_inf(char* format, ...)
+{
+ va_list args;
+ fprintf(stdout, "I> ");
+ va_start(args, format);
+ vfprintf(stdout, format, args);
+ va_end(args);
+ fprintf(stdout, "\n");
+}
+
+// prints a single line to stderr
+void hei_err(char* format, ...)
+{
+ va_list args;
+ fprintf(stderr, "E> ");
+ va_start(args, format);
+ vfprintf(stderr, format, args);
+ va_end(args);
+ fprintf(stderr, "\n");
+}
+
+} // namespace libhei
diff --git a/test/simulator/meson.build b/test/simulator/meson.build
index ec5410f..590e381 100644
--- a/test/simulator/meson.build
+++ b/test/simulator/meson.build
@@ -1,12 +1,12 @@
# Simulator sources
-sim_libhei = [
+sim_src = [
'simulator.cpp',
- 'hei_user_interface.cpp',
- '../hei_user_defines.cpp'
+ 'sim_hardware_access.cpp',
+ '../sim_tracing.cpp'
]
# Test cases
-test_libhei = [
+test_src = [
'sample_test_case.cpp',
]
@@ -15,7 +15,7 @@
# Build simulator linked locally
if gtest.found()
test('simulator',
- executable('simulator', sim_libhei, test_libhei,
+ executable('simulator', sim_src, test_src,
dependencies : gtest,
link_with : libhei_static,
include_directories: incdir))
diff --git a/test/simulator/hei_user_interface.cpp b/test/simulator/sim_hardware_access.cpp
similarity index 100%
rename from test/simulator/hei_user_interface.cpp
rename to test/simulator/sim_hardware_access.cpp