Skip to content

DPAA2 restool

restool is a user space tool that allows DPAA2 resources to be manipulated dynamically.

Uses of restool include:

  • Creating new network interfaces (DPNIs)
  • Viewing Ethernet MAC (DPMAC statistics)
  • Creating new DPRC containers to contain DPAA2 objects
  • Unlinking/removing existing DPAA2 objects from the current DPRC

Apart from restool itself, there are several utility programs such as:

  • ls-listni - List DPNIs and their corresponding Linux interface name
  • ls-listmac - List DPMACs
  • ls-addmux - Create DPDMUX/data center bridge
  • ls-addsw - Create a switch object (not applicable to LS1088)

NXP also provides additional scripts, such as dynamic_dpl.sh to automate configuration for certain use cases such as DPDK and DPAA2 passthrough/VFIO.

Requirements

Restool support is not present in mainline kernels at this time. It is present in NXP LSDK patchsets and derivatives, such as our OpenWrt, uVirt and Recovery images.

CONFIG_FSL_MC_UAPI_SUPPORT=y must be enabled in the kernel configuration.

The latest proposed patch for mainline restool support (to our knowledge) is from March 2018.

The restool source repository can be found at CodeAurora.org.

Usage Examples

ls-listni

root@OpenWrt:/# ls-listni
dprc.1/dpni.9 (interface: eth0, end point: dpmac.7)
dprc.1/dpni.8 (interface: eth1, end point: dpmac.8)
dprc.1/dpni.7 (interface: eth2, end point: dpmac.9)
dprc.1/dpni.6 (interface: eth3, end point: dpmac.10)
dprc.1/dpni.5 (interface: eth4, end point: dpmac.3)
dprc.1/dpni.4 (interface: eth5, end point: dpmac.4)
dprc.1/dpni.3 (interface: eth6, end point: dpmac.5)
dprc.1/dpni.2 (interface: eth7, end point: dpmac.6)
dprc.1/dpni.1 (interface: eth8, end point: dpmac.2)
dprc.1/dpni.0 (interface: eth9, end point: dpmac.1)

ls-listmac

root@OpenWrt:/# ls-listmac
dprc.1/dpmac.10 (end point: dpni.6)
dprc.1/dpmac.9 (end point: dpni.7)
dprc.1/dpmac.8 (end point: dpni.8)
dprc.1/dpmac.7 (end point: dpni.9)
dprc.1/dpmac.6 (end point: dpni.2)
dprc.1/dpmac.5 (end point: dpni.3)
dprc.1/dpmac.4 (end point: dpni.4)
dprc.1/dpmac.3 (end point: dpni.5)
dprc.1/dpmac.2 (end point: dpni.1)
dprc.1/dpmac.1 (end point: dpni.0)

Creating a DPNI

Note: This assumes you have DPNIs available to create - if you are using the default DPL - they are all allocated already.

root@OpenWrt:/# ls-addni --fs-entries=1 dpmac.2
[   49.653234] fsl_dpaa2_eth dpni.1: Adding to iommu group 1
[   49.750369] fsl_dpaa2_eth dpni.1: Probed interface eth1
[   49.755887] fsl_mc_allocator dpbp.10: Adding to iommu group 1
[   49.763027] fsl_mc_allocator dpmcp.35: Adding to iommu group 1
[   49.769303] fsl_mc_allocator dpcon.80: Adding to iommu group 1
[   49.773669] fsl_dpaa2_eth dpni.1 eth1: Link Event: state up
[   49.774154] fsl_dpaa2_eth dpni.1 eth1: Link Event: state up
[   49.775300] fsl_mc_allocator dpcon.79: Adding to iommu group 1
[   49.792405] fsl_mc_allocator dpcon.78: Adding to iommu group 1
[   49.798420] fsl_mc_allocator dpcon.77: Adding to iommu group 1
[   49.804394] fsl_mc_allocator dpcon.76: Adding to iommu group 1
[   49.810356] fsl_mc_allocator dpcon.75: Adding to iommu group 1
[   49.816410] fsl_mc_allocator dpcon.74: Adding to iommu group 1
[   49.822431] fsl_mc_allocator dpcon.73: Adding to iommu group 1
Created interface: eth1 (object:dpni.1, endpoint: dpmac.2)
root@OpenWrt:/# ls-listni
dprc.1/dpni.1 (interface: eth1, end point: dpmac.2)
dprc.1/dpni.0 (interface: eth0, end point: dpmac.7)

