/* * Copyright (C) 2014 Martine Lenders * Copyright (C) 2015 Freie Universität Berlin * * 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_gnrc_netdev Network device driver interface * @ingroup net_gnrc * @deprecated Use @ref drivers_netdev_netdev2 "netdev2" instead for new * devices. This module only allows for interaction with * @ref net_gnrc "GNRC", while @ref drivers_netdev_netdev2 * "netdev2" is independent from the stack. * @brief Common network device interface * @{ * * @file * @brief Network device driver interface definition. * * @author Martine Lenders * @author Hauke Petersen */ #ifndef GNRC_NETDEV_H_ #define GNRC_NETDEV_H_ #include #include #include #include "net/gnrc/pkt.h" #include "net/netopt.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Type for @ref msg_t if device fired an event */ #define GNRC_NETDEV_MSG_TYPE_EVENT (0x0100) /** * @brief Possible event types that are send from the device driver to the * MAC layer */ typedef enum { NETDEV_EVENT_RX_STARTED = 0x0001, /**< started to receive a packet */ NETDEV_EVENT_RX_COMPLETE = 0x0002, /**< finished receiving a packet */ NETDEV_EVENT_TX_STARTED = 0x0004, /**< started to transfer a packet */ NETDEV_EVENT_TX_COMPLETE = 0x0008, /**< finished transferring packet */ NETDEV_EVENT_TX_NOACK = 0x0010, /**< ACK requested but not received */ NETDEV_EVENT_TX_MEDIUM_BUSY = 0x0020, /**< couldn't transfer packet */ /* expand this list if needed */ } gnrc_netdev_event_t; /** * @brief Event callback for signaling event to a MAC layer * * @param[in] type type of the event * @param[in] arg event argument, can e.g. contain a pktsnip_t pointer */ typedef void (*gnrc_netdev_event_cb_t)(gnrc_netdev_event_t type, void *arg); /** * @brief Forward declaration of gnrc_netdev_t due to cyclic dependency to * @ref gnrc_netdev_driver_t. * * @see gnrc_netdev */ typedef struct gnrc_netdev gnrc_netdev_t; /** * @brief Network device API definition. * * @details This is a set of functions that must be implemented by any driver * for a network device. */ typedef struct { /** * @brief Send data via a given network device * * @param[in] dev network device descriptor * @param[in] pkt pointer to the data in the packet buffer * * @return number of bytes that were actually send out * @return -ENODEV if @p dev is invalid * @return -ENOMSG if pkt is invalid * @return -EOVERFLOW if the payload size of @p pkt exceeds the * payload size that can be handled by the device */ int (*send_data)(gnrc_netdev_t *dev, gnrc_pktsnip_t *pkt); /** * @brief Registers an event callback to a given network device * * @param[in] dev network device descriptor * @param[in] cb function that is called on events * * @return 0 on success * @return -ENODEV if @p dev is invalid * @return -ENOBUFS if maximum number of callbacks is exceeded */ int (*add_event_callback)(gnrc_netdev_t *dev, gnrc_netdev_event_cb_t cb); /** * @brief Unregisters an event callback from a given network device * * @param[in] dev network device descriptor * @param[in] cb callback function * * @return 0 on success * @return -ENODEV if @p dev is invalid * @return -ENOENT if callback was not registered */ int (*rem_event_callback)(gnrc_netdev_t *dev, gnrc_netdev_event_cb_t cb); /** * @brief Get an option value from a given network device * * @note This function does not check for proper alignment of the memory * region accessed. It is the responsibility of the caller to * assure aligned memory access. * * @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 -ENODEV if @p dev is invalid * @return -ENOTSUP if @p opt is not supported * @return -EOVERFLOW if available space in @p value given in * @p max_len is too small to store the option value * @return -ECANCELED if internal driver error occurred */ int (*get)(gnrc_netdev_t *dev, netopt_t opt, void *value, size_t max_len); /** * @brief Set an option value for a given network device * * @note This function does not check for proper alignment of the memory * region accessed. It is the responsibility of the caller to * assure aligned memory access. * * @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 -ENODEV if @p dev is invalid * @return -ENOTSUP if @p opt is not supported * @return -EINVAL if @p value is invalid * @return -ECANCELED if internal driver error occurred */ int (*set)(gnrc_netdev_t *dev, netopt_t opt, void *value, size_t value_len); /** * @brief This function is called by a MAC layer when a message of type * @ref GNRC_NETDEV_MSG_TYPE_EVENT was received * * @param[in] dev network device descriptor * @param[in] event_type event type, given by msg_t::content::value * in the received message */ void (*isr_event)(gnrc_netdev_t *dev, uint32_t event_type); } gnrc_netdev_driver_t; /** * @brief The netdev data-structure holds the minimum information needed for * interaction with MAC layers and can be expanded with device * specific fields * * The netdev structure is the parent for all network device driver descriptors. * * @see gnrc_netdev_t */ struct gnrc_netdev { gnrc_netdev_driver_t const *driver; /**< pointer to the devices interface */ gnrc_netdev_event_cb_t event_cb; /**< netdev event callback */ kernel_pid_t mac_pid; /**< the driver's thread's PID */ }; #ifdef __cplusplus } #endif #endif /* GNRC_NETDEV_H_ */ /** @} */