Capabilities templates

These are templates for PCIe Capabilities. They are designed to be applied on a group. For convenience there exists a template defining_xyz_capability for each capability xyz which defines a group xyz with the xyz_capability applied. Most templates only define the registers with their standard access restrictions. If additional behavior is needed, the user of the template must implement this manually.

Each capability template uses the following parameters:

• base: Base address of the capability header
• next_ptr: Value of the next_ptr field in the capability header

Power Management Capability registers

• name: pm_capability
• implemented: registers only

PCI Express Capability registers

• name: exp_capability
• implemented: functional

Parameters:

• has_hotplug_capable_slot: Device has a native PCIe Hot-Plug capable slot. This param will set the has_hotplug_capable in the instantiated exp_slot template, default false
• has_attention_button_slot: Attention button present in slot. This param will set the has_attention_button in the instantiated exp_slot template, default false
• has_links: Presence of links registers, default has_hotplug_capable_slot
• has_slots: Presence of slots registers, default has_hotplug_capable_slot
• has_root: Presence of root registers, default false
• dp_type: Device/port type, as indicated in exp.capability.dpt register field, (see constants), default PCIE_DP_Type_EP.
• cap_version: Version of this capability structure, as indicated in exp.capability.cv register field, default 2
• imn: The MSI/MSI-X vector used for the interrupt message generated in association with any of the status bits of this Capability structure, default 0

Adds groups:

• device which instantiates template exp_dev.
• link which instantiates template exp_link. Optionally added depending on param has_links.
• slot which instantiates template exp_slot. Optionally added depending on param has_slots.
• root which instantiates template exp_root. Optionally added depending on param has_root.

Device/port type constants for field exp.capability.dpt

PCIE_DP_Type_EP, PCIE_DP_Type_Legacy_EP, PCIE_DP_Type_RCiEP, PCIE_DP_Type_RCEC, PCIE_DP_Type_RP, PCIE_DP_Type_UP, PCIE_DP_Type_DP, PCIE_DP_Type_BridgeX, PCIE_DP_Type_XBridge

flit_mode_supported() -> (bool)

Returns true the Flit Mode Supported field is set

PCI Express Capability Device registers

• name: exp_dev
• implemented: functional

set_status_error(uint8 error_type, bool is_ur) throws

Sets the bits in the status register related to error signaling.

PCI Express Capability Link registers

• name: exp_link
• implemented: link training

Parameters:

• dll_link_active_reporting: Link supports DLL Link Active Reporting, default false
• max_link_speed: Max link speed provided as a value of the pcie_link_speed_t enum, default PCIE_Link_Speed_Undefined
• max_link_width: Max link width provided as a value of the pcie_link_width_t enum, PCIE_Link_Width_Undefined
• link_bandwidth_notifications: Support Link Bandwidth Notifications, default ((dp_type == PCIE_DP_Type_DP) || (dp_type == PCIE_DP_Type_RP))

Methods

link_speed_vector_decode(uint8 encoded_link_speed)

Given a value in the Current Link Speed or Max Link Speed field, returns the corresponding link speed based on values in the Supported Link Speeds Vector field. Returns PCIE_Link_Speed_Undefined if the value of encoded_link_speed corresponds to an unset Supported Link Speed vector bit.

set_link_training_target(map_target_t *target)

Sets the default link training target when do_link_training() is called with NULL.

link_training_width_speed_result(const transaction_t *t, exception_type_t exc) -> (bool)

This method handles pcie_link_negotiation atom after a link training transaction has completed. If there is no pcie_link_negotiation atom, the method does nothing.

link_training_flit_mode_result(const transaction_t *t, exception_type_t exc)

This method handles pcie_link_flit_mode atom after a link training transaction has completed. If there is no pcie_link_flit_mode atom, the method does nothing.

link_training_flit_mode_result(const transaction_t *t, exception_type_t exc)

This method handles any custom atoms after a link training transaction has completed. If there are no custom atoms in the transaction, this method should do nothing.

link_training_result(const transaction_t *t, exception_type_t exc) -> (bool)

Calls all the link training result handlers. Returns false if at least one of the handlers return false.

do_link_training(uint16 device_id)

Initiates link training by sending a link training transaction to either the to the target set with set_link_training_target(). Returns true if link negotiation was deemed successful.

do_link_training_extra(uint16 device_id, atom_t *extra_atoms)

