usbdrv.h

软USB核的电力开关PowerSwitch

/* Name: usbdrv.h
 * Project: AVR USB driver
 * Author: Christian Starkjohann
 * Creation Date: 2004-12-29
 * Tabsize: 4
 * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH
 * License: Proprietary, free under certain conditions. See Documentation.
 * This Revision: $Id: usbdrv.h 20 2005-02-20 16:39:43Z cs $
 */

#ifndef __usbdrv_h_included__
#define	__usbdrv_h_included__

/*
Hardware Prerequisites:
=======================
USB lines D+ and D- MUST be wired to the same I/O port (defined as USBIN /
USBOUT). Line D- MUST be wired to bit number 0. D+ must also be connected to
INT0. D- requires a pullup of 1.5k to +3.5V (and the device must be powered
at 3.5V) to identify as low-speed USB device. A pullup of 1M SHOULD be
connected from D+ to +3.5V to prevent interference when no USB master is
connected. We use D+ as interrupt source and not D- because it does not
trigger on keep-alive and RESET states.

The device MUST be clocked at 12 MHz. This is more than the 10 MHz allowed by
an AT90S2313 powered at 4.5V. However, if the supply voltage to maximum clock
relation is interpolated linearly, an ATtiny2313 meets the requirement by
specification. In practice, the AT90S2313 can be overclocked and works well.


Limitations:
============
Compiling:
The bss segment of the driver must be in the first 256 bytes of the address
space because byte wide variables are used as pointers for efficiency reasons.
This is not a problem on devices with 128 byte RAM since the entire RAM
meets this condition. For larger devices please link usbdrv first.

Robustness with respect to communication errors:
The driver assumes error-free communication. It DOES check for errors in
the PID, but does NOT check bit stuffing errors, SE0 in middle of a byte,
token CRC (5 bit) and data CRC (16 bit). CRC checks can not be performed due
to timing constraints: We must start sending a reply within 7 bit times. 
Bit stuffing and misplaced SE0 would have to be checked in real-time, but CPU
performance does not permit that. The driver does not check Data0/Data1
toggling, but application software can implement the check.

Sampling jitter:
The driver guarantees a sampling window of 1/2 bit. The USB spec requires
that the receiver has at most 1/4 bit sampling window. The 1/2 bit window
should still work reliably enough because we work at low speed. If you want
to meet the spec, define the macro "USB_SAMPLE_EXACT" at compile time. This
will unroll a loop which results in bigger code size.

Input characteristics:
Since no differential receiver circuit is used, electrical interference
robustness may suffer. The driver samples only one of the data lines with
an ordinary I/O pin's input characteristics. However, since this is only a
low speed USB implementation and the specification allows for 8 times the
bit rate over the same hardware, we should be on the safe side. Even the spec
requires detection of asymmetric states at high bit rate for SE0 detection.

Number of endpoints:
The driver stores only the LSB of the endpoint number. This limits
implementations to 2 endpoints instead of the maximum permittable 3.
Endpoint 1 may not be used for control our output with the current
implementation. See usbdrvasm.S at label "isSetupOrOut" for more information.

USB Suspend Mode supply current:
The USB standard limits power consumption to 500uA when the bus is in suspend
mode. This is not a problem for self-powered devices since they don't need
bus power anyway. Bus-powered devices can achieve this only by putting the
CPU in sleep mode. The driver does not implement suspend handling by itself.
However, the application may implement activity monitoring and wakeup from
sleep. The host sends regular SE0 states on the bus to keep it active. These
SE0 states can be detected by wiring the INT1 pin to D+. It is not necessary
to enable the interrupt, checking the interrupt pending flag should suffice.
Before entering sleep mode, the application should enable INT1 for a wakeup
on the next bus activity.

Operation without an USB master:
The driver behaves neutral without connection to an USB master if D- reads
as 1. To avoid spurious interrupts, we recommend a high impedance (e.g. 1M)
pullup resistor on D+. If D- becomes statically 0, the driver may block in
the interrupt routine.

Interrupt latency:
The application must ensure that the USB interrupt is not disabled for more
than 20 cycles.

Maximum interrupt duration / CPU cycle consumption:
The driver handles all USB communication during the interrupt service
routine. The routine will not return before an entire USB message is received
and the reply is sent. This may be up to ca. 1200 cycles = 100us if the host
conforms to the standard. The driver will consume CPU cycles for all USB
messages, even if they address an other (low-speed) device on the same bus.

*/

/* ------------------------------------------------------------------------- */
/* ------------------------- configuration Options ------------------------- */
/* ------------------------------------------------------------------------- */

