Google Virtual Ethernet network driver. More...

#include <stdint.h>
#include <ipxe/dma.h>
#include <ipxe/pci.h>
#include <ipxe/in.h>
#include <ipxe/uaccess.h>
#include <ipxe/process.h>
#include <ipxe/retry.h>

Data Structures
struct	google_mac
	A Google Cloud MAC address. More...

struct	gve_admin_header
	Admin queue entry header. More...

struct	gve_admin_simple
	Simple admin command. More...

struct	gve_admin_describe
	Describe device command. More...

struct	gve_device_descriptor
	Device descriptor. More...

struct	gve_admin_configure
	Configure device resources command. More...

struct	gve_admin_register
	Register page list command. More...

struct	gve_pages
	Page list. More...

struct	gve_admin_create_tx
	Create transmit queue command. More...

struct	gve_admin_create_rx
	Create receive queue command. More...

union	gve_admin_command
	An admin queue command. More...

struct	gve_admin
	Admin queue. More...

struct	gve_scratch
	Scratch buffer for admin queue commands. More...

struct	gve_event
	An event counter. More...

struct	gve_events
	Event counter array. More...

struct	gve_irq
	An interrupt channel. More...

struct	gve_irqs
	Interrupt channel array. More...

struct	gve_resources
	Queue resources. More...

struct	gve_qpl
	Queue page list. More...

struct	gve_buffer
	A transmit or receive buffer descriptor. More...

struct	gve_tx_packet
	A transmit packet descriptor. More...

struct	gve_tx_descriptor
	A transmit descriptor. More...

struct	gve_rx_descriptor
	A receive descriptor. More...

struct	gve_rx_packet
	A receive packet descriptor. More...

struct	gve_rx_completion
	A receive completion descriptor. More...

struct	gve_queue
	A descriptor queue. More...

struct	gve_queue_type
	A descriptor queue type. More...

struct	gve_nic
	A Google Virtual Ethernet NIC. More...

Macros
#define	GVE_PAGE_SIZE 0x1000
	Page size. More...

#define	GVE_ALIGN GVE_PAGE_SIZE
	Address alignment. More...

#define	GVE_LEN_ALIGN 64
	Length alignment. More...

#define	GVE_CFG_BAR PCI_BASE_ADDRESS_0
	Configuration BAR. More...

#define	GVE_CFG_SIZE 0x1000
	Configuration BAR size. More...

#define	GVE_CFG_DEVSTAT 0x0000
	Device status. More...

#define	GVE_CFG_DEVSTAT_RESET 0x00000010UL
	Device is reset. More...

#define	GVE_CFG_DRVSTAT 0x0004
	Driver status. More...

#define	GVE_CFG_DRVSTAT_RUN 0x00000001UL
	Run admin queue. More...

#define	GVE_RESET_MAX_WAIT_MS 500
	Maximum time to wait for reset. More...

#define	GVE_CFG_ADMIN_PFN 0x0010
	Admin queue page frame number (for older devices) More...

#define	GVE_CFG_ADMIN_DB 0x0014
	Admin queue doorbell. More...

#define	GVE_CFG_ADMIN_EVT 0x0018
	Admin queue event counter. More...

#define	GVE_CFG_VERSION 0x001f
	Driver version (8-bit register) More...

#define	GVE_CFG_ADMIN_BASE_HI 0x0020
	Admin queue base address high 32 bits. More...

#define	GVE_CFG_ADMIN_BASE_LO 0x0024
	Admin queue base address low 32 bits. More...

#define	GVE_CFG_ADMIN_LEN 0x0028
	Admin queue base address length (16-bit register) More...

#define	GVE_DB_BAR PCI_BASE_ADDRESS_2
	Doorbell BAR. More...

#define	GVE_ADMIN_STATUS_OK 0x00000001
	Command succeeded. More...

#define	GVE_ADMIN_DESCRIBE 0x0001
	Describe device command. More...

#define	GVE_ADMIN_DESCRIBE_VER 1
	Device descriptor version. More...

#define	GVE_ADMIN_CONFIGURE 0x0002
	Configure device resources command. More...

#define	GVE_ADMIN_REGISTER 0x0003
	Register page list command. More...

#define	GVE_QPL_MAX 32
	Maximum number of pages per queue. More...

#define	GVE_ADMIN_UNREGISTER 0x0004
	Unregister page list command. More...

#define	GVE_ADMIN_CREATE_TX 0x0005
	Create transmit queue command. More...

#define	GVE_ADMIN_CREATE_RX 0x0006
	Create receive queue command. More...

