ncfwapi.h

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

//    exact Max Packet Multiple, bytes will remain unsent in the endpoint; for this
//    case the API returns a Partial Packet warning code. The client must request another 
//    transfer (perhaps with Apply Short Packet, Apply ZLP, size of zero bytes, or 
//    another concatenation), validating at least one USB packet so that unsent 
//    bytes can be transferred to the USB host. 
//  - USB OUT: Concatenation is implied for all Rx transfers. Specifically, bytes
//    remaining in an endpoint after a client request is fulfilled can be retrieved
//    with another non-zero request. Transfer size restrictions may be imposed due
//    to chip bus width and endpoint architectures (e.g. 1, 2 or 4 byte minimum 
//    request size). The API returns Partial Packet warning code if request size is
//    too small to acquire all bytes from the packet.
//  - Virtualized endpoints (e.g. NET2272): To prevent deadlock due to endpoints
//    containing partial packets, client completion routines should start transfers
//    to resolve Partial Packet warnings.
#define NC_TRANSFER_FLAG_APPLY_CONCATENATION    6

///////////////////////////////////////////////////////////////////////////////
// Token Notification
//  - Starting a transfer with this flag causes the API to complete the transfer
//    when an IN or OUT token is detected by the endpoint. No data is transferred.
//  - NOTE: Transfer Size in the Transfer Object *must* be clear; "Apply PIO" 
//    flag *must* also be set, all other transfer flag bits must be clear.
//  - Pending tokens: A notification transfer completes immediately if a token
//    is pending in the endpoint when the notification transfer is started.
//  - OUT Token Notification notes: 
//     - Notification of an OUT token can also mean that some packets are waiting in 
//       the endpoint. Therefore, upon completion, the number  of bytes in the endpoint
//       is reported in Bytes Transferred. Tip: A "Zero Length OUT" transfer is
//       indistinguishable from an OUT token with zero packets! Tip: Some NetChip 
//       endpoint architectures (e.g. NET2270 and NET2272) prevent accounting for bytes 
//       in more than one packet, even though the endpoint may contain up to two packets.
//     - An OUT notification transfer will complete immediately if any packets are waiting
//       in the endpoint (that is, even if the host is NOT issuing OUT tokens). Therefore
//       the client's OUT notification handler should complete OUT data transfers before
//       starting a new OUT notification transfer
//  - Token notification cannot be applied to Isochronous or Endpoint Zero transfers
#define NC_TRANSFER_FLAG_TOKEN_NOTIFICATION     5

///////////////////////////////////////////////////////////////////////////////
// Apply programmed I/O (PIO) instead of DMA
//  - Ignored if DMA not supported
#define NC_TRANSFER_FLAG_APPLY_PIO              4

///////////////////////////////////////////////////////////////////////////////
// Transfer flag extensions
//  - The following transfer flags apply to NetChip chips supporting virtualized endpoints
//  - ADVANCED! In most cases, even with virtualized endpoints, these flags are
//    not required, and can be ignored.
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// Transfer virtualization lock:
//  - Prevent virtualization for the duration of the transfer. If set, this transfer
//    will be locked to a physical endpoint until the transfer completes. During 
//    the transfer, the endpoint will not participate in endpoint virtualization. 
//  - Use this flag for performance-critical transfers
//  - Warning: If the number of transfers using the Endpoint and Transfer Lock 
//    flags exceeds the number of physical endpoints on the chip, a deadlock could 
//    occur.
//  - Warning: When applying the Apply Concatenation flag, the Transfer Lock
//    flag (or the Endpoint Lock flag) must also be set.
#define NC_TRANSFER_FLAG_TRANSFER_LOCK           9

///////////////////////////////////////////////////////////////////////////////
// Endpoint virtualization lock:
//  - Prevent any virtualization of this endpoint. If set, the endpoint will not
//    participate in endpoint virtualization.
//  - Use this flag for isochronous endpoints and mission-critical endpoints
//  - Warning: If the number of transfers using the Endpoint and Transfer Lock 
//    flags exceeds the number of physical endpoints on the chip, a deadlock could 
//    occur.
//  - Warning: When applying the Apply Concatenation flag, the Endpoint Lock
//    flag (or the Transfer Lock flag) must also be set.
#define NC_TRANSFER_FLAG_ENDPOINT_LOCK           8