Removing a DPNI / unbinding from Linux

Removing a DPNI by itself can be difficult because the DPNI has associated resources (dpcon's, dpbp, dpmcp's as seen above). It is easier to destroy the entire container - NXP's own scripts do exactly that.

If the DPNI is consumed by a Linux ethernet device, you will need to unbind first:

root@OpenWrt:/# ls-listni
dprc.1/dpni.1 (interface: eth1, end point: dpmac.2)
dprc.1/dpni.0 (interface: eth0, end point: dpmac.7)
root@OpenWrt:/# echo 'dpni.1' > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind
[  315.294020] fsl_dpaa2_eth dpni.1 eth1: Link Event: state down
root@OpenWrt:/# ifconfig eth1
ifconfig: eth1: error fetching interface information: Device not found
root@OpenWrt:/# restool dpni destroy dpni.1
dpni.1 is destroyed
root@OpenWrt:/# [  325.639520] fsl-mc dpni.1: Removing from iommu group 1
root@OpenWrt:/# ls-listni
dprc.1/dpni.0 (interface: eth0, end point: dpmac.7)

Dumping the current DPL

root@OpenWrt:/# restool dprc generate-dpl
/dts-v1/;
/ {
        dpl-version = <10>;
        /*****************************************************************
         * Containers
         *****************************************************************/
        containers {
....
....
....
                connection@10{
                        endpoint1 = "dpni@9";
                        endpoint2 = "dpmac@7";
                };
        };
};

Viewing MAC counters

root@OpenWrt:/# restool dpmac info dpmac.5
dpmac version: 4.4
dpmac object id/portal id: 5
plugged state: plugged
endpoint state: 1
endpoint: dpni.3, link is up
DPMAC link type: DPMAC_LINK_TYPE_FIXED
DPMAC ethernet interface: DPMAC_ETH_IF_QSGMII
maximum supported rate 1000 Mbps
Counters:
rx all frames: 70484
rx frames ok: 70484
rx frame errors: 0
rx frame discards: 0
rx u-cast: 70443
rx b-cast: 6
rx m-cast: 35
rx 64 bytes: 21
rx 65-127 bytes: 1033
rx 128-255 bytes: 25
rx 256-511 bytes: 6
rx 512-1023 bytes: 900
rx 1024-1518 bytes: 68499
rx 1519-max bytes: 0
rx frags: 0
rx jabber: 0
rx align errors: 0
rx oversized: 0
rx pause: 0
rx bytes: 104940085
tx frames ok: 35307
tx u-cast: 35291
tx m-cast: 13
tx b-cast: 3
tx frame errors: 0
tx undersized: 0
tx b-pause: 0
tx bytes: 2473258

Viewing DPNI counters

root@OpenWrt:/# restool dpni info dpni.3
dpni version: 7.13
dpni id: 3
plugged state: plugged
endpoint state: 1
endpoint: dpmac.5, link is up
link status: 1 - up
mac address: 00:0a:fa:24:24:31
dpni_attr.options value is: 0
num_queues: 1
num_cgs: 1
num_rx_tcs: 1
num_tx_tcs: 1
mac_entries: 16
vlan_entries: 0
qos_entries: 0
fs_entries: 1
qos_key_size: 0
fs_key_size: 56
ingress_all_frames: 70454
ingress_all_bytes: 104656040
ingress_multicast_frames: 3
ingress_multicast_bytes: 240
ingress_broadcast_frames: 8
ingress_broadcast_bytes: 706
egress_all_frames: 35307
egress_all_bytes: 2332012
egress_multicast_frames: 13
egress_multicast_bytes: 1513
egress_broadcast_frames: 3
egress_broadcast_bytes: 1032
ingress_filtered_frames: 189
ingress_discarded_frames: 0
ingress_nobuffer_discards: 0
egress_discarded_frames: 0
egress_confirmed_frames: 35307