module_msg.proto

// Copyright (c) 2016-2017, Nefeli Networks, Inc.
// Copyright (c) 2017, The Regents of the University of California.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// * Redistributions of source code must retain the above copyright notice, this
// list of conditions and the following disclaimer.
//
// * Redistributions in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
//
// * Neither the names of the copyright holders nor the names of their
// contributors may be used to endorse or promote products derived from this
// software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.

syntax = "proto3";

package bess.pb;
import "util_msg.proto";

// Module-specific messages.
// The header generated from this file should not be included in the BESS core
// source code.

// For your comments to come out in the auto-documentation:
// Format comments with two stars at the top, or use three slashes (///)
// Anything you write will show up as markdown, so feel free to add italics, etc.

/// The module_msg.proto file is stored in `bess/protobuf/` and it supplies the glue between
/// bessd modules and the outside world via GRPC.
/// bessctl uses GRPC to update modules. Whenever you call a function in bessctl, a corresponding function
/// is called on modules in bessd. This file lists all modules, their initialization parameters
/// and any functions that may be called on them.

message EmptyArg {
}

/**
 * The BPF module has a command `clear()` that takes no parameters.
 * This command removes all filters from the module.
 */
message BPFCommandClearArg {
}

/**
 * The ExactMatch module has a command `add(...)` that takes two parameters.
 * The ExactMatch initializer specifies what fields in a packet to inspect; add() specifies
 * which values to check for over these fields.
 * add() inserts a new rule into the ExactMatch module such that traffic matching
 * that bytestring will be forwarded
 * out a specified gate.
 * Example use: `add(fields=[aton('12.3.4.5'), aton('5.4.3.2')], gate=2)`
 */
message ExactMatchCommandAddArg {
  uint64 gate = 1; /// The gate to forward out packets that mach this rule.
  repeated FieldData fields = 2; /// The exact match values to check for
}

/**
 * The ExactMatch module has a command `delete(...)` which deletes an existing rule.
 * Example use: `delete(fields=[aton('12.3.4.5'), aton('5.4.3.2')])`
 */
message ExactMatchCommandDeleteArg {
  repeated FieldData fields = 2; /// The field values for the rule to be deleted.
}

/**
 * The ExactMatch module has a command `clear()` which takes no parameters.
 * This command removes all rules from the ExactMatch module.
 */
message ExactMatchCommandClearArg {
}

/**
 * The ExactMatch module has a command `set_default_gate(...)` which takes one parameter.
 * This command routes all traffic which does _not_ match a rule to a specified gate.
 * Example use in bessctl: `setDefaultGate(gate=2)`
 */
message ExactMatchCommandSetDefaultGateArg {
  uint64 gate = 1; /// The gate number to send the default traffic out.
}

/**
 * The FlowGen module has a command `set_burst(...)` that allows you to specify
 * the maximum number of packets to be stored in a single PacketBatch released
 * by the module.
 */
message FlowGenCommandSetBurstArg {
  uint64 burst = 1;
}

/**
 * The HashLB module has a command `set_mode(...)` which takes two parameters.
 * The `mode` parameter specifies whether the load balancer will hash over the
 * src/dest ethernet header (`'l2'`), over the src/dest IP addresses (`'l3'`), or over
 * the flow 5-tuple (`'l4'`).  Alternatively, if the `fields` parameter is set, the
 * load balancer will hash over the N-tuple with the specified offsets and
 * sizes.
 * Example use in bessctl: `lb.set_mode('l2')`
 */
message HashLBCommandSetModeArg {
  string mode = 1; /// What fields to hash over, `'l2'`, `'l3'`, and `'l4'` are only valid values.
  repeated Field fields = 2; /// A list of fields that define a custom tuple.
}

/**
 * The HashLB module has a command `set_gates(...)` which takes one parameter.
 * This function takes in a list of gate numbers to send hashed traffic out over.
 * Example use in bessctl: `lb.setGates(gates=[0,1,2,3])`
 */
message HashLBCommandSetGatesArg {
  repeated int64 gates = 1; ///A list of gate numbers to load balance traffic over
}

/**
 * The IPLookup module has a command `add(...)` which takes three paramters.
 * This function accepts the routing rules -- CIDR prefix, CIDR prefix length,
 * and what gate to forward matching traffic out on.
 * Example use in bessctl: `table.add(prefix='10.0.0.0', prefix_len=8, gate=2)`
 */
message IPLookupCommandAddArg {
  string prefix = 1; /// The CIDR IP part of the prefix to match
  uint64 prefix_len = 2; /// The prefix length
  uint64 gate = 3; /// The number of the gate to forward matching traffic on.
}

/**
 * The IPLookup module has a command `delete(...)` which takes two paramters.
 * This function accepts the routing rules -- CIDR prefix, CIDR prefix length,
 * Example use in bessctl: `table.delete(prefix='10.0.0.0', prefix_len=8)`
 */
message IPLookupCommandDeleteArg {
  string prefix = 1; /// The CIDR IP part of the prefix to match
  uint64 prefix_len = 2; /// The prefix length
}