///////////////////////////////////////////////////////////////////////////////
// 
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// NetChip Transfer Object
//  - Transfer Objects specify information about a single transfer (transfer address, 
//    transfer length and optional transfer flags)
//  - Simple usage: By default, Endpoint Objects refer to a default Transfer Object.
//    The default transfer object can be set to a buffer address, length and flags.
//  - Advanced usage: The Endpoint Object can reference a client-owned Transfer 
//    object which can be switched as transfers complete. This method can be useful 
//    for scatter-gather or concatenated transfers
//  - Starting a transfer: Once the Endpoint Object's Transfer Object is set up, the 
//    client calls the API Endpoint Transfer routine. During the transfer, the API
//    'owns' the Endpoint and Transfer Objects.
//  - Completing a transfer. Upon completion of the client transfer, the API calls
//    the endpoint's Completion Handler. The Endpoint Object specifies a completion code
//  - The API does not modify Transfer Objects, however, the client must not change
//    the Transfer or Endpoint object's contents while it is owned by the API
//  - The API is restricted to handling one transfer per endpoint. That is, many endpoints 
//    may have active transfers at one time, but a single endpoint may NOT have more 
//    than one transfer active at one time. (A client may manage a queue of transfers, 
//    but the API does not manage them!)
//  - Members of this structure marked 'private' should not need to be accessed by 
//    client applications
typedef struct _NC_TRANSFER_OBJECT
{
    ///////////////////////////////////////////////////////////////////////////
    // Transfer start:
    //  - Client sets these values (buffer, size, flags, completion handler) before
    //    starting a transfer
    //  - Tip: These entries are persistent for the life of the transfer (the API will
    //    not disturb contents of this section) so these entries can be recycled
    PVOID TransferBuffer;                   // Address of transfer buffer
    UINT TransferSize;                      // Size of the transfer
    UINT TransferFlags;                     // Flags: e.g. Apply ZLP, ...

    // Transfer completion handler (Required)
    //  - The API calls this transfer completion handler when a USB transfer completes
    //  - Handler runs in an interrupt context, and must therefore return quickly
    //  - A completion handler may safely start a transfer on the same or different endpoint
    //  - For USB IN (Tx), a transfer is complete when the final packet of the transfer
    //    is acknowledged (ACK'd) by the host. This raises a subtle issue if the ACK
    //    is corrupted: The transfer will not complete until the host issues tokens
    //    for the *next* transfer. See USB 2.0: 8.6.4
    //  - For USB OUT (Rx), a transfer is complete when a short packet is read, 
    //    even if there is more space in the Transfer Buffer. Tip: See special
    //    note regarding USB OUT and NC_TRANSFER_FLAG_APPLY_ZLP
    void (*ClientCompletionHandler)(struct _NC_ENDPOINT_OBJECT * Endpoint);

    ///////////////////////////////////////////////////////////////////////////
    // Partial transfer handler (Optional, advanced topic)
    //  - This partial transfer handler is called when some, but not necessarily all, packets
    //    have been transferred. This is an advanced topic! Most clients can simply use
    //    the completion handler, and do not need this handler. It is valuable when the
    //    client must be notified of partial transfers in real-time. It is called when
    //    the API's transfer handler has transferred as many packets as it can; the host
    //    must transfer some packets in or out of the endpoint.
    //  - Generally, this partial transfer handler can NOT be called when DMA is applied
    //  - This handler runs in an interrupt context, and must therefore return quickly
    //  - Updated Transfer members: Bytes Transferred and Completion Status. Completion
    //    Status will always be Status Pending. Bytes Transferred will be a multiple of
	//    the endpoint's Max Packet Size.
	//  - Partial transfer handler is NOT called if:
	//     - All requested bytes are transferred
	//     - A short packet is transferred
	//       Instead, for these cases, the normal completion handler is called
    //  - Does not apply to Endpoint Zero
    //  - Use with care! It is generally unsafe for a partial transfer handler to do 
    //    anything that might alter the endpoint or transfer object. There are 
    //    several subtle, and possibly undocumented restrictions.
    void (*PartialTransferHandler)(struct _NC_ENDPOINT_OBJECT * Endpoint);

    ///////////////////////////////////////////////////////////////////////////
    // 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;

} NC_TRANSFER_OBJECT, * PNC_TRANSFER_OBJECT;


