ncfwapi.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.

NCFWAPI.H

NetChip Firmware API: Structures, macros and functions shared between NetChip's 
firmware API and high-level applications.

NetChip's firmware API provides a standardized, portable, chip-independent interface 
between high-level applications such as Transfer, Loopback, Mass Storage, Printer, ...) 
and a NetChip USB interface controller (e.g. NET2272, NET2280, ...). 
 - Sources for NetChip's API and applications are ANSI C compliant. 
 - The API (using Mass Storage on the NetChip NET2272 RDK) passes USB compliance

Overview of NetChip's API structure:
 - Application  (e.g. Transfer.C, Loopback.C MassStor.C, Printer.C)
 - NetChip API  (Middle software layer - Interrupts, DMA, Chapter Nine, transfer handlers)
 - NetChip HAL  (Lowest software layer - Chip read, chip write)
 - Chip         (Hardware - NET2280, NET2272, ...)

NetChip's API is the chip-dependent workhorse layer. It is responsible for USB Chapter
Nine compliance  (including enumeration) and USB transfers.  The HAL is a thin "platform 
dependent" layer for reading and writing NetChip chip registers.

NetChip provides several interchangeable applications ready to port to virtually
any platform: Basic stand-alone applications, Transfer and Loopback, respectively are 
used for bringing up and performing extended-duration transfer tests on new platforms. 
Other applications include USB class applications such as Mass Storage and Printer. One 
or more of these applications may serve as an excellent starting point for a new product
solution. NetChip is continually releasing applications. Contact [e-mail].

Debugging: NetChip API software includes several built-in, portable debugging features.
These features can be enabled or disabled using compile-time switches; they may be 
modified by the developer as needed. Overview:
 - Assert       Alerts developer to situations that could lead to catastrophic failure
 - History      Efficiently logs critical API code branches (logs can be emailed 
                to [e-mail] for review)
 - Statistics   Helps to "performance-tune" software

For engineering support, updates, or to find out about new applications, please contact:
  - [e-mail]

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

///////////////////////////////////////////////////////////////////////////////
#ifndef NCFWAPI_H
#define NCFWAPI_H

///////////////////////////////////////////////////////////////////////////////
// Data type for USB and NetChip byte-sized values
//  - For USB and NetChip there are many 8-bit data types applied, but your
//    compiler or CPU may be more efficient passing its native 'unsigned int' type. 
//  - Here, you can apply any unsigned data type that is most efficient for 
//    your compiler or CPU. 
//  - For example, in most 8051 compilers, the 'unsigned int' type resolves
//    to a 16-bit type, which is not as efficient as an 8-bit type.
//  - Warning: Although the name implies BYTE, it may resolve to something else!
typedef UINT NCBYTE, * PNCBYTE;

///////////////////////////////////////////////////////////////////////////////
// 'Private' members of NetChip's firmware API
//  - Client application firmware should not require access to private API content
#include "NcFwApiPriv.h"

///////////////////////////////////////////////////////////////////////////////
// Forward references to structures:
//  - Required when a structure member references its containing structure
struct _NC_ENDPOINT_OBJECT;
struct _NC_DEVICE_OBJECT;

///////////////////////////////////////////////////////////////////////////////
// NetChip status code constants
//  - Status codes can be returned by the API and the application
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// Status: Success code is always zero
#define NCSTATUS_SUCCESS                    0x00

///////////////////////////////////////////////////////////////////////////////
// Status: Warnings and non-failing status codes are positive:

///////////////////////////////////////////////////////////////////////////////
// Warning: Status pending
//  - The transfer object is still active in the API, probably waiting on the host
//  - Clients should NOT modify the transfer object or the memory it references
//    while the transfer is pending
#define NCSTATUS_PENDING                    0x01

