| LPCOpen Platform v1.03 LPCOpen Platform for NXP LPC Microcontrollers

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Macros | Enumerations | Functions | Variables
Host Management
USB Core - software/LPCUSBLib/Drivers/USB/USB.h

## Detailed Description

USB Host management definitions for USB host mode.

USB Host mode related macros and enums. This module contains macros and enums which are used when the USB controller is initialized in host mode.

## Modules
| Host Controller Drivers

## Macros
#define | USB_HOST_DEVICEADDRESS 1
#define | USB_HOST_TIMEOUT_MS 1000
#define | HOST_DEVICE_SETTLE_DELAY_MS 1000

## Enumerations
enum | USB_Host_States_t { HOST_STATE_WaitForDevice = 0, HOST_STATE_Unattached = 1, HOST_STATE_Powered = 2, HOST_STATE_Powered_WaitForDeviceSettle = 3, HOST_STATE_Powered_WaitForConnect = 4, HOST_STATE_Powered_DoReset = 5, HOST_STATE_Powered_ConfigPipe = 6, HOST_STATE_Default = 7, HOST_STATE_Default_PostReset = 8, HOST_STATE_Default_PostAddressSet = 9, HOST_STATE_Addressed = 10, HOST_STATE_Configured = 11 }
enum | USB_Host_ErrorCodes_t { HOST_ERROR_VBusVoltageDip = 0 }
enum | USB_Host_EnumerationErrorCodes_t { HOST_ENUMERROR_NoError = 0, HOST_ENUMERROR_WaitStage = 1, HOST_ENUMERROR_NoDeviceDetected = 2, HOST_ENUMERROR_ControlError = 3, HOST_ENUMERROR_PipeConfigError = 4 }

