ep.h

Go to the documentation of this file.

#ifndef EVE_NET_EP_H_INCLUDED
#define EVE_NET_EP_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 USB endpoint primitive.
 *
 * The endpoint queues and handles messages (URBs) to be send or received over USB interface.
 *
 * @author DT, Jetro AS
 */ /******************************************************************/

#include <lib/dlist.h>

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

/* forward */ struct urb_t;
/* forward */ struct ep_t;

/** Endpoint transfer status */
typedef enum
{
  EP_XFER_STATUS_OK = 0,        /**< No errors detected. */
  EP_XFER_STATUS_ABORTED,       /**< Transfer was aborted. */
  EP_XFER_STATUS_ERROR,         /**< Transfer error. */
} ep_xfer_status_t;

/**
 * EFM32-compatible callback type.
 * \param status    The transfer status.
 * \param xferred   Number of bytes actually transferred.
 * \param remaining Number of bytes remaining.
 */
typedef ep_xfer_status_t (*ep_if_xfer_cb_t)(ep_xfer_status_t status, uint32_t xferred, uint32_t remaining);

/**
 * Common prototype for generic URB send and URB receive functions
 * \param ep The endpoint
 * \param urb The URB to be send or received
 */
typedef void (*ep_xfer_cb_t)(struct ep_t *ep, struct urb_t *urb);

/**
 * Common prototype for generic URB complete calback
 * \param ep The endpoint
 * \param urb The URB that was just sent or received
 * \param status Status code for the transfer
 */
typedef void (*ep_complete_cb_t)(struct ep_t *ep, struct urb_t *urb, ep_xfer_status_t status);

/**
 * USB complete callback for the EFM32 USB framework.
 * The callback must call \ref ep_xfer_done for the endpoint like below:
 *
 * \code
static int rx_done_trap(ep_xfer_status_t status,
    uint32_t xferred,
    uint32_t remaining)
{
  return ep_xfer_done(status, xferred, remaining, &theEndpoint);
}
 * \endcode
 */
typedef ep_if_xfer_cb_t ep_done_trap_t;

/**
 * USB request block (URB), an atomical message sent or received over USB.
 */
struct urb_t
{
  struct dlist_t      link;         /**< List entry, link to other URBs in the endpoint queue */
  uint8_t            *buf;          /**< Pointer to the buffer with actual data */
  int                 size;         /**< Size of the buffer or actual size of the data in the buffer */
};

/**
 * Endpoint defenition structure, constant part.
 * The structure is supposed to be instantiated in flash memory.
 */
struct ep_c_t {
  ep_xfer_cb_t        xfer;         /**< Data transfer callback used by the endpoint */
  ep_complete_cb_t    complete;     /**< Complete callback, will be called when transfer is done */
  ep_done_trap_t      done_trap;    /**< Internal complete callback, called by the EFM32 USB framework */
  int                 size;         /**< Max size in bytes of a single URB buffer in the endpoint */
};

/**
 * Endpoint defenition structure, variable part.
 * The structure is supposed to be instantiated in RAM memory.
 */
struct ep_t {
  struct dlist_t      pool;         /**< Pool (list) of empty URBs in the endpoint */
  struct dlist_t      head;         /**< URB queue */
  const struct ep_c_t *c;           /**< Pointer to the constant part of the defenition */
};

/**
 * A (typically constant) structure used for endpoint (\ref ep_t structure) initialization.
 */
struct ep_init_t {
  struct ep_t        *ep;           /**< The endpoint */
  const struct ep_c_t *c;           /**< Constant part of the endpoint definition */
  struct urb_t       *urb;          /**< Pointer to an array of URB structures for the endpoint */
  int                 urb_count;    /**< Number of URBs in the urb array */
  uint8_t            *buf;          /**< Pointer to the memory are used as URB buffer space */
  int                 buf_stride;   /**< Difference in bytes between two consequtive addresses of
                                         two buffers in the buffer space */
};

/**
 * Initialize an endpoint, allocate URBs and buffers
 * \param ep The endpoint initialization description structure
 */
void ep_init(const struct ep_init_t *ep);


/**
 * Entry point for transfer done notifications
 * See \ref ep_done_trap_t for details how the function should be called.
 * \param status Transfer status
 * \param xferred Number of bytes transferred
 * \param remaining Number of bytes remaining
 * \param ep The endpoint the function is called for
 */
int ep_xfer_done(ep_xfer_status_t status,
    uint32_t xferred,
    uint32_t remaining,
    struct ep_t *ep);

/**
 * Instantiation of ef ep_xfer_cb_t for receive endpoints
 * \param ep The endpoint
 * \param urb The URB to be received
 */
void ep_xfer_in(struct ep_t *ep, struct urb_t *urb);

/**
 * Instantiation of ef ep_xfer_cb_t for transmit endpoints
 * \param ep The endpoint
 * \param urb The URB to be send
 */
void ep_xfer_out(struct ep_t *ep, struct urb_t *urb);

/**
 * Cancel any ongoing transfer.
 * The function internally called complete callback for the
 * cancelled URBs.
 * \param ep The endpoint
 * \param device Device instance
 */
void ep_kill_all_urbs(struct ep_t *ep, void *device);

/**
 * Allocate a URB from the endpoint
 * \param ep The endpoint
 */
static inline struct urb_t *ep_alloc_urb(struct ep_t *ep)
{
  struct dlist_t *link = ep->pool.next;
  if (dlist_is_empty(link)) {
    link = NULL;
  } else {
    dlist_del(link);
    ((struct urb_t *) link)->size = ep->c->size;
  }
  return (struct urb_t *) link;
}

/**
 * Free a URB
 * \param ep The endpoint
 * \param urb The URB
 */
static inline void ep_free_urb(struct ep_t *ep, struct urb_t *urb)
{
  dlist_append(&ep->pool, &urb->link);
}

/**
 * Check if no more URBs can be allocated from the endpoint
 * \param ep The endpoint
 * \return false if the endpoint is not empty
 * \return true if the endpoint is empty
 */
static inline bool ep_is_empty(struct ep_t *ep)
{
  return dlist_is_empty(&ep->pool);
}

/**
 * Schedule the URB for receiving or transmitting
 * \param ep The endpoint
 * \param urb The URB
 */
static inline void ep_schedule_urb(struct ep_t *ep, struct urb_t *urb)
{
  dlist_append(&ep->head, &urb->link);
  if (urb->link.next == urb->link.prev)
    ep->c->xfer(ep, urb);
}

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

#endif /* EVE_NET_EP_H_INCLUDED */