Subversion Repositories openrisc

//==========================================================================

//

//      usbs_sa11x0.c

//

//      Device driver for the SA11x0 USB port.

//

//==========================================================================

//####ECOSGPLCOPYRIGHTBEGIN####

// -------------------------------------------

// This file is part of eCos, the Embedded Configurable Operating System.

// Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.

//

// eCos is free software; you can redistribute it and/or modify it under

// the terms of the GNU General Public License as published by the Free

// Software Foundation; either version 2 or (at your option) any later version.

//

// eCos is distributed in the hope that it will be useful, but WITHOUT ANY

// WARRANTY; without even the implied warranty of MERCHANTABILITY or

// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

// for more details.

//

// You should have received a copy of the GNU General Public License along

// with eCos; if not, write to the Free Software Foundation, Inc.,

// 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

//

// As a special exception, if other files instantiate templates or use macros

// or inline functions from this file, or you compile this file and link it

// with other works to produce a work based on this file, this file does not

// by itself cause the resulting work to be covered by the GNU General Public

// License. However the source code for this file must still be made available

// in accordance with section (3) of the GNU General Public License.

//

// This exception does not invalidate any other reasons why a work based on

// this file might be covered by the GNU General Public License.

//

// Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.

// at http://sources.redhat.com/ecos/ecos-license/

// -------------------------------------------

//####ECOSGPLCOPYRIGHTEND####

//==========================================================================

//#####DESCRIPTIONBEGIN####

//

// Author(s):    bartv

// Contributors: bartv

// Date:         2000-10-04

//

// This code implements support for the on-chip USB port on the SA11x0

// family of processors. The code has been developed on the SA1110 and

// may or may not work on other members of the SA11x0 family. There

// have problems with the USB support on certain revisions of the silicon,

// so the errata sheet appropriate to the specific processor being used

// should be consulted. There also appear to be problems which do not

// appear on any errata, which this code attempts to work around.

//

//####DESCRIPTIONEND####

//==========================================================================

#include <cyg/infra/cyg_type.h>

#include <cyg/infra/cyg_ass.h>

#include <cyg/infra/cyg_trac.h>

#include <cyg/infra/diag.h>

#include <pkgconf/hal_arm.h>

#include <pkgconf/devs_usb_sa11x0.h>

#include <cyg/hal/drv_api.h>

#include <cyg/hal/hal_arch.h>

#include <cyg/hal/hal_io.h>

#include <cyg/hal/hal_cache.h>

#include <cyg/hal/hal_sa11x0.h>

#include <cyg/error/codes.h>

#include <cyg/io/usb/usb.h>

#include <cyg/io/usb/usbs.h>

// Debugging support. By default this driver operates mostly at

// DSR level, with the ISR doing a minimal amount of processing.

// However is also possible to run most of the code at thread-level,

// This is subject to some restrictions because the USB standard

// imposes timing constraints, e.g. some control operations such

// as SET-ADDRESS have to complete within 50ms. However it is

// very useful for debugging, specifically it allows you to put

// printf()'s in various places.

//

// Right now these configuration options are not exported to the

// user because running at DSR level is likely to be good enough

// for everybody not actively debugging this code. The options

// could be exported if necessary.

//#define CYGPKG_DEVS_USB_SA11X0_THREAD

#undef CYGPKG_DEVS_USB_SA11X0_THREAD

#ifdef CYGPKG_DEVS_USB_SA11X0_THREAD

  // Default stack size should be CYGNUM_HAL_STACK_SIZE_TYPICAL

# define CYGNUM_DEVS_USB_SA11X0_THREAD_STACK_SIZE       4096

# define CYGNUM_DEVS_USB_SA11X0_THREAD_PRIORITY         7

# include <cyg/kernel/kapi.h>

#endif

#if 0

# define DBG(a) diag_printf a

#else

# define DBG(a)

#endif

#undef FAILURES

#ifdef FAILURES

static volatile int ep1_failure = 7;

#endif

#undef STATS

#ifdef STATS

