Windows CE 6.0 APEX ZF

(1)

Windows CE 6.0

For

APEX ZF

User Guide

Document Reference: Windows CE User Guide

Document Issue: 1.0

(2)

Contents

Introduction ... 3

Windows CE 6.0 initialisation and booting overview ... 3

APEX-ZF hardware evaluation with Windows CE 6.0 ... 3

Development tool installation ... 5

Software development ... 8

System and Development tools ... 16

Display Resolution ... 16

Registry Settings ... 16

Regedit ... 17

Touch Screen Calibration ... 17

Visual Studio 2005 Remote Tools ... 17

APEX-ZF Hardware API Libraries ... 18

SMBUS API ... 18

EEPROM API ... 23

GPIO API ... 27

Watchdog API... 35

SYSMON API ... 39

LCD API ... 43

(3)

Introduction

Page 3

Introduction

The content of this document provides all the necessary information required to get started with

application development under Windows CE 6.0 for the APEX-ZF platform. It covers:

An overview of the Windows CE 6.0 Boot Process

How to evaluate the hardware quickly

How to install the tools necessary to develop applications that run under Windows CE 6.0

How to start developing applications

How to use the Hardware API functions supported under APEX-ZF

How to implement APEX-ZF interrupt processing

Windows CE 6.0 initialisation and booting overview

The APEX-ZF platform supports booting Windows CE 6.0 from IDE based media and Compact Flash.

In all implementations the boot process begins with the boot loader initialising. The boot loader

performs basic sanity checking on the hardware, initialises the video display and copies the Windows

CE 6.0 image from the solid state disk into RAM. Once this is complete control is passed to the Kernel

which starts the execution of operating system code. While the boot loader copies the Windows CE

6.0 image into memory a Blue Chip Technology splash screen and progress bar will be seen.

As part of the operating system boot process, Windows CE 6.0 loads device drivers for the major

components of hardware, as well as APEX-ZF drivers which allow access to EEPROM, Watchdog,

GPIO, and other board specific functions. The splash screen may disappear while the operating

system loads with the screen appearing blank.

If the Windows CE image supports the hive based registry, the registry is restored from solid state

media during boot. This allows the OS to persist registry settings through a cold boot.

APEX-ZF hardware evaluation with Windows CE 6.0

The APEX-ZF hardware API allows application developers to easily interface to the device specific

features of the board. These features are demonstrated in the SDK by the use of sample applications.

To allow quick evaluation of the APEX-ZF specific hardware features, the executable binaries of these

sample applications are included in the Evaluation CE 6.0 image. From the command prompt in

windows CE 6.0 run the following applications to test the desired functionality:

(4)

Introduction

Page 4

Application

Description

EEPROMSample.exe

This sample can be used for evaluating the EEPROM

storage capability of the APEX-ZF platform. This application

makes use of the EEPROM.dll API library.

GPIOSample.exe

This sample can be used for evaluating the general purpose

input/output, and analogue inputs of the APEX-ZF platform.

This application makes use of the GPIO.dll API library.

InterruptSample.exe

This sample binds to the APEX-ZF specific interrupt request

line and alerts when a watchdog, GPIO, or system monitor

interrupt occurs.

LCDSample.exe

This sample can be used for evaluating the character mode

LCD driver. The driver allows messages to be displayed on

an appropriate display via the printer port of the APEX-ZF.

See the APEX-ZF manual for details of displays supported,

and wiring diagrams. This application makes use of the

LCDAPI.dll API library.

MicroVersionSample.exe

This sample can be used to read the APEX-ZF firmware

version, and makes use of the SMBUSAPI.dll API library.

ResetSystemSample.exe

This sample can be used to reset the APEX-ZF system, and

makes use of the SMBUSAPI.dll API library.

SystemMonitorSample.exe

This sample demonstrates the system monitor capabilities of

APEX-ZF. It reads all the system voltages and temperatures

and displays them. It also allows the user to set an over

temperature limit for producing an interrupt when the CPU

get too hot.

WatchdogSample.exe

This sample can be used to exercise the watchdog of the

APEX-ZF. It provides an option select whether the watchdog

should cause an interrupt or system reset.

(5)

Installation

Page 5

Development tool installation

Application development targeting windows CE 6 for APEX-ZF environments requires Microsoft

Visual Studio 2005 SP1, Microsoft Active sync 4.5 or greater, and the APEX-ZF software

development kit.

The version of Visual Studio 2005 chosen must support smart device

development.

Ensure that Visual studio is fully installed along with active sync before following the

steps below to install the APEX-ZF SDK.

1. Launch the APEX-ZF SDK installer file from the support CD

2. Click next

(6)

Installation

Page 6

4.

Enter user and company name information and click next

5.

Choose complete installation

(7)

Installation

Page 7

7.

Click install

8.

After the installation completes click the “Finish” button

9.

The installation of the APEX-ZF SDK is now complete.

By default the APEX-ZF SDK installs to location: C:\Program Files\Windows CE

Tools\wce600\APEX-ZF SDK. In this location the following folders will be copied.

