Armando Montanez | d2e4903 | 2019-12-06 13:06:01 -0800 | [diff] [blame] | 1 | .. _chapter-pw-dumb-io: |
| 2 | |
| 3 | .. default-domain:: cpp |
| 4 | |
| 5 | .. highlight:: sh |
| 6 | |
| 7 | ---------- |
| 8 | pw_dumb_io |
| 9 | ---------- |
| 10 | This module defines a simple and unoptimized interface for byte-by-byte |
| 11 | input/output. This can be done over a logging system, stdio, UART, via a |
| 12 | photodiode and modulated kazoo, or basically any way to get data in and out |
| 13 | of an application. |
| 14 | |
| 15 | This facade doesn't dictate any policies on input and output data encoding, |
| 16 | format, or transmission protocol. It only requires that backends return a |
| 17 | ``Status::OK`` if the operation succeeds. Backends may provide useful error |
| 18 | Status types, but depending on the implementation-specific Status values is |
| 19 | NOT recommended. Since this facade provides a very vague I/O interface, it |
| 20 | does NOT provide tests. Backends are expected to provide their own testing to |
| 21 | validate correctness. |
| 22 | |
| 23 | The intent of this module for simplifying bringup or otherwise getting data |
| 24 | in/out of a CPU in a way that is platform-agnostic. The interface is designed |
| 25 | to be easy to understand. There's no initialization as part of this |
| 26 | interface, there's no configuration, and the interface is no-frills WYSIWYG |
| 27 | byte-by-byte i/o. |
| 28 | |
| 29 | **It is strongly advised NOT to build projects on top of this interface.** There |
| 30 | are many drawbacks to using this interface, so it's not generally suited for use |
| 31 | in production. |
| 32 | |
| 33 | Setup |
| 34 | ===== |
| 35 | This module requires relatively minimal setup: |
| 36 | |
| 37 | 1. Chose a ``pw_dumb_io`` backend, or write one yourself. |
| 38 | 2. If using GN build, Specify the ``dir_pw_dumb_io_backend`` GN global |
| 39 | variable to point to your ``pw_dumb_io`` backend. |
| 40 | |
| 41 | Module usage |
| 42 | ============ |
| 43 | See backend docs for how to interact with the underlying dumb io implementation. |
| 44 | |
| 45 | Dependencies |
| 46 | ============ |
| 47 | * pw_dumb_io_backend |
| 48 | * pw_span |
| 49 | * pw_status |