src/developer/ffx/plugins/emulator/configuration/README.md

# Emulator Engine Configuration Types

This crate contains a suite of data structures we've designed to carry all
of the parameters needed to define a virtual device, the guest OS running on the
device, and host-specific configuration for multiple emulation backends. To
ensure a consistent approach to defining these data types, our philosophy is
documented here. Please be sure you understand the roles of each type before
making changes to the structures herein.

## The Types

An emulation engine requires four distinct types to define its operation:

 - GuestConfig: This defines the operating system that will be running within
   the emulated environment. The guest OS is primarily defined by the disk
   images which are loaded to the virtual disks. This data structure includes
   information such as the virtual disk files, kernel files and arguments, etc.
   
 - VirtualDevice: This defines the virtual hardware the emulation backend will
   expose to the guest OS. The virtual hardware includes information about the
   system memory, screen size, peripheral devices, and CPU type and count, etc.
   
 - HostConfig: This provides information to the emulator about the host it will
   be running on which impacts how it initializes and performs the emulation. 
   This can include host-side interfaces to attach to the virtual hardware, disk
   locations for logs or companion programs, terminal environment variables,
   etc.
   
 - RuntimeConfig: This holds parameters that are specific to one instance of
   emulation which directly impact the behavior of the program. This can include
   logging verbosity levels, selectors for attaching to a debugger or emulated 
   consoles or whether to open the GUI, etc.
   
## The Justification

The primary justification for this grouping of parameters is reuse. The ffx
emulator launcher is designed to support multiple backing emulation programs,
such as Qemu, Aemu, Google Cloud Engine, or Vanadium. Each of these engines can
emulate various devices, and each of those devices can potentially run various 
operating systems.

The goal of our design is to be able to define a set of virtual devices (think
a Nest Hub, a Chromebook, a smart speaker), and run the same OS on each of
them just by swapping out the VirtualDevice configuration; or, build a set of 
sample OS versions and run them on identical emulated hardware just by swapping 
out the GuestConfig, which points to the image files for each version.

## The Code

The code in this crate is primarily type definitions, and all the fields are
public. The data for those types may come from anywhere: a test can populate a
GuestConfig with test input files, a developer can write code which defines a
VirtualDevice on-the-fly, and a RuntimeConfig will usually be populated by
command-line flags.

The primary expected use case, though, is to get configuration data from a
Product Bundle Manifest (PBM). The PBM is a well-defined set of configuration
parameters designed to emulate a specific system and device, and is included in
the Fuchsia SDK for public use. It is also generated by the build system for
in-tree users, according to the parameters supplied to the build. 

This crate contains utility functions which call into the PBM library to
retrieve configuration data, and convert it from the PBM library's data
structures into the emulator data structures. The result of these functions will
be checked for internal consistency - for example, if the virtual device has no
audio interface defined, the host shouldn't contain physical device
configuration either. The specific guarantees on each field will be documented 
by the internal doc comments for each type.

## The Takeaway

Each of the types laid out in this document serves a specific purpose, and while
they are closely related, they should not have any overlap. If a user attempting
to run identical guest systems on two devices has to change more than just the
VirtualDevice configs for those devices, something is in the wrong place.

On the back end, these types will probably be manipulated by the emulation
engine, combined and adjusted to fit that back-end's design, and ultimately used
to form a single command-line to invoke the emulator. This crate has no interest
in how that happens; the details of how the engine uses the config types are
specific to the engine itself and so out of scope here.