RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity
630b14b322
RIOT/sys/include/net/fib.h
Benjamin Valentin 378e5e2382 fib: document unused state
2023-02-22 16:47:14 +01:00

519 lines
20 KiB
C
Raw Blame History

/*
* Copyright (C) 2014 Martin Landsmann <Martin.Landsmann@HAW-Hamburg.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @defgroup net_fib Forwarding Information Base (FIB)
* @ingroup net
* @brief FIB implementation
*
* This module is unused by RIOT's networking stacks, see @ref net_gnrc_ipv6_nib_ft
* instead.
* @{
*
* @file
* @brief Types and functions for FIB
* @note The used fib_table_t* used in all essential FIB functions
* MUST be valid.
*
* @author Martin Landsmann <martin.landsmann@haw-hamburg.de>
* @author Oliver Hahm <oliver.hahm@inria.fr>
*/
#ifndef NET_FIB_H
#define NET_FIB_H
#include <stdint.h>
#include "net/fib/table.h"
#include "sched.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Routing Protocol (RP) message content to request/reply notification
*/
typedef struct {
uint8_t *address; /**< The pointer to the address */
uint8_t address_size; /**< The address size */
uint32_t address_flags; /**< The flags for the given address */
} rp_address_msg_t;
/**
* @brief message type for RP notification: no route to destination available,
* start route discovery if appropriate
*/
#define FIB_MSG_RP_SIGNAL_UNREACHABLE_DESTINATION (0x99)
/**
* @brief message type for RP notification: entry used
*/
#define FIB_MSG_RP_SIGNAL_DESTINATION_USED (0x98)
/**
* @brief message type for RP notification: source route created
*/
#define FIB_MSG_RP_SIGNAL_SOURCE_ROUTE_CREATED (0x97)
/**
* @brief entry used to collect available destinations
*/
typedef struct {
uint8_t dest[UNIVERSAL_ADDRESS_SIZE]; /**< The destination address */
size_t dest_size; /**< The destination address size */
} fib_destination_set_entry_t;
/**
* @brief indicator of a lifetime that does not expire (2^64 - 1)
*/
#define FIB_LIFETIME_NO_EXPIRE (0xFFFFFFFFffffffff)
/**
* @brief flag to identify if a route was set by RPL
*/
#define FIB_FLAG_RPL_ROUTE (1UL << 0)
/**
* @brief flag used as shift for the net prefix length in bits
*/
#define FIB_FLAG_NET_PREFIX_SHIFT (24)
/**
* @brief flag used as mask for the net prefix length in bits
*/
#define FIB_FLAG_NET_PREFIX_MASK (0xffUL << FIB_FLAG_NET_PREFIX_SHIFT)
/**
* @brief initializes all FIB entries with 0
*
* @param[in] table the fib instance to initialize
*/
void fib_init(fib_table_t *table);
/**
* @brief de-initializes the FIB entries and source route entries
*
* @param[in] table the fib instance to de-initialize
*/
void fib_deinit(fib_table_t *table);
/**
* @brief Registration of a routing protocol handler function
*
* @param[in] table the fib table the RP should be registered to
* @param[in] prefix the prefix handled by the according RP
* @param[in] prefix_addr_type_size the size of the address type used for the prefix
*
* @return 0 on success
* -ENOMEM if the entry cannot be registered (mximum registrations reached)
* -EINVAL if the prefix is NULL or the provided size is 0
*
*/
int fib_register_rp(fib_table_t *table, uint8_t *prefix, size_t prefix_addr_type_size);
/**
* @brief Adds a new entry in the corresponding FIB table for global destination and next hop
*
* @param[in] table the fib table the entry should be added to
* @param[in] iface_id the interface ID
* @param[in] dst the destination address
* @param[in] dst_size the destination address size
* @param[in] dst_flags the destination address flags
* @param[in] next_hop the next hop address to be updated
* @param[in] next_hop_size the next hop address size
* @param[in] next_hop_flags the next-hop address flags
* @param[in] lifetime the lifetime in ms to be updates
*
* @return 0 on success
* -ENOMEM if the entry cannot be created due to insufficient RAM
* -EFAULT if dst and/or next_hop is not a valid pointer
*/
int fib_add_entry(fib_table_t *table, kernel_pid_t iface_id, uint8_t *dst,
size_t dst_size, uint32_t dst_flags, uint8_t *next_hop,
size_t next_hop_size, uint32_t next_hop_flags,
uint32_t lifetime);
/**
* @brief Updates an entry in the FIB table with next hop and lifetime
*
* @param[in] table the fib table containing the entry to update
* @param[in] dst the destination address
* @param[in] dst_size the destination address size
* @param[in] next_hop the next hop address to be updated
* @param[in] next_hop_size the next hop address size
* @param[in] next_hop_flags the next-hop address flags
* @param[in] lifetime the lifetime in ms to be updates
*
* @return 0 on success
* -ENOMEM if the entry cannot be updated due to insufficient RAM
* -EFAULT if dst and/or next_hop is not a valid pointer
*/
int fib_update_entry(fib_table_t *table, uint8_t *dst, size_t dst_size,
uint8_t *next_hop, size_t next_hop_size,
uint32_t next_hop_flags, uint32_t lifetime);
/**
* @brief removes an entry from the corresponding FIB table
*
* @param[in] table the fib table containing the entry to remove
* @param[in] dst the destination address
* @param[in] dst_size the destination address size
*/
void fib_remove_entry(fib_table_t *table, uint8_t *dst, size_t dst_size);
/**
* @brief removes all entries from the corresponding FIB table and interface combination
*
* @note if interface is KERNEL_PID_UNDEF, then all entries regardless of the interface
* will be removed.
*
* @param[in] table the fib table to flush
* @param[in] interface entries associated with this interface will be removed
*/
void fib_flush(fib_table_t *table, kernel_pid_t interface);
/**
* @brief provides a next hop for a given destination
*
* @param[in] table the fib table that should be searched
* @param[in, out] iface_id pointer to store the interface ID for the next hop
* @param[out] next_hop pointer where the next hop address should be stored
* @param[in, out] next_hop_size the next hop address size. The value is
* overwritten with the actual next hop size
* @param[out] next_hop_flags the next-hop address flags, e.g. compression type
* @param[in] dst the destination address
* @param[in] dst_size the destination address size
* @param[in] dst_flags the destination address flags
*
* @return 0 on success
* -EHOSTUNREACH if no next hop is available in any FIB table
* all RRPs are notified before the return
* -ENOBUFS if the size for the next hop address is insufficient low
* -EFAULT if dst and/or next_hop is not a valid pointer
* -EINVAL if one of the other passed out pointers is NULL
*/
int fib_get_next_hop(fib_table_t *table, kernel_pid_t *iface_id,
uint8_t *next_hop, size_t *next_hop_size,
uint32_t* next_hop_flags, uint8_t *dst, size_t dst_size,
uint32_t dst_flags);
/**
* @brief provides a set of destination addresses matching the given prefix
* If the out buffer is insufficient low or passed as NULL,
* the function will continue to count the number of matching entries
* and provide the number to the caller.
*
* @param[in] table the fib table that should be searched
* @param[in] prefix the destination address
* @param[in] prefix_size the destination address size
* @param[out] dst_set the destination addresses matching the prefix
* @param[in,out] dst_set_size the number of entries available on in and used
* on out
*
* @return 0 on success
* -EHOSTUNREACH if no entry matches the type in the FIB
* -ENOBUFS if the size for the found entries is insufficient low
* The actual needed size is stored then in dst_set_size,
* however the required size may change in between calls.
*/
int fib_get_destination_set(fib_table_t *table, uint8_t *prefix,
size_t prefix_size,
fib_destination_set_entry_t *dst_set,
size_t *dst_set_size);
/**
* @brief creates a new source route
*
* @param[in, out] table the table the new source route belongs to
* @param[in, out] fib_sr pointer to store the new created source route pointer
* @param[in] sr_iface_id the interface ID used for the created source route
* @param[in] sr_flags the flags for the source route
* @param[in] sr_lifetime the lifetime in ms of the source route
*
* @return 0 on success
* -EFAULT on wrong parameters, i.e. fib_sr is NULL and/or sr_lifetime is 0
* -ENOBUFS on insufficient memory, i.e. all source route fields are in use
*/
int fib_sr_create(fib_table_t *table, fib_sr_t **fib_sr, kernel_pid_t sr_iface_id,
uint32_t sr_flags, uint32_t sr_lifetime);
/**
* @brief reads the information from the sr head to the given locations
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to read from
* @param[in, out] sr_iface_id pointer to store the iface_id
* @param[in, out] sr_flags pointer to store the flags
* @param[in, out] sr_lifetime pointer to store the current left lifetime
*
* @return 0 on success
* -ENOENT on expired lifetime of the source route
* -EFAULT on fib_sr is NULL
*/
int fib_sr_read_head(fib_table_t *table, fib_sr_t *fib_sr, kernel_pid_t *sr_iface_id,
uint32_t *sr_flags, uint32_t *sr_lifetime);
/**
* @brief reads the destination address from the sr head to the given location
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to read from
* @param[in, out] dst pointer to the store destination address bytes
* @param[in, out] dst_size pointer to store the destination address size
*
* @return 0 on success
* -ENOENT on expired lifetime of the source route
* -EFAULT on one of the parameter pointers is NULL
* -ENOBUFS if the size to store the destination is insufficient low
* -EHOSTUNREACH on the destination address is not set
*/
int fib_sr_read_destination(fib_table_t *table, fib_sr_t *fib_sr,
uint8_t *dst, size_t *dst_size);
/**
* @brief sets the provided parameters in the given sr header if a given parameter
* is NULL its considered not to be changed
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to write to
* @param[in] sr_iface_id pointer to the new iface_id
* @param[in] sr_flags pointer to the new flags
* @param[in] sr_lifetime pointer to store the new lifetime
*
* @return 0 on success
* -ENOENT on expired lifetime of the source route
* -EFAULT on passed fib_sr is NULL
*/
int fib_sr_set(fib_table_t *table, fib_sr_t *fib_sr, kernel_pid_t *sr_iface_id,
uint32_t *sr_flags, uint32_t *sr_lifetime);
/**
* @brief deletes the sr
*
* @param[in] table the fib instance to access
* @param[in, out] fib_sr pointer to the source route to be deleted
*
* @return 0 on success
* -EFAULT on fib_sr pointer is NULL
*/
int fib_sr_delete(fib_table_t *table, fib_sr_t *fib_sr);
/**
* @brief iterates to the next entry in the sr_path
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to iterate
* @param[in, out] sr_path_entry pointer to the entry for iterating to the next entry
*
* @return 0 on success
* 1 on success, end reached
* -ENOENT on expired lifetime of the source route
* -EFAULT on fib_sr and/or sr_path_entry is NULL
*/
int fib_sr_next(fib_table_t *table, fib_sr_t *fib_sr, fib_sr_entry_t **sr_path_entry);
/**
* @brief searches the entry containing the given address
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to search for a hop address
* @param[in] addr pointer to the searched address bytes
* @param[in] addr_size the size in bytes of the searched address type
* @param[out] sr_path_entry pointer to the found address entry
*
* @return 0 on success
* -EHOSTUNREACH when no address matches on the path
* -ENOENT on expired lifetime of the source route
* -EFAULT on one of the given parameter pointer is NULL
*/
int fib_sr_search(fib_table_t *table, fib_sr_t *fib_sr, uint8_t *addr, size_t addr_size,
fib_sr_entry_t **sr_path_entry);
/**
* @brief append a new entry at the end of the source route, i.e. a new destination
*
* @param[in] table the table with the source route to append the new entry
* @param[in] fib_sr pointer to the sr to append a hop address
* @param[in] dst pointer to the new destination address bytes
* @param[in] dst_size the size in bytes of the destination address type
*
* @return 0 on success
* -EINVAL on the given destination is already on the path in the source route
* -ENOENT on expired lifetime of the source route
* -EFAULT on fib_sr and/or dst is NULL
*/
int fib_sr_entry_append(fib_table_t *table, fib_sr_t *fib_sr,
uint8_t *dst, size_t dst_size);
/**
* @brief adds a new entry behind a given sr entry
*
* @param[in] table the table with the source route to add the new entry
* @param[in] fib_sr pointer to the sr to add a hop address
* @param[in] sr_path_entry pointer to the entry after which we add the new one
* @param[in] addr pointer to the new address bytes
* @param[in] addr_size the size in bytes of the address type
* @param[in] keep_remaining_route indicate if the remaining route after sr_path_entry
* should be kept and appended after the new entry
*
* @return 0 on success
* -EFAULT on fib_sr and/or sr_path_entry and/or addr is NULL
* -ENOENT on expired lifetime of the source route
* -EINVAL on the given address is already present in the path
*/
int fib_sr_entry_add(fib_table_t *table, fib_sr_t *fib_sr,
fib_sr_entry_t *sr_path_entry, uint8_t *addr, size_t addr_size,
bool keep_remaining_route);
/**
* @brief removes an entry from a source route
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to delete a hop address
* @param[in] addr pointer to the address bytes to delete
* @param[in] addr_size the size in bytes of the address type
* @param[in] keep_remaining_route indicate if the remaining route
* should be kept and appended after the predecessor of the removed entry
*
* @return 0 on success
* -EFAULT on one of the passed pointers is NULL
* -ENOENT on expired lifetime of the source route
*/
int fib_sr_entry_delete(fib_table_t *table, fib_sr_t *fib_sr, uint8_t *addr, size_t addr_size,
bool keep_remaining_route);
/**
* @brief overwrites the address of an entry with a new address
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to overwrite a hop address
* @param[in] addr_old pointer to the address bytes to overwrite
* @param[in] addr_old_size the size in bytes of the address type
* @param[in] addr_new pointer to the new address bytes
* @param[in] addr_new_size the size in bytes of the address type
*
* @return 0 on success
* -EINVAL on the given address is already present in the path
* -ENOMEM on no memory left to create a new address entry to overwrite the old one
* -EFAULT on one of the passed pointers is NULL
* -ENOENT on expired lifetime of the source route
*/
int fib_sr_entry_overwrite(fib_table_t *table, fib_sr_t *fib_sr,
uint8_t *addr_old, size_t addr_old_size,
uint8_t *addr_new, size_t addr_new_size);
/**
* @brief writes the address of an entry to the given out pointers
*
* @param[in] table the fib instance to access
* @param[in] fib_sr pointer to the sr to get a hop address
* @param[in] sr_path_entry pointer to the entry with the address
* @param[out] addr pointer to store the address bytes
* @param[in, out] addr_size the size in bytes of the address type
*
* @return 0 on success
* -ENOMEM on insufficient memory provided to store the address
* -EFAULT on one of the passed pointers is NULL
* -ENOENT on expired lifetime of the source route
*/
int fib_sr_entry_get_address(fib_table_t *table, fib_sr_t *fib_sr, fib_sr_entry_t *sr_path_entry,
uint8_t *addr, size_t *addr_size);
/**
* @brief copies a source route to the given destination
*
* @param[in] table table to search for a source route
* @param[in] dst pointer to the destination address bytes
* @param[in] dst_size the size in bytes of the destination address type
* @param[out] sr_iface_id pointer to the store the iface_id for this route
* @param[in, out] sr_flags pointer to store the flags of this route
* @param[out] addr_list pointer to the location for storing the source route addresses
* @param[in, out] addr_list_size the number of elements available in addr_list
* @param[in, out] element_size the provided size for one element in addr_list
* @param[in] reverse indicator if the hops should be stored in reverse order
* @param[in, out] fib_sr pointer for cosecutive receiving matching source routes.
* If NULL only the first matching source route is returned.
* If !NULL the pointer will be overwritten with the current returned fib_sr.
* The FIB skips all entries until the provided fib_sr+1.
* The fib_sr pointer is only overwritten when a further matching sr has been found.
*
* @note The actual needed size for an element and the number of elements
* is stored in addr_list_elements and element_size respectively
* when the return value is NOT -EFAULT or NOT -EHOSTUNREACH.
* However,the required size for may change in between calls.
*
* @return 0 on success, path to destination with equal flags
* 1 on success, path to destination with distinct flags
* -EFAULT on one of the provided parameter pointers is NULL
* -EHOSTUNREACH if no sr for the destination exists in the FIB
* -ENOBUFS if the size to store all hops is insufficient low
*/
int fib_sr_get_route(fib_table_t *table, uint8_t *dst, size_t dst_size, kernel_pid_t *sr_iface_id,
uint32_t *sr_flags,
uint8_t *addr_list, size_t *addr_list_size, size_t *element_size,
bool reverse, fib_sr_t **fib_sr);
/**
* @brief returns the actual number of used FIB entries
*
* @param[in] table the fib instance to check
*/
int fib_get_num_used_entries(fib_table_t *table);
/**
* @brief Prints the kernel_pid_t for all registered RRPs
*/
void fib_print_notify_rrp(void);
/**
* @brief Prints the FIB content (does not print the entries)
*
* @param[in] table the fib instance to print
*/
void fib_print_fib_table(fib_table_t *table);
/**
* @brief Prints the FIB content
*
* @param[in] table the fib instance to print
*/
void fib_print_routes(fib_table_t *table);
/**
* @brief Prints the given FIB sourceroute
*
* @param[in] table the fib instance to print
* @param [in] sr the source route to print
*/
void fib_print_sr(fib_table_t *table, fib_sr_t *sr);
#if FIB_DEVEL_HELPER
/**
* @brief get the point in time at which the entry for destination dst expires.
*
* @param[in] table the fib instance to check
* @param[out] lifetime pointer where the expiration time is written on success
* @param[in] dst the destination address
* @param[in] dst_size the destination address size
*
* @return 0 on success: entry for dst found and lifetime copied
* -EHOSTUNREACH if no fitting entry is available
*/
int fib_devel_get_lifetime(fib_table_t *table, uint64_t *lifetime, uint8_t *dst,
size_t dst_size);
#endif
#ifdef __cplusplus
}
#endif
#endif /* NET_FIB_H */
/** @} */
View Git Blame Copy Permalink