SAI — The Switch Abstraction Interface
SAI is the vendor-neutral API SONiC uses to program forwarding silicon. It models the switch as objects (ports, router interfaces, routes, next hops, neighbors, FDB entries, VLANs, ACLs, tunnels, queues) with attributes, manipulated through create/remove/set/get. SAI standardizes the request; it does NOT make every ASIC identical — supported attributes, limits, and behaviors still vary.
Prerequisites: Lesson 3.1 · Lesson 3.2
Learning objectives
- →State the purpose of SAI and why a vendor-neutral API matters to SONiC.
- →Describe SAI's object-oriented model: object types, object IDs, and attributes.
- →Enumerate the major object categories and what each represents.
- →Explain the create/remove/set/get operations and how SONiC uses them.
- →Explain precisely why SAI standardizes requests but does not erase hardware differences.
SAI is the contract that lets one SONiC run on many ASICs. Every route, neighbor, and ACL you will trace in the labs is a SAI object.
Understanding SAI's object references is what makes ASIC_DB readable: routes point to next hops, next hops point to router interfaces and neighbors, and so on.
What your CCNP already gives you
- • You think in networking objects already: routes, next hops, adjacencies, interfaces, VLANs, ACLs.
- • You understand references between them (a route resolves to a next hop, a next hop to an adjacency).
What is new in SONiC
- • Those objects are made explicit and manipulable through one API, with stable object IDs and typed attributes.
- • The API is the same across vendors, but each vendor's implementation advertises its own capabilities and limits.
- • You can observe the objects and their references directly in ASIC_DB.
| In the analogy | In SONiC |
|---|---|
| A standardized set of levers and dials SONiC uses to command any line | SAI API |
| The named controls: 'route', 'next hop', 'port', 'ACL' | SAI object types |
| The setting on each control (this port's speed, this route's next hop) | Attributes |
| The wiring behind the panel that translates a lever pull into that machine's native motions | Vendor SAI implementation |
Where the analogy stops working
A standardized panel does not make the machines identical. Some lines lack a given lever entirely (an unsupported attribute), some have lower limits (fewer route slots), and some respond with subtly different motion (behavioral differences). SAI standardizes *how you ask*; it cannot standardize *what the hardware can do*. Always check whether this implementation supports the attribute and at what scale.
What SAI is for
SAI (Switch Abstraction Interface) is a C API that defines a common way to program switch forwarding features. SONiC's syncd process calls SAI; a vendor's SAI implementation (a shared library) translates those calls into the vendor's own SDK, which finally programs the chip.
The purpose is decoupling: SONiC does not need per-vendor code to add a route or an ACL. It targets SAI, and any ASIC with a conformant SAI implementation can be driven by the same SONiC logic. This is the technical foundation of disaggregation.
The object-oriented model
SAI models the switch as a graph of objects. Each object has a type (port, route entry, next hop, router interface, neighbor, FDB entry, VLAN, ACL table/entry, tunnel, queue, and more) and a set of attributes (typed key/values — a port's speed, a route's packet action and next-hop reference, an ACL entry's match fields and action).
Most objects are identified by an object ID (OID) — an opaque handle. Some entries are keyed by their own contents instead of an OID: a route entry is keyed by (virtual router, prefix), a neighbor entry by (router interface, IP), an FDB entry by (VLAN/bridge, MAC). Objects reference each other by OID: a route's next-hop attribute holds the OID of a next-hop object; the next hop references a router interface and, through neighbor state, a MAC and port. This reference graph is exactly what you will trace in Lab 3.1 and Lab 3.4.
Major SAI object categories
| Category | Represents | Notes |
|---|---|---|
| Port | A physical/logical front-panel port | Speed, admin state, lanes, attached queues |
| Router interface (RIF) | An L3 interface (routed port, SVI, subport) | Ties L3 to a port/VLAN and a virtual router; source MAC |
| Virtual router | An L3 routing context (VRF) | Route/neighbor entries are scoped to it |
| Route entry | A FIB prefix | Keyed by (vrf, prefix); action + next-hop/next-hop-group reference |
| Next hop | A single L3 forwarding target | References a RIF and a neighbor IP; may be tunnel next hop |
| Next-hop group | An ECMP set of next hops | The unit of ECMP; members reference next hops |
| Neighbor entry | An L3-to-L2 adjacency (ARP/ND result) | Keyed by (RIF, IP); holds destination MAC |
| FDB entry | A learned/static MAC | Keyed by (VLAN/bridge, MAC); points at a bridge port |
| VLAN / VLAN member | An L2 broadcast domain and its ports | Ties ports into a bridged domain |
| ACL table / entry / counter | Classification and policy | Match fields + actions; TCAM-backed; per-entry counters |
| Tunnel / tunnel map | Encap/decap endpoints (e.g., VXLAN) | Bridges overlay and underlay; used heavily in EVPN |
| Queue / scheduler / buffer | Egress QoS and buffering | Per-port/per-queue scheduling and buffer profiles |
| Statistics / counters | Per-object counters | Read via get-stats; surface in COUNTERS_DB |
The four verbs: create, remove, set, get
SAI manipulates objects through a small, uniform set of operations: create (make an object, returning its OID, with an initial attribute list), remove (delete it), set (change one attribute), and get (read attributes, including statistics). Everything SONiC does to the ASIC — add a route, resolve a neighbor, install an ACL, bring a port up — decomposes into these verbs against typed objects.
SONiC's orchestration agents (Lesson 3.4) turn database state into ordered sequences of these calls, respecting references (you cannot create a route pointing at a next hop that does not exist yet). That ordering and dependency management is the heart of the next lesson.
Illustrative: the shape of SAI operations (pseudocode)
# create a router interface bound to a port + virtual router
rif = create(ROUTER_INTERFACE, { port: Ethernet8, vrf: default, src_mac: <switch MAC> })
# neighbor resolves the next-hop IP to a destination MAC on that RIF
create(NEIGHBOR_ENTRY, key={ rif, ip: 10.0.0.2 }, { dst_mac: 00:11:.. })
# a next hop points at the RIF + neighbor IP
nh = create(NEXT_HOP, { type: IP, rif, ip: 10.0.0.2 })
# the route references the next hop
create(ROUTE_ENTRY, key={ vrf, prefix: 10.20.0.0/24 }, { action: FORWARD, next_hop: nh })Not real code you run — a sketch of how a route becomes a sequence of typed SAI calls with references between objects.
This is the single most important accuracy point in the module. SAI standardizes the request: the object model and the four verbs are the same everywhere. It does not standardize the silicon. A given SAI implementation may not support a particular attribute at all, may cap an object type at a lower scale, or may implement a behavior with subtle differences. 'It's all SAI' never means 'it's all the same'.
Common misconceptions
Myth: Because SONiC uses SAI, any feature works on any ASIC.
Reality: Features depend on the ASIC's SAI implementation advertising the needed object types/attributes. Unsupported attributes fail or are ignored regardless of SONiC's request.
Myth: SAI object IDs are meaningful values I can decode.
Reality: OIDs are opaque handles. Their value is the reference graph they let you follow, not any human-readable meaning in the number itself.
Myth: A route is one thing.
Reality: A route is one object that only forwards because a chain of other objects (next hop → RIF → neighbor → port) exists and is resolved. Break any link and the route object is inert.
Go deeperCapability discovery
SAI exposes capability/availability queries so software can ask an implementation what it supports and how much (attribute capability, object-type availability). SONiC and vendors use these to avoid programming things the chip cannot do and to size tables. Operationally, this is why the *right* answer to 'does this ASIC support X?' is to check the platform's SAI capabilities, not to assume from another chip.
- If a feature 'configures' but never forwards, ask whether this ASIC's SAI implementation actually supports the attribute — capability, not config, may be the blocker.
- To understand a forwarding result, follow the SAI reference graph (route → next hop → RIF → neighbor → port), not just the top-level object.
- Different scale ceilings on identical config across platforms are expected: they reflect per-implementation limits.
Key takeaways
- ✓SAI is the vendor-neutral C API SONiC uses to program forwarding silicon.
- ✓It models the switch as typed objects with attributes, connected by OID references.
- ✓All programming reduces to create/remove/set/get against those objects.
- ✓The major categories — ports, RIFs, routes, next hops, neighbors, FDB, VLANs, ACLs, tunnels, queues — are the vocabulary of hardware forwarding.
- ✓SAI standardizes the request but not the hardware: attributes, limits, and behaviors still vary by implementation.
Tested against: SAI as consumed by SONiC 202305 / 202311 · Upstream; vendor SAI implementations differ · Concepts ASIC-independent; capabilities are per-implementation · last reviewed 2026-07. Exact commands and behavior can vary by SONiC release, image, hardware platform, and enterprise distribution.
Knowledge check
Match each SAI object type to what it represents in the forwarding path.
SONiC uses SAI to program many different ASICs. What does that standardization actually guarantee?