Folder

Description

Include

This folder holds all the header files required to build an application for the

APEX-ZF platform

Lib

This folder holds all the library files required to build an application for the

APEX-ZF platform

Sampleapplications This folder holds some sample applications that can be used as reference

while creating applications for APEX-ZF. The examples demonstrate of to

interface to all the APEX-ZF hardware libraries.

(8)

Software Development

Page 8

Software development

This section describes how to create an APEX-ZF Windows CE 6.0 application using the SDK and

deploy the application to the APEX-ZF device using Windows CE Corecon over Ethernet. The sample

application created will demonstrate how to link to the APEX-ZF SMBUSAPI and read the device

firmware version.

1.

Open Visual Studio 2005. Click on File ->New ->Project to begin a new project.

2.

Under the “Visual C++” language click “smart device”. Select “Win32 Smart Device

Project” and give the project the name “SystemVersion”. Click OK

(9)

Page 9

3.

The smart device project wizard should now start. Click next to begin. The APEX-ZF

SDK installed in the previous section should now be populated in the “Installed SDKs”

list. Arrange the list boxes so that “APEX-ZF SDK” is the only SDK in the “Selected

SDK’s” list. Click Next.

(10)

Page 10

5.

Modify the SystemVersion.cpp file to look as below:

#include "stdafx.h" #include <windows.h> #include <commctrl.h>

#include <smbus.h> //holds the SMBUSAPI definitions and error codes

#include <azfavr.h> //holds the APEXZF specific SMBUS function codes

int _tmain(int argc, TCHAR *argv[], TCHAR *envp[]) {

DWORD dwReturnCode; WORD wVersion;

printf("APEX-ZF Micro version sample application V1.00\n\n");

dwReturnCode = BCTSmbusReadWord(AVR_SLAVE_ADDRESS, SMBUS_COMMAND_GET_VERSION,&wVersion); if(dwReturnCode == 0)

{

printf("Version Major: %.2x Version Minor: %.2x\n", HIBYTE(wVersion), LOBYTE(wVersion));

return 0; }

else

{

printf("Get version failed with return code: %d\n", dwReturnCode);

return 1; }

}

6.

As this application is using functions exported by the SMBUSAPI library we need to link

this project to the file “SMBUSAPI.lib”. From the “Project” menu click add an existing

item

(11)

Page 11

7.

Navigate to “C:\Program Files\Windows CE Tools\wce600\APEX-ZF SDK\Lib\x86”,

show files of type “All Files *.*” and add the file SMBUSAPI.lib. The file should now

appear in solution explorer.

8.

We are now ready to compile and build the sample application. From the “Build” menu

click on “Rebuild Solution”.

(12)

Page 12

9.

If the compile and build was successful the output window should state “1 succeeded, 0

failed”.

10.

Visual Studio 2005 SP1 supports deploying applications automatically to the target

device and debugging applications remotely. To configure this, the target devices IP

address must be configured in visual studio and Corecon must be enabled on the target

device. To retrieve the IP address of the target device type “IPconfig” from the command

prompt in windows CE and note down the IP address for the next steps.

(13)

Page 13

11.

From the “Tools” menu in Visual Studio select “Options”.

12.

From the “Device Tools” tree, select “Devices” and the device “APEX-ZF SDK x86

Device”. Click properties.

13.

Click configure next to “TCP Connect Transport”, select “Use Specific IP Address” and

enter the IP address obtained in stage 10. Click “Ok” to exit setting pages get back to

visual studio.

(14)

Page 14

14.

On the remote machine from the desktop click “Start” then “Run”. Enter

“conmanclient2” and click “OK”.

15.

On the remote machine from the desktop click “Start” then “Run”. Enter “cmaccept” and

click “OK”.

(15)

Page 15

16.

Now that “Corecon” is enabled on the target machine and the Target devices IP address

is configured in visual studio we can deploy our application remotely from Visual Studio.

This step must be completed within 3 minutes of step 15. If 3 minutes elapse simply

complete step 15 again. From the “Debug” menu click on “Start Debugging”. Visual

studio should now download the application to the target and run it.

Notes

Steps 14 and 15 only need to be performed once per system boot. I.e. After a

successful deploy, a developer only needs to click “Start Debugging” from the

“Debug” menu to begin another deploy and debug session.

You

can eliminate stage 15 by disabling security on the device. To do so, use the

remote registry editor, or regedit to set HLKM\System\CoreConOverrideSecurity = 1

DWORD value. Disabling security exposes your device to malicious attack and is not

recommended unless you have provided appropriate safeguards.

(16)

System & Development Tools

Page 16

System and Development tools

Display Resolution

Windows CE 6.0 for APEX-ZF comes with a display resolution control panel that can be

used for changing the display adapters screen resolution and active displays. It can be

accessed from the system control panel. All changes made using this utility require a reboot

to take effect.

Registry Settings

Windows CE 6.0 for APEX-ZF comes with a hive based registry enabled by default. This

allows registry settings to be persisted through a cold boot. The Registry Settings utility,

accessible from the system control panel can be used to set how often the volatile registry is

