pcidp_if.h

一个amccs5933芯片的驱动程序开发源程序和部分文档

//*****************************************************************************
// Copyright (C) 2000, Cypress Semiconductor.
//
// ALL RIGHTS RESERVED.  USE, DISCLOSURE, OR REPRODUCTION WITHOUT WRITTEN 
// PERMISSION OF CYPRESS SEMICONDUCTOR IS PROHIBITED.
//
//
// This is PCIDP_IF.h.  It is the C langauage Application Program Interface 
// (API) for the PCI-DP CY7C09449PV-AC kernel driver.  The API is implemented 
// in C language protocol which means it can also be used from C++ or assembly
// language.  Access is via subroutine calls.  The return codes are valid 
// Windows system error codes.
//
// NOTE: for optimal readability set your TABs option to 2 spaces.
//*****************************************************************************



#ifndef _PCIDP_IF_H
#define _PCIDP_IF_H


// API users can ignore this define sequence.
#ifndef out
#define out
#endif
#ifndef in
#define in
#endif


// Interrupt types used with the RegisterInterrupt service.
#define PCIDP_PCIMasterAbort 0x200
#define PCIDP_PCITargetAbort 0x100
#define PCIDP_I2OOutboundPostFIFONotEmpty 0x80
#define PCIDP_DMAComplete 0x20
#define PCIDP_LocalToHostExternalSignal 0x10
#define PCIDP_LocalToHostMailbox 8
#define PCIDP_I2OPCIFIFOOverflow 2

// Structure type used with the Get and Set PCI Configuration services.
typedef struct _tagPCIDP_CONFIG {
	unsigned short VendorID;
	unsigned short DeviceID;
	unsigned short Command;
	unsigned short Status;
	unsigned char RevisionID;
	unsigned char ProgIF;
	unsigned char SubClass;
	unsigned char BaseClass;
	unsigned char CacheLineSize;
	unsigned char LatencyTimer;
	unsigned char HeaderType;
	unsigned char BIST;
	unsigned long BaseAddresses[6];
	unsigned long CIS;
	unsigned short SubVendorID;
	unsigned short SubSystemID;
	unsigned long ROMBaseAddress;
	unsigned long Reserved2[2];
	unsigned char InterruptLine;
	unsigned char InterruptPin;
	unsigned char MIN_GNT;
	unsigned char MAX_LAT;

} PCIDP_CONFIG;

// ----------------------------------------------------------------------------
// OpenPCIDP -
// ----------------------------------------------------------------------------
//
// This service provides access to the PCIDP board.  It returns a handle that
// must be used with all other PCIDP kernel services.
//
// Syntax:
		unsigned long __declspec(dllexport)
		OpenPCIDP(
			in unsigned long BoardNumber, 
			out unsigned long* PCIDPHandle
		);
// 
// where:
// BoardNumber (in) - number of the PCIDP board you wish to open. Board
//   numbers begin with zero.
// PCIDPHandle (out) - PCIDP board identifier that must be used to access all
//   other kernel services.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_BAD_DEVICE - invalid board number	



// ----------------------------------------------------------------------------
// GetDriverVersion -
// ----------------------------------------------------------------------------
//
// This service provides the current version of the PCIDP kernel services.
//
// Syntax:
		unsigned long __declspec(dllexport)
		GetDriverVersion(
			in unsigned long PCIDPHandle,
			out unsigned long* Version
		);
// 
// where:
// PCIDPHandle (in) - PCIDP board identifier
// Version (out) - current version in the following format: YYYYMMDD.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_BAD_DEVICE - invalid board number	



// ----------------------------------------------------------------------------
// MapBaseRegister -
// ----------------------------------------------------------------------------
//
// This service supports mapping to the physical address pointed to by one of
// the board's PCI base registers.  If the address space is memory, the service
// returns a pointer that can be used to reference the memory.  If the address
// space is I/O space, the service returns a value from the base register.  It
// is up to the caller to use this address with an IO access service in order 
// to successfully access the I/O space. You cannot use the address directly 
// like you can with a memory space address.
//
// Syntax:
		unsigned long __declspec(dllexport)
		MapBaseRegister(
			in unsigned long PCIDPHandle,
			in unsigned long RegisterNumber,
			in out unsigned long* Length,
			out unsigned long** Address,
			out unsigned long* IOAddress,
			out unsigned long* IOSpace
		);
// 
// where:
// PCIDPHandle (in) - PCIDP board identifier
// RegisterNumber (in) - a valid base register number (0 - 6).
// Length (in out) - the length in bytes of the size of memory to map; returns
//   the actual size mapped.
// Address (out) - linear address the calling application will use as a  
//   unsigned long pointer to reference the mapped address space; only valid
//   when IOSpace = 0.
// IOAddress (out) - I/O address; only valid when IOSpace = 1.
// IOSpace (out) - indicates the type of mapped space; 1=I/O, 0=memory.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_ACCESS_DENIED - mapping failed
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid
//   ERROR_INVALID_PARAMETER - invalid register number
//   ERROR_UNEXP_NET_ERR - base register address is zero (unused)



