Windows CE 6.0 For APEX ZF User Guide Document Reference: Windows CE User Guide Document Issue: 1.0
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 APEX-ZF Interrupt Processing... 46
Introduction 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: Page 3
Introduction Application EEPROMSample.exe Description 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. Page 4
Installation 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 3. Accept the licence agreement and click next Page 5
Installation 4. Enter user and company name information and click next 5. Choose complete installation 6. Click next Page 6
Installation 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 Include Lib Sampleapplications Description This folder holds all the header files required to build an application for the APEX-ZF platform This folder holds all the library files required to build an application for the APEX-ZF platform 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. Page 7
Software Development 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 Page 8
Software Development 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. 4. Select console application from the Application type selection box and click finish. Page 9
Software Development 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 Page 10
Software Development 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. Page 11
Software Development 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. Page 12
Software Development 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. Page 13
Software Development 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. Page 14
Software Development 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. Page 15
System & Development Tools 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. Page 16
System & Development Tools 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 Remote File Viewer Remote Registry Editor Remote Heap Walker Remote Spy Remote Process Viewer Remote Zoom In Purpose Used to browse a remote CE device for files and folders. Used to remotely view and edit a Windows CE registry Used to remotely view the memory allocation (heap) on a CE device Used to remotely view Windows/Messages on a CE device Used to remotely view processes running on a Windows CE device Used to get a current snap shot of a CE devices desktop Page 17
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); 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 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. 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. Declared in SMBUS.h & azfavr.h Use SMBUSAPI.lib. Requires SMBUSAPI.dll. Page 18
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); bdeviceaddress [in] The slave address on the SMBUS to send the command to bcommand [in] The SMBUS command identifier bdata [out] A pointer to an 8 bit value to hold the data returned 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. 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. Declared in SMBUS.h & azfavr.h Use SMBUSAPI.lib. Requires SMBUSAPI.dll. Page 19
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); bdeviceaddress [in] The slave address on the SMBUS to send the command to bcommand [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 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. 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. Declared in SMBUS.h & azfavr.h Use SMBUSAPI.lib. Requires SMBUSAPI.dll. Page 20
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); bdeviceaddress [in] The slave address on the SMBUS to send the command to bcommand [in] The SMBUS command identifier bdata [out] A pointer to an 16 bit value to hold the data returned 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. 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. Declared in SMBUS.h & azfavr.h Use SMBUSAPI.lib. Requires SMBUSAPI.dll. Page 21
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); bdeviceaddress [in] The slave address on the SMBUS to send the command to bcommand [in] The SMBUS command identifier windata [in] A word of data to pass in with the command. woutdata [out] A pointer to an 16 bit value to hold the data returned 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. 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. Declared in SMBUS.h & azfavr.h Use SMBUSAPI.lib. Requires SMBUSAPI.dll. Page 22
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); woffset bval [in] The location in EEPROM to write the value. Valid locations are 0-499 [in] That value to be written If the function succeeds, the return value is EEPROM_OK. If the function fails, the return value is a nonzero error code defined in eeprom.h. 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. Declared in EEPROM.h Use eeprom.lib. Requires eeprom.dll. Page 23
BCTReadEeprom Reads a byte of data from a location in EEPROM DWORD WINAPI BCTReadEeprom (WORD woffset, PBYTE pbval); woffset pbval [in] The location in EEPROM to read the value from. Valid locations are 0-499 [out] Pointer to an 8 bit value that will hold the returned EEPROM value If the function succeeds, the return value is EEPROM_OK. If the function fails, the return value is a nonzero error code defined in eeprom.h. 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. Declared in EEPROM.h Use eeprom.lib. Requires eeprom.dll. Page 24
BCTEraseEepromByte Erases a location in EEPROM. DWORD WINAPI BCTEraseEepromByte (WORD woffset); woffset [in] The location in EEPROM to erase. If the function succeeds, the return value is EEPROM_OK. If the function fails, the return value is a nonzero error code defined in eeprom.h. 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. Declared in EEPROM.h Use eeprom.lib. Requires eeprom.dll. Page 25
BCTEraseEeprom Erases the entire EEPROM. DWORD WINAPI BCTEraseEeprom (VOID); If the function succeeds, the return value is EEPROM_OK. If the function fails, the return value is a nonzero error code defined in eeprom.h. 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. Declared in EEPROM.h Use eeprom.lib. Requires eeprom.dll. Page 26
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); 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. If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 27
BCTSetGPIOPinDirection Sets the functions of GPIO bits to either input or output. DWORD WINAPI BCTSetGPIOPinDirection (BYTE bval); 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 If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 28
BCTSetGPIOPullups Sets the functions of GPIO bit pull-ups to either enabled for disabled. DWORD WINAPI BCTSetGPIOPullups (BYTE bval); 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. If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 29
BCTReadGPIOPort Reads the current state of the GPIO port DWORD WINAPI BCTReadGPIOPort (PBYTE pbval); pbval [out] A pointer to an 8 bit value that will hold the value of the GPIO port. If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 30
BCTWriteGPIOPort Writes a byte to the GPIO port DWORD WINAPI BCTWriteGPIOPort (BYTE bval); bval [in] The byte that gets written to the GPIO port. If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 31
BCTGetAnalogueInput Reads an ADC channel. DWORD WINAPI BCTGetAnalogueInput (WORD wadcsource, PWORD pwval); 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 If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 32
BCTSetGPIOBit Sets an individual bit to a value specified DWORD WINAPI BCTSetGPIOBit (BYTE bbitnumber, BOOL ivalue); 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 If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 33
BCTGetGPIOBit Gets the value of an individual bit DWORD WINAPI BCTGetGPIOBit (BYTE bbitnumber, PBOOL pivalue); 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 If the function succeeds, the return value is GPIO_OK. If the function fails, the return value is a nonzero error code defined in gpio.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in GPIO.h Use GPIO.lib. Requires GPIO.dll. Page 34
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); bresponse [in] What the response to a watchdog event should be. Valid options are: BCTWDG_RESET BCTWDG_INTERRUPT If the function succeeds, the return value is WATCHDOG_OK. If the function fails, the return value is a nonzero error code defined in watchdog.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in Watchdog.h & azfavr.h Use watchdog.lib. Requires watchdog.dll. Page 35
BCTEnableWatchdog Enables the APEX-ZF watchdog to timeout in the time specified DWORD WINAPI BCTEnableWatchDog (BYTE btimeout); btimeout [in] The duration in seconds before a timeout is triggered. Must be greater than 0. If the function succeeds, the return value is WATCHDOG_OK. If the function fails, the return value is a nonzero error code defined in watchdog.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in Watchdog.h & azfavr.h Use watchdog.lib. Requires watchdog.dll. Page 36
BCTDisableWatchdog Disables the APEX-ZF watch. DWORD WINAPI BCTDisableWatchDog (VOID); If the function succeeds, the return value is WATCHDOG_OK. If the function fails, the return value is a nonzero error code defined in watchdog.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in Watchdog.h & azfavr.h Use watchdog.lib. Requires watchdog.dll. Page 37
BCTRefreshWatchdog Resets the watchdog counter to the timeout value. DWORD WINAPI BCTRefreshWatchDog (VOID); If the function succeeds, the return value is WATCHDOG_OK. If the function fails, the return value is a nonzero error code defined in watchdog.h. 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 will be returned and is normal. The application should wait for an undefined period before retrying. Declared in Watchdog.h & azfavr.h Use watchdog.lib. Requires watchdog.dll. Page 38
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); ctemp [in] The maximum temperature in degrees Celsius allowable before a temperature interrupt occurs. Acceptable values are -40 to 125 If the function succeeds, the return value is SYSMON_OK. If the function fails, the return value is a nonzero error code defined in sysmon.h. See the APEX-ZF hardware manual for further details on the APEX-ZF system monitor. 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 SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS will be returned and is normal. The application should wait for an undefined period before retrying. Declared in sysmon.h Use sysmon.lib. Requires sysmon.dll. Page 39
BCTReadVoltage Reads a specified voltage from APEX-ZF DWORD WINAPI BCTReadVoltage (BYTE bvoltagesource, DOUBLE * pdvoltagereading); 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. If the function succeeds, the return value is SYSMON_OK. If the function fails, the return value is a nonzero error code defined in sysmon.h. See the APEX-ZF hardware manual for further details on the APEX-ZF system monitor. 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 SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS will be returned and is normal. The application should wait for an undefined period before retrying. Declared in sysmon.h Use sysmon.lib. Requires sysmon.dll. Page 40
BCTReadTemp Reads a specified voltage from APEX-ZF DWORD WINAPI BCTReadTemp (BYTE btempsource, char * pctempreading); 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. If the function succeeds, the return value is SYSMON_OK. If the function fails, the return value is a nonzero error code defined in sysmon.h. See the APEX-ZF hardware manual for further details on the APEX-ZF system monitor. 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 SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS will be returned and is normal. The application should wait for an undefined period before retrying. Declared in sysmon.h Use sysmon.lib. Requires sysmon.dll. Page 41
BCTPowerOff Powers off the CPU core and 3.3 voltage rails. DWORD WINAPI BCTPowerOff (VOID); If the function succeeds, the return value is SYSMON_OK. If the function fails, the return value is a nonzero error code defined in sysmon.h. Using this function will lead to the APEZ-ZF unit being powered off and require a manual reset to enable the voltage lines. See the APEX-ZF hardware manual for further details on the APEX-ZF system monitor. 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 SYSMON_SMBUS_DRIVER_LOCKED_BY_OTHER_PROCESS will be returned and is normal. The application should wait for an undefined period before retrying. Declared in sysmon.h Use sysmon.lib. Requires sysmon.dll. Page 42
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); bxsize bysize [in] The number of columns in the display [in] The number of rows in the display If the function succeeds, the return value is LCD_OK. If the function fails, the return value is a nonzero error code defined in lcd.h. 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. Declared in LCD.h Use LCDAPI.lib. Requires LCDAPI.dll. Page 43
BCTLCDWriteCharacter Writes a single character to the LCD display DWORD WINAPI BCTLCDWriteCharacter (BYTE bxpos, BYTE bypos, BYTE bchar); bxpos bypos bchar [in] The column in the display to write the character [in] The row in the display to write the character [in] The character to write If the function succeeds, the return value is LCD_OK. If the function fails, the return value is a nonzero error code defined in lcd.h. See the APEX-ZF hardware manual for further details on the APEX-ZF character LCD support. Declared in LCD.h Use LCDAPI.lib. Requires LCDAPI.dll. Page 44
BCTLCDClearDisplay Clears the LCD display DWORD WINAPI BCTLCDClearDisplay (VOID); If the function succeeds, the return value is LCD_OK. If the function fails, the return value is a nonzero error code defined in lcd.h. See the APEX-ZF hardware manual for further details on the APEX-ZF character LCD support. Declared in LCD.h Use LCDAPI.lib. Requires LCDAPI.dll. BCTLCDClose Closes the handle to the LCD driver DWORD WINAPI BCTLCDClose (VOID); If the function succeeds, the return value is LCD_OK. If the function fails, the return value is a nonzero error code defined in lcd.h. See the APEX-ZF hardware manual for further details on the APEX-ZF character LCD support. Declared in LCD.h Use LCDAPI.lib. Requires LCDAPI.dll. Page 45
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 interrupts to occur. Page 46
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. Page 47
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"))); // Set the thread priority arbitrarily 5 Page 48
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 if(!g_frun ) return 0; Page 49
// 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 )); return 0; //Tell the driver that we have finished processing the interrupt SetEvent(g_hevInterruptdone); Page 50