Interface pci.h

This interface presents a series of helpers when using the VMM PCI Driver. These helpers assisting with the creation of pci device entries and accessors the their configuration spaces.

Brief content:

Functions:

vmm_pci_entry_ignore_write(cookie, offset, size, value)

vmm_pci_mem_device_read(cookie, offset, size, result)

vmm_pci_mem_device_write(cookie, offset, size, value)

define_pci_host_bridge(bridge)

vmm_pci_create_passthrough(addr, config)

vmm_pci_create_bar_emulation(existing, num_bars, bars)

vmm_pci_create_irq_emulation(existing, irq)

vmm_pci_create_cap_emulation(existing, num_caps, cap, num_ranges, range_starts, range_ends)

Structs:

vmm_pci_device_def

vmm_pci_bar

pci_bar_emulation

pci_irq_emulation

pci_passthrough_device

pci_cap_emulation

Functions

The interface pci.h defines the following functions.

Function vmm_pci_entry_ignore_write(cookie, offset, size, value)

Helper write function that just ignores any writes

Parameters:

• cookie {void *}: User supplied PCI entry cookie
• offset {int}: Offset into PCI device header
• size {int}: Size of data to be written
• value {uint32_t}: value to write to PCI device header offset

Returns:

• Returns 0

Back to interface description.

Function vmm_pci_mem_device_read(cookie, offset, size, result)

Read method for a PCI devices memory @result {uint32_t *} result Resulting value read back from PCI device header

Parameters:

• cookie {void *}: PCI device header
• offset {int}: Offset into PCI device header
• size {int}: Size of data to be read

Returns:

• 0 if success, -1 if error

Back to interface description.

Function vmm_pci_mem_device_write(cookie, offset, size, value)

Write method for a PCI devices memory @value {uint32_t} value Value to write to PCI device header offset

Parameters:

• cookie {void *}: PCI device header
• offset {int}: Offset into PCI device header
• size {int}: Size of data to be read

Returns:

• 0 if success, -1 if error

Back to interface description.

Function define_pci_host_bridge(bridge)

Defines the configuration space values of the PCI host bridge

Parameters:

• bridge {vmm_pci_device_def_t *}: PCI bridge device definition

Returns:

No return

Back to interface description.

Function vmm_pci_create_passthrough(addr, config)

Construct a pure passthrough device based on the real PCI. This is almost always useless as you will almost certainly want to rebase io memory

Parameters:

• addr {vmm_pci_address_t}: Address of passthrough PCI device
• config {vmm_pci_config_t}: Ops for accessing the passthrough config space

Returns:

• vmm_pci_entry_t for passthrough device

Back to interface description.

Function vmm_pci_create_bar_emulation(existing, num_bars, bars)

Construct a pci entry that emulates configuration space bar read/write’s. The rest of the configuration space is passed on

Parameters:

• existing {vmm_pci_entry_t}: Existing PCI entry to wrap over and emulate its bar accesses
• num_bars {int}: Number of emulated bars in PCI entry
• bars {vmm_pci_bar_t *}: Set of bars to emulate access to

Returns:

• vmm_pci_entry_t for emulated bar device

Back to interface description.

Function vmm_pci_create_irq_emulation(existing, irq)

Construct a pci entry the emulates configuration space interrupt read/write’s. The rest of the configuration space is passed on

Parameters:

• existing {vmm_pci_entry_t}: Existing PCI entry to wrap over and emulate its IRQ accesses
• irq {int}: IRQ line value in PCI entry

Returns:

• vmm_pci_entry_t for emulated irq device

Back to interface description.

Function vmm_pci_create_cap_emulation(existing, num_caps, cap, num_ranges, range_starts, range_ends)

Capability space emulation. Takes list of addresses to use to form a capability linked list, as well as a ranges of the capability space that should be directly disallowed. Assumes a type 0 device.

Parameters:

• existing {vmm_pci_entry_t}: Existing PCI entry to wrap over and emulated it capability space accesses
• num_caps {int}: Number of caps in capability space
• caps {uint8_t *}: Capability list
• num_ranges {int}: Number of disallowed/ignored capability ranges e.g. MSI capabilities
• range_starts {uint8_t *}: Array of starting indexes of ignored capability ranges
• range_end {uint8_t *}: Array of ending idexes of ignored capabilities range

Returns:

• vmm_pci_entry_t with an emulated capability space

Back to interface description.

Structs

The interface pci.h defines the following structs.

Struct vmm_pci_device_def

Struct definition of a PCI device. This is used for emulating a device from purely memory reads. This is not generally useful on its own, but provides a nice skeleton

Elements:

• vendor_id {uint16_t}
• device_id {uint16_t}
• command {uint16_t}
• status {uint16_t}
• revision_id {uint8_t}
• prog_if {uint8_t}
• subclass {uint8_t}
• class_code {uint8_t}
• cache_line_size {uint8_t}
• latency_timer {uint8_t}
• header_type {uint8_t}
• bist {uint8_t}
• bar0 {uint32_t}
• bar1 {uint32_t}
• bar2 {uint32_t}
• bar3 {uint32_t}
• bar4 {uint32_t}
• bar5 {uint32_t}
• cardbus {uint32_t}
• subsystem_vendor_id {uint16_t}
• subsystem_id {uint16_t}
• expansion_rom {uint32_t}
• caps_pointer {uint8_t}
• reserved1 {uint8_t}
• reserved2 {uint16_t}
• reserved3 {uint32_t}
• interrupt_line {uint8_t}
• interrupt_pin {uint8_t}
• min_grant {uint8_t}
• max_latency {uint8_t}
• caps_len {int}
• caps {void *}

Back to interface description.

Struct vmm_pci_bar

Represents a PCI bar within a device

Elements:

• mem_type {pci_mem_type_t}: Type of memory supporting PCI bar
• address {uintptr_t}: Address of PCI bar
• size_bits {size_t}: Size of PCI bar in bits

Back to interface description.

Struct pci_bar_emulation

Wrapper datastructure over a pci entry and its configuration space. This is leveraged to emulate BAR accesses in an entries configuration space the guest OS over-writing elements in the configuration space

Elements:

• passthrough {vmm_pci_entry_t}: PCI entry being emulated
• num_bars {int}: Number of PCI bars
• bars {vmm_pci_bar_t}: Set of PCI bars being emulated in the PCI entry
• bar_writes {uint32_t}: Most recent write to each PCI bar in the configuration space. This avoids

Back to interface description.

Struct pci_irq_emulation

Wrapper datastructure over a pci entry and its configuration space. This is leveraged to emulate IRQ line accesses in an entries configuration space

Elements:

• passthrough {vmm_pci_entry_t}: PCI entry being emulated
• irq {int}: IRQ line value in PCI entry

Back to interface description.

Struct pci_passthrough_device

Datastructure providing direct passthrough access to a pci entry configuration space

Elements:

• addr {vmm_pci_address_t}: Address of PCI device
• config {vmm_pci_config_t}: Ops for accessing config space

Back to interface description.

Struct pci_cap_emulation

Wrappper datastructure over a pci entry and its configuration space. This is leveraged to emulate capabilities in an entries configuration space.

Elements:

• passthrough {vmm_pci_entry_t}: PCI entry being emulation
• num_caps {int}: Number of caps in capability space
• caps {uint8_t *}: Capability list
• num_ignore {int}: Number of disallowed/ignored capability ranges e.g. MSI capabilities
• ignore_start {uint8_t *}: Array of starting indexes of ignored capability ranges
• ignore_end {uint8_t *}: Array of ending idexes of ignored capabilities range

Back to interface description.

Back to top.