#define	USB_IS_SELFPOWERED	1	/* can be 0 or 1 */
/* Whether the device is self-powered (1) or bus-powered (0) */

/* #define	USB_HAVE_ENDPOINT1 */
/* See comments below about endpoint 1 */

/* #define	USB_SAMPLE_EXACT */
/* See comments above or comments in usbdrvasm.S */

/* symbolic I/O names */
#define	USBOUT		PORTB	/* output port for USB bits */
#define	USBIN		PINB	/* input port for USB bits */
#define	USBDDR		DDRB	/* data direction for USB bits */
#define	USBPLUS		1		/* bit number in port */
#define	USBMINUS	0		/* bit number in port */
#define	USBIDLE		0x01	/* value representing J state */
#define	USBMASK		3		/* mask for USB I/O bits */

/* For more configuration options see usbdrv.c. You should change the USB
 * descriptors according to your application. Please change at least the
 * USB vendor- and product-IDs.
 */

/* constants */
#define	USB_BUFSIZE		11	/* PID, 8 bytes data, 2 bytes CRC */

/* ------------------------------------------------------------------------- */
/* ---------------------- USB Specification Constants ---------------------- */
/* ------------------------------------------------------------------------- */

/* USB Token values */
#define	USBPID_SETUP	0x2d
#define	USBPID_OUT		0xe1
#define	USBPID_IN		0x69
#define	USBPID_DATA0	0xc3
#define	USBPID_DATA1	0x4b

#define	USBPID_ACK		0xd2
#define	USBPID_NAK		0x5a
#define	USBPID_STALL	0x1e

/* USB descriptor constants */
#define	USBATTR_BUSPOWER	0x80
#define	USBATTR_SELFPOWER	0x40
#define	USBATTR_REMOTEWAKE	0x20

/* USB setup recipient values */
#define	USBRQ_RCPT_DEVICE		0
#define	USBRQ_RCPT_INTERFACE	1
#define	USBRQ_RCPT_ENDPOINT		2

/* USB request type values */
#define	USBRQ_TYPE_STANDARD		0
#define	USBRQ_TYPE_CLASS		1
#define	USBRQ_TYPE_VENDOR		2

/* ------------------------------------------------------------------------- */
/* --------------------------- Module Interface ---------------------------- */
/* ------------------------------------------------------------------------- */

#ifndef __ASSEMBLER__

#ifndef uchar
#define	uchar	unsigned char
#endif

#ifdef USB_HAVE_ENDPOINT1
extern char		usbTxLen1 = -1;
extern uchar	usbTxBuf1[USB_BUFSIZE];
/* These are the raw driver variables for sending data to endpoint 1. They
 * can be used for interrupt transfers -- see the example for endpoint 0
 * in usbdrv.c function usbBuildTxBlock(). A high level interface has not yet
 * been defined for this type of transfer.
 */
#endif

extern void		usbInit(void);
/* This function must be called before interrupts are enabled and the main
 * loop is entered.
 */
extern void		usbPoll(void);
/* This function must be called at regular intervals from the main loop.
 * Maximum delay between calls is somewhat less than 50ms (USB timeout between
 * packages of a message).
 */
extern uchar	usbVendorSetup(uchar data[8], uchar *replyBuf);
/* This function must be provided by the application. It gets control requests
 * of type "Vendor" in 'data' and may write a short reply to 'replyBuf' (which
 * can hold 2 bytes in the current implementation). The function must return
 * the length in bytes of the reply.
 */
extern void		usbSendMsg(uchar *data, uchar len, uchar options);
/* This function schedules the static data in 'data' of length 'len' for
 * the next IN transfer on endpoint 0. Any existing or even running transfers
 * are aborted and overwritten. You don't need this function when you
 * usbVendorSetup() since usbVendorSetup() already calls usbSendMsg().
 */
/* values for 'options': */
#define	USBSND_DATA0_RAM	0		/* send RAM data beginning with DATA0 PID */
#define	USBSND_DATA1_RAM	1		/* send RAM data beginning with DATA1 PID */
#define	USBSND_DATA0_ROM	0x80	/* send ROM data beginning with DATA0 PID */
#define	USBSND_DATA1_ROM	0x81	/* send ROM data beginning with DATA1 PID */
extern unsigned	usbCrc16(uchar *data, uchar len);
/* This function calculates the binary complement of the data CRC used in
 * USB data packets. The value is used to build raw transmit packets. You need
 * this only if you implement an interrupt IN endpoint.
 */


#endif

/* ------------------------------------------------------------------------- */

#endif /* __usbdrv_h_included__ */