ncfwapi.h

CE下 NET2778 NDIS Drivers, 在每个平台上都可以使用

    //       API continues configuration.
    //     - Unsuccessful: Requested configuration is unacceptable to the client. 
    //       The API deconfigures the device and stalls the request
    //  - ADVANCED DEVICES: Clients supporting more than a single configuration (e.g. 
    //    configurations 2, 3, ...) should trap and handle the Set Configuration
    //    request in the Device Request event handler. 
    //  - See USB 2.0: 9.4.7
    NC_DEVICE_EVENT_SET_CONFIGURATION,

    //////////////////////////////////////////////////////////////////////////
    // Start of Frame (SOF) Event:
    //  - An SOF has been received from the host
    //  - SOFs arrive from a working host every millesecond
    //  - SOF Interrupts must be enabled for this event to occur
    //  - If SOF interrupts are enabled, the API's Frame count and Extended USB 
    //    Frame count are updated automatically
    //  - Recommendation: For best transfer performance, avoid using SOF events.
    //  - Tip: If the API Update USB Frame routine can be called by the client
    //    periodically, within about one second, the API's Extended USB Frame count
    //    will maintain accuracy.
    NC_DEVICE_EVENT_SOF,

    //////////////////////////////////////////////////////////////////////////
    // Suspend event:
    //  - The host is entering its low-power, suspended state
    //  - This event is triggered when a connected host stops issuing SOFs or,
    //    because of the design of USB cables, it can occur when the cable is
    //    unplugged at a slower rate. (Eventually, a VBUS False event should occur)
    //  - The client should reduce power consumption as much as possible
    //  - Many power-saving options are available. The product's power policy
    //    usually dictates which option is best
    //  - Upon a Suspend event, the client can put the NetChip chip into it's 
    //    low-power suspend mode by calling the API's Suspend Chip function.
    //  - See USB 2.0: 7.1.7.6
    NC_DEVICE_EVENT_SUSPEND,

    //////////////////////////////////////////////////////////////////////////
    // Resume event:
    //  - The host is waking from suspend
    //  - This event is triggered when a suspended host resumes issuing SOFs
    //  - See USB 2.0: 7.1.7.7
    NC_DEVICE_EVENT_RESUME,

    // Chip wakeup:
    //  - The chip has awakened from suspend. The chip may wakeup if there is noise 
    //    on the USB Dp/Dm lines or as a result of the API client calling the API's
    //    Wake Chip routine (Tip: a chip register access may also cause a wakeup.)
    //  - A host resume also wakes the chip, but a Resume event has higher precedence 
    //    than Chip Wakeup. Specifically, if the chip wakes due to a host resume, 
    //    a Resume event is issued to the client, not Chip Wakeup
    NC_DEVICE_EVENT_CHIP_WAKEUP,

    //////////////////////////////////////////////////////////////////////////
    // Place holder: End of event codes
    //  - This is NOT a valid event!
    END_OF_NC_DEVICE_EVENT_CODES
} NC_DEVICE_EVENT_CODE;

