4 files changed, 79 insertions, 20 deletions
diff --git a/doc/developer/building-libyang.rst b/doc/developer/building-libyang.rst
index f50b8cf72d..5f82447d74 100644
--- a/doc/developer/building-libyang.rst
+++ b/doc/developer/building-libyang.rst
@@ -5,12 +5,16 @@ library.
 
 **Option 1: Binary Install**
 
-The FRR project builds binary ``libyang`` packages, which we offer for download
-`here <https://ci1.netdef.org/browse/LIBYANG-YANGRELEASE/latestSuccessful/artifact>`_.
+The FRR project builds some binary ``libyang`` packages.
+
+RPM packages are at our `RPM repository <https://rpm.frrouting.org>`_.
+
+DEB packages are available as CI artifacts `here
+<https://ci1.netdef.org/browse/LIBYANG-LY1REL-DEB10AMD64-4/artifact>`_.
 
 .. warning::
 
-   ``libyang`` version 0.16.105 or newer is required to build FRR.
+   ``libyang`` version 1.0.184 or newer is required to build FRR.
 
 .. note::
 
@@ -50,8 +54,3 @@ The FRR project builds binary ``libyang`` packages, which we offer for download
          -D CMAKE_BUILD_TYPE:String="Release" ..
    make
    sudo make install
-
-When building ``libyang`` version ``0.16.x`` it's also necessary to pass the
-``-DENABLE_CACHE=OFF`` parameter to ``cmake`` to work around a
-`known bug <https://github.com/CESNET/libyang/issues/752>`_ in libyang.
-
diff --git a/doc/developer/lists.rst b/doc/developer/lists.rst
index 9355141aa4..28b21533c0 100644
--- a/doc/developer/lists.rst
+++ b/doc/developer/lists.rst
@@ -497,6 +497,7 @@ API for hash tables
       Items that compare as equal cannot be inserted.  Refer to the notes
       about sorted structures in the previous section.
 
+
 .. c:function:: void Z_init_size(struct Z_head *, size_t size)
 
    Same as :c:func:`Z_init()` but preset the minimum hash table to
@@ -506,6 +507,66 @@ Hash tables also support :c:func:`Z_add()` and :c:func:`Z_find()` with
 the same semantics as noted above. :c:func:`Z_find_gteq()` and
 :c:func:`Z_find_lt()` are **not** provided for hash tables.
 
+Hash table invariants
+^^^^^^^^^^^^^^^^^^^^^
+
+There are several ways to injure yourself using the hash table API.
+
+First, note that there are two functions related to computing uniqueness of
+objects inserted into the hash table. There is a hash function and a comparison
+function. The hash function computes the hash of the object. Our hash table
+implementation uses `chaining
+<https://en.wikipedia.org/wiki/Hash_table#Separate_chaining_with_linked_lists>`_.
+This means that your hash function does not have to be perfect; multiple
+objects having the same computed hash will be placed into a linked list
+corresponding to that key. The closer to perfect the hash function, the better
+performance, as items will be more evenly distributed and the chain length will
+not be long on any given lookup, minimizing the number of list operations
+required to find the correct item. However, the comparison function *must* be
+perfect, in the sense that any two unique items inserted into the hash table
+must compare not equal. At insertion time, if you try to insert an item that
+compares equal to an existing item the insertion will not happen and
+``hash_get()`` will return the existing item. However, this invariant *must* be
+maintained while the object is in the hash table. Suppose you insert items
+``A`` and ``B`` into the hash table which both hash to the same value ``1234``
+but do not compare equal. They will be placed in a chain like so::
+
+   1234 : A -> B
+
+Now suppose you do something like this elsewhere in the code::
+
+   *A = *B
+
+I.e. you copy all fields of ``B`` into ``A``, such that the comparison function
+now says that they are equal based on their contents. At this point when you
+look up ``B`` in the hash table, ``hash_get()`` will search the chain for the
+first item that compares equal to ``B``, which will be ``A``. This leads to
+insidious bugs.
+
+.. warning::
+
+   Never modify the values looked at by the comparison or hash functions after
+   inserting an item into a hash table.
+
+A similar situation can occur with the hash allocation function. ``hash_get()``
+accepts a function pointer that it will call to get the item that should be
+inserted into the list if the provided item is not already present. There is a
+builtin function, ``hash_alloc_intern``, that will simply return the item you
+provided; if you always want to store the value you pass to ``hash_get`` you
+should use this one. If you choose to provide a different one, that function
+*must* return a new item that hashes and compares equal to the one you provided
+to ``hash_get()``. If it does not the behavior of the hash table is undefined.
+
+.. warning::
+
+   Always make sure your hash allocation function returns a value that hashes
+   and compares equal to the item you provided to ``hash_get()``.
+
+Finally, if you maintain pointers to items you have inserted into a hash table,
+then before deallocating them you must release them from the hash table. This
+is basic memory management but worth repeating as bugs have arisen from failure
+to do this.
+
 
 API for heaps
 -------------