int ep1_receives = 0;

int ep1_errors = 0;

int ep2_transmits = 0;

int ep2_errors = 0;

# define INCR_STAT(a) (a) += 1

# define SET_STAT(a, b) (a) = (b)

#else

# define INCR_STAT(a)

# define SET_STAT(a, b)

#endif

// ----------------------------------------------------------------------------

// Serial port 0 on the SA11x0 provides a USB slave connection (aka a

// USB device controller or UDC). The functionality is somewhat

// limited, there are just three endpoints.

//

// Endpoint 0 can only be used for control messages. It has an 8 byte

// fifo which cannot be connected to a DMA engine. Hence incoming

// control packets have to be limited to 8 bytes by the enumeration

// data. The endpoint has to be managed at a low-level, i.e. the

// incoming request has to be extracted from the fifo, processed, and

// any response put back into the fifo within the permitted USB

// response times.

//

// Endpoint 1 can only be used for host->slave bulk OUT transfers. It

// has a 20 byte receive fifo, and it can be hooked up to any of the

// six DMA engines. Since bulk transfers will typically involve 64

// byte packets, most applications will require the use of DMA.

//

// Endpoint 2 can only be used for slave-host bulk IN transfers. There

// is a 16 byte transmit fifo so small messages can be transferred in

// software. The fifo can also be hooked up to DMA, which is a more

// likely scenario.

//

// Start with definitions of the hardware. The use of a structure and

// a const base pointer should allow the compiler to do base/offset

// addressing and keep the hardware base address in a register. This

// is better than defining each hardware register via a separate

// address. Although the registers are only a byte wide, the peripheral

// bus only supports word accesses.

//

// The USBS_CONTROL etc. macros allow for an alternative way of

// accessing the hardware if a better approach is presented, without

// having to rewrite all the code. Macros that correspond to registers

// are actually addresses, making it easier in the code to distinguish

// them from bit values: the & and * operators will just cancel out.

typedef struct usbs_sa11x0_hardware {

    volatile int control;

    volatile int address;

    volatile int out_size;

    volatile int in_size;

    volatile int ep0_control;

    volatile int ep1_control;

    volatile int ep2_control;

    volatile int ep0_data;

    volatile int ep0_write_count;

             int dummy1;

    volatile int fifo;

             int dummy2;

    volatile int status;

} usbs_sa11x0_hardware;

static usbs_sa11x0_hardware* const usbs_sa11x0_base = (usbs_sa11x0_hardware* const) 0x80000000;

#define USBS_CONTROL    (&(usbs_sa11x0_base->control))

#define USBS_ADDRESS    (&(usbs_sa11x0_base->address))

#define USBS_OUT_SIZE   (&(usbs_sa11x0_base->out_size))

#define USBS_IN_SIZE    (&(usbs_sa11x0_base->in_size))

#define EP0_CONTROL     (&(usbs_sa11x0_base->ep0_control))

#define EP1_CONTROL     (&(usbs_sa11x0_base->ep1_control))

#define EP2_CONTROL     (&(usbs_sa11x0_base->ep2_control))

#define EP0_DATA        (&(usbs_sa11x0_base->ep0_data))

#define EP0_WRITE_COUNT (&(usbs_sa11x0_base->ep0_write_count))

#define EP1_DATA        (&(usbs_sa11x0_base->fifo))

#define EP2_DATA        (&(usbs_sa11x0_base->fifo))

#define USBS_STATUS     (&(usbs_sa11x0_base->status))

#define CONTROL_DISABLE                 (1 << 0)

#define CONTROL_ACTIVE                  (1 << 1)

// The meaning of bit 2 changed, see errata

#define CONTROL_RESUME_INTR             (1 << 2)

#define CONTROL_EP0_INTR                (1 << 3)

#define CONTROL_EP1_INTR                (1 << 4)

#define CONTROL_EP2_INTR                (1 << 5)

// The meaning of bit 6 also changed, see errata

#define CONTROL_SUSPEND_INTR            (1 << 6)