/**
 * The IPLookup module has a command `clear()` which takes no parameters.
 * This function removes all rules in the IPLookup table.
 * Example use in bessctl: `myiplookuptable.clear()`
 */
message IPLookupCommandClearArg {
}

/**
 * The L2Forward module forwards traffic via exact match over the Ethernet
 * destination address. The command `add(...)`  allows you to specifiy a
 * MAC address and which gate the L2Forward module should direct it out of.
 */
message L2ForwardCommandAddArg {
  message Entry {
    string addr = 1; /// The MAC address to match
    int64 gate = 2; /// Which gate to send out traffic matching this address.
  }
  repeated Entry entries = 1; /// A list of L2Forward entries.
}

/**
 * The L2Forward module has a function `delete(...)` to remove a rule
 * from the MAC forwarding table.
 */
message L2ForwardCommandDeleteArg {
  repeated string addrs = 1; /// The address to remove from the forwarding table
}

/**
 * For traffic reaching the L2Forward module which does not match a MAC rule,
 * the function `set_default_gate(...)` allows you to specify a default gate
 * to direct unmatched traffic to.
 */
message L2ForwardCommandSetDefaultGateArg {
  int64 gate = 1; /// The default gate to forward traffic which matches no entry to.
}

/**
 * The L2Forward module has a function `lookup(...)` to query what output gate
 * a given MAC address will be forwared to; it returns the gate ID number.
 */
message L2ForwardCommandLookupArg {
  repeated string addrs = 1; /// The MAC address to query for
}

/**
 * This message type provides the reponse to the L2Forward function `lookup(..)`.
 * It returns the gate that a requested MAC address is currently assigned to.
 */
message L2ForwardCommandLookupResponse {
  repeated uint64 gates = 1; /// The gate ID that the requested MAC address maps to
}

/**
 * The L2Forward module has a command `populate(...)` which allows for fast creation
 * of the forwarding table given a range of MAC addresses. The function takes in a
 * 'base' MAC address, a count (number of MAC addresses), and a gate_id. The module
 * will route all MAC addresses starting from the base address, up to base+count address
 * round-robin over gate_count total gates.
 * For example, `populate(base='11:22:33:44:00', count = 10, gate_count = 2)` would
 * route addresses `11:22:33:44::(00, 02, 04, 06, 08)` out a gate 0 and the odd-suffixed
 * addresses out gate 1.
 */
message L2ForwardCommandPopulateArg {
  string base = 1; /// The base MAC address
  int64 count = 2; /// How many addresses beyond base to populate into the routing table
  int64 gate_count = 3; /// How many gates to create in the L2Forward module.
}

/**
 * The Measure module measures and collects latency/jitter data for packets
 * annotated by a Timestamp module. Note that Timestamp and Measure module must reside
 * on the server for accurate measurement (as a result, the most typical use case is
 * measuring roundtrip time).
 * Optionally, you can also retrieve percentile values by specifying points in
 * "percentiles". For example, "percentiles" of [50.0, 99.0] will return
 * [median, 99'th %-ile tail latency] in "percentile_values_ns" in the response.
 */
message MeasureCommandGetSummaryArg {
  bool clear = 1; /// if true, the data will be all cleared after read
  repeated double latency_percentiles = 2; /// ascending list of real numbers in [0.0, 100.0]
  repeated double jitter_percentiles = 3; /// ascending list of real numbers in [0.0, 100.0]
}

/**
 * The Measure module function `get_summary()` returns the following values.
 * Note that the resolution value tells you how grainy the samples are,
 * e.g., 100 means that anything from 0-99 ns counts as "0",
 * anything from 100-199 counts as "100", and so on.  The average
 * is of samples using this graininess, but (being a result of division)
 * may not be a multiple of the resolution.
 */
message MeasureCommandGetSummaryResponse {
  message Histogram {
    uint64 count = 1; /// Total # of measured data points, including above_range
    uint64 above_range = 2; /// # of data points for the "too large value" bucket
    uint64 resolution_ns = 8; /// resolution of measured data
    uint64 min_ns = 3;
    uint64 avg_ns = 4;
    uint64 max_ns = 5;
    uint64 total_ns = 6;
    repeated uint64 percentile_values_ns = 7;
  }

  double timestamp = 1; /// Seconds since boot.
  uint64 packets = 2; /// Total # of packets seen by this module.
  uint64 bits = 3; /// Total # of bits seen by this module.
  Histogram latency = 4;
  Histogram jitter = 5;
}


/**
 * The Module DRR provides fair scheduling of flows based on a quantum which is
 * number of bytes allocated to each flow on each round of going through all flows.
 * Examples can be found [./bessctl/conf/samples/drr.bess]
 *
 * __Input_Gates__: 1
 * __Output_Gates__:  1
 */
message DRRArg {
  uint32 num_flows = 1;  /// Number of flows to handle in module
  uint64 quantum = 2;  /// the number of bytes to allocate to each on every round
  uint32 max_flow_queue_size = 3; /// the max size that any Flows queue can get
}

/**
 * the SetQuantumSize function sets a new quantum for DRR module to operate on.
 */
message DRRQuantumArg {
  uint32 quantum = 1;  /// the number of bytes to allocate to each on every round
}

