\chapter{Machine Configuration Description}
\label{cfgstr}

\begin{commentary}
  To reduce porting effort for OS boots, we have reverted back to
  using Device Trees to communicate platform information to the
  kernel, so this chapter is out of date.  Config string was designed
  for other uses in addition, but for now, we are staying with a
  standard device tree model.
 \end{commentary}

RISC-V platforms may contain myriad devices, processor cores, and
configuration parameters.  To support higher-level software, including
bootloaders and operating systems, it is recommended that hardware
platforms embed a description of their components in read-only memory
that is directly accessible after processor reset for use by low-level
system software, external debuggers, or manufacturing test procedures.
We call this low-level embedded information a configuration
description.  We define here a standard mechanism to encode and locate
the configuration information, and to determine the format of the
configuration information.

\section{Configuration String Search Procedure}

The platform must describe how to locate a pointer to find this
string, for example, by specifying a fixed physical address at which
the pointer resides.  To support a wide variety of platforms,
configuration formats, and chips with manufacturing-time programming
of configuration options, a flexible search procedure is defined to
locate the configuration information seeded by the initial pointer
specified by the platform.

The configuration string pointer provided by the platform points to an
initial memory address at which the search for configuration string
begins.

The configuration string cannot begin with a padding byte, where a
padding byte is defined to contain either {\tt 0x0} or {\tt 0xff}, but
can be preceded by up to 63 padding bytes that are ignored.  If 64
padding bytes are encountered, then the search terminates without
finding a config string.

\begin{commentary}
The padding bytes represent common values returned by unpopulated
memory or bus regions or unprogrammed non-volatile
memory. Configuration strings can therefore include pointers to
regions that are optionally populated or programmed, and these regions
will be ignored if there is nothing present.  The padding bytes also
support alignment of binary data structures.
\end{commentary}

Otherwise the first non-padding byte is the beginning of the
configuration information.  For example, configuration information in
Device Tree String format would begin with a ``/dts-v1/''.
Configuration information in Flattened Device Tree format would begin
with the magic number {\tt 0xd00dfeed}.  Configuration information in
the config string format would begin with ``/cs-v1/''.
\begin{commentary}
  Config string is a new format that is backwards-compatible with
  device tree string (as far as DTS specs exist) but can include
  additional configuration information in other memory regions.
\end{commentary}

