ncfwapi.c

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.

NCFWAPI.C

NetChip Firmware API. This module interfaces between client applications and
a NetChip chip. This module also relies on a device level module for USB
Chapter Nine (for enumeration and control transfers) and device event support.

NetChip application modules are device independent. They rely on this API to handle
virtually all events, enumeration and low-level transfer details. For instance,
an application provides USB descriptors that uniquely describe the USB device but
the API is responsible for correctly transferring those descriptors to the USB host.
Similarly, the API is responsible for the client application's transfers.

Modules provided by NetChip are ANSI C compliant and designed for portability to 
virtually any platform. Modules include built-in debugging features such as Assert 
and trace logging macros. (RDK customers: Trace logs can be emailed to 
[e-mail] for expert review.)

Application modules are interchangeable, meaning your new platform hardware can be 
tested using selections from NetChip's verification application modules before moving 
on to target platform testing and development. (Tip: Use the RDK for application 
development! Operational device models can be developed using the RDK; that model 
code can be applied to the new target platform!)

Debug and development recommendations: NetChip provides Transfer and Loopback 
application modules for verifying USB transfers on new platforms. Transfer performs
basic IN and OUT transfers for testing a device's first transfers. Once Transfer 
meets expectations, Loopback can be applied to test the system for hours and days.
Loopback endlessly loops OUT data to an IN endpoint. After a few days of successful 
loopback, confidence in the device's electrical, hardware and software systems should 
be very good.

Once Transfer and Loopback tests are completed successfully on a new platform, target 
applications can be developed and tested. NetChip provides several pretested target 
modules, including USB class modules. One of these modules may be an excellent starting 
point to fit your needs. Contact [e-mail].

For best support from NetChip, please maintain this file with as few changes as 
possible. If NetChip re-releases this module with corrections or enhancements, it 
can be updated to target platforms more easily.

NetChip support: If you have technical problems, comments or feedback about this product, 
please contact us: [e-mail]. Please write "Firmware API" in the subject.
In the body, please provide the software release code (e.g. RE010203), the application
filename, the NetChip chip you are using, plus any helpful details.
  
******************************************************************************/

///////////////////////////////////////////////////////////////////////////////
#include <string.h>

///////////////////////////////////////////////////////////////////////////////
#include <NcCommon.h>       // Collection of common NetChip header files
#include <NcDevice.h>       // Useful NET2272 functions, types and macros (for USB transfers, etc.)

///////////////////////////////////////////////////////////////////////////////
#if _NCVIRTUALENDPOINTS
#include <NcVirtEp.h>       // Virtualized endpoint support (up to 30 endpoints)
#endif

///////////////////////////////////////////////////////////////////////////////
#pragma message (_NC_MESSAGE"Recommendation: Port this file directly, without functional changes")
// Few, if any changes should be required when porting this file to other platforms. NetChip
// has taken every effort to make this file applicable for any usage on any platform.
//  - Optimization: After successful porting and all applicable tests pass reliably, unused
//    sections may be discarded. Other sections may be tuned for specific performance.
//  - Please contact NetChip support if this file fails to meet your requirements

///////////////////////////////////////////////////////////////////////////////
// Private definitions

///////////////////////////////////////////////////////////////////////////////
// Private variables

///////////////////////////////////////////////////////////////////////////////
// USB device currently in use
//  - NOTE: this is a private copy of the Device Object normally passed as a parameter
//    between the API and client. For a small performance boost, it is kept here
//    as a global. It is for INTERNAL USE ONLY by the low-level device and API 
//    software, in the context of a "single device model". (Not many devices have
//    more than a single USB connection!)
PNC_DEVICE_OBJECT PrivDeviceObject;

///////////////////////////////////////////////////////////////////////////////
// Remaining variables are private to the API
//  - Advanced tip: The remaining variables *could* exist in the 'private' section
//    of the Device Object. For performance reasons (to eliminate an extra reference), 
//    they are listed here. To support multiple USB devices for instance, these 
//    variables would have to be moved to the device object
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// Currently selected USB configuration (High Speed and Full Speed)
//  - Set appropriately anytime after USB speed (HS/FS) is known, but before
//    returning configuration to the host 
PUSB_CONFIGURATION_DESCRIPTOR UsbConfiguration;
WORDBYTE Sizeof_UsbConfiguration;

///////////////////////////////////////////////////////////////////////////////
// Currently selected "Other Speed" USB configuration (Full Speed or High Speed)
//  - Set appropriately anytime after USB speed (FS/HS) is known, but before
//    returning configuration to the host 
PUSB_CONFIGURATION_DESCRIPTOR UsbConfiguration_OtherSpeed;
WORDBYTE Sizeof_UsbConfiguration_OtherSpeed;

///////////////////////////////////////////////////////////////////////////////
// Array of logical endpoints:
//  - The total number of Endpoint Objects managed by the API, including Endpoint Zero.
//  - The number of endpoints is therefore one plus the maximum number of endpoints
//    in any of the device's configurations.
//  - Usage: The API client application initiates transfers on an endpoint by
//    setting up elements of the endpoint's Transfer Object (address, length, transfer 
//    flags) then calling the API Endpoint Transfer function.
//  - Natural endpoint order: Logical Endpoints are ordered as they are found in 
//    the configuration, starting with one. (Logical Endpoint Zero is reserved for EP0.)
//  - To save some memory, developers may wish to adjust the number of endpoints in this 
//    array to match the maximum number of endpoints required by any single configuration,
//    plus one (to account for endpoint zero).
NC_ENDPOINT_OBJECT LogicalEndpoints[NCAPI_MAX_ENDPOINT_COUNT];

