/*
 * Copyright (C) 2015 Kaspar Schleiser <kaspar@schleiser.de>
 *               2015 Ell-i open source co-operative
 *               2015-2017 Freie Universität Berlin
 *               2014 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    drivers_netdev_api Network Device Driver API
 * @ingroup     drivers_netdev
 * @brief       This is a generic low-level network driver interface
 * @{
 *
 * # About
 *
 * This interface provides a uniform API for network stacks to interact with
 * network device drivers. This interface is designed in a way, that it is
 * completely agnostic to the used network stack. This way, device drivers for
 * network devices (e.g. IEEE802.15.4 radios, Ethernet devices, ...) have to
 * implemented once and can be used with any supported network stack in RIOT.
 *
 * The functions provided by the interface cover three major parts:
 *  1. sending and receiving of actual network data
 *  2. network device configuration through reading and setting device
 *     parameters
 *  3. event handling
 *
 *
 * # The Interrupt Context Problem
 *
 * Network devices are typically connected to the host CPU via some sort of bus,
 * most commonly via SPI. This type of connection has the
 * disadvantage, that the bus is not used by the network device alone, but it
 * may be shared with other devices. This makes it necessary to synchronize
 * access to the bus to prevent bus access collisions.
 *
 * To illustrate this behavior, let's look at a typical error situation, that
 * leads to a very hard to find and debug latent failure: say we have two
 * devices A and B on the same SPI bus. Our CPU is now transferring a chunk of
 * 100 bytes to device A. After 20 bytes were transferred, device B triggers
 * an external interrupt on the host CPU. The interrupt handling now typically
 * requires the reading of some sort of status register on the 'triggering'
 * device, device B in this case. So what would happen here, is that the device
 * driver for device B would initiate a new SPI transfer on the already used bus
 * to read B's status register -> BAM.
 *
 * The peripheral drivers for shared buses (i.e. SPI and I2C) implement access
 * synchronization using mutexes, which are locked and unlocked in the driver's
 * `require` and `release` functions. The problem is now, that this type of
 * synchronization does only work in thread context, but not in interrupt
 * context. With reasonable effort and resource usage, we have no means of
 * synchronizing the bus access also in interrupt context.
 *
 * The solution to this problem as implemented by this interface is **not to
 * call any function that interacts with a device directly from interrupt
 * context**. Unfortunately this requires some added complexity for
 * synchronization efforts between thread and interrupt context to be able to
 * handle device events (i.e. external interrupts). See section
 * @ref netdev_sec_events for more information.
 *
 *
 * # Context requirements
 *
 * The `netdev` interface expects the network device drivers to run in thread
 * context (see section above). The interface was however designed in a way, to
 * allow more than one device driver to be serviced in the same thread.
 *
 * The key design element for `netdev` is, that device drivers implementing this
 * interface are not able to run stand-alone in a thread, but need some
 * bootstrapping code. This bootstrapping code can be anything from a simple
 * msg_receive() loop (as done for the GNRC adaption) to a complete network
 * stack that works without messaging entirely but is build on function call
 * interfaces.
 *
 *
 * # Sending and Receiving
 *
 * Sending data using the `netdev` interface is straight forward: simply call
 * the drivers @ref netdev_driver_t::send "send()" function, passing it the data
 * that should be sent. The caller of the @ref netdev_driver_t::send "send()"
 * function (e.g. a network stack) must hereby make sure, that the data is in
 * the correct format expected by the specific network device driver. Typically,
 * the data needs to contain a pre-filled link layer header as e.g. an
 * IEEE802.15.4 or Ethernet header.
 *
 * Receiving data using the `netdev` interface requires typically four steps:
 * 1. wait for a @ref NETDEV_EVENT_RX_COMPLETE event
 * 2. call the @ref netdev_driver_t::recv "recv()" function with `buf := NULL`
 *    and `len := 0` to get the size of the received data
 * 3. allocate a large enough buffer in some way
 * 4. call the @ref netdev_driver_t::recv "recv()" function a second time,
 *    passing the buffer and reading the received data into this buffer
 *
 * This receive sequence can of course be simplified by skipping steps 2 and 3
 * when using fixed sized pre-allocated buffers or similar means. *
 *
 * @note    The @ref netdev_driver_t::send "send()" and
 *          @ref netdev_driver_t::recv "recv()" functions **must** never be
 *          called from interrupt context.
 *
 * # Device Configuration
 *
 * The `netdev` interface covers a wide variety of network devices, which differ
 * to some extend in their configuration parameters (e.g. radios vs. wired
 * interfaces, channel selection vs. link status detection). To cover this
 * variety, `netdev` provides a generic configuration interface by exposing
 * simple @ref netdev_driver_t::get "get()" and
 * @ref netdev_driver_t::set "set()" functions. These are based on a globally
 * defined and **extendable** list of options as defined in @ref netopt.h.
 *
 * Every device driver can choose the options which it supports for reading
 * and/or writing from this list. If an option is not supported by the device
 * driver, the driver simply returns `-ENOTSUP`.
 *
 * @note    The @ref netdev_driver_t::get "get()" and
 *          @ref netdev_driver_t::set "set()" functions **must** never be called
 *          from interrupt context.
 *
 *
 * # Events {#netdev_sec_events}
 *
 * Network devices typically signal events by triggering external
 * interrupts on certain dedicated GPIO pins (in case of external devices), or
 * signal them by triggering internal interrupts directly (in case of register
 * mapped devices). As stated above, we are not allowed to do any kind of
 * interaction with our network device that involves bus access when in
 * interrupt mode. To circumvent this, the
 *
 * 1. an interrupt is triggered
 * 2. the drivers interrupt routine calls the registered @ref
 *    netdev_t::event_callback "netdev->event_callback()" function with
 *    `event:=` @ref NETDEV_EVENT_ISR as argument
 * 3. the @ref netdev_t::event_callback "netdev->event_callback()" (as it is
 *    implemented by the 'user' code) notifies the thread that hosts the device
 *    driver. This can be done in many ways, e.g. by using messaging, mutexes,
 *    thread flags and more
 * 4. the hosting thread is scheduled and calls the `netdev` interfaces
 *    @ref netdev_driver_t::isr "isr()" function
 * 5. now the driver can actual start to handle the interrupt, by e.g. reading
 *    status registers and triggering any subsequent actions like signaling
 *    a @ref NETDEV_EVENT_RX_COMPLETE
 *
 * The way that is used for waking up the hosting thread and telling is to call
 * the @ref netdev_driver_t::isr "isr()" function is completely up to the
 * `netdev` external code and can be done in many ways (e.g. sending messages, #
 * setting thread flags, unlocking mutexes, etc.).
 *
 * Any event that is not of type @ref NETDEV_EVENT_ISR is expected to be
 * triggered from thread context. This enables the code that sits on top of
 * `netdev` to perform the necessary actions right away, as for example reading
 * the received data from the network device or similar.
 *
 * @note    The @ref netdev_event_cb_t function runs in interrupt context when
 *          called for @ref NETDEV_EVENT_ISR, but it **must** run in thread
 *          context for all other events.
 *
 *
 * # Example
 *
 * The following example illustrates a receive sequence triggered by an
 * external interrupt:
 *
 * 1. packet arrives for device
 * 2. The driver previously registered an ISR for handling received packets.
 *    This ISR then calls @ref netdev_t::event_callback "netdev->event_callback()"
 *    with `event:= `@ref NETDEV_EVENT_ISR (from Interrupt Service Routine)
 *    which wakes up event handler
 * 3. event handler calls @ref netdev_driver_t::isr "netdev->driver->isr()"
 *    (from thread context)
 * 4. @ref netdev_driver_t::isr "netdev->driver->isr()" calls
 *    @ref netdev_t::event_callback "netdev->event_callback()" with
 *    `event:= `@ref NETDEV_EVENT_RX_COMPLETE
 * 5. @ref netdev_t::event_callback "netdev->event_callback()" uses
 *    @ref netdev_driver_t::recv "netdev->driver->recv()" to fetch packet
 *
 * ![RX event example](riot-netdev-rx.svg)
 *
 * @file
 * @brief       Definitions low-level network driver interface
 *
 * @author      Kaspar Schleiser <kaspar@schleiser.de>
 * @author      Martine Lenders <mlenders@inf.fu-berlin.de>
 * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
 */