/**
 * The SetMaxQueueSize function sets a new maximum flow queue size for DRR module.
 * If the flow's queue gets to this size, the module starts dropping packets to
 * that flow until the queue is below this size.
 */
message DRRMaxFlowQueueSizeArg {
  uint32 max_queue_size = 1;  /// the max size that any Flows queue can get
}

/**
 * The module PortInc has a function `set_burst(...)` that allows you to specify the
 * maximum number of packets to be stored in a single PacketBatch released by
 * the module.
 */
message PortIncCommandSetBurstArg {
  uint64 burst = 1; /// The maximum "burst" of packets (ie, the maximum batch size)
}

/**
 * The module QueueInc has a function `set_burst(...)` that allows you to specify
 * the maximum number of packets to be stored in a single PacketBatch released
 * by the module.
 */
message QueueIncCommandSetBurstArg {
  uint64 burst = 1; /// The maximum "burst" of packets (ie, the maximum batch size)
}

/**
 * The module Queue has a function `set_burst(...)` that allows you to specify
 * the maximum number of packets to be stored in a single PacketBatch released
 * by the module.
 */
message QueueCommandSetBurstArg {
  uint64 burst = 1; /// The maximum "burst" of packets (ie, the maximum batch size)
}

/**
 * The module Queue has a function `set_size(...)` that allows specifying the
 * size of the queue in total number of packets.
 */
message QueueCommandSetSizeArg {
  uint64 size = 1; /// The maximum number of packets to store in the queue.
}

/**
 * Modules that are queues or contain queues may contain functions
 * `get_status()` that return QueueCommandGetStatusResponse.
 */
message QueueCommandGetStatusArg {}

/**
 * Modules that are queues or contain queues may contain functions
 * `get_status()` that take no parameters and returns the queue occupancy and
 * size.
 */
message QueueCommandGetStatusResponse {
  uint64 count = 1;    /// The number of packets currently in the queue.
  uint64 size = 2;     /// The maximum number of packets the queue can contain.
  uint64 enqueued = 3; /// total enqueued
  uint64 dequeued = 4; /// total dequeued
  uint64 dropped = 5;  /// total dropped
}

/**
 * The function `clear()` for RandomUpdate takes no parameters and clears all
 * state in the module.
 */
message RandomUpdateCommandClearArg {
}

/**
 * The function `clear()` for Rewrite takes no parameters and clears all state
 * in the module.
 */
message RewriteCommandClearArg {
}

/**
 * The function `clear()` for Update takes no parameters and clears all state in
 * the module.
 */
message UpdateCommandClearArg {
}

/**
 * The module WildcardMatch has a command `add(...)` which inserts a new rule
 * into the WildcardMatch module. For an example of code using WilcardMatch see
 * `bess/bessctl/conf/samples/wildcardmatch.bess`.
 */
message WildcardMatchCommandAddArg {
  uint64 gate = 1; /// Traffic matching this new rule will be sent to this gate.
  int64 priority = 2; ///If a packet matches multiple rules, the rule with higher priority will be applied. If priorities are equal behavior is undefined.
  repeated FieldData values = 3; /// The values to check for in each field.
  repeated FieldData masks = 4; /// The bitmask for each field -- set `0x0` to ignore the field altogether.
}

/**
 * The module WildcardMatch has a command `delete(...)` which removes a rule -- simply specify the values and masks from the previously inserted rule to remove them.
 */
message WildcardMatchCommandDeleteArg {
  repeated FieldData values = 1; /// The values being checked for in the rule
  repeated FieldData masks = 2; /// The bitmask from the rule.
}

/**
 * The function `clear()` for WildcardMatch takes no parameters, it clears
 * all state in the WildcardMatch module (is equivalent to calling delete for all rules)
 */
message WildcardMatchCommandClearArg {
}

/**
 * For traffic which does not match any rule in the WildcardMatch module,
 * the `set_default_gate(...)` function specifies which gate to send this extra traffic to.
 */
message WildcardMatchCommandSetDefaultGateArg {
  uint64 gate = 1;
}

/**
 * The module ACL creates an access control module which by default blocks all traffic, unless it contains a rule which specifies otherwise.
 * Examples of ACL can be found in [acl.bess](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/acl.bess)
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message ACLArg {
  /**
   * One ACL rule is represented by the following 6-tuple.
   */
  message Rule {
    string src_ip = 1;    /// Source IP block in CIDR. Wildcard if "".
    string dst_ip = 2;    /// Destination IP block in CIDR. Wildcard if "".
    uint32 src_port = 3;  /// TCP/UDP source port. Wildcard if 0.
    uint32 dst_port = 4;  /// TCP/UDP Destination port. Wildcard if 0.
    bool established = 5; /// Not implemented
    bool drop = 6;        /// Drop matched packets if true, forward if false. By default ACL drops all traffic.
  }
  repeated Rule rules = 1; ///A list of ACL rules.
}

/**
 * The BPF module is an access control module that sends packets out on a particular gate based on whether they match a BPF filter.
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable)
 */
