Runtime Machine Configuration (RMC)
================================================================================

=====
Introduction
=====
RMC project provides BSP and OEM a new way to deal with configuration at a board
or product level in a generic software stack at runtime. It answers two questions
with a centralized approach:

1) How to identify a type of board in a software stack

2) How to access to data associated to a type of board at runtime

With RMC, developer of a client software can have a generic implementation of
logic and hardcoded configuration file names in source code. RMC magically
returns data for the type of the running board at runtime. The final effect is a
better isolation between a generic stack and quirks for different board types.

=====
How it works
=====
Developer runs RMC tool on a board to obtain a fingerprint file. A fingerprint
is the software identity of a type of board. Fingerprint so far is the only RMC-
specific data exposed to outside. Any software calling RMC to get board-specific
data doesn't need to carry fingerprint. It is only used to map data and board
type in a RMC database.

With the same RMC tool, developers can generate a RMC record file which contains
a signature computed from board's fingerprint and all data specific to the type
of board (provided by developers).

The next step is to use RMC tool to generate a RMC database file with records
for different boards.

At runtime, clients (software to call RMC) query files for the type of the
running board with filenames. Once called, via RMC tool or APIs provided from
RMC libraries, RMC collects fingerprint of the running board, computes its
signature, seeks any possible records in RMC database file to match the board it
runs on with signatures, and then returns the file blob to its caller if there
is a blob with the same _name_ specified by the caller.

RMC tool (CLI) lives in Linux user space. RMC libraries provides APIs in C, so
that any programs can link with RMC libraries and call these APIs to get data
specific to a type of board at runtime. RMC libraries can also be linked in EFI
context for bootloaders, as well as in Linux user space.

=====
Build:
=====
To build libraries and RMC tool for user space, run:
 make

To build 64-bit libraries for UEFI context, run:
 RMC_EFI_ARCH=x86_64 make -f Makefile.efi

To build 32-bit libraries for UEFI context, run:
 RMC_EFI_ARCH=ia32 make -f Makefile.efi

RMC_CFLAGS can be used to pass extra flags.

To get usage of RMC tool, just compile the project and run "rmc" without any
arguments. Examples are also provided in usage message, in a rough order of
recommended workflow.

Refer to rmcl.h and rsmp.h for APIs. RMC tool itself uses these APIs, so it can
be a good example (rmc.c).

To integrate RMC into a build system (Yocto, Android...):
On build host, compile RMC tool for host architecture and use it to generate RMC
database files with all fingerprints and board-specific data checked in source
tree. Build system is responsible to manage fingerprints and data. RMC database
files shall be available in live-boot or installer image.

For target, compile RMC tool and libraries again for target architecture. RMC
tool, an executable, can be deployed to target for clients like scripts. RMC
libraries are expected to be linked in programs.

Further refactor work is planned to simplify the integration
between RMC and other software clients.

=====
Requirements
=====
Board is required to have UEFI and SMBIOS compliant firmware. The efi driver in
Linux kernel is also necessary.

=====
Patch submission & Maintenance
=====
1. Developers please submit patches to yocto@yoctoproject.org mailing list for
review. We suggest developers to have "RMC" or "rmc" in mail subjects for
visibility in this generic mailing list.

2. Once there is no any open items from code review in a period, maintainer pulls
the patches and run test in rmc project.

3. Maintainer merges patch to branch "rmc-dev" that always holds changes passed
review and internal test, otherwise informs submitter to re-work if test fails.

4. Maintainer tests changes pending on "rmc-dev" branch with any build system
integrated with RMC (e.g. a Yocto BSP).

5. Maintainer merges the pending patches from "rmc-dev" to "master" branch that
shall be always for good changes passed code review, internal test and system
test.

Maintainer:
jianxun.zhang@linux.intel.com
