Memories and registers

The chip-access commands address the switch ASIC by the register and memory (table) names of the SDK’s chip description, for example ING_CONFIG_64 (a register) or L2X and EGR_L3_NEXT_HOP (memories). They work below the BCM API and the SAI: they read and write the hardware directly, or the SDK’s cached copy of it. Reads show exactly what is programmed. Writes are not seen by the SDK or by SONiC; a write that contradicts what syncd programmed can break forwarding until syncd rewrites the entry or is restarted.

Finding names

  • listmem lists every memory; listmem <TABLE> shows a table’s fields, and a name that is not a memory filters the list.

  • listreg <name> shows a register’s fields; a partial name lists matching registers.

  • Names are the SDK’s, not always the hardware manual’s. Case does not matter, but names cannot be abbreviated: unlike command names, a register or memory name must be typed in full.

  • Not every name from other Broadcom chips exists on a Trident 3. An unknown register prints Syntax error parsing "<name>"; an unknown table ERROR: unknown table "<name>". In the SAI shell a failed command also ends with Failed to execute the diagnostic command. Error: Operation failed.

  • Many tables and registers have aliases, and the shell accepts them, but output always uses the primary name. L2X is an alias of L2_ENTRY (dump chg l2x prints L2_ENTRY.ipipe0[…]), VLAN_TAB of VLAN, and ING_CONFIG of ING_CONFIG_64. listmem and listreg show the aliases (Memory: L2X.ipipe0 aka L2_ENTRY alias L2X).

Table views

Several names often describe the same hardware table.

  • Entry-format views. A hash table is described once per entry format, and one table can hold entries of several formats. The L2 table (L2_ENTRY, alias L2X) is the example: its fields carry a view prefix such as L2:MAC_ADDR or VLAN:STATIC_BIT, and listmem L2X marks it multiview. On a SONiC Trident 3 switch listmem L2X reports 32768 entries (indices 0–32767). Pick the view whose fields you want decoded.

  • Per-pipe views. A Trident 3 has two pipelines. A table such as IFP_TCAM_WIDE also exists as IFP_TCAM_WIDE_PIPE0 and IFP_TCAM_WIDE_PIPE1, which address one pipeline’s copy.

  • View prefix on the command line. Write, MODify, Insert and MemWatch accept <view>:<table>; the view is then added to field names given without one.

The index range of a table is shown by listmem. Some tables are sized at boot, so the range on a running switch can be smaller than the chip maximum.

Table suffixes

<TABLE>.<COPY>

One copy (block) of a table that exists in several blocks, by block name and instance (for example epipe0) or, for per-port tables, by port name. Without it, reads use any copy and writes go to all copies. The block types of a Trident 3 are ipipe, epipe, mmu_glb, mmu_sc, mmu_sed, mmu_xpe, clport, xlport, cmic, iproc, top, ser, avs, lb, cpu and cch_pseudo.

<TABLE>[<n>]

One element of a table array (<TABLE>(<n>) also works). An array table requires it; other tables reject it.

dump, Write and some others also take a pipeline keyword before the table: pipe0 or pipe1 on a Trident 3. dump refuses pipe2 and above (Number of chip is 2, try to dump pipe_0/pipe_1).

Register references

REG

Every instance: all ports of a port register, all blocks of a block register.

REG.<ports>

A port register on some ports: CLMAC_CTRL.ce0, CLMAC_CTRL.ce0-ce3 (see Ports and port bitmaps).

REG.<blocks>

A block register in some blocks.

REG.<cos>.<blocks>

A per-class-of-service register.

REG[<i>], REG[<i>-<j>]

Elements of a register array, for example PROTOCOL_PKT_CONTROL[0] (64 elements on a Trident 3).

A leading $ is ignored. A register instance is printed as <NAME>.<block>[<instance>][<address>]=<value>: <FIELD=value,...>, for example CLMAC_CTRL.ce0[15][0x60000]=0xd040: <TX_EN=0,RX_EN=0>. Long field lists wrap onto indented continuation lines.

Getreg, Setreg and dump also take a register type before the register: SOC (the default; also SCHAN) for internal registers, PCIM for CMIC registers, PCIC for PCI configuration space, IPROC, MCS, PHY (MII, phyID<<8|phyADDR) and MW, MH, MB, MEM for host memory. A register can also be given by address; use the names where possible.

Fields and values

  • Values are decimal or 0x hex; wide values are long hex strings.

  • <FIELD>=<VALUE> sets a field by name. Several assignments can be separated by commas or spaces: A=1,B=2 and A=1 B=2 are the same. Field names are the ones listreg and listmem print.

  • Setreg and Write with fields start from zero: every field you do not name is cleared. Modreg and MODify read first and change only the named fields.

  • After the register or table name, Getreg and dump accept field names; only those fields are printed.

Display options

raw

Raw words instead of decoded fields (getreg, dump).

hex

Hex data only, for scripts (getreg, dump).

chg

Only fields, and for tables only entries, that differ from the reset value (getreg, dump). dump chg <TABLE> is the usual way to see what the SDK programmed.

all

dump: include invalid entries. Without it, entries whose valid field is clear are skipped, and sorted tables are dumped only up to their entry count.

nocache

Read or write the hardware even when the SDK keeps a cached copy of the table (see CACHE). Otherwise reads of cached tables come from the copy.

Safety

  • getreg, listreg, listmem, dump, search, lookup and check only read. Reading a clear-on-read counter or a FIFO still changes it, and a large dump keeps the shell busy for a long time: dump socmem diff to a file took close to three minutes on a running switch, while dump soc diff (about 4900 registers) took a few seconds.

  • setreg, modreg, editreg, write, modify, insert, delete, remove, push, pop and clear change the ASIC behind the SDK’s and SONiC’s back. See each command’s page.