message BPFArg {
  /**
   * One BPF filter is represented by the following 3-tuple.
   */
  message Filter {
    int64 priority = 1; /// The priority level for this rule. If a packet matches multiple rules, it will be forwarded out the gate with the highest priority. If a packet matches multiple rules with the same priority, the behavior is undefined.
    string filter = 2; /// The actual BPF string.
    int64 gate = 3; ///What gate to forward packets that match this BPF to.
  }
  repeated Filter filters = 1; /// The BPF initialized function takes a list of BPF filters.
}

/**
 * The Buffer module takes no parameters to initialize (ie, `Buffer()` is sufficient to create one).
 * Buffer accepts packets and stores them; it may forward them to the next module only after it has
 * received enough packets to fill an entire PacketBatch.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message BufferArg {
}

/**
 * The Bypass module forwards packets by emulating pre-defined packet processing overhead.
 * It burns cpu cycles per_batch, per_packet, and per-bytes.
 * Bypass is useful primarily for testing and performance evaluation.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message BypassArg {
  uint32 cycles_per_batch = 1;
  uint32 cycles_per_packet = 2;
  uint32 cycles_per_byte = 3;
}

/**
 * The Dump module blindly forwards packets without modifying them. It periodically samples a packet and prints out out to the BESS log (by default stored in `/tmp/bessd.INFO`).
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message DumpArg {
  double interval = 1; ///How frequently to sample and print a packet, in seconds.
}

/**
 * The EtherEncap module wraps packets in an Ethernet header, but it takes no parameters. Instead, Ethernet source, destination, and type are pulled from a packet's metadata attributes.
 * For example: `SetMetadata('dst_mac', 11:22:33:44:55) -> EtherEncap()`
 * This is useful when upstream modules wish to assign a MAC address to a packet, e.g., due to an ARP request.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message EtherEncapArg {
}

/**
 * The ExactMatch module splits packets along output gates according to exact match values in arbitrary packet fields.
 * To instantiate an ExactMatch module, you must specify which fields in the packet to match over. You can add rules using the function `ExactMatch.add(...)`
 * Fields may be stored either in the packet data or its metadata attributes.
 * An example script using the ExactMatch code is found
 * in [`bess/bessctl/conf/samples/exactmatch.bess`](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/exactmatch.bess).
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable)
 */
message ExactMatchArg {
  repeated Field fields = 1; ///A list of ExactMatch Fields
  repeated FieldData masks = 2; /// mask(i) corresponds to the mask for field(i)
}

/**
 * ExactMatchConfig represents the current runtime configuration
 * of an ExactMatch module, as returned by get_runtime_config and
 * set by set_runtime_config.
 */
message ExactMatchConfig {
  uint64 default_gate = 1;
  repeated ExactMatchCommandAddArg rules = 2;
}

/**
 * The FlowGen module generates simulated TCP flows of packets with correct SYN/FIN flags and sequence numbers.
 * This module is useful for testing, e.g., a NAT module or other flow-aware code.
 * Packets are generated off a base, "template" packet by modifying the IP src/dst and TCP src/dst. By default, only the ports are changed and will be modified by incrementing the template ports by up to 20000 more than the template values.
 *
 * __Input Gates__: 0
 * __Output Gates__: 1
 */
message FlowGenArg {
  bytes template = 1; /// The packet "template". All data packets are derived from this template and contain the same payload.
  double pps = 2; /// The total number of packets per second to generate.
  double flow_rate = 3; /// The number of new flows to create every second. flow_rate must be <= pps.
  double flow_duration = 4; /// The lifetime of a flow in seconds.
  string arrival = 5; /// The packet arrival distribution -- must be either "uniform" or "exponential"
  string duration = 6; /// The flow duration distribution -- must be either "uniform" or "pareto"
  bool quick_rampup = 7; /// Whether or not to populate the flowgenerator with initial flows (start generating full pps rate immediately) or to wait for new flows to be generated naturally (all flows have a SYN packet).
  uint32 ip_src_range = 8; /// When generating new flows, FlowGen modifies the template packet by changing the IP src, incrementing it by at most ip_src_range (e.g., if the base packet is 10.0.0.1 and range is 5, it will generate packets with IPs 10.0.0.1-10.0.0.6).
  uint32 ip_dst_range = 9; /// When generating new flows, FlowGen modifies the template packet by changing the IP dst, incrementing it by at most ip_dst_range.
  uint32 port_src_range = 10; /// When generating new flows, FlowGen modifies the template packet by changing the TCP port, incrementing it by at most port_src_range.
  uint32 port_dst_range = 11; /// When generating new flows, FlowGen modifies the template packet by changing the TCP dst port, incrementing it by at most port_dst_range.
}

/**
 * The GenericDecap module strips off the first few bytes of data from a packet.
 *
 * __Input Gates__: 1
 * __Ouptut Gates__: 1
 */
message GenericDecapArg {
  uint64 bytes = 1; /// The number of bytes to strip off.
}

