usbnet.h

Go to the documentation of this file.

#ifndef EVE_NET_USBNET_H_INCLUDED
#define EVE_NET_USBNET_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2014-2016, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Common USB network layer, used by virtually all supported network USB protocols

 * @author DT, Jetro AS
 */ /******************************************************************/

#include <lib/dlist.h>
#include <net/uip.h>
#include <net/common/ep.h>

/**
 * \addtogroup net_common
 * \{
 */

/*** Typedef's and defines. ***/
#define USBNET_ETH_FRAME_LEN        (UIP_BUFSIZE + 58 - UIP_LLH_LEN) /**< Size of ethernet frame buffer */
#define USBNET_RX_BUF_SIZE          USBNET_ETH_FRAME_LEN /**< Packet size when receiving on USB         */
#define USBNET_TX_BUF_SIZE          USBNET_ETH_FRAME_LEN /**< Packet size when transmitting on USB      */

/** Ethernet frames with size <= USBNET_TX_TINY_BUF_SIZE bytes are sent over a dedicated tiny pool      */
#define USBNET_TX_TINY_BUF_SIZE     (248)
#define USBNET_RX_POOL_SIZE         (1)   /**< Number of frames in the RX pool                          */
#define USBNET_TX_POOL_SIZE         (1)   /**< Number of frames on full-size TX pool                    */
#define USBNET_TX_TINY_POOL_SIZE    (2)   /**< Number of frames in the tiny TX pool                     */
#define USBNET_MANAGED_TX_POOL_SIZE (2)   /**< Number of frames in the managed (TCP data) TX pool       */

enum
{
  /**
   * The event is sent to usbnet process when a new frame is received.
   * Event data points to an URB structure, containing the data received.
   */
  USBNET_PROCESS_EVENT_RXED,
#if 0
  /**
   * Obsolete. Replaced by PROCESS_EVENT_NET_FLOW_ON
   * The event is sent to usbnet process when a new buffer becomes available
   * in the managed pool and UIP code can continue data sending
   */
  USBNET_PROCESS_EVENT_TX_FLOW_ON,
#endif
  /**
   * The constant is used to count number of common events related to usbnet.
   */
  USBNET_PROCESS_EVENT__LAST,
};

/**
 * USB RX buffer.
 *
 * Here urb->buf points to the .data field of the structure.
 */
struct usbnet_rx_buf_t
{
  struct process *device;                 /**< Pointer to the network device                      */
  uint8_t data[USBNET_RX_BUF_SIZE];       /**< The actual data buffer                             */
} __attribute__ ((aligned(4)));

/**
 * USB TX buffer (general and managed pools).
 *
 * The TX buffers are more complicated than RX buffers, because they are used also 
 * to accelerate TCP retransmissions. When an URB with TCP payload is transmitted,
 * usbnet does not free it automatically, but rather puts it to a retransmission list
 * of the socket, so-called "backlog". Responsibility to free (or retransmit) the URB
 * lays on UIP code in this case.
 * Like in \ref usbnet_rx_buf_t, urb->buf points to the .data field of the structure.
 */
struct usbnet_tx_buf_t
{
  struct dlist_t *backlog;                /**< The backlog the buffer belongs to                  */
  uint32_t seq;                           /**< Internally used for indexing in UIP                */
  struct process *device;                 /**< Pointer to the network device                      */
  uint8_t data[USBNET_TX_BUF_SIZE];       /**< The actual data buffer                             */
} __attribute__ ((aligned(4)));

/**
 * USB TX buffer (tiny pool).
 *
 * The major difference between this structure and \ref usbnet_tx_buf_t is the size
 * of the .data field. Tiny pool is used more to control traffic (like TCP ACKs) and
 * small UDP messages.
 */
struct usbnet_tx_tiny_buf_t
{
  struct dlist_t *backlog;                /**< The backlog always points to usbnetTxTinyEp        */
  uint32_t seq;                           /**< Not used for usbnet_tx_tiny_buf_t                  */
  struct process *device;                 /**< Pointer to the network device                      */
  uint8_t data[USBNET_TX_TINY_BUF_SIZE];  /**< The actual data buffer                              */
} __attribute__ ((aligned(4)));


/**
 * All the usbnet buffer space together
 */
struct net_buffers_t {
  struct usbnet_rx_buf_t     rx[USBNET_RX_POOL_SIZE];               /**< RX buffer space          */
  struct usbnet_tx_buf_t     tx[USBNET_TX_POOL_SIZE];               /**< TX buffer space          */
  struct usbnet_tx_tiny_buf_t tiny[USBNET_TX_TINY_POOL_SIZE];       /**< TX tiny buffer space     */
  struct usbnet_tx_buf_t     managed[USBNET_MANAGED_TX_POOL_SIZE];  /**< TX managed buffer space  */
};

/**
 * USBNET statistics
 */
struct usbnet_stat_h {
  uint32_t txed;
  uint32_t rxed;
};

/** Usbnet statistics */
extern struct usbnet_stat_h usbnetStat;

/**
 * Initialize the usbnet core.
 */
void usbnet_init();

/**
 * Start the interface; begin listening.
 * \param module Usbnet client module
 * \param rx_backlog_len Amount of buffers in the RX backlog
 */
void usbnet_start(struct process *module, uint8_t rx_backlog_len);

/**
 * Stop the interface; kill all URBs
 * \param module Usbnet client module
 */
void usbnet_stop(struct process *module);

/**
 * Allocate an URB for transmitting.
 *
 * The URB is allocated from the appropriate pool, depending on requested size
 * and backlog.
 *
 * \param module Usbnet client module
 * \param size Actual size of data to send
 * \param backlog The backlog the URB will belong to, or NULL for unmanaged allocation
 */
struct urb_t *usbnet_alloc_urb(struct process *module, uint32_t size, struct dlist_t *backlog);

/**
 * Schedule the URB for transmission
 *
 * \param urb The URB to be sent over the interface
 */
void usbnet_schedule_tx(struct urb_t *urb);

/**
 * Schedule the URB for reception
 *
 * \param urb The URB to be received
 */
void usbnet_schedule_rx(struct urb_t *urb);

/**
 * Check if there is at least one URB available in the managed pool
 *
 * Note that it the function returns false, the usbnet core will send
 * USBNET_PROCESS_EVENT_TX_FLOW_ON signal to the usbnet_process when a
 * new fresh URB appears in the managed pool.
 *
 * \return true if at least one URB is available
 * \return false if no URB is available
 */
bool usbnet_quote(void);

/**
 * Convert an URB structure to the usbnet_tx_buf_t it actually points to
 *
 * \param urb The urb
 * \return Pointer to usbnet_tx_buf_t structure
 */
static inline struct usbnet_tx_buf_t *usbnet_tx_buf(struct urb_t *urb)
{
  return (struct usbnet_tx_buf_t *)&urb->buf[-offsetof(struct usbnet_tx_buf_t, data)];
}

/**
 * Convert an URB structure to the usbnet_rx_buf_t it actually points to
 *
 * \param urb The urb
 * \return Pointer to usbnet_rx_buf_t structure
 */
static inline struct usbnet_rx_buf_t *usbnet_rx_buf(struct urb_t *urb)
{
  return (struct usbnet_rx_buf_t *)&urb->buf[-offsetof(struct usbnet_rx_buf_t, data)];
}

/** @} */ /* net_common */

#endif /* EVE_NET_USBNET_H_INCLUDED */