// ----------------------------------------------------------------------------
// UnMapBaseRegister -
// ----------------------------------------------------------------------------
//
// This service is used to unmap from memory space you mapped to using
// MapBaseRegister and IOSpace = 0.  There is no need to unmap from I/O space. 
// 
// Syntax:
		unsigned long __declspec(dllexport)
		UnMapBaseRegister(
			in unsigned long PCIDPHandle,
			in unsigned long* Address
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// Address (in) - linear address obtained from a MapBaseRegister call (IOSpace
//   equals 0).
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid



// ----------------------------------------------------------------------------
// MapDMAMemory - 
// ----------------------------------------------------------------------------
//
// This service returns a pointer that can be used to reference the DMA memory 
// space from the calling application.  A physical address describing the DMA 
// absolute space is also returned; it must be provided to the PDIDP board 
// before DMA transfers will operate. The DMA memory space is 16K bytes of 
// contiguous memory allocated for PCIDP DMA tranactions between shared memory
// and the host. When you are finished with DMA activity and before you exit
// the application you must unmap from DMA space. Use the UnMapDMAMemory service
// to accomplish this. FAILURE TO UNMAP FROM DMA SPACE CAN CAUSE A SYSTEM
// CRASH when you exit your application.
// 
// Syntax:
		unsigned long __declspec(dllexport)
		MapDMAMemory(
			in unsigned long PCIDPHandle,
			out unsigned long** LinearAddress, 
			out unsigned long* PhysicalAddress
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// LinearAddress (out) - linear address the calling application will use as an  
//   unsigned long pointer to reference the DMA address space.
// PhysicalAddress (out) - Absolute address where DMA memory space is located.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid
//   ERROR_OUTOFMEMORY - mapping failed



// ----------------------------------------------------------------------------
// UnMapDMAMemory -
// ----------------------------------------------------------------------------
//
// This service is used to unmap from the DMA memory space you mapped to using
// MapDMAMemory.  Call it when you are finished using the DMA services provided
// by the PCIDP board.  FAILURE TO UNMAP FROM DMA SPACE CAN CAUSE A SYSTEM
// CRASH when your application exits.
// 
// Syntax:
		unsigned long __declspec(dllexport)
		UnMapDMAMemory(
			in unsigned long PCIDPHandle,
			in unsigned long* Address
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// Address (in) - linear address obtained from a MapDMAMemory call.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid



// ----------------------------------------------------------------------------
// GetPCIConfigurationSpace - 
// ----------------------------------------------------------------------------
//
// This service returns the current PCI configuration data.
//
// Syntax:
		unsigned long __declspec(dllexport)
		GetPCIConfigurationSpace(
			in unsigned long PCIDPHandle,
			out PCIDP_CONFIG* PCIConfiguration
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// PCIConfiguration (out) - a structure of 64 bytes that contain the PCI
//   configuration data.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid



// ----------------------------------------------------------------------------
// SetPCIConfigurationSpace - 
// ----------------------------------------------------------------------------
//
// This service will update the PCI configuration fields.  For that reason it's
// best to populate the PCIConfiguration parameter via the 
// GetPCIConfigurationSpace service, modify the affected fields, then call 
// SetPCIConfigurationSpace.
//
// Syntax:
		unsigned long __declspec(dllexport)
		SetPCIConfigurationSpace(
			in unsigned long PCIDPHandle,
			in PCIDP_CONFIG* PCIConfiguration
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// PCIConfiguration (in) - a structure of 64 bytes that contain the PCI
//   configuration data.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid



// ----------------------------------------------------------------------------
// RegisterInterrupt - 
// ----------------------------------------------------------------------------
//
// This service sets up an interrupt handler that will signal a system event
// each time the requested interrupt fires. You must manually reset the system
// event before waiting for it to signal. When you are through, make sure
// to unregister the interrupt via the UnRegisterInterrupt service.  The same
// type of interrupt may be registered by more than one thread in one
// application or across multiple applications.  For this reason, each 
// registration is unique and each must be unregistered as a separate action.
// Your application must be build as a multithreaded application in order for
// interrupt handling to function properly.
//
// Syntax:
		unsigned long __declspec(dllexport)
		RegisterInterrupt(
			in unsigned long PCIDPHandle,
			in unsigned long InterruptType,
			out void** InterruptID,
			out void** InterruptEvent
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// InterruptType (in) - PCIDP interrupt type to enable and signal to the 
//   calling application each time it fires.
// InterruptID (out) - handle that identifies this interrupt request; use it
//   when unregistering the interrupt.  This type can also be declared as a
//   HANDLE.
// InterruptEvent (out) - event handle to the system event that will signal
//   each time the interrupt fires.  YOU MUST RESET InterruptEvent YOURSELF.
//   This type can also be declared as a HANDLE.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid
//   ERROR_INVALID_PARAMETER - invalid interrupt type
//   ERROR_MR_MID_NOT_FOUND - interrupt is not enabled on the board



// ----------------------------------------------------------------------------
// UnRegisterInterrupt - 
// ----------------------------------------------------------------------------
//
// This service will remove the interrupt handler installed via 
// RegisterInterrupt and the system event associated with it.  Be sure to call
// this service when you no longer need to monitor the interrupt in question.
//
// Syntax:
		unsigned long __declspec(dllexport)
		UnRegisterInterrupt(
			in unsigned long PCIDPHandle,
			in void* InterruptID
		);
//
// where:
// PCIDPHandle (in) - PCIDP board identifier
// InterruptID (out) - handle that identifies the interrupt to unregister; this
//   parameter is provided by the RegisterInterrupt service. This type can also
//   be declared as a HANDLE.
// returns - 
//   ERROR_SUCCESS - successful completion
//   ERROR_INVALID_HANDLE - PCIDPHandle is invalid


#endif