///////////////////////////////////////////////////////////////////////////////
// Warning: Partial packet is in the endpoint:
//  - Transfer request completed, but some number of unhandled bytes are in the 
//    endpoint. Further action *must* be taken by the client in order for the host 
//    to transfer more USB packets
//  - IN: This warning cccurs only when concatenation is applied. If the client's
//    concatenated transfer request results in some bytes left in the endpoint, 
//    this warning is returned. The client must issue another request to validate 
//    endpoint contents. Tip: if the request results in an exact multiple of the 
//    endpoint's maximum packet size, endpoint content is automatically validated, 
//    and this warning is NOT returned.
//  - OUT: This warning indicates bytes of a USB transfer remain in the endpoint;
//    it can occur when the client's requested transfer size is smaller than the
//    number bytes in the endpoint. The client must make another non-zero transfer 
//    request. Tip: Due to chip endpoint structure, the requested size may need to 
//    be at least as large as the chip bus width!
//  - NetChip endpoint virtualization (e.g. NET2272): Endpoints containing partial
//    packets cannot be virtualized. To prevent virtualization deadlock due 
//    to endpoints containing partial packets, clients should resolve partial
//    packets from their transfer completion routines.
#define NCSTATUS_PARTIAL_PACKET             0x02

///////////////////////////////////////////////////////////////////////////////
// Warning: Endpoint is empty
//  - Applies to cancelled IN transfers
//  - Differentiates zero bytes transferred from a ZLP transferred.
//  - On cancellation, the API reports the number of bytes transferred. This 
//    warning is returned if zero bytes were transferred. Contrast this with a 
//    transferred ZLP: If a ZLP is transferred before the transfer is cancelled,
//    the API reports zero bytes but without this warning.
#define NCSTATUS_EMPTY                      0x03

///////////////////////////////////////////////////////////////////////////////
// Warning: More processing required
//  - A function returning More Processing Required took no action. In most cases
//    the calling function recognizes this code to mean that it must apply a default
//    action. For instance, a client should return More Processing Required for
//    events that it does not handle in its event handlers. The API will apply 
//    default action.
#define NCSTATUS_MORE_PROCESSING_REQUIRED   0x04

///////////////////////////////////////////////////////////////////////////////
// Status: Failure status codes are negative:
#define NCSTATUS_UNSUCCESSFUL               (NCBYTE)-0x01
#define NCSTATUS_CLIENT_CANCEL              (NCBYTE)-0x02   // Cancellation by client (usually a transfer)

///////////////////////////////////////////////////////////////////////////////
// NetChip API status values fit the CPU's preferred width:
typedef UINT NCSTATUS, *PNCSTATUS;

///////////////////////////////////////////////////////////////////////////////
// Handy macro to make a USB endpoint descriptor (USB_ENDPOINT_DESCRIPTOR) suitable
// for USB configurations:
#define NC_MAKE_ENDPOINT_DESCRIPTOR(EpType, EpDir, EpMaxPkt, EpAddr,  EpPoll)   \
    sizeof(USB_ENDPOINT_DESCRIPTOR),    /* BYTE bLength; */                     \
    ENDPOINT_DESC,                      /* BYTE bDescriptorType; */             \
    (BYTE)EpDir | (BYTE)EpAddr,         /* BYTE bEndpointAddress; */            \
    EpType,                             /* BYTE bmAttributes; */                \
    NC_LOBYTE(EpMaxPkt),                /* BYTE wMaxPacketSizeLo; */            \
    NC_HIBYTE(EpMaxPkt),                /* BYTE wMaxPacketSizeHi; */            \
    EpPoll                              /* BYTE bInterval; */


///////////////////////////////////////////////////////////////////////////////
// Default endpoint mapping
//  - When created, logical endpoints can be mapped to specific netchip endpoints
//    In most cases, default mapping is appropriate. For these endpoints, use the
//    Default Endpoint Mapping value as the mapping parameter to the API's Endpoint 
//    Create function.
//  - When specific NetChip endpoints must be mapped to logical endpoints, specify
//    the NetChip endpoint (EPA, EPB, ...) for the mapping parameter.
//  - See NcApi_EpCreate()
#define NC_DEFAULT_ENDPOINT_MAPPING 0

