Windows 95/98 Device Driver for PCMCIA Notebook
Contents
1. Returns See also Example pbOpen Synopsis Description Returns See also Example include nhc h DWORD pbLoadVxD VOID This function loads the Virtual Device Driver VxD The function returns PB OK if the driver is loaded succesfully A non zero return value indicates a load failure e g the file NHC9815 VXD is not located in the WINDOWS SYSTEM directory pbUnloadVxD include nhc h DWORD pbOpen VOID This function performs the hardware initialization of the Notebook Serial Highway Controller and enables the converter for subsequent PhyBUS operations Internal data structures are initialized I O resources and system resources for handling interrupts are assigned Ifa PhyBUS crate with auto configuration capabilities is used this function also determines the current PhyBUS configuration See section 4 for a description The function returns PB OK if the Notebook Serial Highway Controller 1s succesfully initialized A non zero return value indicates a failure pbClose pbUnloadVxD Synopsis Description Returns See also Example include nhc h DWORD pbUnloadVxD VOID This function unloads the Virtual Device Driver thereby freeing system resources The driver can be unloaded by the application f the application program terminates or f the driver is not needed anymore If the application exits without calling pbUnloadVxD the unloading 1s performed b2. DWORD lastaddress value of Last Address Register DWORD lastdata value of Last Data Register APCDATA PAPCDATA 20 The APCDATA data structure holds all the relevant information for handling any of the exceptions mentioned The structure members have the following meaning Q intrtype E intrent this structure member contains the value representing the exception and is the same as the parameter ExceptionType for which the corresponding exception handler has been installed It can be used for verifying correct operation of the exception handler or for dispatching another specific exception handler function this structure member contains the current number of exceptions for this exception type I timehigh timelow these structure members contain the time stamp of the current n intend E lastaddress Ll lastdata exception The 64 bit number represents the number of real time clock ticks that have elapsed since the current Windows session was started Each clock tick represents a unit of 0 8 microseconds this structure member contains only valid data 1f the exception is a PhyBUS interrupt EXC TYPE PB INTR It contains a copy of the Interrupt Enquiry Register of the Notebook Serial Highway Controller at the time of the PhyBUS interrupt The Interrupt Enquiry Register 1s used to identify the PhyBUS device s which has have issued the interrupt s this structure member contains only valid data 1f t
3. Returns See also Example include nhc h DWORD pbGetVersion PD WORD pVersion This function returns the version number of the DLL and the version number of the driver in the double word location pointed to by pVersion After calling this function the high word bits 31 16 contains the DLL major and minor version number The low word bits 15 0 contains the VxD device driver major and minor version number The function returns PB_OK if the function call has succeeded A non zero return value indicates a failure DWORD version double word area get version result pbGetVersion amp version printf version 0x 08x n version 26
4. a user defined exception handler for the exception specified by ExceptionType The function ExceptionHandler must be declared as VOID MyExceptionHandler PAPCDATA pAPCData If the specified exception occurs the function 1s invoked and the parameter pAPCData holds the address of an internal driver APCDATA structure of which the structure members can be read to obtain the data needed for processing the exception The internal APCDATA structure 1s intended for read only use The default empty exception handler can be set by calling pbSetExceptionHandler with argument NULL for the ExceptionHandler The function returns PB_OK if it has succeeded A non zero return value indicates a failure VOID MyPhyBUSInterruptHandler PAPCDATA pAPCData printf Interrupt Enquiry Register 0x 04x n pAPCData intenq set user defined handler for PhyBUS interrupts result pbSetExceptionHandler EXC TYPE PB INTR MyPhyBUSInterruptHandler set default handler for PhyBUS interrupts result pbSetExceptionHandler EXC TYPE PB INTR NULL 23 pbSetExceptionPriority Synopsis Description Returns See also Example include nhc h DWORD pbSetExceptionPriority DWORD ProcessPriority DWORD ThreadPriority This function sets the process priority and the thread priority of all exception handlers The parameter ProcessPriority is the priority of the current process from which the function is invoked The
5. functions should be used in the order as given in the following sample code DWORD result result pbInitPhyBUSDLLEntries if result PB OK error exit 1 result pbLoadVxD result pbOpen run your application here result pbClose result pbUnloadVxD pbClose Synopsis Description Returns See also Example include nhc h DWORD pbClose VOID This function performs the hardware finalization of the Notebook Serial Highway Controller and disables the controller for subsequent PhyBUS operations Internal data structures are finalized and internal system resources are freed The function returns PB OK if finalization has succeeded A non zero return value indicates a failure pbOpen pbInitPhyBUSDLLEntries Synopsis Description Returns See also Example include nhc h DWORD pbInitPhyBUSDLLEntries VOID This function initializes the driver entry points addresses of the PhyBUS functions in the file NHCLIB C This function must be called before calling any other driver function the function returns PB OK if all driver entry points are initialized correctly A non zero return value specifies the number of non initialized entries An application program should not continue if the function returns non zero result pbInitPhyBUSDLLEntries if result PB OK error exit 1 pbLoadVxD Synopsis Description
6. parameter ThreadPriority is the priority of the thread in which the APC exception handler functions are running The following values for ProcessPriority are allowed refer to the Windows SDK for more information on this subject THREAD PRIORITY ABOVE NORMAL THREAD PRIORITY BELOW NORMAL THREAD PRIORITY HIGHEST THREAD PRIORITY IDLE THREAD PRIORITY LOWEST THREAD PRIORITY NORMAL THREAD PRIORITY TIME CRITICAL The following values for ThreadPriority are allowed refer to the Windows SDK for more information on this subject ABOVE NORMAL PRIORITY CLASS BELOW NORMAL PRIORITY CLASS HIGH PRIORITY CLASS IDLE PRIORITY CLASS NORMAL PRIORITY CLASS REALTIME PRIORITY CLASS The function returns PB OK if it has succeeded A non zero return value indicates a failure DWORD result heavy locks out almost everything result pbSetExceptionPriority REALTIME PRIORITY CLASS THREAD PRIORITY TIME CRITICAL 24 6 Miscellaneous functions pbErrorMessage Synopsis Description Returns See also Example include nhc h PCHAR pbErrorMessage DWORD MessageNumber This function returns a pointer to a null terminated string containing an error message corresponding with the value of MessageNumber pointer to a string containing the error message DWORD result result pbOpen show error if any o printf s n pbErrorMessage result 25 pbGetVersion Synopsis Description
7. 0x37 result pbSetBitsWord 0x37 0x00000007 set bit 15 at PhyBUS address 0x37 result pbSetBitsWord 0x37 0x8000 17 18 5 Exception handling 5 1 Description of exceptions The types of exceptions handled by the driver are Q PhyBUS interrupts A PhyBUS interrupt can be generated by a PhyBUS interface which has its interrupts enabled PhyBUS write bus errors A PhyBUS write bus error occurs when writing to a non accessible PhyBUS address Possible causes are that no PhyBUS interface is present at the specified address that the register at the specified address 1s read only or that the specified address 1s temporarily unaccessible for write operations PhyBUS read bus errors A PhyBUS read bus error occurs when reading from a non accessible PhyBUS address Possible causes are that no PhyBUS interface is present at the specified address that the register at the specified address 1s write only or that the specified address 1s temporarily unaccessible for read operations PhyBUS initialisation bus errors A PhyBUS initialisation bus error occurs when issuing the pbInit command Possible causes include that the PhyBUS is not accessible because of an unpowered system crate PhyBUS protocol errors A PhyBUS protocol error occurs 1f the Serial Highway transmission protocol 1s violated During normal operation this should never occur However for robustness the protocol exceptions can be signaled 19 Al
8. BUSERROR INIT PB ERR BAD LINK PB ERR MALLOC PB ERR OPENKEY PB ERR CLOSEKEY PB ERR QUERYKEY PB ERR ALLOCKEY PB ERR VXDFAILURE PB ERR NOVXD PB ERR UNLOAD PB ERR CLOSEHANDLE PB ERR THREADPRIORITY PB ERR PROCESSPRIORITY PB ERR NOTHREAD Table 2 1 OK no error PhyBUS not open no IO port available for loading EPLD no IO port available for PhyBUS access error opening RBF file error reading RBF file error closing RBF file EPLD configuration error EPLD reset error error in locating device node error in reading node configuration error in IO config error in attribute memory config error in IRQ config invalid PhyBUS address protocol error slave side protocol error master side PhyBUS read bus error PhyBUS write bus error initPB bus error data errors testing Highway link general memory alloc error error opening registry key error closing registry key error query key error memory alloc for key driver failed NHC9815 VxD not found VxD unload error close handle failed error setting exception thread priority error setting current process priority no exception thread running Device driver error codes 3 Driver initialization and finalization functions The following functions are used to initialize the driver and the interface to the driver These functions must be called before using any PhyBUS function Functions for finalizing the driver are also described Driver initialization and finalization
9. S address in the range 0 4095 Returns The function returns PB_ OK if it has succeeded A non zero return value indicates a failure See also Example write word to PhyBUS address 0x11 result pbPutWord 0x011 0x5678 15 pbSetBitsLong Synopsis Description Returns See also Example include nhc h DWORD pbSetBitsLong WORD Address DWORD Mask This function sets the bits specified 1n the double word Mask at PhyBUS address Address All other bits remain unchanged The PhyBUS address must be a valid PhyBUS address in the range 0 4094 AND the address must be even The function returns PB OK if it has succeeded A non zero return value indicates a failure pbSetBitsWord pbClearBitsWord pbClearBitsLong set bits 2 0 at PhyBUS address 0x40 result pbSetBitsLong 0x40 0x00000007 set bit 15 at PhyBUS address 0x40 result pbSetBitsLong 0x40 0x8000 16 pbSetBitsWord Synopsis Description Returns See also Example include nhc h DWORD pbSetBitsWord WORD Address WORD Mask This function sets the bits specified in the word Mask at PhyBUS address Address All other bits remain unchanged The PhyBUS address must be a valid PhyBUS address in the range 0 4095 The function returns PB_OK if it has succeeded A non zero return value indicates a failure pbClearBits Word pbSetBitsLong pbClearBitsLong set bits 2 0 at PhyBUS address
10. Windows 95 98 Device Driver for PCMCIA Notebook Serial Highway Controller BLN 2001 08 UM March 2001 Eindhoven University of Technology Department of Physics Physical amp Technical Laboratory Automation Group Author R Smeets Version 1 0 Date 16 03 2001 Table of contents 1 Inttodue LOfl a a OE Oa ee 3 bel AA TITRE 3 1 2 Conventions used in this manual 0 00 cee eee ee eee eee 4 Driver interface overview ccc ce ee eee rss 5 2 1 Description of functional groups 0 0 cee ees 5 2 2 Device driver error codes lee es 6 Driver initialization and finalization functions 0 00 ce ewes 7 PhyBUS I O and PhyBUS control functions 0 0 0 e eee ees 11 PXCepiom handling secreto dara 19 S l Description of exceptions ess nn a I a 19 3 2 JSXCEDUOR MUINCHONS uou dou Gee E io 22 Miscellaneous functions cler res 25 1 Introduction 1 1 General This document describes the functions and the Application Programming Interface APD ofthe Virtual Device Driver VxD for the Notebook Serial Highway Controller BLN 98 15 for Windows 95 98 The driver offers a C interface to an application program The device driver including the installation script consists of the following files i NHC9815 V XD this file contains the actual device driver for the PCMCIA card in the notebook LY NHCIO DLL this file interfaces the device driver to an application
11. clude nhc h DWORD pbClearBitsWord WORD Address WORD Mask This function clears the bits specified in the word Mask at PhyBUS address Address All other bits remain unchanged The PhyBUS address must be a valid PhyBUS address in the range 0 4095 The function returns PB OK if it has succeeded A non zero return value indicates a failure pbSetBitsWord pbClearBitsLong pbSetBitsLong clear bits 2 0 at PhyBUS address 0x37 result pbClearBitsWord 0x37 0x7 clear bit 15 at PhyBUS address 0x37 result pbClearBitsWord 0x37 0x8000 12 pbGetLong Synopsis Description Returns See also Example Hinclude pb h DWORD pbGetLong WORD Address PDWORD pData This function reads a double word from the PhyBUS address Address The double word read 1s stored in the location pointed to by pData The PhyBUS address must be a valid PhyBUS address in the range 0 4095 and the address must be even The function returns PB_OK if it has succeeded A non zero return value indicates a failure pbGetWord pbPutWord pbPutLong DWORD dataread receives result of pbGetLong read double word from PhyBUS address 0x012 and store it in dataread result pbGetLong 0x012 amp dataread 13 pbGetWord Synopsis Description Returns See also Example pbInit Synopsis Description Returns See also Example include nhc h DWORD pbGetWord WORD Ad
12. dress PWORD pData This function reads a word from the PhyBUS address Address The word read is stored in the location pointed to by pData The PhyBUS address must be a valid PhyBUS address in the range 0 4095 The function returns PB_OK if it has succeeded A non zero return value indicates a failure pbGetWord pbPutWord pbGetLong pbPutLong WORD dataread receives result of pbGetWord read word from PhyBUS address 0x013 result pbGetWord 0x013 amp dataread and store it in dataread include nhc h DWORD pblnit VOID This function executes a global reset of ALL PhyBUS interfaces The function returns PB OK if it has succeeded A non zero return value indicates a failure 14 pbPutLong Synopsis include nhc h DWORD pbPutLong WORD Address DWORD Data Description This function writes the double word Data to the PhyBUS address Address The PhyBUS address must be a valid PhyBUS address n the range 0 4094 AND the address must be even Returns The function returns PB_OK if it has succeeded A non zero return value indicates a failure See also pbGetWord pbPutWord pbGetLong Example write double word to PhyBUS address 0x12 result pbPutLong 0x012 0x12345678 pbPutWord Synopsis include nhc h DWORD pbPutWord WORD Address WORD Data Description This function writes the word Data to the PhyBUS address Address The PhyBUS address must be a valid PhyBU
13. he exception 1s a PhyBUS read bus error EXC TYPE BER RD or a PhyBUS write bus error EXC TYPE BER WR It contains the PhyBUS address where the bus error has occurred this structure member contains only valid data 1f the exception is a PhyBUS read bus error EXC TYPE BER RD or a PhyBUS write bus error EXC TYPE BER WR It contains the PhyBUS data where the bus error has occurred 21 5 2 Exception functions pbGetExceptionStatus Synopsis Description Returns See also Example include nhc h DWORD pbGetExceptionStatus DWORD ExceptionType PAPCDATA pExceptionStatus This function returns the current status of the specified exception type in an APCDATA structure The parameter pExceptionStatus must hold the address of this APCDATA structure Calling this function copies the internal driver exception status to the user APCDATA structure and resets the internal exception counter for the specified exception type of the driver to zero The function returns PB OK if it has succeeded A non zero return value indicates a failure APCDATA apcbuf area for storing result get exception status for PhyBUS interrupts result pbGetExceptionStatus EXC TYPE PB INTR amp apcbuf 22 pbSetExceptionHandler Synopsis Description Returns See also Example include pb h DWORD pbSetExceptionHandler DWORD ExceptionType PEXCEPTIONHANDLER ExceptionHandler This function installs
14. l exceptions are internally queued by the driver to be handled as Asynchronous Procedure Calls APC The driver runs a thread n which the default APC s for all exceptions are defined By using the function pbSetExceptionHandler the user can hook a user defined exception handler to the default APC The function pbSetExceptionHandler has the following prototype DWORD pbSetExceptionHandler DWORD ExceptionType PEXCEPTIONHANDLER ExceptionHandler The parameter ExceptionType defines the type for which the specified exception handler must be installed and must have one of the following values PhyBUS interrupts EXC TYPE PB INTR PhyBUS write bus errors EXC TYPE BER WR PhyBUS read bus errors EXC TYPE BER RD PhyBUS initialisation bus errors EXC TYPE PB INIT protocol errors EXC_TYPE PER The function pbSetExceptionHandler can only be used in an environment which 1s multithread safe Not all compiler vendors do provide these environments If the environment is not multithread safe the application program may crash An exception handler is a pointer to a function defined by the following typedef in NHC H typedef VOID PEXCEPTIONHANDLER PAPCDATA PAPCDATA is a pointer to an APCDATA data structure typedef struct DWORD intrtype interrupt type DWORD intrent sequence number of interrupt DWORD timehigh 64 bit time stamp of exception in units of 0 8 us DWORD timelow DWORD inteng value of inteng register
15. program UY 9815 RBF 981 5B RBF these files contain the configuration for the programmable logic devices on the PCMCIA card Y HIGHWAY INF this file contains the Windows 95 98 installation script for installing the PCMCIA card in a notebook or laptop computer The files NHC9815 VXD NHCIO DLL 9815 RBF and 9815B RBF are installed in the WINDOWS SYSTEM directory An application program must include and link the following source files to obtain the entry points of the PhyBUS functions Q NHC H Q NHCLIB C A number of functions return the hardware status of the Notebook Highway Controller or can modify its settings See the user manual of the Notebook Highway Controller for specific information BLN 98 15 UM 1 2 Conventions used in this manual As the interface to the driver is intended to be used in a C programming environment with the Windows 95 98 operating system the conventions used in this manual with respect to types include files etc are Windows C like An application must always include lt windows h gt A short description of the types used by the driver WORD word 16 bits DWORD double word 32 bits VOID if defined as a formal function parameter function needs no actual parameter if defined as a function return value function does not return a value PWORD pointer to a word PDWORD pointer to a double word PVOID if defined as a formal function parameter actual parameter can be a pointer to any
16. type if defined as a function return value the return value can be a pointer to any type 2 Driver interface overview 2 1 Description of functional groups The driver functions are divided into the following functional groups driver initialization and finalization functions PhyBUS I O and PhyBUS control functions PhyBUS exception functions interrupts amp bus errors miscellaneous d Ea All driver functions start with the prefix pb Every function returns a DWORD indicating function success or failure if the function return value is 0 zero PB OK the function was successful A non zero return value indicates failure In this case the error value identifies the specific failure See section 2 2 Device driver error codes The error codes are defined in the file nhc h and are given in table 2 1 Do not use literal error code values for processing errors but use the symbolic names table 2 1 A number of error codes specify internal driver errors and serve only as a means for tracking down internal system errors PB OK PB ERR NOT OPEN PB ERR NO IOPORT EPLD PB ERR NO IOPORT PB PB ERR RBF OPEN PB ERR RBF READ PB ERR RBF CLOSE PB ERR EPLD CONFIG PB ERR EPLD RESET PB ERR CFG NO DEVNODE PB ERR CFG BAD DEVCONFIG PB ERR CFG BAD IO PB ERR CFG BAD ATTMEM PB ERR CFG BAD IRQ PB ERR INVALID ADDRESS PB ERR PROTOCOL SLAVE PB ERR PROTOCOL MASTER PB ERR BUSERROR READ PB ERR BUSERROR WRITE PB ERR
17. y the operating system The function returns PB OK if the driver is unloaded succesfully A non zero return value indicates an unload failure pbLoadVxD 10 4 PhyBUS I O and PhyBUS control functions The PhyBUS I O and PhyBUS control functions perform word or double word I O operations on PhyBUS addresses Executing a read or a write access on a non accessible PhyBUS address results in a bus error As a default a read bus error 1s signaled by the the return value PB ERR BUSERROR READ of the invoked function a write bus error is signaled by the return value PB ERR BUSERROR WRITE of the invoked function See section 6 for handling of PhyBUS bus errors pbClearBitsLong Synopsis include nhc h DWORD pbClearBitsLong WORD Address DWORD Mask Description This function clears the bits specified in the doubleword Mask at PhyBUS address Address All other bits remain unchanged The PhyBUS address must be a valid PhyBUS address n the range 0 4095 and the address must be even Returns The function returns PB OK if it has succeeded A non zero return value indicates a failure See also pbClearBitsWord pbSetBitsWord pbClearBitsLong pbSetBitsLong Example clear bits 2 0 at PhyBUS address 0x100 result pbClearBitsLong 0x100 0x7 clear bit 31 at PhyBUS address 0x100 result pbClearBitsLong 0x100 0x80000000 11 pbClearBitsWord Synopsis Description Returns See also Example in
Download Pdf Manuals
Related Search