## Functions
uint8_t | USB_Host_GetActiveHost (void)
| Get current active host core number.
static void | USB_Host_EnableSOFEvents (void) ATTR_ALWAYS_INLINE
| Enables the host mode Start Of Frame events. When enabled, this causes the EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus, at the start of each USB frame when a device is enumerated while in host mode.
static void | USB_Host_DisableSOFEvents (void) ATTR_ALWAYS_INLINE
| Disables the host mode Start Of Frame events. When disabled, this stops the firing of the EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.
static void | USB_Host_ResetBus (void) ATTR_ALWAYS_INLINE
| Resets the USB bus, including the endpoints in any attached device and pipes on the LPC host. USB bus resets leave the default control pipe configured (if already configured).
static bool | USB_Host_IsBusResetComplete (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if a previously issued bus reset (via the USB_Host_ResetBus() macro) has completed.
static void | USB_Host_ResumeBus (void) ATTR_ALWAYS_INLINE
| Resumes USB communications with an attached and enumerated device, by resuming the transmission of the 1MS Start Of Frame messages to the device. When resumed, USB communications between the host and attached device may occur.
static void | USB_Host_SuspendBus (void) ATTR_ALWAYS_INLINE
| Suspends the USB bus, preventing any communications from occurring between the host and attached device until the bus has been resumed. This stops the transmission of the 1MS Start Of Frame messages to the device.
static bool | USB_Host_IsBusSuspended (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the USB bus has been suspended via the use of the USB_Host_SuspendBus() macro, false otherwise. While suspended, no USB communications can occur until the bus is resumed, except for the Remote Wakeup event from the device if supported.
static bool | USB_Host_IsDeviceFullSpeed (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the attached device is currently enumerated in Full Speed mode (12Mb/s), or false if the attached device is enumerated in Low Speed mode (1.5Mb/s).
static bool | USB_Host_IsRemoteWakeupSent (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the attached device is currently issuing a Remote Wakeup request, requesting that the host resume the USB bus and wake up the device, false otherwise.
static void | USB_Host_ClearRemoteWakeupSent (void) ATTR_ALWAYS_INLINE
static void | USB_Host_ResumeFromWakeupRequest (void) ATTR_ALWAYS_INLINE
static bool | USB_Host_IsResumeFromWakeupRequestSent (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if a resume from Remote Wakeup request is currently being sent to an attached device.

## Variables
uint8_t | USB_Host_ControlPipeSize [MAX_USB_CORE]
uint8_t | USB_Host_ConfigurationNumber
volatile uint8_t | USB_HostState [MAX_USB_CORE]

## Macro Definition Documentation

#define HOST_DEVICE_SETTLE_DELAY_MS 1000

Constant for the delay in milliseconds after a device is connected before the library will start the enumeration process. Some devices require a delay of up to 5 seconds after connection before the enumeration process can start or incorrect operation will occur.

The default delay value may be overridden in the user project makefile by defining the `HOST_DEVICE_SETTLE_DELAY_MS` token to the required delay in milliseconds, and passed to the compiler using the -D switch.

Definition at line 151 of file Host.h.

#define USB_HOST_DEVICEADDRESS 1

Indicates the fixed USB device address which any attached device is enumerated to when in host mode. As only one USB device may be attached to the LPC in host mode at any one time and that the address used is not important (other than the fact that it is non-zero), a fixed value is specified by the library.

Definition at line 128 of file Host.h.

#define USB_HOST_TIMEOUT_MS 1000

Constant for the maximum software timeout period of sent USB control transactions to an attached device. If a device fails to respond to a sent control request within this period, the library will return a timeout error code.

This value may be overridden in the user project makefile as the value of the USB_HOST_TIMEOUT_MS token, and passed to the compiler using the -D switch.

Definition at line 138 of file Host.h.

## Enumeration Type Documentation

enum USB_Host_EnumerationErrorCodes_t

Enum for the error codes for the EVENT_USB_Host_DeviceEnumerationFailed() event.

See Also
  USB Events for more information on this event.

Enumerator:

  HOST_ENUMERROR_NoError | No error occurred. Used internally, this is not a valid ErrorCode parameter value for the EVENT_USB_Host_DeviceEnumerationFailed() event.
  HOST_ENUMERROR_WaitStage | One of the delays between enumeration steps failed to complete successfully, due to a timeout or other error.
  HOST_ENUMERROR_NoDeviceDetected | No device was detected, despite the USB data lines indicating the attachment of a device.
  HOST_ENUMERROR_ControlError | One of the enumeration control requests failed to complete successfully.
  HOST_ENUMERROR_PipeConfigError | The default control pipe (address 0) failed to configure correctly.

Definition at line 171 of file Host.h.

enum USB_Host_ErrorCodes_t

Enum for the error codes for the EVENT_USB_Host_HostError() event.

See Also
  USB Events for more information on this event.

Enumerator:

  HOST_ERROR_VBusVoltageDip | VBUS voltage dipped to an unacceptable level. This error may be the result of an attached device drawing too much current from the VBUS line, or due to the LPC's power source being unable to supply sufficient current.

Definition at line 158 of file Host.h.

enum USB_Host_States_t

Enum for the various states of the USB Host state machine.

For information on each possible USB host state, refer to the USB 2.0 specification. Several of the USB host states are broken up further into multiple smaller sub-states, so that they can be internally implemented inside the library in an efficient manner.

See Also
  USB_HostState, which stores the current host state machine state.

Enumerator:

  HOST_STATE_WaitForDevice | This state indicates that the stack is waiting for an interval to elapse before continuing with the next step of the device enumeration process.
  HOST_STATE_Unattached | This state indicates that the host state machine is waiting for a device to be attached so that it can start the enumeration process.
  HOST_STATE_Powered | This state indicates that a device has been attached, and the library's internals are being configured to begin the enumeration process.
  HOST_STATE_Powered_WaitForDeviceSettle | This state indicates that the stack is waiting for the initial settling period to elapse before beginning the enumeration process.
  HOST_STATE_Powered_WaitForConnect | This state indicates that the stack is waiting for a connection event from the USB controller to indicate a valid USB device has been attached to the bus and is ready to be enumerated.
  HOST_STATE_Powered_DoReset | This state indicates that a valid USB device has been attached, and that it will now be reset to ensure it is ready for enumeration.
  HOST_STATE_Powered_ConfigPipe | This state indicates that the attached device is currently powered and reset, and that the control pipe is now being configured by the stack.
  HOST_STATE_Default | This state indicates that the stack is currently retrieving the control endpoint's size from the device, so that the control pipe can be altered to match.
  HOST_STATE_Default_PostReset | This state indicates that the control pipe is being reconfigured to match the retrieved control endpoint size from the device, and the device's USB bus address is being set.
  HOST_STATE_Default_PostAddressSet | This state indicates that the device's address has now been set, and the stack is has now completed the device enumeration process. This state causes the stack to change the current USB device address to that set for the connected device, before progressing to the HOST_STATE_Addressed state ready for use in the user application.
  HOST_STATE_Addressed | Indicates that the device has been enumerated and addressed, and is now waiting for the user application to configure the device ready for use.
  HOST_STATE_Configured | Indicates that the device has been configured into a valid device configuration, ready for general use by the user application.

Definition at line 70 of file Host.h.

## Function Documentation

static void USB_Host_ClearRemoteWakeupSent | ( | void |  | ) |
| inline static

Clears the flag indicating that a Remote Wakeup request has been issued by an attached device.

Definition at line 321 of file Host.h.

static void USB_Host_DisableSOFEvents | ( | void |  | ) |
| inline static

Disables the host mode Start Of Frame events. When disabled, this stops the firing of the EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.

Note
  Not available when the NO_SOF_EVENTS compile time token is defined.

Returns
  Nothing

Definition at line 226 of file Host.h.

static void USB_Host_EnableSOFEvents | ( | void |  | ) |
| inline static

Enables the host mode Start Of Frame events. When enabled, this causes the EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus, at the start of each USB frame when a device is enumerated while in host mode.

Note
  Not available when the `NO_SOF_EVENTS` compile time token is defined.

Returns
  Nothing

Definition at line 214 of file Host.h.

uint8_t USB_Host_GetActiveHost | ( | void |  | ) |

Get current active host core number.

Returns
  Active USB host core number

Definition at line 225 of file Host.c.

static bool USB_Host_IsBusResetComplete | ( | void |  | ) |
| inline static

Determines if a previously issued bus reset (via the USB_Host_ResetBus() macro) has completed.

Returns
  Boolean `true` if no bus reset is currently being sent, `false` otherwise.

Definition at line 251 of file Host.h.

static bool USB_Host_IsBusSuspended | ( | void |  | ) |
| inline static

Determines if the USB bus has been suspended via the use of the USB_Host_SuspendBus() macro, false otherwise. While suspended, no USB communications can occur until the bus is resumed, except for the Remote Wakeup event from the device if supported.

Returns
  Boolean `true` if the bus is currently suspended, `false` otherwise.

Definition at line 287 of file Host.h.

static bool USB_Host_IsDeviceFullSpeed | ( | void |  | ) |
| inline static

Determines if the attached device is currently enumerated in Full Speed mode (12Mb/s), or false if the attached device is enumerated in Low Speed mode (1.5Mb/s).

Returns
  Boolean `true` if the attached device is enumerated in Full Speed mode, `false` otherwise.

Definition at line 300 of file Host.h.

static bool USB_Host_IsRemoteWakeupSent | ( | void |  | ) |
| inline static

Determines if the attached device is currently issuing a Remote Wakeup request, requesting that the host resume the USB bus and wake up the device, false otherwise.

Returns
  Boolean `true` if the attached device has sent a Remote Wakeup request, `false` otherwise.

Definition at line 313 of file Host.h.

static bool USB_Host_IsResumeFromWakeupRequestSent | ( | void |  | ) |
| inline static

Determines if a resume from Remote Wakeup request is currently being sent to an attached device.

Returns
  Boolean `true` if no resume request is currently being sent, `false` otherwise.

Definition at line 341 of file Host.h.

static void USB_Host_ResetBus | ( | void |  | ) |
| inline static

Resets the USB bus, including the endpoints in any attached device and pipes on the LPC host. USB bus resets leave the default control pipe configured (if already configured).

If the USB bus has been suspended prior to issuing a bus reset, the attached device will be woken up automatically and the bus resumed after the reset has been correctly issued.

Returns
  Nothing

Definition at line 241 of file Host.h.

static void USB_Host_ResumeBus | ( | void |  | ) |
| inline static

Resumes USB communications with an attached and enumerated device, by resuming the transmission of the 1MS Start Of Frame messages to the device. When resumed, USB communications between the host and attached device may occur.

Returns
  Nothing

Definition at line 264 of file Host.h.

static void USB_Host_ResumeFromWakeupRequest | ( | void |  | ) |
| inline static

Accepts a Remote Wakeup request from an attached device. This must be issued in response to a device's Remote Wakeup request within 2ms for the request to be accepted and the bus to be resumed.

Definition at line 330 of file Host.h.

static void USB_Host_SuspendBus | ( | void |  | ) |
| inline static

Suspends the USB bus, preventing any communications from occurring between the host and attached device until the bus has been resumed. This stops the transmission of the 1MS Start Of Frame messages to the device.

Returns
  Nothing

Definition at line 275 of file Host.h.

## Variable Documentation

uint8_t USB_Host_ConfigurationNumber

Indicates the currently set configuration number of the attached device. This indicates the currently selected configuration value if one has been set sucessfully, or 0 if no configuration has been selected.

To set a device configuration, call the USB_Host_SetDeviceConfiguration() function.

Note
  This variable should be treated as read-only in the user application, and never manually changed in value.

Definition at line 41 of file HostStandardReq.c.

uint8_t USB_Host_ControlPipeSize[MAX_USB_CORE]

Array stores pre-set size of control pipe of all available USB cores

Definition at line 41 of file Host.c.

volatile uint8_t USB_HostState[MAX_USB_CORE]

Indicates the current host state machine state. When in host mode, this indicates the state via one of the values of the USB_Host_States_t enum values.

This value should not be altered by the user application as it is handled automatically by the library.

To reduce program size and speed up checks of this global on the LPC architecture, it can be placed into one of the LPC's `GPIOR` hardware registers instead of RAM by defining the `HOST_STATE_AS_GPIOR` token to a value between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When defined, the corresponding GPIOR register should not be used in the user application except implicitly via the library APIs.

Note
  This global is only present if the user application can be a USB host.

See Also
  USB_Host_States_t for a list of possible device states.