#define	GVE_ADMIN_DESTROY_TX 0x0007
	Destroy transmit queue command. More...

#define	GVE_ADMIN_DESTROY_RX 0x0008
	Destroy receive queue command. More...

#define	GVE_ADMIN_DECONFIGURE 0x0009
	Deconfigure device resources command. More...

#define	GVE_ADMIN_COUNT ( GVE_PAGE_SIZE / sizeof ( union gve_admin_command ) )
	Number of admin queue commands. More...

#define	GVE_EVENT_MAX ( GVE_LEN_ALIGN / sizeof ( struct gve_event ) )
	Maximum number of event counters. More...

#define	GVE_IRQ_COUNT 2
	Number of interrupt channels. More...

#define	GVE_IRQ_DISABLE 0x40000000UL
	Disable interrupts. More...

#define	GVE_BUF_SIZE ( GVE_PAGE_SIZE / 2 )
	Queue data buffer size. More...

#define	GVE_BUF_PER_PAGE ( GVE_PAGE_SIZE / GVE_BUF_SIZE )
	Number of data buffers per page. More...

#define	GVE_TX_FILL 8
	Maximum number of transmit buffers. More...

#define	GVE_TX_QPL 0x18ae5458
	Transmit queue page list ID. More...

#define	GVE_TX_IRQ 0
	Tranmsit queue interrupt channel. More...

#define	GVE_TX_TYPE_START 0x00
	Start of packet transmit descriptor type. More...

#define	GVE_TX_TYPE_CONT 0x20
	Continuation of packet transmit descriptor type. More...

#define	GVE_RX_FILL 64
	Maximum number of receive buffers. More...

#define	GVE_RX_QPL 0x18ae5258
	Receive queue page list ID. More...

#define	GVE_RX_IRQ 1
	Receive queue interrupt channel. More...

#define	GVE_RXF_ERROR 0x08
	Receive error. More...

#define	GVE_RXF_MORE 0x20
	Receive packet continues into next descriptor. More...

#define	GVE_RX_SEQ_MASK 0x07
	Receive sequence number mask. More...

#define	GVE_RX_PAD 2
	Padding at the start of all received packets. More...

#define	GVE_ADMIN_MAX_WAIT_MS 500
	Maximum time to wait for admin queue commands. More...

#define	GVE_RESET_MAX_RETRY 5
	Maximum number of times to reattempt device reset. More...

#define	GVE_WATCHDOG_TIMEOUT ( 1 * TICKS_PER_SEC )
	Time between reset recovery checks. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)

Detailed Description

Google Virtual Ethernet network driver.

The Google Virtual Ethernet NIC (GVE or gVNIC) is found only in Google Cloud instances. There is essentially zero documentation available beyond the mostly uncommented source code in the Linux kernel.

Definition in file gve.h.

Macro Definition Documentation

◆ GVE_PAGE_SIZE

#define GVE_PAGE_SIZE 0x1000

Page size.

Definition at line 42 of file gve.h.

◆ GVE_ALIGN

#define GVE_ALIGN GVE_PAGE_SIZE

Address alignment.

All DMA data structure base addresses seem to need to be aligned to a page boundary. (This is not documented anywhere, but is inferred from existing source code and experimentation.)

Definition at line 51 of file gve.h.

◆ GVE_LEN_ALIGN

#define GVE_LEN_ALIGN 64

Length alignment.

All DMA data structure lengths seem to need to be aligned to a multiple of 64 bytes. (This is not documented anywhere, but is inferred from existing source code and experimentation.)

Definition at line 60 of file gve.h.

◆ GVE_CFG_BAR

#define GVE_CFG_BAR PCI_BASE_ADDRESS_0

Configuration BAR.

Definition at line 63 of file gve.h.

◆ GVE_CFG_SIZE

#define GVE_CFG_SIZE 0x1000

Configuration BAR size.

All registers within the configuration BAR are big-endian.

Definition at line 70 of file gve.h.

◆ GVE_CFG_DEVSTAT

#define GVE_CFG_DEVSTAT 0x0000

Device status.

Definition at line 73 of file gve.h.

◆ GVE_CFG_DEVSTAT_RESET

#define GVE_CFG_DEVSTAT_RESET 0x00000010UL

Device is reset.

Definition at line 74 of file gve.h.

◆ GVE_CFG_DRVSTAT

#define GVE_CFG_DRVSTAT 0x0004

Driver status.

Definition at line 77 of file gve.h.

◆ GVE_CFG_DRVSTAT_RUN

#define GVE_CFG_DRVSTAT_RUN 0x00000001UL

