Add const attribute to class driver APIs.

Add new manual pages detailing the advantages of LUFA over the official Atmel USB AVR stack, and reasons why LUFA should be used over a built-from-scratch USB stack.

LUFA/Drivers/USB/Class/Device/HID.h

@@ -74,7 +74,7 @@
 					uint8_t  ReportINEndpointNumber; /**< Endpoint number of the HID interface's IN report endpoint */
 					uint16_t ReportINEndpointSize; /**< Size in bytes of the HID interface's IN report endpoint */					
 					
-					void*    PrevReportINBuffer; /** Pointer to a buffer where the previously created HID input report can be
+					void*    PrevReportINBuffer; /**< Pointer to a buffer where the previously created HID input report can be
 					                              *  stored by the driver, for comparison purposes to detect report changes that
 					                              *  must be sent immediately to the host. This should point to a buffer big enough
 					                              *  to hold the largest HID input report sent from the HID interface. If this is set
@@ -86,7 +86,7 @@
 												  *        this buffer should be set to NULL and the decision to send reports made
 												  *        by the user application instead.
 					                              */
-					uint8_t  PrevReportINBufferSize; /** Size in bytes of the given input report buffer. This is used to create a
+					uint8_t  PrevReportINBufferSize; /**< Size in bytes of the given input report buffer. This is used to create a
 					                                  *  second buffer of the same size within the driver so that subsequent reports
 					                                  *  can be compared.
 					                                  */
@@ -96,9 +96,9 @@
 				struct
 				{
 					bool     UsingReportProtocol; /**< Indicates if the HID interface is set to Boot or Report protocol mode */
-					uint16_t IdleCount; /**< Report idle period, in mS, set by the host */
-					uint16_t IdleMSRemaining; /**< Total number of mS remaining before the idle period elapsed - this should be
-											   *   decremented by the user application if non-zero each millisecond */	
+					uint16_t IdleCount; /**< Report idle period, in milliseconds, set by the host */
+					uint16_t IdleMSRemaining; /**< Total number of milliseconds remaining before the idle period elapsed - this 
+											   *   should be decremented by the user application if non-zero each millisecond */	
 				} State; /**< State data for the USB class interface within the device. All elements in this section
 				          *   are reset to their defaults when the interface is enumerated.
 				          */

LUFA/Drivers/USB/Class/Host/CDC.c

@@ -132,7 +132,7 @@ uint8_t CDC_Host_ConfigurePipes(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo
 	return CDC_ENUMERROR_NoError;
 }
 
