pw_assert: Expand documentation coverage
Change-Id: Ic3f57f30286ca96fb6d0bc303de39c60322ea663
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 5bc0f00..f9d371f 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -39,6 +39,7 @@
":core_docs",
":target_docs",
"$dir_pw_assert:docs",
+ "$dir_pw_assert_basic:docs",
"$dir_pw_bloat:docs",
"$dir_pw_boot_armv7m:docs",
"$dir_pw_build:docs",
diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst
index 44ed397..c181416 100644
--- a/pw_assert/docs.rst
+++ b/pw_assert/docs.rst
@@ -4,17 +4,49 @@
.. highlight:: cpp
----------
+=========
pw_assert
----------
+=========
+
+--------
+Overview
+--------
Pigweed's assert module provides facilities for applications to check
-preconditions. The module is split into two components:
+preconditions. The module is split into two components:
1. The facade (this module) which is only a macro interface layer
2. The backend, provided elsewhere, that implements the low level checks
-Basic usage example
--------------------
+All behaviour is controlled by the backend.
+
+The ``pw_assert`` public API provides three classes of macros:
+
++-----------------------------------------+--------------------------------+
+| PW_CRASH(format, ...) | Trigger a crash with a message |
++-----------------------------------------+--------------------------------+
+| PW_CHECK(condition[, format, ...]) | Assert a condition, optionally |
+| | with a message |
++-----------------------------------------+--------------------------------+
+| PW_CHECK_<type>_<cmp>(a, b[, fmt, ...]) | Assert that the expression |
+| | ``a <cmp> b`` is true, |
+| | optionally with a message. |
++-----------------------------------------+--------------------------------+
+
+.. tip::
+ All of the assert macros optionally support a message with additional
+ arguments, to assist in debugging when an assert triggers:
+
+ .. code-block:: cpp
+
+ PW_CHECK_INT_LE(ItemCount(), 100);
+ PW_CHECK_INT_LE(ItemCount(), 100, "System state: %s", GetStateStr());
+
+Compatibility
+-------------
+The facade is compatible with C and C++.
+
+Example
+-------
.. code-block:: cpp
@@ -23,5 +55,141 @@
int main() {
bool sensor_running = StartSensor(&msg);
PW_CHECK(sensor_running, "Sensor failed to start; code: %s", msg);
+
+ int temperature_c = ReadSensorCelcius();
+ PW_CHECK_INT_LE(temperature_c, 100,
+ "System is way out of heat spec; state=%s",
+ ReadSensorStateString());
}
+
+---------------------------
+Assert facade API reference
+---------------------------
+
+The below functions describe the assert API functions that applications should
+invoke to assert.
+
+.. cpp:function:: PW_CRASH(format, ...)
+
+ Trigger a crash with a message. Replaces LOG_FATAL() in other systems. Can
+ include a message with format arguments; for example:
+
+ .. code-block:: cpp
+
+ PW_CRASH("Unexpected: frobnitz in state: %s", frobnitz_state);
+
+ Note: ``PW_CRASH`` is the equivalent of ``LOG_FATAL`` in other systems, where
+ a device crash is triggered with a message. In Pigweed, logging and
+ crashing/asserting are separated. There is a ``LOG_CRITICAL`` level in the
+ logging module, but it does not have side effects; for ``LOG_FATAL``, instead
+ use this macro (``PW_CRASH``).
+
+.. cpp:function:: PW_CHECK(condition)
+.. cpp:function:: PW_CHECK(condition, format, ...)
+
+ Assert that a condition is true, optionally including a message with
+ arguments to report if the codition is false.
+
+ .. code-block:: cpp
+
+ PW_CHECK(StartTurbines());
+ PW_CHECK(StartWarpDrive(), "Oddly warp drive couldn't start; ruh-roh!");
+
+.. cpp:function:: PW_CHECK_TYPE_OP(a, b)
+.. cpp:function:: PW_CHECK_TYPE_OP(a, b, format, ...)
+
+ Asserts that ``a OP b`` is true, where ``a`` and ``b`` are converted to
+ ``TYPE``; with ``OP`` and ``TYPE`` described below.
+
+ If present, the optional format message is reported on failure. Depending on
+ the backend, values of ``a`` and ``b`` will also be reported.
+
+ Example, with no message:
+
+ .. code-block:: cpp
+
+ PW_CHECK_INT_LE(CurrentTemperature(), 100);
+ PW_CHECK_INT_LE(ItemCount(), 100);
+
+ Example, with an included message and arguments:
+
+ .. code-block:: cpp
+
+ PW_CHECK_FLOAT_GE(BatteryVoltage(), 3.2, "System state=%s", SysState());
+
+ Below is the full list of binary comparison assert macros, along with the
+ type specifier. The specifier is irrelevant to application authors but is
+ needed for backend implementers.
+
+ +-------------------+--------------+-----------+-----------------------+
+ | Macro | a, b type | condition | a, b format specifier |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_INT_LE | int | a <= b | %d |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_INT_LT | int | a < b | %d |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_INT_GE | int | a >= b | %d |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_INT_GT | int | a > b | %d |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_INT_EQ | int | a == b | %d |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_UINT_LE | unsigned int | a <= b | %u |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_UINT_LT | unsigned int | a < b | %u |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_UINT_GE | unsigned int | a >= b | %u |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_UINT_GT | unsigned int | a > b | %u |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_UINT_EQ | unsigned int | a == b | %u |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_FLOAT_LE | float | a <= b | %f |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_FLOAT_LT | float | a < b | %f |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_FLOAT_GE | float | a >= b | %f |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_FLOAT_GT | float | a > b | %f |
+ +-------------------+--------------+-----------+-----------------------+
+ | PW_CHECK_FLOAT_EQ | float | a == b | %f |
+ +-------------------+--------------+-----------+-----------------------+
+
+----------------------------
+Assert backend API reference
+----------------------------
+
+The backend controls what to do in the case of an assertion failure. In the
+most basic cases, the backend could display the assertion failure on something
+like sys_io and halt in a while loop waiting for a debugger. In other cases,
+the backend could store crash details like the current thread's stack to flash.
+
+This module does not provide a backend; see ``pw_assert_basic`` for a basic
+implementation (which we do not advise using in production).
+
+Here are the macros the backend must provide:
+
+.. cpp:function:: PW_HANDLE_CRASH(message, ...)
+
+ The backend should trigger a system crash or halt, and if possible, deliver
+ the specified message and arguments to the user or developer.
+
+.. cpp:function:: PW_HANDLE_ASSERT_FAILURE(condition_str, message, ...)
+
+ This macro is invoked from ``PW_CHECK`` if condition is false. The
+ application should crash with the given message and specified format
+ arguments, and may optionally include the stringified condition provided in
+ ``condition_str``.
+
+.. cpp:function:: PW_HANDLE_ASSERT_BINARY_COMPARE_FAILURE( \
+ a_str, a_val, op_str, b_str, b_val, type_fmt, message, ...)
+
+ This macro is invoked from the ``PW_CHECK_*_*`` macros if the condition
+ ``a_val op b_val`` is false. The facade API macros have already evaluated and
+ stringified the arguments, so the backend is free to report the details as
+ needed.
+
+ The backend is expected to report the failure to the user or developer in a
+ useful way, potentially capturing the string and values of the binary
+ comparison operands.
diff --git a/pw_assert_basic/BUILD.gn b/pw_assert_basic/BUILD.gn
index 9b39a97..091a095 100644
--- a/pw_assert_basic/BUILD.gn
+++ b/pw_assert_basic/BUILD.gn
@@ -12,6 +12,8 @@
# License for the specific language governing permissions and limitations under
# the License.
+import("$dir_pw_docgen/docs.gni")
+
config("default_config") {
include_dirs = [ "public" ]
}
@@ -43,3 +45,7 @@
public = [ "public/pw_assert_basic/assert_basic.h" ]
sources = public + [ "assert_basic.cc" ]
}
+
+pw_doc_group("docs") {
+ sources = [ "docs.rst" ]
+}
diff --git a/pw_assert_basic/docs.rst b/pw_assert_basic/docs.rst
new file mode 100644
index 0000000..c930b79
--- /dev/null
+++ b/pw_assert_basic/docs.rst
@@ -0,0 +1,15 @@
+.. _chapter-pw-assert-basic:
+
+.. default-domain:: cpp
+
+.. highlight:: cpp
+
+===============
+pw_assert_basic
+===============
+
+--------
+Overview
+--------
+This is a simple assert backend to complement the ``pw_assert`` facade.
+