backed up to solid state media, and perform manual commits.

(17)

System & Development Tools

Page 17

Regedit

Windows CE 6.0 for APEX-ZF comes with a built in registry editor in the style of the

standard Windows registry editor. To access it load “regedit” from either the command

prompt or Run menu.

Touch Screen Calibration

If the Windows CE image includes support for a touch screen controller, it can be calibrated

using a built in calibration utility. To access it load “calibrate” from either the command

prompt or Run menu. Ensure that the touch screen is connected to COM1 before booting the

CE image for it to be detected properly.

Visual Studio 2005 Remote Tools

Visual 2005 includes remote tools that can be used for managing Windows CE images and

debugging Windows CE applications. All the remote tools require Corecon to be enabled on

the target device. Follow steps 10-15 in the previous section to configure Corecon. The

remote tools must be run from the start menu rather than Visual Studio itself at location:

Start->Programs->Microsoft Visual Studio 2005->Visual Studio Remote Tools.

The table below details the remote tools available and their purpose:

Remote Tool

Purpose

Remote File Viewer

Used to browse a remote CE device for files

and folders.

Remote Registry Editor

Used to remotely view and edit a Windows

CE registry

Remote Heap Walker

Used to remotely view the memory allocation

(heap) on a CE device

Remote Spy

Used to remotely view Windows/Messages

on a CE device

Remote Process Viewer

Used to remotely view processes running on

a Windows CE device

Remote Zoom In

Used to get a current snap shot of a CE

devices desktop

(18)

Hardware API libraries

Page 18

APEX-ZF Hardware API Libraries

SMBUS API

All APEX-ZF hardware functionality (GPIO, EEPROM, Watchdog, System monitor, etc) are

accessed via the SMBUS. The SMBUSAPI is provided to give developers a simple

mechanism for accessing these functions. The five SMBUSAPI functions provided are

detailed over the next pages.

BCTSmbusWriteByte

Sends a command, and writes a byte of data to a device on the SMBUS.

DWORD WINAPI BCTSmbusWriteByte (BYTE bDeviceAddress, BYTE bCommand, BYTE bData);

Parameters

bDeviceAddress

[in] The slave address on the SMBUS to send the command to bCommand

[in] The SMBUS command identifier bData

[in] A byte of data to pass in with the command. For commands that do not require any data be passed in, set this value to 0x00

Return Value

If the function succeeds, the return value is

SMBUS_OK

.

If the function fails, the return value is a nonzero error code defined in SMBUS.h.

Remarks

See the APEX-ZF hardware manual for a list of supported SMBUS commands with their definitions. As the SMBUS architecture is a two wire interface it operates on a “first come first served” bases. For this reason the driver also operates in the same way and limits access to its functions to one process at a time. If the SMBUS is accessed while already in use the error code

SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

will be returned and is normal. The application should wait for an undefined period before retrying.

Requirements

Header

Declared in SMBUS.h & azfavr.h

Library

Use SMBUSAPI.lib.

(19)

Page 19

BCTSmbusReadByte

Sends a command, and reads a byte of data from a device on the SMBUS.

DWORD WINAPI BCTSmbusReadByte (BYTE bDeviceAddress, BYTE bCommand, PBYTE pbData);

Parameters

bDeviceAddress

[out] A pointer to an 8 bit value to hold the data returned

Return Value

SMBUS_OK

.

Remarks

SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use SMBUSAPI.lib.

(20)

Page 20

BCTSmbusWriteWord

Sends a command, and writes a word of data to a device on the SMBUS.

DWORD WINAPI SmbusWriteWord (BYTE bDeviceAddress, BYTE bCommand, WORD wData);

Parameters

bDeviceAddress

[in] The SMBUS command identifier wData

[in] A word of data to pass in with the command. For commands that do not require any data be passed in, set this value to 0x00

Return Value

SMBUS_OK

.

Remarks

SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use SMBUSAPI.lib.

(21)

Page 21

BCTSmbusReadWord

Sends a command, and reads a word of data from a device on the SMBUS.

DWORD WINAPI SmbusReadByte (BYTE bDeviceAddress, BYTE bCommand, PWORD pwData);

Parameters

bDeviceAddress

Return Value

SMBUS_OK

.

Remarks

SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use SMBUSAPI.lib.

(22)

Page 22

BCTSmbusProcessCall

Sends a command, writes a word of data and reads back a word of data from a device on the SMBUS in one transaction.

DWORD WINAPI SmbusReadByte (BYTE bDeviceAddress, BYTE bCommand, WORD wInData, PWORD pwOutData);

Parameters

bDeviceAddress

[in] The SMBUS command identifier wInData

[in] A word of data to pass in with the command. wOutData

Return Value

SMBUS_OK

.

Remarks

SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use SMBUSAPI.lib.

(23)

Page 23

EEPROM API

The EEPROM API library sits on top of the SMBUSAPI library to provide a simple

framework for accessing the 500 bytes of non volatile EEPROM memory on an APEX-ZF.

The library exports four functions which are detailed below.

