`KNETctrl`

Manage kernel network functions

KNETctrl

Shortest form: knet.

Manage the KNET kernel network driver. KNET provides network interfaces (netifs: Linux netdevs such as SONiC’s EthernetN) and filters, which decide whether a packet sent to the CPU goes to a netif, to the user-space receive layer, or nowhere. See KNET and the CPU port.

The words netif, filter, debugpkt, create, destroy, show, on and off must be written in full (case does not matter), so knetctrl netif sh is rejected. The Key=<value> options of the two create forms can be abbreviated as usual.

The show forms are read-only. On SONiC, syncd creates and owns the netifs and filters, and it is not told about changes made here.

Warning

Destroying a netif or filter that syncd created cuts off the packets it carried, for example LACP, LLDP or BGP to the host. syncd can also run into errors later, when it tries to remove an object that is already gone. Creating a filter with a higher priority than SONiC’s can divert its packets.

Hardware-validated

drivshell> knetctrl netif show
Interface ID 1: name=Ethernet0 type=Port vlan=0 port=ce0 keeprxtag
Interface ID 2: name=Ethernet4 type=Port vlan=0 port=ce1 keeprxtag
Interface ID 3: name=Ethernet8 type=Port vlan=0 port=xe0 keeprxtag
Interface ID 4: name=Ethernet9 type=Port vlan=0 port=xe1 keeprxtag
Interface ID 5: name=Ethernet10 type=Port vlan=0 port=xe2 keeprxtag
Interface ID 6: name=Ethernet11 type=Port vlan=0 port=xe3 keeprxtag
Interface ID 7: name=Ethernet12 type=Port vlan=0 port=ce2 keeprxtag
Interface ID 8: name=Ethernet16 type=Port vlan=0 port=ce3 keeprxtag
Interface ID 9: name=Ethernet20 type=Port vlan=0 port=ce4 keeprxtag
Interface ID 10: name=Ethernet24 type=Port vlan=0 port=ce5 keeprxtag
Interface ID 11: name=Ethernet28 type=Port vlan=0 port=ce6 keeprxtag
Interface ID 12: name=Ethernet32 type=Port vlan=0 port=ce7 keeprxtag
Interface ID 13: name=Ethernet36 type=Port vlan=0 port=ce8 keeprxtag
Interface ID 14: name=Ethernet40 type=Port vlan=0 port=ce9 keeprxtag
Interface ID 15: name=Ethernet44 type=Port vlan=0 port=ce10 keeprxtag
Interface ID 16: name=Ethernet48 type=Port vlan=0 port=ce11 keeprxtag
Interface ID 17: name=Ethernet52 type=Port vlan=0 port=ce12 keeprxtag
Interface ID 18: name=Ethernet56 type=Port vlan=0 port=ce13 keeprxtag
Interface ID 19: name=Ethernet60 type=Port vlan=0 port=ce14 keeprxtag
Interface ID 20: name=Ethernet64 type=Port vlan=0 port=ce15 keeprxtag
Interface ID 21: name=Ethernet68 type=Port vlan=0 port=ce16 keeprxtag
Interface ID 22: name=Ethernet72 type=Port vlan=0 port=ce17 keeprxtag
Interface ID 23: name=Ethernet76 type=Port vlan=0 port=ce18 keeprxtag
Interface ID 24: name=Ethernet80 type=Port vlan=0 port=ce19 keeprxtag
Interface ID 25: name=Ethernet84 type=Port vlan=0 port=ce20 keeprxtag
Interface ID 26: name=Ethernet88 type=Port vlan=0 port=ce21 keeprxtag
Interface ID 27: name=Ethernet92 type=Port vlan=0 port=ce22 keeprxtag
Interface ID 28: name=Ethernet96 type=Port vlan=0 port=ce23 keeprxtag
Interface ID 29: name=Ethernet100 type=Port vlan=0 port=ce24 keeprxtag
Interface ID 30: name=Ethernet104 type=Port vlan=0 port=ce25 keeprxtag
Interface ID 31: name=Ethernet108 type=Port vlan=0 port=ce26 keeprxtag
Interface ID 32: name=Ethernet112 type=Port vlan=0 port=ce27 keeprxtag
Interface ID 33: name=Ethernet116 type=Port vlan=0 port=ce28 keeprxtag
Interface ID 34: name=Ethernet120 type=Port vlan=0 port=ce29 keeprxtag
Interface ID 35: name=Ethernet124 type=Port vlan=0 port=ce30 keeprxtag
Interface ID 36: name=Ethernet128 type=Port vlan=0 port=xe4 keeprxtag