//////////////////////////////////////////////////////////////////////////////
// Endpoint event codes:
//  - The following "non-transfer" events can be associated with an endpoint:
//  - The client application should return More Processing Required for any
//    device events it does not specifically handle.
typedef enum _NC_ENDPOINT_EVENT_CODE
{
    //////////////////////////////////////////////////////////////////////////
    // Event unknown 
    //  - This is an error, and should never occur!
    NC_ENDPOINT_EVENT_UNKNOWN = 0,

    //////////////////////////////////////////////////////////////////////////
    // Endpoint stall has been set or cleared:by the host
    //  - See USB 2.0: 9.4.1 or 9.4.9
    //  - Note: If an endpoint is stalled after a transfer is started, the API 
    //    does not automatically stop the transfer
    NC_ENDPOINT_EVENT_SET_CLEAR_STALL,

    //////////////////////////////////////////////////////////////////////////
    // Surprise transfer cancellation
    //  - The transfer was cancelled by surprise (usually, due to an unplug event)
    NC_ENDPOINT_EVENT_SURPRISE_CANCEL_TRANSFER,

    //////////////////////////////////////////////////////////////////////////
    // Surprise close:
    //  - Usually, a surprise close means the device is being reset or deconfigured
    //  - The client may wish to free buffers associated with this endpoint
    NC_ENDPOINT_EVENT_SURPRISE_CLOSE,

    // Placeholder: End of event code list (not a valid event code!)
    END_OF_NC_ENDPOINT_EVENT_CODES
} NC_ENDPOINT_EVENT_CODE;

///////////////////////////////////////////////////////////////////////////////
// NetChip Endpoint Object
//  - Every endpoint supported by the chip has an associated endpoint object
//    that describes the endpoint, its transfer, and its state
typedef struct _NC_ENDPOINT_OBJECT
{
    ///////////////////////////////////////////////////////////////////////////
    // Endpoint's current Transfer Object
    //  - Before starting a transfer, this entry *must* refer to a valid Transfer Object.
    //  - The client may manage its own transfer objects, or, for the simplest of 
    //    endpoint implementations, the client may use the default Transfer Object. 
    //  - Upon successful initialization, of the endpoint, this transfer object 
    //    refers to the endpoint's Default Transfer Object.
    PNC_TRANSFER_OBJECT Transfer;

    ///////////////////////////////////////////////////////////////////////////
    // Transfer completion values:
    //  - The API sets these values before calling the Client Completion Handler (or 
    //    the client's Partial Transfer Handler)

    ///////////////////////////////////////////////////////////////////////////
    // Completion status code
    //  - Before the API calls the transfer completion handler, the API sets this
    //    status code. Any code other than Success indicates the client should take
    //    further action.
    //  - Tip: The client's Partial Transfer handler will see a Pending status.
    NCSTATUS CompletionStatus;

    ///////////////////////////////////////////////////////////////////////////
    // Number of bytes actually transferred
    //  - Before the API calls the transfer completion handler, the API sets this
    //    value to the number of bytes actually transferred.
    UINT BytesTransferred;

    ///////////////////////////////////////////////////////////////////////////
    // Logical endpoint number:
    //  - Logical endpoint numbers correspond to the ordinal position of endpoints
    //    in the configuration, starting with endpoint number one. Specifically, the 
    //    first endpoint found in the configuration is Logical Endpoint one, the next 
    //    is Logical Endpoint two, and so on. (Zero is reserved for Endpoint Zero.)
    //  - Non-zero logical endpoint numbers are assigned by the API in the API's Set
    //    Configuration routine. (Unless trapped by the client, the Set Configuration 
    //    routine is called automatically on Set Configuration request from the host,
    //    followed by a Set Configuration event sent to the client.)