diff options
Diffstat (limited to 'src/vnet/bfd')
| -rw-r--r-- | src/vnet/bfd/bfd_api.c | 4 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_api.h | 32 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_cli.c | 4 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_doc.md | 375 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_main.c | 6 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_main.h | 140 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_protocol.c | 6 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_protocol.h | 5 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_udp.c | 4 | ||||
| -rw-r--r-- | src/vnet/bfd/bfd_udp.h | 39 | ||||
| -rw-r--r-- | src/vnet/bfd/dir.dox | 2 |
11 files changed, 526 insertions, 91 deletions
diff --git a/src/vnet/bfd/bfd_api.c b/src/vnet/bfd/bfd_api.c index e64df48e11f..185c03cf86f 100644 --- a/src/vnet/bfd/bfd_api.c +++ b/src/vnet/bfd/bfd_api.c @@ -16,6 +16,10 @@ * limitations under the License. *------------------------------------------------------------------ */ +/** + * @file + * @brief BFD binary API implementation + */ #include <vnet/vnet.h> #include <vlibmemory/api.h> diff --git a/src/vnet/bfd/bfd_api.h b/src/vnet/bfd/bfd_api.h index 35ad3cda9ab..9f0509d5f73 100644 --- a/src/vnet/bfd/bfd_api.h +++ b/src/vnet/bfd/bfd_api.h @@ -14,7 +14,7 @@ */ /** * @file - * @brief BFD global declarations + * @brief BFD API declarations */ #ifndef __included_bfd_api_h__ #define __included_bfd_api_h__ @@ -34,6 +34,9 @@ typedef enum #undef F } bfd_transport_e; +/** + * @brief create a new bfd session + */ vnet_api_error_t bfd_udp_add_session (u32 sw_if_index, const ip46_address_t * local_addr, const ip46_address_t * peer_addr, @@ -41,39 +44,66 @@ bfd_udp_add_session (u32 sw_if_index, const ip46_address_t * local_addr, u8 detect_mult, u8 is_authenticated, u32 conf_key_id, u8 bfd_key_id); +/** + * @brief modify existing session + */ vnet_api_error_t bfd_udp_mod_session (u32 sw_if_index, const ip46_address_t * local_addr, const ip46_address_t * peer_addr, u32 desired_min_tx_usec, u32 required_min_rx_usec, u8 detect_mult); +/** + * @brief delete existing session + */ vnet_api_error_t bfd_udp_del_session (u32 sw_if_index, const ip46_address_t * local_addr, const ip46_address_t * peer_addr); +/** + * @brief set session admin down/up + */ vnet_api_error_t bfd_udp_session_set_flags (u32 sw_if_index, const ip46_address_t * local_addr, const ip46_address_t * peer_addr, u8 admin_up_down); +/** + * @brief create or modify bfd authentication key + */ vnet_api_error_t bfd_auth_set_key (u32 conf_key_id, u8 auth_type, u8 key_len, const u8 * key); +/** + * @brief delete existing authentication key + */ vnet_api_error_t bfd_auth_del_key (u32 conf_key_id); +/** + * @brief activate authentication for existing session + */ vnet_api_error_t bfd_udp_auth_activate (u32 sw_if_index, const ip46_address_t * local_addr, const ip46_address_t * peer_addr, u32 conf_key_id, u8 bfd_key_id, u8 is_delayed); +/** + * @brief deactivate authentication for existing session + */ vnet_api_error_t bfd_udp_auth_deactivate (u32 sw_if_index, const ip46_address_t * local_addr, const ip46_address_t * peer_addr, u8 is_delayed); +/** + * @brief set echo-source interface + */ vnet_api_error_t bfd_udp_set_echo_source (u32 loopback_sw_if_index); +/** + * @brief unset echo-source interface + */ vnet_api_error_t bfd_udp_del_echo_source (); #endif /* __included_bfd_api_h__ */ diff --git a/src/vnet/bfd/bfd_cli.c b/src/vnet/bfd/bfd_cli.c index a3736d98b3c..f15acb4ba36 100644 --- a/src/vnet/bfd/bfd_cli.c +++ b/src/vnet/bfd/bfd_cli.c @@ -737,7 +737,7 @@ VLIB_CLI_COMMAND (bfd_cli_udp_session_auth_activate_command, static) = { " peer-addr <peer-address>" " conf-key-id <config key ID>" " bfd-key-id <BFD key ID>" - " [ delayed <yes|no>]", + " [ delayed <yes|no> ]", .function = bfd_cli_udp_session_auth_activate, }; @@ -815,7 +815,7 @@ VLIB_CLI_COMMAND (bfd_cli_udp_session_auth_deactivate_command, static) = { " interface <interface>" " local-addr <local-address>" " peer-addr <peer-address>" - "[ delayed <yes|no>]", + "[ delayed <yes|no> ]", .function = bfd_cli_udp_session_auth_deactivate, }; /* *INDENT-ON* */ diff --git a/src/vnet/bfd/bfd_doc.md b/src/vnet/bfd/bfd_doc.md index 3e86b178a1f..7d7606e4dd1 100644 --- a/src/vnet/bfd/bfd_doc.md +++ b/src/vnet/bfd/bfd_doc.md @@ -1,3 +1,374 @@ -# BFD Notes {#bfd_doc} +# BFD module {#bfd_doc} -@todo Someone needs to produce this or remove the stub file. +## Overview + +Bidirectional Forwarding Detection in VPP currently supports single-hop UDP +transport based on RFC 5880 and RFC 5881. + +## Usage + +### General usage + +BFD sessions are created using APIs only. The following CLIs are implemented, +which call the APIs to manipulate the BFD: + +#### Show commands: + +> show bfd [keys|sessions|echo-source] + +Show the existing keys, sessions or echo-source. + +#### Key manipulation + +##### Create a new key or modify an existing key + +> bfd key set conf-key-id <id> type <keyed-sha1|meticulous-keyed-sha1> secret <secret> + +Parameters: + +* conf-key-id - local configuration key ID, used to uniquely identify this key +* type - type of the key +* secret - shared secret (hex data) + +Example: + +> bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret 69d685b0d990cdba46872706dc + +Notes: + +* in-use key cannot be modified + +##### Delete an existing key + +> bfd key del conf-key-id <id> + +Parameters: + +* conf-key-id - local configuration key ID, used to uniquely identify this key + +Example: + +> bfd key del conf-key-id 2368880803 + +Notes: + +* in-use key cannot be deleted + +##### Create a new (plain or authenticated) BFD session + +> bfd udp session add interface <interface> local-addr <address> peer-addr <address> desired-min-tx <interval> required-min-rx <interval> detect-mult <multiplier> [ conf-key-id <ID> bfd-key-id <ID> ] + +Parameters: + +* interface - interface to which this session is tied to +* local-addr - local address (ipv4 or ipv6) +* peer-addr - peer address (ipv4 or ipv6, must match local-addr family) +* desired-min-tx - desired minimum tx interval (microseconds) +* required-min-rx - required minimum rx interval (microseconds) +* detect-mult - detect multiplier (must be non-zero) +* conf-key-id - local configuration key ID +* bfd-key-id - BFD key ID, as carried in BFD control frames + +Example: + +> bfd udp session add interface pg0 local-addr fd01:1::1 peer-addr fd01:1::2 desired-min-tx 100000 required-min-rx 100000 detect-mult 3 conf-key-id 1029559112 bfd-key-id 13 + +Notes: + +* if conf-key-id and bfd-key-id are not specified, session is non-authenticated +* desired-min-tx controls desired transmission rate of both control frames and echo packets + +##### Modify BFD session + +> bfd udp session mod interface <interface> local-addr <address> peer-addr <address> desired-min-tx <interval> required-min-rx <interval> detect-mult <multiplier> + +Parameters: + +* interface - interface to which this session is tied to +* local-addr - local address (ipv4 or ipv6) +* peer-addr - peer address (ipv4 or ipv6, must match local-addr family) +* desired-min-tx - desired minimum tx interval (microseconds) +* required-min-rx - required minimum rx interval (microseconds) +* detect-mult - detect multiplier (must be non-zero) + +Example: + +> bfd udp session mod interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 desired-min-tx 300000 required-min-rx 200000 detect-mult 12 + +Notes: + +* desired-min-tx controls desired transmission rate of both control frames and echo packets + +##### Delete an existing BFD session + +> bfd udp session del interface <interface> local-addr <address> peer-addr<address> + +Parameters: + +* interface - interface to which this session is tied to +* local-addr - local address (ipv4 or ipv6) +* peer-addr - peer address (ipv4 or ipv6, must match local-addr family) + +Example: + +> bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 + +##### Set session admin-up or admin-down + +> bfd udp session set-flags interface <interface> local-addr <address> peer-addr <address> admin <up|down> + +Parameters: + +* interface - interface to which this session is tied to +* local-addr - local address (ipv4 or ipv6) +* peer-addr - peer address (ipv4 or ipv6, must match local-addr family) +* admin - up/down based on desired action + +Example: + +> bfd udp session set-flags admin down interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 + +##### Activate/change authentication for existing session + +> bfd udp session auth activate interface <interface> local-addr <address> peer-addr <address> conf-key-id <ID> bfd-key-id <ID> [ delayed <yes|no> ] + +Parameters: + +* interface - interface to which this session is tied to +* local-addr - local address (ipv4 or ipv6) +* peer-addr - peer address (ipv4 or ipv6, must match local-addr family) +* conf-key-id - local configuration key ID +* bfd-key-id - BFD key ID, as carried in BFD control frames +* delayed - is yes then this action is delayed until the peer performs the same action + +Example: + +> bfd udp session auth activate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 conf-key-id 540928695 bfd-key-id 239 delayed yes + +Notes: + +* see [Delayed option] for more information + +##### Deactivate authentication for existing session + +> bfd udp session auth deactivate interface <interface> local-addr <address> peer-addr <address> [ delayed <yes|no> ] + +Parameters: + +* interface - interface to which this session is tied to +* local-addr - local address (ipv4 or ipv6) +* peer-addr - peer address (ipv4 or ipv6, must match local-addr family) +* delayed - is yes then this action is delayed until the peer performs the same action + +Example: + +> bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 + +Notes: + +* see [Delayed option] for more information + +##### Set echo-source interface + +> bfd udp echo-source set interface <interface> + +Parameters: + +* interface - interface used for getting source address for echo packets + +Example: + +> bfd udp echo-source set interface loop0 + +##### Delete echo-source interface + +> bfd udp echo-source del + +Example: + +> bfd udp echo-source del + +### Authentication + +BFD sessions should be authenticated for security purposes. SHA1 and meticulous +SHA1 authentication is supported by VPP. First, authentication keys are +configured in VPP and afterwards they can be used by sessions. + +There are two key IDs in the scope of BFD session: + +* configuration key ID is the internal unique key ID inside VPP and is never + communicated to any peer, it serves only the purpose of identifying the key +* BFD key ID is the key ID carried in BFD control frames and is used for + verifying authentication + +#### Turning auth on/off + +Authentication can be turned on or off at any time. Care must be taken however, +to either synchronize the authentication manipulation with peer's actions +to avoid the session going down. + +##### Delayed option + +Delayed option is useful for synchronizing authentication changes with a peer. +If it's specified, then authentication change is not performed immediately. +In this case, VPP continues to transmit packets using the old authentication +method (unauthenticated or using old sha1 key). If a packet is received, which +does not pass the current authentication, then VPP tries to authenticate it +using the new method (which might be none, if deactivating authentication) +and if it passes, then the new authentication method is put in use. + +The recommended procedure for enabling/changing/disabling session +authentication is: + +1. perform authentication change on vpp's side with delayed option set to yes +2. perform authentication change on peer's side (without delayed option) + +Notes: + +* if both peers use delayed option at the same time, the change will never + be carried out, since none of the peers will see any packet with the new + authentication which could trigger the change +* remote peer does not need to support or even be aware of this mechanism + for it to work properly + + +### Echo function + +Echo function is used by VPP whenever a peer declares the willingness +to support it, echo-source is set and it contains a usable subnet (see below). +When echo function is switched on, the required min rx interval advertised +to peer is set to 1 second (or the configured value, if its higher). + +#### Echo source address + +Because echo packets are only looped back (and not processed in any way) +by a peer, it's necessary to set the source address in a way which avoids +packet drop due to spoofing protection by VPP. Per RFC, the source address +should not be in the subnet set on the interface over which the echo packets +are sent. Also, it must not be any VPP-local address, otherwise the packet +gets dropped on receipt by VPP. The solution is to create a loopback interface +with a (private) IPv4/IPv6 subnet assigned as echo-source. The BFD then picks +an unused address from the subnet by flipping the last bit and uses that as +source address in the echo packets, thus meeting RFC recommendation while +avoiding spoofing protection. + +Example: if 10.10.10.3/31 is the subnet, then 10.10.10.2 will be used as + source address in (IPv4) echo packets + +### Demand mode + +Demand mode is respected by VPP, but not used locally. The only scenario when +demand mode could make sense currently is when echo is active. Because echo +packets are inherently insecure against an adversary looping them back a poll +sequence would be required for slow periodic connectivity verification anyway. +It's more efficient to just ask the remote peer to send slow periodic control +frames without VPP initiating periodic poll sequences. + +### Admin-down + +Session may be put admin-down at any time. This immediately causes the state +to be changed to AdminDown and remain so unless the session is put admin-up. + +## BFD implementation notes + +Because BFD can work over different transport layers, the BFD code is separated +into core BFD functionality - main module implemented in bfd_main.c +and transport-specific code implemented in bfd_udp.c. + +### Main module + +Main module is responsible for handling all the BFD functionality defined +in RFC 5880. + +#### Internal API + +Internal APIs defined in bfd_main.h are called from transport-specific code +to create/modify/delete + +#### Packet receipt + +When a packet is received by the transport layer, it is forwarded to main +module (to main thread) via an RPC call. At this point, the authentication has +been verified, so the packet is consumed, session parameters are updated +accordingly and state change (if applicable). Based on these, the timeouts +are adjusted if required and an event is sent to the process node to wake up +and recalculate sleep time. + +#### Packet transmit + +Main module allocates a vlib_buffer_t, creates the required BFD frame (control +or echo in it), then calls the transport layer to add the transport layer. +Then a frame containing the buffer to the aprropriate node is created +and enqueued. + +#### Process node + +Main module implements one process node which is a simple loop. The process +node gets next timeout from the timer wheel, sleeps until the timeout expires +and then calls a timeout routine which drives the state machine for each +session which timed out. The sleep is interrupted externally via vlib event, +when a session is added or modified in a way which might require timer wheel +manipulation. In this case the caller inserts the necessary timeout to timer +wheel and then signals the process node to wake up early, handle possible +timeouts and recalculate the sleep time again. + +#### State machine + +Default state of BFD session when created is Down, per RFC 5880. State changes +to Init, Up or Down based on events like received state from peer and timeouts. +The session state can be set AdminDown using a binary API, which prevents it +from going to any other state, until this limitation is removed. This state +is advertised to peers in slow periodic control frames. + +For each session, the following timeouts are maintained: + +1. tx timeout - used for sending out control frames +2. rx timeout - used for detecting session timeout +3. echo tx timeout - used for sending out echo frames +3. echo rx timeout - used for detecting session timeout based on echo + +These timeouts are maintained in cpu clocks and recalculated when appropriate +(e.g. rx timeout is bumped when a packet is received, keeping the session +alive). Only the earliest timeout is inserted into the timer wheel at a time +and timer wheel events are never deleted, rather spurious events are ignored. +This allows efficient operation, like not inserting events into timing wheel +for each packet received or ignoring left-over events in case a bfd session +gets removed and a new one is recreated with the same session index. + +#### Authentication keys management + +Authentication keys are managed internally in a pool, with each key tracking +it's use count. The removal/modification is only allowed if the key is not in +use. + +### UDP module + +UDP module is responsible for: + +1. public APIs/CLIs to configure BFD over UDP. +2. support code called by main module to encapsulate/decapsulate BFD packets + +This module implements two graph nodes - for consuming ipv4 and ipv6 packets +target at BFD ports 3874 and 3875. + +#### Packet receipt + +BFD packet receipt receipt starts in the bfd udp graph nodes. Since the code +needs to verify IP/UDP header data, it relies on ip4-local (and ip6-local) +nodes to store pointers to the appropriate headers. First, your discriminator +is extracted from BFD packet and used to lookup the existing session. In case +it's zero, the pair of IP addresses and sw_if_index is used to lookup session. +Then, main module is called to verify the authentication, if present. +Afterwards a check is made if the IP/UDP headers are correct. If yes, then +an RPC call is made to the main thread to consume the packet and take action +upon it. + +#### Packet transmission + +When process node decides that there is a need to transmit the packet, it +creates a buffer, fills the BFD frame data in and calls the UDP module to +add the transport layer. This is a simple operation for the control frames +consisting of just adding UDP/IP headers based on session data. For echo +frames, an additional step, looking at the echo-source interface and picking +and address is performed and if this fails, then the packet cannot be +transmitted and an error is returned to main thread. diff --git a/src/vnet/bfd/bfd_main.c b/src/vnet/bfd/bfd_main.c index d38623c1e0a..ea6db1f9d27 100644 --- a/src/vnet/bfd/bfd_main.c +++ b/src/vnet/bfd/bfd_main.c @@ -1606,8 +1606,6 @@ bfd_consume_pkt (bfd_main_t * bm, const bfd_pkt_t * pkt, u32 bs_idx) bfd_set_remote_required_min_echo_rx (bm, bs, now, clib_net_to_host_u32 (pkt->req_min_echo_rx)); - /* FIXME 6.8.2 */ - /* FIXME 6.8.4 */ if (bfd_pkt_get_final (pkt)) { if (BFD_POLL_IN_PROGRESS == bs->poll_state) @@ -1915,13 +1913,13 @@ bfd_auth_set_key (u32 conf_key_id, u8 auth_type, u8 key_len, { #if WITH_LIBSSL > 0 bfd_auth_key_t *auth_key = NULL; - if (!key_len || key_len > bfd_max_len_for_auth_type (auth_type)) + if (!key_len || key_len > bfd_max_key_len_for_auth_type (auth_type)) { clib_warning ("Invalid authentication key length for auth_type=%d:%s " "(key_len=%u, must be " "non-zero, expected max=%u)", auth_type, bfd_auth_type_str (auth_type), key_len, - (u32) bfd_max_len_for_auth_type (auth_type)); + (u32) bfd_max_key_len_for_auth_type (auth_type)); return VNET_API_ERROR_INVALID_VALUE; } if (!bfd_auth_type_supported (auth_type)) diff --git a/src/vnet/bfd/bfd_main.h b/src/vnet/bfd/bfd_main.h index 3be3694c0f5..4d460f41f46 100644 --- a/src/vnet/bfd/bfd_main.h +++ b/src/vnet/bfd/bfd_main.h @@ -37,19 +37,19 @@ typedef enum typedef struct { - /* global configuration key ID */ + /** global configuration key ID */ u32 conf_key_id; - /* keeps track of how many sessions reference this key */ + /** keeps track of how many sessions reference this key */ u32 use_count; - /* + /** * key data directly usable for bfd purposes - already padded with zeroes * (so we don't need the actual length) */ u8 key[20]; - /* authentication type for this key */ + /** authentication type for this key */ bfd_auth_type_e auth_type; } bfd_auth_key_t; @@ -68,152 +68,152 @@ typedef enum typedef struct bfd_session_s { - /* index in bfd_main.sessions pool */ + /** index in bfd_main.sessions pool */ u32 bs_idx; - /* session state */ + /** session state */ bfd_state_e local_state; - /* remote session state */ + /** remote session state */ bfd_state_e remote_state; - /* local diagnostics */ + /** local diagnostics */ bfd_diag_code_e local_diag; - /* remote diagnostics */ + /** remote diagnostics */ bfd_diag_code_e remote_diag; - /* local discriminator */ + /** local discriminator */ u32 local_discr; - /* remote discriminator */ + /** remote discriminator */ u32 remote_discr; - /* configured desired min tx interval (microseconds) */ + /** configured desired min tx interval (microseconds) */ u32 config_desired_min_tx_usec; - /* configured desired min tx interval (clocks) */ + /** configured desired min tx interval (clocks) */ u64 config_desired_min_tx_clocks; - /* effective desired min tx interval (clocks) */ + /** effective desired min tx interval (clocks) */ u64 effective_desired_min_tx_clocks; - /* configured required min rx interval (microseconds) */ + /** configured required min rx interval (microseconds) */ u32 config_required_min_rx_usec; - /* configured required min rx interval (clocks) */ + /** configured required min rx interval (clocks) */ u64 config_required_min_rx_clocks; - /* effective required min rx interval (clocks) */ + /** effective required min rx interval (clocks) */ u64 effective_required_min_rx_clocks; - /* remote min rx interval (microseconds) */ + /** remote min rx interval (microseconds) */ u64 remote_min_rx_usec; - /* remote min rx interval (clocks) */ + /** remote min rx interval (clocks) */ u64 remote_min_rx_clocks; - /* remote min echo rx interval (microseconds) */ + /** remote min echo rx interval (microseconds) */ u64 remote_min_echo_rx_usec; - /* remote min echo rx interval (clocks) */ + /** remote min echo rx interval (clocks) */ u64 remote_min_echo_rx_clocks; - /* remote desired min tx interval (clocks) */ + /** remote desired min tx interval (clocks) */ u64 remote_desired_min_tx_clocks; - /* configured detect multiplier */ + /** configured detect multiplier */ u8 local_detect_mult; - /* 1 if remote system sets demand mode, 0 otherwise */ + /** 1 if remote system sets demand mode, 0 otherwise */ u8 remote_demand; - /* remote detect multiplier */ + /** remote detect multiplier */ u8 remote_detect_mult; - /* 1 is echo function is active, 0 otherwise */ + /** 1 is echo function is active, 0 otherwise */ u8 echo; - /* set to value of timer in timing wheel, 0 if never set */ + /** set to value of timer in timing wheel, 0 if never set */ u64 wheel_time_clocks; - /* transmit interval */ + /** transmit interval */ u64 transmit_interval_clocks; - /* next time at which to transmit a packet */ + /** next time at which to transmit a packet */ u64 tx_timeout_clocks; - /* timestamp of last packet transmitted */ + /** timestamp of last packet transmitted */ u64 last_tx_clocks; - /* timestamp of last packet received */ + /** timestamp of last packet received */ u64 last_rx_clocks; - /* transmit interval for echo packets */ + /** transmit interval for echo packets */ u64 echo_transmit_interval_clocks; - /* next time at which to transmit echo packet */ + /** next time at which to transmit echo packet */ u64 echo_tx_timeout_clocks; - /* timestamp of last echo packet transmitted */ + /** timestamp of last echo packet transmitted */ u64 echo_last_tx_clocks; - /* timestamp of last echo packet received */ + /** timestamp of last echo packet received */ u64 echo_last_rx_clocks; - /* secret used for calculating/checking checksum of echo packets */ + /** secret used for calculating/checking checksum of echo packets */ u32 echo_secret; - /* detection time */ + /** detection time */ u64 detection_time_clocks; - /* state info regarding poll sequence */ + /** state info regarding poll sequence */ bfd_poll_state_e poll_state; - /* + /** * helper for delayed poll sequence - marks either start of running poll * sequence or timeout, after which we can start the next poll sequnce */ u64 poll_state_start_or_timeout_clocks; - /* authentication information */ + /** authentication information */ struct { - /* current key in use */ + /** current key in use */ bfd_auth_key_t *curr_key; - /* + /** * set to next key to use if delayed switch is enabled - in that case * the key is switched when first incoming packet is signed with next_key */ bfd_auth_key_t *next_key; - /* sequence number incremented occasionally or always (if meticulous) */ + /** sequence number incremented occasionally or always (if meticulous) */ u32 local_seq_number; - /* remote sequence number */ + /** remote sequence number */ u32 remote_seq_number; - /* set to 1 if remote sequence number is known */ + /** set to 1 if remote sequence number is known */ u8 remote_seq_number_known; - /* current key ID sent out in bfd packet */ + /** current key ID sent out in bfd packet */ u8 curr_bfd_key_id; - /* key ID to use when switched to next_key */ + /** key ID to use when switched to next_key */ u8 next_bfd_key_id; - /* + /** * set to 1 if delayed action is pending, which might be activation * of authentication, change of key or deactivation */ u8 is_delayed; } auth; - /* transport type for this session */ + /** transport type for this session */ bfd_transport_e transport; - /* union of transport-specific data */ + /** union of transport-specific data */ union { bfd_udp_session_t udp; @@ -222,48 +222,48 @@ typedef struct bfd_session_s typedef struct { - /* pool of bfd sessions context data */ + /** pool of bfd sessions context data */ bfd_session_t *sessions; - /* timing wheel for scheduling timeouts */ + /** timing wheel for scheduling timeouts */ timing_wheel_t wheel; - /* timing wheel inaccuracy, in clocks */ + /** timing wheel inaccuracy, in clocks */ u64 wheel_inaccuracy; - /* hashmap - bfd session by discriminator */ + /** hashmap - bfd session by discriminator */ u32 *session_by_disc; - /* background process node index */ + /** background process node index */ u32 bfd_process_node_index; - /* convenience variables */ + /** convenience variables */ vlib_main_t *vlib_main; vnet_main_t *vnet_main; - /* cpu clocks per second */ + /** cpu clocks per second */ f64 cpu_cps; - /* default desired min tx in clocks */ + /** default desired min tx in clocks */ u64 default_desired_min_tx_clocks; - /* minimum required min rx while echo function is active - clocks */ + /** minimum required min rx while echo function is active - clocks */ u64 min_required_min_rx_while_echo_clocks; - /* for generating random numbers */ + /** for generating random numbers */ u32 random_seed; - /* pool of authentication keys */ + /** pool of authentication keys */ bfd_auth_key_t *auth_keys; - /* hashmap - index in pool auth_keys by conf_key_id */ + /** hashmap - index in pool auth_keys by conf_key_id */ u32 *auth_key_by_conf_key_id; } bfd_main_t; extern bfd_main_t bfd_main; -/* Packet counters */ +/** Packet counters */ #define foreach_bfd_error(F) \ F (NONE, "good bfd packets (processed)") \ F (BAD, "invalid bfd packets") \ @@ -277,7 +277,7 @@ typedef enum BFD_N_ERROR, } bfd_error_t; -/* bfd packet trace capture */ +/** bfd packet trace capture */ typedef struct { u32 len; @@ -291,14 +291,14 @@ enum BFD_EVENT_CONFIG_CHANGED, } bfd_process_event_e; -/* echo packet structure */ /* *INDENT-OFF* */ +/** echo packet structure */ typedef CLIB_PACKED (struct { - /* local discriminator */ + /** local discriminator */ u32 discriminator; - /* expire time of this packet - clocks */ + /** expire time of this packet - clocks */ u64 expire_time_clocks; - /* checksum - based on discriminator, local secret and expire time */ + /** checksum - based on discriminator, local secret and expire time */ u64 checksum; }) bfd_echo_pkt_t; /* *INDENT-ON* */ @@ -335,10 +335,10 @@ const char *bfd_poll_state_string (bfd_poll_state_e state); #define USEC_PER_MS 1000LL #define USEC_PER_SECOND (1000 * USEC_PER_MS) -/* default, slow transmission interval for BFD packets, per spec at least 1s */ +/** default, slow transmission interval for BFD packets, per spec at least 1s */ #define BFD_DEFAULT_DESIRED_MIN_TX_USEC USEC_PER_SECOND -/* +/** * minimum required min rx set locally when echo function is used, per spec * should be set to at least 1s */ diff --git a/src/vnet/bfd/bfd_protocol.c b/src/vnet/bfd/bfd_protocol.c index 5deb9702eb3..cd51e91a856 100644 --- a/src/vnet/bfd/bfd_protocol.c +++ b/src/vnet/bfd/bfd_protocol.c @@ -12,6 +12,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * @file + * @brief BFD protocol implementation + */ #include <vnet/bfd/bfd_protocol.h> u8 @@ -131,7 +135,7 @@ bfd_pkt_set_multipoint (bfd_pkt_t * pkt) #endif u32 -bfd_max_len_for_auth_type (bfd_auth_type_e auth_type) +bfd_max_key_len_for_auth_type (bfd_auth_type_e auth_type) { #define F(t, l, n, s) \ if (auth_type == t) \ diff --git a/src/vnet/bfd/bfd_protocol.h b/src/vnet/bfd/bfd_protocol.h index cdbb8fa7bd3..210c561b430 100644 --- a/src/vnet/bfd/bfd_protocol.h +++ b/src/vnet/bfd/bfd_protocol.h @@ -40,7 +40,10 @@ typedef enum #undef F } bfd_auth_type_e; -u32 bfd_max_len_for_auth_type (bfd_auth_type_e auth_type); +/** + * @brief get the maximum length of key data for given auth type + */ +u32 bfd_max_key_len_for_auth_type (bfd_auth_type_e auth_type); const char *bfd_auth_type_str (bfd_auth_type_e auth_type); /* *INDENT-OFF* */ diff --git a/src/vnet/bfd/bfd_udp.c b/src/vnet/bfd/bfd_udp.c index e6dbaabb36c..b3eabc9cda9 100644 --- a/src/vnet/bfd/bfd_udp.c +++ b/src/vnet/bfd/bfd_udp.c @@ -12,6 +12,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * @file + * @brief BFD UDP transport layer implementation + */ #include <vppinfra/types.h> #include <vlibmemory/api.h> #include <vlib/vlib.h> diff --git a/src/vnet/bfd/bfd_udp.h b/src/vnet/bfd/bfd_udp.h index e33b7407d56..5080ec98f75 100644 --- a/src/vnet/bfd/bfd_udp.h +++ b/src/vnet/bfd/bfd_udp.h @@ -13,7 +13,7 @@ */ /** * @file - * @brief BFD global declarations + * @brief BFD UDP transport layer declarations */ #ifndef __included_bfd_udp_h__ @@ -25,23 +25,27 @@ #include <vnet/bfd/bfd_api.h> /* *INDENT-OFF* */ +/** identifier of BFD session based on UDP transport only */ typedef CLIB_PACKED (struct { - + /** interface to which the session is tied */ u32 sw_if_index; + /** local address */ ip46_address_t local_addr; + /** peer address */ ip46_address_t peer_addr; - }) bfd_udp_key_t; /* *INDENT-ON* */ +/** UDP transport specific data embedded in bfd_session's union */ typedef struct { + /** key identifying this session */ bfd_udp_key_t key; - + /** adjacency index returned from adj lock call */ adj_index_t adj_index; } bfd_udp_session_t; -/* bfd udp echo packet trace capture */ +/** bfd udp echo packet trace capture */ typedef struct { u32 len; @@ -50,8 +54,23 @@ typedef struct struct bfd_session_s; +/** + * @brief add the necessary transport layer by prepending it to existing data + * + * @param is_echo 1 if this is echo packet, 0 if control frame + * + * @return 1 on success, 0 on failure + */ int bfd_add_udp4_transport (vlib_main_t * vm, vlib_buffer_t * b, const struct bfd_session_s *bs, int is_echo); + +/** + * @brief add the necessary transport layer by prepending it to existing data + * + * @param is_echo 1 if this is echo packet, 0 if control frame + * + * @return 1 on success, 0 on failure + */ int bfd_add_udp6_transport (vlib_main_t * vm, vlib_buffer_t * b, const struct bfd_session_s *bs, int is_echo); @@ -62,10 +81,12 @@ int bfd_add_udp6_transport (vlib_main_t * vm, vlib_buffer_t * b, */ int bfd_udp_is_echo_available (bfd_transport_e transport); -void -bfd_udp_get_echo_source (int *is_set, u32 * sw_if_index, int *have_usable_ip4, - ip4_address_t * ip4, int *have_usable_ip6, - ip6_address_t * ip6); +/** + * @brief get echo source information - used by CLI + */ +void bfd_udp_get_echo_source (int *is_set, u32 * sw_if_index, + int *have_usable_ip4, ip4_address_t * ip4, + int *have_usable_ip6, ip6_address_t * ip6); #endif /* __included_bfd_udp_h__ */ diff --git a/src/vnet/bfd/dir.dox b/src/vnet/bfd/dir.dox index ed656b52074..b9a5978f416 100644 --- a/src/vnet/bfd/dir.dox +++ b/src/vnet/bfd/dir.dox @@ -13,6 +13,6 @@ * limitations under the License. */ /** - @dir vnet/vnet/bfd + @dir @brief Bidirectional Forwarding Detection (BFD) implementation */ |