These are templates for PCIe Extended 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 extended capability template uses the following parameters:
base: Base address of the capability headernext_ptr: Value of the next_ptr field in the capability headeraer_capabilityNote that the methods in this capability are mainly intended to be called by
the error signaling implementation part of the
pcie_error_reporter template.
Uses the following parameters:
has_root_registers: The capability includes root registers, default true
tlp_prefix_log_or_header_log_ctd_len: The length in DWs of the TLP
Prefix Log or Header Log (continued, for Flit mode) register, default 4
### get_uncorrectable_error_severity(pcie_uncorrectable_error_t err) -> (pcie_error_severity_t)
Returns the severity of an uncorrectable error as defined in the AER
capability instance.
Registers a correctable error in the AER capability instance. Throws if the error is invalid.
Returns whether a correctable error is masked in the AER capability. Throws if the error is invalid.
Registers an uncorrectable error in the AER capability instance. Throws if the error is invalid.
Registers an uncorrectable advisory non fatal error in the AER capability instance. Throws if the error is invalid.
Returns whether an uncorrectable error is masked in the AER capability. Throws if the error is invalid.
Reports a correctable root error in the AER capability instance. This is
only applicable for root ports. rid is the requester id of the issuer
of the error message that has reached the root port and ecs is the
ERR_COR Subclass.
Reports an uncorrectable root error in the AER capability instance. This is
only applicable for root ports. rid is the requester id of the issuer
of the error message that has reached the root port.
Returns the size of the header log in DWs.
Log a TLP in the AER capability instance. This method will check if the
entry to log is of type flit or non-flit and call the appropriate log
method (log_flit_tlp() or
log_non_flit_tlp()).
If the log is full, a correctable error of type Header Log Overflow will
be submitted.
Log a Flit based TLP in the AER capability instance.If the log is full, a correctable error of type Header Log Overflow will be submitted.
Log a non-Flit based TLP in the AER capability instance.If the log is, full a correctable error of type Header Log Overflow will be submitted.
This method clears the log but should not be called by the user unless custom logic in addition to what is provided in this library has been introduced that justifies calling this method.
vc_capabilitydsn_capabilitydpb_capabilityrcld_capabilityUses the following parameters:
num_links: number of links.rcilc_capabilityrcecea_capabilityUses the following parameters:
version: version number of this capability, default 2mfvc_capabilityrcrb_capabilityvsec_capabilityacs_capabilityari_capabilityats_capabilityThis is a partially functional template; the user must implement the method
invalidate_received.
invalidate_received(transaction_t *t, uint64 addr) -> (bool)Called by the standard PCIe templates when an ATS Invalidate message
is received. The default implementation logs an unimpl message and
returns false, indicating a ‘Completer Abort’.
translation_request(unint64 addr, pcie_ats_translation_completion_entry_t *entries, int nbr_entries, const pcie_pasid_info_t *pasid, bool no_write, bool cxl_src)-> (pcie_error_t, int)Issue a translation request to Translation Agent (TA).
Set pasid to NULL to exclude the pcie_pasid atom in the transaction.
Returns error status and number of valid completion entries
the TA has filled in.
translation_request_custom(unint64 addr, pcie_ats_translation_completion_entry_t *entries, int nbr_entries, const pcie_pasid_info_t *pasid, bool no_write, bool cxl_src, atom_t *extra_atoms)-> (pcie_error_t, int)A variant of
translation_request()
that allows the user to add custom atoms to the transaction. The
extra_atoms parameter is a list of atoms to be added to the
transaction. The list must be terminated with ATOM_list_end(0).
translation_size_to_entries(uint64 size) -> (uint64)Calculates the maximum number of translation completion entries required
for TA to cover the requested translation of size.
get_translation_range(pcie_ats_translation_completion_entry_t entry) -> (uint64, uint64)Decodes the completion entry and returns the translated address
and the size of the translated region.
get_invalidation_range(pcie_ats_invalidate_request_payload_t payload) -> (uint64, uint64)Decodes the invalidation request message and returns the untranslated address
and the size of the untranslated region.
invalidate_complete(uint64 destination_id, uint32 itag_vector) -> (pcie_error_t)Sends the invalidation message to TA found at B:D:F destination_id.
Returns PCIE_Error_No_Error on success.
memory_read_buf(buffer_t buf, uint64 addr, pcie_at_t at, const pcie_pasid_info_t *pasid) -> (pcie_error_t)Performs an ATS Translated/Untranslated Memory Read.
The input argument at specifies which AT type. Input argument pasid
contains PASID, set to NULL to exclude the pcie_pasid atom in
the transaction. Returns a pcie_error_t.
Requires that an upstream_target is defined.
Should only be used with at set to: PCIE_AT_Untranslated
or PCIE_AT_Translated.
memory_read_custom(buffer_t buf, uint64 addr, pcie_at_t at, const pcie_pasid_info_t *pasid, atom_t *extra_atoms) -> (pcie_error_t)A variant of
memory_read_buf()
that allows the user to add custom atoms to the transaction. The
extra_atoms parameter is a list of atoms to be added to the
transaction. The list must be terminated with ATOM_list_end(0).
memory_write_bytes(bytes_t bytes, uint64 addr, pcie_at_t at, const pcie_pasid_info_t *pasid) -> (pcie_error_t)Performs an ATS Translated/Untranslated Memory Write.
The input argument at specifies which AT type. Input argument pasid
contains PASID, set to NULL to exclude the pcie_pasid atom in
the transaction. Returns a pcie_error_t.
Requires that an upstream_target is defined.
Should only be used with at set to: PCIE_AT_Untranslated
or PCIE_AT_Translated.
memory_write_custom(bytes_t bytes, uint64 addr, pcie_at_t at, const pcie_pasid_info_t *pasid, atom_t *extra_atoms) -> (pcie_error_t)A variant of
memory_write_bytes()
that allows the user to add custom atoms to the transaction. The
extra_atoms parameter is a list of atoms to be added to the
transaction. The list must be terminated with ATOM_list_end(0).
mc_capabilityprs_capabilitypage_group_response_received has to be overridden with device logic. Registers status and alloc has to be implemented if required.page_request(pcie_prs_page_request_t request, const pcie_pasid_info_t *pasid) -> (pcie_error_t)Sends a Page Request message. Input argument pasid
contains PASID, set to NULL to exclude the pcie_pasid atom in
the transaction.
send_stop_marker(const pcie_pasid_info_t *pasid) -> (pcie_error_t)Sends a stop marker message upstream. Input argument pasid
contains PASID, set to NULL to exclude the pcie_pasid atom from
the transaction.
page_response_received(transaction_t *t, uint64 addr) -> (bool)Called by the standard PCIe templates when a Page Response message is
received. The default implementation logs an unimpl message and
returns false.
rbar_capabilityThe standard PCIe templates for Base Address Registers automatically find and use the size configured in instances of this template, when enabled.
Uses the following parameters:
num_bars: Number of resizable bars present in this capability.bar_indexes: list of integers, setting init_val of control.id field for each RBARbar_capabilities: list of integers, setting init_val of capability register for each RBARvf_rbar_capabilityThis template works just like the Resizable Bar (RBAR) template, but is detected and used by the standard PCIe templates for Virtual Function Base Address Registers instead.
dpa_capabilityUses the following parameters:
num_substates: number of power allocation registers, default 1tph_capabilityUses the following parameters:
num_tables: number of TPH ST Table registers, default 1ltr_capabilityspe_capabilityUses the following parameters:
max_link_width: number of Equalization Control registers, no defaultpasid_capabilityVerifies that the PASID capability is configured correctly
to support the contents of the pasid argument.
If the check fails it is considered a modelling error.
Returns true on success.
Verifies that the PASID capability is configured correctly
to support the contents of the pasid argument and the type of argument at.
If the check fails is considered a modelling error.
Returns true on success.
lnr_capabilitydpc_capabilityUses the following parameters:
root_port: presence of PIO registers, default falsel1pms_capabilityFields to be added upon request.
ptm_capabilityFields to be added upon request
mpcie_capabilityfrsq_capabilityFields to be added upon request
rtr_capabilityFields to be added upon request
dlf_capabilitypl16g_capabilityUses the following parameters:
max_link_width: maximum link width, no defaultmax_lanes: maximum number of lanes, no defaultlmar_capabilityUses the following parameters:
max_lanes: number of lane control and status registers, no defaultpl32g_capabilityUses the following parameters:
max_link_width: maximum link width, no defaultmax_lanes: maximum number of lanes, no defaultpl64g_capabilityUses the following parameters:
max_link_width: maximum link width, no defaultmax_lanes: maximum number of lanes, no defaultdvsec_capabilityhid_capabilitynpem_capabilityap_capabilityFields to be added upon request
Fields and access restrictions to be added upon request
sriov_capabilityThis is a partially functional template; users must implement the methods
get_offset and get_stride, create an array of DML-objects that simulate
the configuration header for each virtual function, and add instances of the
vf_base_address template for each VF BAR that is implemented by the
physical function.
Uses the following parameters:
virtual_functions: A sequence of vf_type_0_bank objects simulating the
virtual functions.get_offset() -> (uint16)
Returns the offset to the first virtual function, must be implemented by the user.
get_stride() -> (uint16)
Returns the stride between virtual functions, must be implemented by the user.
dev3_capabilityfl_capabilityfpm_capabilityUses the following parameters:
n_lpms: Number of LTSSM Performance Measurement Status Registers, no defaultfei_capabilitysf_capabilityUses the following parameters:
n_sfi: Number of Shadow Functions Instance Registers, no defaultdoe_capabilityUses the following parameters:
mailbox_len: Length of request and response mailboxinterrupt_support: Use interrupts for DOE related eventsmethod response_ready(uint18 res_len)
This method should be called when the incoming DOE request has been finnished processing. This means that if the request requires a response, that should have been written to the provided response buffer. In the case where no response is needed, or silently discarding the request is desried, this method should still be called but with \p res_len set to 0.
@note After this method has been called, neither the request or the response buffer should be accessed.
@note only one of response_error() and response_ready() should be
called during the processing of a DOE request.
@param[in] res_len The length of the response
method response_error()
This method should be called when an internal error has been encountered during processing of the DOE request.
@note After this method has been called, neither the request or the response buffer should be accessed.
@note only one of response_error() and response_ready() should be
called during the processing of a DOE request.
shared method doe_abort()
This method can optionally be overridden to handle scenarios where doe
requests are aborted.
shared method doe_get_dimn() -> (uint11)
This method can optionally be overridden to control the value of the
“DOE Interrupt Message Number” (dimn) bits. This provides the flexability
to check the “Multiple Message Enable” bits in MSI for example, or other
things might affect what the value of the dimn bits.
template doe_protocolThe doe_protocol template should be used to define user-defined DOE protocols. These should be added to a doe_capability instance accordingly. The way this is done is by adding them to the protocols group in the doe_capability. Example:
template doe_custom_protocol is doe_protocol {
param vendor_id = 0x1234;
param data_object_type = 0;
shared method handle_request(const uint32 *req, uint18 req_len) {
return 0;
}
}
bank pcie_config {
...
is defining_doe_capability;
group doe {
group protocols {
group custom_protocol is doe_custom_protocol;
}
}
...
}
shared method handle_request(const uint32 *req, uint18 req_len_dw);The implementation of this abstract method should handle a DOE request for
the implemented protocol. This method must at some point (or schedule an
event that at some point) call the method response_ready(res, res_len) (
or response_error() which is defined in the instantiating template
doe_capability. This should be done when the response has been written to
the mailbox fifo. The call should contain the length of the response.
@param[in] res The request buffer
@param[in] req_len The length of the request
ide_capabilitynull_capability_extvf_type_0_bankCan be used to implement Virtual Functions, used by SR-IOV capability.
Inherits the config_bank template. Note that this template must use the
vf_base_address template to implement its Base Address Registers.
vf_base_addressCan be used to implement Base Address Registers in the SR-IOV capability
header. Inherits the template memory_base_address.
Users of this template must implement the method get_vf_bar_map.
get_vf_bar_map(uint64 vf_number) -> (conf_object_t *) throwsReturns the mapped object corresponding to the specified virtual function number. Throws if an invalid vf_number is supplied.