BCTWriteEeprom

Writes a byte of data to a location in EEPROM.

DWORD WINAPI BCTWriteEeprom (WORD wOffset, BYTE bVal);

Parameters

wOffset

[in] The location in EEPROM to write the value. Valid locations are 0-499 bVal

[in] That value to be written

Return Value

EEPROM_OK

.

If the function fails, the return value is a nonzero error code defined in eeprom.h.

Remarks

See the APEX-ZF hardware manual for further details on the APEX-ZF EEPROM.

As the SMBUS architecture is a two wire interface it operates on a “first come first served” bases. For this reason the EEPROM driver also operates in the same way and limits access to its functions to one process at a time. If the EEPROM is accessed while the SMBUS is already in use the error code

EEPROM_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

will be returned and is normal. The

application should wait for an undefined period before retrying.

Requirements

Header

Declared in EEPROM.h

Library

Use eeprom.lib.

(24)

Page 24

BCTReadEeprom

Reads a byte of data from a location in EEPROM

DWORD WINAPI BCTReadEeprom (WORD wOffset, PBYTE pbVal);

Parameters

wOffset

[in] The location in EEPROM to read the value from. Valid locations are 0-499 pbVal

[out] Pointer to an 8 bit value that will hold the returned EEPROM value

Return Value

EEPROM_OK

.

Remarks

EEPROM_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use eeprom.lib.

(25)

Page 25

BCTEraseEepromByte

Erases a location in EEPROM.

DWORD WINAPI BCTEraseEepromByte (WORD wOffset);

Parameters

wOffset

[in] The location in EEPROM to erase.

Return Value

EEPROM_OK

.

Remarks

EEPROM_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use eeprom.lib.

(26)

Page 26

BCTEraseEeprom

Erases the entire EEPROM.

DWORD WINAPI BCTEraseEeprom (VOID); Parameters

Return Value

EEPROM_OK

.

Remarks

EEPROM_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use eeprom.lib.

(27)

Page 27

GPIO API

The GPIO API library sits on top of the SMBUSAPI library to provide a simple framework

for using the eight general purpose inputs or outputs of the APEX-ZF. The library exports

eight functions which are detailed below.

BCTSetGPIOPinFunction

Sets the functions of GPIO bits 0-3 to either Digital input/output or analogue input. DWORD WINAPI BCTSetGPIOPinFunction (BYTE bVal);

Parameters

bVal

[in] A bitmap of the required pin functions. Bit set = analogue input. Bit cleared = Digital input/output. The 4 most significant bits are ignored.

E.g. Passing a value of 0x05 into the function would set bits 0 and 2 to analogue inputs and bits 1 and 3 to digital input/outputs.

Return Value

GPIO_OK

.

If the function fails, the return value is a nonzero error code defined in gpio.h.

Remarks

See the APEX-ZF hardware manual for further details on the APEX-ZF GPIO.

As the SMBUS architecture is a two wire interface it operates on a “first come first served” bases. For this reason the GPIO driver also operates in the same way and limits access to its functions to one process at a time. If the GPIO is accessed while the SMBUS is already in use the error code

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(28)

Page 28

BCTSetGPIOPinDirection

Sets the functions of GPIO bits to either input or output. DWORD WINAPI BCTSetGPIOPinDirection (BYTE bVal);

Parameters

bVal

[in] A bitmap of the required pin directions. Bit set = input. Bit cleared = output.

E.g. Passing a value of 0x05 into the function would set bits 0 and 2 to inputs and other bits to outputs

Return Value

GPIO_OK

.

Remarks

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(29)

Page 29

BCTSetGPIOPullups

Sets the functions of GPIO bit pull-ups to either enabled for disabled. DWORD WINAPI BCTSetGPIOPullups (BYTE bVal);

Parameters

bVal

[in] A bitmap of the required pin pull-ups. Bit set = enabled. Bit cleared = disabled. E.g. Passing a value of 0x05 into the function would set bits 0 and 2 to pulled up.

Return Value

GPIO_OK

.

Remarks

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(30)

Page 30

BCTReadGPIOPort

Reads the current state of the GPIO port

DWORD WINAPI BCTReadGPIOPort (PBYTE pbVal);

Parameters

pbVal

[out] A pointer to an 8 bit value that will hold the value of the GPIO port.

Return Value

GPIO_OK

.

Remarks

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(31)

Page 31

BCTWriteGPIOPort

Writes a byte to the GPIO port

DWORD WINAPI BCTWriteGPIOPort (BYTE bVal);

Parameters

bVal

[in] The byte that gets written to the GPIO port.

Return Value

GPIO_OK

.

Remarks

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(32)

Page 32

BCTGetAnalogueInput

Reads an ADC channel.

DWORD WINAPI BCTGetAnalogueInput (WORD wADCSource, PWORD pwVal);

Parameters

wADCSource

[in] The ADC source to read. Acceptable values 0-3. pwValue

[out] A pointer to a 16 bit value that will hold the result of the ADC conversion

Return Value

GPIO_OK

.

Remarks