#define CONTROL_RESET_INTR              (1 << 7)

// Getting the control register settings right is a little bit tricky.

// Bit 0 is the disable bit so touching that is dangerous, and the

// other bits have inverted meanings i.e. 0 enables interrupts. The

// following macro encapsulates this.

#define CONTROL_ALL_INTR                0x00FC

#define CONTROL_INTR_ENABLE(bits)  ((~(bits)) & CONTROL_ALL_INTR)

#define CONTROL_INTR_CLEAR(bits)   ((bits) & CONTROL_ALL_INTR)

// All the endpoint interrupt numbers can be handled en masse,

// but some of the endpoints may be disabled.

#if defined(CYGPKG_DEVS_USB_SA11X0_EP1) && defined(CYGPKG_DEVS_USB_SA11X0_EP2)

# define CONTROL_EP_INTR_BITS      (CONTROL_EP0_INTR | CONTROL_EP1_INTR | CONTROL_EP2_INTR)

#elif defined(CYGPKG_DEVS_USB_SA11X0_EP1)

# define CONTROL_EP_INTR_BITS      (CONTROL_EP0_INTR | CONTROL_EP1_INTR)

#elif defined(CYGPKG_DEVS_USB_SA11X0_EP2)

# define CONTROL_EP_INTR_BITS      (CONTROL_EP0_INTR | CONTROL_EP2_INTR)

#else

# define CONTROL_EP_INTR_BITS      (CONTROL_EP0_INTR)

#endif

#define EP0_OUT_READY                   (1 << 0)

#define EP0_IN_READY                    (1 << 1)

#define EP0_SENT_STALL                  (1 << 2)

#define EP0_FORCE_STALL                 (1 << 3)

#define EP0_DATA_END                    (1 << 4)

#define EP0_SETUP_END                   (1 << 5)

#define EP0_SERVICED_OPR                (1 << 6)

#define EP0_SERVICED_SETUP_END          (1 << 7)

#define EP1_FIFO_SERVICE                (1 << 0)

#define EP1_PACKET_COMPLETE             (1 << 1)

#define EP1_PACKET_ERROR                (1 << 2)

#define EP1_SENT_STALL                  (1 << 3)

#define EP1_FORCE_STALL                 (1 << 4)

#define EP1_FIFO_NOT_EMPTY              (1 << 5)

#define EP2_FIFO_SERVICE                (1 << 0)

#define EP2_PACKET_COMPLETE             (1 << 1)

#define EP2_PACKET_ERROR                (1 << 2)

#define EP2_PACKET_UNDERRUN             (1 << 3)

#define EP2_SENT_STALL                  (1 << 4)

#define EP2_FORCE_STALL                 (1 << 5)

#define STATUS_EP0_INTR                 (1 << 0)

#define STATUS_EP1_INTR                 (1 << 1)

#define STATUS_EP2_INTR                 (1 << 2)

#define STATUS_SUSPEND_INTR             (1 << 3)

#define STATUS_RESUME_INTR              (1 << 4)

#define STATUS_RESET_INTR               (1 << 5)

#define EP0_FIFO_SIZE                     8

#define EP0_MTU                           8

#define EP1_FIFO_SIZE                   20

#ifdef CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL

# define EP1_MTU                        64

#else

# define EP1_MTU                        16

#endif

#define EP2_FIFO_SIZE                   16

#ifdef CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL

# define EP2_MTU                        64

#else

# define EP2_MTU                        16

#endif

#if defined(CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL) || defined(CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL)

typedef struct usbs_sa11x0_dma {

    volatile int                address;

    volatile int                control_set;

    volatile int                control_clear;

    volatile int                status;

    volatile int                buf_a_address;  // Absolute, not remapped

    volatile int                buf_a_size;

    volatile int                buf_b_address;  // Absolute, not remapped

    volatile int                buf_b_size;

} usbs_sa11x0_dma;

#define DMA_CONTROL_RUN                 (1 << 0)

#define DMA_CONTROL_INTR_ENABLE         (1 << 1)

