third_party/pigweed/repo/pw_sys_io/docs.rst

   1 .. _module-pw_sys_io:
   2
   3 ---------
   4 pw_sys_io
   5 ---------
   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
  13 ``OkStatus()`` if the operation succeeds. Backends may provide useful error
  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
  33   1. Chose a ``pw_sys_io`` backend, or write one yourself.
  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.
  36
  37 Module usage
  38 ============
  39 See backend docs for how to interact with the underlying system I/O
  40 implementation.
  41
  42 Dependencies
  43 ============
  44   * pw_sys_io_backend
  45   * pw_span
  46   * pw_status