docs: Update FIB documentation
Type: docs
Signed-off-by: Neale Ranns <nranns@cisco.com>
Change-Id: I3dfde4520a48c945ca9707accabbe1735c1a8799
diff --git a/docs/gettingstarted/developers/fib20/debugging.rst b/docs/gettingstarted/developers/fib20/debugging.rst
new file mode 100644
index 0000000..e0a85fd
--- /dev/null
+++ b/docs/gettingstarted/developers/fib20/debugging.rst
@@ -0,0 +1,106 @@
+.. _debugging:
+
+Debugging
+---------
+
+the anatomy of a route:
+
+.. code-block:: console
+
+ BGvpp# sh ip fib 1.1.1.3/32
+ ipv4-VRF:0, fib_index:0, flow hash:[src dst sport dport proto ] epoch:0 flags:none locks:[adjacency:1, recursive-resolution:4, default-route:1, ]
+ 1.1.1.0/24 fib:0 index:9 locks:2
+ CLI refs:1 src-flags:added,contributing,active,
+ path-list:[24] locks:4 flags:shared, uPRF-list:11 len:1 itfs:[1, ]
+ path:[26] pl-index:24 ip4 weight=1 pref=0 attached-nexthop: oper-flags:resolved,
+ 10.0.0.1 loop0
+ [@0]: arp-ipv4: via 10.0.0.1 loop0
+
+ forwarding: unicast-ip4-chain
+ [@0]: dpo-load-balance: [proto:ip4 index:11 buckets:1 uRPF:11 to:[0:0]]
+ [0] [@3]: arp-ipv4: via 10.0.0.1 loop0
+
+let's go line by line.
+
+.. code-block:: console
+
+ ipv4-VRF:0, fib_index:0, flow hash:[src dst sport dport proto ] epoch:0 flags:none locks:[adjacency:1, recursive-resolution:4, default-route:1, ]
+
+Each field in turn:
+
+- ipv4-VRF:0: the name of the table (as given by the user, or
+ automatically generated by VPP).
+- fib-index:0; in the VPP pool of FIB objects, this is index 0
+- flow hash:[src dst sport dport proto ]: When calculating the flow
+ hash to use for load-balanacing, these are the fields in the packet
+ that are used. There is an API to change this per-table.
+- epoch:0; Used during mark-n-sweep.
+- flags:none; use the force, to find the per-table flags.
+- locks: per-source reference counting, a table can only be deleted
+ when all sources no longer reference it.
+
+next line:
+
+.. code-block:: console
+
+ 1.1.1.0/24 fib:0 index:9 locks:2
+
+this shows the route that matched the show request. note that it is not
+an exact match, it's an LPM. The route is in FIB index 0, its index
+(in the VPP pool of fib_entry_t objects) is nine and there are two
+references to the entry.
+You'll get the same output if you type "sh fib entry 9"
+
+next line:
+
+.. code-block:: console
+
+ CLI refs:1 src-flags:added,contributing,active,
+
+the 'CLI' has sourced this route (it was added via CLI). This source
+has been added (well duh) it is 'active', meaning it is the best
+source, and it is contributing a forwarding object. There are some
+scenarios where sources other than the active source contribute,
+namely interpose sources.
+
+next line:
+
+.. code-block:: console
+
+ path-list:[24] locks:4 flags:shared, uPRF-list:11 len:1 itfs:[1, ]
+
+This is path-list inex 24 (see "sh fib path-list 24" this will also
+show the children), it is 'shared',
+meaning that if other prefixes were to use the same set of paths,
+then they would also use this path-list object. It has uRPF list 11 of
+length 1 containing interface index 1 (which is loop0, see "sh int").
+
+next line:
+
+.. code-block:: console
+
+ path:[26] pl-index:24 ip4 weight=1 pref=0 attached-nexthop: oper-flags:resolved,
+ 10.0.0.1 loop0
+ [@0]: arp-ipv4: via 10.0.0.1 loop0
+
+This is path 26 (see "sh fib path 26"). It's a member of
+path-list 24. It's ip4 has a weight of 1 and a preference of 0. It's
+of type 'attached-nexthop' and currently resolved - woohoo.
+It is a path 'via 10.0.0.1 loop0'. It is contributing an incomplete adjacency.
+
+next line:
+
+.. code-block:: console
+
+ forwarding: unicast-ip4-chain
+ [@0]: dpo-load-balance: [proto:ip4 index:11 buckets:1 uRPF:11 to:[0:0]]
+ [0] [@3]: arp-ipv4: via 10.0.0.1 loop0
+
+This section describes how packets of type 'unicast-ip4' will be
+forwarded. It is the result of processing the path information from
+above.
+Here we see load-balance object 11, which has 1 bucket/choice. It is
+also linked to uRPF instance 11 (which it got from path-list 24).
+In bucket 0 there is the incomplete adjacnecy that was contributed by
+path 26.
+