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