Skip to content

Commit 0039f24

Browse files
joshuaranjanjoshuaranjan
authored
add apis to support pcie downgrade (#403)
* added extension apis to support pcie downgrade Signed-off-by: Joshua Santosh Ranjan <joshua.santosh.ranjan@intel.com>
1 parent 5494b21 commit 0039f24

File tree

3 files changed

+209
-0
lines changed

3 files changed

+209
-0
lines changed

‎scripts/sysman/EXT_PciLinkSpeedDowngrade.rst‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
<%
2+
import re
3+
from templates import helper as th
4+
%><%
5+
OneApi=tags['$OneApi']
6+
x=tags['$x']
7+
X=x.upper()
8+
s=tags['$s']
9+
S=s.upper()
10+
%>
11+
:orphan:
12+
13+
.. _ZES_extension_pci_link_speed_downgrade:
14+
15+
=======================================
16+
PCI Link Speed Downgrade Extension
17+
=======================================
18+
19+
API
20+
----
21+
22+
* Functions
23+
24+
* ${s}DevicePciLinkSpeedUpdateExt
25+
26+
* Enumerations
27+
28+
* ${s}_pci_link_speed_downgrade_ext_version_t
29+
30+
* Structures
31+
32+
* ${s}_pci_link_speed_downgrade_ext_state_t
33+
* ${s}_pci_link_speed_downgrade_ext_properties_t
34+
35+
PCI Link Speed Downgrade
36+
~~~~~~~~~~~~~~~~~~~~~~~~~
37+
38+
This extension provides the ability to query and update PCIe link speed, enabling downgrade or upgrade (restore to its default speed) of the connection between the device and the host.
39+
40+
Query PCI Link Speed Downgrade Capability
41+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42+
43+
To check if the device supports PCIe link speed downgrade capability, pass ${s}_pci_link_speed_downgrade_ext_properties_t to ${s}DevicePciGetProperties as pNext member of ${s}_pci_properties_t.
44+
45+
.. parsed-literal:
46+
47+
${s}_pci_properties_t pciProperties = {${S}_STRUCTURE_TYPE_PCI_PROPERTIES};
48+
${s}_pci_link_speed_downgrade_ext_properties_t extProperties = {${S}_PCI_LINK_SPEED_DOWNGRADE_EXT_PROPERTIES};
49+
pciProperties.pNext = &extProperties;
50+
${x}_result_t result = ${s}DevicePciGetProperties(hDevice, &pciProperties);
51+
52+
if (extProperties.pciLinkSpeedUpdateCapable) {
53+
// Device supports PCIe link speed update
54+
// maxPciGenSupported indicates the maximum PCIe generation supported
55+
}
56+
57+
Query PCI Link Speed Downgrade Status
58+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59+
60+
To check the current PCIe downgrade status, pass ${s}_pci_link_speed_downgrade_ext_state_t to ${s}DevicePciGetState as pNext member of ${s}_pci_state_t.
61+
62+
.. parsed-literal:
63+
64+
${s}_pci_state_t pciState = {${S}_STRUCTURE_TYPE_PCI_STATE};
65+
${s}_pci_link_speed_downgrade_ext_state_t extState = {${S}_PCI_LINK_SPEED_DOWNGRADE_EXT_STATE};
66+
pciState.pNext = &extState;
67+
${x}_result_t result = ${s}DevicePciGetState(hDevice, &pciState);
68+
69+
if (extState.pciLinkSpeedDowngradeStatus) {
70+
// PCIe link is currently downgraded
71+
} else {
72+
// PCIe link is operating at normal speed
73+
}
74+
75+
Update PCI Link Speed
76+
~~~~~~~~~~~~~~~~~~~~~
77+
78+
To downgrade or set to the default PCIe link speed, use ${s}DevicePciLinkSpeedUpdateExt function.
79+
80+
.. parsed-literal::
81+
82+
${s}_device_action_t pendingAction;
83+
${x}_bool_t shouldDowngrade = true; // true for downgrade
84+
85+
${x}_result_t result = ${s}DevicePciLinkSpeedUpdateExt(hDevice, shouldDowngrade, &pendingAction);
86+
87+
Example Usage
88+
~~~~~~~~~~~~~
89+
90+
The following pseudo-code demonstrates an example Usage for managing PCIe link speed:
91+
92+
.. parsed-literal::
93+
94+
// Step 1: Check if device supports PCIe link speed update
95+
${s}_pci_properties_t pciProperties = {${S}_STRUCTURE_TYPE_PCI_PROPERTIES};
96+
${s}_pci_link_speed_downgrade_ext_properties_t extProperties = {${S}_PCI_LINK_SPEED_DOWNGRADE_EXT_PROPERTIES};
97+
pciProperties.pNext = &extProperties;
98+
99+
if (${s}DevicePciGetProperties(hDevice, &pciProperties) == ${X}_RESULT_SUCCESS) {
100+
if (!extProperties.pciLinkSpeedUpdateCapable) {
101+
// Device does not support PCIe link speed update
102+
return;
103+
}
104+
105+
printf("Max PCIe Gen Supported: %d\\n", extProperties.maxPciGenSupported);
106+
}
107+
108+
// Step 2: Check current downgrade status
109+
${s}_pci_state_t pciState = {${S}_STRUCTURE_TYPE_PCI_STATE};
110+
${s}_pci_link_speed_downgrade_ext_state_t extState = {${S}_PCI_LINK_SPEED_DOWNGRADE_EXT_STATE};
111+
pciState.pNext = &extState;
112+
113+
if (${s}DevicePciGetState(hDevice, &pciState) == ${X}_RESULT_SUCCESS) {
114+
printf("Current downgrade status: %s\\n",
115+
extState.pciLinkSpeedDowngradeStatus ? "Downgraded" : "Normal");
116+
}
117+
118+
// Step 3: Perform downgrade
119+
${s}_device_action_t pendingAction;
120+
${x}_result_t result = ${s}DevicePciLinkSpeedUpdateExt(hDevice, true, &pendingAction);
121+
122+
if (result == ${X}_RESULT_SUCCESS) {
123+
printf("PCIe link speed downgrade initiated\\n");
124+
printf("Required action: %d\\n", pendingAction);
125+
}

‎scripts/sysman/common.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -265,6 +265,14 @@ etors:
265265
value: "0x00020012"
266266
desc: $s_device_ecc_default_properties_ext_t
267267
version: "1.13"
268+
- name: PCI_LINK_SPEED_DOWNGRADE_EXT_STATE
269+
value: "0x00020013"
270+
desc: $s_pci_link_speed_downgrade_ext_state_t
271+
version: "1.15"
272+
- name: PCI_LINK_SPEED_DOWNGRADE_EXT_PROPERTIES
273+
value: "0x00020014"
274+
desc: $s_pci_link_speed_downgrade_ext_properties_t
275+
version: "1.15"
268276
--- #-------------------------------------------------------------------------
269277
type: struct
270278
desc: "Base for all properties types"

‎scripts/sysman/pciLinkSpeedDowngrade.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
#
2+
# Copyright (C) 2025 Intel Corporation
3+
#
4+
# SPDX-License-Identifier: MIT
5+
#
6+
# See YaML.md for syntax definition
7+
#
8+
--- #--------------------------------------------------------------------------
9+
type: header
10+
desc: "Intel $OneApi Level-Zero Sysman Extension APIs for PCI Link Speed Downgrade"
11+
version: "1.15"
12+
--- #--------------------------------------------------------------------------
13+
type: macro
14+
desc: "PCI Link Speed Downgrade Extension Name"
15+
version: "1.15"
16+
name: $S_PCI_LINK_SPEED_DOWNGRADE_EXT_NAME
17+
value: '"$XS_extension_pci_link_speed_downgrade"'
18+
--- #--------------------------------------------------------------------------
19+
type: enum
20+
desc: "PCI Link Speed Downgrade Extension Version(s)"
21+
version: "1.15"
22+
name: $s_pci_link_speed_downgrade_ext_version_t
23+
etors:
24+
- name: "1_0"
25+
value: "$X_MAKE_VERSION( 1, 0 )"
26+
desc: "version 1.0"
27+
--- #--------------------------------------------------------------------------
28+
type: struct
29+
desc: "Query PCIe downgrade status."
30+
version: "1.15"
31+
class: $sDevice
32+
name: $s_pci_link_speed_downgrade_ext_state_t
33+
base: $s_base_state_t
34+
members:
35+
- type: $x_bool_t
36+
name: pciLinkSpeedDowngradeStatus
37+
desc: "[out] Returns the current PCIe downgrade status."
38+
details:
39+
- "This structure can be passed in the 'pNext' of $s_pci_state_t"
40+
--- #--------------------------------------------------------------------------
41+
type: struct
42+
desc: "Query PCIe downgrade capability."
43+
version: "1.15"
44+
class: $sDevice
45+
name: $s_pci_link_speed_downgrade_ext_properties_t
46+
base: $s_base_properties_t
47+
members:
48+
- type: $x_bool_t
49+
name: pciLinkSpeedUpdateCapable
50+
desc: "[out] Returns if PCIe downgrade capability is available."
51+
- type: int32_t
52+
name: maxPciGenSupported
53+
desc: "[out] Returns the max supported PCIe generation of the device. -1 indicates the information is not available"
54+
details:
55+
- "This structure can be passed in the 'pNext' of $s_pci_properties_t"
56+
--- #--------------------------------------------------------------------------
57+
type: function
58+
desc: "Update PCI Link Speed (Downgrade or Upgrade (restore to its default speed))"
59+
version: "1.15"
60+
class: $sDevice
61+
name: PciLinkSpeedUpdateExt
62+
details:
63+
- "This function allows updating the PCI link speed to downgrade or upgrade (restore to its default speed) the connection."
64+
params:
65+
- type: $s_device_handle_t
66+
name: hDevice
67+
desc: "[in] Sysman handle of the device."
68+
- type: $x_bool_t
69+
name: shouldDowngrade
70+
desc: "[in] boolean value to decide whether to perform PCIe downgrade(true) or set to default speed(false)"
71+
- type: $s_device_action_t*
72+
name: pendingAction
73+
desc: "[out] Pending action"
74+
returns:
75+
- $X_RESULT_ERROR_INSUFFICIENT_PERMISSIONS:
76+
- "User does not have permissions to perform this operation."

0 commit comments

Comments
 (0)