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 libraries for UEFI context, run:
 make -f Makefile.efi

Installation:
 make install
 make -f Makefile.efi install

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.

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 deployed in live-boot or installer image.

Compiled and deployed onto target, RMC tool, an executable "rmc", is for clients
like scripts. RMC libraries and APIs are provided for client programs running in
EFI context and Linux user space. API and documentation can be found in rmc_api.h.
A single library, librmc.a in Linux or librmcefi.a in EFI, is provided to clients
in each supported context.

We could provide sample code using APIs and libraries in the future.

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

RMC so far is limited to 32 and 64 bit X86 architectures. Considering the
specifications RMC is based on actually support other non-X86 platforms and no
special requirements beyond what the specifications defined, rmc could support
non-X86 EFI platforms with some minimal changes.

The gcc compiler, standard header files and C libraries when compiled in Linux.
The standard header files, standard C libraries, and an EFI implementation to
provide low-level services (e.g. gnu-efi), are _not_ required by RMC in EFI
build.

This design is to keep the simplicity in rmc project and minimize the technical
debt at client side integrating with RMC.

=====
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.

Maintainers:
todor.minchev@linux.intel.com
jianxun.zhang@linux.intel.com