knetctrl netif show

List the KNET network interfaces, one per line, or print <no network interfaces>. Each line reads Interface ID <id>: name=<name> type=<type> vlan=<vid> port=<port> and may end with the flags addtag, rcpu, keeprxtag and forcedid. type is Vlan, Port or Meta. port is the port name for Port netifs and n/a otherwise. Read-only. SONiC’s test suite uses this command (sonic-mgmt test suite files invoking bcmcmd (19 files)).

On a SONiC switch there is one Port netif per front-panel port, named after the SONiC interface (Ethernet0 on ce0, and so on), with vlan=0 and the keeprxtag flag. Interface IDs follow the port order of the SONiC configuration.

Hardware-validated

drivshell> knetctrl netif show
Interface ID 1: name=Ethernet0 type=Port vlan=0 port=ce0 keeprxtag
Interface ID 2: name=Ethernet4 type=Port vlan=0 port=ce1 keeprxtag
Interface ID 3: name=Ethernet8 type=Port vlan=0 port=xe0 keeprxtag
Interface ID 4: name=Ethernet9 type=Port vlan=0 port=xe1 keeprxtag
Interface ID 5: name=Ethernet10 type=Port vlan=0 port=xe2 keeprxtag
Interface ID 6: name=Ethernet11 type=Port vlan=0 port=xe3 keeprxtag
Interface ID 7: name=Ethernet12 type=Port vlan=0 port=ce2 keeprxtag
Interface ID 8: name=Ethernet16 type=Port vlan=0 port=ce3 keeprxtag
Interface ID 9: name=Ethernet20 type=Port vlan=0 port=ce4 keeprxtag
Interface ID 10: name=Ethernet24 type=Port vlan=0 port=ce5 keeprxtag
Interface ID 11: name=Ethernet28 type=Port vlan=0 port=ce6 keeprxtag
Interface ID 12: name=Ethernet32 type=Port vlan=0 port=ce7 keeprxtag
Interface ID 13: name=Ethernet36 type=Port vlan=0 port=ce8 keeprxtag
Interface ID 14: name=Ethernet40 type=Port vlan=0 port=ce9 keeprxtag
Interface ID 15: name=Ethernet44 type=Port vlan=0 port=ce10 keeprxtag
Interface ID 16: name=Ethernet48 type=Port vlan=0 port=ce11 keeprxtag
Interface ID 17: name=Ethernet52 type=Port vlan=0 port=ce12 keeprxtag
Interface ID 18: name=Ethernet56 type=Port vlan=0 port=ce13 keeprxtag
Interface ID 19: name=Ethernet60 type=Port vlan=0 port=ce14 keeprxtag
Interface ID 20: name=Ethernet64 type=Port vlan=0 port=ce15 keeprxtag
Interface ID 21: name=Ethernet68 type=Port vlan=0 port=ce16 keeprxtag
Interface ID 22: name=Ethernet72 type=Port vlan=0 port=ce17 keeprxtag
Interface ID 23: name=Ethernet76 type=Port vlan=0 port=ce18 keeprxtag
Interface ID 24: name=Ethernet80 type=Port vlan=0 port=ce19 keeprxtag
Interface ID 25: name=Ethernet84 type=Port vlan=0 port=ce20 keeprxtag
Interface ID 26: name=Ethernet88 type=Port vlan=0 port=ce21 keeprxtag
Interface ID 27: name=Ethernet92 type=Port vlan=0 port=ce22 keeprxtag
Interface ID 28: name=Ethernet96 type=Port vlan=0 port=ce23 keeprxtag
Interface ID 29: name=Ethernet100 type=Port vlan=0 port=ce24 keeprxtag
Interface ID 30: name=Ethernet104 type=Port vlan=0 port=ce25 keeprxtag
Interface ID 31: name=Ethernet108 type=Port vlan=0 port=ce26 keeprxtag
Interface ID 32: name=Ethernet112 type=Port vlan=0 port=ce27 keeprxtag
Interface ID 33: name=Ethernet116 type=Port vlan=0 port=ce28 keeprxtag
Interface ID 34: name=Ethernet120 type=Port vlan=0 port=ce29 keeprxtag
Interface ID 35: name=Ethernet124 type=Port vlan=0 port=ce30 keeprxtag
Interface ID 36: name=Ethernet128 type=Port vlan=0 port=xe4 keeprxtag

