pw_sys_io#

This module defines a simple and unoptimized interface for byte-by-byte input/output. This can be done over a logging system, stdio, UART, via a photodiode and modulated kazoo, or basically any way to get data in and out of an application.

This facade doesn’t dictate any policies on input and output data encoding, format, or transmission protocol. It only requires that backends return a OkStatus() if the operation succeeds. Backends may provide useful error Status types, but depending on the implementation-specific Status values is NOT recommended. Since this facade provides a very vague I/O interface, it does NOT provide tests. Backends are expected to provide their own testing to validate correctness.

The intent of this module for simplifying bringup or otherwise getting data in/out of a CPU in a way that is platform-agnostic. The interface is designed to be easy to understand. There’s no initialization as part of this interface, there’s no configuration, and the interface is no-frills WYSIWYG byte-by-byte i/o.

It is strongly advised NOT to build projects on top of this interface. There are many drawbacks to using this interface, so it’s not generally suited for use in production.

Setup#

Pigweed AI summary: This module requires minimal setup, including choosing a pw_sys_io backend or writing one, and specifying the pw_sys_io_BACKEND GN build arg if using GN build.

This module requires relatively minimal setup:

  1. Choose a pw_sys_io backend, or write one yourself.

  2. If using GN build, Specify the pw_sys_io_BACKEND GN build arg to point the library that provides a pw_sys_io backend.

Module usage#

Pigweed AI summary: The "Module usage" section advises readers to refer to the backend documentation for instructions on how to interact with the system's I/O implementation.

See backend docs for how to interact with the underlying system I/O implementation.

API reference#

Status pw::sys_io::ReadByte(std::byte *dest)#

Reads a single byte from the pw_sys_io backend. This function blocks until it either succeeds or fails to read a byte.

return:

  • OK - A byte was successfully read and is in dest.

  • RESOURCE_EXHAUSTED - The underlying source vanished.

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

Status pw::sys_io::TryReadByte(std::byte *dest)#

Reads a single byte from the pw_sys_io backend, if available.

return:

  • OK - A byte was successfully read and is in dest.

  • UNAVAILABLE - No byte is available to read; try later.

  • UNIMPLEMENTED - The function is not supported on this target.

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

Status pw::sys_io::WriteByte(std::byte b)#

Writes a single byte out the pw_sys_io backend. The function blocks until it either succeeds or fails to write the byte.

return:

  • OK - A byte was successfully written.

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

StatusWithSize pw::sys_io::WriteLine(const std::string_view &s)#

Writes a string out the pw_sys_io backend.

This function takes a null-terminated string and writes it out the pw_sys_io backend, adding any platform-specific newline character(s) (these are accounted for in the returned StatusWithSize).

return:

  • OK if all the bytes from the source string were successfully written. In all cases, the number of bytes successfully written are returned as part of the StatusWithSize.

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

StatusWithSize pw::sys_io::ReadBytes(ByteSpan dest)#

Fills a byte span from the pw_sys_io backend using ReadByte().

This function is implemented by the facade and simply uses ReadByte() to read enough bytes to fill the destination span. If there’s an error reading a byte, the read is aborted and the contents of the destination span are undefined. This function blocks until either an error occurs or all bytes are successfully read from the backend’s ReadByte() implementation.

Returns:

  • OK if the destination span was successfully filled. In all cases, the number of bytes successuflly read to the destination span are returned as part of the StatusWithSize.

StatusWithSize pw::sys_io::WriteBytes(ConstByteSpan src)#

Writes a span of bytes out the pw_sys_io backend using WriteByte().

This function is implemented by the facade and simply writes the source contents using WriteByte(). If an error writing a byte is encountered, the write is aborted and the error status is returned. This function blocks until either an error occurs, or all bytes are successfully written from the backend’s WriteByte() implementation.

Returns:

  • OK if all the bytes from the source span were successfully written. In all cases, the number of bytes successfully written are returned as part of the StatusWithSize.

Dependencies#

Pigweed AI summary: This paragraph lists the dependencies required for a project, including pw_sys_io_backend, pw_span, and pw_status.

  • pw_sys_io_backend

  • pw_span

  • pw_status