PLX offers this brief tour to familiarize programmers that are new to PLX’s device-side API or USB. The tour is based on a properly working environment. Specifically, PLX chip and related USB circuitry are assumed to be working — register accesses work, IRQ pin causes PLX’s interrupt entry point to be called, (optionally) DMA is in-place and working, and finally, PLX’s core API is successfully ported. This situation applies to new platforms and PLX’s PCI-RDK development environment.
For assistance in porting PLX API firmware to the appropriate platform, see PLX’s Firmware Porting Guide.
The Tour Starts Here: Your Client Calls NcApi_OneTimeInit
Client Applications: The portion of software that calls functions in the API is referred to as the API’s “Client Application.” Client applications are high-level functional units, such as Mass Storage or Printer.
Your first call to the API is NcApi_OneTimeInit. The call must be made in a non-interrupt context, such as main(). NcApiOneTimeInit expects only one parameter, of type NC_DEVICE_OBJECT. Notice that before calling NcApi_OneTimeInit, client sets up several USB descriptors in the Device Object.
When NcApi_OneTimeInit successfully returns, client can up set up additional members in the Device Object. It is recommended that the client minimally specify its own DeviceEventHandler. This way, as device events occur, the API calls the client's Device Event Handler, which can then parse the EventCode for NC_DEVICE_EVENT_CODE events of interest.
PLX USB interface controllers are electrically disconnected from the USB host until commanded to connect, regardless of the physical USB cable connection. When ready, client calls NcApi_UsbEnable to enable the electrical USB connection. The USB host can then recognize the connection and begin an enumeration sequence.
USB Enumeration
Enumeration is a complex series of actions and responses between a USB device and host software. When enumeration successfully completes, device-specific host-side drivers are in place and running—the device is “ready to use.” (See USB 2.0, Sections 9.1.2, 9.4, 9.4.6 for further details.)
Enumeration begins when the host detects a USB device connection. Device USB signal levels indicate to the host (or hub) that it is connected. The host issues wire-level signaling and standard, well-defined USB requests to initialize, address, and identify the newly connected device. The host uses the device’s identification information to load and start device-specific host-side client drivers.
Your API client is notified of enumeration events by way of calls to its DeviceEventHandler. Your client can handle as few or as many enumeration events as appropriate. The API provides built-in handlers for standard USB device requests (see USB 2.0, Section 9.4), but your client may prefer to override some or all of those requests. Typically, clients allow the API to handle standard requests. For example, when the host requests a Device Descriptor (see USB 2.0, Section 9.6.1), the API returns the device descriptor specified in the Device Object by your client.
Tip: Before responding to device requests, the API specifies NC_DEVICE_EVENT_DEVICE_REQUEST in the EventCode and calls your DeviceEventHandler, providing your client an opportunity to override the API’s handler. This mechanism applies well when your client must respond to non-standard USB requests (such as USB Mass Storage Class or private Vendor requests).
Enumeration is complete when the host issues a Set Configuration request. This request is significant, as it indicates a device-specific host-side client driver has loaded and started. The API’s handler for a Set Configuration request notifies your client with NC_DEVICE_EVENT_SET_CONFIGURATION specified in the EventCode. If the UsbConfigurationNumber in the Device Object is non-zero, your client’s handler for this event can:
Increase power drawn from VBUS
Prepare endpoints for data transfers by calling NcApi_EpCreate
Start transfers by calling NcApi_EpTransfer
USB Data Transfers
Data Endpoint transfers can begin any time after the device is enumerated with a non-zero configuration number. The host initiates all transfers. The device may begin transfers on any endpoint, any time after calling NcApi_EpCreate.
NcApi_EpCreate returns a reusable Endpoint Object to the client, which refers to a Transfer Object. Client minimally specifies transfer information (address, length, flags, and a Completion Handler) in the Transfer Object and calls NcApi_EpTransfer.
Client can check transfer status at any time in the Endpoint Object. Client’s Completion Handler can examine the Endpoint Object to determine transfer results. Client’s completion routine may safely begin another transfer on the same endpoint (or any endpoint with status other than “Pending”).
Tip: Advanced clients can manage their own Transfer Objects.