ncfwapipriv.h

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

///////////////////////////////////////////////////////////////////////////////
// API's private members of an endpoint object:
//  - This 'private' structure is a sub-structure of a standard Endpoint Object
//  - Generally, client applications should not need access to these members, as
//    some members are chip-specific, and others may be subject to change.
typedef struct _NC_PRIVATE_ENDPOINT_OBJECT
{
    ///////////////////////////////////////////////////////////////////////////
    // Private firmware API members:
    //  - Client applications should not require access to these members. (Accessing
    //    these members from a client app could cause problems!)

    // Transfer information
    //  - Address and count of the current transfer
    PBYTE pPkt;                  // Pointer to the packet being transferred
    UINT BytesRemaining;         // Bytes remaining in transfer

    // Packet handler function
    //  - Transfers USB packets between an endpoint and memory using 
    //    Programmed I/O methods (not DMA)
    void (*PioPacketHandler)(struct _NC_ENDPOINT_OBJECT * Endpoint);

    // Endpoint's Maximum Packet Size:
    //  - This value is extracted from the Endpoint Descriptor returned to the host
    //  - The same value is programmed into NET2272 EP_MAXPKT0, EP_MAXPKT1 registers
    //  - Keep Max Packet Size here, for quick reference
    WORDBYTE EpMaxPkt;

    // USB endpoint's physical NET2272 endpoint
    //  - A USB data endpoint (0x80, 0x81, ...) can be mapped to any NET2272
    //    physical endpoint (EPA, EPB, ...)
    BYTE PhysEp;

    //XXXXXXXXXXXXX FIX COMMENTS! ALSO APPLIES TO CONCATENATION!!!!!!!
    // Used for rewinding virtualized IN transfers 
    UINT LastPacketSize;

#if _NCVIRTUALENDPOINTS
    ///////////////////////////////////////////////////////////////////////////
    // NetChip Virtualized Endpoint support:
    //  - Virtualized endpoints are specific to the NET2272
    //  - This section holds transfer state information until it can be applied (or
    //    reapplied) to an available physical endpoint.
    //  - During a single transfer (particularly at times when the host's demand for
    //    endpoints exceeds the number of endpoints physically available on the NET2272) 
    //    transfers may become 'virtualized'. Transfer state information will be swapped 
    //    in and out of physical endpoints.
    //  - Virtualized transfer state information includes copies of endpoint registers
    //    as well as various maintenance states.

    // Endpoint's swap priority level:
    //  - Endpoints with highest swap levels are the best candidates for reassignment
    NC_SWAP_CANDIDATE SwapCandidate;

    // Reassignment candidate:
    //  - Used within the reassignment sections, the Reassignment Candidate value helps the
    //    program determine which endpoint contains packets. There is a time penalty to
    //    reassign endpoints that contain packets; empty endpoints that NAK host
    //    requests reassign faster.
    NC_SWAP_CANDIDATE ReassignmentCandidate;

    // Quickly test for active packets 
    //  - Part of the endpoint unassignment strategy to make effecient use of time
    //  - The function tests for active packets (one for Tx, one for Rx)
    //  - The function returns an Active Packets boolean. If TRUE, the 
    //    endpoint is NOT the best choice for unassignment (because packets must
    //    be saved before it can be unassigned)
    BOOL (*TestActivePackets)(struct _NC_ENDPOINT_OBJECT * Endpoint);

    // Endpoint lock time (in USB frames):
    //  - Transfer has been assigned to this physical endpoint for this many USB 
    //    frames (since the transfer was started or restarted):
    //  - The endpoint can be reassigned (i.e. swapped out) to a new transfer
    //    when this Frame Count exceeds a "lock time" limit specified for this 
    //    endpoint. This mechanism prevents firmware from excessive, unproductive 
    //    reassignment of virtualized endpoints.
    UINT FrameCount;

    // Helpers to quickly get NAK status from VIRTOUT0, VIRTOUT1, VIRTIN0, VIRTIN1 registers
    //  - Each virtual endpoint maps to exactly one bit in one of the four VIRTXXX register.
    //  - For better performance we keep the address and a bit mask to quickly test for an 
    //    endpoint's NAK status. 
    //  - NET2272 Data Sheet: "For example, if the host requests an IN on endpoint 3 [. . .], 
    //    bit 3 of the VIRTIN0 register is set (and the Net2272 NAKs the IN request)."
    //     - In other words, if the virtual endpoint's VIRTXXX bit is set, the endpoint requires 
    //       service. The virtual endpoint should be assigned to a physical endpoint, whereupon
    //       the transfer starts or continues. Tip: The state of the physical endpoint must be
    //       saved before the virtual endpoint can be assigned to it!
    BYTE NcVirtReg;             // One of VIRTOUT0, VIRTOUT1, VIRTIN0, VIRTIN1
    BYTE NcVirtBitMask;         // A single bit identifying an endpoint in a VIRTXXX register

    ///////////////////////////////////////////////////////////////////////////
    // NET2272 virtualized endpoint registers (and buffers)
    //  - Following are copies of NET2272 endpoint registers used for endpoint virtualization

    // Dynamic virtualized endpoint registers
    //  - These registers can change while an endpoint is assigned, and therefore need to be 
    //    saved between reassignments:
    BYTE EpRsp;                  // EP_RSPSET (and EP_RSPCLR)
    BYTE EpIrqEnb;               // EP_IRQENB

    // Persistent virtualized endpoint registers
    //  - These endpoint registers values are constant for the life of the configuration,
    //    and therefore do not need to be saved when swapping endoints:
    BYTE EpCfg;                  // EP_CFG

    //XXXXXXXXXXXXXX Comment please?????????
    BOOL Virtualized;
#endif  // _NCVIRTUALENDPOINTS

#if _NCSTATISTICS
    ///////////////////////////////////////////////////////////////////////////
    // Statistical transfer counters
    //  - Statistics should not appear in final release!

    // Total number of bytes transferred on this endpoint
    UINT TotalBytesTransferred;

    // Number of completed transfers on this endpoint
    //  - Reflects number of calls to NcApi_EpTransfer()
    UINT TotalTransfers;

    // Number of times the endpoint for this transfer was disabled because it
    // tested to be a possible candidate for reassignment
    //  - Chosen before OUT endpoint retest!
    UINT Reassign_Possible;

    // Number of times this virtualized endpoint's transfer could be re-assigned 
    // instantly to physical endpoint.
    //  - If one of the assigned physical endpoints is in a "Short Packet Transferred"
    //    state, then that endpoint can be re-assigned to a virtualized endpoint's
    //    transfer instantly, without unloading, rewinding, etc.
    //  - This statistic indicates the fastest, most efficient endpoint reassignment
    UINT Reassign_Instantly;

    // Number of times this transfer was the best choice for re-assignment 
    // because its endpoint was empty
    UINT Reassign_EmptyEp;

    // Number of times this transfer required saving before it could be reassigned
    //  - This statistic indicates more time-consuming endpoint reassignment
    //  - Saving IN transfers is worse than saving OUT transfers: Saving an IN transfer
    //    means data in the IN endpoint is thrown away, and must eventually be written 
    //    again (i.e. rewound). Saving OUT data simply requires time to save the OUT
    //    data before the endpoint can be reassigned
    UINT Reassign_SavedEp;

    // Number of bytes rewound (saved) on IN transfer
    //  - Applies to IN transfers only
    //  - This static indicates time wasted. Bytes (up to two packets) were written
    //    to an IN endpoint, but due to re-assignment, must be written again
    UINT Reassign_BytesRewound;

    // Number of times this OUT endpoint, on a retest, contained packets
    //  - Applies to OUT endpoints only
    UINT Reassign_OutNowContainsPackets;
#endif

#if _NCDEBUG || _NCHISTO || _NCSTATISTICS
    ///////////////////////////////////////////////////////////////////////////
    // Debugging variables
    BYTE UsbEp;
#endif

} NC_PRIVATE_ENDPOINT_OBJECT, * PNC_PRIVATE_ENDPOINT_OBJECT;