///////////////////////////////////////////////////////////////////////////////
// Each physical endpoint on the NET2272 has a reference to a Logical Endpoint
//  - The size of this array should match the number of physical data endpoints
//    on the chip. It can be less, but changes to the code may be required.
PNC_ENDPOINT_OBJECT PhysicalEndpoints[PHYSICAL_ENDPOINT_COUNT];

///////////////////////////////////////////////////////////////////////////////
// Translated strings, ready for USB host:
//  - For convenience, clients provide ASCII strings, which are translated to 
//    USB strings. The USB strings are referenced here:
PUSB_STRING_DESCRIPTOR UsbStrings[NCAPI_MAX_USB_STRINGS];

// Debug: Section of code is running in a NetChip interrupt context:
//  - Set TRUE when the NetChip interrupt handler starts, set FALSE
//    before the interrupt handler returns.
//  - NetChip API functions are performance-tuned to be called from the
//    context of a NetChip interrupt routine. If a call is made to an
//    interrupt-sensitive API function from a non-NetChip interrupt context,
//    the function should assert to warn the developer. The developer may 
//    add interrupt protection to the API call, or restructure client code
//    to call from an interrupt context.
NCDEBUG(BOOL NcDebug_InterruptContext;)

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

#if _NCDEBUG && _NCVIRTUALENDPOINTS
///////////////////////////////////////////////////////////////////////////////
STATIC void
EpSnapshot(
    PNC_ENDPOINT_OBJECT Endpoint
    )
{   // Debug tool: Safely take a snapshot of important endpoint registers
    //  - Snapshot is added to history log
    //  - Endpoint is paused so that various registers can be read without
    //    content changing in between each read
    NCBYTE EpCfg;

    NCBYTE EpStat0;
    NCBYTE EpBuffStates;
    NCBYTE EpRspSet;
    WORDBYTE EpAvail;

    ASSERT(NETCHIP_READ(PAGESEL) == Endpoint->Priv.PhysEp);
    EpCfg = NETCHIP_READ(EP_CFG);

    // Virtualize endpoint
    //  - Virtualizing the endpoint effectively pauses the endpoint, however
    //    if the host issues tokens to the endpoint while virtualized, a bit in one 
    //    of VIRTOUT0, VIRTOUT1, VIRTIN0 or VIRTIN1 will become set.
    NETCHIP_WRITE(EP_CFG, EpCfg & ~(1<<ENDPOINT_ENABLE));
    // Wait for endpoint to disable
    //  - It may already be disabled
    for (;;)
    {
        if (!(NETCHIP_READ(EP_CFG) & (1<<ENDPOINT_ENABLE)))
        {
            break;
        }
    }

    // Endpoint is now paused
    //  - Various endpoint registers can be read safely without content changing between reads
    EpAvail.Byte[MYEND_LO] = NETCHIP_READ(EP_AVAIL0);
    EpAvail.Byte[MYEND_HI] = NETCHIP_READ(EP_AVAIL1);
    EpStat0 = NETCHIP_READ(EP_STAT0);
    EpBuffStates = NETCHIP_READ(EP_BUFF_STATES);
    EpRspSet = NETCHIP_READ(EP_RSPSET);
    
    HISTO(DEFAULT_HISTORY, "StAv", NCHISTO_TRANSFER(Endpoint), EpStat0, EpAvail.Word);
    HISTO(DEFAULT_HISTORY, "BfRs", NCHISTO_TRANSFER(Endpoint), EpBuffStates, EpRspSet);

    NETCHIP_WRITE(EP_CFG, EpCfg);

    // Wait for endpoint reenable
    //  - NET2272 internally uses a global enable bit. That means this endpoint
    //    may not read back as enabled if another endpoint is currently busy
    for (;;)
    {
        if (NETCHIP_READ(EP_CFG) == EpCfg)
        {
            break;
        }
    }

    // While virtualized, the host may have issued a request to the
    // endpoint (e.g. OUT, IN  or PING token). Clear it to prevent
    // unexpected virtualized interrupts
    //  - In virtually all cases, the host will re-issue the request
    NETCHIP_WRITE(Endpoint->Priv.NcVirtReg, Endpoint->Priv.NcVirtBitMask);
}
#else
#define EpSnapshot(Endpoint)
#endif

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

///////////////////////////////////////////////////////////////////////////////
NCSTATUS
DoNothing_MoreProcessingRequired(
    void * pIgnored
    )
{   // Do nothing, except return More Processing Required
    //  - This routine can be referenced in pointers to functions where no action
    //    is required
    UNREFERENCED_PARAMETER(pIgnored);
    return NCSTATUS_MORE_PROCESSING_REQUIRED;
}

///////////////////////////////////////////////////////////////////////////////
void
DoNothing_Void(
    void * pIgnored
    )
{   // Do nothing, return nothing
    //  - This routine can be referenced in pointers to functions where no action
    //    is required
    UNREFERENCED_PARAMETER(pIgnored);
}

///////////////////////////////////////////////////////////////////////////////
STATIC PUSB_STRING_DESCRIPTOR 
BuildUsbStr(
    char * AsciiStr
    )
{   // Helper: Build a USB string descriptor (USD) from a NULL-terminated ascii string
    //  - Return a pointer to the USD
    //  - See USB 2.0: 9.6.7