doc/developer/fpm.rst

   1 FPM
   2 ===
   3
   4 FPM stands for Forwarding Plane Manager and it's a module for use with Zebra.
   5
   6 The encapsulation header for the messages exchanged with the FPM is
   7 defined by the file :file:`fpm/fpm.h` in the frr tree. The routes
   8 themselves are encoded in Netlink or protobuf format, with Netlink
   9 being the default.
  10
  11 Netlink is standard format for encoding messages to talk with kernel space
  12 in Linux and it is also the name of the socket type used by it.
  13 The FPM netlink usage differs from Linux's in:
  14
  15 - Linux netlink sockets use datagrams in a multicast fashion, FPM uses
  16   as a stream and it is unicast.
  17 - FPM netlink messages might have more or less information than a normal
  18   Linux netlink socket message (example: RTM_NEWROUTE might add an extra
  19   route attribute to signalize VxLAN encapsulation).
  20
  21 Protobuf is one of a number of new serialization formats wherein the
  22 message schema is expressed in a purpose-built language. Code for
  23 encoding/decoding to/from the wire format is generated from the
  24 schema. Protobuf messages can be extended easily while maintaining
  25 backward-compatibility with older code. Protobuf has the following
  26 advantages over Netlink:
  27
  28 - Code for serialization/deserialization is generated automatically. This
  29   reduces the likelihood of bugs, allows third-party programs to be integrated
  30   quickly, and makes it easy to add fields.
  31 - The message format is not tied to an OS (Linux), and can be evolved
  32   independently.
  33
  34 .. note::
  35
  36    Currently there are two FPM modules in ``zebra``:
  37
  38    * ``fpm``
  39    * ``dplane_fpm_nl``
  40
  41 fpm
  42 ^^^
  43
  44 The first FPM implementation that was built using hooks in ``zebra`` route
  45 handling functions. It uses its own netlink/protobuf encoding functions to
  46 translate ``zebra`` route data structures into formatted binary data.
  47
  48
  49 dplane_fpm_nl
  50 ^^^^^^^^^^^^^
  51
  52 The newer FPM implementation that was built using ``zebra``'s data plane
  53 framework as a plugin. It only supports netlink and it shares ``zebra``'s
  54 netlink functions to translate route event snapshots into formatted binary
  55 data.
  56
  57
  58 Protocol Specification
  59 ----------------------
  60
  61 FPM (in any mode) uses a TCP connection to talk with external applications.
  62 It operates as TCP client and uses the CLI configured address/port to connect
  63 to the FPM server (defaults to port ``2620``).
  64
  65 FPM frames all data with a header to help the external reader figure how
  66 many bytes it has to read in order to read the full message (this helps
  67 simulates datagrams like in the original netlink Linux kernel usage).
  68
  69 Frame header:
  70
  71 ::
  72
  73     0                   1                   2                   3
  74     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  75    +---------------+---------------+-------------------------------+
  76    | Version       | Message type  | Message length                |
  77    +---------------+---------------+-------------------------------+
  78    | Data...                                                       |
  79    +---------------------------------------------------------------+
  80
  81
  82 Version
  83 ^^^^^^^
  84
  85 Currently there is only one version, so it should be always ``1``.
  86
  87
  88 Message Type
  89 ^^^^^^^^^^^^
  90
  91 Defines what underlining protocol we are using: netlink (``1``) or protobuf (``2``).
  92
  93
  94 Message Length
  95 ^^^^^^^^^^^^^^
  96
  97 Amount of data in this frame in network byte order.
  98
  99
 100 Data
 101 ^^^^
 102
 103 The netlink or protobuf message payload.
 104
 105
 106 Route Status Notification from ASIC
 107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 108
 109 The dplane_fpm_nl has the ability to read route netlink messages
 110 from the underlying fpm implementation that can tell zebra
 111 whether or not the route has been Offloaded/Failed or Trapped.
 112 The end developer must send the data up the same socket that has
 113 been created to listen for FPM messages from Zebra.  The data sent
 114 must have a Frame Header with Version set to 1, Message Type set to 1
 115 and an appropriate message Length.  The message data must contain
 116 a RTM_NEWROUTE netlink message that sends the prefix and nexthops
 117 associated with the route.  Finally rtm_flags must contain
 118 RTM_F_OFFLOAD, RTM_F_TRAP and or RTM_F_OFFLOAD_FAILED to signify
 119 what has happened to the route in the ASIC.