knetctrl netif create [Type=<type>] [Vlan=<vid>] [Port=<port>] [RCPU=<bool>] [AddTag=<bool>] [KeepRxTag=<bool>] [IFName=<name>] [CBData=<n>] [ID=<n>]

Create a KNET netif:

With Port=, packets sent on the netdev go straight out of that port.
With RCPU=yes, the netif carries meta-data.
Otherwise packets are injected into the switch pipeline in VLAN Vlan (default 1).

IFName names the Linux netdev, and ID asks for a specific netif ID. AddTag adds a VLAN tag before sending, and KeepRxTag keeps received tags. The shell also accepts Type=Vlan|Port|Meta, which is not in the built-in help; Port and RCPU take precedence over it. On failure the command prints Error creating network interface: <msg>. This changes KNET state.

Unvalidated

drivshell> knetctrl netif create Port=xe0 IFName=dbg0

knetctrl netif destroy <id>

Destroy netif <id> (take it from knetctrl netif show). The Linux netdev disappears with it. If the ID is not a number, the command prints its help. On failure it prints Error destroying network interface: <msg>. Other network operating systems use this command to tear down their own netifs (baseboxd knet_manager.cc).

Warning

Destroying a SONiC EthernetN netif breaks that port’s host packet path.

Unvalidated

drivshell> knetctrl netif destroy <id>

knetctrl filter show

List the KNET filters in match order, one per line, or print <no filters>. Each line starts Filter ID <id>: prio=<p> dest=<Null|NetIF|RxAPI|CallBack>(<dest_id>) desc='<desc>'. The match fields that are set follow, among them mirror=…, striptag, vlan=, vlanmask=, ingport=, srcmod=, srcport=, fprule=, cpucos=, MirrorSts=, reason=, reasonmask=, and the raw packet or out-of-band bytes (rawdata[<offset>]:0x…, OOBrawdata…). Read-only.

On a SONiC switch there is one filter per front-panel port, with priority 100, matching only ingport and delivering to that port’s netif (dest=NetIF(<n>) desc='EthernetN'). The list is in match order, not ID order: filters that were re-created later, for example when a port was reconfigured, appear at the end.

Hardware-validated

