Documentation/networking/device_drivers/google/gve.rst

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