WIP CFFI Wrapper for routing table tools

 - [x] CFFI wrapper for m-Trie
 - [x] CFFI wrapper for Ordered Covering
 - [x] Utilities for converting to/from C format
 - [ ] Scripts to replace desktop/* executables
 - [ ] Travis updates
 - [ ] Ignore coverage on cffi_compile.py
 - [ ] Utilities for writing/reading routing table files
 - [ ] CFFI wrapper for remove_default_routes when merged

For a later PR
 - SpiNNaker interface for routing table minimisation

Author: mundya

.gitignore

@@ -1,3 +1,8 @@
+*.pyc
+.coverage
+.cache/*
+build/*
+*.egg-info/*
 tests/tests
 *.o
 *.gcov
@@ -7,3 +12,4 @@ tests/tests
 *.aplx
 *.elf
 spinnaker/sark_build.c
+_rig_routing_tables.*

desktop/ordered_covering.c

@@ -43,27 +43,6 @@ int entry_cmp(const void *a, const void *b)
 }
 
 
-void minimise(table_t *table, unsigned int target_length)
-{
-  // Create an empty aliases table
-  aliases_t aliases = aliases_init();
-
-  // Minimise
-  oc_minimise(table, target_length, &aliases);
-
-  // Tidy up the aliases table
-  for (unsigned int i = 0; i < table->size; i++)
-  {
-    keymask_t km = table->entries[i].keymask;
-    if (aliases_contains(&aliases, km))
-    {
-      alias_list_delete((alias_list_t *) aliases_find(&aliases, km));
-      aliases_remove(&aliases, km);
-    }
-  }
-}
-
-
 int main(int argc, char *argv[])
 {
   // Usage:
@@ -128,7 +107,7 @@ int main(int argc, char *argv[])
     qsort(table.entries, table.size, sizeof(entry_t), entry_cmp);
 
     // Perform the minimisation
-    minimise(&table, target_length);
+    oc_minimise_na(&table, target_length);
 
     printf("%u\n", table.size);
 

include/ordered_covering.h

@@ -522,6 +522,28 @@ static inline void oc_minimise(
   }
 }
 
+// Apply the ordered covering algorithm to a routing table without a
+// pre-existing aliases table.
+static inline void oc_minimise_na(table_t *table, unsigned int target_length)
+{
+  // Create an empty aliases table
+  aliases_t aliases = aliases_init();
+
+  // Minimise
+  oc_minimise(table, target_length, &aliases);
+
+  // Tidy up the aliases table
+  for (unsigned int i = 0; i < table->size; i++)
+  {
+    keymask_t km = table->entries[i].keymask;
+    if (aliases_contains(&aliases, km))
+    {
+      alias_list_delete((alias_list_t *) aliases_find(&aliases, km));
+      aliases_remove(&aliases, km);
+    }
+  }
+}
+
 
 #define __ORDERED_COVERING_H__
 #endif  // __ORDERED_COVERING_H__

include/routing_table.h

@@ -59,5 +59,36 @@ typedef struct _table_t
 } table_t;
 
 
+// Table management methods (mostly here for the CFFI wrapper)
+static table_t *new_table(unsigned int size)
+{
+  // Malloc space for the table and associated entries
+  table_t *table = MALLOC(sizeof(table_t));
+  table->size = 0;
+  table->entries = NULL;
+
+  if (table != NULL)
+  {
+    table->entries = MALLOC(sizeof(entry_t) * size);
+
+    if (table->entries != NULL)
+    {
+      table->size = size;
+      return table;
+    }
+  }
+
+  return NULL;
+}
+
+static void free_table(table_t *table)
+{
+  // Free the entries and then the table
+  FREE(table->entries);
+  table->entries = NULL;
+  table->size = 0;
+  FREE(table);
+}
+
 #define __ROUTING_TABLE_H__
 #endif  // __ROUTING_TABLE_H__

py_tests/test_mtrie.py

@@ -0,0 +1,58 @@
+import pytest
+from rig.routing_table import RoutingTableEntry as RTE
+from rig.routing_table import Routes, MinimisationFailedError
+from rig_routing_tables.mtrie import minimise
+
+
+def test_minimise_simple():
+    """Test minimisation of a simple routing table, we assume the C tests are
+    extensive!
+    """
+    # Minimise the table:
+    #    N  -> 0000 -> S SW
+    #    NE -> 0001 -> S SW
+    #    ?  -> 001X -> N
+    table = [
+        RTE({Routes.south, Routes.south_west}, 0x0, 0xf, {Routes.north}),
+        RTE({Routes.south, Routes.south_west}, 0x1, 0xf, {Routes.north_east}),
+        RTE({Routes.north}, 0x2, 0xe),
+    ]
+
+    # We expect the result
+    #    N NE -> 000X -> S SW
+    #    ?    -> 001X -> N
+    expected = [
+        RTE({Routes.south, Routes.south_west}, 0x0, 0xe,
+            {Routes.north, Routes.north_east}),
+        RTE({Routes.north}, 0x2, 0xe),
+    ]
+
+    # Try the minimisation
+    assert minimise(table, None) == expected
+
+
+def test_minimise_fails_if_oversize():
+    """Test minimisation of a simple routing table, we assume the C tests are
+    extensive!
+    """
+    # Minimise the table:
+    #    N  -> 0000 -> S SW
+    #    NE -> 0001 -> S SW
+    #    ?  -> 001X -> N
+    table = [
+        RTE({Routes.south, Routes.south_west}, 0x0, 0xf, {Routes.north}),
+        RTE({Routes.south, Routes.south_west}, 0x1, 0xf, {Routes.north_east}),
+        RTE({Routes.north}, 0x2, 0xe),
+    ]
+
+    # We expect the result to be:
+    #    N NE -> 000X -> S SW
+    #    ?    -> 001X -> N
+    # Which is, clearly, more than 1 entry so an error should be raised
+
+    with pytest.raises(MinimisationFailedError) as exc:
+        minimise(table, 1)
+
+    assert exc.value.target_length == 1
+    assert exc.value.final_length == 2
+    assert exc.value.chip is None

py_tests/test_ordered_covering.py

@@ -0,0 +1,65 @@
+import pytest
+from rig.routing_table import RoutingTableEntry as RTE
+from rig.routing_table import Routes, MinimisationFailedError
+from rig_routing_tables.ordered_covering import minimise
+
+
+@pytest.mark.parametrize("target_length, no_raise",
+                         ((None, False), (0, True)))
+def test_ordered_covering_simple(target_length, no_raise):
+    """Test that a very simple routing table can be minimised, only one
+    merge should be made as there are no conflicts.
+
+    Table::
+
+        0000 -> N, NE
+        0001 -> N, NE
+        001X -> S
+
+    Can be minimised to::
+
+        000X -> N, NE
+        001X -> S
+    """
+    # Original table
+    table = [
+        RTE({Routes.north, Routes.north_east}, 0b0000, 0b1111),
+        RTE({Routes.north, Routes.north_east}, 0b0001, 0b1111),
+        RTE({Routes.south}, 0b0010, 0b1110),
+    ]
+
+    # Expected table
+    expected_table = [
+        RTE({Routes.north, Routes.north_east}, 0b0000, 0b1110),
+        RTE({Routes.south}, 0b0010, 0b1110),
+    ]
+
+    # Minimise and check the result
+    new_table = minimise(table, target_length, no_raise)
+
+    assert new_table == expected_table
+
+
+def test_ordered_covering_simple_fails_if_too_large():
+    """Test that a very simple routing table can be minimised, and that an
+    exception is raised if that minimisation is still too large.
+
+    Table::
+
+        0000 -> N, NE
+        0001 -> N, NE
+        001X -> S
+    """
+    # Original table
+    table = [
+        RTE({Routes.north, Routes.north_east}, 0b0000, 0b1111),
+        RTE({Routes.north, Routes.north_east}, 0b0001, 0b1111),
+        RTE({Routes.south}, 0b0010, 0b1110),
+    ]
+
+    with pytest.raises(MinimisationFailedError) as exc:
+        minimise(table, target_length=1)
+
+    assert exc.value.target_length == 1
+    assert exc.value.final_length == 2
+    assert exc.value.chip is None

py_tests/test_utils.py

@@ -0,0 +1,44 @@
+from rig.routing_table import RoutingTableEntry as RTE
+from rig.routing_table import Routes
+from rig_routing_tables import utils
+
+
+def test_table_to_cffi_and_back():
+    """Test conversion of a Rig routing table to the CFFI format and conversion
+    back again.
+    """
+    # Create the initial table
+    table = [RTE({r}, i, 0xffffffff) for i, r in enumerate(Routes)]
+    table += [
+        RTE({Routes.north, Routes.south}, 0x80000000, 0xffffffff,
+            {Routes.east, Routes.west}),
+    ]
+
+    # Convert the table to C format
+    c_table = utils.rig_to_c_table(table)
+
+    # Check for equivalence
+    assert c_table.size == len(table)
+    for i, entry in enumerate(table):
+        c_entry = c_table.entries[i]
+
+        assert c_entry.keymask.key == entry.key
+        assert c_entry.keymask.mask == entry.mask
+
+        # Check the route is equivalent
+        route = 0x0
+        for r in entry.route:
+            route |= 1 << r
+
+        assert c_entry.route == route
+
+        # Check the source is equivalent
+        source = 0x0
+        for r in entry.sources:
+            source |= 1 << (r if r is not None else 31)
+
+        assert c_entry.source == source
+
+    # Convert back again
+    returned_table = utils.c_to_rig_table(c_table)
+    assert table == returned_table

rig_routing_tables/__init__.py

@@ -0,0 +1,5 @@
+"""Faster C implementation of common routing table minimisers."""
+from rig_routing_tables.version import __version__
+
+from rig_routing_tables._rig_routing_tables import ffi, lib
+from rig_routing_tables import utils

rig_routing_tables/cffi_compile.py

@@ -0,0 +1,53 @@
+import os
+from cffi import FFI
+ffi = FFI()
+
+
+# Get the include directory
+include_dir = os.path.join(os.path.dirname(__file__), "..", "include")
+
+ffi.set_source(
+    "_rig_routing_tables",
+    """
+        #include "mtrie.h"
+        #include "routing_table.h"
+        #include "ordered_covering.h"
+    """,
+    include_dirs=[include_dir]
+)
+
+ffi.cdef("""
+    // Data structures
+    typedef struct _keymask_t
+    {
+      uint32_t key;   // Key for the keymask
+      uint32_t mask;  // Mask for the keymask
+      ...;
+    } keymask_t;
+
+    typedef struct _entry_t
+    {
+      keymask_t keymask;  // Key and mask
+      uint32_t route;     // Routing direction
+      uint32_t source;    // Source of packets arriving at this entry
+      ...;
+    } entry_t;
+
+    typedef struct _table_t
+    {
+      unsigned int size;  // Number of entries in the table
+      entry_t *entries;   // Entries in the table
+      ...;
+    } table_t;
+
+    // Table management
+    table_t* new_table(unsigned int size);
+    void free_table(table_t *table);
+
+    // Minimisation methods
+    void mtrie_minimise(table_t *table);
+    void oc_minimise_na(table_t *table, unsigned int target_length);
+""")
+
+if __name__ == "__main__":
+    ffi.compile()

rig_routing_tables/mtrie.py

@@ -0,0 +1,42 @@
+from rig.routing_table import MinimisationFailedError
+from rig_routing_tables.utils import rig_to_c_table, c_to_rig_table
+from rig_routing_tables._rig_routing_tables import lib
+
+
+def minimise(table, target_length):
+    """Minimise a Rig routing table using the m-Trie method of Ahmad and
+    Mahapatra [1]_.
+
+    Parameters
+    ----------
+    routing_table : [:py:class:`~rig.routing_table.RoutingTableEntry`, ...]
+        Routing table from which to remove entries which could be handled by
+        default routing.
+    target_length : int or None
+        Target length of the routing table.
+
+    Raises
+    ------
+    MinimisationFailedError
+        If the smallest table that can be produced is larger than
+        `target_length`.
+
+    Returns
+    -------
+    [:py:class:`~rig.routing_table.RoutingTableEntry`, ...]
+        Reduced routing table entries.
+
+    [1]_ Ahmad, S. and Mahapatra, R.N., 2007. An efficient approach to on-chip
+    logic minimization. *Very Large Scale Integration (VLSI) Systems, IEEE
+    Transactions on*, 15(9), pp.1040-1050. 
+    """
+    # Convert the table to C format and minimise
+    c_table = rig_to_c_table(table)
+    lib.mtrie_minimise(c_table)
+
+    # If the table is larger than the target length then raise an exception
+    if target_length is not None and c_table.size > target_length:
+        raise MinimisationFailedError(target_length, c_table.size)
+
+    # Otherwise convert back to Rig form and return
+    return c_to_rig_table(c_table)