diff -r f08135942074 -r 2f55e5dd591d firmware/usbmmap.c
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/firmware/usbmmap.c	Tue Jan 29 22:31:52 2008 +0100
@@ -0,0 +1,284 @@
+/*********************************************************************
+ *
+ *                Microchip USB C18 Firmware Version 1.0
+ *
+ *********************************************************************
+ * FileName:        usbmmap.c
+ * Dependencies:    See INCLUDES section below
+ * Processor:       PIC18
+ * Compiler:        C18 2.30.01+
+ * Company:         Microchip Technology, Inc.
+ *
+ * Software License Agreement
+ *
+ * The software supplied herewith by Microchip Technology Incorporated
+ * (the “Company”) for its PICmicro® Microcontroller is intended and
+ * supplied to you, the Company’s customer, for use solely and
+ * exclusively on Microchip PICmicro Microcontroller products. The
+ * software is owned by the Company and/or its supplier, and is
+ * protected under applicable copyright laws. All rights are reserved.
+ * Any use in violation of the foregoing restrictions may subject the
+ * user to criminal sanctions under applicable laws, as well as to
+ * civil liability for the breach of the terms and conditions of this
+ * license.
+ *
+ * THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
+ * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
+ * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
+ * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
+ * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
+ *
+ * Author               Date        Comment
+ *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * Rawin Rojvanit       11/19/04    Original.
+ ********************************************************************/
+
+/******************************************************************************
+ * -usbmmap.c-
+ * USB Memory Map
+ * This file is the USB memory manager; it serves as a compile-time memory
+ * allocator for the USB endpoints. It uses the compile time options passed
+ * from usbcfg.h to instantiate endpoints and endpoint buffer.
+ *
+ * Each endpoint requires to have a set of Buffer Descriptor registers(BDT).
+ * A BDT is 4-byte long and has a specific RAM location for each endpoint.
+ * The BDT for endpoint 0 out is located at address 0x400 to 0x403.
+ * The BDT for endpoint 0 in is located at address 0x404 to 0x407.
+ * The BDT for endpoint 1 out is located at address 0x408 to 0x40B.
+ * and so on... The above allocation assumes the Ping-Pong Buffer Mode 0 is
+ * used. These locations are already hard-wired in the silicon. The point
+ * of doing instantiation, i.e. volatile far BDT ep0Bo;, is to provide the
+ * C compiler a way to address each variable directly. This is very important
+ * because when a register can be accessed directly, it saves execution time
+ * and reduces program size.
+ * 
+ * Endpoints are defined using the endpoint number and the direction
+ * of transfer. For simplicity, usbmmap.c only uses the endpoint number
+ * in the BDT register allocation scheme. This means if the usbcfg.h states
+ * that the MAX_EP_NUMBER is number 1, then four BDTs will be
+ * instantiated: one each for endpoint0 in and endpoint0 out, which must
+ * always be instantiated for control transfer by default, and one each sets
+ * for endpoint1 in and endpoint1 out. The naming convention for instantiating
+ * BDT is
+ * 
+ * ep<#>B<d>
+ *
+ * where # is the endpoint number, and d is the direction of
+ * transfer, which could be either <i> or <o>.
+ *
+ * The USB memory manager uses MAX_EP_NUMBER, as defined in usbcfg.h, to define
+ * the endpoints to be instantiated. This represents the highest endpoint
+ * number to be allocated, not how many endpoints are used. Since the BDTs for
+ * endpoints have hardware-assigned addresses in Bank 4, setting this value too
+ * high may lead to inefficient use of data RAM. For example, if an application
+ * uses only endpoints EP0 and EP4, then the MAX_EP_NUMBER is 4, and not 2.
+ * The in-between endpoint BDTs in this example (EP1, EP2, and EP3) go unused,
+ * and the 24 bytes of memory associated with them are wasted. It does not make
+ * much sense to skip endpoints, but the final decision lies with the user.
+ *
+ * The next step is to assign the instantiated BDTs to different
+ * USB functions. The firmware framework fundamentally assumes that every USB
+ * function should know which endpoint it is using, i.e., the default control
+ * transfer should know that it is using endpoint 0 in and endpoint 0 out.
+ * A HID class can choose which endpoint it wants to use, but once chosen, it
+ * should always know the number of the endpoint.
+ *
+ * The assignment of endpoints to USB functions is managed centrally
+ * in usbcfg.h. This helps prevent the mistake of having more
+ * than one USB function using the same endpoint. The "Endpoint Allocation"
+ * section in usbcfg.h provides examples for how to map USB endpoints to USB
+ * functions.
+ * Quite a few things can be mapped in that section. There is no
+ * one correct way to do the mapping and the user has the choice to
+ * choose a method that is most suitable to the application.
+ *
+ * Typically, however, a user will want to map the following for a given
+ * USB interface function:
+ * 1. The USB interface ID
+ * 2. The endpoint control registers (UEPn)
+ * 3. The BDT registers (ep<#>B<d>)
+ * 4. The endpoint size
+ *
+ * Example: Assume a USB device class "foo", which uses one out endpoint
+ *          of size 64-byte and one in endpoint of size 64-byte, then:
+ *
+ * #define FOO_INTF_ID          0x00
+ * #define FOO_UEP              UEP1
+ * #define FOO_BD_OUT           ep1Bo
+ * #define FOO_BD_IN            ep1Bi
+ * #define FOO_EP_SIZE          64
+ *
+ * The mapping above has chosen class "foo" to use endpoint 1.
+ * The names are arbitrary and can be anything other than FOO_??????.
+ * For abstraction, the code for class "foo" should use the abstract
+ * definitions of FOO_BD_OUT,FOO_BD_IN, and not ep1Bo or ep1Bi.
+ *
+ * Note that the endpoint size defined in the usbcfg.h file is again
+ * used in the usbmmap.c file. This shows that the relationship between
+ * the two files are tightly related.
+ * 
+ * The endpoint buffer for each USB function must be located in the
+ * dual-port RAM area and has to come after all the BDTs have been
+ * instantiated. An example declaration is:
+ * volatile far unsigned char[FOO_EP_SIZE] data;
+ *
+ * The 'volatile' keyword tells the compiler not to perform any code
+ * optimization on this variable because its content could be modified
+ * by the hardware. The 'far' keyword tells the compiler that this variable
+ * is not located in the Access RAM area (0x000 - 0x05F).
+ *
+ * For the variable to be globally accessible by other files, it should be
+ * declared in the header file usbmmap.h as an extern definition, such as
+ * extern volatile far unsigned char[FOO_EP_SIZE] data;
+ *
+ * Conclusion:
+ * In a short summary, the dependencies between usbcfg and usbmmap can
+ * be shown as:
+ *
+ * usbcfg[MAX_EP_NUMBER] -> usbmmap
+ * usbmmap[ep<#>B<d>] -> usbcfg
+ * usbcfg[EP size] -> usbmmap
+ * usbcfg[abstract ep definitions] -> usb9/hid/cdc/etc class code
+ * usbmmap[endpoint buffer variable] -> usb9/hid/cdc/etc class code
+ *
+ * Data mapping provides a means for direct addressing of BDT and endpoint
+ * buffer. This means less usage of pointers, which equates to a faster and
+ * smaller program code.
+ *
+ *****************************************************************************/
+
+/** I N C L U D E S **********************************************************/
+#include "typedefs.h"
+#include "usb.h"
+
+/** U S B  G L O B A L  V A R I A B L E S ************************************/
+#pragma udata
+byte usb_device_state;          // Device States: DETACHED, ATTACHED, ...
+USB_DEVICE_STATUS usb_stat;     // Global USB flags
+byte usb_active_cfg;            // Value of current configuration
+byte usb_alt_intf[MAX_NUM_INT]; // Array to keep track of the current alternate
+                                // setting for each interface ID
+
+/** U S B  F I X E D  L O C A T I O N  V A R I A B L E S *********************/
+#pragma udata usbram4=0x400     //See Linker Script,usb4:0x400-0x4FF(256-byte)
+
+/******************************************************************************
+ * Section A: Buffer Descriptor Table
+ * - 0x400 - 0x4FF(max)
+ * - MAX_EP_NUMBER is defined in autofiles\usbcfg.h
+ * - BDT data type is defined in system\usb\usbmmap.h
+ *****************************************************************************/
+
+#if(0 <= MAX_EP_NUMBER)
+volatile far BDT ep0Bo;         //Endpoint #0 BD Out
+volatile far BDT ep0Bi;         //Endpoint #0 BD In
+#endif
+
+#if(1 <= MAX_EP_NUMBER)
+volatile far BDT ep1Bo;         //Endpoint #1 BD Out
+volatile far BDT ep1Bi;         //Endpoint #1 BD In
+#endif
+
+#if(2 <= MAX_EP_NUMBER)
+volatile far BDT ep2Bo;         //Endpoint #2 BD Out
+volatile far BDT ep2Bi;         //Endpoint #2 BD In
+#endif
+
+#if(3 <= MAX_EP_NUMBER)
+volatile far BDT ep3Bo;         //Endpoint #3 BD Out
+volatile far BDT ep3Bi;         //Endpoint #3 BD In
+#endif
+
+#if(4 <= MAX_EP_NUMBER)
+volatile far BDT ep4Bo;         //Endpoint #4 BD Out
+volatile far BDT ep4Bi;         //Endpoint #4 BD In
+#endif
+
+#if(5 <= MAX_EP_NUMBER)
+volatile far BDT ep5Bo;         //Endpoint #5 BD Out
+volatile far BDT ep5Bi;         //Endpoint #5 BD In
+#endif
+
+#if(6 <= MAX_EP_NUMBER)
+volatile far BDT ep6Bo;         //Endpoint #6 BD Out
+volatile far BDT ep6Bi;         //Endpoint #6 BD In
+#endif
+
+#if(7 <= MAX_EP_NUMBER)
+volatile far BDT ep7Bo;         //Endpoint #7 BD Out
+volatile far BDT ep7Bi;         //Endpoint #7 BD In
+#endif
+
+#if(8 <= MAX_EP_NUMBER)
+volatile far BDT ep8Bo;         //Endpoint #8 BD Out
+volatile far BDT ep8Bi;         //Endpoint #8 BD In
+#endif
+
+#if(9 <= MAX_EP_NUMBER)
+volatile far BDT ep9Bo;         //Endpoint #9 BD Out
+volatile far BDT ep9Bi;         //Endpoint #9 BD In
+#endif
+
+#if(10 <= MAX_EP_NUMBER)
+volatile far BDT ep10Bo;        //Endpoint #10 BD Out
+volatile far BDT ep10Bi;        //Endpoint #10 BD In
+#endif
+
+#if(11 <= MAX_EP_NUMBER)
+volatile far BDT ep11Bo;        //Endpoint #11 BD Out
+volatile far BDT ep11Bi;        //Endpoint #11 BD In
+#endif
+
+#if(12 <= MAX_EP_NUMBER)
+volatile far BDT ep12Bo;        //Endpoint #12 BD Out
+volatile far BDT ep12Bi;        //Endpoint #12 BD In
+#endif
+
+#if(13 <= MAX_EP_NUMBER)
+volatile far BDT ep13Bo;        //Endpoint #13 BD Out
+volatile far BDT ep13Bi;        //Endpoint #13 BD In
+#endif
+
+#if(14 <= MAX_EP_NUMBER)
+volatile far BDT ep14Bo;        //Endpoint #14 BD Out
+volatile far BDT ep14Bi;        //Endpoint #14 BD In
+#endif
+
+#if(15 <= MAX_EP_NUMBER)
+volatile far BDT ep15Bo;        //Endpoint #15 BD Out
+volatile far BDT ep15Bi;        //Endpoint #15 BD In
+#endif
+
+/******************************************************************************
+ * Section B: EP0 Buffer Space
+ ******************************************************************************
+ * - Two buffer areas are defined:
+ *
+ *   A. CTRL_TRF_SETUP
+ *      - Size = EP0_BUFF_SIZE as defined in autofiles\usbcfg.h
+ *      - Detailed data structure allows direct adddressing of bits and bytes.
+ *
+ *   B. CTRL_TRF_DATA
+ *      - Size = EP0_BUFF_SIZE as defined in autofiles\usbcfg.h
+ *      - Data structure allows direct adddressing of the first 8 bytes.
+ *
+ * - Both data types are defined in system\usb\usbdefs\usbdefs_ep0_buff.h
+ *****************************************************************************/
+volatile far CTRL_TRF_SETUP SetupPkt;
+volatile far CTRL_TRF_DATA CtrlTrfData;
+
+/******************************************************************************
+ * Section C: CDC Buffer
+ ******************************************************************************
+ *
+ *****************************************************************************/
+#pragma udata usbram5a=0x500    //See Linker Script,usb5:0x500-...
+#if defined(USB_USE_CDC)
+volatile far unsigned char cdc_notice[CDC_INT_EP_SIZE];
+volatile far unsigned char cdc_data_rx[CDC_BULK_OUT_EP_SIZE];
+volatile far unsigned char cdc_data_tx[CDC_BULK_IN_EP_SIZE];
+#endif
+#pragma udata
+
+/** EOF usbmmap.c ************************************************************/