It is the application developers responsibility to ensure that the ADC channel being read is set as an analogue input and of input direction before calling this function.

It is recommended that pull-ups are disabled on pins that are analogue inputs. See the APEX-ZF hardware manual for further details on the APEX-ZF GPIO.

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(33)

Page 33

BCTSetGPIOBit

Sets an individual bit to a value specified

DWORD WINAPI BCTSetGPIOBit (BYTE bBitNumber, BOOL iValue);

Parameters

bBitNumber

[in] The bit that should be written. Acceptable values 0-7 iValue

[in] The value to be written to the bit. TRUE = Set, FALSE = Clear

Return Value

GPIO_OK

.

Remarks

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(34)

Page 34

BCTGetGPIOBit

Gets the value of an individual bit

DWORD WINAPI BCTGetGPIOBit (BYTE bBitNumber, PBOOL piValue);

Parameters

bBitNumber

[in] The bit that should be read. Acceptable values 0-7 iValue

[in] A pointer to an BOOL that will hold the state of the pin. TRUE = Set, FALSE = Clear

Return Value

GPIO_OK

.

Remarks

GPIO_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in GPIO.h

Library

Use GPIO.lib.

(35)

Page 35

Watchdog API

The Watchdog API library sits on top of the SMBUSAPI library to provide a simple

framework for using the watchdog functionality of APEX-ZF. The library exports four

functions which are detailed below.

BCTSetWatchdogResponse

Sets what the response to a watchdog event should be

DWORD WINAPI BCTSetWatchDogResponse (BYTE bResponse);

Parameters

bResponse

[in] What the response to a watchdog event should be. Valid options are:

BCTWDG_RESET

BCTWDG_INTERRUPT

Return Value

WATCHDOG_OK.

If the function fails, the return value is a nonzero error code defined in watchdog.h.

Remarks

See the APEX-ZF hardware manual for further details on the APEX-ZF Watchdog.

As the SMBUS architecture is a two wire interface it operates on a “first come first served” bases. For this reason the watchdog driver also operates in the same way and limits access to its functions to one process at a time. If the watchdog is accessed while the SMBUS is already in use the error code

WATCHDOG_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in Watchdog.h & azfavr.h

Library

Use watchdog.lib.

(36)

Page 36

BCTEnableWatchdog

Enables the APEX-ZF watchdog to timeout in the time specified DWORD WINAPI BCTEnableWatchDog (BYTE bTimeout);

Parameters

bTimeout

[in] The duration in seconds before a timeout is triggered. Must be greater than 0.

Return Value

WATCHDOG_OK.

Remarks

As the SMBUS architecture is a two wire interface it operates on a “first come first served” bases. For this reason the Watchdog driver also operates in the same way and limits access to its functions to one process at a time. If the Watchdog is accessed while the SMBUS is already in use the error code

WATCHDOG_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use watchdog.lib.

(37)

Page 37

BCTDisableWatchdog

Disables the APEX-ZF watch.

DWORD WINAPI BCTDisableWatchDog (VOID); Parameters

Return Value

WATCHDOG_OK.

Remarks

WATCHDOG_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use watchdog.lib.

(38)

Page 38

BCTRefreshWatchdog

Resets the watchdog counter to the timeout value. DWORD WINAPI BCTRefreshWatchDog (VOID); Parameters

Return Value

WATCHDOG_OK.

Remarks

WATCHDOG_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use watchdog.lib.

(39)

Page 39

SYSMON API

The Sysmon API library sits on top of the SMBUSAPI library to provide a simple framework

for using the system monitoring functionality of APEX-ZF. The library exports four

functions which are detailed below.

BCTSetCPUOverTemperatureLimit

Set the APEX-ZF CPU temperature threshold. When this temperature is breached a system interrupt is generated.

DWORD WINAPI BCTSetCPUOverTemperatureLimit (char cTemp);

Parameters

cTemp

[in] The maximum temperature in degrees Celsius allowable before a temperature interrupt occurs. Acceptable values are -40 to 125

Return Value

SYSMON_OK.

If the function fails, the return value is a nonzero error code defined in sysmon.h.

Remarks

See the APEX-ZF hardware manual for further details on the APEX-ZF system monitor.

SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Declared in sysmon.h

Library

Use sysmon.lib.

(40)

Page 40

BCTReadVoltage

Reads a specified voltage from APEX-ZF

DWORD WINAPI BCTReadVoltage (BYTE bVoltageSource, DOUBLE * pdVoltageReading);

Parameters

bVoltageSource

[in] The voltage source. Acceptable values are:

VOLTAGE_MONITOR_POS3V3 = 3.3 voltage rail

VOLTAGE_MONITOR_POS5V = 5 voltage rail

VOLTAGE_MONITOR_CPUCORE = CPU core voltage

pdVoltageReading

[out] pointer to a double value that will hold the voltage returned.

Return Value

SYSMON_OK.

Remarks

SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use sysmon.lib.

(41)

Page 41

BCTReadTemp

Reads a specified voltage from APEX-ZF

DWORD WINAPI BCTReadTemp (BYTE bTempSource, char * pcTempReading);

