[mirror_frr.git] / doc / developer / fpm.rst

FPM
===

FPM stands for Forwarding Plane Manager and it's a module for use with Zebra.

The encapsulation header for the messages exchanged with the FPM is
defined by the file :file:`fpm/fpm.h` in the frr tree. The routes
themselves are encoded in Netlink or protobuf format, with Netlink
being the default.

Netlink is standard format for encoding messages to talk with kernel space
in Linux and it is also the name of the socket type used by it.
The FPM netlink usage differs from Linux's in:

- Linux netlink sockets use datagrams in a multicast fashion, FPM uses
  as a stream and it is unicast.
- FPM netlink messages might have more or less information than a normal
  Linux netlink socket message (example: RTM_NEWROUTE might add an extra
  route attribute to signalize VxLAN encapsulation).

Protobuf is one of a number of new serialization formats wherein the
message schema is expressed in a purpose-built language. Code for
encoding/decoding to/from the wire format is generated from the
schema. Protobuf messages can be extended easily while maintaining
backward-compatibility with older code. Protobuf has the following
advantages over Netlink:

- Code for serialization/deserialization is generated automatically. This
  reduces the likelihood of bugs, allows third-party programs to be integrated
  quickly, and makes it easy to add fields.
- The message format is not tied to an OS (Linux), and can be evolved
  independently.

.. note::

   Currently there are two FPM modules in ``zebra``:

   * ``fpm``
   * ``dplane_fpm_nl``

fpm
^^^

The first FPM implementation that was built using hooks in ``zebra`` route
handling functions. It uses its own netlink/protobuf encoding functions to
translate ``zebra`` route data structures into formatted binary data.


dplane_fpm_nl
^^^^^^^^^^^^^

The newer FPM implementation that was built using ``zebra``'s data plane
framework as a plugin. It only supports netlink and it shares ``zebra``'s
netlink functions to translate route event snapshots into formatted binary
data.


Protocol Specification
----------------------

FPM (in any mode) uses a TCP connection to talk with external applications.
It operates as TCP client and uses the CLI configured address/port to connect
to the FPM server (defaults to port ``2620``).

FPM frames all data with a header to help the external reader figure how
many bytes it has to read in order to read the full message (this helps
simulates datagrams like in the original netlink Linux kernel usage).

Frame header:

::

    0                   1                   2                   3
    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
   +---------------+---------------+-------------------------------+
   | Version       | Message type  | Message length                |
   +---------------+---------------+-------------------------------+
   | Data...                                                       |
   +---------------------------------------------------------------+


Version
^^^^^^^

Currently there is only one version, so it should be always ``1``.


Message Type
^^^^^^^^^^^^

Defines what underlining protocol we are using: netlink (``1``) or protobuf (``2``).


Message Length
^^^^^^^^^^^^^^

Amount of data in this frame in network byte order.


Data
^^^^

The netlink or protobuf message payload.


Route Status Notification from ASIC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The dplane_fpm_nl has the ability to read route netlink messages
from the underlying fpm implementation that can tell zebra
whether or not the route has been Offloaded/Failed or Trapped.
The end developer must send the data up the same socket that has
been created to listen for FPM messages from Zebra.  The data sent
must have a Frame Header with Version set to 1, Message Type set to 1
and an appropriate message Length.  The message data must contain
a RTM_NEWROUTE netlink message that sends the prefix and nexthops
associated with the route.  Finally rtm_flags must contain
RTM_F_OFFLOAD, RTM_F_TRAP and or RTM_F_OFFLOAD_FAILED to signify
what has happened to the route in the ASIC.
Commit	Line	Data
9d736133 RZ	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.
a0e11736 DS	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.