drivshell> knetctrl filter show
Filter ID 1: prio=100 dest=NetIF(1) desc='Ethernet0' ingport=ce0
Filter ID 2: prio=100 dest=NetIF(2) desc='Ethernet4' ingport=ce1
Filter ID 3: prio=100 dest=NetIF(3) desc='Ethernet8' ingport=xe0
Filter ID 4: prio=100 dest=NetIF(4) desc='Ethernet9' ingport=xe1
Filter ID 5: prio=100 dest=NetIF(5) desc='Ethernet10' ingport=xe2
Filter ID 7: prio=100 dest=NetIF(7) desc='Ethernet12' ingport=ce2
Filter ID 8: prio=100 dest=NetIF(8) desc='Ethernet16' ingport=ce3
Filter ID 9: prio=100 dest=NetIF(9) desc='Ethernet20' ingport=ce4
Filter ID 10: prio=100 dest=NetIF(10) desc='Ethernet24' ingport=ce5
Filter ID 11: prio=100 dest=NetIF(11) desc='Ethernet28' ingport=ce6
Filter ID 12: prio=100 dest=NetIF(12) desc='Ethernet32' ingport=ce7
Filter ID 13: prio=100 dest=NetIF(13) desc='Ethernet36' ingport=ce8
Filter ID 14: prio=100 dest=NetIF(14) desc='Ethernet40' ingport=ce9
Filter ID 15: prio=100 dest=NetIF(15) desc='Ethernet44' ingport=ce10
Filter ID 16: prio=100 dest=NetIF(16) desc='Ethernet48' ingport=ce11
Filter ID 17: prio=100 dest=NetIF(17) desc='Ethernet52' ingport=ce12
Filter ID 18: prio=100 dest=NetIF(18) desc='Ethernet56' ingport=ce13
Filter ID 19: prio=100 dest=NetIF(19) desc='Ethernet60' ingport=ce14
Filter ID 20: prio=100 dest=NetIF(20) desc='Ethernet64' ingport=ce15
Filter ID 21: prio=100 dest=NetIF(21) desc='Ethernet68' ingport=ce16
Filter ID 22: prio=100 dest=NetIF(22) desc='Ethernet72' ingport=ce17
Filter ID 23: prio=100 dest=NetIF(23) desc='Ethernet76' ingport=ce18
Filter ID 24: prio=100 dest=NetIF(24) desc='Ethernet80' ingport=ce19
Filter ID 25: prio=100 dest=NetIF(25) desc='Ethernet84' ingport=ce20
Filter ID 26: prio=100 dest=NetIF(26) desc='Ethernet88' ingport=ce21
Filter ID 27: prio=100 dest=NetIF(27) desc='Ethernet92' ingport=ce22
Filter ID 28: prio=100 dest=NetIF(28) desc='Ethernet96' ingport=ce23
Filter ID 29: prio=100 dest=NetIF(29) desc='Ethernet100' ingport=ce24
Filter ID 30: prio=100 dest=NetIF(30) desc='Ethernet104' ingport=ce25
Filter ID 31: prio=100 dest=NetIF(31) desc='Ethernet108' ingport=ce26
Filter ID 32: prio=100 dest=NetIF(32) desc='Ethernet112' ingport=ce27
Filter ID 33: prio=100 dest=NetIF(33) desc='Ethernet116' ingport=ce28
Filter ID 36: prio=100 dest=NetIF(36) desc='Ethernet128' ingport=xe4
Filter ID 6: prio=100 dest=NetIF(6) desc='Ethernet11' ingport=xe3
Filter ID 35: prio=100 dest=NetIF(35) desc='Ethernet124' ingport=ce30
Filter ID 34: prio=100 dest=NetIF(34) desc='Ethernet120' ingport=ce29

knetctrl filter create DestType=<Null | NetIF | RxAPI | CallBack> [DestID=<id>] [PRIOrity=<prio>] [DESCription=<str>] [StripTag=<bool>] [Mirror=<bool>] [MirrorID=<id>] [MirrorProto=<n>] [DestProto=<n>] [Vlan=<vid>] [VlanMask=<mask>] [IngPort=<port>] [SrcPort=<n>] [SrcModid=<n>] [Reason=<reason>] [ReasonMask=<reason>] [FPRule=<n>] [CpuCos=<cos>] [MirrorSts=<0|1>] [OobOffset=<n>] [OobByte0..3=<n>] [OobMask0..3=<n>] [PktOffset=<n>] [PktByte0..7=<n>] [CBData=<n>]

Create a KNET filter. DestType chooses where matching packets go:

NetIF: to the netif DestID.
RxAPI: to the user-space receive layer.
Null: dropped.

Priority 0 matches first. Reason and ReasonMask take CPU-reason names. PktByteN and OobByteN (with OobMaskN) match bytes at PktOffset in the packet or at OobOffset in its DMA metadata. An offset that is too large prints PktOffset too large - max is <n> (or the OobOffset equivalent). The shell also accepts DestType=CallBack, MirrorID and MirrorProto (a copy to a second netif), which the built-in help does not list. On failure the command prints Error creating packet filter: <msg>. This changes KNET state.

