ethernet/google/gve.rst

1 .. SPDX-License-Identifier: GPL-2.0+
9 The GVE driver binds to a single PCI device id used by the virtual
10 Ethernet device found in some Compute Engine VMs.
12 +--------------+----------+---------+
16 +--------------+----------+---------+
17 |Device ID     | `0x0042` |         |
18 +--------------+----------+---------+
19 |Sub-vendor ID | `0x1AE0` | Google  |
20 +--------------+----------+---------+
21 |Sub-device ID | `0x0058` |         |
22 +--------------+----------+---------+
24 +--------------+----------+---------+
25 |Device Class  | `0x200`  | Ethernet|
26 +--------------+----------+---------+
30 The gVNIC PCI device exposes three 32-bit memory BARS:
31 - Bar0 - Device configuration and status registers.
32 - Bar1 - MSI-X vector table
33 - Bar2 - IRQ, RX and TX doorbells
35 Device Interactions
37 The driver interacts with the device in the following ways:
38  - Registers
39     - A block of MMIO registers
40     - See gve_register.h for more detail
41  - Admin Queue
42     - See description below
43  - Reset
44     - At any time the device can be reset
45  - Interrupts
46     - See supported interrupts below
47  - Transmit and Receive Queues
48     - See description below
51 ------------------
56 ------------------
58 QPL ("queue-page-list") mode communicates data through a set of
59 pre-registered pages.
65 ---------
68 The registers are used for initializing and configuring the device as well as
69 querying device status in response to management interrupts.
72 ----------
73 - Admin Queue messages and registers are all Big Endian.
74 - GQI descriptors and datapath registers are Big Endian.
75 - DQO descriptors and datapath registers are Little Endian.
78 ----------------
80 commands, used by the driver to issue commands to the device and set up
81 resources.The driver and the device maintain a count of how many commands
91 The device will update the status field in each AQ command reported as
94 Device Resets
95 -------------
96 A device reset is triggered by writing 0x0 to the AQ PFN register.
97 This causes the device to release all resources allocated by the
101 ----------
106 The management interrupt is used by the device to tell the driver to
121 ------------------
125 The descriptor rings are power-of-two-sized ring buffers consisting of
126 fixed-size descriptors. They advance their head pointer using a __be32
128 descriptors in-order and updating a __be32 counter. Both the doorbell
131 Each queue's buffers must be registered in advance with the device as a
146 ------------------
147 - Every TX and RX queue is assigned a notification block.
149 - TX and RX buffers queues, which send descriptors to the device, use MMIO
150   doorbells to notify the device of new descriptors.
152 - RX and TX completion queues, which receive descriptors from the device, use a
153   "generation bit" to know when a descriptor was populated by the device. The
154   driver initializes all bits with the "current generation". The device will
159 - It's the driver's responsibility to ensure that the RX and TX completion
163 - TX packets have a 16 bit completion_tag and RX buffers have a 16 bit
164   buffer_id. These will be returned on the TX completion and RX queues
169 A packet's buffers are DMA mapped for the device to access before transmission.
174 The driver posts fixed sized buffers to HW on the RX buffer queue. The packet
175 received on the associated RX queue may span multiple descriptors.