/**
 * The GenericEncap module adds a header to packets passing through it.
 * Takes a list of fields. Each field is either:
 *
 *  1. {'size': X, 'value': Y}          (for constant values)
 *  2. {'size': X, 'attribute': Y}      (for metadata attributes)
 *
 * e.g.: `GenericEncap([{'size': 4, 'value': 0xdeadbeef},
 *                      {'size': 2, 'attribute': 'foo'},
 *                      {'size': 2, 'value': 0x1234}])`
 * will prepend a 8-byte header:
 *    `de ad be ef <xx> <xx> 12 34`
 * where the 2-byte `<xx> <xx>` comes from the value of metadata attribute `'foo'`
 * for each packet.
 * An example script using GenericEncap is in [`bess/bessctl/conf/samples/generic_encap.bess`](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/generic_encap.bess).
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message GenericEncapArg {
  /**
   * An EncapField represents one field in the new packet header.
   */
  message EncapField {
    uint64 size = 1; /// The length of the field.
    oneof insertion {
      string attribute = 2; /// The metadata attribute name to pull the field value from
      FieldData value = 3; /// Or, the fixed value to insert into the packet.
    }
  }
  repeated EncapField fields = 1;
}

/**
 * The HashLB module partitions packets between output gates according to either
 * a hash over their MAC src/dst (`mode='l2'`), their IP src/dst (`mode='l3'`), the full
 * IP/TCP 5-tuple (`mode='l4'`), or the N-tuple defined by `fields`.
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable)
 */
message HashLBArg {
  repeated int64 gates = 1; /// A list of gate numbers over which to partition packets
  string mode = 2; /// The mode (`'l2'`, `'l3'`, or `'l4'`) for the hash function.
  repeated Field fields = 3; /// A list of fields that define a custom tuple.
}

/**
 * Encapsulates a packet with an IP header, where IP src, dst, and proto are filled in
 * by metadata values carried with the packet. Metadata attributes must include:
 * ip_src, ip_dst, ip_proto, ip_nexthop, and ether_type.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message IPEncapArg {
}

/**
 * An IPLookup module perfroms LPM lookups over a packet destination.
 * IPLookup takes no parameters to instantiate.
 * To add rules to the IPLookup table, use `IPLookup.add()`
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable, depending on rule values)
 */
message IPLookupArg {
  uint32 max_rules = 1; /// Maximum number of rules (default: 1024)
  uint32 max_tbl8s = 2; /// Maximum number of IP prefixes with smaller than /24 (default: 128)
}

/**
 * An L2Forward module forwards packets to an output gate according to exact-match rules over
 * an Ethernet destination.
 * Note that this is _not_ a learning switch -- forwards according to fixed
 * routes specified by `add(..)`.
 *
 * __Input Gates__: 1
 * __Ouput Gates__: many (configurable, depending on rules)
 */
message L2ForwardArg {
  int64 size = 1; /// Configures the forwarding hash table -- total number of hash table entries.
  int64 bucket = 2; /// Configures the forwarding hash table -- total number of slots per hash value.
}

/**
 * The MACSwap module takes no arguments. It swaps the src/destination MAC addresses
 * within a packet.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message MACSwapArg {
}

/**
 * The measure module tracks latencies, packets per second, and other statistics.
 * It should be paired with a Timestamp module, which attaches a timestamp to packets.
 * The measure module will log how long (in nanoseconds) it has been for each packet it received since it was timestamped.
 * This module is somewhat experimental and undergoing various changes.
 * There is a test for the the Measure module in [`bessctl/module_tests/timestamp.py`](https://github.com/NetSys/bess/blob/master/bessctl/module_tests/timestamp.py).
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message MeasureArg {
  // int64 warmup = 1; /// removed: instead of warmup delay, user should Clear()
  oneof type {
    uint64 offset = 2; /// Where to store the current time within the packet, offset in bytes.
    string attr_name = 6; /// Where to store the current time as attribute
  }
  double jitter_sample_prob = 3; /// How often the module should sample packets for inter-packet arrival measurements (to measure jitter).
  uint64 latency_ns_max = 4; /// maximum latency expected, in ns (default 0.1 s)
  uint32 latency_ns_resolution = 5; /// resolution, in ns (default 100)
}

/**
 * The merge module takes no parameters. It has multiple input gates,
 * and passes out all packets from a single output gate.
 *
 * __Input Gates__: many (configurable)
 * __Output Gates__: 1
 */
message MergeArg {
}

/**
 * The MetadataTest module is used for internal testing purposes.
 */
message MetadataTestArg {
  map<string, int64> read = 1;
  map<string, int64> write = 2;
  map<string, int64> update = 3;
}

/**
 * The NAT module implements Dynamic IPv4 address/port translation,
 * rewriting packet source addresses with external addresses as specified,
 * and destination addresses for packets on the reverse direction.
 * L3/L4 checksums are updated correspondingly.
 * To see an example of NAT in use, see:
 * [`bess/bessctl/conf/samples/nat.bess`](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/nat.bess)
 *
 * Currently only supports TCP/UDP/ICMP.
 * Note that address/port in packet payload (e.g., FTP) are NOT translated.
 *
 * __Input Gates__: 2 (0 for internal->external, and 1 for external->internal direction)
 * __Output Gates__: 2 (same as the input gate)
 */
