www.beck-ipc.com

@CHIP-RTOS - USB API


    IPC@CHIP® Documentation Index

Introduction

This documentation describes the low-level software-interrupt-based API of the IPC@CHIP® RTOS dual-mode USB-driver. The SC1x3/SC2x disposes of a USB-controller that is compliant with the USB specification version 1.1.
Though the USB-API hides much of the complexity of the USB, one should fly over the specification to get a grasp of how USB works.
We also recommend to take notice of the Requirements and Recommendations for USB Products with Embedded Hosts and/or Multiple Receptacles.

The USB-driver can be used in Device mode to implement a USB device (resp. function) which will then be connected to e.g. a PC-Host; or it can be used in Host mode. In this case USB devices can be connected to the IPC@CHIP® handled by device-specific drivers that use the USB-API.
The RTOS USB-driver can operate in only one mode at a time. To implement a USB Function (Device) using this API, an additional circuit is needed, which manages attach- and speed-detection. A diagram is included in the hardware manual of the SC1x3/SC2x showing how to prepare your hardware to operate in both modes. Any PIO can be used to control this circuit. The API switches the PIO as needed.

Please note that there's no Hub support in Host mode and that there are some restrictions regarding data structures handled by the RTOS USB-driver necessary to keep the driver small and fast. These mainly concern Configurations, Interfaces and Alternate Settings. These restrictions should not constrain you much when implementing a USB-device and most devices connected to an IPC@CHIP® operating in Host mode will fulfil the conditions too.
  • 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.

Use of the USB API C library is recommended, rather than dealing directly with these low level assembly lanaguage interfaces specified here.

Topics

Common Functions - Host and Device mode

  • 0x00:_Install dynamic link, then call function
  • 0x01:_Send data
  • 0x02:_Hand a receive buffer back to the driver
  • 0x03:_Wake up suspended nodes
  • 0x04:_Enable/disable notification of SOF events

  • Device mode only Functions

  • 0x10:_Initialise driver for Device mode
  • 0x11:_Deinitialise Device mode driver
  • 0x12:_Register an interface
  • 0x13:_Register an Alternate Setting
  • 0x14:_Get numbers of endpoints associated with an interface
  • 0x15:_Configure an endpoint
  • 0x16:_Add a class- or verndor-specific descriptor
  • 0x17:_Start the Device mode driver
  • 0x18:_Stop the Device mode driver
  • 0x19:_Set STALL condition for an endpoint
  • 0x1A:_Enable/disable an endpoint

  • Host mode only Functions

  • 0x20:_Initialise driver for Host mode
  • 0x21:_Deinitialise Host mode driver
  • 0x22:_Issue token
  • 0x23:_Clear an endpoint's queues
  • 0x24:_Reserve endpoint 0
  • 0x25:_Release endpoint 0
  • 0x26:_Get Device information
  • 0x27:_Get Configuration information
  • 0x28:_Get Interface information
  • 0x29:_Get Endpoint information
  • 0x2A:_Get string
  • 0x2B:_Get status
  • 0x2C:_Set/clear feature
  • 0x2D:_Set interface


  • Interrupt 0xBF service 0x00:     Install dynamic link, then call function

    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

    This API service is intended to be used by the RTOS C-Library exclusively.
    It should not be used within user applications.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x01:     Send data

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x02:     Hand a receive buffer back to the driver

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x03:     Wake up suspended nodes

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x04:     Enable/disable notification of SOF events

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x10:     Initialise driver for Device mode

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x11:     Deinitialise Device mode driver

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x12:     Register an interface

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x13:     Register an Alternate Setting

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x14:     Get numbers of endpoints associated with an interface

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x15:     Configure an endpoint

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x16:     Add a class- or verndor-specific descriptor

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x17:     Start the Device mode driver

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x18:     Stop the Device mode driver

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x19:     Set STALL condition for an endpoint

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x1A:     Enable/disable an endpoint

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.20V1.20

    Top of list
    Index page
    Interrupt 0xBF service 0x20:     Initialise driver for Host mode

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x21:     Deinitialise Host mode driver

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x22:     Issue token

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x23:     Clear an endpoint's queues

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x24:     Reserve endpoint 0

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x25:     Release endpoint 0

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x26:     Get Device information

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x27:     Get Configuration information

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x28:     Get Interface information

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x29:     Get Endpoint information

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x2A:     Get string

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x2B:     Get status

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x2C:     Set/clear feature

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page
    Interrupt 0xBF service 0x2D:     Set interface

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.06V1.00

    Top of list
    Index page


    End of document