///////////////////////////////////////////////////////////////////////////////
// Endpoint Zero maximum packet size
//  - Required by application's Device Descriptors
#ifndef EP0_MAX_PACKET_SIZE
#define EP0_MAX_PACKET_SIZE         0x40
#endif


///////////////////////////////////////////////////////////////////////////////
// Maximum number of general purpose endpoints available
//  - General purpose endpoints can be configured for any type or direction. Special-
//    use (i.e. 'dedicated') endpoints and endpoint zero are not general purpose.
//  - Tip: Chips supporting Virtualized Endpoint technology can be support up to 31
//    endpoints: 15 IN plus 15 OUT plus EP0. (Restrictions exist for ISOCH endpoints)
#define NCAPI_GENERAL_PURPOSE_ENDPOINT_COUNT    NCPRIV_GENERAL_PURPOSE_ENDPOINT_COUNT

///////////////////////////////////////////////////////////////////////////////
// Maximum number of endpoints available
//  - Absolute maximum endpoints the chip can support, including Endpoint Zero,
//    dedicated endpoints and general purpose endpoints
#define NCAPI_MAX_ENDPOINT_COUNT                NCPRIV_MAX_ENDPOINT_COUNT


///////////////////////////////////////////////////////////////////////////////
// Maximum number of USB strings API will support
//  - API client may change this value to specify the minimum number of strings 
//    required by the device
//  - Most devices require only a three or four USB strings
#define NCAPI_MAX_USB_STRINGS               10  

///////////////////////////////////////////////////////////////////////////////
// NetChip transfer flags
//  - Transfer flags control transfer characteristics, such as ZLP handling
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// Apply Zero Length Packet (ZLP)
//  - USB IN: If the client sets this flag and the transfer results in an exact 
//    multiple of the endpoint's Max Packet size bytes in the endpoint, the API 
//    will add a ZLP to terminate the USB transfer. 
//  - USB OUT: Expect (i.e. wait for) one more packet if an Rx transfer combined
//    with the client's request results in an exact packet multiple. For instance,
//    if Apply ZLP is set AND the client request is an exact multiple of the endpoint's
//    Max Packet size AND the host sends exactly that many bytes, then the transfer 
//    will NOT complete. The host must send one more packet for the API to complete
//    the transfer. Typically, the host will send a ZLP. If it is NOT a ZLP, some 
//    amount of data remains in the endpoint; the API returns Partial Packet code;
//    the client should issue another request to acquire remaining data from its 
//    Completion Handler.
#define NC_TRANSFER_FLAG_APPLY_ZLP              7

///////////////////////////////////////////////////////////////////////////////
// Concatenating transfers (Advanced)
//  - Using concatenation, a single USB transfer can be formed by joining several 
//    client transfer requests.
//  - Concatenation is useful for breaking up a single USB transfer into segments, 
//    such as for arbitrary message headers preceding a data block.
//  - Recommendation (advanced): Apply Scatter/Gather list techniques to build a USB 
//    transfer from several Transfer Objects; use each transfer's completion handler
//    to reference and start the next Transfer Object in the list.
//XXXXXXXXXXXXXXX With preloading, we don't need artificial interrupts!
//  - Note: Concatenation may incur 'artificial' interrupts. The API may use a self-
//    interrupting technique to process some concatenations. (The firmware tricks
//    itself into treating concatenations as interruptable USB packet transfers.)
//  - With concatenation, transfer size and alignment restrictions may be imposed by
//    the chip and endpoint architecture. For instance, on NetChip's NET2280, the 32 
//    bit PCI bus interface to the endpoint FIFOs dictates that concatenated transfers 
//    must be aligned to double-word boundries and the transfer size must also be
//    double- word aligned. 
//  - USB IN: If a concatenated Tx request results in a transfer that is not an