#define DMA_STATUS_ERROR                (1 << 2)

#define DMA_STATUS_DONE_A               (1 << 3)

#define DMA_CONTROL_START_A             (1 << 4)

#define DMA_STATUS_DONE_B               (1 << 5)

#define DMA_CONTROL_START_B             (1 << 6)

#define DMA_STATUS_BUFFER_IN_USE        (1 << 7)

// All the bits that are useful to clear. BUFFER_IN_USE is read-only.

#define DMA_CONTROL_CLEAR_ALL           (DMA_CONTROL_RUN | DMA_CONTROL_INTR_ENABLE | DMA_STATUS_ERROR | \

                                         DMA_STATUS_DONE_A | DMA_CONTROL_START_A | DMA_STATUS_DONE_B | DMA_CONTROL_START_B)

// The DMA engines operate eight-bytes at a time. This affects issues

// such as alignment.

#define DMA_BURST_SIZE                  8

// The DMA engines bypass the cache and MMU, accessing physical

// memory directly. Newer HALS should provide appropriate macros.

#ifndef HAL_VIRT_TO_PHYS_ADDRESS

# error HAL macros for translating between virtual and physical memory are required.

#endif

// Make absolutely sure that the two endpoints use different

// DMA channels. Right now this check cannot be done easily

// at the CDL level.

# if defined(CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL) && defined(CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL)

#  if (CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL == CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL)

#   error Different DMA channels must be selected for the two endpoints.

#  endif

# endif

# ifdef CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL

static usbs_sa11x0_dma* const ep1_dma_base = (usbs_sa11x0_dma* const)(0xB0000000 | (0x20 * CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL));

#  define EP1_DMA_ADDRESS        (&(ep1_dma_base->address))

#  define EP1_DMA_CONTROL_SET    (&(ep1_dma_base->control_set))

#  define EP1_DMA_CONTROL_CLEAR  (&(ep1_dma_base->control_clear))

#  define EP1_DMA_STATUS         (&(ep1_dma_base->status))

#  define EP1_DMA_BUF_A_ADDRESS  (&(ep1_dma_base->buf_a_address))

#  define EP1_DMA_BUF_A_SIZE     (&(ep1_dma_base->buf_a_size))

#  define EP1_DMA_BUF_B_ADDRESS  (&(ep1_dma_base->buf_b_address))

#  define EP1_DMA_BUF_B_SIZE     (&(ep1_dma_base->buf_b_size))

// The correct value for the DMA address register is fixed for USB transfers

// See table 11.6 of the SA1110 Advanced Developer's Manual

//   Device datum width == 1 byte

//   Device burst size  == 8 bytes

//   Device transfer direction == read (device->memory)

//   Endianness is controlled by the ARM architectural HAL package

#  ifdef CYGHWR_HAL_ARM_BIGENDIAN

#   define EP1_DMA_ADDRESS_VALUE        (0x80000A00 | 0x10 | 0x0 | 0x4 | 0x2 | 0x1)

#  else

#   define EP1_DMA_ADDRESS_VALUE        (0x80000A00 | 0x10 | 0x0 | 0x4 | 0x0 | 0x1)

#  endif

# endif // EP1_DMA

# ifdef CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL

static usbs_sa11x0_dma* const ep2_dma_base = (usbs_sa11x0_dma* const)(0xB0000000 | (0x20 * CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL));

#  define EP2_DMA_ADDRESS        (&(ep2_dma_base->address))

#  define EP2_DMA_CONTROL_SET    (&(ep2_dma_base->control_set))

#  define EP2_DMA_CONTROL_CLEAR  (&(ep2_dma_base->control_clear))

#  define EP2_DMA_STATUS         (&(ep2_dma_base->status))

#  define EP2_DMA_BUF_A_ADDRESS  (&(ep2_dma_base->buf_a_address))

#  define EP2_DMA_BUF_A_SIZE     (&(ep2_dma_base->buf_a_size))