#ifndef NET_NETDEV_H
#define NET_NETDEV_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <sys/uio.h>

#include "net/netopt.h"

#ifdef MODULE_NETSTATS_L2
#include "net/netstats.h"
#endif
#ifdef MODULE_L2FILTER
#include "net/l2filter.h"
#endif

enum {
    NETDEV_TYPE_UNKNOWN,
    NETDEV_TYPE_RAW,
    NETDEV_TYPE_ETHERNET,
    NETDEV_TYPE_IEEE802154,
    NETDEV_TYPE_CC110X,
    NETDEV_TYPE_LORA,
    NETDEV_TYPE_NRFMIN,
    NETDEV_TYPE_SLIP,
};

/**
 * @brief   Possible event types that are send from the device driver to the
 *          upper layer
 */
typedef enum {
    NETDEV_EVENT_ISR,                       /**< driver needs it's ISR handled */
    NETDEV_EVENT_RX_STARTED,                /**< started to receive a packet */
    NETDEV_EVENT_RX_COMPLETE,               /**< finished receiving a packet */
    NETDEV_EVENT_TX_STARTED,                /**< started to transfer a packet */
    NETDEV_EVENT_TX_COMPLETE,               /**< transfer packet complete */
    NETDEV_EVENT_TX_COMPLETE_DATA_PENDING,  /**< transfer packet complete and data pending flag */
    NETDEV_EVENT_TX_NOACK,                  /**< ACK requested but not received */
    NETDEV_EVENT_TX_MEDIUM_BUSY,            /**< couldn't transfer packet */
    NETDEV_EVENT_LINK_UP,                   /**< link established */
    NETDEV_EVENT_LINK_DOWN,                 /**< link gone */
    NETDEV_EVENT_TX_TIMEOUT,                /**< timeout when sending */
    NETDEV_EVENT_RX_TIMEOUT,                /**< timeout when receiving */
    NETDEV_EVENT_CRC_ERROR,                 /**< wrong CRC */
    NETDEV_EVENT_FHSS_CHANGE_CHANNEL,       /**< channel changed */
    NETDEV_EVENT_CAD_DONE,                  /**< channel activity detection done */
    /* expand this list if needed */
} netdev_event_t;

