ncfwapi.h

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

    ///////////////////////////////////////////////////////////////////////////
    // Device event handler
    //  - The device event handler is closely associated with device event codes.
    //  - See Device Event Code
    NCSTATUS(*DeviceEventHandler)(struct _NC_DEVICE_OBJECT * DeviceObject);

    ///////////////////////////////////////////////////////////////////////////
    // API client may place any private context here (at any time!)
    //  - Client contexts are ignored by the API
    //  - More context entries can be added as needed
    void * ClientContext1;

    ///////////////////////////////////////////////////////////////////////////
    // Chip-specific extension to Device Object
    //  - Client applications may find extra chip-specific device-level support
    //    in this structure.
    //  - Not defined for all chips!
    NC_DEVICE_OBJECT_EXTENSION Ex;

    ///////////////////////////////////////////////////////////////////////////
    // Private Device Object members
    //  - Private members are used by the API to support the device-level operations
    //  - Client applications should not require access to members of this structure
    //  - Not defined for all implementations!
    NC_PRIVATE_DEVICE_OBJECT Priv;

} NC_DEVICE_OBJECT, *PNC_DEVICE_OBJECT;

///////////////////////////////////////////////////////////////////////////////
// NetChip interrupt handler:
//  - When the NetChip interface controller asserts its IRQ# pin, the system
//    interrupt controller transfers control to NetChip Interrupt Handler. This
//    handler responds to chip status as appropriate, including handling standard USB
//    requests, continuing USB transfers, and dispatching to client functions.
void
Nc_InterruptHandler(
    void
    );

///////////////////////////////////////////////////////////////////////////////
// DMA interrupt handler:
//  - When the system DMA controller asserts its interrupt pin, the system 
//    interrupt controller transfers control to this DMA Interrupt Handler. 
//    Each DMA controller implementation is different. Methods applied by
//    NetChip may not be appropriate for your implementation
void
Dma_InterruptHandler(
    void
    );