#  define EP2_DMA_BUF_B_ADDRESS  (&(ep2_dma_base->buf_b_address))

#  define EP2_DMA_BUF_B_SIZE     (&(ep2_dma_base->buf_b_size))

#  ifdef CYGHWR_HAL_ARM_BIGENDIAN

#   define EP2_DMA_ADDRESS_VALUE        (0x80000A00 | 0x00 | 0x0 | 0x4 | 0x2 | 0x0)

#  else

#   define EP2_DMA_ADDRESS_VALUE        (0x80000A00 | 0x00 | 0x0 | 0x4 | 0x0 | 0x0)

#  endif

# endif // EP2_DMA

#endif  // EP1_DMA || EP2_DMA

// ----------------------------------------------------------------------------

// Static data. There is a data structure for each endpoint. The

// implementation is essentially a private class that inherits from

// common classes for control and data endpoints, but device drivers

// are supposed to be written in C so some ugliness is required.

//

// Devtab entries are defined in usbs_sa11x0_data.cxx to make sure

// that the linker does not garbage-collect them.

// Support for the interrupt handling code.

static cyg_interrupt usbs_sa11x0_intr_data;

static cyg_handle_t  usbs_sa11x0_intr_handle;

static volatile int  isr_status_bits    = 0;

// Endpoint 0 is always present, this module would not get compiled

// otherwise.

static void usbs_sa11x0_ep0_start(usbs_control_endpoint*);

static void usbs_sa11x0_poll(usbs_control_endpoint*);

typedef enum ep0_state {

    EP0_STATE_IDLE      = 0,

    EP0_STATE_IN        = 1,

    EP0_STATE_OUT       = 2

} ep0_state;

typedef struct ep0_impl {

    usbs_control_endpoint   common;

    ep0_state               ep_state;

    int                     length;

    int                     transmitted;

} ep0_impl;

static ep0_impl ep0 = {

    common:

    {

        state:                  USBS_STATE_POWERED, // The hardware does not distinguish  between detached, attached and powered.

        enumeration_data:       (usbs_enumeration_data*) 0,

        start_fn:               &usbs_sa11x0_ep0_start,

        poll_fn:                &usbs_sa11x0_poll,

        interrupt_vector:       SA11X0_IRQ_USB_SERVICE_REQUEST,

        control_buffer:         { 0, 0, 0, 0, 0, 0, 0, 0 },

        state_change_fn:        (void (*)(usbs_control_endpoint*, void*, usbs_state_change, int)) 0,

        state_change_data:      (void*) 0,

        standard_control_fn:    (usbs_control_return (*)(usbs_control_endpoint*, void*)) 0,

        standard_control_data:  (void*) 0,

        class_control_fn:       (usbs_control_return (*)(usbs_control_endpoint*, void*)) 0,

        class_control_data:     (void*) 0,

        vendor_control_fn:      (usbs_control_return (*)(usbs_control_endpoint*, void*)) 0,

        vendor_control_data:    (void*) 0,

        reserved_control_fn:    (usbs_control_return (*)(usbs_control_endpoint*, void*)) 0,

        reserved_control_data:  (void*) 0,

        buffer:                 (unsigned char*) 0,

        buffer_size:            0,

        fill_buffer_fn:         (void (*)(usbs_control_endpoint*)) 0,

        fill_data:              (void*) 0,

        fill_index:             0,

        complete_fn:            (usbs_control_return (*)(usbs_control_endpoint*, int)) 0

    },

    ep_state:           EP0_STATE_IDLE,

    length:             0,

    transmitted:        0

};

extern usbs_control_endpoint usbs_sa11x0_ep0 __attribute__((alias ("ep0")));

// Endpoint 1 is optional. If the application only involves control

// messages or only slave->host transfers then the endpoint 1

// support can be disabled.

#ifdef CYGPKG_DEVS_USB_SA11X0_EP1

typedef struct ep1_impl {

    usbs_rx_endpoint    common;

    int                 fetched;

    cyg_bool            using_buf_a;

} ep1_impl;

