ncfwapipriv.h

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

/******************************************************************************

Copyright (C) 2004, NetChip Technology, Inc. (http://www.netchip.com)

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, 
EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

NcFwApiPriv.h

"Private" structures and variables for NetChip NET2272 firmware API. API
clients (e.g. Transfer, Loopback or Mass Storage) should NOT need access
to this file.

Applicability:
 - This file should be included in any firmware application using the NetChip
   firmware API. It specifies structures and variables that the API uses to
   track transfers and device states. Although this file specifies private
   members, for consistency it is compiled with firmware applications. This
   means its members are opaque, and should not be required for use by firmware
   applications. Private members are often useful for statistics and debugging.
  
******************************************************************************/

///////////////////////////////////////////////////////////////////////////////
#ifndef NCFWAPIPRIV_H
#define NCFWAPIPRIV_H

///////////////////////////////////////////////////////////////////////////////
// Number of general purpose endpoints available on a NET2272:
//  - The NET2272 can support three physical or 30 virtualized general purpose endpoints.
//  - General purpose endpoints can be configured for any type or direction. Special-
//    use (i.e. 'dedicated') endpoints and endpoint zero are not general purpose.
//  - NET2272 virtualized endpoints, with appropriate software, supports up to 30 
//    general purpose endpoints (15 IN plus 15 OUT). Note that virtualization cannot
//    be readily applied to Isochronous endpoints.
//  - Without virtualization software, the NET2272 supports the chip's three 
//    general purpose physical endpoints (EPA, EPB, EPC).
#if _NCVIRTUALENDPOINTS
#define NCPRIV_GENERAL_PURPOSE_ENDPOINT_COUNT   30
#else
#define NCPRIV_GENERAL_PURPOSE_ENDPOINT_COUNT   3
#endif

///////////////////////////////////////////////////////////////////////////////
// Single-line compiler statement with (or without) Virtualized Endpoint support:
//  - This macro applies to making a single statement compile (or not compile)
//    depending on whether Virtualized Endpoints are being applied or not
#if _NCVIRTUALENDPOINTS
// Virtualized endpoints are being applied:
//  - Compile statement within the parenthesis
#define NC_VIRT_EP(_x_) _x_
#else
// Virtualized endpoints are being NOT being applied:
//  - Compiler ignores statement within the parenthesis
#define NC_VIRT_EP(_x_)
#endif

///////////////////////////////////////////////////////////////////////////////
// Maximum number of endpoints available on the NET2272:
//  - The NET2272 can support all general purpose endpoints plus Endpoint Zero
#define NCPRIV_MAX_ENDPOINT_COUNT               (NCPRIV_GENERAL_PURPOSE_ENDPOINT_COUNT + 1)

///////////////////////////////////////////////////////////////////////////////
// Minimum endpoint lock time (Applies to virtualized endpoints only)
//  - To prevent endpoint reassignment from 'thrashing' unproductively, endpoints,
//    once assigned, stay locked for a few USB frames (one millesecond per frame).
//  - A virtualized endpoint that has been freshly assigned locks the physical
//    endpoint for this many USB frames:
#define NCPRIV_MIN_LOCK_TIME                    2 

///////////////////////////////////////////////////////////////////////////////
// Debugging: Special parameter for HISTO(), packed with useful endpoint debugging 
// info in a single 32-bit entry. Typically this macro follows the keyword text parameter. 
// It shows:
//  - USB endpoint as referenced by the USB host (0x01, 0x81, ...)
//  - Logical endpoint (as ordered in the client configuration)
//  - Physical NetChip endpoint (EPA, EPB, ...)
//  - (Virtual Endpoints) Swap candidate level (Larger values are better candidates for swapping)
#if _NCVIRTUALENDPOINTS
#define NCHISTO_TRANSFER(e) ( \
    ((e)->Priv.UsbEp<<24) + \
    ((e)->LogicalEp<<16) + \
    ((e)->Priv.PhysEp<<8) + \
    ((e)->Priv.SwapCandidate<<0) + \
    0)
#else
#define NCHISTO_TRANSFER(e) ( \
    ((e)->Priv.UsbEp<<24) + \
    ((e)->LogicalEp<<16) + \
    ((e)->Priv.PhysEp<<8) + \
    0)
#endif  // _NCVIRTUALENDPOINTS

/////////////////////////////////////////////////////////////////////////////
// Interrupt sensitive code section:
//  - Define the beginning and end of a "NetChip Interrupt Sensitive Section"
//  - Code between START and END must be protected from another interrupt
//    that might write to the chip or chip structures within the section
//  - If the section is *always* called in an NetChip interrupt context (i.e. 
//    it can only get called from a NetChip interrupt subroutine) then interrupt
//    protection is not needed. However if the section can be called from, for
//    instance, main(), then NetChip interrupts must be disabled at the START
//    and restored at the END.
#define NC_INTERRUPT_SENSITIVE_SECTION_START ASSERT(NcDebug_InterruptContext || (System_InterruptController(NCSYS_INTERRUPT_STATUS) == NCSYS_INTERRUPT_DISABLE)); {
#define NC_INTERRUPT_SENSITIVE_SECTION_END }

