Programming Manual WINDOWS IMCEA Driver - … · Programming_Manual_ WINDOWS_IMCEA-driver.pdf ......

INDUSTRIAL MICROCOMPUTERSINDUSTRIAL MICROCOMPUTERSsicomp

Windows NT/2000/XP DriverWINDOWS IMCEA

Programming Manual Edition 02/2005

Introduction 1

Description 2

Software installation 3

IOCTL functions 4

Example source functions 5

Creating an application 6

SICOMP Industrial Microcomputers

WINDOWS IMCEA Driver

Programming Manual

Edition 02/2005 J31069-D2131-U001-A1-7618

Safety Guidelines This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring to property damage only have no safety alert symbol. These notices shown below are graded according to the degree of danger.

Danger

indicates that death or severe personal injury will result if proper precautions are not taken.

Warning

indicates that death or severe personal injury may result if proper precautions are not taken.

Caution

with a safety alert symbol, indicates that minor personal injury can result if proper precautions are not taken.

Caution

without a safety alert symbol, indicates that property damage can result if proper precautions are not taken.

Notice

indicates that an unintended result or situation can occur if the corresponding information is not taken into account.

If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage.

Qualified Personnel The device/system may only be set up and used in conjunction with this documentation. Commissioning and operation of a device/system may only be performed by qualified personnel. Within the context of the safety notes in this documentation qualified persons are defined as persons who are authorized to commission, ground and label devices, systems and circuits in accordance with established safety practices and standards.

Prescribed Usage Note the following:

Warning

This device may only be used for the applications described in the catalog or the technical description and only in connection with devices or components from other manufacturers which have been approved or recommended by Siemens. Correct, reliable operation of the product requires proper transport, storage, positioning and assembly as well as careful operation and maintenance.

Trademarks All names identified by ® are registered trademarks of the Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.

Copyright Siemens AG 2005. All rights reserved. The distribution and duplication of this document or the utilization and transmission of its contents are not permitted without express written permission. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved.

Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions.

Siemens AG Automation and Drives Postfach 4848, 90327 Nuremberg, Germany

Siemens AG 2005 Technical data subject to change

Siemens Aktiengesellschaft J31069-D2131-U001-A1-7618

WINDOWS IMCEA Driver Programming Manual, Edition 02/2005, J31069-D2131-U001-A1-7618 iii

Table of contents 1 Introduction............................................................................................................................................. 1-1 2 Description.............................................................................................................................................. 2-1 3 Software installation................................................................................................................................ 3-1

3.1 Requirements............................................................................................................................. 3-1 3.2 WINDOWS IMCEA (nPnP) installation ...................................................................................... 3-2 3.3 WINDOWS IMCEA (PnP) installation ........................................................................................ 3-6

4 IOCTL functions...................................................................................................................................... 4-1 5 Example source functions....................................................................................................................... 5-1

5.1 Driver - basic functions .............................................................................................................. 5-2 5.1.1 ImcEADrvInstallDriver() ............................................................................................................. 5-3 5.1.2 ImcEADrvUninstallDriver() ......................................................................................................... 5-4 5.1.3 ImcEADrvStartDriver() ............................................................................................................... 5-5 5.1.4 ImcEADrvStopDriver() ............................................................................................................... 5-6 5.1.5 ImcEADrvOpen()........................................................................................................................ 5-8 5.1.6 ImcEADrvClose() ....................................................................................................................... 5-9 5.2 Port - access functions............................................................................................................. 5-10 5.2.1 ImcEADrvReservePort() .......................................................................................................... 5-12 5.2.2 ImcEADrvFreePort() ................................................................................................................ 5-13 5.2.3 ImcEADrvWritePort() ............................................................................................................... 5-14 5.2.4 ImcEADrvReadPort() ............................................................................................................... 5-16 5.3 Memory - access functions ...................................................................................................... 5-18 5.3.1 ImcEADrvReserveMem() ......................................................................................................... 5-19 5.3.2 ImcEADrvFreeMem() ............................................................................................................... 5-22 5.4 Interrupt - processing functions................................................................................................ 5-23 5.4.1 ImcEADrvStartInterruptHandler()............................................................................................. 5-25 5.4.2 ImcEADrvStopInterruptHandler() ............................................................................................. 5-27 5.4.3 ImcEADrvWaitForInterrupt() .................................................................................................... 5-28 5.4.4 ImcEADrvResetWaitForInterrupt() ........................................................................................... 5-30 5.4.5 ImcEADrvWaitForInterruptEx() ................................................................................................ 5-31 5.5 PCI address area - processing functions................................................................................. 5-33 5.5.1 ImcEADrvSearchPCI() ............................................................................................................. 5-34

6 Creating an application ........................................................................................................................... 6-1 Index

WINDOWS IMCEA Driver iv Programming Manual, Edition 02/2005, J31069-D2131-U001-A1-7618

WINDOWS IMCEA Driver Programming Manual, Edition 02/2005, J31069-D2131-U001-A1-7618 1-1

Introduction 1Purpose of the manual

This manual includes all the information you need in order to install and configure the WINDOWS IMCEA driver. It also familiarizes you with all the different functions that can be used via the driver.

