RIOT/sys/include/net/ng_ipv6/nc.h

/*
 * Copyright (C) 2015 Martine Lenders <mlenders@inf.fu-berlin.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_ng_ipv6_nc  IPv6 neighbor cache
 * @ingroup     net_ng_ipv6
 * @brief       Translates IPv6 addresses to link layer addresses.
 * @{
 *
 * @file
 * @brief       Neighbor cache definitions.
 *
 * @author      Martine Lenders <mlenders@inf.fu-berlin.de>
 */

#ifndef NG_IPV6_NC_H_
#define NG_IPV6_NC_H_

#include <stdint.h>

#include "kernel_types.h"
#include "net/ng_ipv6/addr.h"
#include "net/ng_netif.h"
#include "net/ng_pktqueue.h"
#include "timex.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifndef NG_IPV6_NC_SIZE
/**
 * @brief   The size of the neighbor cache
 */
#define NG_IPV6_NC_SIZE             (NG_NETIF_NUMOF * 8)
#endif

#ifndef NG_IPV6_NC_L2_ADDR_MAX
/**
 * @brief   The maximum size of a link layer address
 */
#define NG_IPV6_NC_L2_ADDR_MAX      (8)
#endif

/**
 * @{
 * @name Flag definitions for ng_ipv6_nc_t
 */
/**
 * @{
 * @brief   States of a neighbor cache entry.
 *
 * @see <a href="http://tools.ietf.org/html/rfc4861#section-7.3.2">
 *          RFC 4861, section 7.3.2
 *      </a>
 */
#define NG_IPV6_NC_STATE_MASK           (0x07)  /**< Mask for neighbor cache state */
#define NG_IPV6_NC_STATE_POS            (0)     /**< Shift of neighbor cache state */

#define NG_IPV6_NC_STATE_UNMANAGED      (0x00)  /**< The entry is not manage by NDP */

/**
 * @brief The entry is unreachable
 *
 * @see <a href="http://tools.ietf.org/html/rfc7048#section-3">
 *          RFC 7048, section 3
 *      </a>
 */
#define NG_IPV6_NC_STATE_UNREACHABLE    (0x01)
#define NG_IPV6_NC_STATE_INCOMPLETE     (0x02)  /**< Address resolution is performed */
#define NG_IPV6_NC_STATE_STALE          (0x03)  /**< The entry is stale */
#define NG_IPV6_NC_STATE_DELAY          (0x04)  /**< The entry was stale but packet was sent out */
#define NG_IPV6_NC_STATE_PROBE          (0x05)  /**< Periodic reachabality confirmation */
#define NG_IPV6_NC_STATE_REACHABLE      (0x07)  /**< The entry is reachable */
/**
 * @}
 */

#define NG_IPV6_NC_IS_ROUTER            (0x08)  /**< The neighbor is a router */

#define NG_IPV6_NC_TYPE_MASK            (0x30)  /**< Mask for neighbor cache state */
#define NG_IPV6_NC_TYPE_POS             (4)     /**< Shift of neighbor cache state */

/**
 * @{
 * @brief   States of a neighbor cache entry.
 *
 * @see <a href="http://tools.ietf.org/html/rfc6775#section-3.5">
 *          RFC 6775, section 3.5
 *      </a>
 */
/**
 * @brief The entry has no type
 *
 * @details The node sents multicast Neighbor Solicitations for hosts.
 */
#define NG_IPV6_NC_TYPE_NONE            (0x00)
#define NG_IPV6_NC_TYPE_GC              (0x10)  /**< The entry is marked for removal */
#define NG_IPV6_NC_TYPE_TENTATIVE       (0x20)  /**< The entry is temporary */
#define NG_IPV6_NC_TYPE_REGISTERED      (0x30)  /**< The entry is registered */
/**
 * @}
 */
/**
 * @}
 */

/**
 * @brief   Neighbor cache entry as defined in
 *          <a href="http://tools.ietf.org/html/rfc4861#section-5.1">
 *              RFC 4861, section 5.1
 *          </a>.
 */
