1.. SPDX-License-Identifier: GPL-2.0+
2
3==============================================================
4Linux kernel driver for Compute Engine Virtual Ethernet (gve):
5==============================================================
6
7Supported Hardware
8===================
9The GVE driver binds to a single PCI device id used by the virtual
10Ethernet device found in some Compute Engine VMs.
11
12+--------------+----------+---------+
13|Field         | Value    | Comments|
14+==============+==========+=========+
15|Vendor ID     | `0x1AE0` | Google  |
16+--------------+----------+---------+
17|Device ID     | `0x0042` |         |
18+--------------+----------+---------+
19|Sub-vendor ID | `0x1AE0` | Google  |
20+--------------+----------+---------+
21|Sub-device ID | `0x0058` |         |
22+--------------+----------+---------+
23|Revision ID   | `0x0`    |         |
24+--------------+----------+---------+
25|Device Class  | `0x200`  | Ethernet|
26+--------------+----------+---------+
27
28PCI Bars
29========
30The 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
34
35Device Interactions
36===================
37The 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
49
50Registers
51---------
52All registers are MMIO and big endian.
53
54The registers are used for initializing and configuring the device as well as
55querying device status in response to management interrupts.
56
57Admin Queue (AQ)
58----------------
59The Admin Queue is a PAGE_SIZE memory block, treated as an array of AQ
60commands, used by the driver to issue commands to the device and set up
61resources.The driver and the device maintain a count of how many commands
62have been submitted and executed. To issue AQ commands, the driver must do
63the following (with proper locking):
64
651)  Copy new commands into next available slots in the AQ array
662)  Increment its counter by he number of new commands
673)  Write the counter into the GVE_ADMIN_QUEUE_DOORBELL register
684)  Poll the ADMIN_QUEUE_EVENT_COUNTER register until it equals
69    the value written to the doorbell, or until a timeout.
70
71The device will update the status field in each AQ command reported as
72executed through the ADMIN_QUEUE_EVENT_COUNTER register.
73
74Device Resets
75-------------
76A device reset is triggered by writing 0x0 to the AQ PFN register.
77This causes the device to release all resources allocated by the
78driver, including the AQ itself.
79
80Interrupts
81----------
82The following interrupts are supported by the driver:
83
84Management Interrupt
85~~~~~~~~~~~~~~~~~~~~
86The management interrupt is used by the device to tell the driver to
87look at the GVE_DEVICE_STATUS register.
88
89The handler for the management irq simply queues the service task in
90the workqueue to check the register and acks the irq.
91
92Notification Block Interrupts
93~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94The notification block interrupts are used to tell the driver to poll
95the queues associated with that interrupt.
96
97The handler for these irqs schedule the napi for that block to run
98and poll the queues.
99
100Traffic Queues
101--------------
102gVNIC's queues are composed of a descriptor ring and a buffer and are
103assigned to a notification block.
104
105The descriptor rings are power-of-two-sized ring buffers consisting of
106fixed-size descriptors. They advance their head pointer using a __be32
107doorbell located in Bar2. The tail pointers are advanced by consuming
108descriptors in-order and updating a __be32 counter. Both the doorbell
109and the counter overflow to zero.
110
111Each queue's buffers must be registered in advance with the device as a
112queue page list, and packet data can only be put in those pages.
113
114Transmit
115~~~~~~~~
116gve maps the buffers for transmit rings into a FIFO and copies the packets
117into the FIFO before sending them to the NIC.
118
119Receive
120~~~~~~~
121The buffers for receive rings are put into a data ring that is the same
122length as the descriptor ring and the head and tail pointers advance over
123the rings together.
124