///////////////////////////////////////////////////////////////////////////////
extern struct _NC_ENDPOINT_OBJECT LogicalEndpoints[];
extern struct _NC_ENDPOINT_OBJECT *PhysicalEndpoints[];
extern struct _NC_DEVICE_OBJECT *PrivDeviceObject;


///////////////////////////////////////////////////////////////////////////////
// Chip-specific extension to NetChip standard Endpoint Object
//  - Client applications use members of this structure to get extra chip-specific
//    transfer functionality.
//  - This extension applies only to NetChip's NET2272
//  - For chips that do not need an extension, define this structure as empty
typedef struct NC_ENDPOINT_OBJECT_EXTENSION
{
    // Minimum endpoint lock time (USB frames):
    //  - Prevent endpoint virtualization (i.e. "lock" the endpoint) for some number 
    //    of USB frames
    //  - Applies to NET2272 Virtualized Endpoints
    //  - When a transfer is assigned to a physical endpoint, it can be locked to the
    //    endpoint for some number of frames. This prevents unproductive thrashing that
    //    can occur if lots of virtualized endpoints concurrently require service.
    //  - Set the Minimum Lock Time to the number of USB frames that the endpoint can
    //    hold the time lock
    //  - Tip: Other lock options are available. See Transfer Flags in the Transfer Object
    UINT VirtualEp_MinLockTime;
} NC_ENDPOINT_OBJECT_EXTENSION, * PNC_ENDPOINT_OBJECT_EXTENSION;

///////////////////////////////////////////////////////////////////////////////
// Swap Candidate level
//  - A transfer that is assigned to a physical endpoint may be "swapped out" so 
//    that another endpoint can be assigned the endpoint. 
//  - Each endpoint has a candidacy level indicating how good of a choice it 
//    is for being re-assigned.
//  - The candidacy level can be between Locked (no swapping allowed) and Instant.
//    An Instant endpoint can be reassigned quickly without extra checking or unloading.
typedef enum _NC_SWAP_CANDIDATE
{
    // Unassigned candidate level
    //  - This is an error!
    SwapCandidate_Invalid = 0,     // Error: No level assigned

    // Locked:
    //  - Endpoint is permanently or temporarily locked
    //  - Temporary locks are activated when a logical endpoint gets reassigned
    //    to a physical endpoint. It will remain locked  (i.e. unswappable) 
    //    for a limited number of USB frames. This level prevents unproductive 
    //    swapping. Specifically, it prevents an endpoint from being swapped in 
    //    then immediately swapped out before transferring data.
    //  - Permanent locks apply to mission-critical and iscochronous endpoints.
    SwapCandidate_Locked,

    //  Some bytes transferred
    //  - Some number of bytes were transferred in this interrupt, indicating
    //    the host and endpoint are somewhat active.
    //  - Bytes were transferred in the endpoint handler, but firmware was
    //    able to stay ahead of the endpoint's demand for data. (That is,
    //    firmware can't transfer any bytes on the endpoint until the USB host 
    //    transfers some packets
    //  - IN cost: Cost for reassigning an IN endpoint with this level may be 
    //    high. Data is waiting in the endpoint. If data is still waiting when
    //    the endpoint is unassigned, unsent IN data will be quickly 'rewound' 
    //    back to the Transfer Object. This is unproductive, but demand for
    //    service on other endpoints may take precedence.
    //  - OUT cost: Cost for reassigning an OUT endpoint with this level is 
    //    medium. The endpoint may be momentarily empty, but it is likely that 
    //    the host is sending more packets. If data is in the endpoint when 
    //    unassigned, time must be taken to transfer the data from the endpoint 
    //    to the Transfer Object. 
    SwapCandidate_SomeBytesTransferred,

    // No bytes transferred
    //  - Endpoint does not require immediate service
    //  - The top interrupt loop, handling other endpoints or events, did not
    //    detect the need for service on this endpoint. The endpoint's lock-time
    //    has expired.
    //  - Endpoints at this level are fairly good candidates for reassignment,
    //    as the host does not appear to be very busy with the endpoint
    //  - Cost: Cost for reassignment is the same as for Some Bytes Transferred.
    SwapCandidate_NoBytesTransferred,

    // Transfer completed
    //  - OUT endpoints: This level is set when a client's transfer request 
    //    completes, but without a short packet from the host to terminate
    //    transfer; the endpoint logic may therefore still accept packets,
    //    encurring a potential unloading cost if packets happen to arrive.
    //  - IN endpoints: IN transfer handlers do not set this level, however
    //    other agents may (e.g. Endpoint Transfer, Endpoint Cancel).
    SwapCandidate_TransferComplete,

    // Endpoint can be re-assigned instantly
    //  - The endpoint is assured to be empty, and NAKing any host requests
    //  - Endpoint can be unassigned with the lowest possible cost
    //  - IN endpoints: This level is set when an ACK for the final packet of
    //    an IN transfer has been successfully received.
    //  - OUT endpoints: assigned when a USB Short Packet has been handled
    SwapCandidate_Instant

} NC_SWAP_CANDIDATE, *PNC_SWAP_CANDIDATE;