USB Device Core Interface
[USB Device Framework]

Collaboration diagram for USB Device Core Interface:

Functions
status_t	usb_dev_get_descriptor (struct udc *udc, uint16_t value, uint16_t index, uint16_t len)
	Handle a standard GET_DESCRIPTOR request.
status_t	usb_dev_set_configuration (struct udc *udc, uint16_t config_id)
	Set the active configuration.
status_t	usb_dev_get_interface (struct udc *udc, uint16_t iface_id)
	Get the currently active alternate setting of an interface.
status_t	usb_dev_set_interface (struct udc *udc, uint16_t iface_id, uint16_t alt_setting)
	Select an alternate setting for an interface.
void	usb_dev_reset (struct udc *udc)
	Reset the USB device.
status_t	usb_dev_process_setup_request (struct udc *udc, struct usb_setup_req *setup)
	Handle a class- or vendor-defined setup request.

---

Detailed Description

The functions defined by this module are called by the USB Device Controller driver or the UDC library in response to bus events and control requests from the host. The USB Device Multiplexing layer will, when enabled, implement these, so applications utilizing the UDM should not have to care about these.

---

Function Documentation

status_t usb_dev_get_descriptor	(	struct udc *	udc,
		uint16_t	value,
		uint16_t	index,
		uint16_t	len
	)

Handle a standard GET_DESCRIPTOR request.

This is called when a GET_DESCRIPTOR request is received from the host. The higher-level driver may queue one or more IN buffers with the requested descriptor data if available.

After the descriptor data has been successfully sent, which may or may not happen after this function returns, udc_ep0_expect_status() must be called.

Parameters:

	udc	USB Device Controller instance
	value	The wValue of the request in native byte order
	index	The wIndex of the request in native byte order
	len	The wLength of the request in native byte order. The higher-level driver must never queue more than this number of bytes even if the requested descriptor is larger.

Return values:

	STATUS_OK	The request was handled successfully.
	negative	The request failed, so ep0 should be stalled.

Referenced by udc_lib_standard_request().

status_t usb_dev_get_interface	(	struct udc *	udc,
		uint16_t	iface_id
	)

Get the currently active alternate setting of an interface.

This function will queue a IN packet with a single byte indicating the currently selected alternate setting of the specified interface.

Parameters:

	udc	USB Device Controller instance
	iface_id	The bInterfaceNumber of the interface to query

Return values:

	STATUS_OK	The request was handled successfully, and the IN packet was queued.
	ERR_INVALID_ARG	iface_id does not match any interface in the current configuration, so ep0 should be stalled.

Referenced by udc_lib_standard_request().

status_t usb_dev_process_setup_request	(	struct udc *	udc,
		struct usb_setup_req *	setup
	)

Handle a class- or vendor-defined setup request.

This function is called when a SETUP request whose Type field in bmRequestType does not indicate a standard request. It is completely up to the higher-level driver to decide which requests to support; it may choose not to support any.

This function may queue one or more data or status packets asynchronously, and call udc_ep0_expect_status() when any queued IN data has been sent.

Note that the fields in setup are in USB (little-endian) byte order.

Parameters:

	udc	USB Device Controller instance
	setup	USB SETUP request

Return values:

	STATUS_OK	The request was handled successfully.
	negative	The request failed, so ep0 should be stalled.

void usb_dev_reset

(

struct udc *

udc

)

Reset the USB device.

This is called when a USB bus reset is detected, and when the device is disconnected from the host.

Parameters:

udc

USB Device Controller instance

Referenced by at90usb_udc_detach(), and at90usb_udc_device_worker().

status_t usb_dev_set_configuration	(	struct udc *	udc,
		uint16_t	config_id
	)

Set the active configuration.

This function will deselect the currently active configuration, and optionally select a new one. If config_id is zero, no new configuration will be selected, but the function will still report success. If config_id is higher than the number of supported configurations, the function will report failure.

Parameters:

	udc	USB Device Controller instance
	config_id	The bConfigurationValue of the new configuration, or zero if the device is to change to the Address state.

Return values:

	STATUS_OK	The request was handled successfully.
	negative	The request failed, so ep0 should be stalled.

Referenced by udc_lib_standard_request().

status_t usb_dev_set_interface	(	struct udc *	udc,
		uint16_t	iface_id,
		uint16_t	alt_setting
	)

Select an alternate setting for an interface.

Select alternate setting alt_setting for interface iface_id.

Parameters:

	udc	USB Device Controller instance
	iface_id	The bInterfaceNumber of the interface
	alt_setting	The bAlternateSetting to be selected

Return values:

	STATUS_OK	The request was handled successfully.
	negative	The request failed, so ep0 should be stalled.

Referenced by udc_lib_standard_request().