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