2 * The PCI Utilities -- Margining utility main header
4 * Copyright (c) 2023 KNS Group LLC (YADRO)
6 * Can be freely distributed and used under the terms of the GNU GPL v2+.
8 * SPDX-License-Identifier: GPL-2.0-or-later
17 #include "lib/bitops.h"
19 #define MARGIN_STEP_MS 1000
21 #define MARGIN_TIM_MIN 20
22 #define MARGIN_TIM_RECOMMEND 30
23 #define MARGIN_VOLT_MIN 50
25 enum margin_hw { MARGIN_HW_DEFAULT, MARGIN_ICE_LAKE_RC };
27 /* PCI Device wrapper for margining functions */
37 /* Saved Device settings to restore after margining */
39 bool hasd; // Hardware Autonomous Speed Disable
40 bool hawd; // Hardware Autonomous Width Disable
44 struct margin_dev down_port;
45 struct margin_dev up_port;
48 /* Specification Revision 5.0 Table 8-11 */
49 struct margin_params {
50 bool ind_error_sampler;
51 bool sample_report_method;
52 bool ind_left_right_tim;
53 bool ind_up_down_volt;
68 /* Step Margin Execution Status - Step command response */
69 enum margin_step_exec_sts {
70 MARGIN_NAK = 0, // NAK/Set up for margin
71 MARGIN_LIM, // Too many errors (device limit)
72 MARGIN_THR // Test threshold has been reached
75 enum margin_dir { VOLT_UP = 0, VOLT_DOWN, TIM_LEFT, TIM_RIGHT };
77 /* Margining results of one lane of the receiver */
78 struct margin_res_lane {
81 enum margin_step_exec_sts statuses[4];
84 /* Reason not to run margining test on the Link/Receiver */
85 enum margin_test_status {
87 MARGIN_TEST_READY_BIT,
92 MARGIN_TEST_ARGS_LANES,
93 MARGIN_TEST_ARGS_RECVS,
97 /* All lanes Receiver results */
98 struct margin_results {
99 u8 recvn; // Receiver Number
100 struct margin_params params;
104 enum margin_test_status test_status;
106 /* Used to convert steps to physical quantity.
107 Calculated from MaxOffset and NumSteps */
111 bool tim_off_reported;
112 bool volt_off_reported;
115 struct margin_res_lane *lanes;
118 /* pcilmr arguments */
120 u8 steps_t; // 0 == use NumTimingSteps
121 u8 steps_v; // 0 == use NumVoltageSteps
122 u8 parallel_lanes; // [1; MaxLanes + 1]
123 u8 error_limit; // [0; 63]
124 u8 recvs[6]; // Receivers Numbers
125 u8 recvs_n; // 0 == margin all available receivers
126 u8 lanes[32]; // Lanes to Margin
127 u8 lanes_n; // 0 == margin all available lanes
128 bool run_margin; // Or print params only
129 u8 verbosity; // 0 - basic;
130 // 1 - add info about remaining time and lanes in progress during margining
132 u64 *steps_utility; // For ETA logging
135 /* Receiver structure */
137 struct margin_dev *dev;
138 u8 recvn; // Receiver Number
140 struct margin_params *params;
146 struct margin_lanes_data {
147 struct margin_recv *recv;
149 struct margin_res_lane *results;
165 /* Verify that devices form the link with 16 GT/s or 32 GT/s data rate */
166 bool margin_verify_link(struct pci_dev *down_port, struct pci_dev *up_port);
168 /* Check Margining Ready bit from Margining Port Status Register */
169 bool margin_check_ready_bit(struct pci_dev *dev);
171 /* Verify link and fill wrappers */
172 bool margin_fill_link(struct pci_dev *down_port, struct pci_dev *up_port,
173 struct margin_link *wrappers);
175 /* Disable ASPM, set Hardware Autonomous Speed/Width Disable bits */
176 bool margin_prep_link(struct margin_link *link);
178 /* Restore ASPM, Hardware Autonomous Speed/Width settings */
179 void margin_restore_link(struct margin_link *link);
183 /* Fill margin_params without calling other functions */
184 bool margin_read_params(struct pci_access *pacc, struct pci_dev *dev, u8 recvn,
185 struct margin_params *params);
187 enum margin_test_status margin_process_args(struct margin_dev *dev, struct margin_args *args);
189 /* Awaits that args are prepared through process_args.
190 Returns number of margined Receivers through recvs_n */
191 struct margin_results *margin_test_link(struct margin_link *link, struct margin_args *args,
194 void margin_free_results(struct margin_results *results, u8 results_n);
198 extern bool margin_global_logging;
199 extern bool margin_print_domain;
201 void margin_log(char *format, ...);
204 void margin_log_bdfs(struct pci_dev *down_port, struct pci_dev *up_port);
206 /* Print Link header (bdfs, width, speed) */
207 void margin_log_link(struct margin_link *link);
209 void margin_log_params(struct margin_params *params);
211 /* Print receiver number */
212 void margin_log_recvn(struct margin_recv *recv);
214 /* Print full info from Receiver struct */
215 void margin_log_receiver(struct margin_recv *recv);
217 /* Margining in progress log */
218 void margin_log_margining(struct margin_lanes_data arg);
220 void margin_log_hw_quirks(struct margin_recv *recv);
224 void margin_results_print_brief(struct margin_results *results, u8 recvs_n);
226 void margin_results_save_csv(struct margin_results *results, u8 recvs_n, char *dir,
227 struct pci_dev *up_port);