CompileTimeTokens.txt 18.1 KB
 Dean Camera committed May 08, 2010 1 2 3 4 5 6 7 8 9 /** \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. */ /** \page Page_TokenSummary Summary of Compile Tokens * * The following lists all the possible tokens which can be defined in a project makefile, and passed to the  Dean Camera committed Jul 30, 2010 10  * compiler via the -D switch, to alter the LUFA library code. These tokens may alter the library behaviour,  Dean Camera committed May 08, 2010 11 12  * or remove features unused by a given application in order to save flash space. *  Dean Camera committed May 14, 2011 13 14 15  * \note If the \c USE_LUFA_CONFIG_HEADER token is defined, the library will include a header file named \c LUFAConfig.h located * in the user directory where the below compile time tokens may be defined. This allows for an alternative to makefile * defined tokens for configuring the library.  Dean Camera committed May 08, 2010 16 17 18 19  * * \section Sec_SummaryNonUSBTokens Non USB Related Tokens * This section describes compile tokens which affect non-USB sections of the LUFA library. *  Dean Camera committed Feb 26, 2011 20  * DISABLE_TERMINAL_CODES - (\ref Group_Terminal) - All Architectures \n  Dean Camera committed May 08, 2010 21 22 23 24 25 26 27 28 29  * 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 Feb 26, 2011 30  * HID_HOST_BOOT_PROTOCOL_ONLY - (\ref Group_USBClassHIDHost) - All Architectures \n  Dean Camera committed May 08, 2010 31 32 33  * By default, the USB HID Host class driver is designed to work with HID devices using either the Boot or Report HID * communication protocols. On devices where the Report protocol is not used (i.e. in applications where only basic * Mouse or Keyboard operation is desired, using boot compatible devices), the code responsible for the Report protocol  Dean Camera committed Jun 16, 2010 34  * mode can be removed to save space in the compiled application by defining this token. When defined, it is still necessary  Dean Camera committed May 08, 2010 35  * to explicitly put the attached device into Boot protocol mode via a call to \ref HID_Host_SetBootProtocol().  36  *  Dean Camera committed Feb 26, 2011 37 38  * HID_STATETABLE_STACK_DEPTH=x - (\ref Group_HIDParser) - All Architectures \n * Supported Architectures: All \n  Dean Camera committed May 08, 2010 39 40 41 42 43  * 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 * 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 * table stack. If not defined, this defaults to the value indicated in the HID.h file documentation. *  Dean Camera committed Feb 26, 2011 44  * HID_USAGE_STACK_DEPTH=x - (\ref Group_HIDParser) - All Architectures \n  Dean Camera committed May 08, 2010 45 46 47 48 49 50  * 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 * 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 * usage stack, indicating the maximum number of USAGE items which can be stored temporarily until the next INPUT, OUTPUT * and FEATURE item. If not defined, this defaults to the value indicated in the HID.h file documentation. *  Dean Camera committed Feb 26, 2011 51  * HID_MAX_COLLECTIONS=x - (\ref Group_HIDParser) - All Architectures \n  Dean Camera committed May 08, 2010 52 53 54 55 56 57  * HID reports generally contain several COLLECTION elements, used to group related data items together. Collection information * is stored separately in the processed usage structure (and referred to by the data elements in the structure) to save space. * 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 * 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 Feb 26, 2011 58  * HID_MAX_REPORTITEMS=x - (\ref Group_HIDParser) - All Architectures \n  Dean Camera committed May 08, 2010 59 60 61 62 63 64 65  * 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 * 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 * 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 * processed HID report table. If not defined, this defaults to the value indicated in the HID.h file documentation. *  Dean Camera committed Feb 26, 2011 66  * HID_MAX_REPORT_IDS=x - (\ref Group_HIDParser) - All Architectures \n  Dean Camera committed May 08, 2010 67  * HID reports may contain several report IDs, to logically distinguish grouped device data from one another - for example, a combination  Dean Camera committed Jun 16, 2010 68  * keyboard and mouse might use report IDs to separate the keyboard reports from the mouse reports. In order to determine the size of each  Dean Camera committed May 08, 2010 69 70 71 72 73  * 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 Feb 26, 2011 74  * NO_CLASS_DRIVER_AUTOFLUSH - (\ref Group_USBClassDrivers) - All Architectures \n  Dean Camera committed Oct 27, 2010 75 76 77 78 79  * Many of the device and host mode class drivers automatically flush any data waiting to be written to an interface, when the corresponding * USB management task is executed. This is usually desirable to ensure that any queued data is sent as soon as possible once and new data is * constructed in the main program loop. However, if flushing is to be controlled manually by the user application via the *_Flush() commands, * the compile time token may be defined in the application's makefile to disable automatic flushing during calls to the class driver USB * management tasks.  Dean Camera committed May 08, 2010 80 81 82 83  * * \section Sec_SummaryUSBTokens General USB Driver Related Tokens * This section describes compile tokens which affect USB driver stack as a whole in the LUFA library. *  Dean Camera committed Jul 19, 2011 84  * ORDERED_EP_CONFIG - (\ref Group_EndpointManagement , \ref Group_PipeManagement) - AVR8, UC3 \n  Dean Camera committed Dec 24, 2010 85  * The USB AVRs do not allow for Endpoints and Pipes to be configured out of order; they must be configured in an ascending order to  Dean Camera committed Jun 01, 2011 86  * prevent data corruption issues. However, by default LUFA employs a workaround to allow for unordered Endpoint/Pipe initialization. This compile  Dean Camera committed Jun 08, 2011 87 88 89  * time token may be used to restrict the initialization order to ascending indexes only in exchange for a smaller compiled binary size. Use * caution when applied to applications using the library USB Class drivers; the user application must ensure that all endpoints and pipes are * allocated sequentially.  Dean Camera committed Dec 24, 2010 90  *  Dean Camera committed Feb 26, 2011 91  * USE_STATIC_OPTIONS=x - (\ref Group_USBManagement) - All Architectures \n  Dean Camera committed Jul 30, 2010 92  * By default, the USB_Init() function accepts dynamic options at runtime to alter the library behaviour, including whether the USB pad  Dean Camera committed May 08, 2010 93 94 95 96 97  * 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 Feb 26, 2011 98  * USB_DEVICE_ONLY - (\ref Group_USBManagement) - All Architectures \n  Dean Camera committed May 08, 2010 99 100 101 102 103  * 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 * save space. When defined, the USB_Init() function no longer accepts a Mode parameter. This define is irrelevant on smaller USB AVRs which * do not support host mode. *  Dean Camera committed Feb 26, 2011 104  * USB_HOST_ONLY - (\ref Group_USBManagement) - All Architectures \n  Dean Camera committed May 08, 2010 105 106  * 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 Feb 26, 2011 107  * USB_STREAM_TIMEOUT_MS=x - (\ref Group_USBManagement) - All Architectures \n  Dean Camera committed May 08, 2010 108 109 110 111  * When endpoint and/or pipe stream functions are used, by default there is a timeout between each transfer which the connected device or host * 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 * period for stream transfers, specified in milliseconds. If not defined, the default value specified in LowLevel.h is used instead. *  Dean Camera committed Feb 26, 2011 112  * NO_LIMITED_CONTROLLER_CONNECT - (\ref Group_Events) - AVR8 Only \n  Dean Camera committed May 08, 2010 113 114 115 116 117 118 119  * 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 * 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 * 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 Jul 26, 2011 120  * NO_SOF_EVENTS - (\ref Group_Events) - All Architectures \n  Dean Camera committed Oct 07, 2010 121 122 123 124  * By default, there exists a LUFA application event for the start of each USB frame while the USB bus is not suspended in either host or device mode. * This event can be selectively enabled or disabled by calling the appropriate device or host mode function. When this compile time token is defined, * the ability to receive USB Start of Frame events via the \ref EVENT_USB_Device_StartOfFrame() or \ref EVENT_USB_Host_StartOfFrame() events is removed, * reducing the compiled program's binary size.  Dean Camera committed May 08, 2010 125 126 127 128  * * \section Sec_SummaryUSBDeviceTokens USB Device Mode Driver Related Tokens * This section describes compile tokens which affect USB driver stack of the LUFA library when used in Device mode. *  Dean Camera committed Feb 26, 2011 129  * USE_RAM_DESCRIPTORS - (\ref Group_StdDescriptors) - AVR8 Only \n  Dean Camera committed May 08, 2010 130 131 132  * 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. *  Dean Camera committed Feb 26, 2011 133  * USE_FLASH_DESCRIPTORS - (\ref Group_StdDescriptors) - AVR8 Only \n  Dean Camera committed May 08, 2010 134 135  * Similar to USE_RAM_DESCRIPTORS, but all descriptors are stored in the AVR's FLASH memory rather than RAM. *  Dean Camera committed Feb 26, 2011 136  * USE_EEPROM_DESCRIPTORS - (\ref Group_StdDescriptors) - AVR8 Only \n  Dean Camera committed May 08, 2010 137 138  * Similar to USE_RAM_DESCRIPTORS, but all descriptors are stored in the AVR's EEPROM memory rather than RAM. *  Dean Camera committed Feb 26, 2011 139 140 141 142 143  * NO_INTERNAL_SERIAL - (\ref Group_StdDescriptors) - All Architectures \n * Some AVR models contain a unique 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 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 May 08, 2010 144  *  Dean Camera committed Feb 26, 2011 145  * FIXED_CONTROL_ENDPOINT_SIZE=x - (\ref Group_EndpointManagement) - All Architectures \n  Dean Camera committed May 08, 2010 146 147 148 149 150 151  * 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 * binary. *  Dean Camera committed Feb 26, 2011 152  * DEVICE_STATE_AS_GPIOR - (\ref Group_Device) - AVR8 Only \n  Dean Camera committed Jun 16, 2010 153  * One of the most frequently used global variables in the stack is the USB_DeviceState global, which indicates the current state of  Dean Camera committed May 08, 2010 154 155 156 157 158  * the Device State Machine. To reduce the amount of code and time required to access and modify this global in an application, this token * 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 Feb 26, 2011 159  * FIXED_NUM_CONFIGURATIONS=x - (\ref Group_Device) - All Architectures \n  Dean Camera committed May 08, 2010 160 161 162 163 164  * 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 * 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 26, 2011 165  * CONTROL_ONLY_DEVICE - (\ref Group_Device) - All Architectures \n  Dean Camera committed May 08, 2010 166 167 168 169  * 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 Jul 26, 2011 170  * INTERRUPT_CONTROL_ENDPOINT - (\ref Group_USBManagement) - All Architectures \n  Dean Camera committed Jun 16, 2010 171  * Some applications prefer to not call the USB_USBTask() management task regularly while in device mode, as it can complicate code significantly.  Dean Camera committed May 08, 2010 172 173 174 175  * 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 USB controller interrupts asynchronously to the user application. When defined, USB_USBTask() does not need to be called * when in USB device mode. *  Dean Camera committed Feb 26, 2011 176  * NO_DEVICE_REMOTE_WAKEUP - (\ref Group_Device) - All Architectures \n  Dean Camera committed May 08, 2010 177 178 179  * Many devices do not require the use of the Remote Wakeup features of USB, used to wake up the USB host when suspended. On these devices, * the code required to manage device Remote Wakeup can be disabled by defining this token and passing it to the library via the -D switch. *  Dean Camera committed Feb 26, 2011 180  * NO_DEVICE_SELF_POWER - (\ref Group_Device) - All Architectures \n  Dean Camera committed May 08, 2010 181  * USB devices may be bus powered, self powered, or a combination of both. When a device can be both bus powered and self powered, the host may  Dean Camera committed Jul 08, 2011 182 183  * query the device to determine the current power source, via \ref USB_Device_CurrentlySelfPowered. For solely bus powered devices, this global * and the code required to manage it may be disabled by passing this token to the library via the -D switch.  Dean Camera committed May 08, 2010 184 185 186 187 188 189  * * * \section Sec_SummaryUSBHostTokens USB Host Mode Driver Related Tokens * * This section describes compile tokens which affect USB driver stack of the LUFA library when used in Host mode. *  Dean Camera committed Feb 26, 2011 190  * HOST_STATE_AS_GPIOR - (\ref Group_Host) - AVR8 Only \n  Dean Camera committed Jun 16, 2010 191  * One of the most frequently used global variables in the stack is the USB_HostState global, which indicates the current state of  Dean Camera committed May 08, 2010 192 193 194 195 196  * the Host State Machine. To reduce the amount of code and time required to access and modify this global in an application, this token * 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 Feb 26, 2011 197  * USB_HOST_TIMEOUT_MS=x - (\ref Group_Host) - All Architectures \n  Dean Camera committed May 08, 2010 198 199 200 201  * When a control transfer is initiated in host mode to an attached device, a timeout is used to abort the transfer if the attached * 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 * control transfers, specified in milliseconds. If not defined, the default value specified in Host.h is used instead. *  Dean Camera committed Feb 26, 2011 202  * HOST_DEVICE_SETTLE_DELAY_MS=x - (\ref Group_Host) - All Architectures \n  Dean Camera committed May 08, 2010 203 204 205 206 207  * 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 * 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. */  208