pw_log_string: Add backend
pw_log_string is similar to pw_log_basic in that it simply takes raw
data at logging callsites and pipes it to an extern C symbol. The
difference is that pw_log_string does NOT provide an implementation of
said C symbol. This allows string-based log handling to be dictated by
the project.
Change-Id: Id40262a090a1c17db25425389fe52dce3c546c39
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/77182
Reviewed-by: Carlos Chinchilla <cachinchilla@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
Commit-Queue: Armando Montanez <amontanez@google.com>
diff --git a/pw_log_string/docs.rst b/pw_log_string/docs.rst
new file mode 100644
index 0000000..63d7fad
--- /dev/null
+++ b/pw_log_string/docs.rst
@@ -0,0 +1,30 @@
+.. _module-pw_log_string:
+
+=============
+pw_log_string
+=============
+``pw_log_string`` is a partial backend for ``pw_log``. This backend defines a
+C API that the ``PW_LOG_*`` macros will call out to. ``pw_log_string`` does not
+implement the C API, leaving projects to provide their own implementation.
+See ``pw_log_basic`` for a similar ``pw_log`` backend that also provides an
+implementation.
+
+As this module passes the log message, file name, and module name as a string to
+the handler function, it's relatively expensive and not well suited for
+space-constrained devices. This module is oriented towards usage on a host
+(e.g. a simulated device).
+
+---------------
+Getting started
+---------------
+This module is extremely minimal to set up:
+
+1. Implement ``pw_log_string_HandleMessage()``
+2. Set ``pw_log_BACKEND`` to ``"$dir_pw_log_string"``
+3. Set ``pw_log_string_BACKEND`` to point to the source set that implements
+ ``pw_log_string_HandleMessage()``
+
+What exactly ``pw_log_string_HandleMessage()`` should do is entirely up to the
+implementation. ``pw_log_basic``'s log handler is one example, but it's also
+possible to encode as protobuf and send over a TCP port, write to a file, or
+blink an LED to log as morse code.