/**
 * @brief   Received packet status information for most radios
 *
 * May be different for certain radios.
 */
struct netdev_radio_rx_info {
    uint8_t rssi;       /**< RSSI of a received packet */
    uint8_t lqi;        /**< LQI of a received packet */
};

/**
 * @brief   Forward declaration for netdev struct
 */
typedef struct netdev netdev_t;

/**
 * @brief   Event callback for signaling event to upper layers
 *
 * @param[in] type          type of the event
 */
typedef void (*netdev_event_cb_t)(netdev_t *dev, netdev_event_t event);

/**
 * @brief Structure to hold driver state
 *
 * Supposed to be extended by driver implementations.
 * The extended structure should contain all variable driver state.
 *
 * Contains a field @p context which is not used by the drivers, but supposed to
 * be used by upper layers to store reference information.
 */
struct netdev {
    const struct netdev_driver *driver;     /**< ptr to that driver's interface. */
    netdev_event_cb_t event_callback;       /**< callback for device events */
    void* context;                          /**< ptr to network stack context */
#ifdef MODULE_NETSTATS_L2
    netstats_t stats;                       /**< transceiver's statistics */
#endif
#ifdef MODULE_L2FILTER
    l2filter_t filter[L2FILTER_LISTSIZE];   /**< link layer address filters */
#endif
};

/**
 * @brief Structure to hold driver interface -> function mapping
 *
 * The send/receive functions expect/return a full ethernet
 * frame (dst mac, src mac, ethertype, payload, no checksum).
 */
typedef struct netdev_driver {
    /**
     * @brief Send frame
     *
     * @pre `(dev != NULL)`
     * @pre `(count == 0) || (vector != NULL)`
     *      (`(count != 0) => (vector != NULL)`)
     *
     * @param[in] dev       network device descriptor
     * @param[in] vector    io vector array to send
     * @param[in] count     nr of entries in vector
     *
     * @return number of bytes sent, or `< 0` on error
     */
    int (*send)(netdev_t *dev, const struct iovec *vector, unsigned count);

    /**
     * @brief Get a received frame
     *
     * @pre `(dev != NULL)`
     * @pre `(buf != NULL) && (len > 0)`
     *
     * Supposed to be called from
     * @ref netdev_t::event_callback "netdev->event_callback()"
     *
     * If buf == NULL and len == 0, returns the packet size without dropping it.
     * If buf == NULL and len > 0, drops the packet and returns the packet size.
     *
     * @param[in]   dev     network device descriptor
     * @param[out]  buf     buffer to write into or NULL
     * @param[in]   len     maximum number of bytes to read
     * @param[out] info     status information for the received packet. Might
     *                      be of different type for different netdev devices.
     *                      May be NULL if not needed or applicable.
     *
     * @return `< 0` on error
     * @return number of bytes read if buf != NULL
     * @return packet size if buf == NULL
     */
    int (*recv)(netdev_t *dev, void *buf, size_t len, void *info);

    /**
     * @brief the driver's initialization function
     *
     * @pre `(dev != NULL)`
     *
     * @return `< 0` on error, 0 on success
     */
    int (*init)(netdev_t *dev);

    /**
     * @brief a driver's user-space ISR handler
     *
     * @pre `(dev != NULL)`
     *
     * This function will be called from a network stack's loop when being
     * notified by netdev_isr.
     *
     * It is supposed to call
     * @ref netdev_t::event_callback "netdev->event_callback()" for each
     * occurring event.
     *
     * See receive packet flow description for details.
     *
     * @param[in]   dev     network device descriptor
     */
    void (*isr)(netdev_t *dev);

    /**
     * @brief   Get an option value from a given network device
     *
     * @pre `(dev != NULL)`
     *
     * @param[in]   dev     network device descriptor
     * @param[in]   opt     option type
     * @param[out]  value   pointer to store the option's value in
     * @param[in]   max_len maximal amount of byte that fit into @p value
     *
     * @return              number of bytes written to @p value
     * @return              `< 0` on error, 0 on success
     */
    int (*get)(netdev_t *dev, netopt_t opt,
               void *value, size_t max_len);

    /**
     * @brief   Set an option value for a given network device
     *
     * @pre `(dev != NULL)`
     *
     * @param[in] dev       network device descriptor
     * @param[in] opt       option type
     * @param[in] value     value to set
     * @param[in] value_len the length of @p value
     *
     * @return              number of bytes used from @p value
     * @return              `< 0` on error, 0 on success
     */
    int (*set)(netdev_t *dev, netopt_t opt,
               const void *value, size_t value_len);
} netdev_driver_t;

#ifdef __cplusplus
}
#endif

#endif /* NET_NETDEV_H */
/** @} */