Same as (do_link_training())[#do_link_training], but allows for adding extra atoms to the link training transaction.

get_supported_link_speeds_vector() -> (uint7)

Returns the Supported Link Speeds Vector.

get_target_link_speed() -> (pcie_link_speed_t)

Returns the target link speed. Note that this is not the value of the Target Link Speed field, but rather the decoded target link speed based on the value of the Target Link Speed field. Note that the Downstream component should not be using this during link negotiation, as it's only applicable in Enter Compliance mode in such components, which currently is not supported.

get_max_link_width() -> (pcie_link_width_t)

Returns the value of maximum link width

get_max_link_speed() -> (uint4)

Returns the maximum link speed

set_link_attributes(pcie_link_speed_t speed, pcie_link_width_t width)

Sets the status.ls and status.nlw fields.

flit_mode_supported() -> (bool)

Returns flit_mode_supported() of parent (exp_capability). Convenience method to check if Flit Mode is supported without retrieving an instance of exp_capability if an instance of exp_link is available.

flit_mode_disabled() -> (bool)

Returns true the Flit Mode Disable field is set

set_flit_mode_status(bool enabled)

Set the Flit Mode Status field

drs_supported() -> (bool)

Returns true if DRS is supported

send_drs_msg() -> (pcie_error_t)

Sends a Device Ready Status (DRS) message. This method can only be called from function 0 of a Downstream component. The DRS message is sent to the Upstream component.

drs_msg_received() -> (pcie_error_t)

This method can be called when a DRS message is received. It sets the DRS Message Received field and the Downstream Component Presence field in the Link Status 2 register

get_downstream_component_presence() -> (uint3)

Returns the value of the Downstream Component Presence field

set_downstream_component_presence(uint3 value)

Sets the value of the Downstream Component Presence field

PCI Express Capability Slot registers

• name: exp_slot
• implemented: functional

Parameters:

• is_hotplug_capable: Slot is native PCIe Hot-Plug capable, default false
• has_power_indicator: Slot has a power indicator, default false
• has_power_controller: Slot has a power controller, default false
• has_mrl_sensor: Slot has an MRL sensor, default false
• has_command_completions: Slot sends command completed notifications, default false

Methods

presence_change_event(pcie_hotplug_pd_t state) -> (bool)

Sets the presence detect state field to state. If the state has changed, also sets the presence detect changed field and notifies software if applicable. Returns true if event was registered

mrl_sensor_event(pcie_hotplug_mrl_t state) -> (bool)

Sets the MRL sensor state field to state. If the state has changed, also sets the MRL sensor changed field and notifies software if applicable. Returns true if event was registered

data_link_layer_event(bool is_active) -> (bool)

Sets the Data Link Layer Link Active in the link status register to is_active. If this field changes value, also sets the Data Link Layer state changed field in the slot status register and notifies software if applicable. Returns true if event was registered

power_fault_event() -> (bool)

Sets the Power Fault Detected field and notifies software if applicable. Returns true if event was registered

attention_button_event() -> (bool)

Sets the Attention Button Pressed field and notifies software if applicable. Returns true if event was registered

hotplug_event_enabled(int type) -> (bool)

Returns true if slot has Hot-Plug event types of type type enabled. The available types are param:s defined in this file that have the prefix SLOT_ and LINK_.

hotplug_capable(int type)

Returns true if the slot is capable of handling Hot-Plug events of type type. The available types are param:s defined in this file that have the prefix SLOT_ and LINK_.

PCI Express Capability Root registers

• name: exp_root
• implemented: registers only

VPD Capability registers

• name: vpd_capability
• implemented: registers only

Message Signaled Interrupts (MSI) Capability registers

• name: msi_capability
• implemented: functional

Parameters:

• is_64bit_capable: Support 64-bit addresses, i.e. address register is 8 bytes instead of 4.
• is_pvm_capable: Support Per-Vector-Masking, i.e. the mask register is present.
• is_emd_capable: Support extended message data, i.e. the data register is 8 bytes instead of 4.
• num_vectors: The number of interrupt vectors supported.

Methods

signal_all_pending()

Signals all pending MSI's

raise(uint8 i)

Raises MSI i if capable and enabled, and signals it if not masked

lower(uint8 i)

Lowers MSI i

Message Signaled Interrupts X (MSI-X) Capability registers

• name: msix_capability
• implemented: functional

Parameters:

• table_offset_bir: Initial value of the Table Offset/BIR register (at offset 0x4 in the MSI-X capability structure).
• pba_offset_bir: Initial value of the PBA Offset/BIR register (at offset 0x8 in the MSI-X capability structure).
• data_bank: The bank which holds the Table and Pending Bits data, which must use the template msix_table
• num_vectors: Number of interrupt vectors supported.

Methods

raise(uint16 i)

Raises MSI-X i if enabled, and signals it if not masked

lower(uint16 i)

Lowers MSI-X i

msix_table

Template to model the msix table data and pending bits.

Parameters:

• num_vectors: Number of MSI-X vectors
• msix_bank: Bank containing the group instantiating the MSI-X capability.

Subsystem ID and Subsystem Vendor ID Capability registers

• name: ssid_capability
• implemented: registers only

Conventional PCI Advanced Features Capability (AF) registers

• name: af_capability
• implemented: FLR

Enhanced Allocation (EA) Capability registers

• name: ea_capability
• implemented: registers only

Flattening Portal Bridge (FPB) Capability registers

• name: fpb_capability
• implemented: registers only

Fields and access restrictions to be added upon request.

Null Capability registers

• name: null_capability
• implemented: registers only