1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/firmware/usbmmap.c Tue Jan 29 22:31:52 2008 +0100
1.3 @@ -0,0 +1,284 @@
1.4 +/*********************************************************************
1.5 + *
1.6 + * Microchip USB C18 Firmware Version 1.0
1.7 + *
1.8 + *********************************************************************
1.9 + * FileName: usbmmap.c
1.10 + * Dependencies: See INCLUDES section below
1.11 + * Processor: PIC18
1.12 + * Compiler: C18 2.30.01+
1.13 + * Company: Microchip Technology, Inc.
1.14 + *
1.15 + * Software License Agreement
1.16 + *
1.17 + * The software supplied herewith by Microchip Technology Incorporated
1.18 + * (the “Company”) for its PICmicro® Microcontroller is intended and
1.19 + * supplied to you, the Company’s customer, for use solely and
1.20 + * exclusively on Microchip PICmicro Microcontroller products. The
1.21 + * software is owned by the Company and/or its supplier, and is
1.22 + * protected under applicable copyright laws. All rights are reserved.
1.23 + * Any use in violation of the foregoing restrictions may subject the
1.24 + * user to criminal sanctions under applicable laws, as well as to
1.25 + * civil liability for the breach of the terms and conditions of this
1.26 + * license.
1.27 + *
1.28 + * THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
1.29 + * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
1.30 + * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
1.31 + * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
1.32 + * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
1.33 + * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
1.34 + *
1.35 + * Author Date Comment
1.36 + *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.37 + * Rawin Rojvanit 11/19/04 Original.
1.38 + ********************************************************************/
1.39 +
1.40 +/******************************************************************************
1.41 + * -usbmmap.c-
1.42 + * USB Memory Map
1.43 + * This file is the USB memory manager; it serves as a compile-time memory
1.44 + * allocator for the USB endpoints. It uses the compile time options passed
1.45 + * from usbcfg.h to instantiate endpoints and endpoint buffer.
1.46 + *
1.47 + * Each endpoint requires to have a set of Buffer Descriptor registers(BDT).
1.48 + * A BDT is 4-byte long and has a specific RAM location for each endpoint.
1.49 + * The BDT for endpoint 0 out is located at address 0x400 to 0x403.
1.50 + * The BDT for endpoint 0 in is located at address 0x404 to 0x407.
1.51 + * The BDT for endpoint 1 out is located at address 0x408 to 0x40B.
1.52 + * and so on... The above allocation assumes the Ping-Pong Buffer Mode 0 is
1.53 + * used. These locations are already hard-wired in the silicon. The point
1.54 + * of doing instantiation, i.e. volatile far BDT ep0Bo;, is to provide the
1.55 + * C compiler a way to address each variable directly. This is very important
1.56 + * because when a register can be accessed directly, it saves execution time
1.57 + * and reduces program size.
1.58 + *
1.59 + * Endpoints are defined using the endpoint number and the direction
1.60 + * of transfer. For simplicity, usbmmap.c only uses the endpoint number
1.61 + * in the BDT register allocation scheme. This means if the usbcfg.h states
1.62 + * that the MAX_EP_NUMBER is number 1, then four BDTs will be
1.63 + * instantiated: one each for endpoint0 in and endpoint0 out, which must
1.64 + * always be instantiated for control transfer by default, and one each sets
1.65 + * for endpoint1 in and endpoint1 out. The naming convention for instantiating
1.66 + * BDT is
1.67 + *
1.68 + * ep<#>B<d>
1.69 + *
1.70 + * where # is the endpoint number, and d is the direction of
1.71 + * transfer, which could be either <i> or <o>.
1.72 + *
1.73 + * The USB memory manager uses MAX_EP_NUMBER, as defined in usbcfg.h, to define
1.74 + * the endpoints to be instantiated. This represents the highest endpoint
1.75 + * number to be allocated, not how many endpoints are used. Since the BDTs for
1.76 + * endpoints have hardware-assigned addresses in Bank 4, setting this value too
1.77 + * high may lead to inefficient use of data RAM. For example, if an application
1.78 + * uses only endpoints EP0 and EP4, then the MAX_EP_NUMBER is 4, and not 2.
1.79 + * The in-between endpoint BDTs in this example (EP1, EP2, and EP3) go unused,
1.80 + * and the 24 bytes of memory associated with them are wasted. It does not make
1.81 + * much sense to skip endpoints, but the final decision lies with the user.
1.82 + *
1.83 + * The next step is to assign the instantiated BDTs to different
1.84 + * USB functions. The firmware framework fundamentally assumes that every USB
1.85 + * function should know which endpoint it is using, i.e., the default control
1.86 + * transfer should know that it is using endpoint 0 in and endpoint 0 out.
1.87 + * A HID class can choose which endpoint it wants to use, but once chosen, it
1.88 + * should always know the number of the endpoint.
1.89 + *
1.90 + * The assignment of endpoints to USB functions is managed centrally
1.91 + * in usbcfg.h. This helps prevent the mistake of having more
1.92 + * than one USB function using the same endpoint. The "Endpoint Allocation"
1.93 + * section in usbcfg.h provides examples for how to map USB endpoints to USB
1.94 + * functions.
1.95 + * Quite a few things can be mapped in that section. There is no
1.96 + * one correct way to do the mapping and the user has the choice to
1.97 + * choose a method that is most suitable to the application.
1.98 + *
1.99 + * Typically, however, a user will want to map the following for a given
1.100 + * USB interface function:
1.101 + * 1. The USB interface ID
1.102 + * 2. The endpoint control registers (UEPn)
1.103 + * 3. The BDT registers (ep<#>B<d>)
1.104 + * 4. The endpoint size
1.105 + *
1.106 + * Example: Assume a USB device class "foo", which uses one out endpoint
1.107 + * of size 64-byte and one in endpoint of size 64-byte, then:
1.108 + *
1.109 + * #define FOO_INTF_ID 0x00
1.110 + * #define FOO_UEP UEP1
1.111 + * #define FOO_BD_OUT ep1Bo
1.112 + * #define FOO_BD_IN ep1Bi
1.113 + * #define FOO_EP_SIZE 64
1.114 + *
1.115 + * The mapping above has chosen class "foo" to use endpoint 1.
1.116 + * The names are arbitrary and can be anything other than FOO_??????.
1.117 + * For abstraction, the code for class "foo" should use the abstract
1.118 + * definitions of FOO_BD_OUT,FOO_BD_IN, and not ep1Bo or ep1Bi.
1.119 + *
1.120 + * Note that the endpoint size defined in the usbcfg.h file is again
1.121 + * used in the usbmmap.c file. This shows that the relationship between
1.122 + * the two files are tightly related.
1.123 + *
1.124 + * The endpoint buffer for each USB function must be located in the
1.125 + * dual-port RAM area and has to come after all the BDTs have been
1.126 + * instantiated. An example declaration is:
1.127 + * volatile far unsigned char[FOO_EP_SIZE] data;
1.128 + *
1.129 + * The 'volatile' keyword tells the compiler not to perform any code
1.130 + * optimization on this variable because its content could be modified
1.131 + * by the hardware. The 'far' keyword tells the compiler that this variable
1.132 + * is not located in the Access RAM area (0x000 - 0x05F).
1.133 + *
1.134 + * For the variable to be globally accessible by other files, it should be
1.135 + * declared in the header file usbmmap.h as an extern definition, such as
1.136 + * extern volatile far unsigned char[FOO_EP_SIZE] data;
1.137 + *
1.138 + * Conclusion:
1.139 + * In a short summary, the dependencies between usbcfg and usbmmap can
1.140 + * be shown as:
1.141 + *
1.142 + * usbcfg[MAX_EP_NUMBER] -> usbmmap
1.143 + * usbmmap[ep<#>B<d>] -> usbcfg
1.144 + * usbcfg[EP size] -> usbmmap
1.145 + * usbcfg[abstract ep definitions] -> usb9/hid/cdc/etc class code
1.146 + * usbmmap[endpoint buffer variable] -> usb9/hid/cdc/etc class code
1.147 + *
1.148 + * Data mapping provides a means for direct addressing of BDT and endpoint
1.149 + * buffer. This means less usage of pointers, which equates to a faster and
1.150 + * smaller program code.
1.151 + *
1.152 + *****************************************************************************/
1.153 +
1.154 +/** I N C L U D E S **********************************************************/
1.155 +#include "typedefs.h"
1.156 +#include "usb.h"
1.157 +
1.158 +/** U S B G L O B A L V A R I A B L E S ************************************/
1.159 +#pragma udata
1.160 +byte usb_device_state; // Device States: DETACHED, ATTACHED, ...
1.161 +USB_DEVICE_STATUS usb_stat; // Global USB flags
1.162 +byte usb_active_cfg; // Value of current configuration
1.163 +byte usb_alt_intf[MAX_NUM_INT]; // Array to keep track of the current alternate
1.164 + // setting for each interface ID
1.165 +
1.166 +/** 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 *********************/
1.167 +#pragma udata usbram4=0x400 //See Linker Script,usb4:0x400-0x4FF(256-byte)
1.168 +
1.169 +/******************************************************************************
1.170 + * Section A: Buffer Descriptor Table
1.171 + * - 0x400 - 0x4FF(max)
1.172 + * - MAX_EP_NUMBER is defined in autofiles\usbcfg.h
1.173 + * - BDT data type is defined in system\usb\usbmmap.h
1.174 + *****************************************************************************/
1.175 +
1.176 +#if(0 <= MAX_EP_NUMBER)
1.177 +volatile far BDT ep0Bo; //Endpoint #0 BD Out
1.178 +volatile far BDT ep0Bi; //Endpoint #0 BD In
1.179 +#endif
1.180 +
1.181 +#if(1 <= MAX_EP_NUMBER)
1.182 +volatile far BDT ep1Bo; //Endpoint #1 BD Out
1.183 +volatile far BDT ep1Bi; //Endpoint #1 BD In
1.184 +#endif
1.185 +
1.186 +#if(2 <= MAX_EP_NUMBER)
1.187 +volatile far BDT ep2Bo; //Endpoint #2 BD Out
1.188 +volatile far BDT ep2Bi; //Endpoint #2 BD In
1.189 +#endif
1.190 +
1.191 +#if(3 <= MAX_EP_NUMBER)
1.192 +volatile far BDT ep3Bo; //Endpoint #3 BD Out
1.193 +volatile far BDT ep3Bi; //Endpoint #3 BD In
1.194 +#endif
1.195 +
1.196 +#if(4 <= MAX_EP_NUMBER)
1.197 +volatile far BDT ep4Bo; //Endpoint #4 BD Out
1.198 +volatile far BDT ep4Bi; //Endpoint #4 BD In
1.199 +#endif
1.200 +
1.201 +#if(5 <= MAX_EP_NUMBER)
1.202 +volatile far BDT ep5Bo; //Endpoint #5 BD Out
1.203 +volatile far BDT ep5Bi; //Endpoint #5 BD In
1.204 +#endif
1.205 +
1.206 +#if(6 <= MAX_EP_NUMBER)
1.207 +volatile far BDT ep6Bo; //Endpoint #6 BD Out
1.208 +volatile far BDT ep6Bi; //Endpoint #6 BD In
1.209 +#endif
1.210 +
1.211 +#if(7 <= MAX_EP_NUMBER)
1.212 +volatile far BDT ep7Bo; //Endpoint #7 BD Out
1.213 +volatile far BDT ep7Bi; //Endpoint #7 BD In
1.214 +#endif
1.215 +
1.216 +#if(8 <= MAX_EP_NUMBER)
1.217 +volatile far BDT ep8Bo; //Endpoint #8 BD Out
1.218 +volatile far BDT ep8Bi; //Endpoint #8 BD In
1.219 +#endif
1.220 +
1.221 +#if(9 <= MAX_EP_NUMBER)
1.222 +volatile far BDT ep9Bo; //Endpoint #9 BD Out
1.223 +volatile far BDT ep9Bi; //Endpoint #9 BD In
1.224 +#endif
1.225 +
1.226 +#if(10 <= MAX_EP_NUMBER)
1.227 +volatile far BDT ep10Bo; //Endpoint #10 BD Out
1.228 +volatile far BDT ep10Bi; //Endpoint #10 BD In
1.229 +#endif
1.230 +
1.231 +#if(11 <= MAX_EP_NUMBER)
1.232 +volatile far BDT ep11Bo; //Endpoint #11 BD Out
1.233 +volatile far BDT ep11Bi; //Endpoint #11 BD In
1.234 +#endif
1.235 +
1.236 +#if(12 <= MAX_EP_NUMBER)
1.237 +volatile far BDT ep12Bo; //Endpoint #12 BD Out
1.238 +volatile far BDT ep12Bi; //Endpoint #12 BD In
1.239 +#endif
1.240 +
1.241 +#if(13 <= MAX_EP_NUMBER)
1.242 +volatile far BDT ep13Bo; //Endpoint #13 BD Out
1.243 +volatile far BDT ep13Bi; //Endpoint #13 BD In
1.244 +#endif
1.245 +
1.246 +#if(14 <= MAX_EP_NUMBER)
1.247 +volatile far BDT ep14Bo; //Endpoint #14 BD Out
1.248 +volatile far BDT ep14Bi; //Endpoint #14 BD In
1.249 +#endif
1.250 +
1.251 +#if(15 <= MAX_EP_NUMBER)
1.252 +volatile far BDT ep15Bo; //Endpoint #15 BD Out
1.253 +volatile far BDT ep15Bi; //Endpoint #15 BD In
1.254 +#endif
1.255 +
1.256 +/******************************************************************************
1.257 + * Section B: EP0 Buffer Space
1.258 + ******************************************************************************
1.259 + * - Two buffer areas are defined:
1.260 + *
1.261 + * A. CTRL_TRF_SETUP
1.262 + * - Size = EP0_BUFF_SIZE as defined in autofiles\usbcfg.h
1.263 + * - Detailed data structure allows direct adddressing of bits and bytes.
1.264 + *
1.265 + * B. CTRL_TRF_DATA
1.266 + * - Size = EP0_BUFF_SIZE as defined in autofiles\usbcfg.h
1.267 + * - Data structure allows direct adddressing of the first 8 bytes.
1.268 + *
1.269 + * - Both data types are defined in system\usb\usbdefs\usbdefs_ep0_buff.h
1.270 + *****************************************************************************/
1.271 +volatile far CTRL_TRF_SETUP SetupPkt;
1.272 +volatile far CTRL_TRF_DATA CtrlTrfData;
1.273 +
1.274 +/******************************************************************************
1.275 + * Section C: CDC Buffer
1.276 + ******************************************************************************
1.277 + *
1.278 + *****************************************************************************/
1.279 +#pragma udata usbram5a=0x500 //See Linker Script,usb5:0x500-...
1.280 +#if defined(USB_USE_CDC)
1.281 +volatile far unsigned char cdc_notice[CDC_INT_EP_SIZE];
1.282 +volatile far unsigned char cdc_data_rx[CDC_BULK_OUT_EP_SIZE];
1.283 +volatile far unsigned char cdc_data_tx[CDC_BULK_IN_EP_SIZE];
1.284 +#endif
1.285 +#pragma udata
1.286 +
1.287 +/** EOF usbmmap.c ************************************************************/