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