1 /*********************************************************************
3 * Microchip USB C18 Firmware Version 1.0
5 *********************************************************************
7 * Dependencies: See INCLUDES section below
9 * Compiler: C18 2.30.01+
10 * Company: Microchip Technology, Inc.
12 * Software License Agreement
14 * The software supplied herewith by Microchip Technology Incorporated
15 * (the “Company”) for its PICmicro® Microcontroller is intended and
16 * supplied to you, the Company’s customer, for use solely and
17 * exclusively on Microchip PICmicro Microcontroller products. The
18 * software is owned by the Company and/or its supplier, and is
19 * protected under applicable copyright laws. All rights are reserved.
20 * Any use in violation of the foregoing restrictions may subject the
21 * user to criminal sanctions under applicable laws, as well as to
22 * civil liability for the breach of the terms and conditions of this
25 * THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
26 * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
27 * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
28 * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
29 * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
30 * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
33 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34 * Rawin Rojvanit 11/19/04 Original.
35 ********************************************************************/
37 /******************************************************************************
40 * This file is the USB memory manager; it serves as a compile-time memory
41 * allocator for the USB endpoints. It uses the compile time options passed
42 * from usbcfg.h to instantiate endpoints and endpoint buffer.
44 * Each endpoint requires to have a set of Buffer Descriptor registers(BDT).
45 * A BDT is 4-byte long and has a specific RAM location for each endpoint.
46 * The BDT for endpoint 0 out is located at address 0x400 to 0x403.
47 * The BDT for endpoint 0 in is located at address 0x404 to 0x407.
48 * The BDT for endpoint 1 out is located at address 0x408 to 0x40B.
49 * and so on... The above allocation assumes the Ping-Pong Buffer Mode 0 is
50 * used. These locations are already hard-wired in the silicon. The point
51 * of doing instantiation, i.e. volatile far BDT ep0Bo;, is to provide the
52 * C compiler a way to address each variable directly. This is very important
53 * because when a register can be accessed directly, it saves execution time
54 * and reduces program size.
56 * Endpoints are defined using the endpoint number and the direction
57 * of transfer. For simplicity, usbmmap.c only uses the endpoint number
58 * in the BDT register allocation scheme. This means if the usbcfg.h states
59 * that the MAX_EP_NUMBER is number 1, then four BDTs will be
60 * instantiated: one each for endpoint0 in and endpoint0 out, which must
61 * always be instantiated for control transfer by default, and one each sets
62 * for endpoint1 in and endpoint1 out. The naming convention for instantiating
67 * where # is the endpoint number, and d is the direction of
68 * transfer, which could be either <i> or <o>.
70 * The USB memory manager uses MAX_EP_NUMBER, as defined in usbcfg.h, to define
71 * the endpoints to be instantiated. This represents the highest endpoint
72 * number to be allocated, not how many endpoints are used. Since the BDTs for
73 * endpoints have hardware-assigned addresses in Bank 4, setting this value too
74 * high may lead to inefficient use of data RAM. For example, if an application
75 * uses only endpoints EP0 and EP4, then the MAX_EP_NUMBER is 4, and not 2.
76 * The in-between endpoint BDTs in this example (EP1, EP2, and EP3) go unused,
77 * and the 24 bytes of memory associated with them are wasted. It does not make
78 * much sense to skip endpoints, but the final decision lies with the user.
80 * The next step is to assign the instantiated BDTs to different
81 * USB functions. The firmware framework fundamentally assumes that every USB
82 * function should know which endpoint it is using, i.e., the default control
83 * transfer should know that it is using endpoint 0 in and endpoint 0 out.
84 * A HID class can choose which endpoint it wants to use, but once chosen, it
85 * should always know the number of the endpoint.
87 * The assignment of endpoints to USB functions is managed centrally
88 * in usbcfg.h. This helps prevent the mistake of having more
89 * than one USB function using the same endpoint. The "Endpoint Allocation"
90 * section in usbcfg.h provides examples for how to map USB endpoints to USB
92 * Quite a few things can be mapped in that section. There is no
93 * one correct way to do the mapping and the user has the choice to
94 * choose a method that is most suitable to the application.
96 * Typically, however, a user will want to map the following for a given
97 * USB interface function:
98 * 1. The USB interface ID
99 * 2. The endpoint control registers (UEPn)
100 * 3. The BDT registers (ep<#>B<d>)
101 * 4. The endpoint size
103 * Example: Assume a USB device class "foo", which uses one out endpoint
104 * of size 64-byte and one in endpoint of size 64-byte, then:
106 * #define FOO_INTF_ID 0x00
107 * #define FOO_UEP UEP1
108 * #define FOO_BD_OUT ep1Bo
109 * #define FOO_BD_IN ep1Bi
110 * #define FOO_EP_SIZE 64
112 * The mapping above has chosen class "foo" to use endpoint 1.
113 * The names are arbitrary and can be anything other than FOO_??????.
114 * For abstraction, the code for class "foo" should use the abstract
115 * definitions of FOO_BD_OUT,FOO_BD_IN, and not ep1Bo or ep1Bi.
117 * Note that the endpoint size defined in the usbcfg.h file is again
118 * used in the usbmmap.c file. This shows that the relationship between
119 * the two files are tightly related.
121 * The endpoint buffer for each USB function must be located in the
122 * dual-port RAM area and has to come after all the BDTs have been
123 * instantiated. An example declaration is:
124 * volatile far unsigned char[FOO_EP_SIZE] data;
126 * The 'volatile' keyword tells the compiler not to perform any code
127 * optimization on this variable because its content could be modified
128 * by the hardware. The 'far' keyword tells the compiler that this variable
129 * is not located in the Access RAM area (0x000 - 0x05F).
131 * For the variable to be globally accessible by other files, it should be
132 * declared in the header file usbmmap.h as an extern definition, such as
133 * extern volatile far unsigned char[FOO_EP_SIZE] data;
136 * In a short summary, the dependencies between usbcfg and usbmmap can
139 * usbcfg[MAX_EP_NUMBER] -> usbmmap
140 * usbmmap[ep<#>B<d>] -> usbcfg
141 * usbcfg[EP size] -> usbmmap
142 * usbcfg[abstract ep definitions] -> usb9/hid/cdc/etc class code
143 * usbmmap[endpoint buffer variable] -> usb9/hid/cdc/etc class code
145 * Data mapping provides a means for direct addressing of BDT and endpoint
146 * buffer. This means less usage of pointers, which equates to a faster and
147 * smaller program code.
149 *****************************************************************************/
151 /** I N C L U D E S **********************************************************/
152 #include "typedefs.h"
155 /** U S B G L O B A L V A R I A B L E S ************************************/
157 byte usb_device_state; // Device States: DETACHED, ATTACHED, ...
158 USB_DEVICE_STATUS usb_stat; // Global USB flags
159 byte usb_active_cfg; // Value of current configuration
160 byte usb_alt_intf[MAX_NUM_INT]; // Array to keep track of the current alternate
161 // setting for each interface ID
163 /** 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 *********************/
164 #pragma udata usbram4=0x400 //See Linker Script,usb4:0x400-0x4FF(256-byte)
166 /******************************************************************************
167 * Section A: Buffer Descriptor Table
168 * - 0x400 - 0x4FF(max)
169 * - MAX_EP_NUMBER is defined in autofiles\usbcfg.h
170 * - BDT data type is defined in system\usb\usbmmap.h
171 *****************************************************************************/
173 #if(0 <= MAX_EP_NUMBER)
174 volatile far BDT ep0Bo; //Endpoint #0 BD Out
175 volatile far BDT ep0Bi; //Endpoint #0 BD In
178 #if(1 <= MAX_EP_NUMBER)
179 volatile far BDT ep1Bo; //Endpoint #1 BD Out
180 volatile far BDT ep1Bi; //Endpoint #1 BD In
183 #if(2 <= MAX_EP_NUMBER)
184 volatile far BDT ep2Bo; //Endpoint #2 BD Out
185 volatile far BDT ep2Bi; //Endpoint #2 BD In
188 #if(3 <= MAX_EP_NUMBER)
189 volatile far BDT ep3Bo; //Endpoint #3 BD Out
190 volatile far BDT ep3Bi; //Endpoint #3 BD In
193 #if(4 <= MAX_EP_NUMBER)
194 volatile far BDT ep4Bo; //Endpoint #4 BD Out
195 volatile far BDT ep4Bi; //Endpoint #4 BD In
198 #if(5 <= MAX_EP_NUMBER)
199 volatile far BDT ep5Bo; //Endpoint #5 BD Out
200 volatile far BDT ep5Bi; //Endpoint #5 BD In
203 #if(6 <= MAX_EP_NUMBER)
204 volatile far BDT ep6Bo; //Endpoint #6 BD Out
205 volatile far BDT ep6Bi; //Endpoint #6 BD In
208 #if(7 <= MAX_EP_NUMBER)
209 volatile far BDT ep7Bo; //Endpoint #7 BD Out
210 volatile far BDT ep7Bi; //Endpoint #7 BD In
213 #if(8 <= MAX_EP_NUMBER)
214 volatile far BDT ep8Bo; //Endpoint #8 BD Out
215 volatile far BDT ep8Bi; //Endpoint #8 BD In
218 #if(9 <= MAX_EP_NUMBER)
219 volatile far BDT ep9Bo; //Endpoint #9 BD Out
220 volatile far BDT ep9Bi; //Endpoint #9 BD In
223 #if(10 <= MAX_EP_NUMBER)
224 volatile far BDT ep10Bo; //Endpoint #10 BD Out
225 volatile far BDT ep10Bi; //Endpoint #10 BD In
228 #if(11 <= MAX_EP_NUMBER)
229 volatile far BDT ep11Bo; //Endpoint #11 BD Out
230 volatile far BDT ep11Bi; //Endpoint #11 BD In
233 #if(12 <= MAX_EP_NUMBER)
234 volatile far BDT ep12Bo; //Endpoint #12 BD Out
235 volatile far BDT ep12Bi; //Endpoint #12 BD In
238 #if(13 <= MAX_EP_NUMBER)
239 volatile far BDT ep13Bo; //Endpoint #13 BD Out
240 volatile far BDT ep13Bi; //Endpoint #13 BD In
243 #if(14 <= MAX_EP_NUMBER)
244 volatile far BDT ep14Bo; //Endpoint #14 BD Out
245 volatile far BDT ep14Bi; //Endpoint #14 BD In
248 #if(15 <= MAX_EP_NUMBER)
249 volatile far BDT ep15Bo; //Endpoint #15 BD Out
250 volatile far BDT ep15Bi; //Endpoint #15 BD In
253 /******************************************************************************
254 * Section B: EP0 Buffer Space
255 ******************************************************************************
256 * - Two buffer areas are defined:
259 * - Size = EP0_BUFF_SIZE as defined in autofiles\usbcfg.h
260 * - Detailed data structure allows direct adddressing of bits and bytes.
263 * - Size = EP0_BUFF_SIZE as defined in autofiles\usbcfg.h
264 * - Data structure allows direct adddressing of the first 8 bytes.
266 * - Both data types are defined in system\usb\usbdefs\usbdefs_ep0_buff.h
267 *****************************************************************************/
268 volatile far CTRL_TRF_SETUP SetupPkt;
269 volatile far CTRL_TRF_DATA CtrlTrfData;
271 /******************************************************************************
272 * Section C: CDC Buffer
273 ******************************************************************************
275 *****************************************************************************/
276 #pragma udata usbram5a=0x500 //See Linker Script,usb5:0x500-...
277 #if defined(USB_USE_CDC)
278 volatile far unsigned char cdc_notice[CDC_INT_EP_SIZE];
279 volatile far unsigned char cdc_data_rx[CDC_BULK_OUT_EP_SIZE];
280 volatile far unsigned char cdc_data_tx[CDC_BULK_IN_EP_SIZE];
284 /** EOF usbmmap.c ************************************************************/