Merge PR #956 (v2016.07 release) into master

CONTRIBUTING.md

@@ -1,18 +1,30 @@
-Whenever you create a Pull Request (PR), a maintainer will self-assign
+# Hints for Contributors
+
+* Whenever you create a Pull Request (PR), a maintainer will self-assign
 themselves as the *upstream*. The upstream decides if your PR is accepted and
 might require you to amend additional changes before merging. You can expect
 the upstream to communicate clearly if there are any issues preventing your PR
 from being merged, and how they can be fixed. Once merged, the upstream will
-add the `merged` label to your PR.
+add the `merged` label to your PR. More on [our Git workflow](https://github.com/snabbco/snabb/blob/master/src/doc/git-workflow.md).
+
+* Target your PR against the branch you would like it to be merged into. Refer
+to the [list of subsystem branches](https://github.com/snabbco/snabb/blob/master/src/doc/branches.md).
+When in doubt use `master`.
 
-You are also welcome to submit PRs you would like to receive feedback on, but
+* Feel free to @ping the assignee if you feel like your PR has been overlooked,
+and are waiting for a response.
+
+* You are also welcome to submit PRs you would like to receive feedback on, but
 which are not ready to be merged: include the labels `[wip]` in the title of
 PRs that require further work, and `[sketch]` for PRs that are not meant to be
 merged at all.
 
-Our [Documentation Guide](https://github.com/SnabbCo/snabbswitch/blob/master/src/doc/documentation-guide.md)
+* Please make sure your editor is configured to not emit tabs and use three
+spaces for indentation.
+
+* Our [Documentation Guide](https://github.com/SnabbCo/snabbswitch/blob/master/src/doc/documentation-guide.md)
 gives pointers on how to contribute to the project's documentation.
 
-If you wish to record a copyright notice with your contribution then you can
+* If you wish to record a copyright notice with your contribution then you can
 optionally do this in the file `src/COPYRIGHT`; copyright notices in other
 files will be rejected.

default.nix

@@ -1,17 +1,18 @@
 # Run like this:
 #   nix-build /path/to/this/directory
-# ... and the files are produced in ./result/
+# ... and the files are produced in ./result/bin/snabb
 
 { pkgs ? (import <nixpkgs> {})
+, source ? ./.
+, version ? "dev"
 }:
 
 with pkgs;
 
 stdenv.mkDerivation rec {
-  # TODO: get the version from somewhere?
-  name = "snabb";
-
-  src = ./.;
+  name = "snabb-${version}";
+  inherit version;
+  src = lib.cleanSource source;
 
   buildInputs = [ makeWrapper ];
 
@@ -36,4 +37,6 @@ stdenv.mkDerivation rec {
     mkdir -p $out/bin
     cp src/snabb $out/bin
   '';
+
+  enableParallelBuilding = true;
 }

release.nix

@@ -13,9 +13,9 @@ let
     url = "http://lab1.snabb.co:2008/~max/assets/vm-ubuntu-trusty-14.04-dpdk-snabb.tar.gz";
     sha256 = "0323591i925jhd6wv8h268wc3ildjpa6j57n4p9yg9d6ikwkw06j";
   };
-  optionalGetEnv = first: default: let
-      maybeEnv = builtins.getEnv first;
-    in if (maybeEnv != "") then maybeEnv else default;
+  requiredGetEnv = var:  let
+      maybeEnv = builtins.getEnv var;
+    in if (maybeEnv != "") then maybeEnv else throw "Please export shell variable ${var}";
 in rec {
   manual = import ./src/doc {};
   snabb = import ./default.nix {};
@@ -26,7 +26,7 @@ in rec {
 
     # allow sudo
     __noChroot = true;
-    requiredSystemFeatures = [ "performance" ];
+    requiredSystemFeatures = [ "lugano" ];
 
     buildInputs = [ git telnet tmux numactl bc iproute which qemu ];
 
@@ -45,10 +45,9 @@ in rec {
 
     doCheck = true;
     checkPhase = ''
-      export SNABB_PCI0=${ optionalGetEnv "SNABB_PCI0" "0000:01:00.0"}
-      export SNABB_PCI_INTEL0=${ optionalGetEnv "SNABB_PCI_INTEL0" "0000:01:00.0"}
-      export SNABB_PCI_INTEL1=${ optionalGetEnv "SNABB_PCI_INTEL1" "0000:01:00.1"}
-      export FAIL_ON_FIRST=true
+      export SNABB_PCI0=${ requiredGetEnv "SNABB_PCI0" }
+      export SNABB_PCI_INTEL0=${ requiredGetEnv "SNABB_PCI_INTEL0" }
+      export SNABB_PCI_INTEL1=${ requiredGetEnv "SNABB_PCI_INTEL1" }
 
       # run tests
       sudo -E make test -C src/

src/Makefile

@@ -39,7 +39,7 @@ EXE    := bin/snabb $(patsubst %,bin/%,$(PROGRAM))
 #   core.memory core.lib ...
 # for each module that has a top-level selftest () function.
 TESTMODS = $(shell find . -regex '[^\#]*\.lua' -printf '%P ' | \
-             xargs grep -l '^function selftest *[[:punct:]]' | \
+             xargs grep -s -l '^function selftest *[[:punct:]]' | \
              sed -e 's_\.lua__' -e 's_/_._g')
 
 # TESTSCRIPTS expands to:

src/README.md

@@ -99,6 +99,18 @@ Tables of named input and output links.  These tables are initialized by
 the engine for use in processing and are *read-only*.
 
 
+— Field **myapp.appname**
+
+Name of the app. *Read-only*.
+
+
+— Method **myapp:link**
+
+*Optional*. Called any time the app’s links may have been changed (including on
+start-up). Guaranteed to be called before `pull` and `push` are called with new
+links.
+
+
 — Method **myapp:pull**
 
 *Optional*. Pull packets into the network.
@@ -303,35 +315,41 @@ Returns a structure holding ring statistics for the *link*:
 
 
 ## Packet (core.packet)
-
-A *packet* is a data structure describing one of the network packets that
-is currently being processed. The packet is used to explicitly manage the
-life cycle of the packet. Packets are explicitly allocated and freed by
-using `packet.allocate` and `packet.free`. When a packet is received
-using `link.receive` its ownership is acquired by the calling app. The
-app must then ensure to either transfer the packet ownership to another
-app by calling `link.transmit` on the packet or free the packet using
-`packet.free`. Apps may only use packets they own, e.g. packets that have
-not been transmitted or freed. The number of allocatable packets is
-limited by the size of the underlying "freelist", e.g. a pool of unused
-packet objects from and to which packets are allocated and freed.
 
-— Function **packet.allocate**
+A *packet* is an FFI object of type `packet.packet_t` representing a network
+packet that is currently being processed. The packet is used to explicitly
+manage the life cycle of the packet. Packets are explicitly allocated and freed
+by using `packet.allocate` and `packet.free`. When a packet is received using
+`link.receive` its ownership is acquired by the calling app. The app must then
+ensure to either transfer the packet ownership to another app by calling
+`link.transmit` on the packet or free the packet using `packet.free`. Apps may
+only use packets they own, e.g. packets that have not been transmitted or
+freed. The number of allocatable packets is limited by the size of the
+underlying “freelist”, e.g. a pool of unused packet objects from and to which
+packets are allocated and freed.
 
-Returns a new empty packet. An an error is raised if there are no packets
-left on the freelist.
+— Ctype **packet.packet_t**
 
-— Function **packet.free** *packet*
+```
+struct packet {
+    uint8_t  data[packet.max_payload];
+    uint16_t length;
+};
+```
 
-Frees *packet* and puts in back onto the freelist.
+— Constant **packet.max_payload**
 
-— Function **packet.data** *packet*
+The maximum payload length of a packet.
 
-Returns a pointer to the payload of *packet*.
+— Function **packet.allocate**
 
-— Function **packet.length** *packet*
+Returns a new empty packet. An an error is raised if there are no packets left
+on the freelist. Initially the `length` of the allocated is 0, and its `data`
+is uninitialized garbage.
 
-Returns the payload length of *packet*.
+— Function **packet.free** *packet*
+
+Frees *packet* and puts in back onto the freelist.
 
 — Function **packet.clone** *packet*
 
@@ -357,7 +375,14 @@ accomodate *length* additional bytes.
 
 — Function **packet.shiftleft** *packet*, *length*
 
-Truncates *packet* by *length* bytes from the front.
+Truncates *packet* by *length* bytes from the front. *Length* must be less than
+or equal to `length` of *packet*.
+
+— Function **packet.shiftright** *packet*, *length*
+
+Move *packet* payload to the right by *length* bytes, growing *packet* by
+*length*. The sum of *length* and `length` of *packet* must be less than or
+equal to `packet.max_payload`.
 
 — Function **packet.from_pointer** *pointer*, *length*
 
@@ -376,10 +401,13 @@ can be accessed directly by network cards. The important
 characteristic of DMA memory is being located in contiguous physical
 memory at a stable address.
 
-— Function **memory.dma_alloc** *bytes*
+— Function **memory.dma_alloc** *bytes*, *[alignment]*
 
 Returns a pointer to *bytes* of new DMA memory.
 
+Optionally a specific *alignment* requirement can be provided (in
+bytes). The default alignment is 128.
+
 — Function **memory.virtual_to_physical** *pointer*
 
 Returns the physical address (`uint64_t`) the DMA memory at *pointer*.
@@ -549,10 +577,18 @@ Returns a table that acts as a bounds checked wrapper around a C array of
 ctype and the caller must ensure that the allocated memory region at
 *base*/*offset* is at least `sizeof(type)*size` bytes long.
 
-— Function **lib.timer** *s*
+— Function **lib.timer** *duration*, *mode*, *timefun*
+
+Returns a closure that will return `false` until *duration* has elapsed. If
+*mode* is `'repeating'` the timer will reset itself after returning `true`,
+thus implementing an interval timer. *Timefun* is used to get a monotonic time.
+*Timefun* defaults to `C.get_time_ns`.
+
+The “deadline” for a given *duration* is computed by adding *duration* to the
+result of calling *timefun*, and is saved in the resulting closure. A
+*duration* has elapsed when its deadline is less than or equal the value
+obtained using *timefun* when calling the closure.
 
-Returns a function that accepts no parameters and acts as a predicate to
-test if *ns* nanoseconds have elapsed.
 
 — Function **lib.waitfor** *condition*
 

src/apps/bridge/base.lua

@@ -26,12 +26,6 @@
 -- can access the configuration via self._conf.config.  If config is
 -- not set, it is initialiezed to an empty table.
 --
--- Note that it is necessary to call the method post_config() after
--- the app has been configured with engine.configure() to complete the
--- initialization.  This step will add the ringbuffers associated with
--- the ports to an internal data structure to save a lookup in the
--- input and output tables during packet processing.
---
 -- To make processing in the fast path easier, each port and group is
 -- assigned a unique integer greater than zero to serve as a "handle".
 -- The group handle 0 is assigned to all free ports.
@@ -149,7 +143,7 @@ end
 -- accessible via the keys l_in and l_out, respectively.  This helps
 -- to speed up packet forwarding by eliminating a lookup in the input
 -- and output tables.
-function bridge:post_config ()
+function bridge:link ()
    assert(self.input and self.output)
    for _, port in ipairs(self._ports) do
       port.l_in = self.input[port.name]

src/apps/bridge/learning.lua

@@ -203,7 +203,7 @@ function bridge:push()
          -- packet with one of the packet forwarding tables according
          -- to the result.
          local mac = self._mac
-         mac[0] = packet.data(p)
+         mac[0] = p.data
          mac_table:lookup_pft(mac, ip, ig, p, self._pft_C, self._flood_pl[ip])
          -- Associate the source MAC address with the ingress port and
          -- group.  Multicast addresses are forbidden to occur as