static void ep1_start_rx(usbs_rx_endpoint*);

static void ep1_set_halted(usbs_rx_endpoint*, cyg_bool);

static ep1_impl ep1 = {

    common: {

        start_rx_fn:        &ep1_start_rx,

        set_halted_fn:      &ep1_set_halted,

        complete_fn:        (void (*)(void*, int)) 0,

        complete_data:      (void*) 0,

        buffer:             (unsigned char*) 0,

        buffer_size:        0,

        halted:             0,

    },

    fetched:            0,

    using_buf_a:        0

};

extern usbs_rx_endpoint usbs_sa11x0_ep1 __attribute__((alias ("ep1")));

#endif

// Endpoint 2 is optional. If the application only involves control

// messages or only host->slave transfers then the endpoint 2 support

// can be disabled.

#ifdef CYGPKG_DEVS_USB_SA11X0_EP2

typedef struct ep2_impl {

    usbs_tx_endpoint        common;

    int                     transmitted;

    int                     pkt_size;

} ep2_impl;

static void ep2_start_tx(usbs_tx_endpoint*);

static void ep2_set_halted(usbs_tx_endpoint*, cyg_bool);

static ep2_impl ep2 = {

    common: {

        start_tx_fn:        &ep2_start_tx,

        set_halted_fn:      &ep2_set_halted,

        complete_fn:        (void (*)(void*, int)) 0,

        complete_data:      (void*) 0,

        buffer:             (const unsigned char*) 0,

        buffer_size:        0,

        halted:             0,

    },

    transmitted:        0,

    pkt_size:           0

};

extern usbs_tx_endpoint usbs_sa11x0_ep2 __attribute__ ((alias ("ep2")));

#endif

// ----------------------------------------------------------------------------

// Hardware problem: experiments indicate that manipulating the USB

// controller registers does not always work as expected. The control

// fifo is especially badly affected, with e.g. writes just being lost

// completely. It is necessary to work around these problems using

// retry loops. MAX_RETRIES controls the total number of attempts to

// access a register. MAX_CHECKS controls the number of times a

// register is checked to determine whether or not the attempt has

// been succesful. These constants are used to access the data fifo,

// so MAX_RETRIES has to be > 20 bytes.

#define MAX_RETRIES     32

#define MAX_CHECKS       8

// Write one or more bits to a register. This should result in some

// bits ending up set and other bits ending up clear. Some register

// bits are write-1-to-clear or may have side effects.

static cyg_bool

usbs_sa11x0_poke(volatile int* addr, int value, int should_be_set, int should_be_clear)

{

    cyg_bool    result  = false;

    int         retries, checks;

    for (retries = 0; !result && (retries < MAX_RETRIES); retries++) {

        *addr = value;

        (void) *addr;   // The first read is always invalid.

        for (checks = 0; !result && (checks < MAX_CHECKS); checks++) {

            int current_value = *addr;

            if (should_be_set != (should_be_set & current_value)) {

                continue;

            }

            if ((0 != should_be_clear) && (0 != (should_be_clear & current_value))) {

                continue;

            }

            result = true;

        }

    }

    if (!result) {

        DBG(("usbs_sa11x0_poke failed: addr %x, value %x, should_be_set %x, should_be_clear %x, actual %x\n", \

             (int) addr, value, should_be_set, should_be_clear, *addr));

    }

    return result;

}

// Write a whole value to a register, rather than just manipulating

// individual bits.

static cyg_bool

usbs_sa11x0_poke_value(volatile int* addr, int value)

{

    cyg_bool    result  = false;

    int         retries, checks;

    for (retries = 0; !result && (retries < MAX_RETRIES); retries++) {

        *addr = value;

        (void) *addr;   // The first read is always invalid.

        for (checks = 0; !result && (checks < MAX_CHECKS); checks++) {

            if (value == *addr) {

                result = true;

            }

        }

    }

    if (!result) {

        DBG(("usbs_sa11x0_poke_value failed: addr %x, value %x, actual %x\n", (int) addr, value, *addr));

    }

    return result;

}