message NATArg {
  message PortRange {
    uint32 begin = 1;
    uint32 end = 2;
    bool suspended = 3;
  }
  message ExternalAddress {
    string ext_addr = 1;
    repeated PortRange port_ranges = 2;
  }
  repeated ExternalAddress ext_addrs = 1; /// list of external IP addresses
}

/**
 * Static NAT module implements one-to-one translation of source/destination
 * IPv4 addresses. No port number is translated.
 * L3/L4 checksums are updated correspondingly.
 * To see an example of NAT in use, see:
 * [`bess/bessctl/conf/samples/nat.bess`](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/nat.bess)
 *
 * Forward direction (from input gate 0 to output gate 0):
 *  - Source IP address is updated, from internal to external address.
 * Reverse direction (from input gate 1 to output gate 1):
 *  - Destination IP address is updated, from external to internal address.
 * If the original address is outside any of the ranges, packets are forwarded
 * without NAT.
 *
 * Note that address in packet payload (e.g., FTP) are NOT translated.
 *
 * __Input Gates__: 2 (0 for internal->external, and 1 for external->internal direction)
 * __Output Gates__: 2 (same as the input gate)
 */
message StaticNATArg {
  message AddressRange {
    string start = 1; /// first IP address to use
    string end = 2; /// last IP address to use
  }

  message AddressRangePair {
    AddressRange int_range = 1;
    AddressRange ext_range = 2; /// should be the same size as int_range
  }

  repeated AddressRangePair pairs = 1;
}

/**
 * This module is used for testing purposes.
 */
message NoOpArg {
}

/**
 * The PortInc module connects a physical or virtual port and releases
 * packets from it. PortInc does not support multiqueueing.
 * For details on how to configure PortInc using DPDK, virtual ports,
 * or libpcap, see the sidebar in the wiki.
 *
 * __Input Gates__: 0
 * __Output Gates__: 1
 */
message PortIncArg {
  string port = 1; /// The portname to connect to.
  bool prefetch = 2; /// Whether or not to prefetch packets from the port.
}

/**
 * The PortOut module connects to a physical or virtual port and pushes
 * packets to it. For details on how to configure PortOut with DPDK,
 * virtual ports, libpcap, etc, see the sidebar in the wiki.
 *
 * __Input Gates__: 1
 * __Output Gates__: 0
 */
message PortOutArg {
  string port = 1; /// The portname to connect to.
  bool rpfcheck = 2; /// Allow reflection of packets to source port
}

/**
 * The module QueueInc produces input packets from a physical or virtual port.
 * Unlike PortInc, it supports multiqueue ports.
 * For details on how to configure QueueInc with DPDK, virtualports,
 * libpcap, etc, see the sidebar in the wiki.
 *
 * __Input Gates__: 0
 * __Output Gates__: 1
 */
message QueueIncArg {
  string port = 1; /// The portname to connect to (read from).
  uint64 qid = 2; /// The queue on that port to read from. qid starts from 0.
  bool prefetch = 3; /// When prefetch is enabled, the module will perform CPU prefetch on the first 64B of each packet onto CPU L1 cache. Default value is false.
}

/**
 * The QueueOut module releases packets to a physical or virtual port.
 * Unlike PortOut, it supports multiqueue ports.
 * For details on how to configure QueueOut with DPDK, virtualports,
 * libpcap, etc, see the sidebar in the wiki.
 *
 * __Input Gates__: 1
 * __Output Gates__: 0
 */
message QueueOutArg {
  string port = 1; /// The portname to connect to.
  uint64 qid = 2; /// The queue on that port to write out to.
}

/**
 * The Queue module implements a simple packet queue.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message QueueArg {
  uint64 size = 1; /// The maximum number of packets to store in the queue.
  bool prefetch = 2; /// When prefetch is enabled, the module will perform CPU prefetch on the first 64B of each packet onto CPU L1 cache. Default value is false.
  bool backpressure = 3; // When backpressure is enabled, the module will notify upstream if it is overloaded.
}

/**
 * The RandomSplit module randomly split/drop packets
 *
 * __InputGates__: 1
 * __Output Gates__: many (configurable)
 */
message RandomSplitArg {
  double drop_rate = 1; /// Probability of dropping packet.
  repeated int64 gates = 2; /// A list of gate numbers to split the traffic.
}

/**
 * The RandomSplit module has a function `set_droprate(...)` which specifies
 * the probability of dropping packets
 */
message RandomSplitCommandSetDroprateArg {
  double drop_rate = 1; /// Probability of dropping packet.
}

/**
 * The RandomSplit module has a function `set_gates(...)` which changes
 * the total number of output gates in the module.
 */
message RandomSplitCommandSetGatesArg {
  repeated int64 gates = 1; /// A list of gate numbers to split the traffic.
}

/**
 * The RandomUpdate module rewrites a specified field (`offset` and `size`) in a packet
 * with a random value between a specified min and max values.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message RandomUpdateArg {
  /**
   * RandomUpdate's Field specifies where to rewrite, and what values to rewrite
   * in each packet processed.
   */
  message Field {
    int64 offset = 1; /// Offset in bytes of where to rewrite.
    uint64 size = 2; /// The number of bytes to write.
    uint64 min = 3; /// The minimum value to insert into the packet.
    uint64 max = 4; /// The maximum value to insert into the packet.
  }
  repeated Field fields = 1; /// A list of Random Update Fields.
}

