Config Space Exporting Functions

This group of functions enables the VSE to retrieve Configuration Space Adapter information.

GetTopologyList()

Returns the list of available topologies in the opened trace file.

GetTopologyList()

Return Values

Returns the list of the topology Id values available in the current trace file.

Example

topology_list = GetTopologyList();

GetTopologyListSize()

Returns the size of available topology id list returned by the GetTopologyList() function.

GetTopologyListSize()

Return Values

Size of the topology ids list obtained by the GetTopologyList() function..

Example

topology_list = GetTopologyList();
topology_list_size = GetTopologyListSize();
str = "Available topology ids: "
for(index = 0; index < topology_list_size; index++)
{
  str += Format(“0x%8x “, topology_list[index]);
}

GetAdaptersList()

Returns the list of adapter numbers obtained for a particular topology id.

GetAdaptersList( topology_id )

Return Values

List of adapter numbers for a particular topology id. Note that adapter number 0 is not included in the returned list. If topology_id is absent in the trace file, returns the empty adapter number list.

Example

adapter_num_list = GetAdaptersList( topology_id );

GetAdaptersListSize()

Returns the size of the adapter number list returned by GetAdaptersList().

GetAdaptersListSize( topology_id )

Return Values

The size of an adapter number list obtained by GetAdaptersList() for a particular topology_id. If topology_id is absent in the trace file, function returns 0.

Example

adapters_list = GetAdaptersList(topology_id);
list_size = GetAdaptersListSize(topology_id);
str = "Available adapter numbers: "
for(index = 0; index < list_size; index++)
{
  str += Format(“%8d “, adapters_list[index]);
}

GetCapabilityStartAddress()

Extracts the start address of a specific capability in an adapter.

GetCapabilityStartAddress( topology_id, adapter_num, config_space, capability_id );

Return Value

Returns the start address of the capability. Returns 0 if the parameters are invalid, the capability is not defined for the adapter, the capability's start address does not exist in the current trace file, or the trace file does not contain adapter configuration space information.

Example

FindUpstreamLane0Adapter()
{
    if (in.TraceEvent != _USB4_HS_READ_RESPONSE ||
        (in.RouteStringHigh_TopologyID & 0x7FFFFFFF) != 0 ||
        (in.RouteStringLow_TopologyID & 0xFFFFFF00) != 0 ||
        in.CS != USB4_ROUTER_CFG ||
        in.Address != 0 ||
        in.DataSize < 2) {
        return 0;
    }

    ufp_adp_num = in.Data5 & 0x3F;
    ReportText(FormatEx("Found UFP Lane 0 Adapter: %d, Packet Number: %d",
        ufp_adp_num, in.Index));

    return ufp_adp_num;
}
FindCapAddress(adp_num, cap)
{
    tp_id = in.RouteStringHigh_TopologyID << 32 | in.RouteStringLow_TopologyID;
    cfg_space = USB4_ADAPTER_CFG;
    if (adp_num == 0) {
        cfg_space = USB4_ROUTER_CFG;
    }

    cap_adr = GetCapabilityStartAddress(tp_id, adp_num, cfg_space, cap);

    ReportText(FormatEx("Found 0x%02X Capability, Topology: 0x%x, Adapter: %d, Address: 0x%x",
        cap, tp_id, adp_num, cap_adr));
    return cap_adr;
}

set USB4_CFG_CAP_TMU    = 0x03;
set USB4_CFG_CAP_LANE   = 0x01;
set USB4_CFG_CAP_USB4   = 0x06;
set USB4_CFG_CAP_TUNL   = 0x04;

ProcessEvent()
{
    if (!UpstreamLane0Adapter) {
        UpstreamLane0Adapter = FindUpstreamLane0Adapter();
        if (UpstreamLane0Adapter) {
            RouterTMUCapAddress = FindCapAddress(0, USB4_CFG_CAP_TMU);
            LaneTMUCapAddress = FindCapAddress(UpstreamLane0Adapter, USB4_CFG_CAP_TMU);
            LaneCapAddress = FindCapAddress(UpstreamLane0Adapter, USB4_CFG_CAP_LANE);
        }
    }
    ...
}

GetAdapterCapabilityStartAddresses()

Extracts the list of adapter capability start addresses for a particular adapter number and topology id.

GetAdapterCapabilityStartAddresses( topology_id, adapter_num );

Return Values

A list of capability start addresses for the adapter with a number equal to adapter_num and which belongs to the topology identifying by topology_id. If passed topology_id or adapter_num do not exist in the current trace file or trace file does not contain adapter configuration space info, function returns an empty list.

Example

address_list = GetAdapterCapabilityStartAddresses( topology_id, adapter_num );

GetAdapterCapabilityStartAddressesListSize()

Extracts the size of adapter capability start address list returned by GetAdapterCapabilityStartAddresses().

GetAdapterCapabilityStartAddressesListSize( topology_id, adapter_num );

Return Values

The size of capability start addresses list for adapter_num which belongs to the topology identifed by topology_id. If passed topology_id or adapter_num do not exist in the current trace file or trace file does not contain adapter configuration space info, function returns 0.

Example

size = GetAdapterCapabilityStartAddressesListSize( topology_id, adapter_num );

GetAdapterCapabilityID()

Extracts the capability id from the adapter configuration space field identified by the topology id, adapter number, and field address.

GetAdapterCapabilityID( topology_id, adapter_num, start_addr );

Return Values

Capability id for the configuration space of the adapter belonging to particular topology id and which is addressed in configuration space by the start_addr. If passed adapter number and topology id do not exist in trace file, or trace file does not contain configuration space info or start_addr is invalid, this function returns -1.

Example

Capability_id = GetAdapterCapabilityID( topology_id, adapter_num, start_addr );

GetAdapterCapabilityName()

Extracts a string representation of capability from the adapter configuration space field, which is identified by passed address.

GetAdapterCapabilityName( topology_id, adapter_num, start_addr );

Return Values

Capability name extracted from adapter configuration space registry field addressed by start_addr. If passed topology_id or adapter number are missed in trace file, or trace file does not contain configuration space information, or decoded capability id from registry field addressed in configuration space by start_addr is invalid, function will return “Undefined Capability”.

Example

Capability_name = GetAdapterCapabilityName(topology_id,adapter_num, start_addr);

GetAdapterCapabilityData()

Extracts the raw registry field value from particular adapter capability. The requested field value in capability registers is identified by data_offset, capability in adapter configuration space is addressed by start_addr, requested adapter is identified by adapter number and topology id.

GetAdapterCapabilityData( topology_id, adapter_num, start_addr, data_offset );

Return Values

Raw value of capability registry field addressed by data_offset where the desired adapter capability is given a start_addr in the adapter configuration space. If the passed adapter number or topology id are absent in trace file, or capability start_addr is invalid, or data_offset is exceed the capability registry size, or requested capability registry field is unknown or has not been initialized, the function returns -1.

Example

capability_data = GetAdapterCapabilityData(topology_id,adapter_num, start_addr, data_offset);