요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
=====================================================================
4
Linux kernel driver for Huawei Ethernet Device Driver (hinic3) family
5
=====================================================================
7
Overview
8
========
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.
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).
22
Content
23
=======
25
- Supported PCI vendor ID/device IDs
26
- Source Code Structure of Hinic3 Driver
27
- Management Interface
29
Supported PCI vendor ID/device IDs
30
==================================
32
19e5:0222 - hinic3 PF/PPF
33
19e5:375F - hinic3 VF
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.
39
Source Code Structure of Hinic3 Driver
40
======================================
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
======================== ================================================
72
Management Interface
73
====================
75
Asynchronous Event Queue (AEQ)
76
------------------------------
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.
85
Mailbox
86
-------
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.
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.
98
Completion Event Queue (CEQ)
99
----------------------------
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.
109
Command Queue (cmdq)
110
--------------------
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.
120
Work Queues(WQ)
121
---------------
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.
127
Global function ID
128
------------------
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.
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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
개요, 기능과 PCI function
1-37이 문서는 `GPL-2.0` 라이선스를 따릅니다.
Huawei Ethernet Device Driver(hinic3) 제품군용 Linux 커널 드라이버
개요
hinic3는 data center용 network interface card(NIC)입니다. `10GE`, `25GE`, `100GE` 등 다양한 link speed 장치를 지원합니다.
hinic3 장치는 LOM(LAN on Motherboard) NIC, PCIe 표준 NIC, OCP(Open Compute Project) NIC 등 여러 physical form으로 제공될 수 있습니다.
hinic3 드라이버는 다음 기능을 지원합니다.
- IPv4/IPv6 TCP/UDP checksum offload
- TSO(TCP Segmentation Offload), LRO(Large Receive Offload)
- RSS(Receive Side Scaling)
- MSI-X interrupt aggregation 구성과 interrupt adaptation
- SR-IOV(Single Root I/O Virtualization)
내용
- 지원 PCI vendor ID/device ID
- Hinic3 드라이버 source code 구조
- Management interface
지원 PCI vendor ID/device ID
- `19e5:0222` - hinic3 PF/PPF
- `19e5:375F` - hinic3 VF
Prime Physical Function(PPF)은 NIC card 전체를 관리합니다. 예를 들어 NIC과 host 사이의 clock synchronization을 담당합니다. 어느 PF든 PPF가 될 수 있으며 PPF는 동적으로 선택됩니다.
.. SPDX-License-Identifier: GPL-2.0
=====================================================================
Linux kernel driver for Huawei Ethernet Device Driver (hinic3) family
=====================================================================
Overview
========
The hinic3 is a network interface card (NIC) for Data Center. It supports
a range of link-speed devices (10GE, 25GE, 100GE, etc.). The hinic3
devices can have multiple physical forms: LOM (Lan on Motherboard) NIC,
PCIe standard NIC, OCP (Open Compute Project) NIC, etc.
The hinic3 driver supports the following features:
- IPv4/IPv6 TCP/UDP checksum offload
- TSO (TCP Segmentation Offload), LRO (Large Receive Offload)
- RSS (Receive Side Scaling)
- MSI-X interrupt aggregation configuration and interrupt adaptation.
- SR-IOV (Single Root I/O Virtualization).
Content
=======
- Supported PCI vendor ID/device IDs
- Source Code Structure of Hinic3 Driver
- Management Interface
Supported PCI vendor ID/device IDs
==================================
19e5:0222 - hinic3 PF/PPF
19e5:375F - hinic3 VF
Prime Physical Function (PPF) is responsible for the management of the
whole NIC card. For example, clock synchronization between the NIC and
the host. Any PF may serve as a PPF. The PPF is selected dynamically.Hinic3 드라이버 source code 구조
38-70Hinic3 드라이버 source code 구조
Source역할
hinic3_pci_id_tbl.h지원 device ID
hinic3_hw_intf.hhardware와 driver 사이 interface
hinic3_queue_common.[ch]NIC queue 공통 구조와 method
hinic3_common.[ch]Linux memory operation encapsulation
hinic3_csr.hBAR 내부 register 정의
hinic3_hwif.[ch]BAR interface
hinic3_eqs.[ch]AEQ 및 CEQ interface
hinic3_mbox.[ch]mailbox interface
hinic3_mgmt.[ch]mailbox와 AEQ 기반 management interface
hinic3_wq.[ch]work queue data structure와 interface
hinic3_cmdq.[ch]hardware command 게시용 command queue
hinic3_hwdev.[ch]hardware 구조와 method abstraction
hinic3_lld.[ch]auxiliary driver adaptation layer
hinic3_hw_comm.[ch]공통 hardware operation interface
hinic3_mgmt_interface.hfirmware와 driver 사이 interface
hinic3_hw_cfg.[ch]hardware configuration interface
hinic3_irq.cinterrupt request
hinic3_netdev_ops.cLinux kernel stack에 등록하는 operation
hinic3_nic_dev.hNIC 구조와 method abstraction
hinic3_main.c주 Linux kernel driver
hinic3_nic_cfg.[ch]NIC service configuration
hinic3_nic_io.[ch]TX/RX용 management plane interface
hinic3_rss.[ch]Receive Side Scaling(RSS) interface
hinic3_rx.[ch]transmit interface
hinic3_tx.[ch]receive interface
hinic3_ethtool.cethtool operation interface
hinic3_filter.cMAC address interface
원문의 source code 구조 표를 기능별 설명과 함께 보존합니다.
Source Code Structure of Hinic3 Driver
======================================
======================== ================================================
hinic3_pci_id_tbl.h Supported device IDs
hinic3_hw_intf.h Interface between HW and driver
hinic3_queue_common.[ch] Common structures and methods for NIC queues
hinic3_common.[ch] Encapsulation of memory operations in Linux
hinic3_csr.h Register definitions in the BAR
hinic3_hwif.[ch] Interface for BAR
hinic3_eqs.[ch] Interface for AEQs and CEQs
hinic3_mbox.[ch] Interface for mailbox
hinic3_mgmt.[ch] Management interface based on mailbox and AEQ
hinic3_wq.[ch] Work queue data structures and interface
hinic3_cmdq.[ch] Command queue is used to post command to HW
hinic3_hwdev.[ch] HW structures and methods abstractions
hinic3_lld.[ch] Auxiliary driver adaptation layer
hinic3_hw_comm.[ch] Interface for common HW operations
hinic3_mgmt_interface.h Interface between firmware and driver
hinic3_hw_cfg.[ch] Interface for HW configuration
hinic3_irq.c Interrupt request
hinic3_netdev_ops.c Operations registered to Linux kernel stack
hinic3_nic_dev.h NIC structures and methods abstractions
hinic3_main.c Main Linux kernel driver
hinic3_nic_cfg.[ch] NIC service configuration
hinic3_nic_io.[ch] Management plane interface for TX and RX
hinic3_rss.[ch] Interface for Receive Side Scaling (RSS)
hinic3_rx.[ch] Interface for transmit
hinic3_tx.[ch] Interface for receive
hinic3_ethtool.c Interface for ethtool operations (ops)
hinic3_filter.c Interface for MAC address
======================== ================================================Asynchronous Event Queue
71-84Management interface
Asynchronous Event Queue(AEQ)
AEQ는 descriptor queue를 통해 hardware의 high-priority event를 수신합니다. 모든 descriptor 크기는 고정된 64 bytes입니다.
AEQ는 solicited event와 unsolicited event를 모두 수신할 수 있습니다. VF 또는 PF를 포함한 각 device에는 AEQ가 최대 4개 있을 수 있으며, 각 AEQ는 전용 IRQ 하나에 연결됩니다.
AEQ는 여러 종류의 event를 받을 수 있지만, 실제 hinic3 드라이버는 mailbox 관련 event 2종을 제외한 나머지를 모두 무시합니다.
Management Interface
====================
Asynchronous Event Queue (AEQ)
------------------------------
AEQ receives high priority events from the HW over a descriptor queue.
Every descriptor is a fixed size of 64 bytes. AEQ can receive solicited or
unsolicited events. Every device, VF or PF, can have up to 4 AEQs.
Every AEQ is associated to a dedicated IRQ. AEQ can receive multiple types
of events, but in practice the hinic3 driver ignores all events except for
2 mailbox related events.
Mailbox 통신
85-97Mailbox
Mailbox는 hinic3 드라이버와 hardware 사이의 통신 mechanism입니다. 각 device는 독립적인 mailbox를 가집니다.
드라이버는 mailbox로 management에 request를 보낼 수 있습니다. request에 대한 response 같은 mailbox message는 `HINIC3_AEQ_FOR_MBOX` event를 사용해 AEQ를 통해 수신합니다.
mailbox data register의 크기가 제한되므로 mailbox message는 segment 단위로 나누어 전송합니다.
모든 device는 자신의 mailbox를 사용해 firmware에 request를 게시할 수 있습니다. mailbox는 PF와 그 PF에 속한 VF 사이에서 request와 response를 게시하는 데도 사용할 수 있습니다.
Mailbox
-------
Mailbox is a communication mechanism between the hinic3 driver and the HW.
Each device has an independent mailbox. Driver can use the mailbox to send
requests to management. Driver receives mailbox messages, such as responses
to requests, over the AEQ (using event HINIC3_AEQ_FOR_MBOX). Due to the
limited size of mailbox data register, mailbox messages are sent
segment-by-segment.
Every device can use its mailbox to post request to firmware. The mailbox
can also be used to post requests and responses between the PF and its VFs.
Completion Event Queue
98-108Completion Event Queue(CEQ)
CEQ 구현은 AEQ와 같습니다. hardware에서 32-bit 고정 크기 descriptor를 통해 completion event를 받습니다.
각 device는 CEQ를 최대 32개 가질 수 있고, 각 CEQ에는 전용 IRQ가 있습니다. CEQ는 드라이버 request에 대한 response인 solicited event만 수신합니다.
CEQ는 여러 종류의 event를 받을 수 있지만, 실제 hinic3 드라이버는 이전에 cmdq에 게시한 command의 완료를 나타내는 `HINIC3_CMDQ`를 제외한 나머지를 모두 무시합니다.
Completion Event Queue (CEQ)
----------------------------
The implementation of CEQ is the same as AEQ. It receives completion events
from HW over a fixed size descriptor of 32 bits. Every device can have up
to 32 CEQs. Every CEQ has a dedicated IRQ. CEQ only receives solicited
events that are responses to requests from the driver. CEQ can receive
multiple types of events, but in practice the hinic3 driver ignores all
events except for HINIC3_CMDQ that represents completion of previously
posted commands on a cmdq.
Command Queue와 Work Queue
109-126Command Queue(cmdq)
각 cmdq에는 command를 게시하는 전용 work queue가 있습니다. work queue의 command는 고정 크기 64-byte descriptor입니다.
command 완료는 해당 command를 운반한 descriptor의 control bit로 표시됩니다. command completion 알림은 CEQ event로도 제공됩니다.
각 device에는 하나의 집합인 `cmdqs`로 초기화되는 command queue 4개가 있고, 각각 고유한 type을 가집니다. Hinic3 드라이버는 `HINIC3_CMDQ_SYNC` type만 사용합니다.
Work Queue(WQ)
work queue는 고정 크기 WQE의 logical array입니다. indirection table을 사용하면 이 배열이 서로 연속되지 않은 여러 page에 걸쳐 배치될 수 있습니다. work queue는 I/O queue와 command queue가 사용합니다.
Command Queue (cmdq)
--------------------
Every cmdq has a dedicated work queue on which commands are posted.
Commands on the work queue are fixed size descriptor of size 64 bytes.
Completion of a command will be indicated using ctrl bits in the
descriptor that carried the command. Notification of command completions
will also be provided via event on CEQ. Every device has 4 command queues
that are initialized as a set (called cmdqs), each with its own type.
Hinic3 driver only uses type HINIC3_CMDQ_SYNC.
Work Queues(WQ)
---------------
Work queues are logical arrays of fixed size WQEs. The array may be spread
over multiple non-contiguous pages using indirection table. Work queues are
used by I/O queues and command queues.
Global function ID와 anti-spoofing
127-137Global function ID
PF 또는 VF인 모든 function은 device 안에서 고유한 ordinal identification을 가집니다. 많은 management command(mbox 또는 cmdq)에 이 ID가 들어가므로 hardware는 올바른 function에 command 효과를 적용할 수 있습니다.
PF는 하위 VF의 ID를 지정해 해당 VF에 management command를 게시할 수 있습니다. VF는 반드시 자신의 ID를 제공해야 합니다.
hardware의 anti-spoofing 때문에 VF가 잘못된 ID를 넣어 보낸 command는 실패합니다.
Global function ID
------------------
Every function, PF or VF, has a unique ordinal identification within the device.
Many management commands (mbox or cmdq) contain this ID so HW can apply the
command effect to the right function.
PF is allowed to post management commands to a subordinate VF by specifying the
VFs ID. A VF must provide its own ID. Anti-spoofing in the HW will cause
command from a VF to fail if it contains the wrong ID.
요약·해설
hinic3.rst:1-136hinic3는 여러 물리 형태와 PF·PPF·VF function을 지원하는 data center NIC 드라이버입니다. 관리 경로는 mailbox와 AEQ, command 완료 경로는 cmdq와 CEQ로 나뉘며, 각 function의 global ID로 command 적용 대상을 검증합니다.
지원하는 NIC form, link speed, virtualization과 offload입니다.
PF·PPF·VF의 식별자와 관리 책임입니다.
mailbox request의 응답은 AEQ event로 돌아옵니다.
두 event queue의 크기, 수량과 실제 소비 event를 비교합니다.
descriptor control bit와 CEQ event가 command 완료를 함께 표시합니다.
고정 크기 WQE 배열은 indirection table로 비연속 page에 분산될 수 있습니다.
hardware가 command의 대상 function과 VF의 신원을 확인합니다.