diff --git a/doc/developer/ospf-sr.rst b/doc/developer/ospf-sr.rst
index 070465db5b..efe9b1b12f 100644
--- a/doc/developer/ospf-sr.rst
+++ b/doc/developer/ospf-sr.rst
@@ -1,8 +1,7 @@
 OSPF Segment Routing
 ====================
 
-This is an EXPERIMENTAL support of draft
-`draft-ietf-ospf-segment-routing-extensions-24`.
+This is an EXPERIMENTAL support of `RFC 8665`.
 DON'T use it for production network.
 
 Supported Features
@@ -10,12 +9,13 @@ Supported Features
 
 * Automatic computation of Primary and Backup Adjacency SID with
   Cisco experimental remote IP address
-* SRGB configuration
+* SRGB & SRLB configuration
 * Prefix configuration for Node SID with optional NO-PHP flag (Linux
   kernel support both mode)
 * Node MSD configuration (with Linux Kernel >= 4.10 a maximum of 32 labels
   could be stack)
 * Automatic provisioning of MPLS table
+* Equal Cost Multi-Path (ECMP)
 * Static route configuration with label stack up to 32 labels
 
 Interoperability
@@ -243,16 +243,16 @@ Routing.
    router ospf
     ospf router-id 192.168.1.11
     capability opaque
-     mpls-te on
-     mpls-te router-address 192.168.1.11
-    router-info area 0.0.0.0
     segment-routing on
     segment-routing global-block 10000 19999
+    segment-routing local-block 5000 5999
     segment-routing node-msd 8
     segment-routing prefix 192.168.1.11/32 index 1100
 
-The first segment-routing statement enable it. The Second one set the SRGB,
-third line the MSD and finally, set the Prefix SID index for a given prefix.
+The first segment-routing statement enables it. The second and third one set
+the SRGB and SRLB respectively, fourth line the MSD and finally, set the
+Prefix SID index for a given prefix.
+
 Note that only prefix of Loopback interface could be configured with a Prefix
 SID. It is possible to add `no-php-flag` at the end of the prefix command to
 disable Penultimate Hop Popping. This advertises to peers that they MUST NOT pop
@@ -265,9 +265,6 @@ Known limitations
 * Only single Area is supported. ABR is not yet supported
 * Only SPF algorithm is supported
 * Extended Prefix Range is not supported
-* MPLS table are not flush at startup. Thus, restarting zebra process is
-  mandatory to remove old MPLS entries in the data plane after a crash of
-  ospfd daemon
 * With NO Penultimate Hop Popping, it is not possible to express a Segment
   Path with an Adjacency SID due to the impossibility for the Linux Kernel to
   perform double POP instruction.
diff --git a/doc/developer/process-architecture.rst b/doc/developer/process-architecture.rst
index 6e0eb68188..6a028d0000 100644
--- a/doc/developer/process-architecture.rst
+++ b/doc/developer/process-architecture.rst
@@ -94,7 +94,9 @@ irrelevant for the time being) for the specific type. For example, to add a
    thread_add_read(struct thread_master *master, int (*handler)(struct thread *), void *arg, int fd, struct thread **ref);
 
 The ``struct thread`` is then created and added to the appropriate internal
-datastructure within the ``threadmaster``.
+datastructure within the ``threadmaster``. Note that the ``READ`` and
+``WRITE`` tasks are independent - a ``READ`` task only tests for
+readability, for example.
 
 The Event Loop
 ^^^^^^^^^^^^^^