X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/77fd24511771873c246c56518e77f1aedde9f0b8..HEAD:/firmware/usbdrv/usbdrv.h diff --git a/firmware/usbdrv/usbdrv.h b/firmware/usbdrv/usbdrv.h index 94085762d..113854e71 100644 --- a/firmware/usbdrv/usbdrv.h +++ b/firmware/usbdrv/usbdrv.h @@ -1,36 +1,38 @@ /* Name: usbdrv.h - * Project: AVR USB driver + * Project: V-USB, virtual USB port for Atmel's(r) AVR(r) microcontrollers * Author: Christian Starkjohann * Creation Date: 2004-12-29 * Tabsize: 4 * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH - * License: GNU GPL v2 (see License.txt) or proprietary (CommercialLicense.txt) - * This Revision: $Id: usbdrv.h 375 2007-07-07 12:01:52Z cs $ + * License: GNU GPL v2 (see License.txt), GNU GPL v3 or proprietary (CommercialLicense.txt) */ #ifndef __usbdrv_h_included__ #define __usbdrv_h_included__ -#include "usbconfig.h" -#include "iarcompat.h" /* Hardware Prerequisites: ======================= -USB lines D+ and D- MUST be wired to the same I/O port. 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. - -As a compile time option, the 1.5k pullup resistor on D- can be made +USB lines D+ and D- MUST be wired to the same I/O port. We recommend that D+ +triggers the interrupt (best achieved by using INT0 for D+), but it is also +possible to trigger the interrupt from D-. If D- is used, interrupts are also +triggered by SOF packets. D- requires a pull-up of 1.5k to +3.5V (and the +device must be powered at 3.5V) to identify as low-speed USB device. A +pull-down or pull-up of 1M SHOULD be connected from D+ to +3.5V to prevent +interference when no USB master is connected. If you use Zener diodes to limit +the voltage on D+ and D-, you MUST use a pull-down resistor, not a pull-up. +We use D+ as interrupt source and not D- because it does not trigger on +keep-alive and RESET states. If you want to count keep-alive events with +USB_COUNT_SOF, you MUST use D- as an interrupt source. + +As a compile time option, the 1.5k pull-up resistor on D- can be made switchable to allow the device to disconnect at will. See the definition of usbDeviceConnect() and usbDeviceDisconnect() further down in this file. Please adapt the values in usbconfig.h according to your hardware! -The device MUST be clocked at exactly 12 MHz or 16 MHz or at 16.5 MHz +/- 1%. -See usbconfig-prototype.h for details. +The device MUST be clocked at exactly 12 MHz, 15 MHz, 16 MHz or 20 MHz +or at 12.8 MHz resp. 16.5 MHz +/- 1%. See usbconfig-prototype.h for details. Limitations: @@ -53,16 +55,26 @@ 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 supports up to four endpoints: One control endpoint (endpoint 0), -two interrupt-in (or bulk-in) endpoints (endpoint 1 and 3) and one -interrupt-out (or bulk-out) endpoint (endpoint 1). Please note that the USB -standard forbids bulk endpoints for low speed devices! Most operating systems -allow them anyway, but the AVR will spend 90% of the CPU time in the USB -interrupt polling for bulk data. -By default, only the control endpoint 0 is enabled. To get the other endpoints, -define USB_CFG_HAVE_INTRIN_ENDPOINT, USB_CFG_HAVE_INTRIN_ENDPOINT3 and/or -USB_CFG_IMPLEMENT_FN_WRITEOUT respectively (see usbconfig-prototype.h for -details). +The driver supports the following endpoints: + +- Endpoint 0, the default control endpoint. +- Any number of interrupt- or bulk-out endpoints. The data is sent to + usbFunctionWriteOut() and USB_CFG_IMPLEMENT_FN_WRITEOUT must be defined + to 1 to activate this feature. The endpoint number can be found in the + global variable 'usbRxToken'. +- One default interrupt- or bulk-in endpoint. This endpoint is used for + interrupt- or bulk-in transfers which are not handled by any other endpoint. + You must define USB_CFG_HAVE_INTRIN_ENDPOINT in order to activate this + feature and call usbSetInterrupt() to send interrupt/bulk data. +- One additional interrupt- or bulk-in endpoint. This was endpoint 3 in + previous versions of this driver but can now be configured to any endpoint + number. You must define USB_CFG_HAVE_INTRIN_ENDPOINT3 in order to activate + this feature and call usbSetInterrupt3() to send interrupt/bulk data. The + endpoint number can be set with USB_CFG_EP3_NUMBER. + +Please note that the USB standard forbids bulk endpoints for low speed devices! +Most operating systems allow them anyway, but the AVR will spend 90% of the CPU +time in the USB interrupt polling for bulk data. Maximum data payload: Data payload of control in and out transfers may be up to 254 bytes. In order @@ -76,22 +88,23 @@ 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. +SE0 states can be detected by using D- as the interrupt source. Define +USB_COUNT_SOF to 1 and use the global variable usbSofCount to check for 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. +pull-down or pull-up resistor on D+ (interrupt). If Zener diodes are used, +use a pull-down. 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. This implies that all interrupt routines must either be -declared as "INTERRUPT" instead of "SIGNAL" (see "avr/signal.h") or that they -are written in assembler with "sei" as the first instruction. +than 25 cycles (this is for 12 MHz, faster clocks allow longer latency). +This implies that all interrupt routines must either have the "ISR_NOBLOCK" +attribute set (see "avr/interrupt.h") or be written in assembler with "sei" +as the first instruction. Maximum interrupt duration / CPU cycle consumption: The driver handles all USB communication during the interrupt service @@ -102,11 +115,28 @@ USB messages, even if they address another (low-speed) device on the same bus. */ + +#ifdef __cplusplus +// This header should be included as C-header from C++ code. However if usbdrv.c +// is incorporated into a C++ module with an include, function names are mangled +// and this header must be parsed as C++ header, too. External modules should be +// treated as C, though, because they are compiled separately as C code. +extern "C" { +#endif + +#include "usbconfig.h" +#include "usbportability.h" + +#ifdef __cplusplus +} +#endif + + /* ------------------------------------------------------------------------- */ /* --------------------------- Module Interface ---------------------------- */ /* ------------------------------------------------------------------------- */ -#define USBDRV_VERSION 20070707 +#define USBDRV_VERSION 20121206 /* This define uniquely identifies a driver version. It is a decimal number * constructed from the driver's release date in the form YYYYMMDD. If the * driver's behavior or interface changes, you can use this constant to @@ -134,11 +164,37 @@ USB messages, even if they address another (low-speed) device on the same bus. #endif /* shortcuts for well defined 8 bit integer types */ +#if USB_CFG_LONG_TRANSFERS /* if more than 254 bytes transfer size required */ +# define usbMsgLen_t unsigned +#else +# define usbMsgLen_t uchar +#endif +/* usbMsgLen_t is the data type used for transfer lengths. By default, it is + * defined to uchar, allowing a maximum of 254 bytes (255 is reserved for + * USB_NO_MSG below). If the usbconfig.h defines USB_CFG_LONG_TRANSFERS to 1, + * a 16 bit data type is used, allowing up to 16384 bytes (the rest is used + * for flags in the descriptor configuration). + */ +#define USB_NO_MSG ((usbMsgLen_t)-1) /* constant meaning "no message" */ + +#ifndef usbMsgPtr_t +#define usbMsgPtr_t uchar * +#endif +/* Making usbMsgPtr_t a define allows the user of this library to define it to + * an 8 bit type on tiny devices. This reduces code size, especially if the + * compiler supports a tiny memory model. + * The type can be a pointer or scalar type, casts are made where necessary. + * Although it's paradoxical, Gcc 4 generates slightly better code for scalar + * types than for pointers. + */ + struct usbRequest; /* forward declaration */ USB_PUBLIC void usbInit(void); /* This function must be called before interrupts are enabled and the main - * loop is entered. + * loop is entered. We exepct that the PORT and DDR bits for D+ and D- have + * not been changed from their default status (which is 0). If you have changed + * them, set both back to 0 (configure them as input with no internal pull-up). */ USB_PUBLIC void usbPoll(void); /* This function must be called at regular intervals from the main loop. @@ -147,12 +203,12 @@ USB_PUBLIC void usbPoll(void); * Please note that debug outputs through the UART take ~ 0.5ms per byte * at 19200 bps. */ -extern uchar *usbMsgPtr; +extern usbMsgPtr_t usbMsgPtr; /* This variable may be used to pass transmit data to the driver from the * implementation of usbFunctionWrite(). It is also used internally by the * driver for standard control requests. */ -USB_PUBLIC uchar usbFunctionSetup(uchar data[8]); +USB_PUBLIC usbMsgLen_t usbFunctionSetup(uchar data[8]); /* This function is called when the driver receives a SETUP transaction from * the host which is not answered by the driver itself (in practice: class and * vendor requests). All control transfers start with a SETUP transaction where @@ -165,21 +221,21 @@ USB_PUBLIC uchar usbFunctionSetup(uchar data[8]); * requested data to the driver. There are two ways to transfer this data: * (1) Set the global pointer 'usbMsgPtr' to the base of the static RAM data * block and return the length of the data in 'usbFunctionSetup()'. The driver - * will handle the rest. Or (2) return 0xff in 'usbFunctionSetup()'. The driver - * will then call 'usbFunctionRead()' when data is needed. See the + * will handle the rest. Or (2) return USB_NO_MSG in 'usbFunctionSetup()'. The + * driver will then call 'usbFunctionRead()' when data is needed. See the * documentation for usbFunctionRead() for details. * * If the SETUP indicates a control-out transfer, the only way to receive the * data from the host is through the 'usbFunctionWrite()' call. If you - * implement this function, you must return 0xff in 'usbFunctionSetup()' to - * indicate that 'usbFunctionWrite()' should be used. See the documentation of - * this function for more information. If you just want to ignore the data sent - * by the host, return 0 in 'usbFunctionSetup()'. + * implement this function, you must return USB_NO_MSG in 'usbFunctionSetup()' + * to indicate that 'usbFunctionWrite()' should be used. See the documentation + * of this function for more information. If you just want to ignore the data + * sent by the host, return 0 in 'usbFunctionSetup()'. * * Note that calls to the functions usbFunctionRead() and usbFunctionWrite() * are only done if enabled by the configuration in usbconfig.h. */ -USB_PUBLIC uchar usbFunctionDescriptor(struct usbRequest *rq); +USB_PUBLIC usbMsgLen_t usbFunctionDescriptor(struct usbRequest *rq); /* You need to implement this function ONLY if you provide USB descriptors at * runtime (which is an expert feature). It is very similar to * usbFunctionSetup() above, but it is called only to request USB descriptor @@ -193,7 +249,6 @@ USB_PUBLIC void usbSetInterrupt(uchar *data, uchar len); * interrupt status to the host. * If you need to transfer more bytes, use a control read after the interrupt. */ -extern volatile uchar usbTxLen1; #define usbInterruptIsReady() (usbTxLen1 & 0x10) /* This macro indicates whether the last interrupt message has already been * sent. If you set a new interrupt message before the old was sent, the @@ -201,7 +256,6 @@ extern volatile uchar usbTxLen1; */ #if USB_CFG_HAVE_INTRIN_ENDPOINT3 USB_PUBLIC void usbSetInterrupt3(uchar *data, uchar len); -extern volatile uchar usbTxLen3; #define usbInterruptIsReady3() (usbTxLen3 & 0x10) /* Same as above for endpoint 3 */ #endif @@ -246,27 +300,37 @@ USB_PUBLIC uchar usbFunctionRead(uchar *data, uchar len); * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. */ #endif /* USB_CFG_IMPLEMENT_FN_READ */ + +extern uchar usbRxToken; /* may be used in usbFunctionWriteOut() below */ #if USB_CFG_IMPLEMENT_FN_WRITEOUT USB_PUBLIC void usbFunctionWriteOut(uchar *data, uchar len); -/* This function is called by the driver when data on interrupt-out or bulk- - * out endpoint 1 is received. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT - * to 1 in usbconfig.h to get this function called. +/* This function is called by the driver when data is received on an interrupt- + * or bulk-out endpoint. The endpoint number can be found in the global + * variable usbRxToken. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT to 1 in + * usbconfig.h to get this function called. */ #endif /* USB_CFG_IMPLEMENT_FN_WRITEOUT */ #ifdef USB_CFG_PULLUP_IOPORTNAME #define usbDeviceConnect() ((USB_PULLUP_DDR |= (1<