CompileTimeTokens.txt 14.9 KB
 Dean Camera committed Feb 23, 2009 1 2 3 4 5 6 /** \file * * This file contains special DoxyGen information for the generation of the main page and other special * documentation pages. It is not a project source file. */  Dean Camera committed Jun 15, 2009 7 /** \page Page_TokenSummary Summary of Compile Tokens  Dean Camera committed Feb 23, 2009 8 9 10 11 12  * * The following lists all the possible tokens which can be defined in a project makefile, and passed to the * compiler via the -D switch, to alter the LUFA library code. These tokens may alter the library behaviour, * or remove features unused by a given application in order to save flash space. *  Dean Camera committed Mar 29, 2009 13  *  Dean Camera committed Feb 23, 2009 14 15 16  * \section Sec_SummaryNonUSBTokens Non USB Related Tokens * This section describes compile tokens which affect non-USB sections of the LUFA library. *  Dean Camera committed Apr 17, 2009 17  * DISABLE_TERMINAL_CODES - ( \ref Group_Terminal ) \n  Dean Camera committed Feb 23, 2009 18 19 20 21 22 23 24 25  * If an application contains ANSI terminal control codes listed in TerminalCodes.h, it might be desired to remove them * at compile time for use with a terminal which is non-ANSI control code aware, without modifying the source code. If * this token is defined, all ANSI control codes in the application code from the TerminalCodes.h header are removed from * the source code at compile time. * * \section Sec_SummaryUSBClassTokens USB Class Driver Related Tokens * This section describes compile tokens which affect USB class-specific drivers in the LUFA library. *  Dean Camera committed Sep 21, 2009 26  * HID_STATETABLE_STACK_DEPTH=x - ( \ref Group_HIDParser ) \n  Dean Camera committed Feb 23, 2009 27 28  * HID reports may contain PUSH and POP elements, to store and retrieve the current HID state table onto a stack. This * allows for reports to save the state table before modifying it slightly for a data item, and then restore the previous  Dean Camera committed May 15, 2009 29  * state table in a compact manner. This token may be defined to a non-zero 8-bit value to give the maximum depth of the state  Dean Camera committed Feb 23, 2009 30 31  * table stack. If not defined, this defaults to the value indicated in the HID.h file documentation. *  Dean Camera committed Sep 21, 2009 32  * HID_USAGE_STACK_DEPTH=x - ( \ref Group_HIDParser ) \n  Dean Camera committed Feb 23, 2009 33 34  * HID reports generally contain many USAGE elements, which are assigned to INPUT, OUTPUT and FEATURE items in succession * when multiple items are defined at once (via REPORT COUNT elements). This allows for several items to be defined with  Dean Camera committed May 15, 2009 35  * different usages in a compact manner. This token may be defined to a non-zero 8-bit value to set the maximum depth of the  Dean Camera committed Apr 19, 2009 36  * usage stack, indicating the maximum number of USAGE items which can be stored temporarily until the next INPUT, OUTPUT  Dean Camera committed Feb 23, 2009 37 38  * and FEATURE item. If not defined, this defaults to the value indicated in the HID.h file documentation. *  Dean Camera committed Sep 21, 2009 39  * HID_MAX_COLLECTIONS=x - ( \ref Group_HIDParser ) \n  Dean Camera committed Feb 23, 2009 40  * HID reports generally contain several COLLECTION elements, used to group related data items together. Collection information  Dean Camera committed Apr 19, 2009 41  * is stored separately in the processed usage structure (and referred to by the data elements in the structure) to save space.  Dean Camera committed May 15, 2009 42  * This token may be defined to a non-zero 8-bit value to set the maximum number of COLLECTION items which can be processed by the  Dean Camera committed Feb 23, 2009 43 44 45  * parser into the resultant processed report structure. If not defined, this defaults to the value indicated in the HID.h file * documentation. *  Dean Camera committed Sep 21, 2009 46  * HID_MAX_REPORTITEMS=x - ( \ref Group_HIDParser ) \n  Dean Camera committed Feb 23, 2009 47 48  * All HID reports contain one or more INPUT, OUTPUT and/or FEATURE items describing the data which can be sent to and from the HID * device. Each item has associated usages, bit offsets in the item reports and other associated data indicating the manner in which  Dean Camera committed May 15, 2009 49  * the report data should be interpreted by the host. This token may be defined to a non-zero 8-bit value to set the maximum number of  Dean Camera committed Apr 19, 2009 50 51  * data elements which can be stored in the processed HID report structure, including INPUT, OUTPUT and (if enabled) FEATURE items. * If a item has a multiple count (i.e. a REPORT COUNT of more than 1), each item in the report count is placed separately in the  Dean Camera committed Feb 23, 2009 52 53  * processed HID report table. If not defined, this defaults to the value indicated in the HID.h file documentation. *  Dean Camera committed Sep 21, 2009 54  * HID_MAX_REPORT_IDS=x - ( \ref Group_HIDParser ) \n  Dean Camera committed Sep 09, 2009 55 56 57 58 59 60  * HID reports may contain several report IDs, to logically distinguish grouped device data from one another - for example, a combination * keyboard and mouse might use report IDs to seperate the keyboard reports from the mouse reports. In order to determine the size of each * report, and thus know how many bytes must be read or written, the size of each report (IN, OUT and FEATURE) must be calculated and * stored. This token may be defined to a non-zero 8-bit value to set the maximum number of report IDs in a device which can be processed * and their sizes calculated/stored into the resultant processed report structure. If not defined, this defaults to the value indicated in * the HID.h file documentation.  Dean Camera committed Mar 29, 2009 61  *  Dean Camera committed Feb 23, 2009 62 63 64  * \section Sec_SummaryUSBTokens USB Driver Related Tokens * This section describes compile tokens which affect USB driver stack as a whole in the LUFA library. *  Dean Camera committed Apr 17, 2009 65  * USE_RAM_DESCRIPTORS - ( \ref Group_Descriptors ) \n  Dean Camera committed Jul 16, 2009 66 67 68 69 70  * Define this token to indicate to the USB driver that all device descriptors are stored in RAM, rather than being located in any one * of the AVR's memory spaces. RAM descriptors may be desirable in applications where the descriptors need to be modified at runtime. * * USE_FLASH_DESCRIPTORS - ( \ref Group_Descriptors ) \n * Similar to USE_RAM_DESCRIPTORS, but all descriptors are stored in the AVR's FLASH memory rather than RAM.  Dean Camera committed Feb 23, 2009 71  *  Dean Camera committed Apr 17, 2009 72  * USE_EEPROM_DESCRIPTORS - ( \ref Group_Descriptors ) \n  Dean Camera committed Jul 16, 2009 73  * Similar to USE_RAM_DESCRIPTORS, but all descriptors are stored in the AVR's EEPROM memory rather than RAM.  Dean Camera committed Feb 23, 2009 74  *  Dean Camera committed Jun 21, 2009 75  * NO_INTERNAL_SERIAL - ( \ref Group_Descriptors ) \n  Dean Camera committed Jun 20, 2009 76 77  * Some AVR models contain a unique 20-digit serial number which can be used as the device serial number, while in device mode. This * allows the host to uniquely identify the device regardless of if it is moved between USB ports on the same computer, allowing  Dean Camera committed Jun 21, 2009 78 79  * allocated resources (such as drivers, COM Port number allocations) to be preserved. This is not needed in many apps, and so the * code that performs this task can be disabled by defining this option and passing it to the compiler via the -D switch.  Dean Camera committed Jun 20, 2009 80  *  Dean Camera committed Sep 21, 2009 81  * FIXED_CONTROL_ENDPOINT_SIZE=x - ( \ref Group_EndpointManagement ) \n  Dean Camera committed Feb 23, 2009 82 83 84 85  * By default, the library determines the size of the control endpoint (when in device mode) by reading the device descriptor. * Normally this reduces the amount of configuration required for the library, allows the value to change dynamically (if * descriptors are stored in EEPROM or RAM rather than flash memory) and reduces code maintenance. However, this token can be * defined to a non-zero value instead to give the size in bytes of the control endpoint, to reduce the size of the compiled  Dean Camera committed Apr 24, 2009 86  * binary.  Dean Camera committed Feb 23, 2009 87  *  Dean Camera committed Jul 28, 2009 88  * DEVICE_STATE_AS_GPIOR - ( \ref Group_Device ) \n  Dean Camera committed Jul 28, 2009 89 90  * One of the most frequenty used global variables in the stack is the USB_DeviceState global, which indicates the current state of * the Device State Machine. To reduce the amount of code and time required to access and modify this global in an application, this token  Dean Camera committed Jul 28, 2009 91 92 93  * may be defined to a value between 0 and 2 to fix the state variable into one of the three general purpose IO registers inside the AVR * reserved for application use. When defined, the corresponding GPIOR register should not be used within the user application except * implicitly via the library APIs.  Dean Camera committed Jul 28, 2009 94  *  Dean Camera committed Jul 28, 2009 95  * HOST_STATE_AS_GPIOR - ( \ref Group_Host ) \n  Dean Camera committed Jul 28, 2009 96 97  * One of the most frequenty used global variables in the stack is the USB_HostState global, which indicates the current state of * the Host State Machine. To reduce the amount of code and time required to access and modify this global in an application, this token  Dean Camera committed Jul 28, 2009 98 99 100  * may be defined to a value between 0 and 2 to fix the state variable into one of the three general purpose IO registers inside the AVR * reserved for application use. When defined, the corresponding GPIOR register should not be used within the user application except * implicitly via the library APIs.  Dean Camera committed Jul 28, 2009 101  *  Dean Camera committed Sep 21, 2009 102  * FIXED_NUM_CONFIGURATIONS=x - ( \ref Group_Device ) \n  Dean Camera committed Feb 23, 2009 103 104  * By default, the library determines the number of configurations a USB device supports by reading the device descriptor. This reduces * the amount of configuration required to set up the library, and allows the value to change dynamically (if descriptors are stored in  Dean Camera committed Jul 16, 2009 105 106  * EEPROM or RAM rather than flash memory) and reduces code maintenance. However, this value may be fixed via this token in the project * makefile to reduce the compiled size of the binary at the expense of flexibility.  Dean Camera committed Feb 23, 2009 107  *  Dean Camera committed Apr 23, 2009 108 109 110 111  * CONTROL_ONLY_DEVICE \n * In some limited USB device applications, there are no device endpoints other than the control endpoint; i.e. all device communication * is through control endpoint requests. Defining this token will remove several features related to the selection and control of device * endpoints internally, saving space. Generally, this is usually only useful in (some) bootloaders and is best avoided.  Dean Camera committed Feb 23, 2009 112  *  Dean Camera committed Apr 17, 2009 113  * NO_STREAM_CALLBACKS - ( \ref Group_EndpointPacketManagement , \ref Group_PipePacketManagement )\n  Dean Camera committed Feb 23, 2009 114 115 116 117 118 119 120  * Both the endpoint and the pipe driver code contains stream functions, allowing for arrays of data to be sent to or from the * host easily via a single function call (rather than complex routines worrying about sending full packets, waiting for the endpoint/ * pipe to become ready, etc.). By default, these stream functions require a callback function which is executed after each byte processed, * allowing for early-aborts of stream transfers by the application. If callbacks are not required in an application, they can be removed * by defining this token, reducing the compiled binary size. When removed, the stream functions no longer accept a callback function as * a parameter. *  Dean Camera committed Jul 13, 2009 121 122 123 124 125 126 127  * FAST_STREAM_TRANSFERS - ( \ref Group_EndpointPacketManagement , \ref Group_PipePacketManagement )\n * By default, streams are transferred internally via a loop, sending or receiving one byte per iteration before checking for a bank full * or empty condition. This allows for multiple stream functions to be chained together easily, as there are no alignment issues. However, * this can lead to heavy performance penalties in applications where large streams are used frequently. When this compile time option is * used, bytes are sent or recevied in groups of 8 bytes at a time increasing performance at the expense of a larger flash memory consumption * due to the extra code required to deal with byte alignment. *  Dean Camera committed Sep 21, 2009 128  * USB_HOST_TIMEOUT_MS=x - ( \ref Group_Host ) \n  Dean Camera committed Feb 23, 2009 129  * When a control transfer is initiated in host mode to an attached device, a timeout is used to abort the transfer if the attached  Dean Camera committed May 15, 2009 130  * device fails to respond within the timeout period. This token may be defined to a non-zero 16-bit value to set the timeout period for  Dean Camera committed Feb 23, 2009 131 132  * control transfers, specified in milliseconds. If not defined, the default value specified in Host.h is used instead. *  Dean Camera committed Sep 21, 2009 133  * HOST_DEVICE_SETTLE_DELAY_MS=x - ( \ref Group_Host ) \n  Dean Camera committed Feb 23, 2009 134 135  * Some devices require a delay of up to 5 seconds after they are connected to VBUS before the enumeration process can be started, or * they will fail to enumerate correctly. By placing a delay before the enumeration process, it can be ensured that the bus has settled  Dean Camera committed Jul 13, 2009 136 137  * back to a known idle state before communications occur with the device. This token may be defined to a 16-bit value to set the device * settle period, specified in milliseconds. If not defined, the default value specified in Host.h is used instead.  Dean Camera committed Feb 23, 2009 138  *  Dean Camera committed Sep 21, 2009 139  * USE_STATIC_OPTIONS=x - ( \ref Group_USBManagement ) \n  Dean Camera committed Feb 23, 2009 140 141 142 143 144 145  * By default, the USB_Init() function accepts dynamic options at runtime to alter the library behaviour, including whether the USB pad * voltage regulator is enabled, and the device speed when in device mode. By defining this token to a mask comprised of the USB options * mask defines usually passed as the Options parameter to USB_Init(), the resulting compiled binary can be decreased in size by removing * the dynamic options code, and replacing it with the statically set options. When defined, the USB_Init() function no longer accepts an * Options parameter. *  Dean Camera committed Apr 17, 2009 146  * USB_DEVICE_ONLY - ( \ref Group_USBManagement ) \n  Dean Camera committed Feb 23, 2009 147 148  * For the USB AVR models supporting both device and host USB modes, the USB_Init() function contains a Mode parameter which specifies the * mode the library should be initialized to. If only device mode is required, the code for USB host mode can be removed from the binary to  Dean Camera committed Apr 19, 2009 149  * save space. When defined, the USB_Init() function no longer accepts a Mode parameter. This define is irrelevant on smaller USB AVRs which  Dean Camera committed Feb 23, 2009 150 151  * do not support host mode. *  Dean Camera committed Apr 17, 2009 152  * USB_HOST_ONLY - ( \ref Group_USBManagement ) \n  Dean Camera committed Feb 23, 2009 153 154  * Same as USB_DEVICE_ONLY, except the library is fixed to USB host mode rather than USB device mode. Not available on some USB AVR models. *  Dean Camera committed Sep 21, 2009 155  * USB_STREAM_TIMEOUT_MS=x - ( \ref Group_USBManagement ) \n  Dean Camera committed Feb 23, 2009 156  * When endpoint and/or pipe stream functions are used, by default there is a timeout between each transfer which the connected device or host  Dean Camera committed May 15, 2009 157  * must satisfy, or the stream function aborts the remaining data transfer. This token may be defined to a non-zero 16-bit value to set the timeout  Dean Camera committed Feb 23, 2009 158 159  * period for stream transfers, specified in milliseconds. If not defined, the default value specified in LowLevel.h is used instead. *  Dean Camera committed Apr 17, 2009 160  * NO_LIMITED_CONTROLLER_CONNECT - ( \ref Group_Events ) \n  Dean Camera committed Feb 23, 2009 161 162 163  * On the smaller USB AVRs, the USB controller lacks VBUS events to determine the physical connection state of the USB bus to a host. In lieu of * VBUS events, the library attempts to determine the connection state via the bus suspension and wake up events instead. This however may be * slightly inaccurate due to the possibility of the host suspending the bus while the device is still connected. If accurate connection status is  164  * required, the VBUS line of the USB connector should be routed to an AVR pin to detect its level, so that the USB_DeviceState global  Dean Camera committed Aug 05, 2009 165 166  * can be accurately set and the \ref EVENT_USB_Device_Connect() and \ref EVENT_USB_Device_Disconnect() events manually raised by the RAISE_EVENT macro. * When defined, this token disables the library's auto-detection of the connection state by the aforementioned suspension and wake up events.  Dean Camera committed May 14, 2009 167 168 169 170 171  * * INTERRUPT_CONTROL_ENDPOINT - ( \ref Group_USBManagement ) \n * Some applications prefer to not call the USB_USBTask() management task reguarly while in device mode, as it can complicate code significantly. * Instead, when device mode is used this token can be passed to the library via the -D switch to allow the library to manage the USB control * endpoint entirely via interrupts asynchronously to the user application.  Dean Camera committed Feb 23, 2009 172  */