hinic3.rst

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