Armando Montanez | 1d5da9b | 2022-01-05 16:43:56 -0800 | [diff] [blame] | 1 | .. _module-pw_log_string: |
| 2 | |
| 3 | ============= |
| 4 | pw_log_string |
| 5 | ============= |
Ewout van Bekkum | 5ddc01d | 2022-03-08 12:50:25 -0800 | [diff] [blame] | 6 | ``pw_log_string`` is a partial backend for ``pw_log``. This backend fowards the |
| 7 | ``PW_LOG_*`` macros to the ``pw_log_string:handler`` facade which is backed by |
| 8 | a C API. ``pw_log_string:handler`` does not implement the full C API, leaving |
| 9 | projects to provide their own implementation of |
| 10 | ``pw_log_string_HandleMessageVaList``. See ``pw_log_basic`` for a similar |
| 11 | ``pw_log`` backend that also provides an implementation. |
Armando Montanez | 1d5da9b | 2022-01-05 16:43:56 -0800 | [diff] [blame] | 12 | |
| 13 | As this module passes the log message, file name, and module name as a string to |
| 14 | the handler function, it's relatively expensive and not well suited for |
| 15 | space-constrained devices. This module is oriented towards usage on a host |
| 16 | (e.g. a simulated device). |
| 17 | |
Ewout van Bekkum | 5ddc01d | 2022-03-08 12:50:25 -0800 | [diff] [blame] | 18 | Note that ``pw_log_string:handler`` may be used even when it's not used |
| 19 | as the backend for ``pw_log`` via ``pw_log_string``. For example it can be |
| 20 | useful to mix tokenized and string based logging in case you have a C ABI where |
| 21 | tokenization can not be used on the other side. |
| 22 | |
Armando Montanez | 1d5da9b | 2022-01-05 16:43:56 -0800 | [diff] [blame] | 23 | --------------- |
| 24 | Getting started |
| 25 | --------------- |
| 26 | This module is extremely minimal to set up: |
| 27 | |
Ewout van Bekkum | 5ddc01d | 2022-03-08 12:50:25 -0800 | [diff] [blame] | 28 | 1. Implement ``pw_log_string_HandleMessageVaList()`` |
Armando Montanez | 1d5da9b | 2022-01-05 16:43:56 -0800 | [diff] [blame] | 29 | 2. Set ``pw_log_BACKEND`` to ``"$dir_pw_log_string"`` |
Ewout van Bekkum | 5ddc01d | 2022-03-08 12:50:25 -0800 | [diff] [blame] | 30 | 3. Set ``pw_log_string_HANDLER_BACKEND`` to point to the source set that |
| 31 | implements ``pw_log_string_HandleMessageVaList()`` |
Armando Montanez | 1d5da9b | 2022-01-05 16:43:56 -0800 | [diff] [blame] | 32 | |
Ewout van Bekkum | 5ddc01d | 2022-03-08 12:50:25 -0800 | [diff] [blame] | 33 | What exactly ``pw_log_string_HandleMessageVaList()`` should do is entirely up to |
| 34 | the implementation. ``pw_log_basic``'s log handler is one example, but it's also |
Armando Montanez | 1d5da9b | 2022-01-05 16:43:56 -0800 | [diff] [blame] | 35 | possible to encode as protobuf and send over a TCP port, write to a file, or |
| 36 | blink an LED to log as morse code. |