Parameters

bTempSource

[in] The temperature source. Acceptable values are:

TEMP_MONITOR_CPU = CPU temperature

pdVoltageReading

[out] pointer to a char value that will hold the temperature returned.

Return Value

SYSMON_OK.

Remarks

SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use sysmon.lib.

(42)

Page 42

BCTPowerOff

Powers off the CPU core and 3.3 voltage rails. DWORD WINAPI BCTPowerOff (VOID); Parameters

Return Value

SYSMON_OK.

Remarks

Using this function will lead to the APEZ-ZF unit being powered off and require a manual reset to enable the voltage lines.

SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS

Requirements

Header

Library

Use sysmon.lib.

(43)

Page 43

LCD API

The LCD API library provides developers with a simple interface that allows an APEX-ZF to

communicate with character mode LCD’s, via the onboard printer port. The driver supports

any character mode LCD based on the Hitachi HD44780x based controller.

Before using the LCD API, the LCD driver must be setup with the base address of the printer

port being used. The default setting for an APEX-ZF is 0x378 and the default LCD driver

setting reflects this. If the APEX-ZF printer port is being operating with automatic settings

the LCD driver should not require any configuration of the base address.

If the base address being used is different to 0x378 the base address can be changed through a

registry entry. Using the registry editor or remote registry editor, navigate to

“

HKEY_LOCAL_MACHINE\Drivers\BuiltIn\Lcd”

and change the key

"BaseAddress"

to

the required value. Ensure that the registry hive is committed and perform a reset for the

changes to take effect.

The LCD API library exports four functions which are detailed below.

BCTLCDOpen

Opens the printer port in preparation for talking to an LCD display. DWORD WINAPI BCTLCDOpen (BYTE bXsize, BYTE bYsize);

Parameters

bXsize

[in] The number of columns in the display bYsize

[in] The number of rows in the display

Return Value

LCD_OK.

If the function fails, the return value is a nonzero error code defined in lcd.h.

Remarks

This function must be called before any other LCDAPI functions are used.

See the APEX-ZF hardware manual for further details on the APEX-ZF character LCD support.

Requirements

Header

Declared in LCD.h

Library

Use LCDAPI.lib.

(44)

Page 44

BCTLCDWriteCharacter

Writes a single character to the LCD display

DWORD WINAPI BCTLCDWriteCharacter (BYTE bXpos, BYTE bYpos, BYTE bChar);

Parameters

bXpos

[in] The column in the display to write the character bYpos

[in] The row in the display to write the character bChar

[in] The character to write

Return Value

LCD_OK.

Remarks

Requirements

Header

Declared in LCD.h

Library

Use LCDAPI.lib.

(45)

Page 45

BCTLCDClearDisplay

Clears the LCD display

DWORD WINAPI BCTLCDClearDisplay (VOID); Parameters

Return Value

LCD_OK.

Remarks

Requirements

Header

Declared in LCD.h

Library

Use LCDAPI.lib.

DLL

Requires LCDAPI.dll.

BCTLCDClose

Closes the handle to the LCD driver DWORD WINAPI BCTLCDClose (VOID); Parameters

Return Value

LCD_OK.

Remarks

Requirements

Header

Declared in LCD.h

Library

Use LCDAPI.lib.

(46)

Page 46

APEX-ZF Interrupt Processing

The APEX-ZF features a dedicated interrupt request line allowing system events to trigger a

response in a user’s application. The APEX-ZF currently supports interrupting when:

A watchdog event occurs

The system CPU temperature rises above the set threshold

A GPIO pin changes state

The interrupt request line is dedicated to IRQ 5 and does not support interrupt sharing. For

this reason IRQ 5 must be reserved in the BIOS for use with ISA devices, thus preventing

IRQ 5 being allocated to another device. See the APEX-ZF hardware manual for details on

how to achieve this.

The BCTISR and BCTIST built-in drivers manage the actual binding, triggering, and clearing

of this interrupt, with two system events used for passing interrupt notification to and from

user’s applications. These system events are called, “

BCTINTTEVENT

” and

“

BCTINTCOMPEVENT

” which are both case sensitive. The BCTIST driver creates the

“

BCTINTTEVENT

” event and it is the application writes responsibility to open and bind to this

event. It is also the applications writers responsibility to create the “

BCTINTCOMPEVENT

” event

which the driver then binds to. The definition of these system events is as follows

“

BCTINTTEVENT

” = A system interrupt has occurred. Set by the driver when an interrupt is

detected.

“

BCTINTCOMPEVENT

” = The system interrupt has been serviced. Set by the application when

all interrupt related processing is complete.

Before an application can bind to a system event and monitor interrupts it must first check

that the BCTISR and BCTIST device drivers have loaded successfully. This can be achieved

in two ways:

1.

Check that a logical system interrupt (“sysintr”) value allocation exists at registry

location: “

HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BCTIST

”. When a device driver

binds to an IRQ a logical system interrupt (“sysintr”) is allocated. If this value is

missing it indicates that the BCTIST driver failed to load.

2.

