1.. _module-pw_sys_io: 2 3--------- 4pw_sys_io 5--------- 6This module defines a simple and unoptimized interface for byte-by-byte 7input/output. This can be done over a logging system, stdio, UART, via a 8photodiode and modulated kazoo, or basically any way to get data in and out 9of an application. 10 11This facade doesn't dictate any policies on input and output data encoding, 12format, or transmission protocol. It only requires that backends return a 13``OkStatus()`` if the operation succeeds. Backends may provide useful error 14Status types, but depending on the implementation-specific Status values is 15NOT recommended. Since this facade provides a very vague I/O interface, it 16does NOT provide tests. Backends are expected to provide their own testing to 17validate correctness. 18 19The intent of this module for simplifying bringup or otherwise getting data 20in/out of a CPU in a way that is platform-agnostic. The interface is designed 21to be easy to understand. There's no initialization as part of this 22interface, there's no configuration, and the interface is no-frills WYSIWYG 23byte-by-byte i/o. 24 25**It is strongly advised NOT to build projects on top of this interface.** There 26are many drawbacks to using this interface, so it's not generally suited for use 27in production. 28 29Setup 30===== 31This module requires relatively minimal setup: 32 331. Choose a ``pw_sys_io`` backend, or write one yourself. 342. 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. 36 37Module usage 38============ 39See backend docs for how to interact with the underlying system I/O 40implementation. 41 42API reference 43============= 44.. doxygenfunction:: pw::sys_io::ReadByte(std::byte* dest) 45.. doxygenfunction:: pw::sys_io::TryReadByte(std::byte* dest) 46.. doxygenfunction:: pw::sys_io::WriteByte(std::byte b) 47.. doxygenfunction:: pw::sys_io::WriteLine(std::string_view s) 48.. doxygenfunction:: pw::sys_io::ReadBytes(ByteSpan dest) 49.. doxygenfunction:: pw::sys_io::WriteBytes(ConstByteSpan src) 50 51Dependencies 52============ 53- :ref:`module-pw_sys_io` 54- :ref:`module-pw_span` 55- :ref:`module-pw_status` 56 57.. toctree:: 58 :hidden: 59 :maxdepth: 1 60 61 Backends <backends> 62