Run admin queue.

Definition at line 78 of file gve.h.

◆ GVE_RESET_MAX_WAIT_MS

#define GVE_RESET_MAX_WAIT_MS 500

Maximum time to wait for reset.

Definition at line 81 of file gve.h.

◆ GVE_CFG_ADMIN_PFN

#define GVE_CFG_ADMIN_PFN 0x0010

Admin queue page frame number (for older devices)

Definition at line 84 of file gve.h.

◆ GVE_CFG_ADMIN_DB

#define GVE_CFG_ADMIN_DB 0x0014

Admin queue doorbell.

Definition at line 87 of file gve.h.

◆ GVE_CFG_ADMIN_EVT

#define GVE_CFG_ADMIN_EVT 0x0018

Admin queue event counter.

Definition at line 90 of file gve.h.

◆ GVE_CFG_VERSION

#define GVE_CFG_VERSION 0x001f

Driver version (8-bit register)

Definition at line 93 of file gve.h.

◆ GVE_CFG_ADMIN_BASE_HI

#define GVE_CFG_ADMIN_BASE_HI 0x0020

Admin queue base address high 32 bits.

Definition at line 96 of file gve.h.

◆ GVE_CFG_ADMIN_BASE_LO

#define GVE_CFG_ADMIN_BASE_LO 0x0024

Admin queue base address low 32 bits.

Definition at line 99 of file gve.h.

◆ GVE_CFG_ADMIN_LEN

#define GVE_CFG_ADMIN_LEN 0x0028

Admin queue base address length (16-bit register)

Definition at line 102 of file gve.h.

◆ GVE_DB_BAR

#define GVE_DB_BAR PCI_BASE_ADDRESS_2

Doorbell BAR.

Definition at line 105 of file gve.h.

◆ GVE_ADMIN_STATUS_OK

#define GVE_ADMIN_STATUS_OK 0x00000001

Command succeeded.

Definition at line 122 of file gve.h.

◆ GVE_ADMIN_DESCRIBE

#define GVE_ADMIN_DESCRIBE 0x0001

Describe device command.

Definition at line 133 of file gve.h.

◆ GVE_ADMIN_DESCRIBE_VER

#define GVE_ADMIN_DESCRIBE_VER 1

Device descriptor version.

Definition at line 148 of file gve.h.

◆ GVE_ADMIN_CONFIGURE

#define GVE_ADMIN_CONFIGURE 0x0002

Configure device resources command.

Definition at line 173 of file gve.h.

◆ GVE_ADMIN_REGISTER

#define GVE_ADMIN_REGISTER 0x0003

Register page list command.

Definition at line 192 of file gve.h.

◆ GVE_QPL_MAX

#define GVE_QPL_MAX 32

Maximum number of pages per queue.

This is a policy decision. Must be sufficient to allow for both the transmit and receive queue fill levels.

Definition at line 214 of file gve.h.

◆ GVE_ADMIN_UNREGISTER

#define GVE_ADMIN_UNREGISTER 0x0004

Unregister page list command.

Definition at line 223 of file gve.h.

◆ GVE_ADMIN_CREATE_TX

#define GVE_ADMIN_CREATE_TX 0x0005

Create transmit queue command.

Definition at line 226 of file gve.h.

◆ GVE_ADMIN_CREATE_RX

#define GVE_ADMIN_CREATE_RX 0x0006

Create receive queue command.

Definition at line 247 of file gve.h.

◆ GVE_ADMIN_DESTROY_TX

#define GVE_ADMIN_DESTROY_TX 0x0007

Destroy transmit queue command.

Definition at line 276 of file gve.h.

◆ GVE_ADMIN_DESTROY_RX

#define GVE_ADMIN_DESTROY_RX 0x0008

Destroy receive queue command.

Definition at line 279 of file gve.h.

◆ GVE_ADMIN_DECONFIGURE

#define GVE_ADMIN_DECONFIGURE 0x0009

Deconfigure device resources command.

Definition at line 282 of file gve.h.

◆ GVE_ADMIN_COUNT

#define GVE_ADMIN_COUNT ( GVE_PAGE_SIZE / sizeof ( union gve_admin_command ) )

Number of admin queue commands.

This is theoretically a policy decision. However, older revisions of the hardware seem to have only the "admin queue page frame number" register and no "admin queue length" register, with the implication that the admin queue must be exactly one page in length.

Choose to use a one page (4kB) admin queue for both older and newer versions of the hardware, to minimise variability.

Definition at line 316 of file gve.h.

◆ GVE_EVENT_MAX