-static uint8_t DComp_CDC_Host_NextCDCControlInterface(void* CurrentDescriptor)
+static uint8_t DComp_CDC_Host_NextCDCControlInterface(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
 	{
@@ -150,7 +150,7 @@ static uint8_t DComp_CDC_Host_NextCDCControlInterface(void* CurrentDescriptor)
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 
-static uint8_t DComp_CDC_Host_NextCDCDataInterface(void* CurrentDescriptor)
+static uint8_t DComp_CDC_Host_NextCDCDataInterface(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
 	{
@@ -168,7 +168,7 @@ static uint8_t DComp_CDC_Host_NextCDCDataInterface(void* CurrentDescriptor)
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 
-static uint8_t DComp_CDC_Host_NextCDCInterfaceEndpoint(void* CurrentDescriptor)
+static uint8_t DComp_CDC_Host_NextCDCInterfaceEndpoint(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
 	{

LUFA/Drivers/USB/Class/Host/CDC.h

@@ -227,11 +227,11 @@
 		/* Function Prototypes: */
 			#if defined(INCLUDE_FROM_CDC_CLASS_HOST_C)
 				void CDC_Host_Event_Stub(void);
-				void EVENT_CDC_Host_ControLineStateChanged(USB_ClassInfo_CDC_Host_t* CDCInterfaceInfo)
+				void EVENT_CDC_Host_ControLineStateChanged(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo)
 				                                           ATTR_WEAK ATTR_NON_NULL_PTR_ARG(1) ATTR_ALIAS(CDC_Host_Event_Stub);
-				static uint8_t DComp_CDC_Host_NextCDCControlInterface(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-				static uint8_t DComp_CDC_Host_NextCDCDataInterface(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-				static uint8_t DComp_CDC_Host_NextCDCInterfaceEndpoint(void* CurrentDescriptor);
+				static uint8_t DComp_CDC_Host_NextCDCControlInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_CDC_Host_NextCDCDataInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_CDC_Host_NextCDCInterfaceEndpoint(void* const CurrentDescriptor);
 			#endif	
 	#endif
 				

LUFA/Drivers/USB/Class/Host/HID.c

@@ -106,7 +106,7 @@ uint8_t HID_Host_ConfigurePipes(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo
 	return HID_ENUMERROR_NoError;
 }
 
-static uint8_t DComp_HID_Host_NextHIDInterface(void* CurrentDescriptor)
+static uint8_t DComp_HID_Host_NextHIDInterface(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
 	{
@@ -120,7 +120,7 @@ static uint8_t DComp_HID_Host_NextHIDInterface(void* CurrentDescriptor)
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 
-static uint8_t DComp_NextHID(void* CurrentDescriptor)
+static uint8_t DComp_NextHID(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_HID)
 	  return DESCRIPTOR_SEARCH_Found;
@@ -130,7 +130,7 @@ static uint8_t DComp_NextHID(void* CurrentDescriptor)
 	  return DESCRIPTOR_SEARCH_NotFound;	  
 }
 
-static uint8_t DComp_HID_Host_NextHIDInterfaceEndpoint(void* CurrentDescriptor)
+static uint8_t DComp_HID_Host_NextHIDInterfaceEndpoint(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
 	{

LUFA/Drivers/USB/Class/Host/HID.h

@@ -252,9 +252,9 @@
 
 		/* Function Prototypes: */
 			#if defined(INCLUDE_FROM_HID_CLASS_HOST_C)
-				static uint8_t DComp_HID_Host_NextHIDInterface(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-				static uint8_t DComp_NextHID(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-				static uint8_t DComp_HID_Host_NextHIDInterfaceEndpoint(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_HID_Host_NextHIDInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_NextHID(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_HID_Host_NextHIDInterfaceEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
 			#endif	
 	#endif	
 	

LUFA/Drivers/USB/Class/Host/MIDI.c

@@ -82,7 +82,7 @@ uint8_t MIDI_Host_ConfigurePipes(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceI
 	return MIDI_ENUMERROR_NoError;
 }
 
-static uint8_t DComp_MIDI_Host_NextMIDIStreamingInterface(void* CurrentDescriptor)
+static uint8_t DComp_MIDI_Host_NextMIDIStreamingInterface(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
 	{
@@ -100,7 +100,7 @@ static uint8_t DComp_MIDI_Host_NextMIDIStreamingInterface(void* CurrentDescripto
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 
-static uint8_t DComp_MIDI_Host_NextMIDIStreamingDataEndpoint(void* CurrentDescriptor)
+static uint8_t DComp_MIDI_Host_NextMIDIStreamingDataEndpoint(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
 	{

LUFA/Drivers/USB/Class/Host/MIDI.h

@@ -148,8 +148,8 @@
 
 		/* Function Prototypes: */
 			#if defined(INCLUDE_FROM_MIDI_CLASS_HOST_C)
-				static uint8_t DComp_MIDI_Host_NextMIDIStreamingInterface(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-				static uint8_t DComp_MIDI_Host_NextMIDIStreamingDataEndpoint(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_MIDI_Host_NextMIDIStreamingInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_MIDI_Host_NextMIDIStreamingDataEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
 			#endif	
 	#endif
 				

LUFA/Drivers/USB/Class/Host/MassStorage.c

@@ -86,7 +86,7 @@ uint8_t MS_Host_ConfigurePipes(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, u
 	return MS_ENUMERROR_NoError;
 }
 
-static uint8_t DComp_NextMSInterface(void* CurrentDescriptor)
+static uint8_t DComp_NextMSInterface(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
 	{
@@ -104,7 +104,7 @@ static uint8_t DComp_NextMSInterface(void* CurrentDescriptor)
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 
-static uint8_t DComp_NextMSInterfaceEndpoint(void* CurrentDescriptor)
+static uint8_t DComp_NextMSInterfaceEndpoint(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
 	{

LUFA/Drivers/USB/Class/Host/MassStorage.h

@@ -325,17 +325,17 @@
 			
 		/* Function Prototypes: */
 			#if defined(INCLUDE_FROM_MS_CLASS_HOST_C)		
-				static uint8_t DComp_NextMSInterface(void* CurrentDescriptor);
-				static uint8_t DComp_NextMSInterfaceEndpoint(void* CurrentDescriptor);
+				static uint8_t DComp_NextMSInterface(void* const CurrentDescriptor);
+				static uint8_t DComp_NextMSInterfaceEndpoint(void* const CurrentDescriptor);
 				
-				static uint8_t MS_Host_SendCommand(USB_ClassInfo_MS_Host_t* MSInterfaceInfo,
-				                                   MS_CommandBlockWrapper_t* SCSICommandBlock,
+				static uint8_t MS_Host_SendCommand(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
+				                                   MS_CommandBlockWrapper_t* const SCSICommandBlock,
 				                                   void* BufferPtr);
-				static uint8_t MS_Host_WaitForDataReceived(USB_ClassInfo_MS_Host_t* MSInterfaceInfo);
-				static uint8_t MS_Host_SendReceiveData(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, 
-                                                       MS_CommandBlockWrapper_t* SCSICommandBlock, void* BufferPtr);
-				static uint8_t MS_Host_GetReturnedStatus(USB_ClassInfo_MS_Host_t* MSInterfaceInfo,
-				                                         MS_CommandStatusWrapper_t* SCSICommandStatus);
+				static uint8_t MS_Host_WaitForDataReceived(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo);
+				static uint8_t MS_Host_SendReceiveData(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, 
+                                                       MS_CommandBlockWrapper_t* const SCSICommandBlock, void* BufferPtr);
+				static uint8_t MS_Host_GetReturnedStatus(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
+				                                         MS_CommandStatusWrapper_t* const SCSICommandStatus);
 			#endif
 	#endif
 	

LUFA/Drivers/USB/Class/Host/StillImage.c

@@ -101,7 +101,7 @@ uint8_t SI_Host_ConfigurePipes(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo, u
 	return SI_ENUMERROR_NoError;
 }
 
-uint8_t DComp_SI_Host_NextSIInterface(void* CurrentDescriptor)
+uint8_t DComp_SI_Host_NextSIInterface(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
 	{
@@ -119,7 +119,7 @@ uint8_t DComp_SI_Host_NextSIInterface(void* CurrentDescriptor)
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 
-uint8_t DComp_SI_Host_NextSIInterfaceEndpoint(void* CurrentDescriptor)
+uint8_t DComp_SI_Host_NextSIInterfaceEndpoint(void* const CurrentDescriptor)
 {
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
 	{

LUFA/Drivers/USB/Class/Host/StillImage.h

@@ -228,13 +228,13 @@
 		
 		/* Function Prototypes: */
 			#if defined(INCLUDE_FROM_SI_CLASS_HOST_C)
-				static uint8_t DComp_SI_Host_NextSIInterface(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
-				static uint8_t DComp_SI_Host_NextSIInterfaceEndpoint(void* CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_SI_Host_NextSIInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
+				static uint8_t DComp_SI_Host_NextSIInterfaceEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
 
-				static uint8_t SImage_Host_SendBlockHeader(USB_ClassInfo_SI_Host_t* SIInterfaceInfo,
-				                                           SI_PIMA_Container_t* PIMAHeader);
-				static uint8_t SImage_Host_ReceiveBlockHeader(USB_ClassInfo_SI_Host_t* SIInterfaceInfo,
-				                                              SI_PIMA_Container_t* PIMAHeader);
+				static uint8_t SImage_Host_SendBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
+				                                           SI_PIMA_Container_t* const PIMAHeader);
+				static uint8_t SImage_Host_ReceiveBlockHeader(USB_ClassInfo_SI_Host_t* const SIInterfaceInfo,
+				                                              SI_PIMA_Container_t* const PIMAHeader);
 			#endif
 	#endif
 	

LUFA/Drivers/USB/LowLevel/Host.c

@@ -312,7 +312,7 @@ uint8_t USB_Host_GetDeviceDescriptor(void* const DeviceDescriptorPtr)
 uint8_t USB_Host_ClearPipeStall(uint8_t EndpointNum)
 {
 	if (Pipe_GetPipeToken() == PIPE_TOKEN_IN)
-	  EndpointNum |= (1 << 7);
+	  EndpointNum |= ENDPOINT_DESCRIPTOR_DIR_IN;
 
 	USB_ControlRequest = (USB_Request_Header_t)
 		{

LUFA/ManPages/FutureChanges.txt

@@ -11,7 +11,7 @@
   *  If you have an item to add to this list, please contact the library author via email, the LUFA mailing list,
   *  or post your suggestion as an enhancement request to the project bug tracker.
   *
-  *  <b>Targeted for This Release (SVN Development Only):</b>
+  *  <b>Targeted for the Next Release (SVN Development Only):</b>
   *  - Add hub support to match Atmel's stack
   *  - Add ability to get number of bytes not written with pipe/endpoint write routines after an error
   *
@@ -27,6 +27,7 @@
   *      -# Keyboard/Mouse Dual Class Host
   *      -# Multiple-report HID device
   *      -# Mouse/CDC Dual Class Device
+  *      -# Joystick Host
   *  - Port LUFA to other architectures
   *      -# AVR32 UC3B series microcontrollers
   *      -# Atmel ARM7 series microcontrollers

LUFA/ManPages/LUFAvsAtmelStack.txt

+/** \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_LUFAvsAtmelStack LUFA vs the Atmel Stack
+ *
+ *  Atmel offers an official USB AVR stack, which may be incorporated into user projects and products. As LUFA and the Atmel
+ *  stack aims to give roughly the same functionality to a design, it is often asked what advantages LUFA carries over the
+ *  official Atmel USB stack. Below are just some of the advantages to choosing LUFA over the official stack.
+ *
+ *  - <b>Licensing:</b>
+ *    LUFA is released under a very permissive MIT license (see \ref Page_Licence), while the Atmel stack carries several
+ *    restrictions as to how and where it can be used. LUFA's licensing should be suitable for both Commercial and Non-Commercial
+ *    entities alike.
+ *
+ *  - <b>Demos and Projects:</b>
+ *    Unlike the Atmel stack, LUFA comes with many different Device and Host mode Demos and Projects ready to run out of the box.
+ *    Atmel favours separate downloads for each of their (small set) of USB AVR demos, which requires more time and offers less
+ *    to the end-user. LUFA also contains several open source Bootloaders, which can be modified as the user wishes to suit his or
+ *    her application, instead of being forced to use Atmel's single prebuilt (closed-source) DFU bootloader.
+ *
+ *  - <b>Central Library Code:</b>
+ *    LUFA is designed to allow the central library core code to be shared amongst several projects, so long as the compiled object
+ *    files are cleaned between different projects. This is in direct contrast to the Atmel library, which is strongly coupled to the
+ *    project it is integrated with. Using LUFA allows for only one copy of the library core to be needed for all applications, and
+ *    makes updating the library used in all projects a trivial copy-and-paste process.
+ *
+ *  - <b>Clean API:</b>
+ *    One of the main design goals of LUFA is to make the API easy to use. While LUFA is a fluid project which has undergone many
+ *    API improvements, the API is arguably much nicer to use and easier to understand than the equivelent Atmel stack code. LUFA's
+ *    API is also more complete than the Atmel stack, and contains many features to speed up application development.
+ *
+ *  - <b>Full Hardware Support:</b>
+ *    LUFA supports the full range of Atmel's USB AVR microcontrollers (see \ref Page_DeviceSupport), with porting between chips being
+ *    as simple as a single compile switch in many cases. Atmel's stack requires different libraries to be used based on the USB AVR
+ *    microcontroller series, complicating the process of moving between USB AVR models. In addition, LUFA contains drivers for all the
+ *    hardware contained on Atmel's USB AVR based boards, so you can get started quickly and easily.
+ *
+ *  - <b>Better Library Support:</b>
+ *    As many people are now using LUFA, there is a community being built around it. You can get answers to your LUFA related questions
+ *    quickly by either emailing the library author (subject to author's schedule) or by posting to the official LUFA support mailing list.
+ */
+ 
\ No newline at end of file

LUFA/ManPages/MainPage.txt

@@ -31,6 +31,8 @@
  *  and open source LUFA powered projects.
  *
  *  <b>Subsections:</b>
+ *  - \subpage Page_WhyUseLUFA Why Use LUFA?
+ *  - \subpage Page_LUFAvsAtmelStack How does LUFA compare to the Atmel USB AVR stack?
  *  - \subpage Page_Licence Project licence
  *  - \subpage Page_Donating Donating to Support this Project
  *  - \subpage Page_LibraryApps Overview of included Demos, Bootloaders and Projects

LUFA/ManPages/WhyUseLUFA.txt

+/** \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_WhyUseLUFA Why Use LUFA?
+ *
+ *  The LUFA Library has many advantages over implementing the code required to drive the USB AVRs directly.
+ *  It is much more preferable to incorporate LUFA into your existing projects - or even make a new project
+ *  using LUFA - than it is to start from scratch and use the USB AVR registers directly. Some of these reasons
+ *  are:
+ *
+ *  - <b>Portability:</b>
+ *    The LUFA stack is designed to run (at some capacity) on the entire Atmel range of USB AVRs, regardless of the
+ *    exact USB controller revision used. If you decide to implement your own USB stack, you will either need to
+ *    code around the differences between each USB AVR controller's implementation between different chip models, or
+ *    require your code to run on only one specific USB AVR model series.
+ *
+ *  - <b>Speed of Development:</b>
+ *    LUFA ships with a wide range of pre-made demos, bootloaders and projects for you to try, learn and extend. Each
+ *    of these demos are tested (where possible) across as many USB AVRs and Operating Systems as possible, to ensure
+ *    that they work under as many conditions as possible. In addition, there are inbuilt class drivers for several of
+ *    the USB classes which you can make use of in your projects with minimal effort.
+ *
+ *  - <b>Maintainability:</b>
+ *    As LUFA takes care of much of the USB implementation, you can be left to focusing on your actual project's
+ *    functionality, rather than being held back developing and debugging the USB stack code. Since LUFA uses clear APIs
+ *    for USB development, your code will be more readable than if it had the low level USB stack code integrated into
+ *    it directly. Updating the LUFA library is a simple folder-replacement and gives new features and bug fixes in
+ *    seconds each time a new release is made.
+ *
+ *  - <b>Support:</b>
+ *    Since many people are now using LUFA in their own projects, you can take advantage of other's knowedge when you run
+ *    into difficulties or need some advice. In addition, you can also email the library author to recieve personalised
+ *    support when you need it (subject to author's schedule).
+ */
+ 
\ No newline at end of file