This artificial device is provided by QEMU inside their emulated
machines to feed extra configuration information to the system firmware,
or even to the operating system if it chose to use it. The behavior of
this device is explained in the docs/specs/fw_cfg.txt file in the QEMU
source.
This implementation currently supports the traditional interface, and
does not support the DMA based interface, although it probably wouldn't
be that hard to expand it to in the future.
The interface exposes individual entries which can optionally (and
usually) have paths associated with them that you can look up in a
directory type entry which has a fixed index. There are some entries
which are built into the device itself, which are the ID, signature and
directory entries, but the rest can be set up in the config scripts.
To make it easier to add new entries which are not from config scripts,
aka the ones that are hard coded in C++ and built into the device, the
actual entries themselves are not SimObjects, but it's easy to create a
SimObject wrapper which will spit them out for the device to consume.
Other items can be added to the device manually without generating them
with SimObjects.
Entries can have fixed or automatically generated indices. All entries
have a "path" in the sense that they have a name, but as a minor
deviation from what the QEMU documentation says, a "path" which begins
with a "." is not exported in the directory. This is purposefully
reminiscent of the unix style hidden file mechanism, where files or
directories who's names begin with "." are not normally shown by ls.
There are two different styles of this device, one which is IO port
based, and one which is MMIO based. Which to use depends on the
architecture, where x86 currently uses the IO scheme and ARM uses the
MMIO scheme. The documentation doesn't say what other ISAs use, if any
other ones support this interface, but I'd assume the MMIO version.
These are split out because the rules for how they work are subtly
different, but they share a lot of common machinery under the hood.
In most cases where somebody tries to talk to the device in an unusual
way, for instance accessing a register with an incomplete width or at an
offset, the device will just report all zeroes. The behavior in those
cases isn't specified, in many cases doesn't make sense based on the
design of the device, and doesn't seem to be depended on in the limited
use case I looked at.
Change-Id: Ib81ace406f877b298b9b98883d417e7d673916b5
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/55627
Tested-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Gabe Black <gabe.black@gmail.com>
Maintainer: Gabe Black <gabe.black@gmail.com>
