/* usb/usb.h
 *
 * (c) 2002 Simtec Electronics
 *
 * Ben Dooks, T. Milius
 *
 * General usb header
 *
 * $Id: usb.h,v 1.31 2003/10/20 22:00:17 ben Exp $
 *
 * This Library file is part of the Simtec Electronics USB stack development
 *   suite.
 * Specific licence is granted to use this file by third parties for the
 *   development of USB device drivers.
 *
*/

#ifndef __USB_USB_H
#define __USB_USB_H "$Id: usb.h,v 1.31 2003/10/20 22:00:17 ben Exp $"

#include "usb/list.h"
#include "usb/semaphor.h"
#include "usb/sortmatr.h"

#ifdef IS_RISCOS
#include <stdio.h>
#endif

/* See usb_defs.h also */
#define USB_OFFSET_TAG_MASK        0xFF000000
#define USB_OFFSET_TAG_OFFSET_MASK 0x00FFFFFF

/* internal usage at endpoint only */
#define USB_TRANSACTION_DIRECTION_IN   0x00010000

/* ---------- pipe ---------- */
/* See usb_defs.h also */

/* Pipe states */
#define USB_PIPE_STATE_UNUSED   0x00000000
#define USB_PIPE_STATE_ACTIVE   0x00000001
#define USB_PIPE_STATE_HALTED   0x00000002

#define USB_PIPE_STATE_MASK     0x0000000F
/* Additional Information */
#define USB_PIPE_STATE_SHARED   0x00000010
#define USB_PIPE_STATE_NO_CAP   0x00000020
#define USB_PIPE_STATE_CAPACITY 0x00000040

/* ---------- usb device ---------- */
/* See usb_defs.h also */

/* Device speed */
#define USB_DEVICE_SPEED_MAX        0x01

/* ---------- various ---------- */
/* See usb_defs.h also */

#define USB_ALIAS_FILE "<USB$ChoicesDir>.alias"

/* constant indices for speed table */
#define USB_SPEED_CONSTANT       0
#define USB_SPEED_SIZE_DEPENDEND 1

/* ---------- Control Request ---------- */
/* See usb_defs.h also */

/* this is kept for compatibility */
struct usb_s_request_function_s {
  unsigned long function_code;
  unsigned long parameter_1;
};

typedef struct usb_s_request_function_s usb_ep_old_t;

/* flags for struct usb_endpoint_s ep_flags field
 *
 */

/** USB Endpoint - flag: usb_ep_info_t is valid */
#define USB_EPFLAG_INFOVALID       (0x01)


/* struct usb_ep_info_s (usb_ep_info_t)
 *
 * this structure MUST NOT become bigger than the structure it is
 * replacing (struct usb_s_request_function_s) as then backwards 
 * compatiblity will be lost. 
 *
 * any more fields should be included in the usb2_endpoint_s structure 
*/

struct usb_ep_info_s {
  unsigned short         wMaxPacketSize;    /* from ep descriptor */

  unsigned char          bmAttributes;      /* from ep descriptor */
  unsigned char          bInterval;         /* from ep descriptor */
};

typedef struct usb_ep_info_s usb_ep_info_t;

/* ---------- endpoint ---------- */
/* All communication from and to USB device is done using pipes. A pipe
   is allocated to an endpoint (or pair of endpoints). An endpoint is
   described by a long:

   Bit 0-29 No. of Endpoint
   Bit 30 - Bit 31 gives direction (0) or both (1)
   Bit 31 - Direction (set to zero if both directions)
            0 - OUT endpoint
            1 - In endpoint

*/

struct usb_endpoint_s {
  unsigned long       data_toggle;   /* updated by hcd when finished... */

  semaphor             *protection;
  struct usb_hc_s      *hostcontroller;
  struct usb_device_s  *device;
  unsigned long        device_number;
  unsigned long        speed;
  unsigned long        number;