Ensure that the system event “

BCTINTTEVENT

” exists. If the application fails to open

this event it indicates that the BCTIST driver failed to load.

As an interrupt event can occur from numerous sources, the SMBUS command

GET_IRQ_SOURCE

is provided which returns what caused the interrupt as well as clearing the

interrupt. See the APEX-ZF hardware manual for details on the

GET_IRQ_SOURCE

SMBUS

command.

When an application first loads it is impossible to determine if an interrupt has already

occurred. Before binding itself to the system event “

BCTINTTEVENT

”, the SMBUS command

GET_IRQ_SOURCE

should be issued to ensure that the interrupt is cleared allowing further

(47)

Hardware API libraries

Page 47

After receiving the system event “

BCTINTTEVENT

” and completing all relevant processing the

application services the interrupt must set the system event, “

BCTINTCOMPEVENT

”. This alerts

the driver that the application has finished processing the event and can now receive another

one. If the system event, “

BCTINTCOMPEVENT

” is never set, further interrupts will not be

received.

The following shows the steps that an application should follow when binding to the

APEX-ZF system events:

1.

Check that a logical system interrupt (“sysintr”) value allocation exists at registry

location: “

HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BCTIST

”. Fail if not.

2.

Open system event, “

BCTINTTEVENT

” and check it exists. Fail if not.

3.

Create a system event called, “

BCTINTCOMPEVENT

”.

4.

Create a thread that will manage interrupt events.

5.

Call SMBUS command

GET_IRQ_SOURCE

to reset any previous interrupts that may

have occurred.

6.

Start the thread created in step 4.

7.

Wait on the system event “

BCTINTTEVENT

” to be triggered by the driver.

8.

Call SMBUS command

GET_IRQ_SOURCE

to get the source of the interrupt and reset

the interrupt.

9.

Perform any further processing.

10.

Set the event “

BCTINTCOMPEVENT

” to allow the driver to provide further interrupts.

11.

Got back to step 7.

The following code sample demonstrates the above. The full sample can be viewed in the

APEX-ZF SDK at location: C:\Program Files\Windows CE Tools\wce600\APEX-ZF

SDK\Sampleapplications\Interruptsample.

/* --- */ /* SetupInterrupt - Function to set up interrupt threads and */ /* events */

/* Input : None */

/* Return : BOOL True = success */ /* --- */

BOOL SetupInterrupt( VOID ) {

DWORD dwSysIntr; DWORD dwRetVal; HKEY hKeyActive;

BOOL bErrorFlag = FALSE;

int m_nISTPriority; DWORD dwSize; DWORD dwThreadID; BYTE bResult; DWORD dwResult; int iTryCounter = 0;

// Create the subkey in the registry that we want to look at.

dwRetVal = RegOpenKeyEx(HKEY_LOCAL_MACHINE, (LPTSTR)REGPATH, 0, KEY_ALL_ACCESS, &hKeyActive);

if (dwRetVal != ERROR_SUCCESS) {

RETAILMSG(1, (TEXT("IST: Failed to open BCTIST registry key\r\n"))); CloseKeys(hKeyActive);

return FALSE; }

else

{

//Check that SysIntr exists in the registry under Drivers\BuiltIn\bctist. //If this value is missing it suggests that the driver failed to bind to the IRQ during startup.

(48)

Hardware API libraries

Page 48

dwSize = sizeof(dwSysIntr);

dwRetVal = RegQueryValueEx(hKeyActive, (LPTSTR)SYSINTRNAME, 0, NULL, (LPBYTE)&dwSysIntr, &dwSize);

if (dwRetVal != ERROR_SUCCESS) {

//sysintr is missing from the registry

RETAILMSG(1, (TEXT("IST: Failed to get sysintr from registry\r\n"))); CloseKeys(hKeyActive);

return FALSE; }

else

{

RETAILMSG(1, (TEXT("IST: Got sysintr %d from registry\r\n"),dwSysIntr));

} }

//Store sysintr incase it can be used later in the application

if(dwSysIntr != 0) {

g_dwSysInt = dwSysIntr; }

//Close registry keys

CloseKeys(hKeyActive);

//Open interrupt event "BCTINTTEVENT"

//This is a named event created by the BCTIST driver during startup. We bind to this event

//to allow interrupts to be processed by the application.

//If this event is does not exist it suggests that the driver failed to bind to the IRQ during startup

g_hevInterrupt = OpenEvent(EVENT_ALL_ACCESS, FALSE, TEXT("BCTINTTEVENT"));

if (g_hevInterrupt == NULL) {

RETAILMSG(1, (TEXT("IST: Failed to open BCTINTTEVENT Event\r\n")));

return FALSE; }

else

{

RETAILMSG(1, (TEXT("IST: Opened BCTINTTEVENT Event\r\n"))); }

//Create interrupt complete event "BCTINTCOMPEVENT".

//It is the application writers responsibility to create a named event of name "BCTINTCOMPEVENT".

//After setting the "BCTINTTEVENT" event, the driver waits for the "BCTINTCOMPEVENT" to be set by the application before clearing the interrupt.

//If the "BCTINTCOMPEVENT" event is not created the driver will not pass interrupts on the application.

//If the "BCTINTCOMPEVENT" event is not set after processing an interrupt, the application will not receive further interrupts

g_hevInterruptdone = CreateEvent(NULL, FALSE, FALSE, TEXT("BCTINTCOMPEVENT"));

if (g_hevInterruptdone == NULL) {

RETAILMSG(1, (TEXT("IST: BCTINTCOMPEVENT Event creation failed!!!\r\n")));

return FALSE; }

else

{

RETAILMSG(1, (TEXT("IST: Created BCTINTCOMPEVENT Event\r\n"))); }

// Create a thread that waits for signaling

g_fRun = TRUE;

g_htIST = CreateThread(NULL, 0, ThreadIST, NULL, CREATE_SUSPENDED, &dwThreadID);

if(g_htIST == NULL) {

RETAILMSG(1, (TEXT("IST: Failed to create thread\r\n")));

return FALSE; }

else

{

RETAILMSG(1, (TEXT("IST: Thread created\r\n"))); }

(49)

Hardware API libraries

Page 49

m_nISTPriority = 5;

if( !CeSetThreadPriority( g_htIST, m_nISTPriority )) {

RETAILMSG(1,(TEXT("IST: Failed setting Thread Priority.\r\n")));

return FALSE; }

else

{

RETAILMSG(1,(TEXT("IST: Thread priority set\r\n"))); }

//Before using the Interrupt, the application writed must ensure that it is cleared. //This is achived by sending as SMBUS_COMMAND_GET_IRQ_SOURCE smbus command.

//keep trying until the smbus command is successful or fails more than MAXTRIES times

while(iTryCounter < MAXTRIES) {

dwResult = BCTSmbusReadByte(AVR_SLAVE_ADDRESS, SMBUS_COMMAND_GET_IRQ_SOURCE, &bResult);

if(dwResult != 0) {

//only error we should expect is SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS. //This is by design due to the nature of the SMBUS architecture

if(dwResult == SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS) {

iTryCounter++;

//wait before trying again

Sleep(3); } else { break; } } else { break; } } if(dwResult != 0) {

MessageBox(NULL, TEXT("Failed to issue GET_IRQ_SOURCE command. Interrupts are not operational"), TEXT("ERROR"), 0);

}

// Get the thread started //

ResumeThread( g_htIST );

return TRUE; }