///////////////////////////////////////////////////////////////////////////////
// API functions called by API client
//  - API client examples include Transfer, Loopback, Mass Storage, etc.
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// One-time initialization
//  - Called by API client to initialize USB subsystem
//  - Client provides structure defining the USB device (USB descriptors, various
//    callback entry points, etc.)
//  - 'Creates' endpoint zero
//  - Upon successful return, the USB subsystem is ready for enumeration. The
//    client can call the API USB Enable routine to activate the connection to 
//    the USB host.
NCSTATUS
NcApi_OneTimeInit(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Clean up USB subsystem for shutdown
//  - Disconnect from USB
//  - Free any API memory allocations
void
NcApi_CleanUp(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Called by an atexit() handler
//  - The application is shutting down
void
Nc_AtExit(
    void
    );

///////////////////////////////////////////////////////////////////////////////
// Electrically connect the NetChip USB interface controller to the USB
void
NcApi_UsbEnable(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Electrically disconnect the NetChip USB interface controller to the USB
void
NcApi_UsbDisable(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Enable SOF interrupts
//  - Client SOF handler, specified in the Device Object, will be called on every SOF event
//  - Tip: On some platforms, interrupting on every SOF can be too time consuming
void
NcApi_SofEnableInterrupt(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
void
NcApi_SofDisableInterrupt(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
void
NcApi_UpdateUsbFrame(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Suspend chip:
//  - Place the NetChip chip into its low-power suspend mode
//  - Once suspended:
//     - The chip's clock stops
//     - Any components relying on the chip's clock output pin stop
//  - The chip should NOT be suspended if the host is not suspended
//  - Chip wakeup:
//     - Host resume: When host signalling resumes, the chip wakes up. When wakeup
//       completes, a Resume event is issued to the client.
//     - Wakeup the chip: Call the API Wakeup Chip function (Tip: When suspended 
//       with I/O Wakeup Enable TRUE, *any* chip access can wake the chip.)
//     - Noise on the USB Dp/Dm pins may cause the chip to wake up. In this case,
//       a Chip Wakeup event is issued to the client
void
NcApi_SuspendChip(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Wakeup chip:
//  - Clients call this routine to awaken a suspended chip. When the wakeup completes
//    a Chip Wakeup event is signalled to the client
//  - Wakeup Chip is different than Wakeup Host! A suspended chip must be awakened
//    before calling the Wakeup Host function.
//  - Wakeup notes:
//     - If the chip was suspended with I/O Wakeup Enable TRUE, it can be awakened
//       by calling the API's Wakeup Chip function. When the wakeup completes, a
//       Chip Wakeup event is issued to the client. Tip: When suspended with I/O 
//       Wakeup Enable TRUE, *any* chip access can wake the chip.
//     - If the chip is suspended with I/O Wakeup Enable FALSE, the chip cannot be
//       awakened by a chip access or any API function.
void
NcApi_WakeupChip(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Wakeup host:
//  - A suspened host can be awakened by using the API's Wake Host
//    routine. The host must first enable this feature (See USB 2.0: 9.2.5.2)
//  - If the chip is suspended, it must be awakened before awakening the host. 
//    (See the API Wakeup Chip function)
void
NcApi_WakeupHost(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Update HS and FS configurations:
//  - ADVANCED! Devices supporting multiple configurations may need to apply this
//    routine.
//  - Overview: In the client's Set Configuration request handler, the client installs
//    new FS and HS configurations into the Device Object, calls this routine to 
//    adjust the new configurations, then calls the API Set Configuration handler
//    to count and prepare endpoints specified in the configuration
//  - See API Set Configuration routine
void
NcApi_UpdateHsFsConfigurations(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Set Configuration:
//  - ADVANCED! Devices supporting multiple configurations may need to apply this
//    routine.
//  - Overview: In the client's Set Configuration request handler, the client installs
//    new FS and HS configurations into the Device Object, calls the Update HS
//    and FS Configurations routine to adjust the new configurations, then calls 
//    this routine to count and prepare endpoints specified in the configuration
//  - See API Update HS and FS Configuration routine
void
NcApi_SetConfiguration(
    PNC_DEVICE_OBJECT DeviceObject
    );

///////////////////////////////////////////////////////////////////////////////
// Create an endpoint:
//  - On successful endpoint creation the API returns an Endpoint Object
//  - Can be called anytime after the device has been configured. This includes the 
//    client's Set Configuration handler.
//  - Logical Endpoint parameter: A Logical Endpoint refers to the ordinal position
//    of the endpoint in the current configuration, starting with one (Zero is 
//    reserved for Endpoint Zero). The first endpoint in the configuration is 
//    logical endpoint one, and so on.
//  - Clients specify transfer buffer information in Transfer Objects, then call
//    the API Endpoint Transfer routine to initiate the transfer
//  - "Map To NetChip Endpoint": Logical endpoints can be mapped to specific NetChip
//    endpoints. Some NetChip devices have endpoints with dedicated, specific features
//    and functionality. Set this parameter to the specific NetChip endpoint to map to
//    the logical endpoint. Set it to Default Endpoint Mapping to let the API determine
//    appropriate programming. (Note: The API ignores this parameter if all endpoints in
//    the chip are uniform data endpoints, such as the NET2272.)
//  - Returns NULL if endpoint cannot be created
PNC_ENDPOINT_OBJECT
NcApi_EpCreate(
    NCBYTE LogicalEp,   // Endpoint's ordinal position in configuration (One-based or Zero for EP0)
    NCBYTE MapToNcEp    // (Optional) Map the logical endpoint to this NetChip endpoint
    );

///////////////////////////////////////////////////////////////////////////////
// Close an endpoint
//  - API tears down internal endpoint structures
void
NcApi_EpClose(
    NCBYTE LogicalEp    // Endpoint's ordinal position in configuration (One-based or Zero for EP0)
    );

///////////////////////////////////////////////////////////////////////////////
// Returns an Endpoint Object for the specified USB endpoint
//  - Returns NULL if no Endpoint Object matches the USB endpoint
PNC_ENDPOINT_OBJECT
NcApi_Fi