// ----------------------------------------------------------------------------

// Control transfers

//

// Endpoint 0 is rather more complicated than the others. This is

// partly due to the nature of the control protocol, for example it is

// bidirectional and transfer sizes are unpredictable.

//

// The USB standard imposes some timing constraints on endpoint 0, see

// section 9.2.6 of the spec. For example the set-address operation is

// supposed to take at most 50ms. In general the timings are reasonably

// generous so no special action is taken here. There could be problems

// when debugging, but that is pretty much inevitable.

//

// It is necessary to maintain a state for the control endpoint, the

// default state being idle. Control operations involve roughly the

// following sequence of events:

//

// 1) the host transmits a special setup token, indicating the start

//    of a control operation and possibly cancelling any existing control

//    operation that may be in progress. USB peripherals cannot NAK this

//    even if they are busy.

//

// 2) the setup operation is followed by an eight-byte packet from the host

//    that describes the specific control operation. This fits into the

//    SA11X0's eight-byte control fifo. There will be an endpoint 0

//    interrupt with the out-packet-ready bit set. If the setup token

//    was sent while a previous control operation was also in progress

//    then the setup-end bit will be set as well.

//

// 3) the eight-byte packet is described in section 9.3 of the USB spec.

//    The first byte holds three fields, with the top bit indicating the

//    direction of subsequent data transfer. There are also two bytes

//    specifying the size of the subsequent transfer. Obviously the

//    packet also contains information such as the request type.

//

//    If the specified size is zero then the endpoint will remain in

//    its idle state. Otherwise the endpoint will switch to either

//    IN or OUT state, depending on the direction of subsequent

//    transfers.

// 

// 4) some standard control operations can be handled by the code

//    here. Set-address involves poking the address register and

//    a change of state. Set-feature and clear-feature on the

//    data endpoints can be used in conjunction with endpoint-halt.

//    Get-status on the data endpoints tests the halt condition.

//    It is also possible for the hardware-specific code to

//    implement set-feature, clear-feature and get-status

//    for the device as a whole since the SA11x0 always has to

//    be self-powered and is incapable of initiating a remote

//    wakeup.

//

//    Other standard control operations will be handled by the

//    application-specific installed handler, if any, or by the

//    default handler usbs_handle_standard_control(). Class-specific

//    and vendor-specific functions require appropriate handlers to be

//    installed as well, If a particular request is not recognized

//    then a stall condition should be raised. This will not prevent

//    subsequent control operations, just the current one.

//

//    Data transfers on endpoint 0 involve at most eight bytes at

//    a time. More data will only be accepted if the out-packet-ready

//    bit has been cleared via the serviced-opr bit, with the

//    hardware nak'ing OUT requests. To send data back to the host

//    the FIFO should be filled and then the in-packet-ready bit

//    should be set.

//

// It looks like processing all control packets at DSR level should be

// sufficient. During the data phase the hardware will NAK IN and

// OUT requests if the fifo is still empty/full, so timing is not

// an issue. Timing after receipt of the initial control message

// may be more important, e.g. the 50ms upper limit on processing

// the set-address control message, but this should still be ok.

// This decision may have to be re-examined in the light of

// experience.

// Init may get called during system startup or following a reset.

// During startup no work is needed since the hardware will

// have been reset and everything should be fine. After a reset

// the hardware will also be ok but there may be state information

// in ep0 that needs to be reset.

static void

usbs_sa11x0_ep0_init(void)

{

    if ((EP0_STATE_IDLE != ep0.ep_state) &&

        ((usbs_control_return (*)(usbs_control_endpoint*, int)) 0 != ep0.common.complete_fn)) {

        (*ep0.common.complete_fn)(&ep0.common, -EPIPE);

    }

    ep0.common.state            = USBS_STATE_POWERED;

    memset(ep0.common.control_buffer, 0, 8);

    ep0.common.buffer           = (unsigned char*) 0;

    ep0.common.buffer_size      = 0;

    ep0.common.fill_buffer_fn   = (void (*)(usbs_control_endpoint*)) 0;

    ep0.common.fill_data        = (void*) 0;

    ep0.common.fill_index       = 0;

    ep0.common.complete_fn      = (usbs_control_return (*)(usbs_control_endpoint*, int)) 0;

    ep0.ep_state                = EP0_STATE_IDLE;

    ep0.length                  = 0;

    ep0.transmitted             = 0;

}