/******************************************************************************
Chip-specific extension to Device Object
 - This implementation does not require Device Object extensions

///////////////////////////////////////////////////////////////////////////////
// Chip-specific extension to NetChip's standard Device Object
typedef struct _NC_DEVICE_OBJECT_EXTENSION
{
    UINT AddExtensionHere;
} NC_DEVICE_OBJECT_EXTENSION, * PNC_DEVICE_OBJECT_EXTENSION;
******************************************************************************/
typedef void * NC_DEVICE_OBJECT_EXTENSION;

/******************************************************************************
Private members in Device Object:
 - This implementation does not require private members in the Device Object
 - An application using more than one NetChip interface controller could move
   device variables into this structure facilitating multiple device management,
   however it would add an extra reference, slightly reducing performance.

///////////////////////////////////////////////////////////////////////////////
// API's private members of the Device Object
//  - Clients should not require access to these members
typedef struct _NC_PRIVATE_DEVICE_OBJECT
{
    UINT AddPrivateMemberHere;
} NC_PRIVATE_DEVICE_OBJECT, * PNC_PRIVATE_DEVICE_OBJECT;
******************************************************************************/
typedef void * NC_PRIVATE_DEVICE_OBJECT;

///////////////////////////////////////////////////////////////////////////////
#endif // NCFWAPIPRIV_H

///////////////////////////////////////////////////////////////////////////////
//  End of file
///////////////////////////////////////////////////////////////////////////////