/* --- */

/* ThreadIST - The interrupt service thread */ /* */

/* Input : None */

/* Return : None */ /* --- */

DWORD WINAPI ThreadIST( LPVOID lpvParam ) {

DWORD dwStatus; DWORD dwResult; BOOL fState = TRUE; BYTE bResult; int iTryCounter = 0;

// Always check the running flag

while( g_fRun ) {

//wait for interrupt event

dwStatus = WaitForSingleObject(g_hevInterrupt, INFINITE); // Check to see if we are finished

(50)

Hardware API libraries

Page 50

// Make sure we have the object

if( dwStatus == WAIT_OBJECT_0 ) {

// Do all interrupt processing to complete the interaction // with the board so we can receive another interrupt.

iTryCounter = 0;

while(iTryCounter < MAXTRIES) {

dwResult = BCTSmbusReadByte(AVR_SLAVE_ADDRESS, SMBUS_COMMAND_GET_IRQ_SOURCE, &bResult);

if(dwResult != 0) {

//only error we should expect is SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS.

//This is by design due to the nature of the SMBUS architecture

if(dwResult == SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS) {

RETAILMSG(1,(TEXT("IST: SMBUS locked by other process\r\n")));

iTryCounter++;

//wait before trying again

Sleep(3); } else { break; } } else { break; } } if(dwResult != 0) {

MessageBox(NULL, TEXT("An interrrupt has occurred but failed to get source"), TEXT("Interrrupt") ,0);

RETAILMSG(1,(TEXT("IST: Failed to get irq source for sysintr %d with error code: %d\r\n"),g_dwSysInt, dwResult ));

}

else

{

RETAILMSG(1,(TEXT("IST: Got irq source %d for sysintr %d\r\n"), bResult, g_dwSysInt ));

if(bResult == 1) {

MessageBox(NULL, TEXT("A Watchdog interrrupt has occurred"), TEXT("Interrrupt") ,0);

}

else if(bResult == 2) {

MessageBox(NULL, TEXT("A GPIO interrrupt has occurred"), TEXT("Interrrupt") ,0);

}

else if(bResult == 4) {

MessageBox(NULL, TEXT("A CPU Temperature interrrupt has occurred"), TEXT("Interrrupt") ,0);

}

else

{

MessageBox(NULL, TEXT("IST: An interrrupt has occurred from an unexpected source"), TEXT("Interrrupt") ,0);

RETAILMSG(1,(TEXT("IST: An interrrupt has occurred from an unexpected source: %d"),bResult ));

}

//Tell the driver that we have finished processing the interrupt

SetEvent(g_hevInterruptdone); } } } return 0; }