xref: /aosp_15_r20/external/coreboot/src/vendorcode/cavium/include/bdk/libbdk-hal/qlm/bdk-qlm-common.h (revision b9411a12aaaa7e1e6a6fb7c5e057f44ee179a49c)
1 /***********************license start***********************************
2 * Copyright (c) 2003-2017  Cavium Inc. ([email protected]). All rights
3 * reserved.
4 *
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
9 *
10 *   * Redistributions of source code must retain the above copyright
11 *     notice, this list of conditions and the following disclaimer.
12 *
13 *   * Redistributions in binary form must reproduce the above
14 *     copyright notice, this list of conditions and the following
15 *     disclaimer in the documentation and/or other materials provided
16 *     with the distribution.
17 *
18 *   * Neither the name of Cavium Inc. nor the names of
19 *     its contributors may be used to endorse or promote products
20 *     derived from this software without specific prior written
21 *     permission.
22 *
23 * This Software, including technical data, may be subject to U.S. export
24 * control laws, including the U.S. Export Administration Act and its
25 * associated regulations, and may be subject to export or import
26 * regulations in other countries.
27 *
28 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
29 * AND WITH ALL FAULTS AND CAVIUM INC. MAKES NO PROMISES, REPRESENTATIONS OR
30 * WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT
31 * TO THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY
32 * REPRESENTATION OR DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT
33 * DEFECTS, AND CAVIUM SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES
34 * OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR
35 * PURPOSE, LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT,
36 * QUIET POSSESSION OR CORRESPONDENCE TO DESCRIPTION. THE ENTIRE  RISK
37 * ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
38 ***********************license end**************************************/
39 #ifndef __BDK_QLM_COMMON_H__
40 #define __BDK_QLM_COMMON_H__
41 
42 /* Common QLM code for Thunder based processors. The following chips
43     use the same style SERDES, using the code defined in this header.
44         CN88XX
45         CN83XX
46 */
47 
48 /* These constants represent the possible QLM reference clock speeds in Hz */
49 #define REF_100MHZ 100000000
50 #define REF_125MHZ 125000000
51 #define REF_156MHZ 156250000
52 
53 /**
54  * Figure out which lane mode to use for a given reference clock and GBaud
55  *
56  * @param mode_name String name for error messages
57  * @param qlm       QlM being configured
58  * @param ref_clk   Reference clock in hertz
59  * @param baud_mhz  Baud rate in Mhz
60  *
61  * @return Lane mode or -1 on failure
62  */
63 extern int __bdk_qlm_get_lane_mode_for_speed_and_ref_clk(const char *mode_name, int qlm, int ref_clk, int baud_mhz);
64 
65 /**
66  * Setup the PEM to either driver or receive reset from PRST based on RC or EP
67  *
68  * @param node   Node to use in a Numa setup
69  * @param pem    Which PEM to setuo
70  * @param is_endpoint
71  *               Non zero if PEM is a EP
72  */
73 extern void __bdk_qlm_setup_pem_reset(bdk_node_t node, int pem, int is_endpoint);
74 
75 /**
76  * Measure the reference clock of a QLM
77  *
78  * @param qlm    QLM to measure
79  *
80  * @return Clock rate in Hz
81  */
82 extern int __bdk_qlm_measure_refclock(bdk_node_t node, int qlm);
83 
84 /**
85  * Put a QLM into hardware reset
86  *
87  * @param node   Node to use in a numa setup
88  * @param qlm    QLM to use
89  *
90  * @return Zero on success, negative on failure
91  */
92 extern int __bdk_qlm_reset(bdk_node_t node, int qlm);
93 
94 /**
95  * Enable PRBS on a QLM
96  *
97  * @param node   Node to use in a numa setup
98  * @param qlm    QLM to use
99  * @param prbs   PRBS mode (31, etc)
100  * @param dir    Directions to enable. This is so you can enable TX and later
101  *               enable RX after TX has run for a time
102  *
103  * @return Zero on success, negative on failure
104  */
105 extern int __bdk_qlm_enable_prbs(bdk_node_t node, int qlm, int prbs, bdk_qlm_direction_t dir);
106 
107 /**
108  * Disable PRBS on a QLM
109  *
110  * @param node   Node to use in a numa setup
111  * @param qlm    QLM to use
112  *
113  * @return Zero on success, negative on failure
114  */
115 extern int __bdk_qlm_disable_prbs(bdk_node_t node, int qlm);
116 
117 /**
118  * Return the number of PRBS errors since PRBS started running
119  *
120  * @param node   Node to use in numa setup
121  * @param qlm    QLM to use
122  * @param lane   Which lane
123  * @param clear  Clear counter after return the current value
124  *
125  * @return Number of errors
126  */
127 extern uint64_t __bdk_qlm_get_prbs_errors(bdk_node_t node, int qlm, int lane, int clear);
128 
129 /**
130  * Inject an error into PRBS
131  *
132  * @param node   Node to use in numa setup
133  * @param qlm    QLM to use
134  * @param lane   Which lane
135  */
136 extern void __bdk_qlm_inject_prbs_error(bdk_node_t node, int qlm, int lane);
137 
138 /**
139  * Enable shallow loopback on a QLM
140  *
141  * @param node   Node to use in a numa setup
142  * @param qlm    QLM to use
143  * @param loop   Type of loopback. Not all QLMs support all modes
144  *
145  * @return Zero on success, negative on failure
146  */
147 extern int __bdk_qlm_enable_loop(bdk_node_t node, int qlm, bdk_qlm_loop_t loop);
148 
149 /**
150  * Initialize the QLM mode table
151  *
152  * @param node    Node to initialize
153  * @param qlm     Which QLM
154  * @param ref_clk Reference clock of the QLM in Hz
155  */
156 extern void __bdk_qlm_init_mode_table(bdk_node_t node, int qlm, int ref_clk);
157 
158 /**
159  * Given a valid PEM number, return its speed in Gbaud
160  *
161  * @param node   Node to use in numa setup
162  * @param pem    PEM to get speed of
163  *
164  * @return Speed in Gbaud. Zero if disabled
165  */
166 extern int __bdk_qlm_get_gbaud_mhz_pem(bdk_node_t node, int pem);
167 
168 /**
169  * Get the speed of a QLM using its LMODE. This can't be used on PCIe QLMs.
170  *
171  * @param node   Node to use in numa setup
172  * @param qlm    Which QLM
173  *
174  * @return QLM speed on Gbaud
175  */
176 extern int __bdk_qlm_get_gbaud_mhz_lmode(bdk_node_t node, int qlm);
177 
178 /**
179  * Converts a measured reference clock to a likely ideal value. Rounds
180  * clock speed to the nearest REF_*Mhz define.
181  *
182  * @param node   Node to use in numa setup
183  * @param qlm    Which QLM
184  * @param measured_hz
185  *               Measured value
186  *
187  * @return Value exactly matching a define
188  */
189 extern int __bdk_qlm_round_refclock(bdk_node_t node, int qlm, int measured_hz);
190 
191 /**
192  * For Cavium EVB and EBB board, query the MCU to determine the QLM setup. Applying
193  * any configuration found.
194  *
195  * @param node   Node to configure
196  *
197  * @return Zero on success, negative on failure
198  */
199 extern int bdk_qlm_mcu_auto_config(bdk_node_t node);
200 
201 /**
202  * Display the current settings of a QLM lane
203  *
204  * @param node     Node the QLM is on
205  * @param qlm      QLM to display
206  * @param qlm_lane Lane to use
207  * @param show_tx  Display TX parameters
208  * @param show_rx  Display RX parameters
209  */
210 extern void bdk_qlm_display_settings(bdk_node_t node, int qlm, int qlm_lane, bool show_tx, bool show_rx);
211 
212 /**
213  * Perform RX equalization on a QLM
214  *
215  * @param node     Node the QLM is on
216  * @param qlm      QLM to perform RX equalization on
217  * @param qlm_lane Lane to use, or -1 for all lanes
218  *
219  * @return Zero on success, negative if any lane failed RX equalization
220  */
221 extern int __bdk_qlm_rx_equalization(bdk_node_t node, int qlm, int qlm_lane);
222 
223 /**
224  * Configure the TX tuning parameters for a QLM lane. The tuning parameters can
225  * be specified as -1 to maintain their current value
226  *
227  * @param node      Node to configure
228  * @param qlm       QLM to configure
229  * @param lane      Lane to configure
230  * @param tx_swing  Transmit swing (coef 0) Range 0-31
231  * @param tx_pre    Pre cursor emphasis (Coef -1). Range 0-15
232  * @param tx_post   Post cursor emphasis (Coef +1). Range 0-31
233  * @param tx_gain   Transmit gain. Range 0-7
234  * @param tx_vboost Transmit voltage boost. Range 0-1
235  *
236  * @return Zero on success, negative on failure
237  */
238 extern int __bdk_qlm_tune_lane_tx(bdk_node_t node, int qlm, int lane, int tx_swing, int tx_pre, int tx_post, int tx_gain, int tx_vboost);
239 
240 /**
241  * Some QLM speeds need to override the default tuning parameters
242  *
243  * @param node     Node to use in a Numa setup
244  * @param qlm      QLM to configure
245  * @param mode     Desired mode
246  * @param baud_mhz Desired speed
247  */
248 extern void __bdk_qlm_tune(bdk_node_t node, int qlm, bdk_qlm_modes_t mode, int baud_mhz);
249 
250 /**
251  * Capture an eye diagram for the given QLM lane. The output data is written
252  * to "eye".
253  *
254  * @param node     Node to use in numa setup
255  * @param qlm      QLM to use
256  * @param qlm_lane Which lane
257  * @param eye      Output eye data
258  *
259  * @return Zero on success, negative on failure
260  */
261 extern int __bdk_qlm_eye_capture_cn8xxx(bdk_node_t node, int qlm, int lane, bdk_qlm_eye_t *eye_data) BDK_WEAK;
262 
263 /**
264  * Disables DFE for the specified QLM lane(s).
265  * This function should only be called for low-loss channels.
266  *
267  * @param node   Node to configure
268  * @param qlm    QLM to configure
269  * @param lane   Lane to configure, or -1 for all lanes
270  */
271 extern void __bdk_qlm_dfe_disable(int node, int qlm, int lane);
272 
273 /**
274  * Check if a specific lane is using KR training. This is used by low level GSER
275  * code to remember which QLMs and lanes need to support KR training for BGX. The
276  * hardware doesn't have a bit set aside to record this, so we repurpose the
277  * register GSERX_SCRATCH.
278  *
279  * @param node   Node to check
280  * @param qlm    QLM to check
281  * @param lane   Lane to check
282  *
283  * @return True if this lane uses KR with BGX, false otherwise
284  */
285 extern bool __bdk_qlm_is_lane_kr(bdk_node_t node, int qlm, int lane);
286 
287 /**
288  * Set if a specific lane is using KR training. This is used by low level GSER
289  * code to remember which QLMs and lanes need to support KR training for BGX. The
290  * hardware doesn't have a bit set aside to record this, so we repurpose the
291  * register GSERX_SCRATCH.
292  *
293  * @param node   Node to set
294  * @param qlm    QLM to set
295  * @param lane   Lane to set
296  * @param is_kr  KR (true) or XFI/XLAUI (false)
297  */
298 extern void __bdk_qlm_set_lane_kr(bdk_node_t node, int qlm, int lane, bool is_kr);
299 
300 /**
301  * Initialize a DLM/QLM for use with SATA controllers
302  *
303  * @param node       Node to intialize
304  * @param qlm        Which DLM/QLM to init
305  * @param baud_mhz   QLM speed in Gbaud
306  * @param sata_first First SATA controller connected to this DLM/QLM
307  * @param sata_last  Last SATA controller connected to this DLM/QLM (inclusive)
308  *
309  * @return Zero on success, negative on failure
310  */
311 extern int __bdk_qlm_set_sata_cn8xxx(bdk_node_t node, int qlm, int baud_mhz, int sata_first, int sata_last);
312 
313 /**
314  * Initialize a DLM/QLM for use with SATA controllers
315  *
316  * @param node       Node to intialize
317  * @param qlm        Which DLM/QLM to init
318  * @param baud_mhz   QLM speed in Gbaud
319  * @param sata_first First SATA controller connected to this DLM/QLM
320  * @param sata_last  Last SATA controller connected to this DLM/QLM (inclusive)
321  *
322  * @return Zero on success, negative on failure
323  */
324 extern int __bdk_qlm_set_sata_cn9xxx(bdk_node_t node, int qlm, int baud_mhz, int sata_first, int sata_last);
325 
326 #endif /* __BDK_QLM_COMMON_H__ */
327