From a416c424b726d9d1bd0b1e5d8dad8e3bfac109f8 Mon Sep 17 00:00:00 2001
From: Max Rottenkolber <max@mr.gy>
Date: Thu, 25 Aug 2022 12:36:57 +0200
Subject: [PATCH] wip

---
 src/lib/yang/snabb-snabbflow-v1.yang          | 281 +++++++++++-------
 src/program/ipfix/probe_ptree/probe_ptree.lua |   5 +-
 src/program/ipfix/probe_ptree/snabbflow.conf  |  16 +-
 3 files changed, 182 insertions(+), 120 deletions(-)

diff --git a/src/lib/yang/snabb-snabbflow-v1.yang b/src/lib/yang/snabb-snabbflow-v1.yang
index fde82f2e35..1c21a62b5c 100644
--- a/src/lib/yang/snabb-snabbflow-v1.yang
+++ b/src/lib/yang/snabb-snabbflow-v1.yang
@@ -16,6 +16,9 @@ module snabb-snabbflow-v1 {
       "Initial draft.";
   }
 
+
+  // Snabbflow configuration
+
   container snabbflow-config {
     description
      "Configuration for the Snabbflow IPFIX exporter.";
@@ -57,16 +60,19 @@ module snabb-snabbflow-v1 {
     container rss {
       description
         "Receive-side scaling (RSS) configuration.
-        The workload is distributed across multiple workers by
-        a) hardware scaling: the device driver used to ingest traffic
-           on an interface serving as an observation point distributes
-           packets across workers.
-        b) software-scaling: traffic is further distributed to exporter
-           instance workers via software RSS.
-           (number of workers = hardware-scaling + hardware-scaling * number of instances with embed: false)
-        The resulting worker processes are bound to CPU cores in cpu-pool.";
+        The IPFIX workload can be scaled across multiple worker processes via
+
+        1. hardware-scaling: the device driver used to ingest traffic
+           on an interface distributes packets across one or more RSS groups.
+
+        2. software-scaling: traffic may further be distributed to any number
+           of dedicated exporter instance workers via software RSS.";
 
       container cpu-pool {
+        description
+          "Snabbflow worker processes are bound to CPU cores
+          from the cpu-pool.";
+
         leaf-list cpu {
           type uint32;
           description
@@ -75,73 +81,124 @@ module snabb-snabbflow-v1 {
       }
 
       container hardware-scaling {
+        description
+          "Snabbflow supports hardware assisted RSS to scale the workload
+          across one ore more RSS groups. Each RSS group is handled by a
+          dedicated worker process.";
+        
         leaf rss-groups {
           type uint32 { range 1..64; }
           default 1;
           description
-            "N-way hardware-assisted RSS scaling.";
+            "Number of hardware-assisted RSS groups used for scaling.";
         }
       }
 
       container software-scaling {
         description
-          "Software RSS configuration.";
+          "In addition to hardware assisted RSS Snabbflow supports
+          software RSS. For each IPFIX exporter, traffic is scaled across
+          one or more exporter instances in each RSS group.";
 
         list exporter {
-          key name;
+          key "name";
           description
-            "XXX";
+            "Sofware RSS configuration for the selected exporter.";
 
           leaf name {
-            type string;
+            type string-name;
+            description
+              "The 'name' of an exporter defined in
+              /snabbflow-config/ipfix/exporter.";
           }
 
-          leaf class {
-            type string;
-            default "default";
+          leaf embed {
+            type boolean;
+            default true;
             description
+              "By default a single instance of each exporter is embedded
+              in each RSS group worker process.
+              
+              If set to false, then for each RSS group the exporter is
+              executed in one or more instances, each in its own dedicated
+              worker process (using a dedicated CPU core).";
           }
           
           leaf instances {
-            type uint32 { range 1..64; }
+            type uint32 { range 1..max; }
             default 1;
             description
-              "XXX";
+              "When 'embed' is false, number of exporter instances per
+              RSS group. Has no effect when 'embed' is set to true.";
           }
 
-          leaf embed {
-            type boolean;
-            default true;
+          container restart {
             description
-              "If this is set to false, this instance will not be assigned
-              a dedicated process (and CPU core), but will instead be
-              embedded within one of the processes used to
-              realize 'hardware-scaling'.";
+              "Restart policy for exporter instance workers.
+              Exporter workers will be restarted if they crash unless they
+              would exceed the configured restart policy.
+              The restart policy is expressed as follows: a process may be
+              restarted up to 'intensity' times within 'period' seconds.
+              Setting 'intensity' to 0 effectively disables restarts.";
+
+            leaf intensity {
+              type decimal64 { range 0..max; }
+              default 5;
+              description
+                "The number of restarts permitted within a given time period.
+                Setting the intensity to 0 effectively disables restarts.";
+            }
+
+            leaf period {
+              type decimal64 { range 0..max; }
+              default 30;
+              description
+                "The duration of the time period in seconds.";
+            }
           }
         }
       }
 
-      container traffic-classes {
+      container flow-director {
+        description
+          "Snabbflow supports distinct sets of flows being processed by
+          any number of exporters.
+          
+          Each exporter selects a traffic class matching the set of flows
+          it should process. A traffic class can be processed by multple
+          exporters. The 'default' class matches all packets.";
+        
+        leaf default-class {
+          type boolean;
+          default true;
+          description
+            "If this is set to false, packets not matching any other class
+            are dropped, and the catch-all traffic class 'default' does not
+            match any packets/flows.";
+        }
 
         list class {
           key "name order";
-
           description
-            "Traffic classes to be aggregated in exporters.";
+            "A traffic class matches packets making up a set of flows.
+            
+            Classes are ordered and matched in sequence. Packets may match
+            multiple classes unless a previous match terminates matching of
+            the packet.";
 
           ordered-by user; // XXX not yet implemented, hence the 'order' leaf
 
           leaf name {
-            type string;
+            type string-name;
             description
-              "Identifier of the class. This is used to refer to a class in
-              the exporter configuration.";
+              "Identifier of the class. This is used to select the class in
+              /snabbflow-config/ipfix/exporter.";
           }
 
           leaf order {
             type uint32;
             description
-              "Processing order of this class.";
+              "Match order of this class.";
           }
           
           leaf filter {
@@ -157,26 +214,19 @@ module snabb-snabbflow-v1 {
             default false;
             description
               "If set to true, a packet matching this class can also match
-              further consecutive classes (in processing order).";
+              further consecutive classes (in match order)
+              By default the matching of a packet to a class terminates
+              the matching process.";
           }
         }
-      }
 
-      leaf default-traffic-class {
-        type boolean;
-        default true;
-        description
-          "If this is set to false, packets not matching any class
-          are dropped, and the catch-all traffic class 'default' is
-          not created.";
-      }
-
-      leaf remove-ipv6-extension-headers {
-        type boolean;
-        default true;
-        description
-          "IPv6 extention headers are stripped from packets unless this
-          is set to false.";
+        leaf remove-ipv6-extension-headers {
+          type boolean;
+          default true;
+          description
+            "IPv6 extention headers are stripped from packets unless this
+            is set to false.";
+        }
       }
     }
 
@@ -334,10 +384,10 @@ module snabb-snabbflow-v1 {
           distribute exported flows across the collectors in a pool.";
 
         leaf name { 
-          type string;
+          type string-name;
           description
-            "Identifier used to refer to the collector pool used by
-            an exporter.";
+            "Identifier used to refer to the collector pool in
+            /snabbflow-config/ipic/exporter.";
         }
 
         list collector {
@@ -374,17 +424,23 @@ module snabb-snabbflow-v1 {
       list exporter {
         key "name";
         description
-          "Set of configured exporters. Each exporter receives traffic
-          matching a single class defined in 'rss/software-scaling',
+          "Set of configured exporters. Each exporter receives flows
+          matching a single class defined in /snabbflow-config/rss/flow-director,
           aggregates flows according to a set of templates, and
-          exports them to a specified 'collector-pool'.
-          Exporters can be instantiated and thereby scaled across
-          multiple CPU cores.";
+          exports them to a specified /snabbflow-config/ipfix/collector-pool.";
 
         leaf name {
-          type string;
+          type string-name;
           description
-            "The name used to refer to this exporter.";
+            "The name used to refer to this exporter in
+            /snabbflow-config/rss/software-scaling.";
+        }
+
+        leaf traffic-class {
+          type string-name;
+          default "default";
+          description
+            "A traffic class defined in /snabbflow-config/rss/flow-director.";
         }
 
         leaf-list template {
@@ -397,94 +453,97 @@ module snabb-snabbflow-v1 {
         leaf collector-pool {
           type string;
           description
-            "The 'name' of a 'collector-pool' to be used as an endpoint
-            for this exporter.";
-        }
-
-        container restart {
-          description
-            "Restart policy for exporter instances with embed: false.
-            Exporter processes will be restarted if they crash unless they
-            would exceed the configured restart policy.
-            The restart policy is expressed as follows: a process may be
-            restarted up to 'intensity' times within 'period' seconds.
-            Setting 'intensity' to 0 effectively disables restarts.";
-          leaf intensity {
-            type decimal64 { range 0..max; }
-            default 5;
-            description
-              "The number of restarts permitted within a given time period.
-              Setting the intensity to 0 effectively disables restarts.";
-          }
-          leaf period {
-            type decimal64 { range 0..max; }
-            default 30;
-            description
-              "The duration of the time period in seconds.";
-          }
+            "A collector pool defined in /snabbflow-config/ipfix/collector-pool.";
         }
       }
     }
   }
 
+
+  // Types 
+  
+  typedef string-name {
+    type string { pattern '[\w_]+'; }
+    description
+      "A string name used to refer to various Snabbflow components.";
+  }
+
+  typedef numeric-id {
+    type uint32 { range "1..max"; }
+    description
+      "A numeric identifier.";
+  }
+
+  typedef pci-address {
+    type string {
+      pattern '([0-9a-fA-F]{4}:)?[0-9a-fA-F]{2}:[0-9a-fA-F]{2}\.[0-9a-fA-F]';
+    }
+    description
+      "The bus address of a PCI device.";
+  }
+
+
+  // Snabbflow state
+
   container snabbflow-state {
     config false;
     description
-     "State counters for the Snabbflow IPFIX exporter.";
+     "Inspectable state for the Snabbflow IPFIX exporter.";
 
     list interface {
       key "device";
       description
         "Network device statistics";
+
       uses interface-state;
     }
 
     list exporter {
       key "name";
       description
-        "Exporter statistics."
+        "Exporter statistics.";
 
       leaf name {
-        type string;
+        type string-name;
+        description
+          "An exporter defined in /snabbflow-config/ipfix/exporter.";
       }
 
       uses exporter-state;
 
       list template {
         key "id";
-
-        leaf id {
-          type uint32;
-        }
+        description
+          "Template statistics.";
 
         uses template-state;
       }
     }
 
     list rss-group {
-      key id;
-
-      leaf id {
-        type uint32;
-      }
+      key "pid";
+      description
+        "Statistics for the RSS group workers defined in
+        /snabbflow-config/rss/hardware-scaling.";
 
       uses worker-state;
 
       list exporter {
         key "name";
         description
-          "Exporter statistics."
+          "Exporter statistics for this RSS group as per
+          /snabbflow-config/rss/software-scaling.";
 
         leaf name {
-          type string;
+          type string-name;
+          description
+            "An exporter defined in /snabbflow-config/ipfix/exporter.";
         }
 
         list instance {
-          key id;
-
-          leaf id {
-            type uint32;
-          }
+          key "pid";
+          description
+            "Statistics for exporter instance workers for this RSS group.";
 
           uses worker-state;
           uses exporter-state;
@@ -492,10 +551,8 @@ module snabb-snabbflow-v1 {
 
           list template {
             key "id";
-
-            leaf id {
-              type uint32;
-            }
+            description
+              "Statistics for template instances.";
 
             uses template-state;
             uses template-instance-state;
@@ -569,11 +626,17 @@ module snabb-snabbflow-v1 {
       leaf pid {
         type uint32;
         description
-          "Process identifier of this exporter instance.";
+          "Process identifier of this worker.";
       }
     }
 
-    grouping table-state {
+    grouping template-state {
+      leaf id {
+        type numeric-id;
+        description
+          "Template ID. See apps/ipfix/README.templates.md.";
+      }
+
       leaf packets-processed {
         type yang:zero-based-counter64;
         description
diff --git a/src/program/ipfix/probe_ptree/probe_ptree.lua b/src/program/ipfix/probe_ptree/probe_ptree.lua
index d6ed389437..d73ed54e62 100644
--- a/src/program/ipfix/probe_ptree/probe_ptree.lua
+++ b/src/program/ipfix/probe_ptree/probe_ptree.lua
@@ -109,7 +109,7 @@ function setup_workers (config)
 
    update_cpuset(rss.cpu_pool)
 
-   for rssq = 0, rss.hardware_scaling-1 do
+   for rssq = 0, rss.hardware_scaling.rss_groups-1 do
       local inputs, outputs = {}, {}
       for device, opt in pairs(interfaces) do
          local input = lib.deepcopy(opt)
@@ -161,6 +161,9 @@ function setup_workers (config)
             config.maps = maps
          end
 
+         local software_scaling = rss.software_scaling.exporter[name]
+                               or default_software_scaling(name)
+         -- XXX
          local num_instances = 0
          for _ in pairs(exporter.instance) do
             num_instances = num_instances + 1
diff --git a/src/program/ipfix/probe_ptree/snabbflow.conf b/src/program/ipfix/probe_ptree/snabbflow.conf
index 28d7325ef7..ed1df796b3 100644
--- a/src/program/ipfix/probe_ptree/snabbflow.conf
+++ b/src/program/ipfix/probe_ptree/snabbflow.conf
@@ -23,17 +23,13 @@ snabbflow-config {
         software-scaling {
             exporter {
                 name e1;
-                class ip;
+                embed false;
                 instances 2;
             }
-            exporter {
-                name e2;
-                class ip6;
-                embed true;
-            }
         }
 
-        traffic-classes {
+        flow-director {
+            default-class false;
             class {
                 name ip6;
                 order 1;
@@ -45,10 +41,8 @@ snabbflow-config {
                 order 2;
                 filter ip;
             }
+            remove-ipv6-extension-headers true;
         }
-
-        default-traffic-class false;
-        remove-ipv6-extension-headers true;
     }
 
     ipfix {
@@ -71,12 +65,14 @@ snabbflow-config {
 
         exporter {
             name e1;
+            class ip;
             template "v4_extended";
             collector-pool c1;
         }
 
         exporter {
             name e2;
+            class ip6;
             template "v6_extended";
             collector-pool c1;
         }