#define GVE_EVENT_MAX ( GVE_LEN_ALIGN / sizeof ( struct gve_event ) )

Maximum number of event counters.

We tell the device how many event counters we have provided via the "configure device resources" admin queue command. The device will accept being given only a single counter, but will subsequently fail to create a receive queue.

There is, of course, no documentation indicating how may event counters actually need to be provided. In the absence of evidence to the contrary, assume that 16 counters (i.e. the smallest number we can allocate, given the length alignment constraint on allocations) will be sufficient.

Definition at line 367 of file gve.h.

◆ GVE_IRQ_COUNT

#define GVE_IRQ_COUNT 2

Number of interrupt channels.

We tell the device how many interrupt channels we have provided via the "configure device resources" admin queue command. The device will accept being given zero interrupt channels, but will subsequently fail to create more than a single queue (either transmit or receive).

There is, of course, no documentation indicating how may interrupt channels actually need to be provided. In the absence of evidence to the contrary, assume that two channels (one for transmit, one for receive) will be sufficient.

Definition at line 401 of file gve.h.

◆ GVE_IRQ_DISABLE

#define GVE_IRQ_DISABLE 0x40000000UL

Disable interrupts.

Definition at line 414 of file gve.h.

◆ GVE_BUF_SIZE

#define GVE_BUF_SIZE ( GVE_PAGE_SIZE / 2 )

Queue data buffer size.

In theory, we may specify the size of receive buffers. However, the original version of the device seems not to have a parameter for this, and assumes the use of half-page (2kB) buffers. Choose to use this as the buffer size, on the assumption that older devices will not support any other buffer size.

Definition at line 446 of file gve.h.

◆ GVE_BUF_PER_PAGE

#define GVE_BUF_PER_PAGE ( GVE_PAGE_SIZE / GVE_BUF_SIZE )

Number of data buffers per page.

Definition at line 449 of file gve.h.

◆ GVE_TX_FILL

#define GVE_TX_FILL 8

Maximum number of transmit buffers.

This is a policy decision.

Definition at line 501 of file gve.h.

◆ GVE_TX_QPL

#define GVE_TX_QPL 0x18ae5458

Transmit queue page list ID.

Definition at line 504 of file gve.h.

◆ GVE_TX_IRQ

#define GVE_TX_IRQ 0

Tranmsit queue interrupt channel.

Definition at line 507 of file gve.h.

◆ GVE_TX_TYPE_START

#define GVE_TX_TYPE_START 0x00

Start of packet transmit descriptor type.

Definition at line 538 of file gve.h.

◆ GVE_TX_TYPE_CONT

#define GVE_TX_TYPE_CONT 0x20

Continuation of packet transmit descriptor type.

Definition at line 541 of file gve.h.

◆ GVE_RX_FILL

#define GVE_RX_FILL 64

Maximum number of receive buffers.

This is a policy decision. Experiments suggest that using fewer than 64 receive buffers leads to excessive packet drop rates on some instance types.

Definition at line 550 of file gve.h.

◆ GVE_RX_QPL

#define GVE_RX_QPL 0x18ae5258

Receive queue page list ID.

Definition at line 553 of file gve.h.

◆ GVE_RX_IRQ

#define GVE_RX_IRQ 1

Receive queue interrupt channel.

Definition at line 556 of file gve.h.

◆ GVE_RXF_ERROR

#define GVE_RXF_ERROR 0x08

Receive error.

Definition at line 575 of file gve.h.

◆ GVE_RXF_MORE

#define GVE_RXF_MORE 0x20

Receive packet continues into next descriptor.

Definition at line 578 of file gve.h.

◆ GVE_RX_SEQ_MASK

#define GVE_RX_SEQ_MASK 0x07

Receive sequence number mask.

Definition at line 581 of file gve.h.

◆ GVE_RX_PAD

#define GVE_RX_PAD 2

Padding at the start of all received packets.

Definition at line 592 of file gve.h.

◆ GVE_ADMIN_MAX_WAIT_MS

#define GVE_ADMIN_MAX_WAIT_MS 500

Maximum time to wait for admin queue commands.

Definition at line 701 of file gve.h.

◆ GVE_RESET_MAX_RETRY

#define GVE_RESET_MAX_RETRY 5

Maximum number of times to reattempt device reset.

Definition at line 704 of file gve.h.

◆ GVE_WATCHDOG_TIMEOUT

#define GVE_WATCHDOG_TIMEOUT ( 1 * TICKS_PER_SEC )

Time between reset recovery checks.

Definition at line 707 of file gve.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

Data Structures

Macros

Functions