1132db935SJakub Kicinski.. SPDX-License-Identifier: GPL-2.0+ 2132db935SJakub Kicinski 3132db935SJakub Kicinski============================================================== 4132db935SJakub KicinskiLinux kernel driver for Compute Engine Virtual Ethernet (gve): 5132db935SJakub Kicinski============================================================== 6132db935SJakub Kicinski 7132db935SJakub KicinskiSupported Hardware 8132db935SJakub Kicinski=================== 9132db935SJakub KicinskiThe GVE driver binds to a single PCI device id used by the virtual 10132db935SJakub KicinskiEthernet device found in some Compute Engine VMs. 11132db935SJakub Kicinski 12132db935SJakub Kicinski+--------------+----------+---------+ 13132db935SJakub Kicinski|Field | Value | Comments| 14132db935SJakub Kicinski+==============+==========+=========+ 15132db935SJakub Kicinski|Vendor ID | `0x1AE0` | Google | 16132db935SJakub Kicinski+--------------+----------+---------+ 17132db935SJakub Kicinski|Device ID | `0x0042` | | 18132db935SJakub Kicinski+--------------+----------+---------+ 19132db935SJakub Kicinski|Sub-vendor ID | `0x1AE0` | Google | 20132db935SJakub Kicinski+--------------+----------+---------+ 21132db935SJakub Kicinski|Sub-device ID | `0x0058` | | 22132db935SJakub Kicinski+--------------+----------+---------+ 23132db935SJakub Kicinski|Revision ID | `0x0` | | 24132db935SJakub Kicinski+--------------+----------+---------+ 25132db935SJakub Kicinski|Device Class | `0x200` | Ethernet| 26132db935SJakub Kicinski+--------------+----------+---------+ 27132db935SJakub Kicinski 28132db935SJakub KicinskiPCI Bars 29132db935SJakub Kicinski======== 30132db935SJakub KicinskiThe gVNIC PCI device exposes three 32-bit memory BARS: 31132db935SJakub Kicinski- Bar0 - Device configuration and status registers. 32132db935SJakub Kicinski- Bar1 - MSI-X vector table 33132db935SJakub Kicinski- Bar2 - IRQ, RX and TX doorbells 34132db935SJakub Kicinski 35132db935SJakub KicinskiDevice Interactions 36132db935SJakub Kicinski=================== 37132db935SJakub KicinskiThe driver interacts with the device in the following ways: 38132db935SJakub Kicinski - Registers 39132db935SJakub Kicinski - A block of MMIO registers 40132db935SJakub Kicinski - See gve_register.h for more detail 41132db935SJakub Kicinski - Admin Queue 42132db935SJakub Kicinski - See description below 43132db935SJakub Kicinski - Reset 44132db935SJakub Kicinski - At any time the device can be reset 45132db935SJakub Kicinski - Interrupts 46132db935SJakub Kicinski - See supported interrupts below 47132db935SJakub Kicinski - Transmit and Receive Queues 48132db935SJakub Kicinski - See description below 49132db935SJakub Kicinski 50c6a7ed77SBailey ForrestDescriptor Formats 51c6a7ed77SBailey Forrest------------------ 52c6a7ed77SBailey ForrestGVE supports two descriptor formats: GQI and DQO. These two formats have 53c6a7ed77SBailey Forrestentirely different descriptors, which will be described below. 54c6a7ed77SBailey Forrest 55*5a3f8d12SRushil GuptaAddressing Mode 56*5a3f8d12SRushil Gupta------------------ 57*5a3f8d12SRushil GuptaGVE supports two addressing modes: QPL and RDA. 58*5a3f8d12SRushil GuptaQPL ("queue-page-list") mode communicates data through a set of 59*5a3f8d12SRushil Guptapre-registered pages. 60*5a3f8d12SRushil Gupta 61*5a3f8d12SRushil GuptaFor RDA ("raw DMA addressing") mode, the set of pages is dynamic. 62*5a3f8d12SRushil GuptaTherefore, the packet buffers can be anywhere in guest memory. 63*5a3f8d12SRushil Gupta 64132db935SJakub KicinskiRegisters 65132db935SJakub Kicinski--------- 66c6a7ed77SBailey ForrestAll registers are MMIO. 67132db935SJakub Kicinski 68132db935SJakub KicinskiThe registers are used for initializing and configuring the device as well as 69132db935SJakub Kicinskiquerying device status in response to management interrupts. 70132db935SJakub Kicinski 71c6a7ed77SBailey ForrestEndianness 72c6a7ed77SBailey Forrest---------- 73c6a7ed77SBailey Forrest- Admin Queue messages and registers are all Big Endian. 74c6a7ed77SBailey Forrest- GQI descriptors and datapath registers are Big Endian. 75c6a7ed77SBailey Forrest- DQO descriptors and datapath registers are Little Endian. 76c6a7ed77SBailey Forrest 77132db935SJakub KicinskiAdmin Queue (AQ) 78132db935SJakub Kicinski---------------- 79132db935SJakub KicinskiThe Admin Queue is a PAGE_SIZE memory block, treated as an array of AQ 80132db935SJakub Kicinskicommands, used by the driver to issue commands to the device and set up 81132db935SJakub Kicinskiresources.The driver and the device maintain a count of how many commands 82132db935SJakub Kicinskihave been submitted and executed. To issue AQ commands, the driver must do 83132db935SJakub Kicinskithe following (with proper locking): 84132db935SJakub Kicinski 85132db935SJakub Kicinski1) Copy new commands into next available slots in the AQ array 86132db935SJakub Kicinski2) Increment its counter by he number of new commands 87132db935SJakub Kicinski3) Write the counter into the GVE_ADMIN_QUEUE_DOORBELL register 88132db935SJakub Kicinski4) Poll the ADMIN_QUEUE_EVENT_COUNTER register until it equals 89132db935SJakub Kicinski the value written to the doorbell, or until a timeout. 90132db935SJakub Kicinski 91132db935SJakub KicinskiThe device will update the status field in each AQ command reported as 92132db935SJakub Kicinskiexecuted through the ADMIN_QUEUE_EVENT_COUNTER register. 93132db935SJakub Kicinski 94132db935SJakub KicinskiDevice Resets 95132db935SJakub Kicinski------------- 96132db935SJakub KicinskiA device reset is triggered by writing 0x0 to the AQ PFN register. 97132db935SJakub KicinskiThis causes the device to release all resources allocated by the 98132db935SJakub Kicinskidriver, including the AQ itself. 99132db935SJakub Kicinski 100132db935SJakub KicinskiInterrupts 101132db935SJakub Kicinski---------- 102132db935SJakub KicinskiThe following interrupts are supported by the driver: 103132db935SJakub Kicinski 104132db935SJakub KicinskiManagement Interrupt 105132db935SJakub Kicinski~~~~~~~~~~~~~~~~~~~~ 106132db935SJakub KicinskiThe management interrupt is used by the device to tell the driver to 107132db935SJakub Kicinskilook at the GVE_DEVICE_STATUS register. 108132db935SJakub Kicinski 109132db935SJakub KicinskiThe handler for the management irq simply queues the service task in 110132db935SJakub Kicinskithe workqueue to check the register and acks the irq. 111132db935SJakub Kicinski 112132db935SJakub KicinskiNotification Block Interrupts 113132db935SJakub Kicinski~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 114132db935SJakub KicinskiThe notification block interrupts are used to tell the driver to poll 115132db935SJakub Kicinskithe queues associated with that interrupt. 116132db935SJakub Kicinski 117132db935SJakub KicinskiThe handler for these irqs schedule the napi for that block to run 118132db935SJakub Kicinskiand poll the queues. 119132db935SJakub Kicinski 120c6a7ed77SBailey ForrestGQI Traffic Queues 121c6a7ed77SBailey Forrest------------------ 122c6a7ed77SBailey ForrestGQI queues are composed of a descriptor ring and a buffer and are assigned to a 123c6a7ed77SBailey Forrestnotification block. 124132db935SJakub Kicinski 125132db935SJakub KicinskiThe descriptor rings are power-of-two-sized ring buffers consisting of 126132db935SJakub Kicinskifixed-size descriptors. They advance their head pointer using a __be32 127132db935SJakub Kicinskidoorbell located in Bar2. The tail pointers are advanced by consuming 128132db935SJakub Kicinskidescriptors in-order and updating a __be32 counter. Both the doorbell 129132db935SJakub Kicinskiand the counter overflow to zero. 130132db935SJakub Kicinski 131132db935SJakub KicinskiEach queue's buffers must be registered in advance with the device as a 132132db935SJakub Kicinskiqueue page list, and packet data can only be put in those pages. 133132db935SJakub Kicinski 134132db935SJakub KicinskiTransmit 135132db935SJakub Kicinski~~~~~~~~ 136132db935SJakub Kicinskigve maps the buffers for transmit rings into a FIFO and copies the packets 137132db935SJakub Kicinskiinto the FIFO before sending them to the NIC. 138132db935SJakub Kicinski 139132db935SJakub KicinskiReceive 140132db935SJakub Kicinski~~~~~~~ 141132db935SJakub KicinskiThe buffers for receive rings are put into a data ring that is the same 142132db935SJakub Kicinskilength as the descriptor ring and the head and tail pointers advance over 143132db935SJakub Kicinskithe rings together. 144c6a7ed77SBailey Forrest 145c6a7ed77SBailey ForrestDQO Traffic Queues 146c6a7ed77SBailey Forrest------------------ 147c6a7ed77SBailey Forrest- Every TX and RX queue is assigned a notification block. 148c6a7ed77SBailey Forrest 149c6a7ed77SBailey Forrest- TX and RX buffers queues, which send descriptors to the device, use MMIO 150c6a7ed77SBailey Forrest doorbells to notify the device of new descriptors. 151c6a7ed77SBailey Forrest 152c6a7ed77SBailey Forrest- RX and TX completion queues, which receive descriptors from the device, use a 153c6a7ed77SBailey Forrest "generation bit" to know when a descriptor was populated by the device. The 154c6a7ed77SBailey Forrest driver initializes all bits with the "current generation". The device will 155c6a7ed77SBailey Forrest populate received descriptors with the "next generation" which is inverted 156c6a7ed77SBailey Forrest from the current generation. When the ring wraps, the current/next generation 157c6a7ed77SBailey Forrest are swapped. 158c6a7ed77SBailey Forrest 159c6a7ed77SBailey Forrest- It's the driver's responsibility to ensure that the RX and TX completion 160c6a7ed77SBailey Forrest queues are not overrun. This can be accomplished by limiting the number of 161c6a7ed77SBailey Forrest descriptors posted to HW. 162c6a7ed77SBailey Forrest 163c6a7ed77SBailey Forrest- TX packets have a 16 bit completion_tag and RX buffers have a 16 bit 164c6a7ed77SBailey Forrest buffer_id. These will be returned on the TX completion and RX queues 165c6a7ed77SBailey Forrest respectively to let the driver know which packet/buffer was completed. 166c6a7ed77SBailey Forrest 167c6a7ed77SBailey ForrestTransmit 168c6a7ed77SBailey Forrest~~~~~~~~ 169c6a7ed77SBailey ForrestA packet's buffers are DMA mapped for the device to access before transmission. 170c6a7ed77SBailey ForrestAfter the packet was successfully transmitted, the buffers are unmapped. 171c6a7ed77SBailey Forrest 172c6a7ed77SBailey ForrestReceive 173c6a7ed77SBailey Forrest~~~~~~~ 174c6a7ed77SBailey ForrestThe driver posts fixed sized buffers to HW on the RX buffer queue. The packet 175c6a7ed77SBailey Forrestreceived on the associated RX queue may span multiple descriptors. 176