Target group The manual is aimed at programmers and configurators.

Manual - range of validity The manual is valid for all supplier variants of the WINDOWS IMCEA driver and describes the as-delivered condition as of February 2005.

History

Release Overview of changes Release date A1 First edition 02/2005

Further information For information on SIMATIC and SICOMP hardware as well as on the Visual Studio V6.0 development environment, please refer to the respective product manuals. Windows-specific questions can be asked on the Microsoft support page (http://support.microsoft.com).

http://support.microsoft.com

Introduction

WINDOWS IMCEA Driver 1-2 Programming Manual, Edition 02/2005, J31069-D2131-U001-A1-7618

Conventions The abbreviation "driver" is also used in this manual for the product name WINDOWS IMCEA Driver.

Notation

* An asterisk appended to the signal name indicates an active-low signal (e.g. IOR*). / A slash between two signal names separates two level-specific functions of a signal

(example: C/D* means high level for a "command" and low level for "data"). k, M, G as auxiliary characters for the units bit and byte: Abbreviations for the numerical factors

1.024 = 210, 1.048.576 = 220 or 1.073.741.824 = 230.


Description 2

Under the operating systems Microsoft Windows NT / Windows 2000 and Windows XP, the WINDOWS IMCEA driver offers direct access functions (low-level) to physical I/O resources (memory-mapped I/O, port-based I/O and interrupts). With the driver, applications can directly access the hardware.

Notice

The driver is only enabled for use on SIMATIC IPC and SICOMP IMC hardware platforms.

Note

Under Windows XP, alongside the uniprocessor version, the driver also supports the multiprocessor version.

Operation Several threads can simultaneously send jobs to the WINDOWS IMCEA driver. However, the I/O manager only passes on these jobs to the IMCEA driver if they have differing handles (connections). The handles are created by calling "ImcEADrvOpen()". As processing in the WINDOWS IMCEA driver takes place according to the priority of the thread, processing in the driver can also be interrupted by another thread.

Description


Driver variants The "WINDOWS IMCEA" product contains two driver variants: • WINDOWS IMCEA (PnP): PlugAndPlay-capable driver for Windows 2000 / XP • WINDOWS IMCEA (nPnP): Non-PlugAndPlay driver for Windows NT / 2000 / XP

Note

Both drivers can be operated at the same time.

Product components The following files are components of the "WINDOWS IMCEA" product:

File Description Imcea.sys WINDOWS IMCEA (nPnP) driver Imceapnp.sys WINDOWS IMCEA (PnP) driver Setup.exe Setup program for the WINDOWS IMCEA (nPnP) driver Imcea.inf Installation file for the WINDOWS IMCEA (PnP) driver Programming_Manual_ WINDOWS_IMCEA-driver.pdf

User documentation for the WINDOWS IMCEA driver

Examples\Imcealib.cpp Example source with the calls. This file includes the source code of all functions for access to the driver.

Examples\microbox.cpp Example source for the SIMATIC Microbox PC 420 Examples\Imcealib.h Header file for WINDOWS IMCEA calls (example source). This file

includes definitions for the example functions for access to the driver. All driver functions are accessible via a C port.

Examples\Imceadrv.h Header file for direct access to the WINDOWS IMCEA driver. This file includes definitions for the IOCTL code for access to the driver, and definitions for the transfer structures.

Development environment All the example files included in the product have been tested with Visual Studio V6.0.


Software installation 33.1 Requirements

Hardware requirements You need a Windows computer in order to install the WINDOWS IMCEA driver. To use the PlugAndPlay version of the driver, your computer must have a PCI or CPCI bus. Then the driver can be used, for example, for the SICOMP CPCI-EA221 module.

Software requirements To install the driver you need the "WINDOWS IMCEA" product.

Software installation 3.2 WINDOWS IMCEA (nPnP) installation


3.2 WINDOWS IMCEA (nPnP) installation

IMCEA (nPnP) installation procedure To install the driver, proceed as follows: • Run the installation program Setup.exe that is included in the product package. The

Setup dialog box appears:

• In the Setup dialog box, select the Install option. The driver is installed and registered in

the system. • After completing the installation, restart the system. The driver is now ready for normal

operation and, after start-up, is visible in the Device Manager of the Windows Control Panel by means of the application program.

Alternative method of installation The nPnP driver can also be installed from an application program. For more information on this, please refer to the description of the "ImcEADrvInstallDriver()" function.



Driver presentation in the Device Manager Windows NT With Windows NT, the Device Manager can be reached via the Control Panel and the "Devices" submenu. The following dialog box appears:

The driver is indicated by the name "IMCEA". The "Manual" starting mode is selected as the default setting. But you can alter the starting mode accordingly. The following settings are available:

If the driver is to automatically start every time the system is booted up, then select the "Automatic" option. The operating system launches the driver after the user has logged in. There is now no need to start the driver separately.



Windows 2000 / XP With Windows 2000 / XP, the Device Manager can be reached via the Control Panel and the submenus "Administration / Computer Management". In order to show non-PlugAndPlay devices, use the right mouse key to activate the "View" menu on the Device Manager icon and there select "Show hidden devices".

Note

If the drivers are not displayed in the Device Manager, then either manually start the driver or restart the system.



The driver is indicated by the name "IMCEA". The starting mode "Demand" is selected as the default setting. However, you can change the starting mode by clicking the right mouse key and selecting the "Properties" menu. The following settings are available:

If the driver is to automatically start every time the system is booted up, then select the "Automatic" option. The operating system launches the driver after the user has logged in. There is now no need to start the driver separately.

Software installation 3.3 WINDOWS IMCEA (PnP) installation


3.3 WINDOWS IMCEA (PnP) installation

IMCEA (PnP) installation procedure To install the driver, proceed as follows: • After installing a module and the subsequent restart of the system, the "Found New

Hardware Wizard" is displayed. Now insert the data medium containing the "WINDOWS IMCEA" product into the respective drive of your computer (for example: floppy disk in A:\) and select the following options:



• Select "Have Disk" and then drive A:\

• The system then finds the PnP driver on the floppy disk. This is then installed once you

click on "Next":



Note

As the driver isn´t digitally signed, during installation under Windows XP a system message appears stating that the driver has not passed the Windows logo test. Ignore this message and continue with the installation.

• The "Finish" option concludes the installation:

• After installation, the driver is ready for normal operation and is visible in the Device

Manager of the Windows Control Panel.



Driver presentation in the Device Manager With Windows 2000 / XP, the Device Manager can be reached via the Control Panel and the submenus "Administration / Computer Management". The driver is indicated by the name "Siemens SICOMP CPCI-EA221" in the "Multifunction adapters" menu.


IOCTL functions 4

All access to the driver takes place via IOCTL functions. They are passed to the driver by the "DeviceIoControl()" function. The Defines of the possible calls are defined in the header file IMCDRV.H. The following IOCTL functions are available:

Function Description CTRLCD_RESERVE_PORT Reserving I/O port CTRLCD_READ_PORT Reading a port CTRLCD_WRITE_PORT Writing to a port CTRLCD_FREE_PORT Enabling a reserved port CTRLCD_RESERVE_MEM Reserving a memory area CTRLCD_FREE_MEM Enabling a reserved memory area CTRLCD_START_INTR_HANDLER Reserve interrupt and set up handler CTRLCD_FREE_INTR_HANDLER Enable reserved interrupt CTRLCD_WAIT_FOR_INTERRUPT Waiting for receipt of an interrupt CTRLCD_RESET_WAIT_FOR_INTERRUPT Aborting waiting for an interrupt CTRLCD_SEARCH_PCI Configuration Space - search and read CTRLCD_WAIT_FOR_INTERRUPTEx Waiting for receipt of an interrupt and read

Note

A more detailed description of the IOCTL functions is not included in this documentation.


Example source functions 5The functions available in the example source can be subdivided into the following groups: • Driver - basic functions • Port - access functions • Memory - access functions • Interrupt - processing functions • PCI address area - processing functions

Note

All the functions described in the following chapters have been tested with Visual Studio V6.0.

Example source functions 5.1 Driver - basic functions


5.1 Driver - basic functions

The WINDOWS IMCEA driver offers the following basic functions:

Function Description ImcEADrvInstallDriver() Install nPnP driver ImcEADrvUninstallDriver() Uninstall nPnP driver ImcEADrvStartDriver() Start nPnP driver ImcEADrvStopDriver() Stop nPnP driver ImcEADrvOpen() Open driver ImcEADrvClose() Close driver



5.1.1 ImcEADrvInstallDriver()

Description With the "ImcEADrvInstallDriver()" function, the nPnP driver can be installed from an application program.

Note

Prior to executing the "ImcEADrvInstallDriver()" function, you must first copy the file imcea.sys to the "<Windows>\system32\drivers" directory.

Syntax

DWORD ImcEADrvInstallDriver (

char* szDriverPath,

char* szDriverName )

Parameter

Parameter Description szDriverPath Path and file name, e.g. "%SystemRoot%\\system32\\drivers\\imcea.sys" szDriverName Driver name - "IMCEA"

Programming example

dwRetCode = ImcEADrvInstallDriver("%SystemRoot%\\system32\\drivers\\imcea.sys", "IMCEA" ); if( (dwRetCode != ERROR_SUCCESS) && (dwRetCode != ERROR_SERVICE_EXISTS) )

{ printf( "ImcEADrvInstallDriver: Error 0x%lx\n", dwRetCode);

}

After completing the installation, restart the system. The driver is now ready for normal operation and, after start-up, is visible in the Device Manager of the Windows Control Panel by means of the application program.



5.1.2 ImcEADrvUninstallDriver()

Description With the "ImcEADrvUninstallDriver()" function, the nPnP driver can be uninstalled from an application program.

Syntax

DWORD ImcEADrvUninstallDriver (


Parameter

Parameter Description szDriverName Driver name - "IMCEA"

Programming example

dwRetCode = ImcEADrvUninstallDriver( "IMCEA" ); if( dwRetCode != ERROR_SUCCESS )

{ printf( "ImcEADrvUninstallDriver: Error 0x%lx\n", dwRetCode);

}



5.1.3 ImcEADrvStartDriver()

Description The "ImcEADrvStartDriver()" function included in the example source is started at the runtime of the nPnP driver. "IMCEA" is given as the driver name.

Note

It is then only necessary to start the driver via this function if the starting mode "Manual" is selected in the device settings.

Syntax

DWORD ImcEADrvStartDriver (


Parameter


Programming example

dwRetCode = ImcEADrvStartDriver("IMCEA"); if( dwRetCode != ERROR_SUCCESS )

{ printf( "ImcEADrvStartDriver: Error 0x%lx\n", dwRetCode);

}



5.1.4 ImcEADrvStopDriver()

Description The "ImcEADrvStopDriver()" function included in the example source stops the nPnP driver. "IMCEA" is given as the driver name. When it is stopped, the driver independently performs all the clearing work. As a result, the occupied resources (ports, memory and interrupts) are enabled.

Note

It is usually unnecessary to stop the driver. In the development phase of an application, the explicit starting and stopping of a driver can sometimes be helpful.

Notice

Stopping the driver using this function can cause problems with other applications that are also using the driver.

Syntax

DWORD ImcEADrvStopDriver (


Parameter




Programming example

dwRetCode = ImcEADrvStopDriver("IMCEA"); if( dwRetCode != ERROR_SUCCESS )

{ printf( "ImcEADrvStopDriver: Error 0x%lx\n", dwRetCode);

}



5.1.5 ImcEADrvOpen()

Description The "ImcEADrvOpen()" function included in the example source opens the driver. The name "IMCEA" is given for the nPnP driver, and "IMCEA0" for the PnP driver (with several modules then "IMCEA1", "IMCEA2" etc.). As a result a handle is returned. Subsequent calls on the driver are only possible using this handle.

Syntax

DWORD ImcEADrvOpen (

char* szDriverName,

HANDLE* hDrvHandle )

Parameter

Parameter Description szDriverName Driver name - "IMCEA" hDrvHandle Driver handle

Programming example

dwRetCode = ImcEADrvOpen( "IMCEA", &DrvHandle ); if( dwRetCode != ERROR_SUCCESS )

{ printf( "ImcEADrvOpen: Error 0x%lx\n", dwRetCode);

}



5.1.6 ImcEADrvClose()

Description The "ImcEADrvClose()" function included in the example source closes the driver.

Syntax

DWORD ImcEADrvClose (

HANDLE hDrvHandle )

Parameter

Parameter Description hDrvHandle Driver handle

Programming example

ImcEADrvClose (hDrvHandle);

Example source functions 5.2 Port - access functions


5.2 Port - access functions

The following port access functions can be used with the WINDOWS IMCEA driver:

Function Description ImcEADrvReservePort() Reserve ports ImcEADrvFreePort() Enable ports ImcEADrvWritePort() Write ports ImcEADrvReadPort() Read ports

Function sequence Before a program can access ports, you must register the I/O area with the operating system by means of the "ImcEADrvReservePort()" function. After successfully registering the I/O area, ports can be read and described via the "ImcEADrvReadPort()" and "ImcEADrvWritePort()" functions. After concluding the access, you can then again enable the registered area by means of the "ImcEADrvFreePort()" function.

Note

The functions "ImcEADrvReservePort()" and "ImcEADrvFreePort()" are no longer of significance, and merely exist for compatibility reasons with earlier driver versions.

Note

A direct port access of the application is not possible.



Data structures used The data structures "RESERVEIO" and "PORTIO" are used for the port access functions.

RESERVEIO Type definition Variables Description PVOID StartAddress Start address of the port or the memory ULONG Length Length of the area in bytes

PORTIO Type definition Variables Description PVOID Address Address of the port at IMCEA(nPnP)

Offset of the port at IMCEA(PnP) ULONG Value of the value to be written ULONG Mode 0: PORT_MODE_UCHAR: Byte access

1: PORT_MODE_USHORT: Word access 2: PORT_MODE_ULONG: Dword access



5.2.1 ImcEADrvReservePort()

Description The "ImcEADrvReservePort()" function checks the transferred parameters for completeness and correctness. The function then checks to see if the necessary ports in the system are unoccupied. If the ports are unoccupied they will be exclusively occupied by the driver.

Note

The "ImcEADrvReservePort()" function is no longer of significance, and it merely exists for compatibility reasons with earlier driver versions.

Syntax

DWORD ImcEADrvReservePort (

HANDLE hDrvHandle,

RESERVEIO *ReserveIO )

Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" ReserveIO Data structure for the port access function

Returncode

Code Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_NO_SYSTEM_RESOURCES The requested area could not be reserved (resources are

already occupied) ERROR_NO_MORE_ITEMS The number of reserved I/O areas is too great

(max. 50)



5.2.2 ImcEADrvFreePort()

Description The function "ImcEADrvFreePort()" again enables the I/O areas that were occupied with the function "ImcEADrvReservePort()".

Note

The "ImcEADrvFreePort()" function is no longer of significance, and it merely exists for compatibility reasons with earlier driver versions.

Syntax

DWORD ImcEADrvFreePort (

HANDLE hDrvHandle,


Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" ReserveIO Data structure for the port access function

Returncode

Code Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_INVALID_ADDRESS The area to be enabled has not been reserved

("Reserve ports" call missing)



5.2.3 ImcEADrvWritePort()

Description The "ImcEADrvWritePort()" function can write a port with a byte, word or dword. To do this, the respective value must be entered in the "Mode" field. With PnP drivers, the parameter Address includes the offset as an input parameter and the actual address (basic address of the module + offset) as an output parameter.

Syntax

DWORD ImcEADrvWritePort (

HANDLE hDrvHandle,

PORTIO *PortIO )

Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" PortIO Data structure for the port access function

Returncode

Code Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are

incorrect ERROR_INVALID_PARAMETER The mode does not correspond with the three

predefined types



Programming example

PORTIO PortIO; PortIO.Address = (void*)0x3f8; // absolute address for IMCEA(nPnP) // relative address for IMCEA(PnP) PortIO.Value = 0x41; PortIO.Mode = PORT_MODE_UCHAR; dwRetCode = ImcEADrvWritePort(hDrvHandle, &PortIO ); if( dwRetCode == ERROR_SUCCESS )

{ printf ("Value(mode=%d) 0x%x written to Address 0x%x\n",

PortIO.mode, PortIO.Value, PortIO.Address); }



5.2.4 ImcEADrvReadPort()

Description The "ImcEADrvReadPort()" function can read a port with a byte, word or dword. To do this, the respective value must be entered in the "Mode" field. With IMCEA(PnP) the parameter Address includes the offset as an input parameter and the actual address (basic address of the module + offset) as an output parameter.

Syntax

DWORD ImcEADrvReadPort (

HANDLE hDrvHandle,

PORTIO *PortIO )

Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" PortIO Data structure for the port access function

Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_INVALID_PARAMETER The mode does not correspond with the three predefined

types



Programming example

PORTIO PortIO; PortIO.Address = (void*)0x21; // absolute address for IMCEA(nPnP) // relative address for IMCEA(PnP) PortIO.Value = 0x0; PortIO.Mode = PORT_MODE_UCHAR; dwRetCode = ImcEADrvReadPort(hDrvHandle, &PortIO ); if( dwRetCode == ERROR_SUCCESS )

{ printf ("Value(mode=%d) of Address 0x%x = 0x%x\n",

PortIO.mode, PortIO.Address, PortIO.Value); }

Example source functions 5.3 Memory - access functions


5.3 Memory - access functions

The following memory access functions can be used with the WINDOWS IMCEA driver:

Function Description ImcEADrvReserveMem() Reserve memory ImcEADrvFreeMem() Enable memory

Data structures used The data structure "RESERVEIO" is used for the memory access functions.

RESERVEIO Type definition Variables Description PVOID StartAddress Start address of the port or the memory ULONG Length Length of the area in bytes



5.3.1 ImcEADrvReserveMem()

WINDOWS IMCEA (nPnP) With function "ImcEADrvReserveMem()" you can reserve the transferred memory addresses. The function is informed of the start address and the number of bytes following. The driver checks the resources in view of the resources already occupied by Windows. If there is no conflict, then the resources are designated as occupied.

WINDOWS IMCEA (PnP) Via the PnP mechanism, the driver already knows the address and the length of the memory. Both parameters of the RESERVEIO structure are therefore not evaluated.

Description The function carries out an address mapping with the start address. The resulting virtual address is returned to the caller. All future access to the memory must be conducted via the virtual address. With this address, the application can work directly in User Mode.

Syntax

DWORD ImcEADrvReserveMem (

HANDLE hDrvHandle,


Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" ReserveIO Data structure for the memory access function



Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_NO_SYSTEM_RESOURCES The required area could not be reserved as it has already

been reserved by another call. ERROR_NO_MORE_ITEMS The number of reserved areas is too great

(max. 50) ERROR_ACCESS_DENIED The address mapping is refused by the operating system

WINDOWS IMCEA (nPnP) - programming example

RESERVEIO ReserveIO; ReserveIO.StartAddress = (void*)Address; // for IMCEA(PnP) unused ReserveIO.Length = length; ; // with IMCEA(PnP) without

significance dwRetCode = ImcEADrvReserveMem(hDrvHandle, &ReserveIO ); if( dwRetCode == ERROR_SUCCESS )

{ printf( "IMCEAReserveMem(Address: 0x%x) was successful\n",

ReserveIO.StartAddress); }

WINDOWS IMCEA (PnP) - programming example

RESERVEIO ReserveIO; dwRetCode = ImcEADrvReserveMem(hDrvHandle, &ReserveIO ); if( dwRetCode == ERROR_SUCCESS )

{ printf( "IMCEAReserveMem(Address: 0x%x, Length: 0x%x) was

successful\n", ReserveIO.StartAddress, ReserveIO. Length); }



Conduct memory access After reserving the desired memory area, access to the memory can take place directly within the application.

Note

Please note that all modern compilers carry out a very strong code optimization. This can result in individual memory accesses being optimized away. If you want to avoid this, then you must remove the respective accesses via Pragmas prior to optimization, or the pointer will be declared as "volatile".

Memory access - programming example

volatile ULONG * helpmem; RESERVEIO ReserveIO; dwRetCode = ImcEADrvReserveMem(hDrvHandle, &ReserveIO ); if( dwRetCode == ERROR_SUCCESS )

{ printf( "IMCEAReserveMem(Address: 0x%x, Length: 0x%x) was

successful\n",ReserveIO.StartAddress, ReserveIO. Length); }

helpmem = (ULONG*) ReserveIO.StartAddress; helpmem[0] = 0x00000000; // out value readmem = helpmem[6]; // read register 6



5.3.2 ImcEADrvFreeMem()

Description Using the function "ImcEADrvFreeMem()" you can again enable the memory areas that were occupied using the function "ImcEADrvReserveMem()". To do this, the virtual addresses that provide the function "ImcEADrvReserveMem()" must be transferred.

Syntax

DWORD ImcEADrvFreeMem (

HANDLE hDrvHandle,


Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" ReserveIO Data structure for the memory access function

Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_INVALID_ADDRESS The area to be enabled has not been reserved ("Reserve

memory" call missing)

Programming example

dwRetCode = ImcEADrvFreeMem( hDrvHandle, &ReserveIO );

Example source functions 5.4 Interrupt - processing functions


5.4 Interrupt - processing functions

The following interrupt processing functions can be used with the WINDOWS IMCEA driver:

Function Description ImcEADrvStartInterruptHandler() Reserve interrupts ImcEADrvStopInterruptHandler() Enable interrupts ImcEADrvWaitForInterrupt() Wait for interrupts ImcEADrvResetWaitForInterrupt() Reset wait for interrupts ImcEADrvWaitForInterruptEx() Wait for interrupts with read

Data structures used The data structures "RESERVEINT" and "RESERVEINTEX" (for "ImcEADrvWaitForInterruptEx()") are used for the interrupt processing functions.

RESERVEINT Type definition Variables Description ULONG IntNr Number of interrupts for WINDOWS IMCEA (nPnP) ULONG Mode Exclusive or shared for WINDOWS IMCEA (nPnP):

INT_MODE_EXCLUSIVE INT_MODE_SHARED bus type for WINDOWS IMCEA(nPnP): INT_BUS_ISA INT_BUS_PCI Trigger mode for both drivers: INT_LATCHED INT_LEVELSENSITIVE

ULONG Timeout Timeout in milliseconds or INFINITE ULONG IntHandle Returned handle from the function

"ImcEADrvStartInterruptHandler()" ULONG Status Reason for feedback:

INT_NORMAL: Interrupt has arrived INT_BREAK: Interrupt is shut down INT_TIMEOUT: Timeout



RESERVEINTEX Type definition Variables Description ULONG Address Physical address read from there is for WINDOWS

IMCEA(nPnP) or offset for WINDOWS IMCEA(PnP)

ULONG Mode Reading mode: INT_MODE_IO_READ8 INT_MODE_IO_READ16 INT_MODE_IO_READ32 INT_MODE_MEM_READ8 INT_MODE_MEM_READ16 INT_MODE_MEM_READ32

ULONG Timeout Timeout in milliseconds or INFINITE ULONG IntHandle Returned handle from the function

"ImcEADrvStartInterruptHandler()" ULONG Status Reason for feedback:

INT_NORMAL: Interrupt has arrived INT_BREAK: Interrupt is shut down INT_TIMEOUT: Timeout

ULONG Value Input: Mask for read value Output: read value



5.4.1 ImcEADrvStartInterruptHandler()

Description The function "ImcEADrvStartInterruptHandler()" installs an interrupt service routine (ISR) for the transferred interrupt number. A flag informs the driver if the interrupt is to be used exclusively or shared.

Note

After calling this function the application must not trigger the interrupt. Only after calling the functions "ImcEADrvWaitForInterrupt()" or "ImcEADrvWaitForInterruptEx()" is the driver able to pass on the information to the application, without losing an interrupt.

Note

The driver WINDOWS IMCEA (PnP) already knows the interrupt number via the PnP mechanism. The parameters IntNr and Mode from the RESERVEINT structure are therefore not evaluated. As the WINDOWS IMCEA (PnP) driver can only operate PCI interrupts, the function "ImcEADrvWaitForInterrupt()" cannot be used.

Syntax

DWORD ImcEADrvStartInterruptHandler (

HANDLE hDrvHandle,

RESERVEINT *IntData )

Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" IntData Data structure for the interrupt processing function



Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_NO_SYSTEM_RESOURCES The required interrupt is already occupied ERROR_NO_MORE_ITEMS The number of occupied interrupts is too great

(max. 15)


RESERVEINT IntData; IntData.IntNo = 5; // IRQ IntData.IntHandle = 0; // Don`t care IntData.Mode = INT_MODE_SHARED|INT_BUS_ISA|INT_LEVELSENSITIVE; // Shared dwRetCode = ImcEADrvStartInterruptHandler( hDrvHandle,&IntData );

WINDOWS IMCEA (PnP) - programming example

RESERVEINT IntData; IntData.IntHandle = 0; // Don`t care IntData.Mode = INT_LATCHED; // latched dwRetCode = ImcEADrvStartInterruptHandler(hDrvHandle, &IntData ); if( dwRetCode == ERROR_SUCCESS )

{ printf("StartInterruptHandler(IntNo: 0x%x) was successful\n",

IntData.IntNo); }



5.4.2 ImcEADrvStopInterruptHandler()

Description The function "ImcEADrvStopInterruptHandler()" again enables the resources that have been reserved by means of the function "ImcEADrvStartInterruptHandler()".

Syntax

DWORD ImcEADrvStopInterruptHandler (

HANDLE hDrvHandle,


Parameter


Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_INVALID_ADDRESS The interrupt was not occupied

("Reserve interrupt" call missing)

Programming example

ImcEADrvStopInterruptHandler(hDrvHandle, &IntData );



5.4.3 ImcEADrvWaitForInterrupt()

Description The function "ImcEADrvWaitForInterrupt()" waits for the interrupt to arrive. This waiting function is informed of the result within the interrupt service routine (ISR). The function can now return to the application and hence report the interrupt event.

Note

This call can only be used for ISA interrupts and is therefore not suitable for the WINDOWS IMCEA (PnP) driver.

In order to be able to execute the function, within the application a special thread is required, which is executed asynchronously to the normal sequence. This thread needs a special handle to call in order to be able to access the driver. If the interrupt is not reported as being exclusive, then the application must itself check to see if the interrupt is coming from the module to be operated. The "Break" flag within the structure indicates if the interrupt is cancelled with the function "ImcEADrvResetWaitForInterrupt()".

Note

This call cannot be used for shared interrupts and level-triggered interrupts.

Syntax

DWORD ImcEADrvWaitForInterrupt (

HANDLE hDrvHandle,


Parameter




Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are

incorrect ERROR_INVALID_HANDLE The handle is invalid


ImcEADrvWaitForInterrupt(hDrvHandle, &IntData ); if( dwRetCode == ERROR_SUCCESS )

{ printf( "ImcEADrvWaitForInterrupt(Status: 0x%x) was successful\n",

IntData.Status); }



5.4.4 ImcEADrvResetWaitForInterrupt()

Description The function "ImcEADrvResetWaitForInterrupt()" acknowledges the wait functions "ImcEADrvWaitForInterrupt()" or "ImcEADrvWaitForInterruptEx()". You must use this function in order to cancel the wait functions.

Syntax

DWORD ImcEADrvResetWaitForInterrupt (

HANDLE hDrvHandle,


Parameter


Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are

incorrect ERROR_INVALID_HANDLE The handle is invalid

Programming example

ImcEADrvResetWaitForInterrupt(hDrvHandle, &IntData );



5.4.5 ImcEADrvWaitForInterruptEx()

Description The function "ImcEADrvWaitForInterruptEx()" waits for the interrupt to arrive. With an interrupt, the address (I/O or memory) given in the parameter block is read and masked with the transferred mask. If, after masking, a bit is still set, the interrupt from this module is triggered and the read value (without masking) is returned. This waiting function is informed of the result within the interrupt service routine (ISR). The function can now return to the application and therefore report the interrupt event. In order to be able to execute the function "ImcEADrvWaitForInterruptEx()", a special thread is required within the application and this is executed asynchronously to the normal sequence. This thread needs a special handle to call in order to be able to access the driver. The "Break" flag within the structure indicates if the interrupt has been cancelled with the function "ImcEADrvResetWaitForInterruptEx()".

Syntax

DWORD ImcEADrvWaitForInterruptEx (

HANDLE hDrvHandle,

RESERVEINTEX *IntDataX )

Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" IntDataX Data structure for the interrupt processing function

Returncode

Returncode Meaning ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_INVALID_HANDLE The handle is invalid



Programming example

RESERVEINTEX IntDataX; IntDataX.Address = 0x0; // relative address IntDataX.IntHandle = IntData.IntHandle; IntDataX.Mode = INT_MODE_MEM_READ32; IntDataX.Value = 0xffffffff; // check all bits IntDataX.Timeout = INFINITE; // wait till interrupt is occured dwRetCode = ImcEADrvWaitForInterruptEx(hDrvHandle, &IntDataX ); if( dwRetCode == ERROR_SUCCESS )

{ printf( "interrupt status register = 0x%x,status = 0x%x\n",

IntDataX.Value, IntData.Status); }

Example source functions 5.5 PCI address area - processing functions


5.5 PCI address area - processing functions

The following PCI address area processing functions can be used with the WINDOWS IMCEA driver:

Function Description ImcEADrvSearchPCI() Search configuration space



5.5.1 ImcEADrvSearchPCI()

Description The function "ImcEADrvSearchPCI()" searches the entire PCI bus for all functions that correspond with the selected parameters VendorID, DeviceID, Subsystem VendorID and Subsystem ID. In order to search all devices on the bus, VendorID = 0xFFFF can be transferred.

Note

Please refer to the manufacturer´s information concerning configuration space for precise details regarding the parameters DeviceID andVendorID.

The contents of the device(s) found are entered in the transferred config-space-field. The function cancels the search when the config-space-field is full. If the function finds no device on the bus for the selected parameters VendorID andDeviceID, then NumOfFunctions = 0 is set.

Syntax

DWORD ImcEADrvSearchPCI (

HANDLE hDrvHandle,

ULONG VendorID,

ULONG DeviceID,

ULONG SubVendorID,

ULONG SubDeviceID,

PCI_CONFIG_SPACE *ConfigSpace,

ULONG MaxNumOfFunctions,

ULONG *NumOfFunctions )



Structure of the PCI_CONFIG_SPACE field

uchar PciBusNum /* Bus number / uchar PciDeviceNum /* Device number / uchar PciFunctionNum /* Function number */ ushort VendorId ushort DeviceId ushort Cmdreg ushort StatReg uchar RevisionId uchar ClassCode[3] uchar CacheLineSize uchar LatencyTime uchar HeaderType uchar BIST uint BaseAdr0 uint BaseAdr1 uint BaseAdr2 uint BaseAdr3 uint BaseAdr4 uint BaseAdr5 uint CardbusCisPtr ushort SubsysVendorId ushort SubsysId uint ExpRomBaseAdr uint reserved[2] uchar IntLine /* Interrupt*/ uchar IntPin uchar Min_Gnt uchar Max_Lat

Parameter

Parameter Description hDrvHandle Return value of the function "ImcEADrvOpen()" VendorID Vendor ID DeviceID Device ID SubVendorID Subsystem Vendor ID SubDeviceID Subsystem ID ConfigSpace Array of Config-Space MaxNumOfFunctions Maximum number of entries in Config-Space NumOfFunctions Number of functions found

[out Parameter]



Returncode

Returncode Description ERROR_SUCCESS No error ERROR_INSUFFICIENT_BUFFER The data structures to / from the driver are incorrect ERROR_INVALID_HANDLE The handle is invalid

Programming example

// search for all PCI modules. dwRetCode = ImcEADrvSearchPCI( hDrvHandle, 0xffffffff,

0xffffffff,

0,

0,

ConfigSpace,

sizeof(ConfigSpace)/sizeof(PCI_CONFIG_SPACE),

&NumOfFunctions); if( dwRetCode != ERROR_SUCCESS )

{ printf( "ImcEADrvSearchPCI: Error 0x%lx\n", dwRetCode);

}


Creating an application 6

This chapter briefly explains how to create an application using the example source file for the SIMATIC Microbox PC 420 microbox.cpp. Visual Studio V6.0 serves as a development environment.

Procedures for creating an application 1. In Visual Studio V6.0 set up a new project via the menu "File / New". 2. Select the option "Win32 console application" and establish the file and project names. 3. Open the file microbox.cpp and select the option "Insert file in project". 4. Create the application via the menus "Create / Establish active configuration" and "Create

/ Regenerate everything". 5. Test your new application by means of the menu "Create / Start debug".

WINDOWS IMCEA Driver Programming Manual, Edition 02/2005, J31069-D2131-U001-A1-7618 Index-1

Index

C Close driver, 5-9 Creating an application, 6-1

D Describe ports, 5-14 Driver - basic functions, 5-2

E Enable interrupts, 5-27 Enable memory, 5-22 Enable ports, 5-13 Example source functions, 5-1

I ImcEADrvClose(), 5-9 ImcEADrvFreeMem(), 5-22 ImcEADrvFreePort(), 5-13 ImcEADrvInstallDriver(), 5-3 ImcEADrvOpen(), 5-8 ImcEADrvReadPort(), 5-16 ImcEADrvReserveMem(), 5-19 ImcEADrvReservePort(), 5-12 ImcEADrvResetWaitForInterrupt(), 5-30 ImcEADrvSearchPCI(), 5-34 ImcEADrvStartDriver(), 5-5 ImcEADrvStartInterruptHandler(), 5-25 ImcEADrvStopDriver(), 5-6 ImcEADrvStopInterruptHandler(), 5-27 ImcEADrvUninstallDriver(), 5-4 ImcEADrvWaitForInterrupt(), 5-28 ImcEADrvWaitForInterruptEx(), 5-31 ImcEADrvWritePort(), 5-14 Install driver (nPnP), 5-3 Interrupt - processing functions, 5-23 IOCTL functions, 4-1

M Memory - access functions, 5-18

O Open driver, 5-8

P PCI address area - processing functions, 5-33 Port - access functions, 5-10 Product components, 2-2

R Read ports, 5-16 Reserve interrupts, 5-25 Reserve memory, 5-19 Reserve ports, 5-12 Reset wait for interrupt, 5-30

S Search configuration space, 5-34 Software installation, 3-1 Start driver (nPnP), 5-5 Stop (nPnP) driver, 5-6

U Uninstall driver (nPnP), 5-4

W Wait for interrupts, 5-28 Wait for interrupts with read, 5-31 WINDOWS IMCEA (nPnP) installation, 3-2 WINDOWS IMCEA (PnP) installation, 3-6

Siemens AG

Automation and DrivesSystems EngineeringIndustrial PCPostfach 235590713 FürthGERMANY

www.siemens.com/sicompJ31069-D2131-U001-A1-7618

Programming Manual WINDOWS IMCEA Driver - … · Programming_Manual_ WINDOWS_IMCEA-driver.pdf ......

Documents

Transcript of Programming Manual WINDOWS IMCEA Driver - … · Programming_Manual_ WINDOWS_IMCEA-driver.pdf ......