2 ********************************************************************************
3 Copyright (C) 2015 Annapurna Labs Ltd.
5 This file may be licensed under the terms of the Annapurna Labs Commercial
8 Alternatively, this file can be distributed under the terms of the GNU General
9 Public License V2 as published by the Free Software Foundation and can be
10 found at http://www.gnu.org/licenses/gpl-2.0.html
12 Alternatively, redistribution and use in source and binary forms, with or
13 without modification, are permitted provided that the following conditions are
16 * Redistributions of source code must retain the above copyright notice,
17 this list of conditions and the following disclaimer.
19 * Redistributions in binary form must reproduce the above copyright
20 notice, this list of conditions and the following disclaimer in
21 the documentation and/or other materials provided with the
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
25 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
26 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
27 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
28 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
29 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
31 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 *******************************************************************************/
38 * @defgroup grouppcie PCI Express Controller
40 * @section overview Overview
41 * This header file provide API for the HAL driver of the pcie port, the driver
42 * provides the following functionalities:
43 * - Port initialization
45 * - Interrupts transactions generation (Endpoint mode).
46 * - Configuration Access management functions
47 * - Internal Translation Unit programming
49 * This API does not provide the following:
50 * - PCIe transactions generation and reception (except interrupts as mentioned
51 * above) as this functionality is done by the port without need for sw
53 * - Configuration Access: those transactions are generated automatically by
54 * the port (ECAM or ATU mode) when the CPU issues memory transaction
55 * through the fabric toward the PCIe port. This API provides management
56 * function for controlling the Configuration Access type and bus destination
57 * - Interrupt Handling.
58 * - Message Generation: common used messages are automatically generated, also,
59 * the ATU generic mechanism for generating various kind of messages.
60 * - PCIe Port Management: both link and port power management features can be
61 * managed using the PCI/PCIe standard power management and PCIe capabilities
63 * - PCIe link and protocol error handling: the feature can be managed using
64 * the Advanced Error Handling PCIe capability registers.
66 * @section flows Software Flows
67 * @subsection init Initialization
68 * - allocation and set zeros al_pcie_port and al_pcie_pf structures handles
69 * - call al_pcie_port_handle_init() with pointer to the allocated
70 * al_pcie_port handle, address of the port internal registers space, and
72 * - call al_pcie_pf_handle_init() with pointer to the al_pcie_port handle
74 * - set the port mode, End-Point or Root-Compex (default).
75 * - set number of lanes connected to the controller.
76 * - enable the controller using the al_pcie_port_enable(). note that this
77 * function expect the virtual address of the PBS Functional Registers.
78 * - wait for 2000 South-bridge cycles.
79 * - prepare al_pcie_port_config_params and al_pcie_pf_config_params
80 * structures depending on chip, board and system configuration.
81 * for example, when using the port as root complex, the operating_mode
82 * field should be set to AL_PCIE_OPERATING_MODE_RC. In this example we
83 * prepare the following configuration:
84 * For port configuration
86 * - Set the Max Link Speed to Gen2
87 * - Set the max lanes width to 2 (x2)
88 * - Enable Snoops to support I/O Hardware cache coherency
89 * - Enable pcie core RAM parity
90 * - Enable pcie core AXI parity
91 * - Keep transaction layer default credits
92 * For pf configuration
94 * - No SR-IOV parameters
95 * so the structures we prepare:
97 * - struct al_pcie_link_params link_params = {
98 * AL_PCIE_LINK_SPEED_GEN2,
99 * AL_PCIE_MPS_DEFAULT};
101 * - struct al_pcie_port_config_params config_params = {
103 * AL_TRUE, // enable Snoop for inbound memory transactions
104 * AL_TRUE, // enable pcie port RAM parity
105 * AL_TRUE, // enable pcie port AXI parity
106 * NULL, // use default latency/replay timers
107 * NULL, // use default gen2 pipe params
108 * NULL, // gen3_params not needed when max speed set to Gen2
109 * NULL, // don't change TL credits
110 * NULL, // end point params not needed
111 * AL_FALSE, //no fast link
112 * AL_FALSE}; //return 0xFFFFFFFF for read transactions with
115 * - now call al_pcie_port_config() with pcie_port and port_config_params
116 * @subsection link-init Link Initialization
117 * - once the port configured, we can start PCIe link:
118 * - call al_pcie_link_start()
119 * - call al_pcie_link_up_wait()
120 * - allocate al_pcie_link_status struct and call al_pcie_link_status() and
121 * check the link is established.
123 * @subsection cap Configuration Access Preparation
124 * - Once the link is established, we can prepare the port for pci
125 * configuration access, this stage requires system knowledge about the PCI
126 * buses enumeration. For example, if 5 buses were discovered on previously
127 * scanned root complex port, then we should start enumeration from bus 5 (PCI
128 * secondary bus), the sub-ordinary bus will be temporarily set to maximum
129 * value (255) until the scan process under this bus is finished, then it will
130 * updated to the maximum bus value found. So we use the following sequence:
131 * - call al_pcie_secondary_bus_set() with sec-bus = 5
132 * - call al_pcie_subordinary_bus_set() with sub-bus = 255
134 * @subsection cfg Configuration (Cfg) Access Generation
135 * - we assume using ECAM method, in this method, the software issues pcie Cfg
136 * access by accessing the ECAM memory space of the pcie port. For example, to
137 * issue 4 byte Cfg Read from bus B, Device D, Function F and register R, the
138 * software issues 4 byte read access to the following physical address
139 * ECAM base address of the port + (B << 20) + (D << 15) + (F << 12) + R.
140 * But, as the default size of the ECAM address space is less than
141 * needed full range (256MB), we modify the target_bus value prior to Cfg
142 * access in order make the port generate Cfg access with bus value set to the
143 * value of the target_bus rather than bits 27:20 of the physical address.
144 * - call al_pcie_target_bus_set() with target_bus set to the required bus of
145 * the next Cfg access to be issued, mask_target_bus will be set to 0xff.
146 * no need to call that function if the next Cfg access bus equals to the last
147 * value set to target_bus.
149 * @file al_hal_pcie.h
150 * @brief HAL Driver Header for the Annapurna Labs PCI Express port.
153 #ifndef _AL_HAL_PCIE_H_
154 #define _AL_HAL_PCIE_H_
156 #include "al_hal_common.h"
157 #include "al_hal_pcie_regs.h"
159 /******************************************************************************/
160 /********************************* Constants **********************************/
161 /******************************************************************************/
164 * PCIe Core revision IDs:
169 #define AL_PCIE_REV_ID_1 1
170 #define AL_PCIE_REV_ID_2 2
171 #define AL_PCIE_REV_ID_3 3
173 /** Number of extended registers */
174 #define AL_PCIE_EX_REGS_NUM 40
176 /*******************************************************************************
177 * The inbound flow control for headers is programmable per P, NP and CPL
178 * transactions types. The following parameters define the total number of
179 * available header flow controls for all types.
180 ******************************************************************************/
181 /** Inbound header credits sum - rev1/2 */
182 #define AL_PCIE_REV_1_2_IB_HCRD_SUM 97
183 /** Inbound header credits sum - rev3 */
184 #define AL_PCIE_REV3_IB_HCRD_SUM 259
186 /*******************************************************************************
187 * PCIe AER uncorrectable error bits
188 * To be used with the following functions:
189 * - al_pcie_aer_config
190 * - al_pcie_aer_uncorr_get_and_clear
191 ******************************************************************************/
192 /** Data Link Protocol Error */
193 #define AL_PCIE_AER_UNCORR_DLP_ERR AL_BIT(4)
195 #define AL_PCIE_AER_UNCORR_POISIONED_TLP AL_BIT(12)
196 /** Flow Control Protocol Error */
197 #define AL_PCIE_AER_UNCORR_FLOW_CTRL_ERR AL_BIT(13)
198 /** Completion Timeout */
199 #define AL_PCIE_AER_UNCORR_COMPL_TO AL_BIT(14)
200 /** Completer Abort */
201 #define AL_PCIE_AER_UNCORR_COMPL_ABT AL_BIT(15)
202 /** Unexpected Completion */
203 #define AL_PCIE_AER_UNCORR_UNEXPCTED_COMPL AL_BIT(16)
204 /** Receiver Overflow */
205 #define AL_PCIE_AER_UNCORR_RCV_OVRFLW AL_BIT(17)
207 #define AL_PCIE_AER_UNCORR_MLFRM_TLP AL_BIT(18)
209 #define AL_PCIE_AER_UNCORR_ECRC_ERR AL_BIT(19)
210 /** Unsupported Request Error */
211 #define AL_PCIE_AER_UNCORR_UNSUPRT_REQ_ERR AL_BIT(20)
212 /** Uncorrectable Internal Error */
213 #define AL_PCIE_AER_UNCORR_INT_ERR AL_BIT(22)
214 /** AtomicOp Egress Blocked */
215 #define AL_PCIE_AER_UNCORR_ATOMIC_EGRESS_BLK AL_BIT(24)
217 /*******************************************************************************
218 * PCIe AER correctable error bits
219 * To be used with the following functions:
220 * - al_pcie_aer_config
221 * - al_pcie_aer_corr_get_and_clear
222 ******************************************************************************/
223 /** Receiver Error */
224 #define AL_PCIE_AER_CORR_RCV_ERR AL_BIT(0)
226 #define AL_PCIE_AER_CORR_BAD_TLP AL_BIT(6)
228 #define AL_PCIE_AER_CORR_BAD_DLLP AL_BIT(7)
229 /** REPLAY_NUM Rollover */
230 #define AL_PCIE_AER_CORR_RPLY_NUM_ROLL_OVR AL_BIT(8)
231 /** Replay Timer Timeout */
232 #define AL_PCIE_AER_CORR_RPLY_TMR_TO AL_BIT(12)
233 /** Advisory Non-Fatal Error */
234 #define AL_PCIE_AER_CORR_ADVISORY_NON_FTL_ERR AL_BIT(13)
235 /** Corrected Internal Error */
236 #define AL_PCIE_AER_CORR_INT_ERR AL_BIT(14)
238 /** The AER erroneous TLP header length [num DWORDs] */
239 #define AL_PCIE_AER_ERR_TLP_HDR_NUM_DWORDS 4
241 /******************************************************************************/
242 /************************* Data Structures and Types **************************/
243 /******************************************************************************/
246 * al_pcie_ib_hcrd_config: data structure internally used in order to config
247 * inbound posted/non-posted parameters.
248 * Note: this is a private member in pcie_port handle and MUST NOT be modified
251 struct al_pcie_ib_hcrd_config {
252 /* Internally used - see 'al_pcie_ib_hcrd_os_ob_reads_config' */
253 unsigned int nof_np_hdr;
255 /* Internally used - see 'al_pcie_ib_hcrd_os_ob_reads_config' */
256 unsigned int nof_p_hdr;
259 /* The Max Payload Size. Measured in bytes.
260 * DEFAULT: do not change the current MPS
262 enum al_pcie_max_payload_size {
269 * al_pcie_port: data structure used by the HAL to handle a specific pcie port.
270 * this structure is allocated and set to zeros by the upper layer, then it is
271 * initialized by the al_pcie_port_handle_init() that should be called before any
272 * other function of this API. later, this handle passed to the API functions.
274 struct al_pcie_port {
275 void __iomem *pcie_reg_base;
276 struct al_pcie_regs regs_ptrs;
277 struct al_pcie_regs *regs;
278 uint32_t *ex_regs_ptrs[AL_PCIE_EX_REGS_NUM];
280 void __iomem *pbs_regs;
284 unsigned int port_id;
287 /* For EP mode only */
288 uint8_t max_num_of_pfs;
290 /* Internally used */
291 struct al_pcie_ib_hcrd_config ib_hcrd_config;
295 * al_pcie_pf: the pf handle, a data structure used to handle PF specific
296 * functionality. Initialized using "al_pcie_pf_handle_init()"
298 * Note: This structure should be used for EP mode only
302 struct al_pcie_port *pcie_port;
305 /** Operating mode (endpoint, root complex) */
306 enum al_pcie_operating_mode {
307 AL_PCIE_OPERATING_MODE_EP,
308 AL_PCIE_OPERATING_MODE_RC,
309 AL_PCIE_OPERATING_MODE_UNKNOWN
312 /* The maximum link speed, measured GT/s (Giga transfer / second)
313 * DEFAULT: do not change the current speed
318 * Note: The values of this enumerator are important for proper behavior
320 enum al_pcie_link_speed {
321 AL_PCIE_LINK_SPEED_DEFAULT,
322 AL_PCIE_LINK_SPEED_GEN1 = 1,
323 AL_PCIE_LINK_SPEED_GEN2 = 2,
324 AL_PCIE_LINK_SPEED_GEN3 = 3
327 /** PCIe capabilities that supported by a specific port */
328 struct al_pcie_max_capability {
329 al_bool end_point_mode_supported;
330 al_bool root_complex_mode_supported;
331 enum al_pcie_link_speed max_speed;
333 uint8_t atu_regions_num;
334 uint32_t atu_min_size; /* Size granularity: 4 Kbytes */
337 /** PCIe link related parameters */
338 struct al_pcie_link_params {
339 enum al_pcie_link_speed max_speed;
340 enum al_pcie_max_payload_size max_payload_size;
344 /** PCIe gen2 link parameters */
345 struct al_pcie_gen2_params {
346 al_bool tx_swing_low; /* set tx swing low when true, and tx swing full when false */
347 al_bool tx_compliance_receive_enable;
348 al_bool set_deemphasis;
351 /** PCIe gen 3 standard per lane equalization parameters */
352 struct al_pcie_gen3_lane_eq_params {
353 uint8_t downstream_port_transmitter_preset;
354 uint8_t downstream_port_receiver_preset_hint;
355 uint8_t upstream_port_transmitter_preset;
356 uint8_t upstream_port_receiver_preset_hint;
359 /** PCIe gen 3 equalization parameters */
360 struct al_pcie_gen3_params {
362 al_bool interrupt_enable_on_link_eq_request;
363 struct al_pcie_gen3_lane_eq_params *eq_params; /* array of lanes params */
364 int eq_params_elements; /* number of elements in the eq_params array */
366 al_bool eq_disable; /* disables the equalization feature */
367 al_bool eq_phase2_3_disable; /* Equalization Phase 2 and Phase 3 */
368 /* Disable (RC mode only) */
369 uint8_t local_lf; /* Full Swing (FS) Value for Gen3 Transmit Equalization */
370 /* Value Range: 12 through 63 (decimal).*/
372 uint8_t local_fs; /* Low Frequency (LF) Value for Gen3 Transmit Equalization */
376 * Inbound posted/non-posted header credits and outstanding outbound reads
377 * completion header configuration.
379 * This structure controls the resource partitioning of an important resource in
380 * the PCIe port. This resource includes the PCIe TLP headers coming on the PCIe
381 * port, and is shared between three types:
382 * - Inbound Non-posted, which are PCIe Reads as well as PCIe Config Cycles
383 * - Inbound Posted, i.e. PCIe Writes
384 * - Inbound Read-completion, which are the completions matching and outbound
385 * reads issued previously by the same core.
386 * The programmer need to take into consideration that a given outbound read
387 * request could be split on the return path into Ceiling[MPS_Size / 64] + 1
388 * of Read Completions.
389 * Programmers are not expected to modify these setting except for rare cases,
390 * where a different ratio between Posted-Writes and Read-Completions is desired
393 * - nof_cpl_hdr + nof_np_hdr + nof_p_hdr ==
394 * AL_PCIE_REV_1_2_IB_HCRD_SUM/AL_PCIE_REV3_IB_HCRD_SUM
399 struct al_pcie_ib_hcrd_os_ob_reads_config {
400 /** Max number of outstanding outbound reads */
401 uint8_t nof_outstanding_ob_reads;
404 * This value set the possible outstanding headers CMPLs , the core
405 * can get (the core always advertise infinite credits for CMPLs).
407 unsigned int nof_cpl_hdr;
410 * This value set the possible outstanding headers reads (non-posted
411 * transactions), the core can get (it set the value in the init FC
414 unsigned int nof_np_hdr;
417 * This value set the possible outstanding headers writes (posted
418 * transactions), the core can get (it set the value in the init FC
421 unsigned int nof_p_hdr;
425 * PCIe Ack/Nak Latency and Replay timers
427 * Note: Programmer is not expected to modify these values unless working in
428 * very slow external devices like low-end FPGA or hardware devices
429 * emulated in software
431 struct al_pcie_latency_replay_timers {
432 uint16_t round_trip_lat_limit;
433 uint16_t replay_timer_limit;
437 * SRIS KP counter values
439 * Description: SRIS is PCI SIG ECN, that enables the two peers on a given PCIe
440 * link to run with Separate Reference clock with Independent Spread spectrum
441 * clock and requires inserting PCIe SKP symbols on the link in faster frequency
442 * that original PCIe spec
444 struct al_pcie_sris_params {
445 /** set to AL_TRUE to use defaults and ignore the other parameters */
446 al_bool use_defaults;
447 uint16_t kp_counter_gen3; /* only for Gen3 */
448 uint16_t kp_counter_gen21;
452 * Relaxed ordering params
453 * Enable ordering relaxations for applications that does not require
454 * enforcement of 'completion must not bypass posted' ordering rule.
457 * - For downstream port, set enable_tx_relaxed_ordering
458 * - For upstream port
459 * - set enable_rx_relaxed_ordering
460 * - set enable tx_relaxed_ordering for emulated EP.
463 * - For Root-Complex:
464 * - tx_relaxed_ordering = AL_FALSE, rx_relaxed_ordering = AL_TRUE
466 * - tx_relaxed_ordering = AL_TRUE, rx_relaxed_ordering = AL_FALSE
468 struct al_pcie_relaxed_ordering_params {
469 al_bool enable_tx_relaxed_ordering;
470 al_bool enable_rx_relaxed_ordering;
473 /** PCIe port configuration parameters
474 * This structure includes the parameters that the HAL should apply to the port
475 * (by al_pcie_port_config()).
476 * The fields that are pointers (e.g. link_params) can be set to NULL, in that
477 * case, the al_pcie_port_config() will keep the current HW settings.
479 struct al_pcie_port_config_params {
480 struct al_pcie_link_params *link_params;
481 al_bool enable_axi_snoop;
482 al_bool enable_ram_parity_int;
483 al_bool enable_axi_parity_int;
484 struct al_pcie_latency_replay_timers *lat_rply_timers;
485 struct al_pcie_gen2_params *gen2_params;
486 struct al_pcie_gen3_params *gen3_params;
488 * Sets all internal timers to Fast Mode for speeding up simulation.
489 * this varible should be set always to AL_FALSE unless user is running
490 * on simulation setup
492 al_bool fast_link_mode;
494 * when true, the PCI unit will return Slave Error/Decoding Error to any
495 * I/O Fabric master or Internal Processors in case of error.
496 * when false, the value 0xFFFFFFFF will be returned without error indication.
498 al_bool enable_axi_slave_err_resp;
499 struct al_pcie_sris_params *sris_params;
500 struct al_pcie_relaxed_ordering_params *relaxed_ordering_params;
504 * BAR register configuration parameters
505 * Note: This structure should be used for EP mode only
507 struct al_pcie_ep_bar_params {
509 al_bool memory_space; /**< memory or io */
510 al_bool memory_64_bit; /**< is memory space is 64 bit */
511 al_bool memory_is_prefetchable;
512 uint64_t size; /* the bar size in bytes */
516 * PF config params (EP mode only)
517 * Note: This structure should be used for EP mode only
519 struct al_pcie_pf_config_params {
521 * disable advertising D1 and D3hot state
522 * Recommended to be AL_TRUE
524 al_bool cap_d1_d3hot_dis;
526 * disable advertising support for Function-Level-Reset
527 * Recommended to be AL_FALSE
531 * disable advertising Advanced power management states
533 al_bool cap_aspm_dis;
534 al_bool bar_params_valid;
536 * Note: only bar_params[0], [2] and [4] can have memory_64_bit enabled
537 * and in such case, the next bar ([1], [3], or [5] respectively) is not used
539 struct al_pcie_ep_bar_params bar_params[6];
540 struct al_pcie_ep_bar_params exp_bar_params;/* expansion ROM BAR*/
543 /** PCIe link status */
544 struct al_pcie_link_status {
546 enum al_pcie_link_speed speed;
547 uint8_t lanes; /* Number of lanes */
551 /** PCIe lane status */
552 struct al_pcie_lane_status {
554 enum al_pcie_link_speed requested_speed;
558 * PCIe MSIX capability configuration parameters
559 * Note: This structure should be used for EP mode only
561 struct al_pcie_msix_params {
562 /* Number of entries - size can be up to: 2024 */
564 uint16_t table_offset;
567 /* which bar to use when calculating the PBA table address and adding offset to */
571 /** PCIE AER capability parameters */
572 struct al_pcie_aer_params {
573 /** ECRC Generation Enable
574 * while this feature is powerful, all known Chip-sets and processors
575 * do not support it as of 2015
578 /** ECRC Check Enable */
582 * Enabled reporting of correctable errors (bit mask)
583 * See 'AL_PCIE_AER_CORR_*' for details
584 * 0 - no reporting at all
586 unsigned int enabled_corr_err;
588 * Enabled reporting of non-fatal uncorrectable errors (bit mask)
589 * See 'AL_PCIE_AER_UNCORR_*' for details
590 * 0 - no reporting at all
592 unsigned int enabled_uncorr_non_fatal_err;
594 * Enabled reporting of fatal uncorrectable errors (bit mask)
595 * See 'AL_PCIE_AER_UNCORR_*' for details
596 * 0 - no reporting at all
598 unsigned int enabled_uncorr_fatal_err;
601 /******************************************************************************/
602 /********************************** PCIe API **********************************/
603 /******************************************************************************/
605 /*************************** PCIe Initialization API **************************/
608 * Initializes a PCIe port handle structure.
610 * @param pcie_port an allocated, non-initialized instance.
611 * @param pcie_reg_base the virtual base address of the port internal
613 * @param pbs_reg_base the virtual base address of the pbs functional
615 * @param port_id the port id (used mainly for debug messages)
617 * @return 0 if no error found.
619 int al_pcie_port_handle_init(struct al_pcie_port *pcie_port,
620 void __iomem *pcie_reg_base,
621 void __iomem *pbs_reg_base,
622 unsigned int port_id);
625 * Initializes a PCIe pf handle structure
626 * @param pcie_pf an allocated, non-initialized instance of pf handle
627 * @param pcie_port pcie port handle
628 * @param pf_num physical function number
629 * @return 0 if no error found
631 int al_pcie_pf_handle_init(
632 struct al_pcie_pf *pcie_pf,
633 struct al_pcie_port *pcie_port,
634 unsigned int pf_num);
637 * Get port revision ID
638 * @param pcie_port pcie port handle
639 * @return Port rev_id
641 int al_pcie_port_rev_id_get(struct al_pcie_port *pcie_port);
643 /************************** Pre PCIe Port Enable API **************************/
646 * @brief set current pcie operating mode (root complex or endpoint)
647 * This function can be called only before enabling the controller using
648 * al_pcie_port_enable().
650 * @param pcie_port pcie port handle
651 * @param mode pcie operating mode
653 * @return 0 if no error found.
655 int al_pcie_port_operating_mode_config(struct al_pcie_port *pcie_port,
656 enum al_pcie_operating_mode mode);
659 * Configure number of lanes connected to this port.
660 * This function can be called only before enabling the controller using al_pcie_port_enable().
662 * @param pcie_port pcie port handle
663 * @param lanes number of lanes (must be 1,2,4,8,16 and not any other value)
665 * Note: this function must be called before any al_pcie_port_config() calls
667 * @return 0 if no error found.
669 int al_pcie_port_max_lanes_set(struct al_pcie_port *pcie_port, uint8_t lanes);
672 * Set maximum physical function numbers
673 * @param pcie_port pcie port handle
674 * @param max_num_of_pfs number of physical functions
677 * - this function must be called before any al_pcie_pf_config() calls
678 * - exposed on a given PCIe Endpoint port
679 * - PCIe rev1/rev2 supports only single Endpoint
680 * - PCIe rev3 can support up to 4
682 int al_pcie_port_max_num_of_pfs_set(
683 struct al_pcie_port *pcie_port,
684 uint8_t max_num_of_pfs);
687 * @brief Inbound posted/non-posted header credits and outstanding outbound
688 * reads completion header configuration
690 * @param pcie_port pcie port handle
691 * @param ib_hcrd_os_ob_reads_config
692 * Inbound header credits and outstanding outbound reads
695 int al_pcie_port_ib_hcrd_os_ob_reads_config(
696 struct al_pcie_port *pcie_port,
697 struct al_pcie_ib_hcrd_os_ob_reads_config *ib_hcrd_os_ob_reads_config);
699 /** return PCIe operating mode
700 * @param pcie_port pcie port handle
701 * @return operating mode
703 enum al_pcie_operating_mode al_pcie_operating_mode_get(
704 struct al_pcie_port *pcie_port);
707 * PCIe AXI quality of service configuration
710 * Initialized PCIe port handle
712 * AXI read quality of service (0 - 15)
714 * AXI write quality of service (0 - 15)
716 void al_pcie_axi_qos_config(
717 struct al_pcie_port *pcie_port,
721 /**************************** PCIe Port Enable API ****************************/
724 * Enable PCIe unit (deassert reset)
725 * This function only enables the port, without any configuration/link
726 * functionality. Should be called before starting any configuration/link API
728 * @param pcie_port pcie port handle
730 * @return 0 if no error found.
732 int al_pcie_port_enable(struct al_pcie_port *pcie_port);
734 /** Disable PCIe unit (assert reset)
736 * @param pcie_port pcie port handle
738 void al_pcie_port_disable(struct al_pcie_port *pcie_port);
741 * Port memory shutdown/up
742 * Memory shutdown should be called for an unused ports for power-saving
744 * Caution: This function can be called only when the controller is disabled
746 * @param pcie_port pcie port handle
747 * @param enable memory shutdown enable or disable
750 int al_pcie_port_memory_shutdown_set(
751 struct al_pcie_port *pcie_port,
755 * Check if port enabled or not
756 * @param pcie_port pcie port handle
757 * @return AL_TRUE of port enabled and AL_FALSE otherwise
759 al_bool al_pcie_port_is_enabled(struct al_pcie_port *pcie_port);
761 /*************************** PCIe Configuration API ***************************/
764 * @brief configure pcie port (mode, link params, etc..)
765 * this function must be called before initializing the link
767 * @param pcie_port pcie port handle
768 * @param params configuration structure.
770 * @return 0 if no error found
772 int al_pcie_port_config(struct al_pcie_port *pcie_port,
773 const struct al_pcie_port_config_params *params);
776 * @brief Configure a specific PF
777 * this function must be called before any datapath transactions
779 * @param pcie_pf pcie pf handle
780 * @param params configuration structure.
782 * @return 0 if no error found
784 int al_pcie_pf_config(
785 struct al_pcie_pf *pcie_pf,
786 const struct al_pcie_pf_config_params *params);
788 /************************** PCIe Link Operations API **************************/
791 * @brief start pcie link
792 * This function starts the link and should be called only after port is enabled
793 * and pre port-enable and configurations are done
794 * @param pcie_port pcie port handle
796 * @return 0 if no error found
798 int al_pcie_link_start(struct al_pcie_port *pcie_port);
801 * @brief stop pcie link
803 * @param pcie_port pcie port handle
805 * @return 0 if no error found
807 int al_pcie_link_stop(struct al_pcie_port *pcie_port);
810 * @brief check if pcie link is started
811 * Note that this function checks if link is started rather than link is up
812 * @param pcie_port pcie port handle
813 * @return AL_TRUE if link is started and AL_FALSE otherwise
815 al_bool al_pcie_is_link_started(struct al_pcie_port *pcie_port);
818 * @brief trigger link-disable
820 * @param pcie_port pcie port handle
821 * @param disable AL_TRUE to disable the link and AL_FALSE to enable it
823 * Note: this functionality differs from "al_pcie_link_stop" as it's a spec
824 * functionality where both sides of the PCIe agrees to disable the link
825 * @return 0 if no error found
827 int al_pcie_link_disable(struct al_pcie_port *pcie_port, al_bool disable);
830 * @brief wait for link up indication
831 * this function waits for link up indication, it polls LTSSM state until link is ready
833 * @param pcie_port pcie port handle
834 * @param timeout_ms maximum timeout in milli-seconds to wait for link up
836 * @return 0 if link up indication detected
839 int al_pcie_link_up_wait(struct al_pcie_port *pcie_port, uint32_t timeout_ms);
842 * @brief get link status
844 * @param pcie_port pcie port handle
845 * @param status structure for link status
847 * @return 0 if no error found
849 int al_pcie_link_status(struct al_pcie_port *pcie_port, struct al_pcie_link_status *status);
852 * @brief get lane status
859 * Pointer to returned structure for lane status
862 void al_pcie_lane_status_get(
863 struct al_pcie_port *pcie_port,
865 struct al_pcie_lane_status *status);
868 * @brief trigger hot reset
869 * this function initiates In-Band reset while link is up.
870 * to initiate hot reset: call this function with AL_TRUE
871 * to exit from hos reset: call this function with AL_FALSE
872 * Note: This function should be called in RC mode only
874 * @param pcie_port pcie port handle
875 * @param enable AL_TRUE to enable hot-reset and AL_FALSE to disable it
877 * @return 0 if no error found
879 int al_pcie_link_hot_reset(struct al_pcie_port *pcie_port, al_bool enable);
882 * @brief trigger link-retain
883 * this function initiates Link retraining by directing the Physical Layer LTSSM
884 * to the Recovery state. If the LTSSM is already in Recovery or Configuration,
885 * re-entering Recovery is permitted but not required.
886 * Note: This function should be called in RC mode only
888 * @param pcie_port pcie port handle
890 * Note: there's no need to disable initiating link-retrain
891 * @return 0 if no error found
893 int al_pcie_link_retrain(struct al_pcie_port *pcie_port);
896 * @brief change port speed
897 * this function changes the port speed, it doesn't wait for link re-establishment
899 * @param pcie_port pcie port handle
900 * @param new_speed the new speed gen to set
902 * @return 0 if no error found
904 int al_pcie_link_change_speed(struct al_pcie_port *pcie_port, enum al_pcie_link_speed new_speed);
906 /* TODO: check if this function needed */
907 int al_pcie_link_change_width(struct al_pcie_port *pcie_port, uint8_t width);
909 /**************************** Post Link Start API *****************************/
911 /************************** Snoop Configuration API ***************************/
914 * @brief configure pcie port axi snoop
915 * This enable the inbound PCIe posted write data or the Read completion data to
916 * snoop the internal processor caches for I/O cache coherency
918 * @param pcie_port pcie port handle
919 * @param enable_axi_snoop enable snoop.
921 * @return 0 if no error found
923 /* TODO: Can this API be called after port enable? */
924 int al_pcie_port_snoop_config(struct al_pcie_port *pcie_port,
925 al_bool enable_axi_snoop);
927 /************************** Configuration Space API ***************************/
930 * Configuration Space Access Through PCI-E_ECAM_Ext PASW
931 * This feature enables the internal processors to generate configuration cycles
932 * on the PCIe ports by writing to part of the processor memory space marked by
933 * the PCI-E_EXCAM_Ext address window
937 * @brief get base address of pci configuration space header
938 * @param pcie_pf pcie pf handle
939 * @param addr pointer for returned address;
940 * @return 0 if no error found
942 int al_pcie_config_space_get(
943 struct al_pcie_pf *pcie_pf,
944 uint8_t __iomem **addr);
947 * Read data from the local configuration space
949 * @param pcie_pf pcie pf handle
950 * @param reg_offset Configuration space register offset
953 uint32_t al_pcie_local_cfg_space_read(
954 struct al_pcie_pf *pcie_pf,
955 unsigned int reg_offset);
958 * Write data to the local configuration space
960 * @param pcie_pf PCIe pf handle
961 * @param reg_offset Configuration space register offset
962 * @param data Data to write
963 * @param cs2 Should be AL_TRUE if dbi_cs2 must be asserted
964 * to enable writing to this register, according to
965 * the PCIe Core specifications
966 * @param allow_ro_wr AL_TRUE to allow writing into read-only regs
969 void al_pcie_local_cfg_space_write(
970 struct al_pcie_pf *pcie_pf,
971 unsigned int reg_offset,
974 al_bool allow_ro_wr);
977 * @brief set target_bus and mask_target_bus
979 * Call this function with target_bus set to the required bus of the next
980 * outbound config access to be issued. No need to call that function if the
981 * next config access bus equals to the last one.
983 * @param pcie_port pcie port handle
985 * @param mask_target_bus
986 * @return 0 if no error found
988 int al_pcie_target_bus_set(struct al_pcie_port *pcie_port,
990 uint8_t mask_target_bus);
993 * @brief get target_bus and mask_target_bus
994 * @param pcie_port pcie port handle
996 * @param mask_target_bus
997 * @return 0 if no error found
999 int al_pcie_target_bus_get(struct al_pcie_port *pcie_port,
1000 uint8_t *target_bus,
1001 uint8_t *mask_target_bus);
1004 * Set secondary bus number
1006 * Same as al_pcie_target_bus_set but with secondary bus
1008 * @param pcie_port pcie port handle
1009 * @param secbus pci secondary bus number
1011 * @return 0 if no error found.
1013 int al_pcie_secondary_bus_set(struct al_pcie_port *pcie_port, uint8_t secbus);
1016 * Set subordinary bus number
1018 * Same as al_pcie_target_bus_set but with subordinary bus
1020 * @param pcie_port pcie port handle
1021 * @param subbus the highest bus number of all of the buses that can be reached
1022 * downstream of the PCIE instance.
1024 * @return 0 if no error found.
1026 int al_pcie_subordinary_bus_set(struct al_pcie_port *pcie_port,uint8_t subbus);
1029 * @brief Enable/disable deferring incoming configuration requests until
1030 * initialization is complete. When enabled, the core completes incoming
1031 * configuration requests with a Configuration Request Retry Status.
1032 * Other incoming non-configuration Requests complete with Unsupported Request status.
1034 * Note: This function should be used for EP mode only
1036 * @param pcie_port pcie port handle
1037 * @param en enable/disable
1039 void al_pcie_app_req_retry_set(struct al_pcie_port *pcie_port, al_bool en);
1042 * @brief Check if deferring incoming configuration requests is enabled or not
1043 * @param pcie_port pcie port handle
1044 * @return AL_TRUE is it's enabled and AL_FALSE otherwise
1046 al_bool al_pcie_app_req_retry_get_status(struct al_pcie_port *pcie_port);
1048 /*************** Internal Address Translation Unit (ATU) API ******************/
1050 enum al_pcie_atu_dir {
1051 AL_PCIE_ATU_DIR_OUTBOUND = 0,
1052 AL_PCIE_ATU_DIR_INBOUND = 1,
1055 /** decoding of the PCIe TLP Type as appears on the wire */
1056 enum al_pcie_atu_tlp {
1057 AL_PCIE_TLP_TYPE_MEM = 0,
1058 AL_PCIE_TLP_TYPE_IO = 2,
1059 AL_PCIE_TLP_TYPE_CFG0 = 4,
1060 AL_PCIE_TLP_TYPE_CFG1 = 5,
1061 AL_PCIE_TLP_TYPE_MSG = 0x10,
1062 AL_PCIE_TLP_TYPE_RESERVED = 0x1f
1065 /** default response types */
1066 enum al_pcie_atu_response {
1067 AL_PCIE_RESPONSE_NORMAL = 0,
1068 AL_PCIE_RESPONSE_UR = 1, /* UR == Unsupported Request */
1069 AL_PCIE_RESPONSE_CA = 2 /* CA == Completion Abort */
1072 struct al_pcie_atu_region {
1074 /**********************************************************************
1075 * General Parameters *
1076 **********************************************************************/
1079 /* outbound or inbound */
1080 enum al_pcie_atu_dir direction;
1083 /* the 64-bit address that get matched with the 64-bit address incoming
1088 * limit marks the region's end address.
1089 * For Alpine V1 (PCIe rev1): only bits [39:0] are valid
1090 * For Alpine V2 (PCIe rev2/rev3): only bits [47:0] are valid
1091 * an access is a hit in iATU if the:
1092 * - address >= base_addr
1093 * - address <= base_addr + limit
1097 * the address that matches (hit) will be translated to:
1098 * target_addr + offset
1100 * Exmaple: accessing (base_addr + 0x1000) will be translated to:
1101 * (target_addr + 0x1000) in case limit >= 0x1000
1103 uint64_t target_addr;
1105 * When the Invert feature is activated, an address match occurs when
1106 * the untranslated address is not in the region bounded by the Base
1107 * address and Limit address. Match occurs when the untranslated address
1108 * is not in the region bounded by the base address and limit address
1110 al_bool invert_matching;
1113 * Can be: Mem, IO, CGF0, CFG1 or MSG
1115 enum al_pcie_atu_tlp tlp_type;
1117 * PCIe frame header attr field.
1118 * When the address of a TLP is matched to this region, then the ATTR
1119 * field of the TLP is changed to the value in this register.
1123 /**********************************************************************
1124 * Outbound specific Parameters *
1125 **********************************************************************/
1129 * MSG TLPs (Message Code). When the address of an outbound TLP is
1130 * matched to this region, and the translated TLP TYPE field is Msg
1131 * then the message field of the TLP is changed to the value in this
1136 * CFG Shift Mode. This is useful for CFG transactions where the PCIe
1137 * configuration mechanism maps bits [27:12] of the address to the
1138 * bus/device and function number. This allows a CFG configuration space
1139 * to be located in any 256MB window of your application memory space
1140 * using a 28-bit effective address.Shifts bits [27:12] of the
1141 * untranslated address to form bits [31:16] of the translated address.
1143 al_bool cfg_shift_mode;
1145 /**********************************************************************
1146 * Inbound specific Parameters *
1147 **********************************************************************/
1151 * Match Mode. Determines Inbound matching mode for TLPs. The mode
1152 * depends on the type of TLP that is received as follows:
1153 * MEM-I/O: 0 = Address Match Mode
1154 * 1 = BAR Match Mode
1155 * CFG0 : 0 = Routing ID Match Mode
1157 * MSG : 0 = Address Match Mode
1158 * 1 = Vendor ID Match Mode
1163 * - AL_TRUE : enables taking the function number of the translated TLP
1164 * from the PCIe core
1165 * - AL_FALSE: no function number is taken from PCIe core
1167 * - AL_TRUE : enables ATU function match mode
1168 * - AL_FALSE: no function match mode applied to transactions
1170 * Note: this boolean is ignored in RC mode
1172 al_bool function_match_bypass_mode;
1174 * The function number to match/bypass (see previous parameter)
1175 * Note: this parameter is ignored when previous parameter is AL_FALSE
1177 uint8_t function_match_bypass_mode_number;
1179 * setting up what is the default response for an inbound transaction
1180 * that matches the iATU
1182 enum al_pcie_atu_response response;
1184 * Attr Match Enable. Ensures that a successful AT TLP field comparison
1185 * match (see attr above) occurs for address translation to proceed
1187 al_bool enable_attr_match_mode;
1189 * Message Code Match Enable(Msg TLPS). Ensures that a successful
1190 * message Code TLP field comparison match (see Message msg_code)occurs
1191 * (in MSG transactions) for address translation to proceed.
1193 al_bool enable_msg_match_mode;
1195 * USE WITH CAUTION: setting this boolean to AL_TRUE allows setting the
1196 * outbound ATU even after link is already started. DO NOT SET this
1197 * boolean to AL_TRUE unless there have been NO traffic before calling
1198 * al_pcie_atu_region_set function
1200 al_bool enforce_ob_atu_region_set;
1204 * @brief program internal ATU region entry
1205 * @param pcie_port pcie port handle
1206 * @param atu_region data structure that contains the region index and the
1207 * translation parameters
1208 * @return 0 if no error
1210 int al_pcie_atu_region_set(
1211 struct al_pcie_port *pcie_port,
1212 struct al_pcie_atu_region *atu_region);
1215 * @brief get internal ATU is enabled and base/target addresses
1216 * @param pcie_port pcie port handle
1217 * @param direction input: iATU direction (IB/OB)
1218 * @param index input: iATU index
1219 * @param enable output: AL_TRUE if the iATU is enabled
1220 * @param base_addr output: the iATU base address
1221 * @param target_addr output: the iATU target address
1223 void al_pcie_atu_region_get_fields(
1224 struct al_pcie_port *pcie_port,
1225 enum al_pcie_atu_dir direction, uint8_t index,
1226 al_bool *enable, uint64_t *base_addr, uint64_t *target_addr);
1229 * @brief Configure axi io bar.
1231 * This is an EP feature, enabling PCIe IO transaction to be captured if it fits
1232 * within start and end address, and then mapped to internal 4-byte
1233 * memRead/memWrite. Every hit to this bar will override size to 4 bytes.
1235 * @param pcie_port pcie port handle
1236 * @param start the first address of the memory
1237 * @param end the last address of the memory
1240 void al_pcie_axi_io_config(
1241 struct al_pcie_port *pcie_port,
1242 al_phys_addr_t start,
1243 al_phys_addr_t end);
1245 /************** Interrupt generation (Endpoint mode Only) API *****************/
1247 enum al_pcie_legacy_int_type{
1248 AL_PCIE_LEGACY_INTA = 0,
1249 AL_PCIE_LEGACY_INTB,
1250 AL_PCIE_LEGACY_INTC,
1255 /* @brief generate FLR_PF_DONE message
1256 * @param pcie_pf pcie pf handle
1257 * @return 0 if no error found
1259 int al_pcie_pf_flr_done_gen(struct al_pcie_pf *pcie_pf);
1262 * @brief generate INTx Assert/DeAssert Message
1263 * @param pcie_pf pcie pf handle
1264 * @param assert when true, Assert Message is sent
1265 * @param type type of message (INTA, INTB, etc)
1266 * @return 0 if no error found
1268 int al_pcie_legacy_int_gen(
1269 struct al_pcie_pf *pcie_pf,
1271 enum al_pcie_legacy_int_type type);
1274 * @brief generate MSI interrupt
1275 * @param pcie_pf pcie pf handle
1276 * @param vector the vector index to send interrupt for.
1277 * @return 0 if no error found
1279 int al_pcie_msi_int_gen(struct al_pcie_pf *pcie_pf, uint8_t vector);
1282 * @brief configure MSIX capability
1283 * @param pcie_pf pcie pf handle
1284 * @param msix_params MSIX capability configuration parameters
1285 * @return 0 if no error found
1287 int al_pcie_msix_config(
1288 struct al_pcie_pf *pcie_pf,
1289 struct al_pcie_msix_params *msix_params);
1292 * @brief check whether MSIX capability is enabled
1293 * @param pcie_pf pcie pf handle
1294 * @return AL_TRUE if MSIX capability is enabled, AL_FALSE otherwise
1296 al_bool al_pcie_msix_enabled(struct al_pcie_pf *pcie_pf);
1299 * @brief check whether MSIX capability is masked
1300 * @param pcie_pf pcie pf handle
1301 * @return AL_TRUE if MSIX capability is masked, AL_FALSE otherwise
1303 al_bool al_pcie_msix_masked(struct al_pcie_pf *pcie_pf);
1305 /******************** Advanced Error Reporting (AER) API **********************/
1308 * @brief configure EP physical function AER capability
1309 * @param pcie_pf pcie pf handle
1310 * @param params AER capability configuration parameters
1311 * @return 0 if no error found
1313 int al_pcie_aer_config(
1314 struct al_pcie_pf *pcie_pf,
1315 struct al_pcie_aer_params *params);
1318 * @brief EP physical function AER uncorrectable errors get and clear
1319 * @param pcie_pf pcie pf handle
1320 * @return bit mask of uncorrectable errors - see 'AL_PCIE_AER_UNCORR_*' for
1323 unsigned int al_pcie_aer_uncorr_get_and_clear(struct al_pcie_pf *pcie_pf);
1326 * @brief EP physical function AER correctable errors get and clear
1327 * @param pcie_pf pcie pf handle
1328 * @return bit mask of correctable errors - see 'AL_PCIE_AER_CORR_*' for
1331 unsigned int al_pcie_aer_corr_get_and_clear(struct al_pcie_pf *pcie_pf);
1334 * @brief EP physical function AER get the header for
1335 * the TLP corresponding to a detected error
1336 * @param pcie_pf pcie pf handle
1337 * @param hdr pointer to an array for getting the header
1339 void al_pcie_aer_err_tlp_hdr_get(
1340 struct al_pcie_pf *pcie_pf,
1341 uint32_t hdr[AL_PCIE_AER_ERR_TLP_HDR_NUM_DWORDS]);
1344 * @brief configure RC port AER capability
1345 * @param pcie_port pcie port handle
1346 * @param params AER capability configuration parameters
1347 * @return 0 if no error found
1349 int al_pcie_port_aer_config(
1350 struct al_pcie_port *pcie_port,
1351 struct al_pcie_aer_params *params);
1354 * @brief RC port AER uncorrectable errors get and clear
1355 * @param pcie_port pcie port handle
1356 * @return bit mask of uncorrectable errors - see 'AL_PCIE_AER_UNCORR_*' for
1359 unsigned int al_pcie_port_aer_uncorr_get_and_clear(
1360 struct al_pcie_port *pcie_port);
1363 * @brief RC port AER correctable errors get and clear
1364 * @param pcie_port pcie port handle
1365 * @return bit mask of correctable errors - see 'AL_PCIE_AER_CORR_*' for
1368 unsigned int al_pcie_port_aer_corr_get_and_clear(
1369 struct al_pcie_port *pcie_port);
1372 * @brief RC port AER get the header for
1373 * the TLP corresponding to a detected error
1374 * @param pcie_port pcie port handle
1375 * @param hdr pointer to an array for getting the header
1377 void al_pcie_port_aer_err_tlp_hdr_get(
1378 struct al_pcie_port *pcie_port,
1379 uint32_t hdr[AL_PCIE_AER_ERR_TLP_HDR_NUM_DWORDS]);
1381 /******************** Loop-Back mode (RC and Endpoint modes) ******************/
1384 * @brief enter local pipe loop-back mode
1385 * This mode will connect the pipe RX signals to TX.
1386 * no need to start link when using this mode.
1387 * Gen3 equalization must be disabled before enabling this mode
1388 * The caller must make sure the port is ready to accept the TLPs it sends to
1389 * itself. for example, BARs should be initialized before sending memory TLPs.
1391 * @param pcie_port pcie port handle
1392 * @return 0 if no error found
1394 int al_pcie_local_pipe_loopback_enter(struct al_pcie_port *pcie_port);
1397 * @brief exit local pipe loopback mode
1399 * @param pcie_port pcie port handle
1400 * @return 0 if no error found
1402 int al_pcie_local_pipe_loopback_exit(struct al_pcie_port *pcie_port);
1405 * @brief enter master remote loopback mode
1406 * No need to configure the link partner to enter slave remote loopback mode
1407 * as this should be done as response to special training sequence directives
1408 * when master works in remote loopback mode.
1409 * The caller must make sure the port is ready to accept the TLPs it sends to
1410 * itself. for example, BARs should be initialized before sending memory TLPs.
1412 * @param pcie_port pcie port handle
1413 * @return 0 if no error found
1415 int al_pcie_remote_loopback_enter(struct al_pcie_port *pcie_port);
1418 * @brief exit remote loopback mode
1420 * @param pcie_port pcie port handle
1421 * @return 0 if no error found
1423 int al_pcie_remote_loopback_exit(struct al_pcie_port *pcie_port);
1426 /** @} end of grouppcie group */