/**
 * The Rewrite module replaces an entire packet body with a packet "template"
 * converting all packets that pass through to copies of the of one of
 * the templates.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message RewriteArg {
  repeated bytes templates = 1; /// A list of bytestrings representing packet templates.
}

/**
 * The RoundRobin module has a function `set_gates(...)` which changes
 * the total number of output gates in the module.
 */
message RoundRobinCommandSetGatesArg {
  repeated int64 gates = 1; /// A list of gate numbers to round-robin the traffic over.
}

/**
 * The RoundRobin module has a function `set_mode(...)` which specifies whether
 * to balance traffic across gates per-packet or per-batch.
 */
message RoundRobinCommandSetModeArg {
  string mode = 1; /// whether to perform `'packet'` or `'batch'` round robin partitioning.
}

/**
 * The RoundRobin module splits packets from one input gate across multiple output
 * gates.
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable)
 */
message RoundRobinArg {
  repeated int64 gates = 1; /// A list of gate numbers to split packets across.
  string mode = 2; /// Whether to split across gate with every `'packet'` or every `'batch'`.
}

/**
 * The Replicate module makes copies of a packet sending one copy out over each
 * of n output gates.
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable)
 */
message ReplicateArg {
  repeated int64 gates = 1; /// A list of gate numbers to send packet copies to.
}

/**
 * The Replicate module has a function `set_gates(...)` which changes
 * the total number of output gates in the module.
 */
message ReplicateCommandSetGatesArg {
  repeated int64 gates = 1; /// A list of gate numbers to replicate the traffic over.
}

/**
 * The SetMetadata module adds metadata attributes to packets, which are not stored
 * or sent out with packet data. For examples of SetMetadata use, see
 * [`bess/bessctl/conf/attr_match.bess`](https://github.com/NetSys/bess/blob/master/bessctl/conf/metadata/attr_match.bess)
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message SetMetadataArg {
  /**
   * SetMetadata Attribute describes a metadata attribute and value to attach to every packet.
   * If copying data from a packet buffer, SetMetadata can also logically shift
   * then mask the value before storing it as metadata, i.e.,
   * metadata_value = (packet_value >> `rshift_bits`) & `mask`.
   */
  message Attribute {
    string name = 1; /// The metadata attribute name.
    uint64 size = 2; /// The size of values stored in this attribute in bytes.
    oneof value {
      uint64 value_int = 3; /// An integer value to store in the packet (host-order).
      bytes value_bin = 4; /// A binary value to store in the packet (host-order).
    }
    int32 offset = 5; /// An index in the packet data to store copy into the metadata attribute.
    bytes mask = 6; /// An array of bit masks to apply to each of the bytes copied starting from `offset`. If empty, the mask `[0xFF,....,0xFF]` will be used.
    int32 rshift_bits = 7; /// The number of bits to shift the value at `offset` by before masking. Must be a multiple of 8. Positive and negative values represent right and left shifts respectively.
  }
  repeated Attribute attrs = 1; /// A list of attributes to attach to the packet.
}

/**
 * The sink module drops all packets that are sent to it.
 *
 * __Input Gates__: 1
 * __Output Gates__: 0
 */
message SinkArg {
}

/**
 * The Source module has a function `set_burst(...)` which
 * specifies the maximum number of packets to release in a single packetbatch
 * from the module.
 */
message SourceCommandSetBurstArg {
  uint64 burst = 1; /// The maximum number of packets to release in a packetbatch from the module.
}

/**
 * The Source module has a function `set_pkt_size(...)` which specifies the size
 * of packets to be produced by the Source module.
 */
message SourceCommandSetPktSizeArg {
  uint64 pkt_size = 1; /// The size (in bytes) of the packets for Source to create.
}

/**
 * The Source module generates packets with no payload contents.
 *
 * __Input Gates__: 0
 * __Output Gates__: 1
 */
message SourceArg {
  uint64 pkt_size = 1; /// The size (in bytes) of packet data to produce.
}

/**
* The IPChecksum module calculates the IPv4 checksum of packets. If
* verify is set to true, the module can be used to validate the checksum
* of the IPv4 packet. All non-IPv4 packets are forwarded without
* modification. Output gates: (0) Default, (1) Drop.
*
* __Input Gates__: 1
* __Output Gates__: 2
*/
message IPChecksumArg {
 bool verify = 1; /// check checksum
}

/**
* The L4Checksum module calculates the UDP/IPv4 checksum of packets. If
* verify is set to true, the module can be used to validate the checksum
* of the UDP/IPv4 packet. All non-IPv4 packets are forwarded without
* modification. Output gates: (0) Default, (1) Drop.
*
* __Input Gates__: MAX_GATES
* __Output Gates__: 2
*/
message L4ChecksumArg {
 bool verify = 1; /// check checksum
}

/**
 * The Split module is a basic classifier which directs packets out a gate
 * based on data in the packet (e.g., if the read in value is 3, the packet
 * is directed out output gate 3).
 *
 * __Input Gates__: 1
 * __Output Gates__: many (up to 2^(size * 8))
 */
