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

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

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.

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

Returns:

Code	Description
OK	A byte was successfully read and is in dest.
RESOURCE_EXHAUSTED	The underlying source vanished.

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

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

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

Returns:

Code	Description
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.

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.

Warning

Do not build production projects on top of pw_sys_io.

Pre:

This function must be implemented by the pw_sys_io backend.

Returns:

Code	Description
OK	A byte was successfully written.

StatusWithSize pw::sys_io::WriteLine(std::string_view s)

Writes a string out the pw_sys_io backend.

This function takes a string_view and writes it out the pw_sys_io backend, adding any platform-specific newline character(s) (these are accounted for in the returned 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.

Returns:

Code	Description
OK	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.

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:

Code	Description
OK	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:

Code	Description
OK	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

• pw_sys_io

• pw_span

• pw_status