typedef struct {
    ng_pktqueue_t pkts;                     /**< Packets waiting for address resolution */
    ng_ipv6_addr_t ipv6_addr;               /**< IPv6 address of the neighbor */
    uint8_t l2_addr[NG_IPV6_NC_L2_ADDR_MAX];/**< Link layer address of the neighbor */
    uint8_t l2_addr_len;                    /**< Length of ng_ipv6_nc_t::l2_addr */
    uint8_t flags;                          /**< Flags as defined above */
    kernel_pid_t iface;                     /**< PID to the interface where the neighbor is */
} ng_ipv6_nc_t;

/**
 * @brief   Initializes neighbor cache
 */
void ng_ipv6_nc_init(void);

/**
 * @brief   Adds a neighbor to the neighbor cache
 *
 * @param[in] iface         PID to the interface where the neighbor is.
 *                          Must not be KERNEL_PID_UNDEF.
 * @param[in] ipv6_addr     IPv6 address of the neighbor. Must not be NULL.
 * @param[in] l2_addr       Link layer address of the neighbor. NULL if unknown.
 * @param[in] l2_addr_len   Length of @p l2_addr, must be lesser than or equal
 *                          to NG_IPV6_L2_ADDR_MAX. 0 if unknown.
 * @param[in] flags         Flags for the entry
 *
 * @return  0 on success
 * @return  -EADDRINUSE, if @p ipv6_addr is already registered to the neighbor
 *          cache.
 * @return  -EFAULT, if @p ipv6_addr was NULL.
 * @return  -EINVAL, if @p l2_addr_len is greater then @ref NG_IPV6_NC_L2_ADDR_MAX,
 *          @p ipv6_addr is unspecified or @p iface is KERNEL_PID_UNDEF.
 * @return  -ENOMEM, if no space is left to store entry.
 */
int ng_ipv6_nc_add(kernel_pid_t iface, const ng_ipv6_addr_t *ipv6_addr,
                   const void *l2_addr, size_t l2_addr_len, uint8_t flags);

/**
 * @brief   Removes a neighbor from the neighbor cache
 *
 * @param[in] iface         PID to the interface where the neighbor is. If it
 *                          is KERNEL_PID_UNDEF it will be removed for all
 *                          interfaces.
 * @param[in] ipv6_addr     IPv6 address of the neighbor
 */
void ng_ipv6_nc_remove(kernel_pid_t iface, const ng_ipv6_addr_t *ipv6_addr);

/**
 * @brief   Searches for any neighbor cache entry fitting the @p ipv6_addr.
 *
 * @param[in] iface         PID to the interface where the neighbor is. If it
 *                          is KERNEL_PID_UNDEF it will be searched on all
 *                          interfaces.
 * @param[in] ipv6_addr     An IPv6 address
 *
 * @return  The neighbor cache entry, if one is found.
 * @return  NULL, if none is found.
 */
ng_ipv6_nc_t *ng_ipv6_nc_get(kernel_pid_t iface, const ng_ipv6_addr_t *ipv6_addr);

/**
 * @brief   Searches for any neighbor cache entry fitting the @p ipv6_addr,
 *          where you currently can send a packet to (do not confuse with
 *          NG_IPV6_NC_STATE_REACHABLE).
 *
 * @param[in] iface         PID to the interface where the neighbor is. If it
 *                          is KERNEL_PID_UNDEF it will be searched on all
 *                          interfaces.
 * @param[in] ipv6_addr     An IPv6 address
 *
 * @return  The neighbor cache entry, if one is found.
 * @return  NULL, if none is found.
 */
ng_ipv6_nc_t *ng_ipv6_nc_get_reachable(kernel_pid_t iface,
                                       const ng_ipv6_addr_t *ipv6_addr);

/**
 * @brief   Marks an entry as still reachable, if one with a fitting @p ipv6_addr
 *          can be found.
 *
 * @details This function can be used by upper layer protocols for neighbor
 *          discovery optimization to confirm that there was a reachability
 *          confirmation (e. g. an ACK in TCP) from the neighbor.
 *
 * @see <a href="http://tools.ietf.org/html/rfc4861#section-7.3.1">
 *          RFC 4861, section 7.3.1
 *      </a>
 *
 * @param[in] ipv6_addr     An IPv6 address
 *
 * @return  The neighbor cache entry, if one is found.
 * @return  NULL, if none is found.
 */
ng_ipv6_nc_t *ng_ipv6_nc_still_reachable(const ng_ipv6_addr_t *ipv6_addr);

#ifdef __cplusplus
}
#endif

#endif /* NG_IPV6_NC_H_ */
/**
 * @}
 */