README
¶
Lucius Dataplane
The dataplane reads and writes packets from ports and the forwards packets between them.
Overview
The dataplane consists of a several components:
- forwarding: packet processing actions, tables, and ports.
- saiserver: implements a "proto-ized" version of the Switch Abstraction Interface API and defines the forwarding pipeline
- apigen: code to generate the proto API for the saiserver and C++ code that calls the API
- dplanerc: gNMI reconciler that configures the dataplane based on OpenConfig schema
- standalone: shared library that a implements the C SAI API and container running only the dataplane
There are two ways to run the dataplane. The first as part of Lemming, using the gNMI reconciliation. The second is a SAI implementation (e.g. in SONIC).
Components
forwarding
The forwarding directory contains packet processing actions, tables, and ports. These are the building blocks of the dataplane: they can be combined to create the packet processing pipeline. The forwarding behavior is configured using the gRPC API.
Generally, external users should not program the dataplane using this API directly. It is too flexible and low-level. Instead, the saiserver API should be used instead.
Each port has a stack of input and output actions. The forwarding server processes an incoming packet using the input actions of the input port. If after processing all the actions, if there is an output port, then the server processes the output actions of the output port.
The following sections describe the key parts of the forwarding server. The relevant packages and protobuf files contain more complete documentation.
Actions
Actions can modify the contents of the packet, output the packet etc...
Some of the important actions include:
- Update: Set packet headers values
- Transmit: Set the output port
- Lookup: Lookup in a table and process the resulting action. Read more in the Tables section.
Implementation: fwdport
Ports
Ports define how to read and write the packets. A port contains a list of input and output actions that define actions to take on a packet after reading and before writing.
Note: If no actions are added to a port: all packets are dropped!
Example ports types:
- Kernel: uses linux AF_PACKET
- TAP: uses ioctl and a file descriptor to create/read to TAP interface
Implementation: fwdport
Tables
Tables match against packet headers and perform actions. Each table has a default action list, and list of entries. An entry defines a set of field and values to match against and a list of the corresponding actions.
Note: After a packet is looked up in a table, the new actions are processed before any pending actions.
Example table types:
- Prefix: longest matching prefix of header values
- Exact: exact match
Implementation: fwdport
saiserver
The saiserver is a gRPC API generated from the SAI API. It is the recommended API for programming the dataplane. It is simpler than the forwarding API, can be call from a variety of languages, and is compatible with software already using the SAI API (eg SONiC). The saiserver package implements the API by calling the corresponding forwarding API. This package also configures the forwarding pipeline, by setting up the required tables.
A simple example: the CreateRouteEntry RPC adds a entry to the FIB. This looks something like:
- Compute forwarding actions
- Update the next hop ip metadata field.
- If the next hop is port: transmit action.
- If next hop is next hop: update packet metadata next hop ID, lookup next-hop table.
- If next hop is a group: update packet metadata next hop group, lookup next-hop-group table.
- Figure out the address family of the prefix.
- Add forwarding table entry to correct fib: prefix entry with fields vrf and next hop ip and above action.
dplanerc
The dplanerc implements a gNMI reconciler based on reconciler package. These reconcilers convert from OpenConfig to saiserver proto messages to support configuring the dataplane from gNMI.
Note: The fib uses a custom, simple proto message because OpenConfig does not model configured forwarding tables (only state).
standalone
The dataplane standalone is meant to be used by a NOS to configure a dataplane using the C SAI API. (eg SONiC). The current design runs the dataplane separately from the NOS and all communication is over gRPC.
- The sai directory contains generated C++ code that converts the C SAI API to protobuf API and performs the RPCs.
- Note: the common.cc and common.h contain hand-crafted conversion funcs.
- The packetio package receives packets punted to the CPU port and transmits to the correct interface. It programs the dataplane with the IP assigned to the local interfaces.
- The lucius directory is the Go main that starts the dataplane RPC server.
- The entrypoint.cc is compiled to a shared library that can be loaded in the NOS.
apigen
These packages generate the protobuf and C++ source and headers based on the SAI headers.
Documentation
¶
Overview ¶
Package dataplane is an implementation of the dataplane HAL API.
Package dataplane is an implementation of the dataplane HAL API.
Index ¶
- type Dataplane
- func (d *Dataplane) Conn() (grpc.ClientConnInterface, error)
- func (d *Dataplane) ID() string
- func (d *Dataplane) SaiServer() *saiserver.Server
- func (d *Dataplane) Start(ctx context.Context, c gpb.GNMIClient, target string) error
- func (d *Dataplane) Stop(ctx context.Context) error
- func (d *Dataplane) Validate(*oc.Root) error
- func (d *Dataplane) ValidationPaths() []ygnmi.PathStruct
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dataplane ¶
type Dataplane struct {
// contains filtered or unexported fields
}
Dataplane is an implementation of Dataplane HAL API.
func (*Dataplane) Conn ¶ added in v0.4.0
func (d *Dataplane) Conn() (grpc.ClientConnInterface, error)
FwdClient gets a gRPC client to the packet forwarding engine.
func (*Dataplane) ValidationPaths ¶
func (d *Dataplane) ValidationPaths() []ygnmi.PathStruct
ValidationPaths is a noop to implement to the reconciler interface.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
The apigen command generates C++ and protobuf code for the SAI API.
|
The apigen command generates C++ and protobuf code for the SAI API. |
|
docparser
Package docparser implements a parser for Doxygen xml.
|
Package docparser implements a parser for Doxygen xml. |
|
protogen
Package protogen implements a generator for SAI to protobuf.
|
Package protogen implements a generator for SAI to protobuf. |
|
saiast
Package saiast contains information parsed from AST of the SAI header.
|
Package saiast contains information parsed from AST of the SAI header. |
|
Package dplanerc contains gNMI task handlers.
|
Package dplanerc contains gNMI task handlers. |
|
Package forwarding manages forwarding contexts and forwarding objects.
|
Package forwarding manages forwarding contexts and forwarding objects. |
|
fwdaction
Package fwdaction contains routines and types to manage forwarding actions.
|
Package fwdaction contains routines and types to manage forwarding actions. |
|
fwdaction/actions
Package actions implements various types of actions supported within Lucius.
|
Package actions implements various types of actions supported within Lucius. |
|
fwdaction/mock_fwdpacket
Package mock_fwdpacket is a generated GoMock package.
|
Package mock_fwdpacket is a generated GoMock package. |
|
fwdaction/mock_fwdport
Package mock_fwdport is a generated GoMock package.
|
Package mock_fwdport is a generated GoMock package. |
|
fwdaction/mock_fwdtable
Package mock_fwdtable is a generated GoMock package.
|
Package mock_fwdtable is a generated GoMock package. |
|
fwdconfig
Package fwdconfig contains builders for varius proto types.
|
Package fwdconfig contains builders for varius proto types. |
|
fwdport
Package fwdport contains routines and types to manage forwarding ports.
|
Package fwdport contains routines and types to manage forwarding ports. |
|
fwdport/mock_fwdpacket
Package mock_fwdpacket is a generated GoMock package.
|
Package mock_fwdpacket is a generated GoMock package. |
|
fwdport/ports
Package ports implements various types of ports supported within Lucius.
|
Package ports implements various types of ports supported within Lucius. |
|
fwdport/porttestutil
Package porttestutil contains routines used to create and manage ports for test cases.
|
Package porttestutil contains routines used to create and manage ports for test cases. |
|
fwdtable
Package fwdtable contains routines and types to manage forwarding tables.
|
Package fwdtable contains routines and types to manage forwarding tables. |
|
fwdtable/bridge
Package bridge implements an exact match table that operates on the packet's mac address.
|
Package bridge implements an exact match table that operates on the packet's mac address. |
|
fwdtable/exact
Package exact implements a Lucius table that performs packet matches using an exact match match and satisfies the interface fwdtable.Table.
|
Package exact implements a Lucius table that performs packet matches using an exact match match and satisfies the interface fwdtable.Table. |
|
fwdtable/flow
Package flow implements a Lucius table that performs packet matches using an flow matching and satisfies the interface fwdtable.Table.
|
Package flow implements a Lucius table that performs packet matches using an flow matching and satisfies the interface fwdtable.Table. |
|
fwdtable/mock_fwdpacket
Package mock_fwdpacket is a generated GoMock package.
|
Package mock_fwdpacket is a generated GoMock package. |
|
fwdtable/prefix
Package prefix implements a Lucius table that performs packet matches using the longest prefix match and satisfies the interface fwdtable.Table.
|
Package prefix implements a Lucius table that performs packet matches using the longest prefix match and satisfies the interface fwdtable.Table. |
|
fwdtable/tabletestutil
Package tabletestutil consists of routines used to test Lucius tables like prefix match, exact match and flow match tables.
|
Package tabletestutil consists of routines used to test Lucius tables like prefix match, exact match and flow match tables. |
|
fwdtable/tableutil
Package tableutil contains utilites used to implement tables in Lucius like prefix, flow and exact match.
|
Package tableutil contains utilites used to implement tables in Lucius like prefix, flow and exact match. |
|
infra/deadlock
Package deadlock is a set of simple utilities meant to detect deadlocks based on timeouts.
|
Package deadlock is a set of simple utilities meant to detect deadlocks based on timeouts. |
|
infra/fwdattribute
Package fwdattribute provides types and mechanisms used to manage attributes for forwarding objects.
|
Package fwdattribute provides types and mechanisms used to manage attributes for forwarding objects. |
|
infra/fwdcontext
Package fwdcontext contains routines for managing the context of the forwarding engine.
|
Package fwdcontext contains routines for managing the context of the forwarding engine. |
|
infra/fwdflowcounter
Package fwdflowcounter implements the functionality of Flow Counters.
|
Package fwdflowcounter implements the functionality of Flow Counters. |
|
infra/fwdobject
Package fwdobject contains routines and interfaces used to implement various forwarding objects.
|
Package fwdobject contains routines and interfaces used to implement various forwarding objects. |
|
infra/fwdpacket
Package fwdpacket contains routines and types for manipulating packets.
|
Package fwdpacket contains routines and types for manipulating packets. |
|
infra/fwdset
Package fwdset implements a set of members.
|
Package fwdset implements a set of members. |
|
protocol
Package protocol enables Lucius to uniformly query and mutate network packets containing various protocols.
|
Package protocol enables Lucius to uniformly query and mutate network packets containing various protocols. |
|
protocol/arp
Package arp implements the ARP header.
|
Package arp implements the ARP header. |
|
protocol/ethernet
Package ethernet implements the Ethernet header.
|
Package ethernet implements the Ethernet header. |
|
protocol/icmp
Package icmp implements the ICMP header support in Lucius.
|
Package icmp implements the ICMP header support in Lucius. |
|
protocol/ip
Package ip handles the IP L3 portion of the packet.
|
Package ip handles the IP L3 portion of the packet. |
|
protocol/metadata
Package metadata implements the metadata packet header.
|
Package metadata implements the metadata packet header. |
|
protocol/opaque
Package opaque implements the opaque packet header.
|
Package opaque implements the opaque packet header. |
|
protocol/packettestutil
Package packettestutil contains a set of routines used to test the processing of packet headers and fields.
|
Package packettestutil contains a set of routines used to test the processing of packet headers and fields. |
|
protocol/tcp
Package tcp implements the TCP header support in Lucius.
|
Package tcp implements the TCP header support in Lucius. |
|
protocol/udp
Package udp implements the UDP header support in Lucius.
|
Package udp implements the UDP header support in Lucius. |
|
util/frame
Package frame contains utilities to implement various network protocols and describe their relationship within Lucius.
|
Package frame contains utilities to implement various network protocols and describe their relationship within Lucius. |
|
util/hash/crc16
Package crc16 computes the 16 bit checksum over a series of bytes.
|
Package crc16 computes the 16 bit checksum over a series of bytes. |
|
util/hash/csum16
Package csum16 computes the 16 bit Internet checksum.
|
Package csum16 computes the 16 bit Internet checksum. |
|
util/hash/hash16
Package hash16 provides interfaces for functions computing 16 bit hashes.
|
Package hash16 provides interfaces for functions computing 16 bit hashes. |
|
util/queue
Package queue provides a queue to processes elements in FIFO order using a specified handler, while allowing non-blocking writes to the queue.
|
Package queue provides a queue to processes elements in FIFO order using a specified handler, while allowing non-blocking writes to the queue. |
|
util/stats
Package stats implements Stats that collects data.
|
Package stats implements Stats that collects data. |
|
Package kernel contains funcs that interact with the kernel (sycalls, netlink).
|
Package kernel contains funcs that interact with the kernel (sycalls, netlink). |
|
kerneltest
package kerneltest contains fake implemetation of structs in kernel package
|
package kerneltest contains fake implemetation of structs in kernel package |
|
proto
|
|
|
Package registry is the registry of protocol on the dataplane.
|
Package registry is the registry of protocol on the dataplane. |
|
attrmgr
Package attrmgr contains a SAI attribute key/value store.
|
Package attrmgr contains a SAI attribute key/value store. |
|
standalone
|
|