message SplitArg {
  uint64 size = 1; /// The size of the value to read in bytes
  oneof type {
    string attribute = 2; /// The name of the metadata field to read.
    int64 offset = 3; /// The offset (in bytes) of the data field to read.
  }
}

/**
 * The timestamp module takes an offset parameter. It inserts the current
 * time in nanoseconds into the packet, to be used for latency measurements
 * alongside the Measure module.  The default offset is after an IPv4 UDP
 * header.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message TimestampArg {
  oneof type {
    uint64 offset = 1;
    string attr_name = 2;
  }
}

/**
 * The Update module rewrites a field in a packet's data with a specific value.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message UpdateArg {
  /**
   * Update Field describes where in a packet's data to rewrite, and with what value.
   */
  message Field {
    int64 offset = 1; /// The offset in the packet in bytes to rewrite at.
    uint64 size = 2; /// The number of bytes to rewrite (max 8 bytes).
    uint64 value = 3; /// The value to write into the packet, max 8 bytes.
  }
  repeated Field fields = 1; /// A list of Update Fields.
}

/**
 * The URLFilter performs TCP reconstruction over a flow and blocks
 * connections which mention a banned URL.
 *
 * __Input Gates__: 2
 * __Output Gates__: 2
 *
 * Note that the add() command takes this same argument, and the
 * clear() command takes an empty argument.
 */
message UrlFilterArg {
  /**
   * A URL consists of a host and a path.
   */
  message Url {
    string host = 1;  /// Host field, e.g. "www.google.com"
    string path = 2;  /// Path prefix, e.g. "/"
  }
  repeated Url blacklist = 1; /// A list of Urls to block.
}

/**
 * The runtime configuration of a URLFilter is the current
 * blacklist.  This means that getting the Arg gets an *empty*
 * list: we assume anyone using get_initial_arg is also using
 * get_runtime_config.
 */
message UrlFilterConfig {
  repeated UrlFilterArg.Url blacklist = 1;
}

/**
 * VLANPop removes the VLAN tag.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message VLANPopArg {
}

/**
 * VLANPush appends a VLAN tag with a specified TCI value.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message VLANPushArg {
  uint64 tci = 1; /// The TCI value to insert in the VLAN tag.
}

/**
 * Splits packets across output gates according to VLAN id (e.g., id 3 goes out gate 3).
 *
 * __Input Gates__: 1
 * __Output Gates__: many
 */
message VLANSplitArg {
}

/**
 * VXLANDecap module decapsulates a VXLAN header on a packet.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message VXLANDecapArg {
}

/**
 * VXLANEncap module wraps a packet in a VXLAN header with a specified destination port.
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message VXLANEncapArg {
  uint64 dstport = 1; /// The destination UDP port
}

/**
 * The WildcardMatch module matches over multiple fields in a packet and
 * pushes packets that do match out a specified gate, and those that don't out a default
 * gate. WildcardMatch is initialized with the fields it should inspect over,
 * rules are added via the `add(...)` function.
 * An example of WildcardMatch is in [`bess/bessctl/conf/samples/wildcardmatch.bess`](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/wildcardmatch.bess)
 *
 * __Input Gates__: 1
 * __Output Gates__: many (configurable)
 */
message WildcardMatchArg {
  repeated Field fields = 1; /// A list of WildcardMatch fields.
}

/**
 * WildcardMatchConfig represents the current runtime configuration
 * of a WildcardMatch module, as returned by get_runtime_config and
 * set by set_runtime_config.
 */
message WildcardMatchConfig {
  uint64 default_gate = 1;
  repeated WildcardMatchCommandAddArg rules = 2;
}

/**
 * The ARP Responder module is responding to ARP requests.
 * It has a function `add(...)` which adds one IP-MAC mapping.
 *
 * TODO: Dynamic learn new MAC's-IP's mapping
 *
 * __Input Gates__: 1
 * __Output Gates__: 1
 */
message ArpResponderArg {
  string ip = 1; /// The IP
  string mac_addr = 2; /// The MAC address
}

/**
 * The MPLS pop module removes MPLS labels
 *
 * __Input Gates__: 1
 * __Output Gates__: 2
 */
message MplsPopArg {
  bool remove_eth_header = 1; /// Remove ETH header with the pop
  uint32 next_eth_type = 2; /// The next ETH type to set
}

/**
 * WorkerSplit splits packets based on the worker calling ProcessBatch(). It has
 * two modes.
 * 1) Packets from worker `x` are mapped to output gate `x`. This is the default
 *    mode.
 * 2) When the `worker_gates` field is set, packets from a worker `x` are mapped
 *    to `worker_gates[x]`.  In this mode, packet batches from workers not
 *    mapped to an output gate will be dropped.
 *
 * Calling the `reset` command with an empty `worker_gates` field will revert
 * WorkerSplit to the default mode.
 *
 * __Input Gates__: 1
 * __Output Gates__: many
 */
message WorkerSplitArg {
  map<uint32, uint32> worker_gates = 1; // ogate -> worker mask
}