| 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 |
|