Unvalidated

drivshell> knetctrl filter create DestType=NetIF DestID=<id> IngPort=xe0 StripTag=yes PRIOrity=0 DESCription=dbg

knetctrl filter destroy <id>

Destroy filter <id> (take it from knetctrl filter show). On failure the command prints Error destroying packet filter: <msg>.

Warning

Destroying a filter that SONiC created silently stops the packets it delivered, for example a trap’s packets to its EthernetN interface.

Unvalidated

drivshell> knetctrl filter destroy <id>

knetctrl debugpkt <on | off | show>

on makes KNET send one extra copy of every packet to the user-space receive layer, for debugging, and off stops the copies. show prints Knet debugging packet function is on! or … is off! and is read-only. Without an argument the command prints Requires string argument. While debug copies are on, every host packet is processed twice. It is off on a SONiC switch.

Hardware-validated

drivshell> knetctrl debugpkt show
Knet debugging packet function is off!

Built-in help

Usages:
  knetctrl netif create [Vlan=<vlan>] [Port=<port>] [RCPU=yes|no]
        Create a virtual network interface.
        Supported options:
          [AddTag=yes|no]      - Add tag before sending to switch port
          [KeepRxTag=yes|no]   - Keep tag of packets which are sent to this netif
          [IFName=<str>]       - Optional network device name
          [CBData=<val>]       - User data for knet rx cb
          [ID=<val>]           - Optional virtual network interface ID
  knetctrl netif destroy <id>
        Destroy a virtual network interface.
  knetctrl netif show
        Show virtual network interfaces.
  knetctrl filter create DestType=Null|NetIF|RxAPI [DestID=<id>] [options]
        Create a packet filter.
        DestID is required for DestType=NetIF only.
        Supported options:
          [DESCription=<str>]  - Optional filter description
          [PRIOrity=<prio>]    - Filter match order priority (0 is highest)
          [StripTag=yes|no]    - Strip VLAN tag before sending packet to NetIF
          [Mirror=yes|no]      - Copy packet to RxAPI (if DestType=NetIF)
          [DestProto=<proto>]  - Override default protocol (if DestType=NetIF)
          [Vlan=<vlan>]        - Match specified VLAN ID
          [VlanMask=<vlan>]    - Mask for vlan ID
          [IngPort=<port>]     - Match specified local ingress port
          [SrcPort=<port>]     - Match specified module port
          [SrcModid=<modid>]   - Match specified module ID
          [Reason=<reason>]    - Match specified reason for copy to CPU
          [ReasonMask=<reason>]- Mask to match copy to CPU reason
          [FPRule=<rule>]      - Match specified FP rule number (if FP match)
          [CpuCos=<cosq>]      - Match specified CPU COS
          [MirrorSts=<val>]    - Match on Mirror status
                                 1:mirrored copy 0:switched copy
          [OobOffset=<offet>]  - Match OOB data starting at this offset
          [OobByteX=<val>]     - Match OOB data byte X (X=[0..3] supported)
          [OobByte0=<val>]     - Match OOB data byte 0 (example)
          [OobMaskX=<val>]     - Match OOB mask byte X (X=[0..3] supported)
          [OobMask0=<val>]     - Match OOB mask byte 0 (example)
          [PktOffset=<offet>]  - Match packet data starting at this offset
          [PktByteX=<val>]     - Match packet data byte X (X=[0..7] supported)
          [PktByte0=<val>]     - Match packet data byte 0 (example)
          [CBData=<val>]       - User data for knet rx cb
  knetctrl filter destroy <id>
        Destroy a packet filter.
  knetctrl filter show
        Show all packet filters.
  knetctrl debugpkt [on|off|show]
        Enable/Disable debugging packet function.
        Once enabling this function, there will be one packet copy being
        sent/mirrored to RX API for debugging usage.