Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / USB / Core / Device.h @ 978b99e5

History | View | Annotate | Download (8.2 KB)

1
/*
2
             LUFA Library
3
     Copyright (C) Dean Camera, 2011.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7
*/
8

    
9
/*
10
  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
11

12
  Permission to use, copy, modify, distribute, and sell this
13
  software and its documentation for any purpose is hereby granted
14
  without fee, provided that the above copyright notice appear in
15
  all copies and that both that the copyright notice and this
16
  permission notice and warranty disclaimer appear in supporting
17
  documentation, and that the name of the author not be used in
18
  advertising or publicity pertaining to distribution of the
19
  software without specific, written prior permission.
20

21
  The author disclaim all warranties with regard to this
22
  software, including all implied warranties of merchantability
23
  and fitness.  In no event shall the author be liable for any
24
  special, indirect or consequential damages or any damages
25
  whatsoever resulting from loss of use, data or profits, whether
26
  in an action of contract, negligence or other tortious action,
27
  arising out of or in connection with the use or performance of
28
  this software.
29
*/
30

    
31
/** \file
32
 *  \brief Common USB Device definitions for all architectures.
33
 *  \copydetails Group_Device
34
 *
35
 *  \note This file should not be included directly. It is automatically included as needed by the USB driver
36
 *        dispatch header located in LUFA/Drivers/USB/USB.h.
37
 */
38

    
39
/** \ingroup Group_USB
40
 *  \defgroup Group_Device Device Management
41
 *  \brief USB Device management definitions for USB device mode.
42
 *
43
 *  USB Device mode related definitions common to all architectures. This module contains definitions which
44
 *  are used when the USB controller is initialized in device mode.
45
 *
46
 *  @{
47
 */
48

    
49
#ifndef __USBDEVICE_H__
50
#define __USBDEVICE_H__
51

    
52
        /* Includes: */
53
                #include "../../../Common/Common.h"
54
                #include "USBMode.h"                
55
                #include "StdDescriptors.h"
56
                #include "USBInterrupt.h"
57
                #include "Endpoint.h"
58

    
59
        /* Enable C linkage for C++ Compilers: */
60
                #if defined(__cplusplus)
61
                        extern "C" {
62
                #endif
63

    
64
        /* Preprocessor Checks: */
65
                #if !defined(__INCLUDE_FROM_USB_DRIVER)
66
                        #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
67
                #endif
68

    
69
        /* Public Interface - May be used in end-application: */
70
                /* Enums: */
71
                        /** Enum for the various states of the USB Device state machine. Only some states are
72
                         *  implemented in the LUFA library - other states are left to the user to implement.
73
                         *
74
                         *  For information on each possible USB device state, refer to the USB 2.0 specification.
75
                         *
76
                         *  \see \ref USB_DeviceState, which stores the current device state machine state.
77
                         */
78
                        enum USB_Device_States_t
79
                        {
80
                                DEVICE_STATE_Unattached                   = 0, /**< Internally implemented by the library. This state indicates
81
                                                                                *   that the device is not currently connected to a host.
82
                                                                                */
83
                                DEVICE_STATE_Powered                      = 1, /**< Internally implemented by the library. This state indicates
84
                                                                                *   that the device is connected to a host, but enumeration has not
85
                                                                                *   yet begun.
86
                                                                                */
87
                                DEVICE_STATE_Default                      = 2, /**< Internally implemented by the library. This state indicates
88
                                                                                *   that the device's USB bus has been reset by the host and it is
89
                                                                                *   now waiting for the host to begin the enumeration process.
90
                                                                                */
91
                                DEVICE_STATE_Addressed                    = 3, /**< Internally implemented by the library. This state indicates
92
                                                                                *   that the device has been addressed by the USB Host, but is not
93
                                                                                *   yet configured.
94
                                                                                */
95
                                DEVICE_STATE_Configured                   = 4, /**< May be implemented by the user project. This state indicates
96
                                                                                *   that the device has been enumerated by the host and is ready
97
                                                                                *   for USB communications to begin.
98
                                                                                */
99
                                DEVICE_STATE_Suspended                    = 5, /**< May be implemented by the user project. This state indicates
100
                                                                                *   that the USB bus has been suspended by the host, and the device
101
                                                                                *   should power down to a minimal power level until the bus is
102
                                                                                *   resumed.
103
                                                                                */
104
                        };
105

    
106
                /* Function Prototypes: */
107
                        /** Function to retrieve a given descriptor's size and memory location from the given descriptor type value,
108
                         *  index and language ID. This function MUST be overridden in the user application (added with full, identical
109
                         *  prototype and name so that the library can call it to retrieve descriptor data.
110
                         *
111
                         *  \param[in] wValue               The type of the descriptor to retrieve in the upper byte, and the index in the
112
                         *                                  lower byte (when more than one descriptor of the given type exists, such as the
113
                         *                                  case of string descriptors). The type may be one of the standard types defined
114
                         *                                  in the DescriptorTypes_t enum, or may be a class-specific descriptor type value.
115
                         *  \param[in] wIndex               The language ID of the string to return if the \c wValue type indicates
116
                         *                                  \ref DTYPE_String, otherwise zero for standard descriptors, or as defined in a
117
                         *                                  class-specific standards.
118
                         *  \param[out] DescriptorAddress   Pointer to the descriptor in memory. This should be set by the routine to
119
                         *                                  the address of the descriptor.
120
                         *  \param[out] MemoryAddressSpace  A value from the \ref USB_DescriptorMemorySpaces_t enum to indicate the memory
121
                         *                                  space in which the descriptor is stored. This parameter does not exist when one
122
                         *                                  of the \c USE_*_DESCRIPTORS compile time options is used, or on architectures which
123
                         *                                  use a unified address space.
124
                         *
125
                         *  \note By default, the library expects all descriptors to be located in flash memory via the \c PROGMEM attribute.
126
                         *        If descriptors should be located in RAM or EEPROM instead (to speed up access in the case of RAM, or to
127
                         *        allow the descriptors to be changed dynamically at runtime) either the \c USE_RAM_DESCRIPTORS or the
128
                         *        \c USE_EEPROM_DESCRIPTORS tokens may be defined in the project makefile and passed to the compiler by the -D
129
                         *        switch.
130
                         *
131
                         *  \return Size in bytes of the descriptor if it exists, zero or \ref NO_DESCRIPTOR otherwise.
132
                         */
133
                        uint16_t CALLBACK_USB_GetDescriptor(const uint16_t wValue,
134
                                                            const uint8_t wIndex,
135
                                                            const void** const DescriptorAddress
136
                        #if (defined(ARCH_HAS_MULTI_ADDRESS_SPACE) || defined(__DOXYGEN__)) && \
137
                            !(defined(USE_FLASH_DESCRIPTORS) || defined(USE_EEPROM_DESCRIPTORS) || defined(USE_RAM_DESCRIPTORS))
138
                                                            , uint8_t* MemoryAddressSpace
139
                        #endif
140
                                                            ) ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(3);
141

    
142
        /* Architecture Includes: */
143
                #if (ARCH == ARCH_AVR8)
144
                        #include "AVR8/Device_AVR8.h"
145
                #elif (ARCH == ARCH_UC3)
146
                        #include "UC3/Device_UC3.h"
147
                #elif (ARCH == ARCH_XMEGA)
148
                        #include "XMEGA/Device_XMEGA.h"                
149
                #endif
150

    
151
        /* Disable C linkage for C++ Compilers: */
152
                #if defined(__cplusplus)
153
                        }
154
                #endif
155

    
156
#endif
157

    
158
/** @} */
159