// The start function is called by higher-level code when things have

// been set up, i.e. the enumeration data is available, appropriate

// handlers have been installed for the different types of control

// messages, and communication with the host is allowed to start. The

// next event that should happen is a reset operation from the host,

// so all other interrupts should be blocked. However it is likely

// that the hardware will detect a suspend state before the reset

// arrives, and hence the reset will act as a resume as well as a

// reset.

static void

usbs_sa11x0_ep0_start(usbs_control_endpoint* endpoint)

{

    CYG_ASSERT( endpoint == &ep0.common, "USB startup involves the wrong endpoint");

    // Activate the hardware. Write a 0 to the enable/disable bit 0.

    // Bit 1 is read-only. The other bits are set to 1 to disable

    // the corresponding interrupt source.

    usbs_sa11x0_poke(USBS_CONTROL, CONTROL_ALL_INTR, CONTROL_ALL_INTR, 0);

    // If there is additional platform-specific initialization to

    // perform, do it now. This macro can come from the platform HAL.

#ifdef SA11X0_USB_PLATFORM_INIT

    SA11X0_USB_PLATFORM_INIT;

#endif

    // Clear any pending interrupts. There should not be any, but just

    // in case. Note: passing 0x00FF as the should_be_clear argument

    // is a race condition, an external event can happen at any time,

    // so we may loop unnecessarily and lose an interrupt. However

    // the initial reset should last for 10ms.

    usbs_sa11x0_poke(USBS_STATUS, 0x00FF, 0x00, 0x00FF);

    // The only interrupt really of interest right now is reset, but

    // it is likely to be preceded by a resume. 

    usbs_sa11x0_poke(USBS_CONTROL,

                     CONTROL_INTR_ENABLE(CONTROL_RESET_INTR | CONTROL_RESUME_INTR),

                     0,

                     CONTROL_INTR_CLEAR(CONTROL_RESET_INTR | CONTROL_RESUME_INTR));

}

// Filling the fifo with a reply to the host. This can be called

// immediately at the end of a control message, to prepare for

// the next IN token. It will also get called after each subsequent

// IN operation when the fifo has been emptied.

//

// Experiments have indicated serious problems with the control fifo:

// some writes to the fifo just get lost completely. The failure rate

// is sufficiently high that more often than not the host will be

// unable to read all the enumeration data. However, the write-count

// register appears to give a valid indication of the current fifo

// contents. This means the code can retry stuffing a particular byte

// into the fifo until the write-count goes up.

static void

usbs_sa11x0_ep0_fill_fifo(void)

{

    cyg_bool ok     = true;

    int filled      = 0;

    int max;

    int fifo_count  = *EP0_WRITE_COUNT;

    int bits_to_set = 0;

    // The host can interrupt the current control message at any time

    // with a new one. In practice this is unlikely, things could get

    // rather confused on the host side. However if a control message

    // has been received then the fifo should obviously not be filled.

    // A new control message is indicated by the SETUP_END bit.

    //

    // The hardware design means that there is a race condition: the

    // new control message can come in at any time, even in the middle

    // of filling the fifo. Checking the SETUP_END more often would

    // reduce the probability of things getting messed up, but not

    // eliminate it.

    //

    // There is a check for SETUP_END at the start of the DSR, so

    // the setting of this bit should have resulted in another ISR

    // and another DSR being scheduled. Hence there is no need for

    // special action here.

    if (0 != (*EP0_CONTROL & EP0_SETUP_END)) {

        DBG(("EP0_fill_fifo(), interrupted by SETUP_END\n"));

        return;

    }