simics-uefi

Description

The simics-uefi class implements a pseudo device that provides information to the BIOS and also transmits information from the BIOS into other simulation devices.
The device deliberately sets vendor and device ID to 0xffff so that any proper PCI enumeration will not see it. Software like the Simics UEFI BIOS, which knows the exact BDF of the device can then do PCI configuration accesses to talk to the device without it interfering with other PCI operations.

The features of the device are:

Simics package list retrieval
Allows the BIOS to read the list of packages associated with the current project.
Video mode inspection and selection
During boot, the BIOS will write out the list of supported video modes to the simics-uefi device. This can be checked using the status command of the device.
On a subsequent boot, the user can set the attribute video_mode to one of these modes and the BIOS will then switch into that mode before handing over to the OS.
Boot device selection
The user can set the attribute selected_boot_option to define what boot device shall have maximum priority. Please note that this must be an exact match of the boot device name. You can check that by booting manually first, go into the boot device selection menu in the BIOS and then use one of the strings listed there. Please ensure that whatever device you want to boot from is connected when checking the available boot devices.
ACPI table overrides/additions
The attribute additional_acpi_tables contains a list of 32 references to objects of class image (by default all entries point to None). If an actual image reference is inserted into the list, the BIOS will assume that it contains a binary ACPI table and install that. If the table has a signature that already exists, it will be replaced with what is in the image. Only top-level, single-instance ACPI tables can be installed/replaced.
RSDP write out
The attribute legacy_bios_rom_image can point to an object of class image (by default, it does not). If it does, the BIOS will write the RSDP structure into that image at the offset defined in attribute legacy_bios_rom_offset. Some OSes that do not use the UEFI RSDP access will scan certain memory regions for the RSDP structure. This mechanism allows the end user to ensure the RSDP structure appears where their SW wants it to be.
Additional memory regions to reserve
The attribute additional_memory_regions_to_reserve can store a list of regions that shall be reserved by the BIOS so that they are no longer used by the target OS. The list is of the format [[S0, L0], [S1, L1], [S2, L2], ...] where Sx is the start of an area and Lx is the length of the area.

Interfaces Implemented

conf_object, log_object, pcie_device

Connects

additional_acpi_tables (optional): Required interfaces: image
clkreq (optional): Required interfaces: signal
legacy_bios_rom_image (optional): Required interfaces: image
upstream_target (optional): Required interfaces: pcie_map; Optional interfaces: io_memory, memory_space, pcie_link_control, port_space, ram, rom, transaction, transaction_translator, translator

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.
state-change: Notifier on potential DML state change

Port Objects

bank.pcie_config: simics-uefi.pcie_config
port.HRESET: simics-uefi.HRESET
port._upstream_egress: simics-uefi._upstream_egress
port._upstream_egress_dead_end: simics-uefi._upstream_egress_dead_end
port.phy: simics-uefi.phy
port.upstream_ingress: simics-uefi.upstream_ingress
upstream_ingress_targets: simics-uefi.upstream_ingress_targets

Commands for this class

add-acpi-table-bytes – add ACPI table
add-acpi-table-file – add ACPI table
info – print information about the object
status – print status of the object

Attributes

additional_memory_regions_to_reserve: Optional attribute; read/write access; type: [[ii]*]
List of memory regions that need to be reserved. Each list element is a pair of a region start address and the region size.
caps_accesses: Pseudo attribute; read-only access; type: i
Number of accesses to capabilities data
clkreq: Optional attribute; read/write access; type: o|[os]|n
CLKREQ output signal (active high)
Required interface: signal
detected_video_modes: Pseudo attribute; read/write access; type: [s*]|s
Video modes that were detected during BIOS run
legacy_bios_rom_image: Optional attribute; read/write access; type: o|[os]|n
Target image for legacy BIOS data
Required interface: image
legacy_bios_rom_offset: Optional attribute; read/write access; type: i
Offset at which to start writing
package_data: Pseudo attribute; read-only access; type: [i*]
Package data stored in capabilities
selected_boot_option: Optional attribute; read/write access; type: s|n
Boot device that shall get maximum priority
video_mode: Optional attribute; read/write access; type: i
Video mode to be set during boot

Provided By

simics-uefi

Interfaces Implemented

conf_object, log_object, signal

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Interfaces Implemented

conf_object, log_object, transaction_translator, translation_flush

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface transaction_translator

memory-map – print physical memory map
wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete

Interfaces Implemented

conf_object, log_object, transaction

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface transaction

wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete

Interfaces Implemented

conf_object, log_object, bank_instrumentation_subscribe, instrumentation_order, pcie_function_info, register_view, register_view_catalog, register_view_read_only, transaction

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface bank_instrumentation_subscribe

bp-break-bank – set device access break
bp-run-until-bank – run until specified device access occurs
bp-trace-bank – enable tracing of device accesses
bp-wait-for-bank – wait for specified device access

Commands for interface instrumentation_order

instrumentation-move – reorder instrumentation connections
instrumentation-order – list instrumentation order for object

Commands for interface pcie_function_info

pcie-dma-read – memory PCIe DMA Read
pcie-dma-write – memory PCIe (DMA) Write
pcie-memory-probe – probe an upstream PCIe DMA

Commands for interface transaction

wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete

Attributes

function_number: Pseudo attribute; read-only access; type: i
PCIe function number of this bank

Interfaces Implemented

conf_object, log_object, pcie_link_readiness, transaction

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface transaction

wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete

Interfaces Implemented

conf_object, log_object, pcie_ingress_handling, transaction_translator, translation_flush

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface transaction_translator

memory-map – print physical memory map
wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete

Interfaces Implemented

conf_object, log_object

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Port Objects

config: memory-space – Instances of the memory-space class provide linear address spaces into which devices and memory can be mapped.
io: memory-space – Instances of the memory-space class provide linear address spaces into which devices and memory can be mapped.
memory: memory-space – Instances of the memory-space class provide linear address spaces into which devices and memory can be mapped.
message: memory-space – Instances of the memory-space class provide linear address spaces into which devices and memory can be mapped.
port._dead_end: simics-uefi.upstream_ingress_targets._dead_end
port.broadcast: simics-uefi.upstream_ingress_targets.broadcast

Interfaces Implemented

conf_object, log_object, transaction

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface transaction

wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete

Interfaces Implemented

conf_object, log_object, transaction

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for interface transaction

wait-for-get – issue an inquiry read transaction and wait for it to complete
wait-for-read – issue a read transaction and wait for it to complete
wait-for-set – issue an inquiry write transaction and wait for it to complete
wait-for-write – issue a write transaction and wait for it to complete