///////////////////////////////////////////////////////////////////////////////
typedef struct _NC_DEVICE_OBJECT
{   // Device Object structure defining a USB device
    //  - This structure is created and owned by the client. Effectively, this
    //    structure defines the device and its characteristics
    //  - In this structure, a client application specifies USB descriptors and 
    //    device-level callback functions. Callback functions include "Plug-and-Play"
    //    and power event handlers. Status members in the structure help the handlers 
    //    determine details about the events
    //  - Client applications set up some members of this structure, such as USB
    //    descriptors, *before* passing it to the API's One Time Initialization function. 
    //    The API then populates other members, such as callback functions, with default
    //    handlers. Upon return, the client can override these default handlers with 
    //    its own handlers.

    ///////////////////////////////////////////////////////////////////////////
    // USB descriptors
    //  - Client applications provide USB descriptors that uniquely identify and
    //    define the client's USB device.
    //  - Descriptors are provided by the client *before* initializing the API
    //  - Using Control Transfers, the API returns these descriptors to the USB
    //    host when requested. 
    //  - Descriptor content must remain constant as long as the device is
    //    connected to the USB host
    //  - See USB 2.0: 9.5
    ///////////////////////////////////////////////////////////////////////////

    ///////////////////////////////////////////////////////////////////////////
    // Device descriptors:
    //  - For descriptor content, see USB 2.0: 9.6.1, 9.6.2
    PUSB_DEVICE_DESCRIPTOR DeviceDescriptor;
    PUSB_DEVICE_QUALIFIER_DESCRIPTOR DeviceQualifierDescriptor;

    ///////////////////////////////////////////////////////////////////////////
    // Configurations:
    //  - Clients provide two configurations: one for Full Speed (FS), one 
    //    for High Speed (HS). The API automatically chooses the right one to return
    //    upon host's Get Configuration and Get Other_Speed_Configuration requests. 
    //  - Tip: The API adjusts the bDescriptorType field of each configuration as 
    //    required for the connection speed (FS or HS)
    //  - ADVANCED: Clients supporting multiple HS and FS configurations (e.g. 
    //    configurations 2, 3. ...) must detect and handle the standard Get Descriptor 
    //    (Configuration) request (See USB 2.0: 9.4.3): It must specify the requested 
    //    FS and HS configurations here, then return Success to allow the API to 
    //    update and return the configurations to the host. Further, the client must 
    //    detect and handle the standard Set Configuration request: it must specify 
    //    the requested FS and HS configurations here then call the API's Set 
    //    Configuration handler to parse the host's requested configuration.
    //  - For configuration content, see USB 2.0: 9.6.3 (and 9.6.4)
    PUSB_CONFIGURATION_DESCRIPTOR FS_Configuration;     // Full Speed configuration
    PUSB_CONFIGURATION_DESCRIPTOR HS_Configuration;     // High Speed configuration

    ///////////////////////////////////////////////////////////////////////////
    // Strings:
    //  - Strings in the following array are translated by the API from ASCII 
    //    to USB format. Exception: The first string is a special "Language ID 
    //    String" and is not translated.
    //  - The first string (i.e. ClientString[0]) is the Language ID string (LangID). 
    //    The LangID string is returned 'as is' to the USB host when the host requests 
    //    USB string zero. (Ex: USB LangID for US-English is: 0x04, 0x03, 0x09, 0x04.)
    //  - The remaining strings (i.e. ClientString[1], ...) are specified with plain,
    //    null-terminated ASCII strings. The API translates the ASCII strings to USB strings 
    //    at initialization time, and automatically returns them to the USB host when requested.
    //  - The ordinal position of a string in this array determines the USB string index. For
    //    example, if the product ID string is in ClientStrings[1], then the iProduct field
    //    in the Device Descriptor should also be one (1).
    //  - Tip: This method closely follows the USB specification for strings. See USB 2.0: 9.6.7
    //  - First unused string must be set to NULL (to terminate ASCII to USB string conversion)
    //  - Optimization tip: reduce the size of this array to the minimum string count for your device
    //  - Advanced tip: To save storage or for non-ASCII or language considerations, you can 
    //    modify the API to use pre-translated strings
    PCHAR ClientStrings[NCAPI_MAX_USB_STRINGS];

    ///////////////////////////////////////////////////////////////////////////
    // Copy of most recent eight-byte USB Setup Packet 
    //  - Client applications supporting non-standard USB requests (e.g. USB class 
    //    devices) should parse this setup packet from their non-standard USB request
    //    handler.
    //  - If the client's non-standard request handler successfully handles the request,
    //    it should return Success. Any other return code causes the API to continue
    //    processing the setup packet as a Standard Request (See USB 2.0: 9.4)
    //  - Endianism tip: USB is Little Endian; As shipped, NetChip RDKs assume the CPU is
    //    also Little Endian. The API should translate this setup packet to match the endianism
    //    of the CPU. See WORDBYTE and related macros to help endianism translation
    //  - For Setup Packet content information, see USB 2.0: 9.3
    USB_SETUP_PACKET SetupPacket;

    ///////////////////////////////////////////////////////////////////////////
    // USB configuration number
    //  - May be zero or non zero (see USB 2.0: 9.4.7) but is most often one!
    //  - Client's Set Configuration handler should examine this number. If the
    //    requested configuration is NOT supported by the client, the handler 
    //    should return anything other than Success. Tip: Client Set Configuration
    //    handlers should handle Configuration Zero (de-configured) and One (configured)
    //    successfully. 
    //  - Client must not change this setting
    //  - On root port reset, the API clears the USB configuration number to zero
    NCBYTE UsbConfigurationNumber;

    ///////////////////////////////////////////////////////////////////////////
    // Number of endpoints in the configuration
    //  - Set to the number endpoints counted in the current configuration.
    //  - Set by the API before calling the client's Set Configuration handler, set
    //    to zero by the API when the configuration becomes invalid (e.g host sets 
    //    configuration zero, root port reset). 
    //  - Client must not change this setting
    //  - On root port reset, the API clears the configuration endpoint count to zero
    NCBYTE ConfigurationEndpointCount;

    ///////////////////////////////////////////////////////////////////////////
    // Endpoint Zero is automatically created by the API in its One Time Init
    // routine. 
    //  - Clients handling Class and Vendor requests with a Data Phase specify
    //    a transfer using this structure. 
    //  - From the client perspective, Endpoint Zero works *almost* like data endpoints
    //  - Tip: Unlike data endpoints, Endpoint Zero data phase transfers may 
    //    only be started in the context of Device Request event.
    PNC_ENDPOINT_OBJECT EndpointZero;

    ///////////////////////////////////////////////////////////////////////////
    // Bus speed
    //  - Specifies USB connection speed (HS or FS)
    //  - Bus speed may not be valid until *after* certain setup requests have
    //    been handled. Specifically:
    //     - Get Descriptor (Configuration)
    //     - Get Descriptor (Configuration Other Speed)
    //  - Client must not change Bus Speed
    NC_BUS_SPEED BusSpeed;

    ///////////////////////////////////////////////////////////////////////////
    // USB frame number
    //  - USB frame number is restricted to 11 bits (USB 2.0: 8.4.3)
    //  - The API updates the USB frame number when:
    //     - SOF interrupts have been enabled (which may impact overall performance)
    //     - API is called to update the USB frame (See API Update USB Frame routine)
    UINT UsbFrame;

    ///////////////////////////////////////////////////////////////////////////
    // Extended USB frame number
    //  - USB frame number is updated when:
    //     - SOF interrupts have been enabled (which may impact overall performance)
    //     - API is called to update the USB frame (See API Update USB Frame routine)
    //  - If the extended frame is updated periodically, within about a second,
    //    the extended frame number should stay accurate
    UINT UsbFrameEx;

    ///////////////////////////////////////////////////////////////////////////
    // Host wakeup capability
    //  - If TRUE, this device can wake a suspended host. To wake a suspended
    //    host, the client calls the API's Wake Chip and Host routine.
    //  - Default is FALSE: A suspended host can only be awakened when this boolean
    //    is set TRUE by the host via a Set Feature (DEVICE) request.
    //  - See USB 2.0: 9.4.5, 9.4.9, table 9-6
    //  - Clients should treat this boolean as "Read Only"
    BOOL HostWakeupEnable;

    ///////////////////////////////////////////////////////////////////////////
    // Device event code
    //  - Device event codes are closely associated with the client's Device Event handler. 
    //  - When a device event occurs, the API sets an event-appropriate code and calls 
    //    the client's device event handler.
    //  - Tip: The API initialization routine installs a default handler. The default
    //    handler takes no action. If the client requires event notification, it 
    //    should replace the default handler with its own.
    //  - Tip: Be sure to differentiate device event codes from other API event codes!
    NC_DEVICE_EVENT_CODE EventCode;

    ///////////////////////////////////////////////////////////////////////////
    // USB Power
    //  - USB power available state (Off, On, Suspended)
    //  - When power is On, two USB power levels are available: configured and 
    //    unconfigured. The USB Configuration Number is non-zero when configured.
    NC_USB_POWER UsbPowerState;

    ///////////////////////////////////////////////////////////////////////////
    // NetChip chip state:
    //  - Chip is Running or Suspended
    //  - While suspended, client applications must not call API functions that 
    //    access the chip (except the special chip waking functions).
    NC_CHIP_STATE ChipState;