@CHIP-RTOS - USB API

Introduction

• There can only be one Configuration. (It is uncommon to use more than one Configuration though the specification allows it.)
• There can be at most 10 Interfaces.
• Each interface can have maximal 12 alternate settings.
• Alternate settings in Device mode can only be used to alter the maximum packet size and the polling interval of its assigned endpoints. It is impossible to change e.g. the number of assigned endpoints. This would also be very uncommon. In Host mode a device may also have a different number of endpoints and different transfer types in Alternate Settings.

Topics

USB API Data Structures

Common Functions - Host and Device mode

Device mode only Functions

Host mode only Functions

This function installs a far JMP opcode in the vicinity of the return instruction pointer to enter the specified USB API function directly from the user code. This function is provided for efficiency in real-time applications.

Parameters

AH

USB_SERVICE_DYNAMIC_LINK (0x00)

AL

Number of USB API function that is to be linked

Return Value

Instruction Pointer is moved back 10 bytes so that newly installed far JMP will execute immediately.

(Refer to respective linked function's documention for further return value information.)

Note: All dynamically linked functions are free to use all registers except for DS, SI, DI, and BP registers which are preserved. This matches Paradigm C, Borland C++ 5.02 and Microsoft Visual C 1.52 calling conventions.

Comments

A JMP FAR instruction will be written 10 bytes before the user's return instruction pointer. This far jump will transfer control directly into the RTOS from the user code when executed. This new far JMP will execute immediately upon return from this software interrupt due to the instruction pointer adjustment performed within the call.

Interrupts are masked and restored to their state on entry.

Since the code at calling site will be patched by this RTOS call, it is important that it has exactly the following form (the link index carried in AL register will vary)

JMP SHORT over_patch  ; Occupies 2 bytes of instruction code here
NOP    ; Never executed (1 byte)
NOP    ; Never executed (1 byte)
NOP    ; never executed (1 byte)
over_patch:  ; Linker overwrites above 5 bytes with JMP FAR instruction
MOV AX,00001h  ; AH = 0x00, AL = 0x01 = usbSend()
INT 0BFh

Developer Notes

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Enqueues a send request to an endpoint's TX queue. In Device mode the data will be transmitted when the Host issues an IN token. In Host mode the data will be transmitted when a SETUP or OUT token is issued using USB_SERVICE_HOST_ISSUE_TOKEN. When the request has been completed the callback -function will be called with a status of USB_EVENT_SENT.

Parameters

AH

USB_SERVICE_SEND (0x01)

AL

Host mode: Address of the device that is to receive the data
Device mode: Must always be 0x00

CL

Number of the enpoint via which the data is to be sent

ES:BX

Data to be sent

DX

Length of data to be sent

CH

Host mode: Must always be FALSE
Device mode: Set this parameter to TRUE if the host demanded more data than is to be sent. This does only apply to control endpoints.

Return Value

Error code in AX

Comments

The buffer that is used for sending must be allocated by the application and be available while the USB-driver processes the send-request. After it has completed the callback-function will be called with an USB_EVENT_SENT event (or maybe an error event). After that the buffer can be released.

Beck C-Library Usage

usbSend()

Related Topics

USB_SERVICE_DEVICE_CONFIG_EP Configure an endpoint

USB_SERVICE_HOST_ISSUE_TOKEN Issue token

USB_SERVICE_HOST_CLEAR_QUEUE Clear an endpoint's queues

USB_SERVICE_HOST_RESERVE_EP0 Reserve endpoint 0

USB_SERVICE_HOST_RELEASE_EP0 Release endpoint 0

Type UsbCallback

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Frees a receive buffer. The RTOS USB-driver manages a bunch of receive buffers internally. Each time data is received on any endpoint, it is put into one of these buffers and the buffer is handed to a user driver along with a callback event.
To enable the reuse of the buffer, this function has to be called as soon as possible.

Parameters

AH

USB_SERVICE_FREE_RECEIVE_BUFFER (0x02)

ES:BX

Pointer to the receive buffer that is to be freed

Return Value

None

Beck C-Library Usage

usbFreeReceiveBuffer()

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Sends a resume signal to the bus to wakeup suspended nodes

Parameters

AH

USB_SERVICE_WAKEUP (0x03)

Return Value

Error code in AX

Comments

As well hosts as devices may perform resume signaling. But the Remote Wakeup Feature of devices may be disabled. In this case a call to this function will fail in Device mode.

Beck C-Library Usage

usbWakeup()

Related Topics

USB_SERVICE_HOST_SET_CLEAR_FEATURE Set/clear feature

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Use this function to enable or disable the forwarding of SOF events to your application. By default the event USB_EVENT_SOF is not notified.

Parameters

AH

USB_SERVICE_SOF_NOTIFY (0x04)

AL

Host mode: ID of the user driver
Device mode: Must always be 0x00

BL

Indicates whether to enable (TRUE) or disable (FALSE) the notification of SOF events

Return Value

Error code in AX

Beck C-Library Usage

usbSofNotify()

Related Topics

Type UsbCallback

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Initialises the USB driver in Device mode and registers a callback-function that will be called to notify the user driver of events like completed transactions.
Also sets sundry strings that describe the device.
Only one user program can use the USB driver in Device mode.
Several information on the device is given to this function via the structure UsbInit. For detailed information on the structure's members refer to its documentation.

Parameters

AH

USB_SERVICE_DEVICE_INIT (0x10)

ES:BX

Pointer to the structure variable

Return Value

Error code in AX

Beck C-Library Usage

usbDeviceInit()

Related Topics

USB_SERVICE_DEVICE_DEINIT Deinitialise Device mode driver

Type UsbInit

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function deinitialises the USB-driver in Device mode.

Parameters

AH

USB_SERVICE_DEVICE_DEINIT (0x11)

Return Value

None

Comments

If the USB-driver has already been started, stop it first.

Beck C-Library Usage

usbDeviceDeinit()

Related Topics

USB_SERVICE_DEVICE_INIT Initialise driver for Device mode

USB_SERVICE_DEVICE_STOP Stop the Device mode driver

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function registers a new interface.

Parameters

AH

USB_SERVICE_DEVICE_REGISTER_INTERFACE (0x12)

AL

Number of endpoints to associate with the interface

CL

Class code of this interface

DL

Subclass code of this interface

CH

Protocol code of this interface

ES:BX

Human readable string describing this interface; must be static for the RTOS USB-driver will not copy it. The string can have a maximum length of USB_SPEC_MAX_STRING_LENGTH characters. If no string is needed, set this to NULL.

Return Value

ID of the newly registered interface or Error code in AX

Comments

For further information on Class, Subclass and Protocol code see the description of USB_SERVICE_DEVICE_INIT .
Use the function USB_SERVICE_DEVICE_GET_EPS to get the numbers of the endpoints that are assigned to the interface.

Beck C-Library Usage

usbDeviceRegisterInterface()

Related Topics

USB_SERVICE_DEVICE_INIT Initialise driver for Device mode

USB_SERVICE_DEVICE_REGISTER_ALT_SETTING Register an Alternate Setting

USB_SERVICE_DEVICE_GET_EPS Get numbers of endpoints associated with an interface

USB_SERVICE_DEVICE_ADD_SPECIFIC_DESC Add a class- or verndor-specific descriptor

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function registers a new alterate setting to a given interface.

Parameters

AH

USB_SERVICE_DEVICE_REGISTER_ALT_SETTING (0x13)

AL

ID of the interface to that the alternate settings is to be registered

Return Value

ID of the new alternate setting or Error code in AX

Comments

Alternate settings can only be used to change the maximum packet size of associated endpoints and the polling interval of associated interrupt or isochronous endpoints. Alternate settings cannot be used to alter the number or transfer type of endpoints.

Beck C-Library Usage

usbDeviceRegisterAltSetting()

Related Topics

USB_SERVICE_DEVICE_REGISTER_INTERFACE Register an interface

USB_SERVICE_DEVICE_CONFIG_EP Configure an endpoint

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function gets the numbers of the endpoints that have been associated with an interface. The numbers are returned in a bitmap field. Each bit that is set to "1" marks an assigned endpoint. If e.g. Bit 1 is set, endpoint 1 is assigned to the interface.
By default both the IN and OUT endpoint at the resp. endpoint number are reserved to the interface. You decide which direction actually to assign to the interface when configuring the endpoints. You may even use both directions if both have the same transfer type.

Parameters

AH

USB_SERVICE_DEVICE_GET_EPS (0x14)

AL

ID of the interface whose endpoints are to be gotten

ES:BX

Result parameter: Bitmap indicating which endpoints belong to the given interface.

Return Value

Error code in AX

Beck C-Library Usage

usbDeviceGetEps()

Related Topics

USB_SERVICE_DEVICE_REGISTER_INTERFACE Register an interface

USB_SERVICE_DEVICE_CONFIG_EP Configure an endpoint

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function can be used to configure an endpoint. Transfer type and the transfer direction can be configured once for each endpoint. The maximum packet size and the polling interval can be configured for each alternate setting of the interface that the endpoint is associated to.

Parameters

AH

USB_SERVICE_DEVICE_CONFIG_EP (0x15)

AL

ID of the interface the endpoint is associated to

BL

ID of the alternate setting to the given interface

CL

Number of the endpoint that is to be configured

BH

Transfer type; possible values are:

• USB_SPEC_TRANSFER_TYPE_CONTROL
• USB_SPEC_TRANSFER_TYPE_ISOCHRONOUS
• USB_SPEC_TRANSFER_TYPE_BULK
• USB_SPEC_TRANSFER_TYPE_INTERRUPT

The symbolic names are defined in USB_SPEC.H.

CH

TRUE, if this is an IN-endpoint, which means that data is transfered from the device to the host. This parameter is ignored for control-endpoints.

DX

Maximum size of packets sent/received through this endpoint; Please note that the packet size may also be limited by the USB specification and by the capabilities of the controller.

ES

Polling interval for interrupt and isochronous endpoints; given in 2ms steps.

Return Value

Maximum packet size set (respecting the USB specification and the capabilities of the controller) or Error code in AX

Beck C-Library Usage

usbDeviceConfigEp()

Related Topics

USB_SERVICE_DEVICE_REGISTER_INTERFACE Register an interface

USB_SERVICE_DEVICE_REGISTER_ALT_SETTING Register an Alternate Setting

USB_SERVICE_DEVICE_GET_EPS Get numbers of endpoints associated with an interface

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function can be used to add class- oder vendor-specific descriptors to the Configuration, to an interface or an endpoint. A buffer has to be allocated by the application into which the descriptor is written. Several descriptors can be written in this single buffer, but only one buffer can be added to each entity. The buffer must be available during the whole program execution because the RTOS USB-driver will not copy it. The specific descriptors will be concatenated to the resp. standard descriptors.

Parameters

AH

USB_SERVICE_DEVICE_ADD_SPECIFIC_DESC (0x16)

AL

Type of entity to which the specific descriptor is to be added. These are possible values:

• USB_SPEC_DESCRIPTOR_TYPE_CONFIG
• USB_SPEC_DESCRIPTOR_TYPE_INTERFACE
• USB_SPEC_DESCRIPTOR_TYPE_EP

The symbolic names are defined in USB_SPEC.H.

CL

ID/number of entity to which the specific descriptor is to be added. If the descriptor type is USB_SPEC_DESCRIPTOR_TYPE_EP this is the endpoint number. If descriptor type is USB_SPEC_DESCRIPTOR_TYPE_INTERFACE this is the index of the interface. If descriptor type is USB_SPEC_DESCRIPTOR_TYPE_CONFIG this parameter should be 0.

ES:BX

Pointer to the buffer containing the descriptor(s)

DL

Length of the descriptor(s) in bytes

Return Value

Error code in AX

Comments

If a specific descriptor is added to an interface it is added to all alternate settings.

Beck C-Library Usage

usbDeviceAddSpecificDesc()

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function will start the Device mode USB-driver and enable the attach- and speed-detection circuit via the configured PIO pin.

Parameters

AH

USB_SERVICE_DEVICE_START (0x17)

Return Value

None

Beck C-Library Usage

usbDeviceStart()

Related Topics

USB_SERVICE_DEVICE_STOP Stop the Device mode driver

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function will stop the Device mode USB-driver and disable the attach- and speed-detection circuit via the configured PIO pin.

Parameters

AH

USB_SERVICE_DEVICE_STOP (0x18)

Return Value

None

Beck C-Library Usage

usbDeviceStop()

Related Topics

USB_SERVICE_DEVICE_START Start the Device mode driver

USB_SERVICE_DEVICE_DEINIT Deinitialise Device mode driver

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function will set the STALL condition for an endpoint. The USB controller will reject all arriving packets and send requests on this endpoint and return a STALL handshake, which tells the Host that the endpoint has a permanent error. A distinction between the IN and OUT direction is not possible. Both directions will be stalled.
Host intervention is needed to reset the STALL condition.

Parameters

AH

USB_SERVICE_DEVICE_STALL_EP (0x19)

AL

Number of endpoint that is to be stalled

Return Value

Error code in AX

Beck C-Library Usage

usbDeviceStallEp()

Related Topics

USB_SERVICE_HOST_SET_CLEAR_FEATURE Set/clear feature

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function enables or disables communication in the OUT direction (Host to Device) of an endpoint. When the Host tries to send data on a disabled endpoint a NAK handshake will be returned (except for ISOCHRONOUS endpoints). A NAK handshake tells the Host that the Device is temporary unable to receive data.

By default all configured endpoints are enabled after the Device has been started.

Note that this function will not stop reception immediately. At least two more packets can be received, because respective requests have already been handed to the controller hardware. Some more data may already have been received, but still be pending in a software queue inside the RTOS.

Parameters

AH

USB_SERVICE_DEVICE_ENABLE_EP (0x1A)

AL

Number of endpoint that is to be enabled/disabled

BH

Indicates whether the endpoint is to be enabled (TRUE) or disabled (FALSE)

Return Value

Error code in AX

Comments

If the device is permanent unable to receive data, the endopint should be stalled.

To achieve sending of a NAK handshake in the IN direction (Device to Host) of an endpoint, simply stop sending on this endpoint. If the Host then tries to receive data on that endpoint, a NAK handshake is returned automatically.

Beck C-Library Usage

usbDeviceEnableEp()

Related Topics

USB_SERVICE_DEVICE_STALL_EP Set STALL-condition for an endpoint

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.20	V1.20

This function registers a user driver and initialises the RTOS USB-driver for Host mode if no other user driver has already done this. There can be several user drivers loaded in Host mode. Each driver registers a callback-function which is called when an event (e.g. completed transaction) appears on a device that the driver is assigned to. User drivers are assigned to Interfaces which allows a device with two different functions and thus two different Interfaces to be handled by two different drivers. The criteria for the assignment of user drivers to Interfaces are the codes handed to this function.

Parameters

AH

USB_SERVICE_HOST_INIT (0x20)

ES:BX

Callback function

AL

Class code

CL

Subclass code

CH

Protocol code
If the user driver can handle devices of one of the Device Classes, these arguements identify the class, subclass and protocol. If the user driver handles vendor-specific protocols, set these arguments to 0.

DX

Vendor ID

SI

Product ID

DI

Product version in BCD code
If the user driver handles devices using a vendor-specific protocol, these arguements identify the Vendor and Product ID of the resp. device as well as the maximum product version that the driver can handle. If the user driver can handle devices of one of the Device Classes, set these arguments to 0.

Return Value

Assigned driver ID or error code in AX; The driver ID will be needed for other API functions.

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostInit()

Related Topics

USB_SERVICE_HOST_DEINIT Deinitialise Host mode driver

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

This function unregisters a user driver and deinitialises the USB driver if there are no more user drivers registered.

Parameters

AH

USB_SERVICE_HOST_DEINIT (0x21)

AL

ID of the user driver that is to be unregistered

Return Value

None

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostDeinit()

Related Topics

USB_SERVICE_HOST_INIT Initialise driver for Host mode

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Issues an IN, OUT or SETUP token on a given endpoint. This is needed in Host mode to initiate a data transfer. To receive a packet from a device, an IN token has to be issued to tell the device to start sending. To send a packet to a device an OUT or SETUP token has to be issued after calling USB_SERVICE_SEND to tell the RTOS USB-driver to start transmission.

Parameters

AH

USB_SERVICE_HOST_ISSUE_TOKEN (0x22)

AL

Address of the device that is to receive the token

BL

Number of the endpoint that is to receive the token

BH

Token that is to be sent; must be one of the following:

• USB_SPEC_PID_IN
• USB_SPEC_PID_OUT
• USB_SPEC_PID_SETUP

The symbolic names are defined in USB_SPEC.H.

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostIssueToken()

Related Topics

USB_SERVICE_SEND Send data

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

This function clears the send and token queue of a given endpoint. It can be used to reset an endpoint when an error occured.
Buffers associated with send requests cleared by this function will later be handed back to the user driver via an event with the status USB_EVENT_RELEASE.
Note that queue entries already passed to the USB controller cannot be removed.

Parameters

AH

USB_SERVICE_HOST_CLEAR_QUEUE (0x23)

AL

Address of the resp. device

BL

Number of the endpoint whose queues are to be cleared

BH

States that the IN direction of the endpoint is to be cleared; set to FALSE for OUT or CONTROL endpints

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostClearQueue()

Related Topics

USB_SERVICE_SEND Send data

USB_SERVICE_HOST_ISSUE_TOKEN Issue token

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Reserves endpoint 0 of a device for a user driver. Since it might happen that several user drivers share one device, access to endpoint 0 of the device has to be synchronised. A user driver must not use (i.e. send or issue tokens) endpoint 0 before reserving it.
The endpoint has to be released again using the interrupt service USB_SERVICE_HOST_RELEASE_EP0.

Parameters

AH

USB_SERVICE_HOST_RESERVE_EP0 (0x24)

AL

ID of the user driver

BL

Address of the resp. device

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostReserveEp0()

Related Topics

Interrupt service USB_SERVICE_HOST_RELEASE_EP0

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Releases endpoint 0 of a device after it was reserved using the interrupt service USB_SERVICE_HOST_RESERVE_EP0.

Parameters

AH

USB_SERVICE_HOST_RELEASE_EP0 (0x25)

AL

ID of the user driver that has reserved the endpoint

BL

Address of the resp. device

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostReleaseEp0()

Related Topics

Interrupt service USB_SERVICE_HOST_RESERVE_EP0

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Returns information from the Device Descriptor of a given device

Parameters

AH

USB_SERVICE_HOST_GET_DEVICE_INFO (0x26)

AL

Address of the resp. device

ES:BX

Result parameter: Pointer to a structure of the type UsbDevice which is to be filled with the information

CL

Size of the handed structure in bytes

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostGetDeviceInfo()

Related Topics

USB_SERVICE_HOST_GET_CONFIG_INFO Get Configuration information

USB_SERVICE_HOST_GET_INTERFACE_INFO Get Interface information

USB_SERVICE_HOST_GET_EP_INFO Get Endpoint information

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Returns information from the Configuration Descriptor of a given device

Parameters

AH

USB_SERVICE_HOST_GET_CONFIG_INFO (0x27)

AL

Address of the resp. device

ES:BX

Result parameter: Pointer to a structure of the type UsbConfig which is to be filled with the information

CL

Size of the handed structure in bytes

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostGetConfigInfo()

Related Topics

USB_SERVICE_HOST_GET_DEVICE_INFO Get Device information

USB_SERVICE_HOST_GET_INTERFACE_INFO Get Interface information

USB_SERVICE_HOST_GET_EP_INFO Get Endpoint information

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Returns information from the Interface Descriptor of a given interface

Parameters

AH

USB_SERVICE_HOST_GET_INTERFACE_INFO (0x28)

AL

Address of the resp. device

CL

ID of the resp. Interface

CH

ID of the resp. Alternate Setting

ES:BX

Result parameter: Pointer to a structure of the type UsbInterface which is to be filled with the information

DL

Size of the handed structure in bytes

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostGetInterfaceInfo()

Related Topics

USB_SERVICE_HOST_GET_DEVICE_INFO Get Device information

USB_SERVICE_HOST_GET_CONFIG_INFO Get Configuration information

USB_SERVICE_HOST_GET_EP_INFO Get Endpoint information

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Returns information from the Endpoint Descriptor of a given endpoint

Parameters

AH

USB_SERVICE_HOST_GET_EP_INFO (0x29)

AL

Address of the resp. device

CL

ID of the resp. alternate setting

CH

Number of the resp. endpoint

DL

Indicates that information on an IN endpoint is desired; always set to FALSE for control-endpoints

ES:BX

Result parameter: Pointer to a structure of the type UsbEp which is to be filled with the information

DL

Size of the handed structure in bytes

Return Value

Error code in AX

Comments

This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostGetEpInfo()

Related Topics

USB_SERVICE_HOST_GET_DEVICE_INFO Get Device information

USB_SERVICE_HOST_GET_CONFIG_INFO Get Configuration information

USB_SERVICE_HOST_GET_INTERFACE_INFO Get Interface information

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Retrieves a string from a given device

Parameters

AH

USB_SERVICE_HOST_GET_STRING (0x2A)

AL

ID of the user driver

CL

Address of the resp. device

CH

ID of the string that is desired

ES:BX

Pointer to a buffer where the string is to be stored; Must be large enough to store a string consisting of USB_SPEC_MAX_STRING_LENGTH characters plus trailing zero-byte

Return Value

Error code in AX

Comments

This function reserves endpoint 0 of the resp. device for the user driver that calls it before using the endpoint and it releases it again afterwards.
Note that this function may take up to 2000 ms to complete, because it waits that long for data to arrive from the device.
This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostGetString()

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Retrieves status information from a given device using the GetStatus Standard Device Request

Parameters

AH

USB_SERVICE_HOST_GET_STATUS (0x2B)

AL

ID of the user driver

CL

Address of the resp. device

CH

Receiver of the GetStatus request; this parameter decides whether the status of the device, an interface, an endpoint or a user- defined structure is to be retrieved; must be one of the following:

• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_DEVICE
• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_INTERFACE
• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_ENDPOINT
• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_OTHER

The symbolic names are defined in USB_SPEC.H.

DL

Index of the resp. structure. The value of this parameter depends on the value of the receiver parameter.
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_DEVICE, the index must always be 0.
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_INTERFACE, the index must contain the ID of the resp. interface.
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_ENDPOINT, the index parameter must contain the number of the resp. endpoint. If it is an IN endpoint, bit 7 has to be set additionally. (e.g. IN endpoint 1 => 0x81).
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_OTHER, the value of the index parameter is device-specific.

ES:BX

Pointer to an unsigned short variable where the status is to be stored.

Return Value

Error code in AX

Comments

This function reserves endpoint 0 of the resp. device for the user driver that calls it before using the endpoint and it releases it again afterwards.
Note that this function may take up to 2000 ms to complete, because it waits that long for data to arrive from the device.
This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostGetStatus()

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Sets or clears a feature of a given device by sending a SetFeature or ClearFeature Standard Device Request

Parameters

AH

USB_SERVICE_HOST_SET_CLEAR_FEATURE (0x2C)

AL

ID of the user driver

BL

Address of the resp. device

BH

Receiver of the SetFeature or GetFeature request; this parameter decides whether a feature of the device, an interface, an endpoint or a user- defined structure is to be set/cleared; must be one of the following:

• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_DEVICE
• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_INTERFACE
• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_ENDPOINT
• USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_OTHER

The symbolic names are defined in USB_SPEC.H.

CL

Index of the resp. structure. The value of this parameter depends on the value of the receiver parameter.
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_DEVICE, the index must always be 0.
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_INTERFACE, the index must contain the ID of the resp. interface.
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_ENDPOINT, the index parameter must contain the number of the resp. endpoint. If it is an IN endpoint, bit 7 has to be set additionally. (e.g. IN endpoint 1 => 0x81).
If the receiver is USB_SPEC_DEVICE_REQUEST_TYPE_RECEIVER_OTHER, the value of the index parameter is device-specific.

CH

Identifies the feature that is to be set/cleared. Actually the feature USB_SPEC_FEATURE_REMOTE_WAKEUP is defined for devices and USB_SPEC_FEATURE_STALL for endpoints.
The symbolic names are defined in USB_SPEC.H.

DL

If this parameter is TRUE the feature will be set, otherwise it will be cleared.

Return Value

Error code in AX

Comments

This function reserves endpoint 0 of the resp. device for the user driver that calls it before using the endpoint and it releases it again afterwards.
Note that this function may take up to 2000 ms to complete, because it waits that long for data to arrive from the device.
This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostSetClearFeature()

Related Topics

USB_SERVICE_WAKEUP Wake up suspended nodes

USB_SERVICE_DEVICE_STALL_EP Set STALL-condition for an endpoint

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00

Sets one of the alternate settings of a given interface as the current one by sending a SetInterface Standard Device Request

Parameters

AH

USB_SERVICE_HOST_SET_INTERFACE (0x2D)

AL

ID of the user driver

BL

Address of the resp. device

BH

ID of the resp. interface

CL

ID of the alternate setting that is to be activated

Return Value

Error code in AX

Comments

This function reserves endpoint 0 of the resp. device for the user driver that calls it before using the endpoint and it releases it again afterwards.
Note that this function may take up to 2000 ms to complete, because it waits that long for data to arrive from the device.
This function must not be called from within the callback-function.

Beck C-Library Usage

usbHostSetInterface()

Related Topics

USB_SERVICE_HOST_GET_CONFIG_INFO Get Configuration information

USB_SERVICE_HOST_GET_INTERFACE_INFO Get Interface information

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.06	V1.00