  /* fields before here are fixed from release revision 1.15 (18Jun2002),
   * do not rely on the following fields staying fixed from here on */

  /* Transaction information */
  unsigned long        type;
  unsigned long        max_data_size;

  /* (06 Oct 03) 
   *
   * The next two fields have finally been recycled. Anyone using
   * these, is in need of an recompile of their clients, as these fields
   * have not been valid for an long time (pre RISC OS release 1.3)
   *
   * ->  unsigned long        transaction_information;
   * replaced with
   * ->  unsigned long        ep_flags;
   *
  */

  unsigned long        ep_flags;

  /* the values in the union are only valid if the relevant flag is set
   * in ep_flags (USB_EPFLAG_INFOVALID)
   */

  union {
    usb_ep_old_t       old;   /* not used, compatiblity */   
    usb_ep_info_t      info;  /* dependant on USB_EPFLAG_INFOVALID */
  } ep_info;

  unsigned long        frame_repeat;
  unsigned long        frame_last_transaction;

  /* Pipe information */
  unsigned long        pipe_state;
  unsigned long        pipe_usages;

  /* (17 Oct 03) 
   *
   * it is possible the next fields are going to be updated in the near
   * future... they are old, and in need of renovation. If your client
   * is using them, then it is imperative that Simtec is informed, as they
   * are actually not being used by the stack at the moment.
   *
   * the mechanism is probably going to be removed, as it serves no real
   * purpose with all the new host controllers.
  */

  void (*request_tracking)(struct usb_transaction_basic_s *act_transaction,
			   void *request_tracking_handle,
			   int transaction_result);
  void *request_tracking_handle;

};


#ifndef __USB_TYPE_ENDPOINT
typedef struct usb_endpoint_s * usb_endpoint_t;
#define __USB_TYPE_ENDPOINT __FILE__
#endif /* __USB_TYPE_ENDPOINT */

/* ---------- usb device ---------- */
/* devices can be addressed by their number. */
struct usb_device_s {
  semaphor           *protection;
  struct usb_hc_s    *hostcontroller;
  unsigned long      number;

  char               *name;          /* not used at the moment */
  unsigned long      speed;

  /* fields before this are fixed from revision 1.15 (18Jun2002), do not
   * rely on anything after this being kept the same */

  unsigned long      flags;
};

#ifndef __USB_DEVICE_T
#define __USB_DEVICE_T __FILE__
typedef struct usb_device_s *usb_device_t;
#endif /* __USB_DEVICE_T */

/* ---------- host controller ---------- */
/* See usb_defs.h for details of host controller properties */

struct usb_reqpend_endpoint_s {
  struct usb_endpoint_s *endpoint;
  unsigned long          frame_start;
};

#ifndef __USB_TYPE_HOST_CONTROLLER_PROPERTY

typedef struct usb_hc_property_s * host_controller_property_t;

#define __USB_TYPE_HOST_CONTROLLER_PROPERTY __FILE__
#endif /* __USB_TYPE_HOST_CONTROLLER_PROPERTY */

struct usb_hc_s {
  struct usb_hc_list_s *common;
  semaphor             *protection;
  char                 *name;

  /* Information for building the transaction structure */
  unsigned long        *offset_list;
  unsigned long        size_of_transactions;

  /* controller properties */
  host_controller_property_t properties;

  /* Bus state information */
  unsigned long        act_frame_number;

  /* device management - DO NOT USE left for structure compatibility. */
  unsigned long        max_unused_device_number;

  /* all other information now removed, any use of the removed 
   * field was in-advisable anyway */
};

#ifndef __USB_TYPE_HOST_CONTROLLER
typedef struct usb_hc_s * usb_hc_t;

#define __USB_TYPE_HOST_CONTROLLER __FILE__
#endif /* __USB_TYPE_HOST_CONTROLLER */

struct usb_hc_list_s {
  semaphor      *protection;
};

#endif /* __USB_USB_H */



