Debian Codegraph @

Documentation/networking/device_drivers/ethernet/huawei/hinic3.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 =====================================================================
4 Linux kernel driver for Huawei Ethernet Device Driver (hinic3) family
5 =====================================================================
6
7 Overview
8 ========
9
10 The hinic3 is a network interface card (NIC) for Data Center. It supports
11 a range of link-speed devices (10GE, 25GE, 100GE, etc.). The hinic3
12 devices can have multiple physical forms: LOM (Lan on Motherboard) NIC,
13 PCIe standard NIC, OCP (Open Compute Project) NIC, etc.
14
15 The hinic3 driver supports the following features:
16 - IPv4/IPv6 TCP/UDP checksum offload
17 - TSO (TCP Segmentation Offload), LRO (Large Receive Offload)
18 - RSS (Receive Side Scaling)
19 - MSI-X interrupt aggregation configuration and interrupt adaptation.
20 - SR-IOV (Single Root I/O Virtualization).
21
22 Content
23 =======
24
25 - Supported PCI vendor ID/device IDs
26 - Source Code Structure of Hinic3 Driver
27 - Management Interface
28
29 Supported PCI vendor ID/device IDs
30 ==================================
31
32 19e5:0222 - hinic3 PF/PPF
33 19e5:375F - hinic3 VF
34
35 Prime Physical Function (PPF) is responsible for the management of the
36 whole NIC card. For example, clock synchronization between the NIC and
37 the host. Any PF may serve as a PPF. The PPF is selected dynamically.
38
39 Source Code Structure of Hinic3 Driver
40 ======================================
41
42 ======================== ================================================
43 hinic3_pci_id_tbl.h Supported device IDs
44 hinic3_hw_intf.h Interface between HW and driver
45 hinic3_queue_common.[ch] Common structures and methods for NIC queues
46 hinic3_common.[ch] Encapsulation of memory operations in Linux
47 hinic3_csr.h Register definitions in the BAR
48 hinic3_hwif.[ch] Interface for BAR
49 hinic3_eqs.[ch] Interface for AEQs and CEQs
50 hinic3_mbox.[ch] Interface for mailbox
51 hinic3_mgmt.[ch] Management interface based on mailbox and AEQ
52 hinic3_wq.[ch] Work queue data structures and interface
53 hinic3_cmdq.[ch] Command queue is used to post command to HW
54 hinic3_hwdev.[ch] HW structures and methods abstractions
55 hinic3_lld.[ch] Auxiliary driver adaptation layer
56 hinic3_hw_comm.[ch] Interface for common HW operations
57 hinic3_mgmt_interface.h Interface between firmware and driver
58 hinic3_hw_cfg.[ch] Interface for HW configuration
59 hinic3_irq.c Interrupt request
60 hinic3_netdev_ops.c Operations registered to Linux kernel stack
61 hinic3_nic_dev.h NIC structures and methods abstractions
62 hinic3_main.c Main Linux kernel driver
63 hinic3_nic_cfg.[ch] NIC service configuration
64 hinic3_nic_io.[ch] Management plane interface for TX and RX
65 hinic3_rss.[ch] Interface for Receive Side Scaling (RSS)
66 hinic3_rx.[ch] Interface for transmit
67 hinic3_tx.[ch] Interface for receive
68 hinic3_ethtool.c Interface for ethtool operations (ops)
69 hinic3_filter.c Interface for MAC address
70 ======================== ================================================
71
72 Management Interface
73 ====================
74
75 Asynchronous Event Queue (AEQ)
76 ------------------------------
77
78 AEQ receives high priority events from the HW over a descriptor queue.
79 Every descriptor is a fixed size of 64 bytes. AEQ can receive solicited or
80 unsolicited events. Every device, VF or PF, can have up to 4 AEQs.
81 Every AEQ is associated to a dedicated IRQ. AEQ can receive multiple types
82 of events, but in practice the hinic3 driver ignores all events except for
83 2 mailbox related events.
84
85 Mailbox
86 -------
87
88 Mailbox is a communication mechanism between the hinic3 driver and the HW.
89 Each device has an independent mailbox. Driver can use the mailbox to send
90 requests to management. Driver receives mailbox messages, such as responses
91 to requests, over the AEQ (using event HINIC3_AEQ_FOR_MBOX). Due to the
92 limited size of mailbox data register, mailbox messages are sent
93 segment-by-segment.
94
95 Every device can use its mailbox to post request to firmware. The mailbox
96 can also be used to post requests and responses between the PF and its VFs.
97
98 Completion Event Queue (CEQ)
99 ----------------------------
100
101 The implementation of CEQ is the same as AEQ. It receives completion events
102 from HW over a fixed size descriptor of 32 bits. Every device can have up
103 to 32 CEQs. Every CEQ has a dedicated IRQ. CEQ only receives solicited
104 events that are responses to requests from the driver. CEQ can receive
105 multiple types of events, but in practice the hinic3 driver ignores all
106 events except for HINIC3_CMDQ that represents completion of previously
107 posted commands on a cmdq.
108
109 Command Queue (cmdq)
110 --------------------
111
112 Every cmdq has a dedicated work queue on which commands are posted.
113 Commands on the work queue are fixed size descriptor of size 64 bytes.
114 Completion of a command will be indicated using ctrl bits in the
115 descriptor that carried the command. Notification of command completions
116 will also be provided via event on CEQ. Every device has 4 command queues
117 that are initialized as a set (called cmdqs), each with its own type.
118 Hinic3 driver only uses type HINIC3_CMDQ_SYNC.
119
120 Work Queues(WQ)
121 ---------------
122
123 Work queues are logical arrays of fixed size WQEs. The array may be spread
124 over multiple non-contiguous pages using indirection table. Work queues are
125 used by I/O queues and command queues.
126
127 Global function ID
128 ------------------
129
130 Every function, PF or VF, has a unique ordinal identification within the device.
131 Many management commands (mbox or cmdq) contain this ID so HW can apply the
132 command effect to the right function.
133
134 PF is allowed to post management commands to a subordinate VF by specifying the
135 VFs ID. A VF must provide its own ID. Anti-spoofing in the HW will cause
136 command from a VF to fail if it contains the wrong ID.
137