Pluto 8 Software

Software Documentation Guide

Software Overview

The Pluto 8 controller board software documentation is supplied in Compiled Help format. Documentation topics and pages can be accessed in the following ways:

  • Click on the Contents tab at the top of the left hand window and expand each of the documentation books to view the topic pages. Click on a topic page to display the contents in the right hand window.
  • Click on the Index tab at the top of the left hand window to search through the indexed topics in the compiled help file. Type the topic that you are looking for in the edit box at the top of the left hand window and the relevant topic will be highlighted in the index list. Click on the highlighted item to view the associated page.
  • Click on the Search tab at the top of the left hand window to perform a key word search of the whole of the software user guide. Type the key word that you wish to search for in the edit box at the top of the window and click the List Topics button. All of the pages that contain the key word that you entered will be listed below. Each of the pages found will have the number of times that the key word appears in the page. To view a particular page listed click on the page title and click the Display button.
  • Click on the Favorites tab at the top of the left hand window to store your on set of links to particular help pages. To add a page to your lists of favorites first find the page and display it in the left window using one of the three methods listed above. Click the Add button at the bottom of the left window to add the topic to your list of favorites. To view a page in your favorites list click on the topic name in the list. To remove a topic click on the topic name and click the Remove button.

Within the compiled help documentation there are links to relevant third party documentation, This documentation is presented in Adobe®.pdf format. To view the documentation you must have Adobe® Acrobat Reader installed. To install Acrobat Reader click on the button below:

Get Acrobat Reader

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.
Document No: 80-20013, Issue 1 Release Date: 02.07.08 Email: support@heber.co.uk www.heber.co.uk


Pluto 8 Software - Getting Started

Getting Started

This page provides basic information to get you started with the Pluto 8 development environment and software.

Building Software

To build a Pluto 8 project using the GNU compiler do the following:

  • On the PC where the Pluto 8 Development Kit software is installed open a Command Prompt (DOS) Window (Start - Accessories - Command Prompt).
  • Change directory into the Pluto 8 demo project directory (C:\heber-pluto8\projects\demo)
  • Type make clean to run the makefile and delete all of the object files the demo project.
    Type make to run the makefile to build the demo project.
  • For futher information on the makefile refer to the GNU Compiler page.

Running Your Code on Pluto 8

Built projects in the project directory can be loaded on to the Pluto 8 control board in the following ways:

From CompactFlash

  • The Pluto 8 board has a pre-programmed boot loader that runs when the board is powered up. The boot loader sets up the CPU registers and loads a project called game.s19 from the Compact Flash card.
  • Ensure that the output file from the project that you have built is called game.s19.
  • Copy the .s19 file to the root directory of the Compact Flash card using the Compact Flash reader/writer.
  • Fit the the Compact Flash card into the Compact Flash slot (P3) on the Pluto 8 board.
  • Power the board up and the project will be loaded into SDRAM and execute.

Using the P&E® ICD Debugger

  • Ensure that the ICD software is installed and the debug module attached to the BDM connector (P7) on the Pluto 8 board and to a USB port on the host PC.
  • Power up the Pluto 8 board and launch the P&E® ICDCFZ In Circuit Debugger software.
  • Click the Reset button on the software tool bar to reset the ColdFire® on the Pluto 8.
  • Click the Go button on the software tool bar to execute the boot loader code. This code will run the Pluto 8 entry code and set up the chip select registers on the ColdFire®.
  • After a few seconds click the Stop button on the software tool bar to stop the boot flash code executing.
    Note: Do not reset the CPU at this point because the chip select settings set by the boot flash code will be cleared.
  • Click the Load button on the software tool bar, select the .s19 file that you wish to load (e.g. game.s19) and click Open.
    In the ICD software Status Window a Loading.... message will appear. When the .s19 file has loaded a loaded message will appear in the Status Window.
  • In the edit box at the bottom of the Status Window type dump.l 60000004 60000004 1 and press Enter. This will display the address that the program counter needs to be set to in order to run the code that you have downloaded. In the example given the program counter value is 6000AA10.
  • To set the program counter to the new value, type pc < new pc value > into the Status Window edit box and press Enter. In the example given the program counter is reset to 6000AA10.
  • To reinitialise the processor to a supervisor mode, type SR 2700 into the Status Window edit box and press enter.
  • In the Code Disassembly Window MOVE.W #2700,SR should be displayed which is the first instruction of the Pluto 8 entry code.
  • Click the Go button on the software tool bar to run the code that you have downloaded.

P&E® ICD Tool Bar

P&E® ICD Status Window

P&E® ICD Status Window Displaying Game Program Counter

P&E® ICD Memory Window Program Counter Reset

P&E® ICD Status Window Supervisor Mode

P&E® ICD Code Disassembly Window

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Software Updates

Software Updates

The software that is supplied with the Pluto 8 Development Kit is the current version at the time that the product was released. Periodically the Heber Pluto 8 software will be revised. The latest software can be downloaded from the Heber website: www.heber.co.uk

It is recommended that you check the website and download the latest version of the software drivers before starting your game development. Release Notes are also provided on the website giving information regarding changes made for each version of the software.

If you experience problems with the software during game development please check the website to ensure that you are using the latest versions of the software.

For further information, or to report any problems with the Pluto 8 software, email Heber Technical Support: support@heber.co.uk

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Overview

Pluto 8 Software

Suppiled Software

The Pluto 8 controller board is supplied with a suite of software to allow developers to create gaming applications.

Software Libraries

Structured software libraries with an Application Programming Interface (API) in the C programming language provide the following:

  • Access to the Pluto 8 hardware
  • High level peripheral device controllers
  • Example drivers that can be used as a template for writing custom drivers
  • Demonstration project software that can be used as a template for gaming application development

Sample Projects

The source code for example projects is supplied to provide a starting point for game development. The following projects are supplied:

  • Standard demonstration project demonstrating use of the Pluto 8 software API
  • Dual Video project using the Advanced Video 1 Calypso 32 video card
  • Touchscreen demonstration project
  • Boot loader project to demonstrate loading game code from a Compact Flash card

Tools and Utilities

Where particular data formats are required ensure optimum performance from the Pluto 8 platform file pre-processing tools and utilities are provided. The tools and utilities can be run from the command line in a MS-DOS window.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Sample Projects

Pluto 8 Sample Projects

Sample projects are provided as a starting point for developers writing gaming applications. Files within the module allow the configuration and installation of device drivers provided by the library modules, and provide a basic framework for game development. The source code is supplied for the projects.

Project Examples

The following example projects are provided that can be used as a template/starting point for game development:

Example Project | Description
Standard Demonstration Project | Standard project demonstrating use of the Pluto 8 software API.
Video Project | Dual screen video demonstration using video reels and animations

Module Components

The example projects are built using a standard set of component files. For a description of the main source files in the projects click here.

See Also

  • GNU Compiler
  • Software Conventions
  • Software Architecture
  • Source File Types
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Demonstration Program

Pluto 8 Demonstration Program

Demonstration Program Documentation

The executable file, game.s19, created from the demonstration program is on the Compact Flash Card supplied as part of the Pluto 8 Development Kit.

Component | Description
Demonstration Program Overview | An overview of the demonstration project

See Also

  • Remote PC Physical Setup
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Demonstration Program

Demonstration Program Overview

The standard demonstration program supplied with the Pluto 8 Development Kit allows the user to test the hardware functionality using the Heber software libraries. The program demonstrates the API functions that would typically be used in a gaming application.

Demonstration Program Operation

The demonstration program is menu driven, and allows the user to test each part of the Pluto 8 functionality in isolation. The demonstration program requires the user to run a terminal emulation program on a host PC, for example Hyperterminal. For instructions on how to setup a terminal to display the demonstration program menus click here.

To navigate throught the menus of the demonstration program type the number next to the menu option followed by ENTER.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Demonstration Program

Pluto 8 Video Demonstration Program

Video Demonstration Program Documentation

The Pluto 8 Development Kit is shipped with an example dual video demonstration program. The source code for the project can be found at {INSTALL_DIR}\projects\videodemo, for example C:\heber-pluto8\projects\videodemo. To run the project copy the executable game.s19 and the image file folder gifimages ({INSTALL_DIR}\projects\videodemo\cflash_image\) to the compact flash card.

Component | Description
Video Demonstration Program Overview | An overview of the video demonstration project

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Demonstration Program

Video Demonstration Program Overview

The video demonstration program supplied with the Pluto 8 Development Kit demonstrates the use of the video drivers supplied with the Pluto 8 development kit. The demonstration is designed to run using 2 screens connected to connectors VGA1 (P16) and VGA2 (P15).

The demonstration software uses the Pluto 8 Video Reel Driver and the GIF Image File Loader giving examples of spinning video reels with animations.

Video Demonstration Program Operation

The video demonstration program is free running. Some infromation is output to the BACTA serial port (P11). To run view this data run a terminal emulation program on a host PC, for example Hyperterminal. For instructions on how to setup a terminal to display the video demonstration program output click here.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Project Common Files

Pluto 8 Project Common Files

The following files are common to all Pluto 8 projects.

Common Files

File Name | Description
config.c | Project specific device configuration settings
devices.c | Project specific device driver management
fpga.h | FPGA register map
game.c | Entry point to the game application
demo.c | File where the game/demonstration program is located
idram.c | File to hold variables whose values must be preserved and stored in non-volatile memory.
sysram.c | File to hold variables declarations that are then allocated to non-volatile memory.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Project Configuration File

Project Configuration File

The file config.c in the project directory allows the game developer to provide configuration options for some of the Pluto 8 software drivers. The configuration options are applied to the drivers on installation. In the example projects default configuration options are provided for the configurable drivers.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Device List File

Project Device List File

The file devices.c allows the game developer to specify which device drivers are loaded for a particular gaming application. The device list is read on system startup by the Device Manager and all listed device drivers are loaded.

For further information on device list entry definition refer to the Defining a Device List page.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Project FPGA file

FPGA Register Memory Mappings

This file provides memory mappings for accessible registers in the Pluto 8 FPGA.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Project Game File

game.c

This module contains function ‘Game()’. After system initialisation this function calls DemoFnc() and enters an infinite loop until the user ends the program.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Project Demo File

demo.c

This file provides a template for the development of gaming applications. In the supplied software the file demo.c contains a function DemoFnc() which is called from the function Game(). This functions contains the source code for the demonstration program.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Project IDRAM File

idram.c

This section of memory is cleared on start-up only when a change of program identity is detected. It is intended to hold variables whose values must be preserved through a software revision update. It is the responsibility of the game programmer to ensure that each game has a unique identity. The 32bit constant integer ‘MachineId’ holds the value, which identifies the software.

Variables may be placed in this section only on a file by file basis by modifying the linker script. The demonstration program contains a module called ‘idram.c’. Any uninitialised variables defined in this file are located in the Identity RAM section of memory.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Project SYSRAM File

sysram.c

Variables declared in this file will be stored in non-volatile memory. Values assigned to the variables will be retained during system power down.

This section of memory is cleared on start-up when a change of identity or change of checksum is detected. This section is intended for variables whose values are not initialised on start-up and retain their values through a power down. Variables may be placed in this section only on a file by file basis by modifying the linker script.

The demonstration program contains a module called ‘sysram.c’. Any uninitialised variables defined in this file are located in the System RAM section of memory.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Remote PC Setup

Remote PC Setup

Physical Connection

To access the demonstration program menu the Pluto 8 control board must be connected to a remote PC via a serial cable. To do this attach one of the ribbon cables with a 25-way D-Type connector supplied in the Development Kit to either connector DATAPORT (P11) on the Pluto 8 board, or if the Pluto 8 is mounted on the Evaluation board, the DATAPORT connector.

The D-Type connector at the other end of the ribbon cable should be fitted with the 25 to 9-Way D-Type converter supplied in the Pluto 8 Development Kit, and then connected to a serial port on the remote PC.

PC Software Setup

Launch HyperTerminal on the host PC (Start - Programs - Accessories - Communications - HyperTerminal).

Enter the name for your connection in the Name edit box and click OK.

Select the serial port that you have connected the serial ribbon cable to on your PC in the Connect Using box and click OK.

Set the following serial port configuration:

  • Bits per second: 9600
  • Ddata bits: 8
  • Parity: None
  • Stop bits: 1
  • Flow control: None

Click OK.

Power up the Pluto 8 board with the Compact Flash card containing the demonstration software fitted and a screen similar to the one above should be displayed.
To run tests enter the corresponding menu item number followed by ENTER.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Libraries

Software Libraries

The Pluto 8 control board is supplied with software in compiled library format that can be read by the GNU linker. The software is organised in discreet modules, each of which provides a specific type of functionality to the game developer. One compiled library is supplied for each software module.

In addition to the compiled libraries, the source code is supplied for two of the software modules to provide a template for developers to create specialised drivers and gaming applications.

Library | Description
Hardware Library | Provides a software interface to the Pluto 8 hardware with low level device drivers, board initialisation and process management software in compiled library format.
Standard Peripherals Library | Provides higher level drivers for many common peripheral devices which access the hardware through the Hardware Module. The software is supplied in compiled library format.
Custom Peripherals Library | Provides examples of higher level peripheral drivers that can be used as a starting point for game developers to create specialised drivers. The source code is supplied for this module.
Standard Interface Library | Provides higher level drivers that are not hardware specific and can address one or more hardware devices. Hardware is accessed through the Hardware Module, or indirectly through the Peripherals Modules. The software is supplied in compiled library format.
Custom Interface Library | Provides examples of higher level interface drivers that can be used as a starting point for game developers to create specialised drivers. The source code is supplied for this module.
Security Library | Provides all of the security related Pluto 8 drivers. The software is supplied in compiled library format.

See Also

  • GNU Compiler
  • Software Conventions
  • Software Architecture
  • File Types
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Hardware Library

Hardware Library

The hardware library contains the following components:

  • System initialisation code
  • Process management code
  • Low level drivers that allow direct access to hardware on the Pluto 8 control board.

The software Application Programming Interface (API) in the hardware module provides a software interface to the Pluto 8 hardware.

Hardware Library Software Components

Component | Description
ATA Driver | The ATA Driver provides the low level functions to access an ATA hard disk or compact flash card.
Dual Video Driver | The Dual Video Driver provides a software interface to the on-board video and Calypso32 video expansion card.
Audio Driver | The Audio Driver provides functions to play audio samples.
Multiplexed Inputs Driver | The Multiplexed Inputs Driver allows the control of Pluto 8 system inputs.
Outputs Driver | The Outputs Driver allows the control of the Pluto 8 system outputs.
Serial Communications Driver | The Serial Communications Driver allows access to the services of multiple serial devices available on the Pluto 8 control board.
PIC Driver | The PIC Driver provides functions to access data on the PIC16 Security Device.
I2C Driver | The I2C Driver provides an interface to the I²C bus on the Pluto 8 control board.
Device Manager | The Device Manager provides the functionality for manipulating device drivers.
Entry Module | The Entry module provides the low-level initialisation of the Pluto 8 hardware.
Main Function | The main( ) function continues the Pluto 8 system configuration and initialisation.
Interrupt Module | The Interrupt Module provides functionality to allow the user to install functions that will run triggered by system interrupts.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

The Pluto 8 ATA driver povides low level access to ATA/IDE devices (for example Compact Flash cards) running in true IDE mode, connected to the Pluto 8 board.
This driver is used by the FAT32 interface module to access FAT32 filesystems on a Compact Flash card fitted to connector P3.

API Functions

The following API functions are provided by this module:

Function | Description
ReadDriveID | Access the ATA device to retrieve the drive information.
GetDriveModel | Return a pointer to the drive model/description text string retrieved from the ATA device.
GetDriveRev | Return a pointer to the drive revision text string retrieved from the ATA device.
GetDriveSerialno | Return a pointer to the drive serial number text string retrieved from the ATA device.
GetDriveCyls | Return the number of cyclinders in the drive geometry of the ATA device.
GetDriveHeads | Return the number of heads in the drive geometry of the ATA device.
GetDriveSectors | Return the number of sectors in the drive geometry of the ATA device.
GetPIOMode | Return the maximum PIO mode supported by the ATA device (in the range 1-4).
SetPIOMode | Set the FPGA ATA interface and the ATA device to operate at the chosen PIO mode (in the range 1-4).
DriveSpinup | Spin up the platter to operating speed if the ATA device is mechanical (E.G. A hard disk or microdrive).
DriveSpindown | Spin down the platter to a standby state if the ATA device is mechanical (E.G. A hard disk or microdrive).
ReadSectors | Read the specified number of sectors from the ATA device into a buffer.
WriteSector | Write the a sector from a buffer to the specified logical block address in the ATA device.

See Also

  • ATA configuration data
  • ATA function return codes
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

ReadDriveID

BYTE ReadDriveID(const DEVICE* atadevice)

Description

This function sends an "Identify Device" command to the ATA device, then reads back 256 words of device information which is then held in a substructure within the atadevice stucture, to be retrieved by other API functions.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns ATA_OK if the operation was performed succesfully
Returns ATA_BSY_TIMEOUT if the operation timed out while waiting for the BSY bit in the status register of the ATA device to clear
Returns ATA_DRQ_TIMEOUT if the operation timed out while waiting for the DRQ bit in the status register of the ATA device to become set

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetDriveModel

UBYTE *GetDriveModel(const DEVICE* atadevice)

Description

This function returns a pointer to the drive model/description text string held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a pointer to a UBYTE which may be treated as a string containing the drive model name of the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetDriveRev

UBYTE *GetDriveRev(const DEVICE* atadevice)

Description

This function returns a pointer to the drive revision text string held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a pointer to a UBYTE which may be treated as a string containing the drive revision of the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetDriveSerialno

UBYTE *GetDriveSerialno(const DEVICE* atadevice)

Description

This function returns a pointer to the serial number text string held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a pointer to a UBYTE which may be treated as a string containing the serial number of the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetDriveCyls

UWORD GetDriveCyls(const DEVICE* atadevice)

Description

This function returns the number of cylinders in the drive geometry as held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a UWORD containing the number of cylinders in the drive geometry of the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetDriveHeads

UWORD GetDriveHeads(const DEVICE* atadevice)

Description

This function returns the number of heads in the drive geometry as held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a UWORD containing the number of heads in the drive geometry of the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetDriveSectors

UWORD GetDriveSectors(const DEVICE* atadevice)

Description

This function returns the number of sectors in the drive geometry as held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a UWORD containing the number of sectors in the drive geometry of the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

GetPIOMode

UBYTE GetPIOMode(const DEVICE* atadevice)

Description

This function returns the maximum PIO mode that the ATA device is capable of operating at as held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

The PIO mode dictates the timing between the control signals used by the ATA interface in the FPGA to access the ATA device. At higher modes, the time between the signal changes is shortened, allowing the card to operate faster. The FPGA supports PIO modes 0-4, however certain ATA devices such as older CompactFlash cards may not support up to mode 4.
See Achieving maximum ATA performance for information on how to make the most of the PIO modes available on Pluto 8.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns a UBYTE containing the maximum PIO mode that the ATA device is capable of within the range 0-4.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

SetPIOMode

BYTE SetPIOMode(const DEVICE* atadevice, UBYTE mode)

Description

This function sets the PIO mode the ATA device and FPGA are to operate in. The chosen mode is checked against the maximum possible mode held in the info structure within the atadevice structure. The info structure is populated by the ReadDriveID function, so it is important to call ReadDriveID on the same atadevice structure first to ensure the drive information is valid.

The PIO mode dictates the timing between the control signals used by the ATA interface in the FPGA to access the ATA device. At higher modes, the time between the signal changes is shortened, allowing the card to operate faster. The FPGA supports PIO modes 0-4, however certain ATA devices such as older CompactFlash cards may not support up to mode 4.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)
mode | The PIO mode which the ATA device and FPGA are set to, should be within the range supported by the ATA device, up to the range 0-4.

Return Value

Returns ATA_OK if the operation was performed succesfully
Returns ATA_PIO_INVALID if the mode argument is above the maximum supported by the ATA device
Returns ATA_BSY_TIMEOUT if the operation timed out while waiting for the BSY bit in the status register of the ATA device to clear

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

DriveSpinup

BYTE DriveSpinup(const DEVICE* atadevice)

Description

This function spins up the disk platter to operating speed if the ATA device is mechanical (E.G. A hard disk or microdrive).

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns ATA_OK if the operation was performed succesfully
Returns ATA_BSY_TIMEOUT if the operation timed out while waiting for the BSY bit in the status register of the ATA device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

DriveSpindown

BYTE DriveSpindown(const DEVICE* atadevice)

Description

This function spins down the disk platter to a standby state if the ATA device is mechanical (E.G. A hard disk or microdrive).

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)

Return Value

Returns ATA_OK if the operation was performed succesfully
Returns ATA_BSY_TIMEOUT if the operation timed out while waiting for the BSY bit in the status register of the ATA device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

ReadSectors

BYTE ReadSectors(const DEVICE* atadevice, ULONG lba, UWORD *buffer, UBYTE count)

Description

This function reads the specified number of sectors from the ATA device into a buffer. The data is read in a raw fashion, the main use of this function is by the FAT32 interface driver, which then interprets the data as valid files and directories to allow easier access.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)
lba | The logical block address on the disk at which the reading begins
buffer | The address of the memory into which the sector data is read
count | The number of sectors to read from the disk

Return Value

Returns ATA_OK if the operation was performed succesfully
Returns ATA_BSY_TIMEOUT if the operation timed out while waiting for the BSY bit in the status register of the ATA device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver

WriteSector

BYTE WriteSector(const DEVICE* atadevice, ULONG lba, UWORD *buffer)

Description

This function writes a sector from a buffer to the ATA device. The data is written in a raw fashion. The main use of this function is by the FAT32 interface driver which composes data into a valid file system structure before placing it onto disk.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device)
lba | The logical block address on the disk at which the sector is written
buffer | The address of the memory containing the data to be written to the disk

Return Value

Returns ATA_OK if the operation was performed succesfully
Returns ATA_BSY_TIMEOUT if the operation timed out while waiting for the BSY bit in the status register of the ATA device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA driver configuration data and FAT32 filesystem stucture

The ATA driver is configurable at game level via the use of a configuration structure in config.c. The configuration structure contains the following fields:

typedef struct
{
    BYTE driveselect;
    LONG timeoutval;
    FAT32FILESYSTEM *filesystem;
} ATACFG;

These fields have the following meaning:

Configuration data field | Description
driveselect | This value determines whether the ATA device structure to which the configuration structure is allocated controls the master or slave on the ATA channel. Pluto 8 supports a single ATA device which should be configured as ATA_MASTER.
timeoutval | This is the number of times the DRQ and BSY bits in the status register of the ATA devices are polled before the ATA API functions return a timeout error.
filesystem | This is a pointer to a FAT32FILESYSTEM structure. The filesystem structure must be instantiated in the game code.

Code Example

The following is an example of a configuration structure for a master ATA device together with a FAT32 filesystem structure:

const FAT32FILESYSTEM ata0fs;

const ATACFG ATA0Cfg[]=
{
    {ATA_MASTER, 90000000, (void*)&ata0fs},
    {0}
};
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver Defined Return Codes

ATA Defined Return Codes

Label | Value | Meaning
ATA_OK | 0 | The requested operation was performed successfully.
ATA_DRQ_TIMEOUT | -1 | The operation timed out while waiting for the DRQ bit in the status register of the ATA device to clear
ATA_BSY_TIMEOUT | -2 | The operation timed out while waiting for the BSY bit in the status register of the ATA device to clear
ATA_PIO_INVALID | -3 | The PIO mode argument is above the maximum supported by the ATA device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Dual Video Driver

Dual Video Driver

API Functions

The following API functions are provided by this module:

Initialisation Functions

Function | Description
CalypsoInitDisplayMode | Set video display mode
CalypsoVideoOn | Enable video output
CalypsoVideoOff | Disable video output

Layer Functions

Function | Description
CalypsoInitLayer | Initialise Display Layer parameters
CalypsoEnableLayer | Enable Display Layer(s)
CalypsoDisableLayer | Disable Display Layer(s)
CalypsoScrollLayerX | Scroll Display Layer horizontally
CalypsoScrollLayerY | Scroll Display Layer vertically
CalypsoClearLayer | Clear Display Layer
CalypsoFillLayer | Fill Display Layer with specified colour
CalypsoSetWindowLayer | Set Window Layer parameters
CalypsoScreenPartitionX | Set screen x position of partition between left layer and right layer
CalypsoLayerReadSkipMap | Initialise a readskip map
CalypsoLayerReadSkip | Display Layer "readskip"
CalypsoGetColorMode | Get Display Layer color mode

Double Buffering, Frame Advance Functions

Function | Description
CalypsoSetFrameRate | Set double buffer frame rate
CalypsoSetDoubleBufferFrame | Set the current displayed double-buffer frame
CalypsoGetDoubleBufferFrame | Return currently displayed double-buffer frame
CalypsoSetFrameNumber | Initialise the Frame Number Count
CalypsoGetFrameNumber | Get the current frame number
CalypsoFrameAdvance | Manually advance frame
CalypsoWaitNframes | Wait for specified number of display frames

Alpha Blending Functions

Function | Description
CalypsoAlphaBlend | Enable/disable alpha blending
CalypsoSetBlendRatio | Set Alpha Blending blend ratio

Image Loading Functions

Function | Description
CalypsoLoadImage | Load image from system to video memory
CalypsoLoadImageLayer | Load image from system to display layer
CalypsoLoadSprite | Load video image from system to video memory

Blitting Functions

Function | Description
CalypsoPutSprite | Block Copy from undisplayed video memory to screen display layer
CalypsoCopySprite | As CalypsoPutSprite() - source pitch specified
CalypsoSaveSprite | Copy block from screen layer to undisplayed video memory
CalypsoClearSprite | Clear display block to BLACK
CalypsoFillSprite | Fill display block with specified color
CalypsoSetBltTransparentColor | Set BitBlt transparent colour
CalypsoGetBltTransparentColor | Returns current BitBlt transparent colour

Text Functions

Function | Description
CalypsoSetAsciiFont | Set the current active ASCII character font
CalypsoSetTextColor | Set text foreground and background colour
CalypsoSetTextPosition | Set current text writing position for specified display layer.
CalypsoGetTextPositionX | Get x coordinate of the current text writing position
CalypsoGetTextPositionY | Get Y coordinate of the current text writing position
CalypsoPutChar | Write ASCII Character to Display Layer
CalypsoPutStr | Write text string to video display layer

Draw Engine Status Functions

Function | Description
CalypsoDrawBusy | Tests if Carmine drawing engine is busy

See Also

  • Video Driver Defined Values
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video InitDisplay

Video Driver

CalypsoInitDisplayMode

void CalypsoInitDisplayMode(const DEVICE* dev, const DISPLAY_INIT_TABLE *reg_table)

Description

Set video display mode

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
reg_table | Pointer to initialisation table

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video On

Video Driver

CalypsoVideoOn

void CalypsoVideoOn(const DEVICE* dev)

Description

Enable video output

Parameters

Parameter | Description
dev | Pointer to Destination Video Device

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video Off

Video Driver

CalypsoVideoOff

void CalypsoVideoOff(const DEVICE* dev)

Description

Disable video output

Parameters

Parameter | Description
dev | Pointer to Destination Video Device

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video InitLayer

Video Driver

CalypsoInitLayer

LONG CalypsoInitLayer(const DEVICE* dev, LONG layer_select, BYTE color_mode, BYTE buffer_mode, WORD transparent_color, WORD width_pixels, WORD height, LONG start_address)

Description

Initialise Display Layer parameters

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Display Layer
color_mode | Display color mode 16/24 bits per pixel
buffer_mode | SINGLEBUFFER | DOUBLEBUFFER
transparent_color | Layer transparent color (16/24 bit)
width_pixels | Layer width in pixels - must be multiple of 64
height | Layer height in lines
start_address | Start video memory address (offset)

Return Value

Next free video memory (offset) after memory assigned to layer

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video EnableLayer

Video Driver

CalypsoEnableLayer

void CalypsoEnableLayer(const DEVICE* dev, UBYTE select)

Description

Enable Display Layer(s)

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
select | Layer(s) to be enabled

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video DisableLayer

Video Driver

CalypsoDisableLayer

void CalypsoDisableLayer(const DEVICE* dev, UBYTE select)

Description

Disable Display Layer(s)

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
select | Layer(s) to be disabled

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ScrollLayerX

Video Driver

CalypsoScrollLayerX

void CalypsoScrollLayerX(const DEVICE* dev, LONG layer_select, ULONG offset)

Description

Scroll Display Layer horizontally

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
offset | Offset in pixels from screen origin to display start

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ScrollLayerY

Video Driver

CalypsoScrollLayerY

void CalypsoScrollLayerY(const DEVICE* dev, LONG layer_select, ULONG offset)

Description

Scroll Display Layer vertically

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
offset | Offset in lines from screen origin to display start

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ClearLayer

Video Driver

CalypsoClearLayer

WORD CalypsoClearLayer(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame)

Description

Clear Display Layer.

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
doublebuffer_frame | Destination Double Buffer Frame

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video FillLayer

Video Driver

CalypsoFillLayer

WORD CalypsoFillLayer(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG color, LONG mode)

Description

Fill Display Layer with specified colour.

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
doublebuffer_frame | Destination Double Buffer Frame
color | 16/24 bit colour value.
mode | writing mode BLT_CLEAR| BLT_COPY| BLT_AND | BLT_OR

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetWindowLayer

Video Driver

CalypsoSetWindowLayer

void CalypsoSetWindowLayer(const DEVICE* dev, WORD x_position, WORD y_position, WORD width, WORD height)

Description

Set Window Layer parameters

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
x_position | x position in pixels from screen left
y_position | y position in lines from screen top
width | window width in pixels
height | window height in lines

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ScreenPartitionX

Video Driver

CalypsoScreenPartitionX

void CalypsoScreenPartitionX(const DEVICE* dev, WORD partition_xpos)

Description

Set screen x position of partition between left layer and right layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
partition_xpos | partition x position in pixels

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ReadSkipMap

Video Driver

CalypsoLayerReadSkipMap

void CalypsoLayerReadSkipMap(READSKIP_MAP *map, LONG x0, LONG x1, LONG y0, LONG y1, LONG mask)

Description

Initialise a readskip map, defining layer areas to be skipped Layer areas "skipped" are not accessed to reduce memory bandwidth when using Carmine read skip capability

Parameters

Parameter | Description
map | pointer to "map" structure
x0 | xo partition in pixels
x1 | x1 partition in pixels
y0 | y0 partition in lines
y1 | y1 partition in lines
mask | OR'd list of skipped areas: A0|A1|A2|A3|A4|A5|A6|A7

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ReadSkip

Video Driver

CalypsoLayerReadSkip

void CalypsoLayerReadSkip(const DEVICE* dev, LONG layer_select, READSKIP_MAP *map, LONG enable)

Description

Display Layer "readskip" using map defined with CalypsoLayerReadSkipMap().

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Display Layer affected
map | Readskip map defined by CalypsoLayerReadSkipMap()
enable | Enable/disable readskipping for this layer

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video GetColorMode

Video Driver

CalypsoGetColorMode

BYTE CalypsoGetColorMode(const DEVICE* dev, LONG layer_select)

Description

Get current color mode for specified Display Layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Display Layer

Return Value

COLOR_16 | COLOR_24

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video FrameRate

Video Driver

CalypsoSetFrameRate

void CalypsoSetFrameRate(const DEVICE* dev, BYTE rate)

Description

Set double buffer frame rate. If frame_rate = FRAME_0HZ, frame advanced manually

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
rate | Double buffer frame rate in Hz

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetDoubleBufferFrame

Video Driver

CalypsoSetDoubleBufferFrame

void CalypsoSetDoubleBufferFrame(const DEVICE* dev, BYTE frame)

Description

Set the current displayed double-buffer frame. The double buffer frame is updated during the next vertical sync period.

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
frame | 0=Double Buffer Frame 0, 1=Double Buffer Frame 1

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video GetDoubleBufferFrame

Video Driver

CalypsoGetDoubleBufferFrame

BYTE CalypsoGetDoubleBufferFrame(const DEVICE* dev)

Description

Return currently displayed double-buffer frame.

Parameters

Parameter | Description
dev | Pointer to Destination Video Device

Return Value

Double buffer frame (0 or 1)

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetFrameNumber

Video Driver

CalypsoSetFrameNumber

void CalypsoSetFrameNumber(const DEVICE* dev, WORD n)

Description

Initialise the Frame Number Count. The Frame Number Count is incremented at the current frame rate

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
n | Frame Number

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


PLuto 8 Video GetFrameNumber

Video Driver

CalypsoGetFrameNumber

WORD CalypsoGetFrameNumber(const DEVICE* dev)

Description

Get the current frame number

Parameters

Parameter | Description
dev | Pointer to Destination Video Device

Return Value

Frame Number

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video FrameAdvance

Video Driver

CalypsoFrameAdvance

void CalypsoFrameAdvance(const DEVICE* dev)

Description

Manually advance frame when frame rate = FRAME_0HZ

Parameters

Parameter | Description
dev | Pointer to Destination Video Device

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video WaitNFrames

Video Driver

CalypsoWaitNframes

void CalypsoWaitNframes(const DEVICE* dev, ULONG nframes)

Description

Wait for specified number of display frames. Crude in-line delay (blocking function) Length of delay depends on current frame rate.

Accuracy +1 -0 frames

WARNING: will wait forever if framehz==0 (manual frame update)

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
nframes | Number of frames

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Video AlphaBlend

Video Driver

CalypsoAlphaBlend

void CalypsoAlphaBlend(const DEVICE* dev, BYTE enable)

Description

Enable/disable alpha blending

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
enable | 1=enable, 0=disable alpha blending

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetBlendRatio

Video Driver

CalypsoSetBlendRatio

void CalypsoSetBlendRatio(const DEVICE* dev, UBYTE blend_ratio, BYTE select)

Description

Alpha Blending: Set blend ratio between console layer and other layers,

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
blend_ratio | 0 <= blend_ratio < 256
select | Not used. For compatibility.

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video LoadImage

Video Driver

CalypsoLoadImage

LONG CalypsoLoadImage(const DEVICE* dev, LONG video_addr, const CALYPSOIMAGE* image)

Description

Load image from system to video memory

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
video_addr | Destination video memory address (offset)
image | Pointer to image to be loaded

Return Value

Returns next free video memory address (offset)

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


PLuto 8 Video LoadImageLayer

Video Driver

CalypsoLoadImageLayer

LONG CalypsoLoadImageLayer(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, const CALYPSOIMAGE* image)

Description

Load image from system to display layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination layer
doublebuffer_frame | Doublebuffer frame - ignored, always loads to frame 0
image | Pointer to image to be loaded

Return Value

Next free video memory address (offset)

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video LoadSprite

Video Driver

CalypsoLoadSprite

LONG CalypsoLoadSprite(const DEVICE* dev, LONG video_addr, const CALYPSOIMAGE* image)

Description

Load video image from system to video memory.Image stored in block of width rounded up to next multple of 8 bytes

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
video_addr | Display memory address (offset from start)
image | Pointer to image to be loaded

Return Value

Next free video memory address (offset)

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video PutSprite

Video Driver

CalypsoPutSprite

WORD CalypsoPutSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG image_start, LONG xsize, LONG ysize, LONG mode)

Description

Block Copy from undisplayed video memory to screen display layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
doublebuffer_frame | Destination Double Buffer Frame
x | Destination top left X coordinate in pixels
y | Destination top left Y coordinate in pixels
image_start | Source start address (offset from start of video memory)
xsize | Block width in pixels
ysize | Block height in pixels
mode | Block transfer mode - NORMAL_MODE | TRANSPARENT_MODE

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


PLuto 8 Video CopySprite

Video Driver

CalypsoCopySprite

WORD CalypsoCopySprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG image_start, LONG xsize, LONG ysize, LONG mode, LONG src_pitch)

Description

Variant of CalypsoPutSprite() with extra parameter to specify source pitch

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
doublebuffer_frame | Destination Double Buffer Frame
x | Destination top left X coordinate in pixels
y | Destination top left Y coordinate in pixels
image_start | Source start address (offset from start of video memory)
xsize | Block width in pixels
ysize | Block height in pixels
mode | block transfer mode - NORMAL_MODE | TRANSPARENT_MODE
src_pitch | source pitch in pixels

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SaveSprite

Video Driver

CalypsoSaveSprite

WORD CalypsoSaveSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG save_address, LONG xsize, LONG ysize)

Description

Copy block of pixels ("sprite") from screen layer to undisplayed video memory

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Source Layer
doublebuffer_frame | Double buffer frame
x | Source x position
y | Source y position
save_address | Destination start address (offset)
xsize | Block width pixels
ysize | Block height in lines

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video ClearSprite

Video Driver

CalypsoClearSprite

WORD CalypsoClearSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG xsize, LONG ysize)

Description

Clear display block ("sprite") to BLACK (color zero)

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
doublebuffer_frame | Destination Double Buffer Frame
x | Block top left X coordinate in pixels
y | Block top left Y coordinate in lines
xsize | Block width in pixels
ysize | Block height in lines

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video FillSprite

Video Driver

CalypsoFillSprite

WORD CalypsoFillSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG xsize, LONG ysize, LONG color, LONG mode)

Description

Fill block ("sprite") with specified color

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
doublebuffer_frame | Destination Double Buffer Frame
x | Block top left X coordinate in pixels
y | Block top left Y coordinate in pixels
xsize | Block width in pixels
ysize | Block height in lines
color | Fill color (16/24 bits)
Mode | Write mode - BLT_CLEAR | BLT_COPY | BLT_AND | BLT_OR

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetBltTransparentColor

Video Driver

CalypsoSetBltTransparentColor

WORD CalypsoSetBltTransparentColor(const DEVICE* dev, ULONG tcolor)

Description

Set BitBlt transparent colour

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
tcolor | 16/32 bit transparent colour value

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video GetBltTransparentColor

Video Driver

CalypsoGetBltTransparentColor

ULONG CalypsoGetBltTransparentColor(const DEVICE* dev)

Description

Returns current BitBlt transparent colour

Parameters

Parameter | Description
dev | Pointer to Destination Video Device (ignored)

Return Value

Transparent Color

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetAsciiFont

Video Driver

CalypsoSetAsciiFont

void CalypsoSetAsciiFont(const DEVICE* dev, const CALYPSOFONT *font)

Description

Set the current active ASCII character font.

Parameters

Parameter | Description
dev | Pointer to Destination Video Device (ignored) - Font is common to both channels.
font | Pointer to font

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetTextColor

Video Driver

CalypsoSetTextColor

WORD CalypsoSetTextColor(const DEVICE* dev, ULONG foreground_color, ULONG background_color)

Description

Set text foreground and background colour Background color=0 is TRANSPARENT

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
foreground_color | 16/32 bit foreground colour value
background_color | 16/32 bit background colour value

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video SetTextPosition

Video Driver

CalypsoSetTextPosition

void CalypsoSetTextPosition(const DEVICE* dev, LONG layer_select, WORD x, WORD y)

Description

Set current text writing position for specified display layer. Text writing coordinate specifies the BOTTOM LEFT corner of the next character to be written to the display.

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination Display Layer
x | Screen X coordinate in pixels
y | Screen Y coordinate in pixels

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video GetTextPositionX

Video Driver

CalypsoGetTextPositionX

WORD CalypsoGetTextPositionX(const DEVICE* dev, LONG layer_select)

Description

Get x coordinate of the current text writing position on display layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Display Layer

Return Value

X position in pixels from left of screen

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video GetTextPositionY

Video Driver

CalypsoGetTextPositionY

WORD CalypsoGetTextPositionY(const DEVICE* dev, LONG layer_select)

Description

Get Y coordinate of the current text writing position for display layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Display Layer

Return Value

Y position in lines from top of screen

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video PutCHar

Video Driver

CalypsoPutChar

WORD CalypsoPutChar(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, UBYTE input_ch)

Description

Write ASCII Character to Display Layer

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Display Layer
doublebuffer_frame | Double buffer frame
input_ch | ASCII character to display

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video PutStr

Video Driver

CalypsoPutStr

WORD CalypsoPutStr(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, BYTE *str)

Description

Write text string to video display layer using currently selected font

Parameters

Parameter | Description
dev | Pointer to Destination Video Device
layer_select | Destination layer
doublebuffer_frame | Double buffer frame
str | Pointer to null terminated text string

Return Value

Returns SUCCESS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video DrawBusy

Video Driver

CalypsoDrawBusy

LONG CalypsoDrawBusy()

Description

Tests the status of the Carmine drawing engine

Parameters

None

Return Value

Returns TRUE if busy
Returns FALSE if not busy

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video Defined Values

Video Driver Defined Values

The following values have been defined for the Video Driver:

Read Skip Defined Values

Label | Description
READSKIP_DISABLE | Disable readskip function
READSKIP_NORMAL | Normal skipping
READSKIP_INVERSE | Invert the map: skip - noskip swapped

Display Mode Defined Values

reg_table | Description
Calypso640x480 | Display Resolution 640x480
Calypso800x600 | Display Resolution 800x600
Calypso1024x768 | Display Resolution 1024x768
Calypso1280x1024 | Display Resolution 1280x1024

Color Mode Defined Values

Label | Description
COLOR_16 | 16 bits per pixel
COLOR_24 | 24 bits per pixel

Layer Select Defined Values

layer_select | Description
C_LAYER | Console Layer
W_LAYER | Window Layer
ML_LAYER | Middle Left Layer
MR_LAYER | Middle Right Layer
BL_LAYER | Base Left Layer
BR_LAYER | Base Right Layer

Layer Enable Defined Values

layer | Description
CONSOLE_SELECT | Console Layer
WINDOW_SELECT | Window Layer
MIDDLE_SELECT | Left and Right Middle Layers
BASE_SELECT | Left and Right Base Layers
ALL_SELECT | Select All Layers

Double Buffer Frame Defined Values

Label | Description
DOUBLEBUFFER_FRAME0 | Write to Frame 0
DOUBLEBUFFER_FRAME1 | Write to Frame 1
DOUBLEBUFFER_AUTO | Write to currently non-displayed Frame

Frame Rate Defined Values

rate | Description
FRAME_60HZ | Frame Update Rate 60Hz
FRAME_30HZ | Frame Update Rate 30Hz
FRAME_20HZ | Frame Update Rate 20Hz
FRAME_15HZ | Frame Update Rate 15Hz
FRAME_12HZ | Frame Update Rate 12Hz
FRAME_10HZ | Frame Update Rate 10Hz
FRAME_5HZ | Frame Update Rate 5Hz
FRAME_3HZ | Frame Update Rate 3Hz
FRAME_2HZ | Frame Update Rate 2Hz
FRAME_1HZ | Frame Update Rate 1Hz
FRAME_0HZ | Manual Update

Device Parameter Defined Values

All the API functions in the Calypso 32 Video Driver include a device parameter. This identifies which of the two video screens the function refers:

Calypso32SomeFunction(const DEVICE *dev, parameter list...)

Where dev is one of the following:

dev | Description
&Calypso32Dual0Device | First screen
&Calypso32Dual1Device | Second screen

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Audio Driver

Audio Driver

The Pluto 8 audio driver provides the capabilty to play up to four channels of audio data. The driver supports the proprietary Heber Sound File format which has the following features:

  • The Heber Sound Files are pre-processed - header information has been reduced to a single length field
  • The audio data is compressed using CCITT-ULAW
  • Stereo samples are stored in separate HSF files

API Functions

The following API functions are provided by this module:

Function | Description
AudioPlay | Play audio data from specified system memory address
AudioStop | Stop audio playback
AudioRestart | Restart audio playback
AudioStatus | Return status of audio channel

See Also

  • Audio Defined Values
  • Audio Function Return Codes
  • Audio Sample Preparation
  • HSF Audio Pre-Processing Utility
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Audio Play

Audio Driver

AudioPlay

BYTE AudioPlay(const DEVICE* dev, UBYTE channel, ULONG *address, UWORD volume, UBYTE loop)

Description

Playback audio data on given channel from system memory address.

Parameters

Parameter | Description
dev | Pointer to the audio device
channel | Audio channel
address | Source address of audio data
volume | Playback volume values over 256 amplifies the sample, under 256 attenuates signal
loop | Loop audio playback

Return Value

Returns SUCCESS if the operation is successful
Returns NOT_INSTALLED if the driver has not been installed
Returns CHANNEL_BUSY if the specified channel is in use
Returns INVALID_CHANNEL if the channel specified is not valid

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Audio Stop

Audio Driver

AudioStop

BYTE AudioStop(const DEVICE* dev, UBYTE channel)

Description

Stop audio playback on given channel.

Parameters

Parameter | Description
dev | Pointer to the audio device
channel | Audio channel

Return Value

Returns SUCCESS if the operation is successful
Returns NOT_INSTALLED if the driver has not been installed
Returns INVALID_CHANNEL if the channel specified is not valid

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Audio Restart

Audio Driver

AudioRestart

BYTE AudioRestart(const DEVICE* dev, UBYTE channel)

Description

Restart audio playback on given channel from current audio position.

Parameters

Parameter | Description
dev | Pointer to the audio device
channel | Audio channel

Return Value

Returns SUCCESS if the operation is successful
Returns NOT_INSTALLED if the driver has not been installed
Returns INVALID_CHANNEL if the channel specified is not valid

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Audio ChannelStatus

Audio Driver

AudioChannelStatus

BYTE AudioChannelStatus(const DEVICE* dev, UBYTE channel)

Description

Return status of given audio channel.

Parameters

Parameter | Description
dev | Pointer to the audio device
channel | Audio channel

Return Value

Returns CHANNEL_STOP if the channel is stopped
Returns CHANNEL_PLAY if the channel is playing
Returns NOT_INSTALLED if the driver has not been installed
Returns INVALID_CHANNEL if the channel specified is not valid

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Audio Defined Values

Audio Driver Defined Values

The following values are defined for use with the Heber audio driver:

Defined Audio Channels

Label | Meaning
CHANNEL_LEFT0 | Left Audio channel 0
CHANNEL_LEFT1 | Left Audio Channel 1
CHANNEL_RIGHT0 | Right Audio Channel 0
CHANNEL_RIGHT1 | Right Audio Channel 1

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Audio Return Codes

Audio Driver Return Codes

Audio Defined Return Codes

Label | Value | Meaning
SUCCESS | 0 | The requested operation was performed successfully.
CHANNEL_STOP | 0 | The channel status is currently stopped.
CHANNEL_PLAY | 1 | The channel status is currently playing.
NOT_INSTALLED | -1 | Audio driver is not installed.
INVALID_CHANNEL | -2 | Specified auido channel is not valid.
CHANNEL_BUSY | -3 | The specified audio channel is busy.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Audio Sample Preparation

Silence/Fading

It is recommended that at the end of all audio samples either the sample is faded to silence, or a period of silence is added. Failure to do this may result in an audible click when a sample is stopped and immediately restarted. The audible click is a result of the following sequence of events:

  • Audio sample stopped. Audio amplifier is at an unknown voltage level
  • Audio amplifier begins to settle to 0 volts (silence)
  • Sample restarts before the audio amplifier has settled causing the volatge to dip to 0 volts and rise rapidly causing a click

By fading samples or adding silence the audio amplifier is forced to 0 volts before the sample ends. 5ms of silence should be sufficient to prevent this problem.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Multiplexed Inputs Driver

Multiplexed Inputs Driver

The Multiplexed Inputs module is a device driver controlling system inputs. There are 32 general purpose inputs, and 16 inputs connected to 2 DIL switches (DIL1 and DIL2). In their inactive state they are pulled up to +5v and read by the software as TRUE (‘1’). When the inputs are pulled down to ground they are read as FALSE (‘0’).

The following defined values are used to access the inputs:

  • General purpose inputs - IP0-IP31
  • DIL switch 1 - DIL0-DIL7
  • DIL switch 2 - DIL8-DIL15

API Functions

The following API functions are provided by this module:

Function | Description
Test | Allows the status of a given input to be tested.(Buffered)
TestDir | Allows the status of a given input to be tested.(Unbuffered)
CurrentSense | Tests the current sense circuitry
PushButton | Tests the state of the push button SW1
ExternalPushButton | Tests the state of the external push button

See Also

  • Multiplexed Inputs API function return codes
  • Multiplexed Inputs Configuration Data
  • Multiplexed Inputs Defined Values
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Test Inputs

Multiplexed Inputs Driver

Test

BYTE Test(const INPUT input)

Description

This function allows the status of a given input to be tested. The inputs are read every N* milliseconds in an interrupt routine and a change of state registered after three consecutive reads that are the same. The function can also test inputs wired to one of the input strobes rather than zero volts.

Note: * N is the de-bounce sample time defined in the INPUTCFG structure at application level in config.c.

Parameters

Parameter | Description
input | The input to be tested. This will be one of the macros defining the Heber input numbers ie. IP0 - IP31 and DIL0 - DIL15.

Return Value

Returns ON if the input is at its active state
Returns OFF if the input is not at its active state
Returns INVALID_INPUT_ID if the input value is out of the range of this function

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: TestDir Inputs

Multiplexed Inputs Driver

TestDir

BYTE TestDir(const INPUT input)

Description

This function tests the I/O space directly and calculates its return value based on the instantaneous value read.

Parameters

Parameter | Description
input | The input to be tested. This will be one of the macros defining the Heber input numbers ie. IP0 - IP31 and DIL0 - DIL15.

Return Value

Returns ON if the input is at its active state
Returns OFF if the input is not at its active state
Returns INVALID_INPUT_ID if the input value is out of the range of this function

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Current Sense

Multiplexed Inputs Driver

CurentSense

BYTE CurrentSense(void)

Description

Test the current sense circuitry. This can be used to test for the presence of electro-mechanical counters.

Parameters

None.

Return Value

Returns ON if the current sense circuit is active. (i.e. current is flowing)
Returns OFF if current is not flowing

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Push Button Test

Multiplexed Inputs Driver

PushButton

BYTE PushButton(void)

Description

Tests the state of the push button SW1 on the Pluto 8 board.

Parameters

None.

Return Value

Returns ON if the button is depressed
Returns OFF if the button is not depressed

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Push Button Test

Multiplexed Inputs Driver

ExternalPushButton

BYTE ExternalPushButton(void)

Description

Tests the state of the external push button on the Pluto 8 board.

Parameters

None.

Return Value

Returns ON if the button is depressed
Returns OFF if the button is not depressed

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Multiplexed Inputs Return Codes

Multiplexed Inputs Driver Function Return Codes

The following return codes are returned by the Multiplexed Inputs API functions.

Return Code | Value | Description
ON | 1 | The input is in its active state
OFF | 0 | The input is not in its active state
INSTALL_INPUTS_FAILURE | -1 | The install function is called when the MXIDevice is used in the device list in devices.c at project level. The failure will be reported when the driver is loaded.
INVALID_INPUT_ID | -2 | It is possible to use byte values rather than Heber inputs(e.g. IP2). This is not recommended but if a user chooses to do so any value below 0 and above 39 will return this error.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Code Example

Multiplexed Inputs Driver Configuration Data

The following data related to the Multiplexed Input Driver is user configurable and is contained in the config.c file at game level.

Debounce Sample Time

The sample time in milliseconds between each of the three reads when using debounced input reading can be set in the InputCfg structure:

const INPUTCFG InputCfg[] = { {3}, }; /* Debounce sample time = 3ms */

Strobe Input Memory Maps

For each input strobe defined a memory map needs to be defined. In the sample code below 2 memory maps are defined for 2 input strobes.

INPUTMAP MxiInputMap[2];

Strobe Assignments

Any of the outputs (OP0 – OP63) can be allocated for use as input strobes. In the sample code below outputs OP30 and OP31 are defined as strobes for the multiplexed inputs.

const WORD MxiStrobeLst[] = { OP30, OP31, -1 };
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Multiplexed Inputs Defined Values

Multiplexed Inputs Driver Function Defined Values

The following values are defined for use with the Multiplexed Inputs Driver:

Defined Inputs

The following values are defined to represent all Pluto 8 inputs:

Label | Meaning
IP0 to IP31 | 32 inputs connected to pin header I/O-1 and I/O-2
DIL0 to DIL15 | Connected to the dil switches (DIL1 and DIL2)

Example Use:

Test input number 20.

if(Test(IP20))
{
    return(SUCCESS);
}

Active Inputs

Label | Meaning
ACT0 | Active Low
ACT1 | Active High

Example Use:

Test the input number 20 with the input treated as active high. The function returns TRUE when the input is inactive (read as 1).

if(Test(ACT1 | IP20))
{
    return(SUCCESS);
}

Multiplexed Strobes

Label | Meaning
MXI0 | Multiplexed Strobe 0
MXI1 | Multiplexed Strobe 1
MXI2 | Multiplexed Strobe 2
MXI3 | Multiplexed Strobe 3

Example Use:

Strobes can only be used with the Test() function. below we test input IP20 with reference to input strobe 0.

if(Test(MXI0 | IP20))
{
    return(SUCCESS);
}
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Outputs Driver

Outputs Driver

The output module is a device driver controlling system outputs. There are 32 open drain outputs that are high impedance when inactive, and pulled down to ground when active. The status of all 32 outputs is maintained in RAM and written out to the I/O space every millisecond to give noise immunity.

API Functions

The following API functions are provided by this module:

Function | Description
OutputOn | Sets the given output
OutputOff | Clears the given output

See Also

  • Output driver defined values
  • Output driver return codes
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: Output On

Outputs Driver

OutputOn

BYTE OutputOn(const OUTPUT output)

Description

Sets the status of the given output to on (or active) in the status RAM. It takes up to 1 millisecond before the output status is written out to the I/O space and the output pulled down to ground.

Parameters

Parameter | Description
output | The input to be asserted. This will be one of the macros defining the Heber output numbers (OP0 - OP31).

Return Value

Returns SUCCESS if the operation is successful
Returns INVALID_OUTPUT_ID if the ouput specified was not within the range of valid outputs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: OutputOff

Ouputs Driver

OutputOff

BYTE OutputOff(const OUTPUT output)

Description

Sets the status of the given output to off (or inactive) in the status RAM. It is up to 1 millisecond before the output status is written out to the I/O space and the output goes into high impedance state.

Parameters

Parameter | Description
output | The output to be asserted. This will be one of the macros defining the Heber output numbers (OP0 - OP31)

Return Value

Returns SUCCESS if the operation is successful
Returns INVALID_OUTPUT_ID if the ouput specified was not within the range of valid outputs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Output Values

Output Driver Defined Values

The following values are defined for use with the Heber outputs driver:

Defined Outputs

The following values are defined to represent all Pluto 8 outputs:

Label | Meaning
OP0 - OP31 | Output 0 to 31

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Output REturn Codes

Output Driver Function Return Codes

The following return codes are returned by the Outputs API functions.

Return Code | Value | Description
SUCCESS | 0 | The specific function executed correctly.
INVALID_OUTPUT_ID | -1 | Ouput is not within the range of valid outputs.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Serial Communications Driver

Serial Communications Driver

The Serial Communications Driver contains functions which are used to access the services of the serial devices on the Pluto 8 control board

  • Serial RS232 devices at a range of Baud rates
  • Serial RS485 devices
  • TTL level outputs
  • CCTALK devices

API Functions

The following API functions are provided by this module:

Function | Description
ConfigureSerial | Configures the receiver and transmitter for a specified serial port
TxChar | Transmit a character using a specified serial port
TxString | Transmit a string of characters using a specified serial port
RxChar | Read a character from a specified serial port
TxEmpty | Test the status of the transmit buffer
RxEmpty | Test the status of the recieve buffer
TxClear | Set the transmit buffer to zero
RxClear | Set the recieve buffer to zero
SetRouting | Route a serial port to a specified physical output
WriteModemControls | Manually set/clear modem control signals
ReadModemControls | Read status of modem control input signals

See Also

  • Serial API function return codes.
  • Serial API function defines values
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

ConfigureSerial

BYTE ConfigureSerial(const DEVICE* dev, BYTE channel, BYTE txbaud, BYTE rxbaud, BYTE data_bits, BYTE stop_bits, BYTE parity, BYTE txhs, BYTE rxhs)

Description

This function is the prerequisite for all Serial Communications functions.Supported values for port configuration settings are listed in the Serial Device Defined Values page.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.
txbaud | baud rate at which the selected port will transmit data
rxbaud | baud rate at which the selected port will recieve data
data_bits | number of bits per character sent or recieved
stop_bits | number of stop bits
parity | parity setting
txhs | transmit handshaking procedure
rxhs | recieve handshaking procedure

Return Value

Returns SUCCESS if the serial device was successfully configured
Returns RTS_FAIL if the serial device is not ready to send
Returns UPSUPPORTED_BAUD_RATE if the baud rate supplied is not supported by the serial device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

TxChar

BYTE TxChar(const DEVICE* dev, BYTE channel, BYTE ch)

Description

Transmit a character using the specified device. It is possible the TxChar() function will fail due to transmit buffer overflow if called repeatedly in quick succession because the function is non-blocking.

Parameters

Parameter | Description
dev | Hardware address of the Serial Communications device to send data from
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.
ch | The character to be transmitted over the selected channel

Return Value

Returns SUCCESS if the character was successfully placed in the transmit buffer
Returns BUFFER_FULL is the transmit buffer is full

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

TxString

void TxString(const DEVICE* dev, BYTE channel, const BYTE* string)

Description

Transmit a string of characters using the specified serial device.

Parameters

Parameter | Description
dev | Hardware address of the Serial Communications device to transmit data from
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.
string | Pointer to the string to be transmitted

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

RxChar

WORD RxChar(const DEVICE* dev, BYTE channel)

Description

Read a character from the specified UART.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.

Return Value

Returns a character if the read operation is successful
Returns BUFFER_EMPTY if the receive buffer is empty

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

TxEmpty

BYTE TxEmpty(const DEVICE* dev, BYTE channel)

Description

This function checks the status of the transmit buffer for the specified UART. This function can be used to ensure data has been transmitted before clearing the buffer.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.

Return Value

Returns SUCCESS if the transmit buffer is empty
Returns BUFFER_NOT_EMPTY if the transmit buffer is not empty

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

RxEmpty

BYTE RxEmpty(const DEVICE* dev, BYTE channel)

Description

This function checks the status of the receive buffer for the specified UART.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.

Return Value

Returns SUCCESS if the transmit buffer is empty
Returns BUFFER_NOT_EMPTY if the transmit buffer is not empty

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

TxClear

void TxClear(const DEVICE* dev, BYTE channel)

Description

This function clears any data in the transmit buffer for the specified UART.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

SetRouting

void SetRouting(const DEVICE* dev, BYTE channel, BYTE route)

Description

This function sets the route between a specified UART and output connector, for example, Coldfire® UART PSC0 to output RS232A.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.
route | The route for the specified UART.

Return Value

None.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

WriteModemControls

void WriteModemControls(const DEVICE* dev, BYTE channel, BYTE control)

Description

Manually set/clear modem control signals

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.
control | RTS | RS485_TX - Modem Control signals asserted

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software RNG_StartRNG

Serial Communications Driver

ReadModemControls

BYTE ReadModemControls(const DEVICE* dev, BYTE channel)

Description

Read status of modem control input signals

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.

Return Value

Modem Control signals status (bit fields ORed together) Implemented: CTS

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Define Values

Serial Driver Defined Values

The following values are defined for use with the Pluto 8 serial communications device driver for the Coldfire® UARTs and FPGA UARTs

Coldfire® UARTs

Label | Device
PSC0Device | Coldfire® UART 0
PSC1Device | Coldfire® UART 1
PSC2Device | Coldfire® UART 2
PSC3Device | Coldfire® UART 3

FPGA UARTs

Label | Device
FPUart0Device | FPGA UART 0
FPUart1Device | FPGA UART 1

Baud Rates

Label | Baud Rate | Coldfire® UARTs | FPGA UARTs
BAUD1200 | 1200 | ✔ | ✔
BAUD1800 | 1800 | ✔ | not supported
BAUD2000 | 2000 | ✔ | not supported
BAUD2400 | 2400 | ✔ | ✔
BAUD4800 | 4800 | ✔ | ✔
BAUD7200 | 7200 | ✔ | not supported
BAUD9600 | 9600 | ✔ | ✔
BAUD19200 | 19200 | ✔ | ✔
BAUD38400 | 38400 | ✔ | ✔
BAUD76800 | 76800 | ✔ | not supported

Data Bits

The following values define the number of bits per character in each serial communication. Note that signals routed through the FPGA cannot use the label BITS6.

Label | Setting | Coldfire® UARTs | FPGA UARTs
BITS6 | 6 data bits | Port 0 only | not supported
BITS7 | 7 data bits | ✔ | ✔
BITS8 | 8 data bits | ✔ | ✔

Stop Bits

The following defined numbers of stop bits are valid for all serial devices:

Label | Setting
STOP1 | 1 stop bit
STOP2 | 2 stop bits

Parity Setting

The following defined parity settings are valid for all serial devices:

Label | Setting
PARITYEVEN | Even Parity
PARITYODD | Odd Parity
PARITYNONE | No Parity

Handshaking Settings

The following defined Handshaking settings are valid for the Coldfire® UART devices only. They use the Request To Send (RTS) and Clear To Send (CTS) lines. The FPGA UARTSs do not provide automatic hardware handshaking.

Transmit Handshaking Settings

Label | Setting
TXNONE | No Handshaking
TXRTS | Uses only the RTS line for handshaking
TXCTS | Uses only the CTS line for handshaking
TXBITS | Uses both the RTS and CTS line for handshaking

Recieve Handshaking Settings

Label | Setting
RXNONE | No Handshaking
RXRTS | Uses only the RTS line for handshaking
RXBITS | Same as RXRTS

Routing Options

The following defined routing options are valid for the FPGA UART devices only.

Label | Setting
UART1_RS485 | FPGA Uart 0 routed to RS485 channel
UART1_TTLA | FPGA Uart 0 routed to TTL channel A
UART2_RS232C | FPGA Uart 1 routed to RS232 channel C
UART2_TTLB | FPGA Uart 1 routed to TTL channel B

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Return Codes

Serial Driver Function Return Codes

The following return codes are returned by the Serial Communications API functions.

Return Code | Value | Description
BUFFER_NOT_EMPTY | 1 | The buffer contains one or more characters
SUCCESS | 0 | The operation was executed successfully
BUFFER_FULL | -1 | The buffer is full
UNSUPPORTED_BAUD_RATE | -2 | The baud rate supplied to the serial port is not supported
RTS_FAIL | -3 | The serial device is not ready to send
BUFFER_EMPTY | -4 | The buffer is contains no characters
UNSUPPORTED_PARAMETER | -5 | The specified data bits, stop bits or parity bits are not supported

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 PIC Driver

PIC Driver

The PIC microcontroller fitted to socket U51 on Pluto 8 is used for two purposes:

  • Maintaining a Real Time Clock
  • Reading and storing the state of the security switches

The I2C driver is used in order to communicate between the Coldfire and the PIC.

API Functions

The following API functions are provided by this module:

Function | Description
GetPicTime | Read the real time clock.
SetPicTime | Set the real time clock to a specific date and time.
GetPicLog | Read a record from the security switch change log
ClearPicLog | Clear all entries in the security switch log
StartPicLogRead | Set the internal PIC log pointer to the most recently changed log entry
GetPicStatus | Check whether a switch value has changed since the last read security switch log read
GetPicRevision | Read the PIC software revision number
GetPicSerialNumber | Read the serial number from the PIC
SetPicSerialNumber | Set the PIC serial number

See Also

  • PIC function return codes
  • PIC associated data types
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicTime

PIC Driver

GetPicTime

BYTE GetPicTime(const DEVICE* picdev, PTIME* picrtctime);

Description

This function reads the Real Time Clock provided by the PIC. The picrtctime struct (of type PTIME) is populated with the lastest time and date from the PIC. The SetPicTime() function can be used to set the Real Time Clock.

Parameters

Parameter | Description
picdev | PIC Device address
picrtctime | Pointer to a structure holding the time read back from the PIC

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - SetPicTime

PIC Driver

SetPicTime

BYTE SetPicTime(DEVICE* picdev, PTIME* time)

Description

This function changes the Date and Time stored in PIC to the nearest second. In order to set the time, set each member of the time structure using HEXADECIMAL values and pass a pointer to this structure to the function.

Parameters

Parameter | Description
picdev | PIC Device address
time | Pointer to a structure holding the date and time to be set in the PIC Real Time Clock.

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicLog

PIC Driver

GetPicLog

BYTE GetPicLog(const DEVICE* picdev, PTIME* picrtctime, BYTE* pwroffinput);

Description

A change in the status of security switches will be recorded as an entry in the security switch log. The security switch log is a 10 entry circular buffer holding the switch status and time stamp for each entry. Entries to the switch log are stored consecutively. The GetPicLog() function reads the log entry at position determined by an internal pointer in the PIC. The pointer can be set to the last entry using the StartPicLogRead() function. The result of the log read is stored as the switch reading in pwroffinput and time stamp in the picrtctime structure.

Repeated calls to the GetPicLog() function without reseting the log internal pointer in the PIC will return log entries startign with the most recent and stepping backwards to the oldest.

The GetStatus() function can be used to test whether there has been a change in the switch status since the last read. Where regular checking of the switch status is required it is recommended that the GetStatus() function is used to determine if the log data has changed and therefore needs to be read.

Parameters

Parameter | Description
picdev | PIC Device address
picrtctime | Pointer to a structure holding the time stamp held in the log entry
pwroffinput | pointer to the value of the 'Power off switches' held in the log entry

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Pic Driver - ClearPicLog

PIC Driver

ClearPicLog

BYTE ClearPicLog(DEVICE* picdev)

Description

Clear all of the entries in the switch log. After the log has been cleared the first entry is populated with the current switch reading. The current switch reading provides a comparison for subsequent reads of the switches. The switches are read every 10ms in powered up mode and every 17ms when running on battery power.

Parameters

Parameter | Description
picdev | PIC Device address

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus
Returns PIC_INDEX_ERROR if a log index value of less than 1 or greater than 10 is supplied
Returns PIC_RECORD_EMPTY if the record at the specified index does not contain any data

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - StartPicLogRead

PIC Driver

StartPicLogRead

BYTE StartPicLogRead(const DEVICE* picdev);

Description

Reset the internal PIC Log pointer to the most recent entry.

Parameters

Parameter | Description
picdev | PIC Device address

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicStatus

PIC Driver

GetPICStatus

BYTE GetPicStatus(const DEVICE* picdev, SW_STATUS* statusdata)

Description

The status bit will be set if the swich value read by the PIC changes but has not yet been read. This allows the user to poll this bit instead of reading the switch log entries thus significantly reducing the I2C traffic. This function populates a struct of type SW_STATUS that holds not only the status byte but also the log entry number of the most recently changed log entry. This allows the user to then fetch the newest switch reading along with its time stamp using the GetPicLog function.

Parameters

Parameter | Description
picdev | PIC Device address
statusdata | Pointer to a struct holding the Status byte and Log Entry byte

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_IN_PROGRESS if an operation is still in progress
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicRevision

PIC Driver

GetPicRevision

BYTE GetPicRevision(const DEVICE* picdev, BYTE* revisiondata)

Description

As with any software, updates can be made as maintainence for this software is ongoing. This function allows end users to establish which revision of the software has been programmed into the pic.

Parameters

Parameter | Description
PICDevice | Pic Device address
revisiondata | Pointer to a byte containing the revision number of the PIC software.

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_IN_PROGRESS if an operation is still in progress
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

HEBER LTD. 2005. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicSerialNumber

PIC Driver

GetPicSerialNumber

BYTE GetPicSerialNumber(const DEVICE* picdev, UBYTE* serial)

Description

This function is used to read back the serial number stored in the PIC device EEPROM.

Parameters

Parameter | Description
PICDevice | PIC Device address
serial | Pointer to a ULONG containing the serial number stored in the PIC.

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_IN_PROGRESS if an operation is still in progress
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus
Returns PIC_RECORD_EMPTY if all of the bytes in the PIC EEPROM entry (no serial number has been set)

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - SetPicSerialNumber

PIC Driver

SetPicSerialNumber

BYTE SetPicSerialNumber( const DEVICE* picdev, BYTE* serial )

Description

This function is used to set the serial number stored in the PIC device EEPROM.

NOTE: This function can only be used once to set the serial number.

Parameters

Parameter | Description
PICDevice | PIC Device address
serial | Pointer to a ULONG containing the serial number to be stored in the PIC.

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_IN_PROGRESS if the operation is still in progress
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Data Types

PIC Driver Associated Data Types

PTIME structure

The PTIME data type is used to store time data retrieved from the PIC.

Type | Name
WORD | year
BYTE | month
BYTE | day
BYTE | date
BYTE | hours
BYTE | minutes
BYTE | seconds
BYTE | hundredths

SW_STATUS structure

The SW_STATUS data type is used to hold the security switch status information read from the PIC.

Type | Name
BYTE | switch_status 1 = changed but not read 0 = no change since last read
BYTE | logentry

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Return Codes

PIC Driver Function Return Codes

The following return codes are returned by the PIC API functions. You will notice that most of the return codes are exactly the same as the i2c return codes, this is because the PIC driver functions are essentially wrapper functions using the i2c Drivers.

Return Code | Value | Description
PIC_RECORD_EMPTY | 2 | If all of the bytes in the PIC log entry are equal to 0 (empty) then GetPicLog() will return 2. For example, after calling ClearPicLog() entr 2 - 10 will be empty.
I2C_IN_PROGRESS | 1 | An I2C operation is in progress
SUCCESS | 0 | The function executed successfully
I2C_BUS_BUSY | -2 | The I2C bus is in use and a new read or write operation can not be started
I2C_TIMEOUT | -3 | The I2C operation failed because one of the parts of the communication was not completed before the error timer expired. If this error condition occurs the I2C bus will be reset to ensure that the bus is not locked by either the slave or master.
I2C_SLAVE_ERROR | -4 | The slave address transmitted by the master was not acknowledged by any slave device on the I2C bus.
PIC_INDEX_ERROR | -5 | The PIC log has only ten entries therefore calling GetPicLog() with an index value greater than 10 or less than 1 will return this error

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 I2C Driver

I2C Driver

I2C is a 2 wire master/slave protocol that is used on Pluto 8 for communication between the main system processor and the following devices/interfaces:

  • PIC16 low power monitor device
  • E2PROM device
  • External I2C interface

The I2C driver has been implemented to provide bus master functionality, allowing the Pluto 8 main processor to communicate with the peripheral slave devices listed above.

API Functions

The following API functions are provided by this module:

Function | Description
I2CRead | Read data from a specified location on an I2C slave device.
I2CSeqRead | Read data sequentially from an I2C slave device.
I2CReadStatus | Test the status of a read operation from an I2C slave device.
I2CWrite | Write data to an I2C slave device.
I2CWriteStatus | Test the status of a write operation to an I2C slave device.

See Also

  • I2C function return codes
  • Description of the Pluto 8 I2C implementation
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Read

I2C Driver

I2cRead

BYTE I2cRead(BYTE deviceaddress, BYTE internaladdress, LONG bytecount)

Description

Issue a command to read n bytes of data from an I2C slave device.

Parameters

Parameter | Description
deviceaddress | Hardware address of the I2C slave device to read data from
internaladdress | Internal address code on the I2C slave device to read data from
bytecount | Number of bytes to read from the I2C slave device

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_BUS_BUSY if the bus is busy

Remarks

Following a call to the the I2CRead() function a call to the I2CReadStatus() function is required to ensure that the read operation has completed and was successful. The I2CReadStatus() function allows the user to access the data read from the I2C slave device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Sequential Read

I2C Driver

I2cSeqRead

BYTE I2cSeqRead(BYTE deviceaddress, ULONG bytecount)

Description

The I2cSeqRead() function allows n bytes of data from an I2C slave device. The function is suitable for use with I2C peripheral devices that maintain a local pointer to record the location in memory where the read operation will start from.

This function can also be used following an I2CWrite operation in cases where a read is required from a specific memory location on an I2C peripheral device that does not support repeated start operations. For further information refer to driver implementation notes.

Parameters

Parameter | Description
deviceaddress | Hardware address of the I2C slave device to read data from
bytecount | Number of bytes to read from the I2C slave device

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_BUS_BUSY if the bus is busy

Remarks

Following a call to the the I2CRead() function a call to the I2CReadStatus() function is required to ensure that the read operation has completed and was successful.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Read Status

I2C Driver

I2cReadStatus

BYTE I2cReadStatus(BYTE *buffer ULONG bytecount )

Description

Test the status of a read operation from an I2C slave device. If the call to the I2CRead() function was sucessful the pointer *buffer is set to the I2C receive buffer to allow the user access to the data that was read back from the I2C slave device. If the read operation was unsuccessful, or is still in progress, the pointer *buffer is set to NULL.

Parameters

Parameter | Description
buffer | Byte pointer to an array used to store the data read from the I2c receive buffer
bytecount | Number of bytes to read from the receive buffer

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_IN_PROGRESS if the operation is still in progress
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR the slave address transmitted by the master was not acknowledged by any slave device on the I2C bus

© HEBER LTD. 2008S. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Write

I2C Driver

I2cWrite

BYTE I2cWrite(const BYTE* source,LONG bytecount,BYTE deviceaddress, BYTE internaladdress )

Description

Write n bytes of data to an I2C slave device.

Parameters

Parameter | Description
source | Byte pointer to the buffer where the data to be written is stored
bytecount | Number of bytes of data to write
deviceaddress | Hardware address of the I2C slave device to write data to
internaladdress | Internal address code on the I2C slave device to write data to

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_BUS_BUSY if the bus is busy

Remarks

Following a call to the the I2cWrite() function a call to the I2CWriteStatus() function is required to ensure that the write operation has completed and was successful.

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Write Status

I2C Driver

I2cWriteStatus

BYTE I2cWriteStatus(void)

Description

Test the status of a write operation to an I2C slave device.

Parameters

None.

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_IN_PROGRESS if the operation is still in progress
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR the slave address transmitted by the master was not acknowledged by any slave device on the I2C bus

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Return Codes

I2C Driver Function Return Codes

The following return codes are returned by the I2C API functions.

Return Code | Value | Description
I2C_IN_PROGRESS | 1 | An I2C operation is in progress
SUCCESS | 0 | The function executed successfully
I2C_BUS_BUSY | -2 | The I2C bus is in use and a new read or write operation can not be started
I2C_TIMEOUT | -3 | The I2C operation failed because one of the parts of the communication was not completed before the error timer expired. If this error condition occurs the I2C bus will be reset to ensure that the bus is not locked by either the slave or master.
I2C_SLAVE_ERROR | -4 | The slave address transmitted by the master was not acknowledged by any slave device on the I2C bus.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Implementation

I2C Driver Implementation

The Pluto 8 I2C driver has been implemented using the I2C hardware module on the Coldfire® 5475 processsor. The driver uses a processor interrupt service routine to transmit/receive data to and from an I2C slave device.

Writing to an I2C slave device

The I2cWrite() function used to send data to an I2C slave device is a non-blocking function. The I2cWrite()function performs the following operations:

  • Test that the bus is free
  • Set the processer hardware module in transmit mode
  • Send a start condition over the I2C bus
  • Transmit the hardware address of the I2C slave in write mode

If the bus is busy the function will return with a return value of I2C_BUS_BUSY. If the hardware address has been transmitted the function will return SUCCESS.

The remaining data to be transmitted is sent by the I2C interrupt service routine. The status of the transmission can be tested by calling the I2cWriteStatus() function. While the transmission is in progress another operation can not be started.

Reading from an I2C slave device

There are three possible ways to read from an I2C slave device using the Pluto 8 driver. The I2C read functions are non-blocking.

Sequential Read

The I2cSeqRead() function allows a specified number of bytes to be read from an I2C slave device. The function is suitable for use a slave device such as an E2PROM where the device maintains a local pointer to the next memory location to begin the read from. The function performs the following operations:

  • Test that the bus is free
  • Set the processer hardware module in transmit mode
  • Send a start condition over the I2C bus
  • Transmit the hardware address of the I2C slave in read mode

If the bus is busy the function will return with a return value of I2C_BUS_BUSY. If the hardware address has been transmitted the function will return SUCCESS.

The data is read by the I2C interrupt service routine. The status of the read operation can be tested by calling the I2cReadStatus() function. During a read operation another I2C operation can not be started. When the read operation is complete the I2cReadStatus() function will return SUCCESS and pointer set to the read data buffer.

Repeated Start Read

The I2cRead() function allows a specified number of bytes to be read from a specified address on an I2C slave device. The function can be used with I2C slave devices that support repeated start, or to perform a read from a specified address on an E2PROM device. The function performs the following operations:

  • Test that the bus is free
  • Set the processer hardware module in transmit mode
  • Send a start condition over the I2C bus
  • Transmit the hardware address of the I2C slave in write mode

If the bus is busy the function will return with a return value of I2C_BUS_BUSY. If the hardware address has been transmitted the function will return SUCCESS.

The following operations are performed in the interrupt service routine:

  • Transmit the internal address that data is to be read from
  • Generate a repeated start condition
  • Transmit the hardware address of the I2C slave device in read mode
  • Read n bytes of data from the I2C slave device

The status of the read operation can be tested by calling the I2cReadStatus() function. During a read operation another I2C operation can not be started. When the read operation is complete the I2cReadStatus() function will return SUCCESS and pointer set to the read data buffer.

Simulated Repeated Start

If a device does not support repeated start but requires an internal address to be transmitted prior to reading data the following combination of function calls can be used:

  • Use the I2cWrite() function to send out the internal I2C slave address to read from
  • Use the I2cWriteStatus() function to ensure that operation is complete
  • Use the I2cReadSeq() function to read data from the I2C slave device
  • Use the I2cReadStatus() function test that the operation is complete and retrieve the read data

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Device Manager

Device Manager

The device manager provides the mechanism by which device drivers for hardware and peripherals can be installed.

API Functions

The following API function is associated with this module:

Function | Description
InstallDevices | Installs the device drivers in the given list

See Also

  • Defining a Device List
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Device Manager

InstallDevices

BYTE InstallDevices( const INSTALLDEVICE* dlist )

Description

Install the device drivers in the given list

Parameters

Parameter | Description
dlist | The list of device drivers to install

Return Value

Return TRUE on success.
Return FALSE if one or more drivers have reported errors

Code Example

/* install devices listed in DeviceLst */
if(InstallDevices(DeviceLst))
{
      return(TRUE);
}
else
{
      return(FALSE);
}
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Device Manager

A device list defines all of the device drivers to be installed for a given game application. Each entry in the device list is of type INSTALLDEVICE and consists of the following 4 elements:

Element | Description
Device | The address of the device driver structure to be installed
Device Select Function | A pointer to the device select function. This function returns TRUE if the device is to be installed. If this field is zero the device is installed
Configuration Select Function | A pointer to the configuration select function. The device driver structure contains a pointer to an array of configuration structures for the device. This function is responsible for calculating the index into this array and thereby selecting the configuration data to be used. If this field is zero configuration index zero is used
Optional Parameter | This is an optional parameter, which is passed into the configuration select function. It will typically be some parameter that the configuration select function uses to determine which index to return. (For example a list of DIL switches)

Code Example

/* a simple device list to install three Pluto devices - timer, audio and outputs */
const	INSTALLDEVICE DeviceList[]=
{
    {&TimerDevice  ,0,0,0},
    {&AudioDevice  ,0,0,0},
    {&OutputDevice ,0,0,0},
    {0,0,0}
};

The device list for a gaming application is created in the file devices.c in the Application Module

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Entry Module

Entry Module

The entry module provides start-up code to perform low-level initialisation of the Pluto 8 hardware.
The entry module sets up the following on the ColdFire® processor:

Vector base register | The vector base register holds the initial address for the interrupt vector table
Processor register base address | The internal processor registers are defined as offsets from the base address
Instruction caching | Cache processor instructions to optimise performance
Internal processor SRAM | Configure the internal processor SRAM is used for the stack

At this point code can be run on the processor. Following the intial configuration the code jumps to the main( ) function where further configuration takes place.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Main Function

Main Function

The main( ) function continues the configuration of the Pluto 8 hardware.
The following ColdFire® modules are configured and operations executed:

General Purpose I/O (GPIO) ports | The GPIO are configured to allow access to on board peripheral devices and memory.
Flex bus module | The Flex bus module is used to access the FPGA, Compact Flash and External Pluto 8 SRAM
SDRAM controller | The SDRAM controller is setup to allow access to the 128MB of onboard SDRAM.
SRAM controller | The SDRAM controller is setup to allow access to the onboard SRAM.
Timers | Setup the General purpose and Slice Timers(to generate 1ms and 10ms interrupts).
Edge Port Module | Setup up pins fro external interrupts (Video and FPGA UARTs).
PCI Module | Setup the PCI bus (used to communicate with the video processor).
Install Coldfire serail ports | Install and configure the Coldfire serial ports.
I2C | Configure the I2C bus controller.
Install peripheral device drivers | Install all of the devices listed to the device list in the application.
Enable Interrupts | Enable the sytem interrupts.

When the processor has been configured and device drivers installed the code jumps to the main application.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Interrupt Module

Interrupt Module

Functionality is provided in the interrupt module to allow the user to install functions that will be run based on system interrupts.

API Functions

The following API functions is associated with this module:

Function | Description
InstallIntFnc | Installs a function into the given interrupt list.

See Also

  • Pluto 8 Interrupts
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Interrupt Module

Interrupt Module

InstallIntFnc

BYTE InstallIntFnc(void(*fnc)(),void(**fnc_lst)())

Description

Add a pointer to an interrupt handler function fnc, to the end of the specified interrupt scheduler list fnc_lst.

Remarks

Before using this function refer to the Pluto 8 Interrupts page.

Parameters

Parameter | Description
fnc | Address of the function to be installed to the given interrupt list.
fnc_lst | Address of the interrupt list where the function fnc is to be installed.

Return Value

Returns TRUE if the operation was performed succesfully
Returns FALSE if the interrupt scheduler queue is full.
It is recommended that the return value is always tested.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Interrupt Module

Pluto8 Interrupts

Pluto 8 Interrupts

Six interrupt scheduler lists are defined in the Pluto 8 software which are declared and initialised in config.c in the project directory:

void (*Int1msLst[])()={0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*Int10msLst[])()={0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*Int250msLst[])()={0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntVideo0Lst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntVideo1Lst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntFpuartLst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};

The Pluto 8 system software uses several levels of interrupts. These levels of interrupt are fixed and should not be changed by the user. In certain case users may need to install their own driver or interrupt driven functions, which can be achieved by adding functions to the appropriate interrupt scheduler list.

Note: Caution must be exercised when making any changes to the interrupts. Modification of priorities or overloading of an interrupt list may stop the platform from working correctly. Modifying interrupt level will not necessarily improve the operation of a game. If you feel you need to modify the priority of interrupts please contact technical support for advice on alternative solutions.

Each interrupt scheduler list must be large enough to accommodate:

  • All of the interrupt handlers installed by the device drivers specified.
  • Any additional interrupt handlers installed by the user application.

InstallIntFnc() adds a pointer to an interrupt handler function fnc, to the end of the specified interrupt scheduler list fnc_lst.

The zeroed entries in each of the above lists are place holders for pointers to interrupt service routines. The number of entries in a list must be greater than or equal to the number of interrupts plus 2. The last entry must be EOF_FUNCTIONS.

The order of execution for handler functions is the same as the order of installation.

Installing User Defined Interrupt Functions

It is recommended that user defined interrupt functions are only installed in the following interrupt lists:

  • Int10msLst - 10ms periodic interrupt list.
  • Int250msLst - 250ms periodic interrupt list.

Note: Adding user defined interrupt functions to other interrupt lists (for example the video interrupt list) may result in undetermined behaviour in drivers that use the given interrupt.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Standard Peripherals Module

This module contains drivers that allow the game developer to control devices that are peripheral to the Pluto 8 control board but are commonly used in game development.

Peripherals Module Components

Component | Description
E2ROM Driver | The E2ROM driver module provides functions to read from and write data to the EEPROM device.
Stepper Motor Driver | The Stepper Motor driver provides a common API to control specific stepper motors.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 E2ROM Driver

E2ROM Driver

The Pluto 8 E2ROM driver provides the functions to read from and write data to an E2ROM device fitted to socket U33. The driver uses the services of the Pluto 8 I2C driver.

API Functions

The following API functions are provided by this module:

Function | Description
ReadE2Rom | Read n bytes of data from a given offest in an E2ROM device.
WriteE2Rom | Write n bytes of data to a given offest in an E2ROM device.

See Also

  • E2ROM Driver Defined Values
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 E2ROM Read

E2ROM Driver

ReadE2Rom

BYTE ReadE2Rom(WORD offset, ULONG numbytes, BYTE *dst)

Description

Read n bytes from the E2Rom device at the given offset. This is a blocking function that uses the repeated start read function from the I2C driver.

Parameters

Parameter | Description
offset | Internal offset in the E2ROM device.
numbytes | Number of bytes to read.
dst | Destination buffer.

Return Value

Returns SUCCESS if the read operation was successful.
Returns E2_BUS_BUSY if the I2C bus is already in use.
Returns E2_OUT_OF_BOUNDS if a read out of the memory range was attempted.
Returns E2_READ_FAILED ifthe read operation was unsuccessful.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 E2ROM Write

E2ROM Driver

WriteE2Rom

BYTE WriteE2Rom(const BYTE * src, WORD numbytes, WORD offset)

Description

Write n bytes to the E2Rom device at the given offset. This is a blocking function that uses the write function from the I2C driver

Parameters

Parameter | Description
src | Source buffer.
numbytes | Number of bytes to write.
offset | Internal offset in E2ROM device.

Return Value

Returns SUCCESS if the write operation was successful.
Returns E2_BUS_BUSY if the I2C bus is already in use.
Returns E2_OUT_OF_BOUNDS if a write out of the memory range was attempted.
Returns E2_WRITE_FAILED if the write operation was unsuccessful.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 E2ROM Driver Values

E2ROM Driver Defined Values

The following values are defined for use with the E2ROM driver:

E2ROM Defined Return Codes

Label | Meaning
E2_BUS_BUSY | The I2C bus is busy so the requested operation could not be started.
E2_OUT_OF_BOUNDS | A read or write operation was attempted on memory outside the bounds of the device.
E2_READ_FAILED | A read operation failed due to an E2ROM device error.
E2_WRITE_FAILED | A write operation failed due to an E2ROM device error.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

This module contains generic wrapper functions which call the appropriate functions from the given stepper driver.

API Functions

The following API functions are associated with this module:

Function | Description
GetNofMotors | Gets the number of stepper motors controlled by the given stepper motor device driver
InitialiseStepMotors | Initialises all the stepper motors controlled by the given device driver
StepMotorsIdle | Tests the status of all motors controlled by the device
DetectStepMotorOptos | Returns a 32 bit integer with each bit representing the status of each motor
SpinStepMotorsToTab | Spins all motors controlled by the device to their reference positions
SpinStepMotor | The motor is set up to spin the given distance
StopStepMotor | Brings the motor to rest on the first possible motor position
GetStepMotorPosn | Returns the current motor position
StepMotorSpinning | Tests the status of the motor
GetStepMotorTabsMissed | Gets the number of times the motor has passed through the reference position
GetStepMotorPosnCorrected | Gets the number of times the motors internal position variable has been corrected
ClearStepMotorErrors | Clears the internal position detection variables

See Also

  • Stepper Configuration Data
  • Stepping Motor Profiles
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

GetNofMotors

WORD GetNofMotors(const DEVICE* dev)

Description

Get the number of stepper motors controlled by the given stepper motor device driver.

Parameters

Parameter | Description
dev | Address of the stepper device

Return Value

Returns the number of stepping motors controlled by the given device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

InitialiseStepMotors

void InitialiseStepMotors(const DEVICE* dev)

Description

Initialise all the stepper motors controlled by the given device driver. Spin all motors to the reference position and detect missing or faulty motors/position sensors. If errors are detected the system shuts down and calls the error handler.

Parameters

Parameter | Description
dev | Address of the stepper device

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

StepMotorsIdle

BYTE StepMotorsIdle(const DEVICE* dev);

Description

Test the status of all motors controlled by the device and return TRUE if they are all idle.

Parameters

Parameter | Description
dev | Address of the stepper device

Return Value

Return TRUE if all motors are idle.
Return FALSE if any motor is spinning.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

GetStepMotorPosn

WORD GetStepMotorPosn(const DEVICE* dev, WORD motidx)

Description

Return the current motor position. The relationship between motor position and physical motor steps is contained in the motor type structure.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies which motor to get the position of. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

Returns the current motor position in the range 0 to N-1 (where N is the number of motor position in a complete revolution).

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

SpinStepMotorsToTab

void SpinStepMotorsToTab(const DEVICE* dev, WORD rampidx)

Description

Spin all motors controlled by the device to their reference positions.

Parameters

Parameter | Description
dev | Address of the stepper device
rampidx | The index to the ramp table to use. The ramp table specifies how the motor is controlled and the delays between each step. This information is found in the reel type structure

Return Value

None.

Remarks

Refer to Stepping Motor Profiles for a description of the reel type structure.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

SpinStepMotor

void SpinStepMotor(const DEVICE* dev, WORD motidx, WORD dist, WORD rampidx)

Description

The motor is set up to spin the given distance. Control returns from the function immediately and the reel spins and stops in its own time. If the motor is not in the idle state when this function is called it first waits for the motor to enter the idle state and then starts the next spin and returns.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor to spin. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c
dist | The distance to spin the motor. The distance is in motor positions not physical motor steps. The relationship between motor position and physical motor steps is contained in the motor type structure. Negative value will cause the motor to spin in reverse
rampidx | The index to the ramp table to use. The ramp table specifies how the motor is controlled and the delays between each step. This information is found in the reel type structure

Return Value

None.

Remarks

Refer to stepping motor profiles for a description of the reel type structure.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

StopStepMotor

void StopStepMotor(const DEVICE* dev,WORD motidx)

Description

Bring the motor to rest on the first possible motor position.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor to stop. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

None.

Remarks

For this function to work the motor must be spinning with one of the 'skill' control ramps. The spin must be given a non-zero distance which translates to more physical steps than the 'ramp up' phase of the control ramp. Having reached full speed the motor will spin until it is stopped using this function.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

StepMotorSpinning

BYTE StepMotorSpinning(const DEVICE* dev, WORD motidx)

Description

Test the status of the motor and return TRUE if the motor is spinning. The motor will leave the spinning state some time before entering the idle state. This function should be used to synchronise events with the motor stopping.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor to test. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

Returns TRUE if the motor is spinning
Return FALSE if the motor is not spinning

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

GetStepMotorTabsMissed

WORD GetStepMotorTabsMissed(const DEVICE* dev, WORD motidx)

Description

Get the number of times the motor has passed through the reference position without the position sensor being read as active. The count is kept internally and cleared by ClearStepMotorErrors().

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor to test. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

Returns the number of times the position sensor has been expected but not detected.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

GetStepMotorPosnCorrected

WORD GetStepMotorPosnCorrected(const DEVICE* dev, WORD motidx)

Description

Get the number of times the motors internal position variable has been corrected as a result of the position sensor being read as active when the position variable has not shown the reference position. The count is kept internally and cleared by ClearStepMotorErrors().

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor to test. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

Returns the number of times that motor position has been corrected.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

ClearStepMotorErrors

void ClearStepMotorErrors(const DEVICE* dev, WORD motidx)

Description

Clear the internal position detection variables.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor whose errors are to be cleared. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

None.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Configuration Data

The following data related to the Stepper Device Driver is user configurable and is contained in the config.c file at game level.

For each reel that the game application uses the following data must be set:

/* Reel 1 */
/* clear stepper variables */

STEPPERVARS reel1_ram =
{
    0,0,		/* Set position/index */
    0,		/* Direction */
    0,0,		/* Pattern table/index */
    0,		/* Vector table */
    0,0,0,		/* Delay table index timer */
    0,0,		/* Pix mask/opto count */
    0,0,		/* Spin/enable flags */
    0,0		/* Pos correction/tab missed */
};

STEPPERZVARS reel1_ram2;

/* set the inputs and outputs */
const REEL_ADDR reel1_addr =
{
    REEL1_OPS,
    REEL1_IP
};

/* configure the reel – in this case using the RM161680 ramp tables */
const STEPPER reel1 =
{
    &reel1_addr,
    &RM161680,
    &reel1_ram,
    &reel1_ram2,
    0
};

Once all of the reels have been configured they must be a added to the stepper list. In the example code below four reel steppers were previously defined and are used to create the stepper list.

/* create a list of all of the stepper devices */
const	STEPPER* const	stepperlist[]=
{
    &reel1,
    &reel2,
    &reel3,
    &reel4,
    EOF_STEPPERS
};

Each member of the stepper list is then configured:

/* configure the steppers in the list */
const	STEPCFG StepperCfg=
{
    stepperlist,
    5,	/* No. of steps to wake up steppers */
    50,	/* delay between steps */
    50	/* opto delay */
};
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepping Motor Profiles

Overview

The generic stepper motor driver will typically be used to control reels and can handle many different types of reel. There is no limit in the software to the number of reels or the number of different types of reel that can be controlled simultaneously.

All the information defining a particular reel type is contained in a REEL_TYPE structure. An example of a reel structure is in the Custom Peripheral driver library and it is suggested that any new reel types defined be added to this library. (libcustomperipherals.a)

Defining a New Reel Type

The type declaration for the REEL_TYPE structure in stepper.h should be used when defining a new type structure.

typedef	struct reel_type
{
    WORD		steps_per_rev;
    WORD		steps_per_symbol;
    BYTE		min_opto;
    BYTE		tolerance;
    BYTE		revpos;
    const RAMP	*ramps[MAX_RAMPS];
} REEL_TYPE;

steps_per_rev
The number of stepper motor steps required to move the reel one complete revolution.

steps_per_symbol
The number of stepper motor steps required to move the reel one whole reel symbol.

min_opto
The number of times the position sensor must be seen during one step to activate the position correction software.

tolerance
This is the size of the position error in motor steps, which is allowable without activating the position correction software.

revpos
This should be set TRUE if the position detection software is to be active whilst the reel is spinning backwards. This position correction software is always active whilst the reel is spinning forwards.

ramps
This is a list of pointers to RAMP structures. A RAMP structure contains all the information required to define a particular type of reel movement. There are two ramps for system use, 'system' and 'initialisation' ramps, In addition there are ramps for spinning at 69RPM, 78RPM, 89RPM, 96RPM, and 104RPM.There is provision for three different nudge ramps and three different 'skill stop' ramps.

The RAMP Structure

The RAMP structure allows the stepper driver to be very flexible in the way it can control the reels. A RAMP structure can be defined to make a reel do almost anything.

typedef	struct ramp
{
    const WORD	*pattern_tbl;
    WORD		pixmask;
    void		(*const *vector_tbl)(const void*);
    const WORD	*delay_lst;
} RAMP;

pattern_tbl
The pattern table defines the energising sequence of the four phases of the stepper motor. To move one step the reel increments its index into this table and writes the new pattern out to the motor coils.

pixmask
Each time the pattern table index is incremented (or decremented for reverse spin) it is logically ANDed with this value to wrap it around at the end of the table.

vector_tbl
This is a list of function pointers to the functions, which will be called by the stepper driver in order to control the reel. The standard vector tables provided will suffice for most situations but for any special requirements a new vector table may be defined and new functions written.

delay_lst
A list of delays (in milliseconds) required to time the various steps. The vector functions will access these delays and the meaning of any particular delay is dependant on the vector functions used and the number of steps controlled by each vector function. For the standard vector functions (RampUp, Run, and RampDown) the first number indicates the number of steps to be controlled by that vector function and that is followed by the a delay for each step. It is left to the vector functions to manipulate the index into this delay list.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Custom Peripherals

Custom Peripherals Library

This library contains drivers that allow the game developer to control devices that are peripheral to the Pluto 8 control board but are commonly used in game development. This module has been provided to give developers the flexibility to build their own peripheral drivers into the Pluto 8 library code. All drivers are supplied with source code that can be used as a template to develop custom drivers.

Custom Peripherals Library Components

Component | Description
Starpoint SEC meter driver | SPI software driver for a Starpoint SEC meter
RM161680 Reel Profile | Ramp table prifle for the Starpoint RM161680 reel.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The Starpoint SEC meter is an electronic counter designed as a modern replacement for traditional mechanical counters found in gaming machines. The SEC features a seven digit seven segment LC Display. The meter holds 30 individual counters with an associated seven character text string, these are contained in EEPROM and so are non-volatile. Either one counter value or one counter text may be shown on the display at any time.

The SEC driver is an example driver demonstrating the use of the Software SPI driver for providing high level control of an SPI peripheral.

API Functions

The following API functions are provided by this module and have been implemented by Heber:

Function | Description
SecRequestCounterValue | Get the current value of one of the counters in the SEC.
SecSetCounterText | Set the text string associated with a certain counter in the SEC.
SecShowText | Show a text string on the SEC display.
SecShowCounterValue | Show the counter value of a certain counter on the SEC display.
SecShowCounterText | Show the text string associated with a certain counter on the SEC display.
SecCounterIncrementSmall | Increment a certain counter in the SEC from 1-15.
SecCounterIncrementMedium | Increment a certain counter in the SEC from 1-255.
SecCounterIncrementLarge | Increment a certain counter in the SEC from 1-65535.
SecSetNumberOfCounters | Set the number of counters to show when cycling the display on the SEC.
SecCycleCounterDisplay | Cycle through the text and value for each counter specified on the SEC.
SecStopCycle | Halt the cycling activity in the SEC.

The following API functions are suggested by Heber in order to implement the remaining commands available in the SEC, they may be completed by customers using the SEC meter who require the commands:

Function | Description
SecSelfTest | Have the SEC perform a self test and send back the results.
SecShowBitPattern | Write a bit pattern to the SEC display.
SecSetMarketType | Set the market type on the SEC.
SecRequestFingerprint | Get the binary fingerprint from the SEC.
SecRequestLastCommandId | Get the ID of the last command sent to the SEC.
SecRequestStatus | Get the status of the SEC.
SecRequestMarketType | Get the market type from the SEC.
SecRequestLastError | Get the last error code generated by the SEC.
SecRequestVersion | Get the software version on the SEC.

See Also

  • SEC function return codes
© HEBER LTD. 2005. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecRequestCounterValue

BYTE SecRequestCounterValue(UBYTE counternumber, ULONG *counterval)

Description

Get the current value of one of the counters in the SEC. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter in the SEC to get the value from (0-30).
counterval | Pointer to a LONG in which the value returned from the SEC is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecSetCounterText

BYTE SecSetCounterText(UBYTE counternumber, BYTE * countertext)

Description

Set the text string associated with a certain counter in the SEC. The text is stored on EEPROM within the SEC and so is non-volatile. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter in the SEC to which the associated text is set (0-30).
countertext | A Pointer to the text string to set in the SEC.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecShowText

BYTE SecShowText(BYTE * textstring)

Description

Show a text string on the SEC display. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
countertext | A Pointer to the text string to display on the SEC.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecShowCounterValue

BYTE SecShowCounterValue(UBYTE counternumber)

Description

Show the value for a specified counter on the SEC display. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter to display the value of (0-30).

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecShowCounterText

BYTE SecShowCounterText(UBYTE counternumber)

Description

Show the text string associated with a specified counter on the SEC display. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter of which to display the associated text string (0-30).

Return Value

Returns SUCCESS if if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecCounterIncrementSmall

BYTE SecCounterIncrementSmall(UBYTE counternumber, UBYTE data)

Description

Increment the specified counter by a value in the range 1 to 15. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter to increment (0-30).
data | The value to increment the counter by (1-15).

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecCounterIncrementMedium

BYTE SecCounterIncrementMedium(UBYTE counternumber, UBYTE data)

Description

Increment the specified counter by a value in the range 1 to 255. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter to increment (0-30).
data | The value to increment the counter by (1-255).

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecCounterIncrementLarge

BYTE SecCounterIncrementLarge(UBYTE counternumber, WORD data)

Description

Increment the specified counter by a value in the range 1 to 65535. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
counternumber | The number of the counter to increment (0-30).
data | The value to increment the counter by (1-65535).

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH ifthe message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecSetNumberOfCounters

BYTE SecSetNumberOfCounters(UBYTE number)

Description

Set the number of counters to show when cycling the display on the SEC when SecCycleCounterDisplay is called. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
number | The number of counters in the SEC to cycle through (0-30).

Return Value

Returns SUCCESS if if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecCycleCounterDisplay

BYTE SecCycleCounterDisplay(void)

Description

The SEC will display the counter 0 text for 1 second, then the counter value for 3 seconds. This will repeat 3 times, then the same is repeated for subsequent counters up to the number set by SecSetNumberOfCounters. This is a blocking function that uses the services of the software SPI driver.

Parameters

None.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK ifthe message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

SecStopCycle

BYTE SecStopCycle(void)

Description

Halt the cycling activity in the SEC, it will then show the value of counter 0.

Parameters

None.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecSelfTest

BYTE SecSelfTest(UBYTE *result)

Description

Have the SEC perform a limited self test, if it fails an error code is placed in result and the function returns SEC_NACK. See the SEC manual for these error codes. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
result | A Pointer into which the result is placed if the self test fails.

Return Value

Returns SUCCESS if if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecShowBitPattern

BYTE SecShowBitPattern(UBYTE *patternstring)

Description

Write a bit pattern to the display. Each BYTE represents the pattern for each of the 7 characters on the SEC display. This control of the display of each segment is to allow patterns and animations to be displayed. This is a blocking function that uses the services of the software SPI driver.

Parameters

Parameter | Description
patternstring | A Pointer to the string of bytes containing the bit patterns. The first byte in the string is the left digit on the display, the last byte is the right digit.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecSetMarketType

BYTE SecSetMarketType(UBYTE markettype)

Description

Set the market type of the SEC meter. The market type can be used as an identifier of a particular game so that if a SEC must be replaced, the market type can be read by the game code. If the market type is not that expected, counter values and texts can be altered and the market type set. The SEC does not make any use of the value, but will store it in EEPROM so it is non-volatile.

Parameters

Parameter | Description
markettype | The market type value to be set in the SEC.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecRequestFingerprint

BYTE SecRequestFingerprint(LONG *fingerprint)

Description

Get the fingerprint of the SEC meter. The fingerprint is a 4 byte value which is individual to each SEC meter. The SEC fingerprint can be used by game code to check if a counter has been swapped in order to prevent counter fraud.

Parameters

Parameter | Description
fingerprint | A pointer to a LONG into which the fingerprint is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecRequestLastCommandId

BYTE SecRequestLastCommandId(UBYTE *commandid)

Description

Get the ID of the last command sent to the SEC.

Parameters

Parameter | Description
commandid | A pointer into which the last command ID sent to the SEC is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecRequestStatus

BYTE SecRequestStatus(UBYTE *status)

Description

Get the current status of the SEC. A byte is returned, for the meanings of the individual bits in this byte, see this command in the SEC manual.

Parameters

Parameter | Description
status | A pointer into which the current status byte from the SEC is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecRequestMarketType

BYTE SecRequestMarketType(UBYTE *markettype)

Description

Get the market type currently set in the SEC. For details of the use of the market type value see SecSetMarketType.

Parameters

Parameter | Description
markettype | A pointer into which the current market type value from the SEC is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH ifthe message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecRequestLastError

BYTE SecRequestLastError(UBYTE *lasterror)

Description

Get the last error code generated by the SEC. A byte is returned, for the meanings of the individual bits in this byte, see this command in the SEC manual.

Parameters

Parameter | Description
lasterror | A pointer into which the last error code generated by the SEC is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if the data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver

Starpoint SEC Meter example driver

The following is the API description suggested by Heber in order to implement this SEC command. A stub matching the following has been placed in the seccounter.c driver file in the customer peripherals library in order to implement this function.

SecRequestVersion

BYTE SecRequestVersion(ULONG *version)

Description

Get the software version which the SEC is programmed with. This can be used to work around possible errors in known versions of the SEC software. The SEC returns three bytes, which are placed in the three least significant bytes of version.

Parameters

Parameter | Description
version | A pointer into which the software version of the SEC is placed.

Return Value

Returns SUCCESS if the operation was successful
Returns SEC_BUSY if the SPI bus is busy with another transaction, so the command wasn't sent.
Returns SEC_RX_CHKSUM_ERROR if the checksum of the message received back from the SEC is invalid.
Returns SEC_NACK if the message type received back from the SEC is a NACK, indicating the command sent to it was not performed successfully.
Returns SEC_UNEXPECTED_MESSAGE if the message type received back from the SEC is not that expected in reply to the command sent to it.
Returns SEC_MESSAGE_MISMATCH if the message ID of the reply from the SEC doesn't match that of the message sent to it, indicating a message was missed.
Returns SEC_INVALID_RX_DATA_LENGTH if data length byte in the message received back from the SEC is not that expected in reply to the command sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 SEC Meter Driver Return Codes

Starpoint SEC Meter example driver Return Codes

The following return codes are returned by the SEC Meter example driver API functions.

Return Code | Value | Description
SUCCESS | 0 | The function executed successfully
SEC_BUSY | -2 | The software SPI driver is currently performing a previous transaction.
SEC_RX_CHKSUM_ERROR | -3 | The checksum of the message received back from the SEC is incorrect.
SEC_NACK | -4 | A NACK message was received backfrom the SEC.
SEC_UNEXPECTED_MESSAGE | -5 | The type of the message received back from the SEC was not that expected for the message sent and was not a NACK.
SEC_MESSAGE_MISMATCH | -6 | The message ID field of the message received back from the SEC doesn't match up with the message ID of the message sent to it, indicating that the SEC has missed a message.
SEC_INVALID_RX_DATA_LENGTH | -7 | The value of the data length field in the message received back from the SEC was not that expected for the message sent to it.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Custom Peripherals

RM161680 Reel Profile

This module contains the reel profile for a Starpoint RM161680 reel. The profile is used in the reel configuration in the file config.c at project level. The stepper driver uses the profile data to control the reels.

The profile contains the following data:

Pattern Tables

Pattern tables are specified to send to the stepper motors to perform full and half steps.

Vector Tables

Vector tables of functions are provided for operations such as spinning, nudging and wobbling reels.

Ramp Tables

Ramp and ramp delay tables are provided for reel operation.

Reel Type Definition

A REEL_TYPE structure is populated with the reel specific data.

See Also

  • Stepper Configuration Data
  • Stepping Motor Profiles
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Interface

Standard Interface Library

This module provides interface drivers which use the services of lower level device drivers.

Standard Interface Library Components

Component | Description
FAT 32 Driver | Provides an interface to a FAT32 file system
Heber Image File (HIF) loader | Provides the functionality to load HIF files
GIF Image File loader | Provides the functionality to load animated GIF files
Video Reel Driver | Provides a framework for creating video reels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

The FAT32 interface driver allows file and directory orientated access to the data on ATA devices including hard disks and CompactFlash cards. The functions in this driver make use of the ATA driver in the hardware library to read and write the raw data on the disk and interpret it as files and directories.

API Functions

The following API functions are provided by this driver:

Partition/Volume Orientated Functions

Function | Description
MountFAT32 | Mount the FAT32 partition on the specified ATA device.
FAT32GetStatus | Check whether the FAT32 partition on the specified ATA device has been mounted or not.
FAT32VolumeLabel | Return a pointer to the volume label text string of the FAT32 partition on the specified ATA device.
FAT32PartitionSize | Return the partition size in MB of the FAT32 partition on the specified ATA device.
FAT32LockoutStatus | Check if any FAT32 functions are running which access the ATA bus.

Directory Orientated Functions

Function | Description
FAT32GetDir | Return a pointer to the current directory text string.
FAT32ChangeDir | Change to the directory specified.
FAT32NextDirRecord | Return a pointer to the next directory record structure in the current directory.
FAT32DirEntryAttrib | Return the directory attribute string of the specified directory entry.
FAT32DirEntryAlias | Return the short file or directory name (8.3 format) of the specified directory entry.
FAT32DirEntryFilesize | Return the file/directory size in bytes of the specified directory entry.
FAT32DirEntryLongfilename | Return the long file or directory name of the specified directory entry.

File Orientated Functions

Function | Description
FAT32FileOpen | Initialise a file pointer using the specified file path string.
FAT32FileGetChar | Read a BYTE from an opened file.
FAT32FileGetSectors | Read the specified number of sectors of data from an opened file.
FAT32FilePutSector | Write a sector of data to an opened file.
FAT32FileLoad | Load a whole file to the specified memory address.
FAT32FileRewind | Set the file position of an open file descriptor back to the start.
FAT32FileSeekSector | Set the file position of an open file descriptor to the specified sector.
FAT32FileCurrentSector | Return the current offset from the start of the file in sectors of the specified file descriptor.
FAT32GetFileSize | Return the size in bytes of the file opened with the specified file descriptor.
FAT32FileClose | Close an opened file descriptor.

See Also

  • FAT32 API return codes
  • FAT32 API defined values
  • FAT32 filesystem structure for ATA configuration
  • FAT32 mount error handling
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

MountFAT32

BYTE MountFAT32(const DEVICE* atadevice)

Description

This function mounts the first FAT32 partition found on the specified ATA device. The partition must be mounted with this function before any of the other FAT32 API functions will operate correctly for the ATA device specified.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_MOUNT_WARNING if non fatal errors were encountered while inspecting the file allocation table structures, but the filesystem was mounted. See FAT32 mount error handling in order to display the warnings
Returns FAT32_MOUNT_ERROR if fatal errors were encountered while inspecting the file allocation table structures, and the filesystem was not mounted. See FAT32 mount error handling in order to display the errors
Returns FAT32_DISK_ERROR if there was a problem reading the disk in the lower level ATA driver
Note that FAT32_MOUNT_WARNING and FAT32_MOUNT_ERROR may be ORed together to signify that both errors and warnings were encountered, and the return value checked using the & operator

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32GetStatus

UBYTE FAT32GetStatus(const DEVICE* atadevice)

Description

This function returns the mount status of the filesystem on the specified ATA device, and may be used to check if the filesystem is currently mounted or not.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)

Return Value

Returns MOUNTED if the filesystem is currently mounted
Returns UNMOUNTED if the filesystem is currently not mounted, either the MountFAT32 function has not been called on the appropriate ATA device, or it was not successful

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32VolumeLabel

UBYTE *FAT32VolumeLabel(const DEVICE* atadevice)

Description

This function returns a pointer to the volume label text string of the FAT32 filesystem mounted on the specified ATA device.
The value is held within the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before this one to ensure the value is correct.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)

Return Value

A pointer to a UBYTE which may be treated as a string containing the volume label of the FAT32 partition mounted on the ATA device

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32PartitionSize

ULONG FAT32PartitionSize(const DEVICE* atadevice)

Description

This function returns a ULONG specifying the size in megabytes of the filesystem mounted on the specified ATA device. The value is held within the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before this one to ensure the value is correct.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)

Return Value

A ULONG containing the size in megabytes of the FAT32 partition mounted on the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32LockoutStatus

BYTE FAT32LockoutStatus()

Description

This function returns the state of a flag which is set during the execution of any FAT32 function which accesses the ATA bus (E.G. reading sectors, selecting the master or slave device etc.)
The FAT32 API functions are not designed to execute at the same time. For example a collection of sectors is being read from a disk by function A, and function B interrupts A then changes the logical block address with new ATA commands. When function A resumes it will not continue to read sectors from the disk as it was intended to, because the ATA device won't remember the previous commands written to it by A before the interruption.

In order to prevent such a scenario, if game code ever needs to access FAT32 API functions in any interrupt service routines, this function should be called to check no disk accesses on the ATA bus are currently occurring.

Parameters

None.

Return Value

Returns TRUE if another FAT32 function is currently accessing the ATA bus and it is not safe to call another
Returns FALSE if no other FAT32 functions are running, so it is safe to call one

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32GetDir

UBYTE *FAT32GetDir(const DEVICE* atadevice)

Description

This function returns a pointer to the directory name text string of the current directory that the filesystem descriptor is pointed to.
The current directory is held within the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before this one to ensure the value is correct.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)

Return Value

A pointer to a UBYTE which may be treated as a string containing the current directory name of the FAT32 partition mounted on the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32ChangeDir

BYTE FAT32ChangeDir(const DEVICE* atadevice, BYTE *dirname)

Description

This function changes the current directory pointed to by the filesystem descriptor to the path specified.
The path is held within the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before this one to ensure the directory passed is found and changed to correctly.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
dirname | A pointer to a string containing the directory name to change to. Entries in the current directory of the filesystem are compared with this name for a match, so the string should contain only the directory name not the full path (E.G. "music", not "\audio\music\"). Also supported are "\\" to change to the root directory of the filesystem, ".." to go up a directory, and "." to reset the directory record pointer back to the first record of the current directory.

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_FILE_NOT_FOUND if the specified directory was not found in the current directory and no action was taken

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32NextDirRecord

BYTE FAT32NextDirRecord(const DEVICE* atadevice, DIR_ENTRY* dir_entry)

Description

This function will initialise the dir_entry structure passed to it with the values of the next directory record in the current directory, and incremement the directory record index held within the filesystem structure of the ATA device. Despite the naming, a directory record may be a file or directory residing in the current directory of the filesystem. This function can therefore be used to step through all the files and directories in the current directory.
The current directory and directory record index is held within the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before this one to ensure the function performs correctly.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
dir_entry | A pointer to a DIR_ENTRY structure which must be declared outside of the function to ensure memory is reserved for it. The structure is then populated by the function.

Return Value

Returns FAT32_OK if he operation was performed succesfully
Returns FAT32_EODIR_RECORDS if there are no more entries in the current directory, the dir_entry parameter ill not contain valid values

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32DirEntryAttrib

UBYTE *FAT32DirEntryAttrib(const DEVICE* atadevice, DIR_ENTRY* dir_entry)

Description

This function returns a pointer to the attribute text string of the DIR_ENTRY specified.
The attribute string is in the format "<dir> rhs" If the directory entry is a directory, then the first five characters of the attribute string will be "<dir> otherwise they will be spaces. If the entry is read only then the seventh character will be "r" otherwise it will be a space. If the entry is hidden then the eighth character will be "h" otherwise it will be a space. If the entry is a system file or directory then the nineth character will be "s" otherwise it will be a space.

The attribute string is held within the dir_entry structure, which is populated by the FAT32NextDirRecord function, so that function must be called before this one to ensure the value is correct. The directory records are accessed by FAT32NextDirRecord using the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before FAT32NextDirRecord to ensure the directory records are correct.

Parameters

Parameter | Description
dir_entry | A pointer to a DIR_ENTRY structure which must be pre-initialised by FAT32NextDirRecord.

Return Value

A pointer to a UBYTE which may be treated as a string containing the attribute string of the directory entry

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32DirEntryAlias

UBYTE *FAT32DirEntryAlias(DIR_ENTRY* dir_entry)

Description

This function returns a pointer to the alias text string of the DIR_ENTRY specified. This is the short file name in 8.3 format which files with longer names appear with in older Microsoft operating systems such as MS-DOS 6.22.
The alias strind is held within the dir_entry structure, which is populated by the FAT32NextDirRecord function, so that function must be called before this one to ensure the value is correct. The directory records are accessed by FAT32NextDirRecord using the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before FAT32NextDirRecord to ensure the directory records are correct.

Parameters

Parameter | Description
dir_entry | A pointer to a DIR_ENTRY structure which must be pre-initialised by FAT32NextDirRecord.

Return Value

A pointer to a UBYTE which may be treated as a string containing the alias/short file name string of the directory entry

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32DirEntryFilesize

ULONG FAT32DirEntryFilesize(DIR_ENTRY* dir_entry)

Description

This function returns the size in bytes of the file or directory represented by the directory entry.
The size value is held within the dir_entry structure, which is populated by the FAT32NextDirRecord function, so that function must be called before this one to ensure the value is correct. The directory records are accessed by FAT32NextDirRecord using the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before FAT32NextDirRecord to ensure the directory records are correct.

Parameters

Parameter | Description
dir_entry | A pointer to a DIR_ENTRY structure which must be pre-initialised by FAT32NextDirRecord.

Return Value

A ULONG containing the size in bytes of the file or directory represented by dir_entry

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32DirEntryLongfilename

UBYTE *FAT32DirEntryLongfilename(DIR_ENTRY* dir_entry)

Description

This function returns a pointer to the long filename of the DIR_ENTRY specified.

The file name is held within the dir_entry structure, which is populated by the FAT32NextDirRecord function, so that function must be called before this one to ensure the value is correct. The directory records are accessed by FAT32NextDirRecord using the filesystem structure of the ATA device, which is populated by the MountFAT32 function, so that function must be called before FAT32NextDirRecord to ensure the directory records are correct.

Parameters

Parameter | Description
dir_entry | A pointer to a DIR_ENTRY structure which must be pre-initialised by FAT32NextDirRecord.

Return Value

A pointer to a UBYTE which may be treated as a string containing the long file name string of the directory entry

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileOpen

BYTE FAT32FileOpen(const DEVICE* atadevice, BYTE *filename, FILE_DESCRIPTOR *fd, UBYTE mode)

Description

This function will open the file specified by the filename string and initialise the FILE_DESCRIPTOR structure passed to it for use in the other file orientated FAT32 functions.
The ability to open files is dependent on the data in the filesystem structure of the ATA device being initialised correctly, which is accompliahed by the MountFAT32 function, so that function must be called before this one to ensure correct behaviour.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
filename | A pointer to a string containing the file name to open. Entries in the current directory of the filesystem are compared with this name for a match, so the string should contain only the file name not the full path (E.G. "sample1.hsf", not "\audio\effects\sample1.hsf").
fd | A pointer to a FILE_DESCRIPTOR structure which must be declared outside of the function to ensure memory is reserved for it. The structure is then populated by the function.
mode | A flag specifying the level of access to the file using this file descriptor, the value should be one of READ_ONLY, OVERWRITE_ONLY or READ_OVERWRITE, for read only, write only or read and write access, respectively.

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_FILE_NOT_FOUND if the specified file was not found in the current directory and no action was taken

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileGetChar

UWORD FAT32FileGetChar(const DEVICE* atadevice, FILE_DESCRIPTOR *fd)

Description

This function returns a character from the file opened previously with the FILE_DESCRIPTOR fd using FAT32FileOpen. The file pointer held in the FILE_DESCRIPTOR structure is incremented by one BYTE. The return value is a UWORD to allow for error return codes outside of the BYTE range.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to read from using FAT32FileOpen.

Return Value

The next char from the file is returned on success (this will be in the range 0-255)
Returns FAT32_EOF if the end of the file has been reached
Returns FAT32_FILE_NOT_OPEN if the file descriptor has not been used to open a file yet using FAT32FileOpen
Returns FAT32_DISK_ERROR if there was a problem reading the disk in the lower level ATA driver.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileGetSectors

ULONG FAT32FileGetSectors(const DEVICE* atadevice, FILE_DESCRIPTOR *fd, UWORD *mem, ULONG nsectors, ULONG *sectorsloaded)

Description

This function reads the number of sectors specified by nsectors from the file opened previously with the FILE_DESCRIPTOR fd using FAT32FileOpen. The file position pointer held in the FILE_DESCRIPTOR structure is incremented by nsectors*512 bytes (512 bytes per sector). The data read from the file is placed at the address specified by mem.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to read from using FAT32FileOpen.
mem | A pointer to some memory which must be reserved before calling the function and be large enough to hold the number of sectors to be read (E.G. an array). The data is placed at this address.
nsectors | The number of sectors worth of data to read (multiples of 512 bytes).
sectorsloaded | A pointer to a ULONG which upon returning contains the number of sectors worth of data which was actually loaded.If this is lower than the number passed in by nsectors, the end of the file has been reached

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_FILE_NOT_OPEN if the file descriptor has not been used to open a file yet using FAT32FileOpen
Returns FAT32_DISK_ERROR if there was a problem reading the disk in the lower level ATA driver

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FilePutSector

BYTE FAT32FilePutSector(const DEVICE* atadevice, FILE_DESCRIPTOR *fd, UWORD *mem)

Description

This function wites a sector (512 bytes) of data from the address specified by mem to the file opened previously with the FILE_DESCRIPTOR fd using FAT32FileOpen. The file position pointer held within the FILE_DESCRIPTOR is moved forward by one sectors worth of bytes.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to write to using FAT32FileOpen.
mem | A pointer to the memory the sector of data to be written to the file.

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_FILE_NOT_OPEN if the file descriptor has not been used to open a file yet using FAT32FileOpen.
Returns FAT32_FILE_SECTOR_OUT_OF_RANGE if the sector offset in the file descriptor is beyond the last sector of the file.
Returns FAT32_FILE_READ_ONLY if the file descriptor was opened as read only, see the mode argument in FAT32FileOpen.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileLoad

BYTE FAT32FileLoad(const DEVICE* atadevice, FILE_DESCRIPTOR *fd, UWORD *mem)

Description

This function reads the entire file opened previously with the FILE_DESCRIPTOR fd using FAT32FileOpen. The file position pointer held in the FILE_DESCRIPTOR structure is then rewound back to the start of the file. The data read from the file is placed at the address specified by mem.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to read from using FAT32FileOpen.
mem | A pointer to some memory which must be reserved before calling the function and be large enough to hold the entire file. The data is placed at this address.

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_FILE_NOT_OPEN if the FILE_DESCRIPTOR has not been used to open a file yet using FAT32FileOpen
Returns FAT32_DISK_ERROR if there was a problem reading the disk in the lower level ATA driver

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileRewind

void FAT32FileRewind(FILE_DESCRIPTOR *fd)

Description

This function resets the reading/writing position of the FILE_DESCRIPTOR fd back to the beginning. The FILE_DESCRIPTOR should have been opened previously using FAT32FileOpen.

Parameters

Parameter | Description
fd | A pointer to a FILE_DESCRIPTOR structure which should have been initialised to the file to read from using FAT32FileOpen.

Return Value

None - because the function simply resets index values held within the FILE_DESCRIPTOR structure, there is no possibility of error and so no checking required.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileSeekSector

BYTE FAT32FileSeekSector(const DEVICE* atadevice, FILE_DESCRIPTOR *fd, ULONG sector_offset)

Description

This function sets the reading/writing position of the FILE_DESCRIPTOR fd to the sector number specified by sector_offset. The FILE_DESCRIPTOR must have been opened previously using FAT32FileOpen.

Parameters

Parameter | Description
atadevice | A pointer to the ATA device structure (E.G. ATA0Device for the master drive, ATA1Device for the slave)
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to write to using FAT32FileOpen.
sector_offset | The number of sectors from the beginning of the file to set the file position pointer of the FILE_DESCRIPTOR structure to.

Return Value

Returns FAT32_OK if the operation was performed succesfully
Returns FAT32_FILE_NOT_OPEN if the file descriptor has not been used to open a file yet using FAT32FileOpen
Returns FAT32_FILE_SECTOR_OUT_OF_RANGE if the sector_offset argument is beyond the last sector of the file

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileCurrentSector

ULONG FAT32FileCurrentSector(const DEVICE* atadevice, FILE_DESCRIPTOR *fd)

Description

This function returns the current reading/writing position of the FILE_DESCRIPTOR fd. The FILE_DESCRIPTOR must have been opened previously using FAT32FileOpen.

Parameters

Parameter | Description
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to read from using FAT32FileOpen.

Return Value

The current offset in sectors (multiples of 512 bytes) of the file position pointer in the FILE_DESCRIPTOR from the start of the file

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32GetFileSize

ULONG FAT32GetFileSize(FILE_DESCRIPTOR *fd)

Description

This function returns the size of the file opened with the FILE_DESCRIPTOR fd. The FILE_DESCRIPTOR must have been opened previously using FAT32FileOpen.

Parameters

Parameter | Description
fd | A pointer to a FILE_DESCRIPTOR structure which must have been initialised to the file to read from using FAT32FileOpen.

Return Value

The size in bytes of the file opened with the FILE_DESCRIPTOR fd

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver

FAT32FileClose

void FAT32FileClose(FILE_DESCRIPTOR *fd)

Description

This function closes the FILE_DESCRIPTOR fd. The FILE_DESCRIPTOR should have been opened previously using FAT32FileOpen.

Parameters

Parameter | Description
fd | A pointer to a FILE_DESCRIPTOR structure which should have been initialised to the file to read from using FAT32FileOpen.

Return Value

None - because the function simply resets index values held within the FILE_DESCRIPTOR structure, there is no possibility of error and so no checking required

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver Defined Return Codes

FAT32 Interface Driver Defined Return Codes

Label | Value | Meaning
FAT32_OK | 0 | The requested operation was performed successfully.
FAT32_MOUNT_WARNING | 1 | While mounting the filesystem non-fatal errors were found with the filesystem data structures on the disk. The filesystem was still mounted, and the warnings may be inspected via the error structure, see FAT32 mount error handling for more information.
FAT32_MOUNT_ERROR | 2 | While mounting the filesystem fatal errors were found with the filesystem data structures on the disk. The filesystem was not mounted, and the errors may be inspected via the error structure, see FAT32 mount error handling for more information. Note this return value may be ORed with FAT32_MOUNT_WARNING if both warnings and errors were found.
FAT32_FILE_NOT_FOUND | -1 | If the function called involves searching for a file or directory to open or change to, this value means the entry was not found in the currnt directory.
FAT32_EODIR_RECORDS | -2 | When fetching the next directory record in a directory this values means there are no more entries in the current directory.
FAT32_FILE_NOT_OPEN | -3 | When calling a function which uses a FILE_DESCRIPTOR structure, this value means the descriptor has not been opened yet using FAT32FileOpen.
FAT32_FILE_READ_ONLY | -4 | When calling a function which writes data back to a file using a FILE_DESCRIPTOR structure, this value means when the descriptor was opened using FAT32FileOpen the mode argument was not one allowing write access, - use OVERWRITE_ONLY or READ_OVERWRITE instead.
FAT32_FILE_SECTOR_OUT_OF_RANGE | -5 | When calling a function which reads or writes sectors of data at a time to a file using a FILE_DESCRIPTOR structure, this value means that the file position pointer in the file descriptor is beyond the end of the file.
FAT32_DISK_ERROR | -6 | When calling a function which causes the file system interface to access the ATA device which the file system resides on, this values means that a time out occured when accessing the ATA device.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Library

FAT32 Interface Driver Library Values

The following values have been defined for the FAT32 Driver:

Label | Value | Meaning
MOUNTED | 0 | The file system has been mounted.
UNMOUNTED | 1 | The file system has not been mounted

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 FAT32 Interface Driver

FAT32 Interface Driver Error Handling

FAT32 Interface Driver Error Structure

When the filesystem on an ATA device is mounted by MountFAT32 there are various possible errors that could occur in the Master Boot Record (MBR) and BIOS Parameter Block (BPB) structures on disk. To avoid filling the return code list for the whole API with values that only apply when mounting, these errors and warnings are held in an error structure within the FAT32FILESYSTEM structure held by the ATA device.

The FAT32 error structure is defined as follows:

typedef struct fat32error
{
    UBYTE ident[FAT32_ERROR_END];	/* individual test results*/
    UBYTE result;			/* overall result*/
} FAT32ERROR;

The ident variable is an array containing the individual test results when mounting the file system. Each element of the ident array is a possible source of an error. The result variable is the overall result of all the tests. The values assigned to each element in ident and to result are the same as those returned from the MountFAT32 function:

Label | Value | Meaning
FAT32_OK | 0 | The individual filesystem check or overall result had no errors or warnings.
FAT32_MOUNT_WARNING | 1 | The individual filesystem check or overall result had a non-fatal error in the relevant data structure on the disk. This means an unexpected value in the MBR or BPB.
FAT32_MOUNT_ERROR | 2 | The individual filesystem check or overall result had a fatal error in the relevant data structure on the disk. This means an invalid value in the MBR or BPB.

In the result variable FAT32_MOUNT_ERROR may be ORed with FAT32_MOUNT_WARNING meaning some elements in the ident array contain FAT32_MOUNT_ERROR and some contain FAT32_MOUNT_WARNING.

In order to inspect the values held in the ident array after mount is called the error structure may be accessed as follows:

    const ATACFG* 	cp;
    const ATAVARS*	vars;
    vars=(const ATAVARS*)ATA0Device->vars;
    cp = (const ATACFG*)vars->config;

    if(cp->filesystem->fat32error.ident[0] != FAT32_OK)
    {
        ...
    }

In order to establish what file system checks correspond to which elements of ident, the following values have been defined. They may be used as indexes to ident:

Label | Value | Meaning if set to FAT32_MOUNT_WARNING | Meaning if set to FAT32_MOUNT_ERROR
MBR_ERROR_NO_PARTITION | 0 | The MBR does not contain an active partition. | -
MBR_ERROR_SIGNATURE | 1 | - | The MBR does not contain a valid signature.
MBR_ERROR_FS_TYPE | 2 | - | The primary partition in the MBR is not of FAT32 type.
MBR_ERROR_END | 3 | This isn't actually an error itself, it simply signals the end of the MBR errors.
BPB_ERROR_JMP_BOOT | 4 | - | The JMP BOOT field in the BPB is not 0xEB or 0xE9.
BPB_ERROR_OEM_NAME | 5 | The OEM name fireld in the BPB does not begin with "MSDOS". | -
BPB_ERROR_BYTES_PER_SECTOR | 6 | The bytes per sector value in the BPB is not 512. | The bytes per sector value in the BPB is not one of 512, 1024, 2048 or 4096.
BPB_ERROR_SECTORS_PER_CLUSTER | 7 | - | The sectors per cluster value in the BPB is not one of 1, 2, 4, 8, 16, 32, 64 or 128.
BPB_ERROR_RESERVED_SECTORS | 8 | The reserved sectors value in the BPB is not 32. | The reserved sectors value in the BPB is 0.
BPB_ERROR_NUM_FATS | 9 | The number of FATs in the BPB is not 2. | The number of FATs in the BPB is 0.
BPB_ERROR_ROOT_ENTRIES16 | 10 | - | The number of boot entries in the BPB is not 0.
BPB_ERROR_TOTAL_SECTORS16 | 11 | - | The total sectors value in the BPB is not 0.
BPB_ERROR_MEDIA_DESCRIPTOR | 12 | The total sectors value in the BPB is not 0xF0 or 0xF9. | The total sectors value in the BPB is less than 0xF8.
BPB_ERROR_FAT_SIZE16 | 13 | - | The FAT size16 value in the BPB is not 0.
BPB_ERROR_HIDDEN_SECTORS | 14 | The hidden sectors value in the BPB is not 0. | -
BPB_ERROR_TOTAL_SECTORS32 | 15 | - | The total sectors32 value in the BPB is 0.
BPB_ERROR_FAT_SIZE32 | 16 | - | The FAT size32 value in the BPB is 0.
BPB_ERROR_ROOT_START_CLUSTER32 | 17 | -. | The root start cluster32 value in the BPB is 0.
BPB_ERROR_FSINFO_START_SECTOR32 | 18 | -. | The FSINFO start sector32 value in the BPB is 0.
BPB_ERROR_BACKUP_BOOT_SECTOR | 19 | - | The backup boot sector value in the BPB is 0.
BPB_ERROR_BOOT_SIGNATURE | 20 | - | The boot signature value in the BPB is not 0x29.
BPB_ERROR_FILE_SYSTEM_TYPE | 21 | - | The file system type field in the BPB does not begin "FAT32".
FAT32_ERROR_END | 22 | This isn't actually an error itself, it simply signals the end of the BPB errors.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Heber Image File Loader

Heber Image File (HIF) Graphics File Loader

HIF (Heber Image File) is a proprietary image format. HIF files are created using an image pre-processing tool from a 24 bit per pixel Microsoft® Windows® BMP bitmap file. Pre-processing allows the image data to be reversed and converted from 24 to 16 bit colour prior to use. This offers a significant performance increase when loading files because they can be loaded directly into video memory.

API Functions

The following API functions are provided by this module:

Function | Description
LoadHIF | Load a 16 bit per pixel Heber Image File image into video memory

See Also

  • HIF Defined Data Structures
  • File Loader Return Codes
  • bmp24tohif Bitmap to HIF file conversion tool
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Heber Image File Loader

Heber Image File Graphics File Loader

LoadHIF

BYTE LoadHIF(const DEVICE* dev, BYTE *filename, HEBERIMAGEINFO *heberinfo, UWORD *dataoutaddress)

Description

This function loads a 16 bit per pixel Heber Image File image into video memory.

Parameters

Parameter | Description
dev | Address of the device.
filename | Pointer to the name of the file to load.
heberinfo | Pointer to HIF file information structure.
dataoutaddress | Output memory address.

Remarks

For more information on conversion of .bmp bitmap files to .hif Heber Image File files see the bmp24tohif conversion tool page.

Return Value

Returns SUCCESS if the operation is successfull
Returns FILENOTFOUNDERR if the specified file could not be found

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HIF File Loader Return Codes

The following return codes are used in the HIF graphics file loader:

Return Code | Value | Description
SUCCESS | 0 | The function executed successfully
FILENOTFOUNDERR | -1 | The file requested can not be found on the storage media.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HIF Loader Data Structures

HIF Loader Defined Data Structures

The HEBERIMAGEINFO data structure is used to hold the height and width data for a Heber Image File image:

HEBERIMAGEINFO struct

Type | Name | Description
ULONG | imageheight | height of image in pixels
ULONG | imagewidth | width of image in pixels
ULONG | imagedataaddress | address of image data

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

The GIF file loader provides functions to load and control animated GIF files allowing animations to be included in video applications.

API Functions

The following API functions are provided by this driver:

GIF File: Open,Rewind,Close Functions

Function | Description
GIFOpen | Associates GIFIMAGE with GIF file image in memory.
GIFRewind | Rewind GIF file back to first image.
GIFClose | Close GIFIMAGE.

GIF File: Image Loading Functions

Function | Description
GIFLoadNextImage | Read next image frame in GIF file, decompress and write to Video Memory.
GIFSetImageDelay | Enforce a specified delay between current image and next image.

Gif File: Screen Information Functions

Function | Description
GIFHeaderStr | Get GIF file header string.
GIFScreenWidth | Get logical screen width.
GIFScreenHeight | Get logical screen height.
GIFScreenBackgroundColor16 | Get logical screen background color (16 bit display).
GIFScreenBackgroundColor24 | Get logical screen background color (24 bit display).

GIF File: Current Image Information Functions

Function | Description
GIFImageWidth | Get width of currently loaded image.
GIFImageHeight | Get height of currently loaded image.
GIFImageX | Get X Position of currently loaded image..
GIFImageY | Get Y Position of currently loaded image.
GIFImageSizeBytes | Get the size in bytes occupied in video memory by the currently loaded image.

GIF File: Current Graphic Rendering Information Functions

Function | Description
GIFGraphicDisposal | Get disposal method for current graphic rendering block (affects currently loaded image).
GIFGraphicDelayTime | Get delay time for current graphic rendering block (affects currently loaded image).
GIFGraphicTransparent | Returns True if transparency enabled for current rendered graphic.
GIFGraphicTransparentColor16 | Get 16 bit transparent color for current graphic rendering block (affects currently loaded image).
GIFGraphicTransparentColor24 | Get 24 bit transparent color for current graphic rendering block (affects currently loaded image).

See Also

  • GIF Image User Guide
  • GIF Function Return Codes
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFOpen

LONG GIFOpen(GIFIMAGE *gif, const UBYTE *data, ULONG size_bytes)

Description

Associates GIFIMAGE with GIF file image in memory

Initialises GIF parser

Initialises GIF structure with Header and Logical Screen parameters

Entire GIF file must be present as an image in memory

- loaded from CF using FAT32FileLoad()

- or linked in with program executable

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure
data | Pointer to start of gif file image in system memory
size_bytes | Size of gif file image in bytes

Return Value

Returns GIF_IMAGE_AVAILABLE if another image available in file
Returns GIF_EOF if end of file

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFRewind

LONG GIFRewind(GIFIMAGE *gif)

Description

Rewind GIF file back to first image

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns GIF_IMAGE_AVAILABLE if another image available in file
Returns GIF_EOF if end of file

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFClose

void GIFClose(GIFIMAGE *gif)

Description

Close GIFIMAGE (deassociate from GIF file image in memory)

Included for completeness - not strictly necessary as GIFIMAGEs are statically declared and do not use dynamically allocated memory

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFLoadNextImage

LONG GIFLoadNextImage(GIFIMAGE *gif, ULONG display_addr, ULONG display_pitch, ULONG display_bpp)

Description

Reads next image frame (animation) or single image frame

Decompresses image

Writes image to video memory

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure
display_addr | Destination Video memory address (offset)
display_pitch | Video display pitch. non-displayed video memory : display_pitch = 0 displayed video memory: display_pitch = layer width (pixels)
display_bpp | Video display bytes per pixel : 16 bit color display_bpp = 2 24 bit color display_bpp = 4

Return Value

Returns GIF_IMAGE_AVAILABLE if another image available in file
Returns GIF_EOF if end of file

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFGraphicDelayTime

UWORD GIFGraphicDelayTime(GIFIMAGE *gif)

Description

Get delay time for current graphic rendering block (affects currently loaded image)

Delay time is between current image and subsequent image

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Delay Time in hundredths of a second

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFHeaderStr

BYTE *GIFHeaderStr(GIFIMAGE *gif)

Description

Get GIF file header string. Returns pointer to a null terminated string.

Expected value "GIF89A" or "GIF87A"

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns pointer to header string

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFScreenWidth

UWORD GIFScreenWidth(GIFIMAGE *gif)

Description

Get logical screen width

Logical Screen is area of display device within which subsequent images will be rendered

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Screen Width in pixels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFScreenHeight

UWORD GIFScreenHeight(GIFIMAGE *gif)

Description

Get logical screen height

Logical Screen is area of display device within which subsequent images will be rendered

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Screen Height in pixels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFScreenBackgroundColor16

UWORD GIFScreenBackgroundColor16(GIFIMAGE *gif)

Description

Get logical screen background color (16 bit display)

Logical Screen is area of display device within which subsequent images will be rendered

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns background color

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFScreenBackgroundColor24

ULONG GIFScreenBackgroundColor24(GIFIMAGE *gif)

Description

Get logical screen background color (24 bit display)

Logical Screen is area of display device within which subsequent images will be rendered

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns background color

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFImageWidth

UWORD GIFImageWidth(GIFIMAGE *gif)

Description

Get width of currently loaded image

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Image Width in pixels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFImageHeight

UWORD GIFImageHeight(GIFIMAGE *gif)

Description

Get height of currently loaded image

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Image Height in pixels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFImageX

UWORD GIFImageX(GIFIMAGE *gif)

Description

Get X Position of currently loaded image.

Position is relative to the left edge of the Logical Screen

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns X position in pixels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFImageY

UWORD GIFImageY(GIFIMAGE *gif)

Description

Get Y Position of currently loaded image

Position is relative to the top edge of the Logical Screen

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Y position in pixels

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFImageSizeBytes

UWORD GIFImageSizeBytes(GIFIMAGE *gif)

Description

Get the size in bytes occupied in video memory by the currently loaded image

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns Image Size in bytes

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFGraphicDisposal

UWORD GIFGraphicDisposal(GIFIMAGE *gif)

Description

Get disposal method for current graphic rendering block (affects currently loaded image)

Disposal indicates way in which graphic is to be treated after display

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns DISPOSAL_UNSPECIFIED no action
Returns DISPOSAL_NONE graphic left in place
Returns DISPOSAL_BGND graphic area restored to background color
Returns DISPOSAL_PREVIOUS graphic area restored to overwritten contents

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Loader

GIF Image File Loader

GIFGraphicTransparent

UWORD GIFGraphicTransparent(GIFIMAGE *gif)

Description

Returns True if transparency enabled for current rendered graphic

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns TRUE if transprency enabled for current graphic, else FALSE

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFGraphicTransparentColor16

UWORD GIFGraphicTransparentColor16(GIFIMAGE *gif)

Description

Get 16 bit transparent color for current graphic rendering block (affects currently loaded image)

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns transparent color

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 GIF Loader

GIF Image File Loader

GIFGraphicTransparentColor24

ULONG GIFGraphicTransparentColor24(GIFIMAGE *gif)

Description

Get 24 bit transparent color for current graphic rendering block (affects currently loaded image)

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure

Return Value

Returns transparent color

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software GIF Image Return Codes

GIF Image Function Return Codes

The following return codes are returned by the GIF Image API functions.

Return Code | Value | Description
GIF_IMAGE_AVAILABLE | 0 | Another image available
GIF_EOF | -1 | End Of File - No More Images
DISPOSAL_UNSPECIFIED | 0 | no action
DISPOSAL_NONE | 1 | graphic left in place
DISPOSAL_BGND | 2 | graphic area restored to background color
DISPOSAL_PREVIOUS | 3 | graphic area restored to overwritten contents

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video Reel Driver

Video Reel Driver

The Video Reel Driver provides a framework to allow developers to implement video based spin reels. The Video Reel Driver uses the services of the low level video driver.

API Functions

The following API functions are provided by this module:

Video Reel: Initialisation Functions

Function | Description
VideoReelInit | Initialises reel with starting_symbol at winline.
VideoReelSetParameters | Set Reel Parameters.
VideoReelShow | Paint reel to display in current position.

Video Reel: Motion Control Functions

NOTE: Motion control functions are NON BLOCKING and return immediately.

Function | Description
VideoReelSpinToSymbol | Initiate a reel spin to a symbol preceded by n whole revolutions.
VideoReelStep | Initiate reel spin of n symbols from current position.
VideoReelStart | starts reel spinning continuously at max speed.
VideoReelStop | stops continuous spinning reel at next symbol after ramp down.
VideoReelSetSpeed | Set Reel Maximum Speed.

Video Reel: Motion Status Functions

Function | Description
VideoReelStatus | returns Reel run state: indicates when a reel move is finished.
VideoReelGetPosition | Gets Reel Position (the symbol currently at the winline)
VideoReelGetSpinTime | Returns spin time remaining.

See Also

  • Video Reel Driver User Guide
  • Video Reel Driver Return Codes
  • Video Reel Driver Defined Values
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Init

Video Reel Driver

VideoReelInit

void VideoReelInit(VIDEOREEL *reel, LONG starting_symbol)

Description

Initialises reel with starting_symbol at winline

Parameters

Parameter | Description
reel | pointer to video reel
starting_symbol | start symbol

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Set Params

Video Reel Driver

VideoReelSetParameters

LONG VideoReelSetParameters(REELGROUP *reelgroup, VIDEOREEL *reel, REELBAND *reelband, LONG max_speed, LONG incr, LONG decr, LONG overshoot)

Description

Set Reel Parameters. The following are requirements:

0 <= max_speed < steps_per_symbol

0 <= incr < max_speed

0 <= decr < max_speed

0 <= overshoot < steps_per_symbol/2

Parameters

Parameter | Description
reelgroup | pointer to video reel group
reel | pointer to video reel
reelband | pointer to reelband assigned to reel
max_speed | max steps advanced per video frame.
incr | rampup acceleration. Speed increment in steps/video frame.
decr | rampdown de-acceleration. Speed decrement in steps/ video frame.
overshoot | final position overshoot in steps (for visual realism)

Return Value

Returns SUCCESS if the reel parameters are set successfully
Returns INVALID_PARAMETER if an invalid parameter value has been set

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Set Speed

Video Reel Driver

VideoReelSetSpeed

LONG VideoReelSetSpeed(VIDEOREEL *reel, LONG max_speed)

Description

Set Reel maximum speed

Required: 0 <= max_speed < steps_per_symbol

Parameters

Parameter | Description
reel | pointer to video reel
max_speed | max steps advanced per video frame.

Return Value

Returns SUCCESS if the speed is set successfully
Returns INVALID_PARAMETER if the speed is outside the allowed range

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Show

Video Reel Driver

VideoReelShow

void VideoReelShow(REELGROUP *reelgroup, LONG reel_index)

Description

Paint reel to display in current position

Used to initially display reel before spinning Subsequent updates of reel display are automatic

If automatic double buffering (reel->frame = DOUBLEBUFFER_AUTO) then reel painted to both double buffer frames

Parameters

Parameter | Description
reel | pointer to video reel group
reel_index | specifies reel

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Spin to Symbol

Video Reel Driver

VideoReelSpinToSymbol

LONG VideoReelSpinToSymbol(VIDEOREEL *reel, LONG nrevs, LONG target_symbol, LONG dir)

Description

Initiate a reel spin to a symbol preceded by n whole revolutions (non-blocking). The reel must be stationary (status==REEL_IDLE) otherwise REEL_BUSY error is returned and function has no effect.

Parameters

Parameter | Description
reel | pointer to video reel
nrevs | number of complete revolutions to spin
target_symbol | target symbol
dir | direction to spin: NORMAL_SPIN | REVERSE_SPIN

Return Value

Returns SUCCESS if the reel can be spun to a symbol
Returns REEL_BUSY if the reel is already in use

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Step

Video Reel Driver

VideoReelStep

LONG VideoReelStep(VIDEOREEL *reel, LONG nsymbols, LONG dir)

Description

Initiate reel spin of n symbols from current position (nudges) (non-blocking) Reel must be stationary (status==REEL_IDLE) otherwise REEL_BUSY error returned and function has no effect.

Parameters

Parameter | Description
reel | pointer to video reel
nsymbols | number of symbols to step
dir | direction to spin: NORMAL_SPIN | REVERSE_SPIN

Return Value

Returns SUCCESS if the reel is moved the defined number of symbols
Returns REEL_BUSY if the reel is already in use

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Start

Video Reel Driver

VideoReelStart

LONG VideoReelStart(VIDEOREEL *reel, LONG dir)

Description

Starts a reel spinning continuously at max speed. The reel stopped by the VideoReelStop command. The reel must be stationary (status==REEL_IDLE) otherwise REEL_BUSY error is returned and function has no effect.

Parameters

Parameter | Description
reel | pointer to video reel
dir | direction to spin: NORMAL_SPIN | REVERSE_SPIN

Return Value

Returns SUCCESS if the reel is started successfully
Returns REEL_BUSY if the reel is already in use

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Stop

Video Reel Driver

VideoReelStop

LONG VideoReelStop(VIDEOREEL *reel)

Description

Stops continuous spinning reel at next symbol after ramp down

Parameters

Parameter | Description
reel | pointer to video reel

Return Value

Returns SUCCESS if the reel is stopped
Returns REEL_NOT_SPINNING if the reel is not in spin forever mode

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Status

Video Reel Driver

VideoReelStatus

LONG VideoReelStatus(VIDEOREEL *reel)

Description

Returns Reel Run State

Parameters

Parameter | Description
reel | pointer to video reel

Return Value

Returns the reel run state

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Get Position

Video Reel Driver

VideoReelGetPosition

LONG VideoReelGetPosition(VIDEOREEL *reel)

Description

Gets Reel position, defined as the symbol currently at the winline.

Parameters

Parameter | Description
reel | pointer to video reel

Return Value

Returns Current Symbol

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Videoreel Get Spintime

Video Reel Driver

VideoReelGetSpinTime

LONG VideoReelGetSpinTime(VIDEOREEL *reel)

Description

Returns spin time remaining

Parameters

Parameter | Description
reel | pointer to video reel

Return Value

Returns the time until the reel will stop in multiples of video frame time. 1 video frame = 16.77 ms @60Hz frame rate

Returns CONTINUOUS_SPIN if reel state = REEL_SPIN_FOREVER

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Reel Driver Return Codes

The following return codes are used in the Video Reel Driver:

Return Code | Value | Description
SUCCESS | 0 | The function executed successfully
REEL_BUSY | -1 | A command has been issued to a reel that is already in use
INVALID_PARAMETER | -2 | A parameter has been used that is not within the range of those supported. For example, a max speed value has been used that is not within the range supported by the driver
REEL_NOT_SPINNING | -3 | An attempt has been made to stop a reel that is not spinning
CONTINUOUS_SPIN | -1 | This reel is set to spin forever and therefore has an infinite remaining spin time.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Reel Driver Defined Values

The following values have been defined for the Video Reel Driver:

Reel Spin Direction Enumeration

Label | Value | Meaning
NORMAL_SPIN | 0 | The reel is spinning in the normal direction
REVERSE_SPIN | 1 | The reel is spinning in the reverse direction

Reel Spin State Enumeration

Label | Value | Meaning
REEL_IDLE | 0 | The reel is stationary
REEL_RAMPUP | 1 | The reel is ramping up
REEL_RUNNING | 2 | The reel is spinning
REEL_RAMPDOWN | 3 | The reel is ramping down
REEL_OVERSHOOT | 4 | The reel has overshot the stopping position
REEL_SPIN_FOREVER | 5 | The reel is set to spin until stopped
REEL_SHOW_ANIMATION | 6 | An animation is showing on the reel

Reel Group State Enumeration

Label | Value | Meaning
REELGROUP_IDLE | 0 | The group of reels is not spinning
REELGROUP_BUSY | 1 | The group of reels is spinning

Reel Orientation Enumeration

Label | Value | Meaning
VERTICAL_ORIENTATION | 0 | The reel is postioned vertically
HORIZONTAL_ORIENTATION | 1 | The reel is postioned horizontally

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Custom Interface

Custom Interface Module

This module provides custom interface drivers which use the services of lower level device drivers. This module has been provided to give developers the flexibility to build their own peripheral drivers into the Pluto 8 library code. All drivers are supplied with source code that can be used as a template to develop custom drivers.

Custom Interface Module Components

Component | Description
Generic Touchscreen Driver | The Generic touch screen driver provides a common API to specific touch screen controllers.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver

Generic Touchscreen Driver

The Generic Touchscreen module provides a common API allowing game developers to write touchscreen applications that are independent of the underlying hardware controller. Using the generic driver applications can be successfully created that will run with either of the supported touchscreen controllers using single set of functions.

The standard peripherals library provides support for the following touchscreen hardware controllers:

  • ELO
  • Microtouch

A touchscreen driver requires the services of a serial port on the Pluto 8 control board. Any of the available serial ports can be allocated to work with the touchscreen controller.

Note: If CTS/RTS are wired to the ELO touchscreen and the Serial Device does not handle these signals, the ELO touchscreen will NOT work. Heber advises to use RX/TX/Ground only for this device.

Touchscreen Driver Structure

API Functions

The following API functions are associated with this module:

Function | Description
TouchScreenSetScale | Sets the screen resolution for the Touchscreen Controller
TouchScreenCalibrate | Calibrates the Touchscreen controller
TouchScreenInit | Initialise the Touchscreen Controller
TouchScreenReset | Resets the Touchscreen Controller
TouchScreenIdentify | Identifies the Touchscreen Controller
TouchScreenSetSerial | Sets the Touchscreen serial communication parameters
TouchScreenSetMode | Sets the reporting mode for the Touchscreen controller
TouchScreenCommsMode | Set the communication mode with the Touchscreen Controller
TouchScreenGetNextData | Get the next Touch Data Packet from the Touch Event Buffer
TouchScreenGetX | Returns the scaled and calibrated screen touch X position from a Touch Data Packet
TouchScreenGetY | Returns the scaled and calibrated screen touch Y position from a Touch Data Packet
TouchScreenGetZ | Returns the screen touch Z value (touch pressure) from a Touch Data Packet
TouchScreenGetTouchStatus | Returns the screen touch status from a Touch Data Packet

See Also

  • Touchscreen Controller Installation and Configuration
  • Supported Touchscreen Controller Serial Interfaces
  • Touchscreen Controller Calibration
  • Touchscreen Controller Modes of Operation
  • Touchscreen Defined Values
  • Touchscreen Defined Data Types
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Set Scale

Generic Touchscreen Driver

TouchScreenSetScale

void TouchScreenSetScale(WORD xmax, WORD ymax, BYTE xinvert, BYTE yinvert)

Description

Set the screen resolution for the Touchscreen Controller

Parameters

Parameter | Description
xmax | Touchscreen X Resolution (0 < xmax < = 1024)
ymax | Touchscreen Y Resolution (0 < ymax < = 1024)
xinvert | 0 (Screen Left = 0, Screen Right = xmax) 1 (Screen Left = xmax, Screen Right = 0)
yinvert | 0 (Screen Left = 0, Screen Right = ymax) 1 (Screen Left = ymax, Screen Right = 0)

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver

Generic Touchscreen Driver

TouchScreenCalibrate

UWORD TouchScreenCalibrate(const DEVICE* dev, UWORD step_number)

Description

Calibrate the Touchscreen Controller

Parameters

Parameter | Description
dev | Address of the touchscreen device
step_number | Step number in the three step controller calibration. Use values from 1-3 incrementing on successive calls to this function (multi-step calibration).

Return Value

Returns SUCCESS if the calibration step is successful
Returns a comms error code if the calibration fails. The error code value will depend on the device specific driver (ELO or Microtouch).

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Init

Generic Touchscreen Driver

TouchScreenInit

UWORD TouchScreenInit(const DEVICE* dev)

Description

Initialise the Touchscreen Controller

Parameters

Parameter | Description
dev | Address of the touchscreen device

Return Value

Unused

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Reset

Generic Touchscreen Driver

TouchScreenReset

UWORD TouchScreenReset(const DEVICE* dev, UBYTE reset_type)

Description

Reset the Touchscreen Controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device
reset_type | Type of reset (see Touchscreen Defined Values page)

Return Value

Not used

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Identity

Generic Touchscreen Driver

TouchScreenIdentify

UWORD TouchScreenIdentify(const DEVICE* dev, TOUCHIDENTITY *touchidentity)

Description

Identify the Touchscreen Controller

Parameters

Parameter | Description
dev | Address of the touchscreen device
touchidentity | Address of a touch TOUCHINDENTITY structure to hold information about the touchscreen controller.

Return Value

Returns SUCCESS if the calibration step is successful
Returns a comms error code if the operation fails. The error code value will depend on the device specific driver (ELO or Microtouch).

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Set Serial

Generic Touchscreen Driver

TouchScreenSetSerial

UWORD TouchScreenSetSerial(const DEVICE* dev, BYTE baud, BYTE bits, BYTE stop, BYTE parity, BYTE handshake)

Description

Set the touchscreen serial communication parameters.

By default the touchscreen controller serial port has the following configuration:

  • 9600 baud
  • 8 data bits
  • 1 stop bit
  • no parity
  • no handshake

The default settings are common for both the ELO and MicroTouch touchscreen controllers and are applied during driver initialisation. It is recommended that the defaults settings are used.

Parameters

Parameter | Description
dev | Address of the touchscreen device
baud | Baud rate setting
bits | Number of data bits
stop | Number of stop bits
parity | Parity setting
handshake | Handshaking setting

Return Value

Returns SUCCESS if the calibration step is successful
Returns a comms error code if the operation fails. The error code value will depend on the device specific driver (ELO or Microtouch).

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Set Mode

Generic Touchscreen Driver

TouchScreenSetMode

UWORD TouchScreenSetMode(const DEVICE* dev, UBYTE mode)

Description

Set the reporting mode for the touchscreen controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device
mode | Reporting mode. The value can be a single mode or combination of those available.

Return Value

Returns SUCCESS if the calibration step is successful
Returns a comms error code if the operation fails. The error code value will depend on the device specific driver (ELO or Microtouch).

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Get Next Data

Generic Touchscreen Driver

TouchScreenGetNextData

TOUCHDATA *TouchScreenGetNextData(TOUCHDATA *touch_packet)

Description

Get the next Touch Data Packet from the Touch Event Buffer.

Parameters

Parameter | Description
touch_packet | Pointer to touch data packet structure to store the data in.

Return Value

Returns Pointer to touch data packet structure

Return NULL if there is no data in the buffer.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Get X

Generic Touchscreen Driver

TouchScreenGetX

UWORD TouchScreenGetX(TOUCHDATA *touch_packet)

Description

Returns the scaled and calibrated screen touch X position from a Touch Data Packet. The scaling applied must be initially specified using function TouchScreenSetScale().

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from

Return Value

Returns the X value from the touch packet.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Get Y

Generic Touchscreen Driver

TouchScreenGetY

UWORD TouchScreenGetY(TOUCHDATA *touch_packet)

Description

Returns the scaled and calibrated screen touch Y position from a Touch Data Packet. The scaling applied must be initially specified using function TouchScreenSetScale().

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from

Return Value

Returns the Y value from the touch packet.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Get Z

Generic Touchscreen Driver

TouchScreenGetZ

UWORD TouchScreenGetZ(TOUCHDATA *touch_packet)

Description

Returns the screen touch Z value (touch pressure) from a Touch Data Packet (If supported by the Touchscreen hardware).

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from

Return Value

Returns the Z value (0-255) from the touch packet.
If pressure sensitivity is not supported by the hardware the return value is dependent on the packet data structure component initialisation value. If the packet data structure was not initialised the return value in indeterminable.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Get Touch Status

Generic Touchscreen Driver

TouchScreenGetTouchStatus

UBYTE TouchScreenGetTouchStatus(TOUCHDATA *touch_packet)

Description

Returns the screen touch status from a Touch Data Packet.

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from.

Return Value

Returns a UBYTE containing a value representing the packet status information based on the touch event.
The following bits represent the possible events if set:
Bit0 = 1 DOWN_EVENT Touch down
Bit1 = 1 STREAM_EVENT Continuous touch
Bit2 = 1 UP_EVENT Lift up

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver

Touchscreen Controller Installation and Configuration

Installation

To use a specific Touchscreen Controller the device driver must be added to the DeviceList in the file devices.c in the project directory. The game applications should then reference the loaded device driver for touchscreen related operations.

To install the ELO device driver add the following to the DeviceList in the file devices.c:

const	INSTALLDEVICE	DeviceList[]=
{
    /*
    add this line to the device list to install the
    ELO touchscreen device driver
    */
    {&EloDevice ,0,0,0},
};

To install the MicroTouch device driver add the following to the DeviceList in the file devices.c:

const	INSTALLDEVICE	DeviceList[]=
{
    /*
    add this line to the device list to install the
    MicroTouch touchscreen device driver
    */
    {&MicroTouchDevice,0,0,0},
};

For further information on installing devices, refer to the Installing Device Drivers page.

Referencing the Loaded Device Driver

To use the loaded touchscreen device driver with the generic touchscreen API functions a reference to the driver must be used.

The following code examples demonstrate using the generic initialisation function TouchScreenInit() with references to the touchscreen controllers:

Using the ELO touchscreen controller:

/* declare a device */
const DEVICE* touchscreendev;
/*
set the device to the address of the ELO touchscreen device driver
*/
touchscreendev = &EloDevice;
/*
initialise the ELO touchscreen device using the
generic initialisation function
*/
TouchScreenInit(touchscreendev );

Using the MicroTouch Touchscreen Controller:

/* declare a device */
const DEVICE* touchscreendev;
/*
set the device to the address of the MicroTouch
touchscreen device driver
*/
touchscreendev = &MicroTouchDevice;
/*
initialise the MicroTouch touchscreen device using the
generic initialisation function
*/
TouchScreenInit(touchscreendev);

Configuring the Touchscreen Device Driver with a Serial Port

A touchscreen device requires a serial port to allow communication between the touchscreen controller and the Pluto 8 control board. Any of the available serial ports can be allocated to the touchscreen driver. The serial port allocation is defined in the file config.c in the project directory.

The following code examples show the allocation of serial ports to the Touchscreen controllers supported in the Pluto 8 software libraries:

To assign a serial port to the ELO touchscreen controller:

const ELOCFG EloCfg =
{
    /* FPGA UART 0 serial port */
    &FPUART0Device, 0
};

To assign a serial port to the MicroTouch touchscreen controller:

const MICROTOUCHCFG MicroTouchCfg =
{
    /* DUART serial port channel 0 */
    &DUART0Device, 0
};

It is recommended that the receive buffer size for the serial port assigned to the touchscreen device is increased to a minimum of 64 bytes. This is necessary because, due to the amount of serial data output by the touchscreen device, valid readings may be overwritten. The serial buffer size is defined for each serial port in the file config.c in the project directory. In the following example the DUART receive buffer size is set to 256 bytes:

/* set DUART0 channel 0 Rx buffer to 256 bytes for touchscreen data*/
static BYTE Duart0RxABuffer[1<<8]={0};

Creation of a Calibration Buffer

A calibration buffer needs to be created:

TOUCHCALIBDATA touchscreen_calib_data;

If this buffer is created in the IDRAM OR SYRAM, the calibration of the touchscreen will be preserved on power down otherwise if created in config.c, touchscreen will need to be re- after each power down.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver

Supported Touchscreen Controller Serial Interfaces

The following Touchscreen Controller serial interfaces are supported in the Pluto 8 Software Libraries:

Manufacturer | Serial Interface
MicroTouch | Serial SMT2 Serial SMT3 Serial SMT3V Serial SMT3R Serial SMT3RV
ELO SmartSet Family | E271-2200 AccuTouch, DuraTouch E211-2210 AccuTouch, DuraTouch E281-2310 IntelliTouch 2500S IntelliTouch

For further information on the above devices, refer to the following manufacturer documentation:

  • MicroTouch Touch Controllers Reference Guide 19-213 V2.2
  • ELO SmartSet Touchscreen Controller Family: Technical Reference Manual V1.0
  • ELO Addendum for E281-2310 Controller
  • ELO Addendum for IntelliTouch 2500S Controller
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver

Touchscreen Controller Calibration

All touchscreens require calibration to ensure correspondence between touch layer co-ordinates and physical display screen co-ordinates.

A generic API function TouchScreenCalibrate() is provided for this purpose, which is used identically for ELO and MicroTouch screens.

A two point calibration sequence is used, which involves the user touching a target near the bottom left of the screen, followed by a target at the top right of the screen. If the display screen has dimensions HSIZE and VSIZE, the targets should be at the following locations:

  • Target 1 (x, y) = ( HSIZE/8 , VSIZE - VSIZE/8 )
  • Target 2 (x, y) = ( HSIZE-HSIZE/8 , VSIZE/8 )

Although the generic API function can be used identically for ELO and MicroTouch screens, the underlying mechanism is different:

  • The MicroTouch Driver uses hardware calibration within the MicroTouch controller. After calibration, the calibration data is stored in non-volatile memory in the MicroTouch controller, and calibration corrections are applied to touch data before it is transmitted to the Pluto 8 system.
  • The ELO driver uses software calibration, with calibration data stored in a structure non-volatile RAM in the Pluto system. The ELO driver applies calibration correction to incoming touch co-ordinate data. If using an ELO touchscreen, the following should be declared in sysram.c in the project directory.
/* Touchscreen calibration data: NOT cleared on power up */
TOUCHCALIBDATA touchscreen_calib_data;

Calibration is only necessary at system installation. Re-calibration should not be necessary unless the display screen size and position are modified.

A code example demonstrating touchscreen calibration using the generic calibration function is listed in the TouchScreenCalibrate() API function documentation.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver

Touchscreen Controller Modes of Operation

Serial communication between the touchscreen controller and the Pluto 8 control board operates in two possible modes. The communication mode is set by the TouchScreenCommsMode() function in the generic touchscreen driver API.

Command Mode

This bi-directional communication mode is used for initialising and sending commands to the touchscreen controller. Both the ELO and MicroTouch controllers use a simple <command> <response> protocol. The protocols are implemented in the respective device drivers.

The generic touchscreen API provides the following functions for initialising and sending commands to the touchscreen controller:

API Function | Description
TouchScreenReset() | Resets the Touchscreen Controller
TouchScreenInit() | Initialises the Touchscreen Controller
TouchScreenIdentity() | Identify the Touchscreen Hardware
TouchScreenSetSerial()< /TD> | Set the Touchscreen serial parameters
TouchScreenCommsMode() | Set the Touchscreen communications mode
TouchScreenSetMode() | Set the reporting mode for the Touchscreen Controller
TouchScreenCalibrate() | Calibrate the Touchscreen Controller

All of the above functions are not re-entrant. They should only be called from main line code and not from interrupt service routines. All of the above functions expect a response from the Touchscreen Controller, and terminate with a timeout error if no response is received.

Touch Data Mode

In this mode of operation the assigned serial port receives a continuous stream of serial touch data from the touchscreen controller.

When the driver for a touchscreen controller is installed (ELO or MicroTouch) the appropriate 10ms interrupt service routine is installed to perform the following operations:

  • Read incoming touch data packets from the serial receive buffer
  • Convert the touch data packets into a standard format TOUCHDATA record
  • Store the TOUCHDATA records in the buffer TouchDataBuffer[]

The TouchDataBuffer[] used to store the TOUCHDATA records is defined in the file config.c in the project directory. The buffer size must be a power of two. The buffer is circular so the oldest record is overwritten on overflow. A buffer size of n records will contain the last n-1-- TOUCHDATA records.

The following example defines a TouchDataBuffer with 256 entries:

/* touch packet data buffer with 256 entries */
TOUCHDATA	TouchDataBuffer[1<<8]={0};
const	WORD	TouchDataBufferMask=(1<<8)-1;
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Defined Values

Generic Touchscreen Driver Defined Values

The following values are defined for use with the generic Touchscreen driver:

Command Mode Defined Values

Label | Meaning
COMMAND_MODE | Bi-directional communication mode to allow initialisation and commands to sent to the touchscreen controller using a command/response protocol. Functions using this mode are executed from main line code and the controller is polled for a response
TOUCH_DATA_MODE | Uni-directional communication to allow data to be streamed from the touchscreen controller to Pluto 8. Data capture in this mode is achieved in an interrupt service routine, with the driver controlling the data packet buffer where the data is stored.

Reporting Mode Defined Values

Label | Meaning
DOWN_REPORT | Enable reporting of screen touch down events
STREAM_REPORT | Enable reporting of continuous stream event data
UP_REPORT | Enable reporting of screen touch up events

Touch Packet Status Defined Values

The following bit mask values are used to represent the event status in a touch data packet returned from the Touchscreen Controller:

Label | Value | Meaning
DOWN_EVENT | 0x01 | Touch down event
STREAM_EVENT | 0x02 | Continuous touch event
UP_EVENT | 0x04 | Lift up event

Reset Defined Values

The following defined values can be used with the TouchScreenReset() function in the generic Touchscreen API:

Label | Meaning
HARD_RESET | Full hardware reset
SOFT_RESET | Software reset

API Function Return Codes

A return value of zero indicates that the function was successfully executed, a non-zero value indicates a communications error:

Generic Return Codes | Value
SUCCESS | The communication was successful

ELO Communication Return Codes | Value
ELO_COMMS_OK | The communication was successful
ELO_COMMS_FAIL | The communication failed
ELO_COMMS_TIMEOUT | The attempted communication timed out
ELO_COMMS_CHECKSUM_ERROR | The data check sum failed
ELO_COMMS_PROTOCOL_ERROR | A protocol error occurred
ELO_ACKNOWLEDGE_ERROR | An attempted communication was not acknowledged

MicroTouch Communication Return Codes | Meaning
MICROTOUCH_COMMS_OK | The communication was successful
MICROTOUCH _COMMS_FAIL | The communication failed
MICROTOUCH _COMMS_TIMEOUT | The attempted communication timed out
MICROTOUCH _COMMS_INVALID_RESPONSE | An invalid response was received from the Touchscreen Controller

Serial Port Setting Parameter Values

The following settings can be used to configure the touchscreen controller serial port for the devices indicated:

Data Rate
Parameter | Meaning
BAUD1200 | 1200 Baud rate (MicroTouch only)
BAUD2400 | 2400 Baud rate (MicroTouch only)
BAUD4800 | 4800 Baud rate (MicroTouch only)
BAUD9600 | 9600 Baud rate (ELO, MicroTouch )
BAUD19200 | 19200 Baud rate (ELO, MicroTouch
Data Bits
Parameter | Meaning
BITS7 | 7 data bits (ELO, MicroTouch)
BITS8 | 8 data bits (ELO, MicroTouch)
Stop Bits
STOP1 1 | stop bit (ELO, MicroTouch)
STOP2 | 2 stop bits (ELO, MicroTouch)
Parity Setting
PARITYEVEN | Even parity (ELO, MicroTouch)
PARITYODD | Odd parity (ELO, MicroTouch)
PARTIYNONE | No parity (ELO, MicroTouch)
Handshaking
0 | No handshaking (ELO only)
1 | Handshaking enabled (ELO only)
Note: Handshaking parameter is not used by the MicroTouch controller.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Data Types

Generic Touchscreen Driver Defined Data Types

The following data types are defined for use with the generic touchscreen driver:

Touchscreen Identity

The following data structure is used to store the controller identity information:

typedef struct touchidentity
{
    BYTE model[32];
    BYTE revision[32];
    BYTE features[32];
    BYTE status[32];
}TOUCHIDENTITY;

The components of the touch identity structure represent the following information:

model | Touchscreen controller model
revision | Revision version of the model
features | Special features of the controller
status | Status of the controller

Generic Touch Data Packet

The following data structure is used to store touch data packets by the generic driver:

typedef struct touchdata
{
    UWORD x;
    UWORD y;
    UWORD z;
    UBYTE status;
}TOUCHDATA;

The components of the touch data packet represent the following information:

x | X touch co-ordinate (unscaled 10 bit value in the range 0 1023)
y | Y touch co-ordinate (unscaled 10 bit value in the range 0 1023)
z | Touch pressure reading (if supported by the hardware)
status | Type of touchscreen event

Generic Touchscreen Calibration Data

The following data structure is used to store touchscreen calibration data by the generic driver:

typedef struct touchcalibdata
{
    UWORD x[2];
    UWORD y[2];
    UBYTE flag;
} TOUCHCALIBDATA;

The following data is set during calibration:

x[0] | Lower left x screen co-ordinate
y[0] | Lower left y screen co-ordinate
X[1] | Upper right x screen co-ordinate
y[1] | Upper right y screen co-ordinate
flag | Flag that is set to indicate that calibration has been performed

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Security Library

Security Library

The security library contains the following components:

  • Random Number Generator
  • 3DES Core Interface Driver
  • Smart Card Driver

The software Application Programming Interface (API) in the hardware module provides a software interface to the Pluto 8 hardware.

Security Library Components

Integrated Security Engine Module | The Integrated Security Engine Module provides the low level functions to access the Coldfire® 5475 security engine.
DES3 Security Module | The DES3 Security Driver provides the interface to the Pluto 8 Triple DES functionality.
Smart Card Driver | The Smart Card driver provides the interface to the security functions provided by the Pluto 8 Smart Card.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


SEC Driver

Integrated Security Engine Module

The Integrated Security Engine Module provides a set of API functions that use the Coldfire® 5475 security engine.

The following functionality is currently implemented:

  1. Random Number Generator (RNG) - generates 32-bit random numbers and is designed to comply with FIPS 140-1 standards for randomness and non-determinism.

RNG API Functions

The following API function is provided by this module:

Function | Description
GetRandValue | Get a random number

See Also

  • RNG API function return codes
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software

Integrated Security Engine Module

GetRandValue

BYTE GetRandValue(LONG * randomnumber);

Description

Generates and returns a random number.

Parameters

Parameter | Description
randomnumber | Pointer to a address LONG to store random number

Return Value

Returns SUCCESS if the operation is successful
Returns RNG_TIMEOUT if a timeout condition occured before a random number was generated
Returns RNG_ERROR if an error occured and a random number has not been successfully generated

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software RNG function return codes

RNG Function Return Codes

The following return codes are returned by the RNG API functions.

Return Code | Value | Description
SUCCESS | 0 | The function executed successfully
RNG_TIMEOUT | -1 | A timeout condition occured before a random number was generated
RNG_ERROR | -2 | An error occured and a random number has not been successfully generated

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 DES3 Driver

DES3 Driver

The DES3 device driver provides a software interface to the 3DES security core implemented in the Pluto 8 FPGA. The driver provides the necessary functions to allow the user to implement game and platform security on Pluto 8.

API Functions

The following API functions are provided by this module:

Function | Description
DES3Reset | Reset the FPGA DES3 module
AuthenticateStage1 | Initiate Stage 1 of FPGA authentication process
AuthenticateStage2 | Initiate Stage 2 of FPGA authentication process
DES3CreateKey | Create internal triple-DES key (used by DES3Encrypt() and DES3Decrypt() functions)
DES3Encrypt | Encrypt 8 bytes of plaintext using a previously loaded key
DES3Decrypt | Decrypt 8 bytes of encrypted data using a previously loaded key

See Also

  • DES3 security procedure
  • DES3 driver return codes
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: DES3Reset

DES3 Driver

DES3Reset

void DES3Reset( )

Description

Reset the FPGA 3DES encryption module.

Parameters

None

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: AuthenticateStage1

DES3 Driver

AuthenticateStage1

LONG AuthenticateStage1(UBYTE *in, UBYTE *out)

Description

Initiate the first stage of FPGA 3DES authentication process

Parameters

Parameter | Description
in | Pointer to a 24 byte encrypted key string
out | Pointer to the 8 byte returned nonce string

Return Value

Returns SUCCESS if the operation was successful
Returns DES3_TIMEOUT_ERROR if a timeout occurs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: AuthenticateStage2

DES3 Driver

AuthenticateStage2

LONG AuthenticateStage2(UBYTE *in)

Description

Initiate the second stage FPGA 3DES authentication process.

Parameters

Parameter | Description
in | Pointer to an 8 byte nonce string

Return Value

Returns SUCCESS if the operation was successful
Returns DES3_TIMEOUT_ERROR if a timeout occurs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: DES3CreateKey

DES3 Driver

DES3CreateKey

LONG DES3CreateKey(UBYTE *in)

Description

Create an internal 3DES key to be used by the DES3Encrypt( ) and DES3Decrypt( ) functions.
The input to the function is an encrypted version of required key, encrypted using the Master key.

Parameters

Parameter | Description
in | Pointer to a 24 byte encrypted key string

Return Value

Returns SUCCESS if the operation was successful
Returns DES3_TIMEOUT_ERROR if a timeout occurs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: DES3Encrypt

DES3 Driver

DES3Encrypt

LONG DES3Encrypt(UBYTE *in, UBYTE *out)

Description

Encrypt an 8 byte plaintext string using a previously loaded key.

Parameters

Parameter | Description
in | Pointer to an 8 byte plaintext input string
out | Pointer to an 8 byte encrypted returned string

Return Value

Returns SUCCESS if the operation was successful
Returns DES3_TIMEOUT_ERROR if a timeout occurs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software: DES3Decrypt

DES3 Driver

DES3Decrypt

LONG DES3Decrypt(UBYTE *in, UBYTE *out)

Description

Decrypt an 8 byte encrypted data string using a previously loaded key.

Parameters

Parameter | Description
in | Pointer to an 8 byte encrypyed input string
out | Pointer to an 8 byte returned plaintext string

Return Value

Returns SUCCESS if the operation was successful
Returns DES3_TIMEOUT_ERROR if a timeout occurs

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software DES3 Security Procedure

DES3 Security Procedure

Steps to Unlock Security

To unlock security on Pluto 8 the following operations need to executed in the order listed below:

  1. Install the Smart Card Driver using the device manager

    Example

    const INSTALLDEVICE DeviceList[]=
{
   ...
  {&SmartCardDevice,0,0,0},
   ...
}
  2. Initialise the Smart Card in game code startup

    Example

    UBYTE atr[32];  /* Smart Card Answer To Reset string */

if (SmartCardReset(atr) != SMARTCARD_TIMEOUT_ERROR)
{
   /* success */
   SetSessionId (SESSIONID);
}
  3. Call the authentication routine periodically (at least every 100 seconds) in the game code

    Example

UBYTE FPGAOut[8];
UBYTE SmartCardOut[8];

/* FPGA Stage 1 */
AuthenticateStage1( CypherKey, FPGAOut );

/* Smart Card */
Authenticate( SESSIONID, FPGAOut, SmartCardOut );

/* FPGA Stage 2 */
AuthenticateStage2( SmartCardOut );

NOTES:

The following notes relate to the code samples above:

  • CypherKey (...UBYTE CypherKey[24] ) is the Customer Specific Encrypted Key supplied by Heber as a header file

  • SESSIONID is an arbritrary constant
    After function SetSessionID( ) is called, all subsequent Smart Card commands require the same SessionID as a parameter, or the commands will return a failure.
    The development code defines SESSIONID with a #define in a header file.
    If prevention of Smart Card hot-swapping is required, the SessionID should be a random number generated once at initialisation

  • SmartCardReset( ) is a blocking function taking several hundred ms. It should only be called at initialisation.

  • Authenticate() is also a blocking function.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software DES3 Return Codes

DES3 Driver Return Codes

DES3 Defined Return Codes

Label | Value | Meaning
SUCCESS | 0 | The requested operation was performed successfully
DES3_TIMEOUT_ERROR | -1 | The operation timed out

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Smart Card Driver

Smart Card Driver

API Functions

The following API functions are provided by this module:

API to Smart Card Embedded Security Application

Function | Description
Authenticate | Run Heber Authentication process.
SetSessionId | Set Smart Card Session ID.
GetSessionKey | Get Session Key from Smart Card.

API to ZeitControl Basic CardTM Native Functions

Function | Description
GetApplicationID | Get Basic Card Application ID.
StartEncryption | Enable data-link encryption to Basic Card.
EndEncryption | Disable data-link encryption to Basic Card.

Low Level Smart Card Function

Function | Description
SmartCardReset | Smart Card Hardware Reset.

See Also

  • Smart Card function return codes
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Smart Card Authenticate

Smart Card Driver

Authenticate

LONG Authenticate(ULONG SessionID, UBYTE *nonce_in, UBYTE *nonce_out)

Description

Run Heber Authentication process on data packet

Parameters

Parameter | Description
SessionID | identifier set by SetSessionID function
nonce_in | 8 byte encrypted data packet in
nonce_out | 8 byte encrypted data packet out

Return Value

Returns the Smart Card status bytes SW1SW if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Smart Card Set Session ID

Smart Card Driver

SetSessionId

LONG SetSessionId(ULONG SessionID)

Description

Set session ID

This is a unique identifier that must be provided as a parameter to subsequent commands

Parameters

Parameter | Description
SessionID | session ID

Return Value

Returns the Smart Card status bytes SW1SW if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Smart Card Get Session Key

Smart Card Driver

GetSessionKey

LONG GetSessionKey(ULONG SessionID, ULONG Indx, UBYTE *Des3Key)

Description

Get Session Key (1 of 20) stored on card

Parameters

Parameter | Description
SessionID | identifier set by SetSessionID function
Indx | which key (1-20)
Des3Key | Pointer to 8 byte string buffer to hold Session Key

Return Value

Returns the Smart Card status bytes SW1SW if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Basic Card Get Application ID

Smart Card Driver

GetApplicationID

LONG GetApplicationID(UBYTE *IDstr)

Description

Get Application ID string from the Smart Card

Parameters

Parameter | Description
IDstr | Pointer to string buffer for holding ID string

Return Value

Returns the Smart Card status bytes SW1SW if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Basic Card Start Encryption

Smart Card Driver

StartEncryption

LONG StartEncryption(UBYTE alg, UBYTE key, ULONG rand)

Description

Enable data-link level encryption of data stream between Pluto 8 and Smart Card

Parameters

Parameter | Description
alg | encryption algorithm
key | encryption key
rand | random number seed

Return Value

Returns the Smart Card status bytes SW1SW if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Basic Card End Encryption

Smart Card Driver

EndEncryption

LONG EndEncryption(void)

Description

Disable data-link level encryption of data stream between Pluto 8 and Smart Card

Parameters

None

Return Value

Returns the Smart Card status bytes SW1SW if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Smart Card Reset

Smart Card Driver

SmartCardReset

LONG SmartCardReset(UBYTE *atr_str)

Description

Send 100ms RESET pulse to Smart Card.

Returns received Answer To Reset (ATR) string

Blocks for 100ms: use only at initialisation!

Parameters

Parameter | Description
atr_str | Pointer to 32 byte buffer to hold returned ATR

Return Value

Returns the length of the ATR string if the transaction is successful
Returns SMARTCARD_TIMEOUT_ERROR if the transaction fails

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Smart Card function return codes

Smart Card Function Return Codes

The following return codes are returned by the Smart Card API functions.

Return Code | Value | Description
SMARTCARD_TIMEOUT_ERROR | -1 | A communication timeout occured and the Smart Card transaction failed

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Tools and Utilities

Pluto 8 Tools and Utilities

A set of software tools and utilities are supplied with the Pluto 8 development kit to enable game developers to pre-process data into the format supported by some of the system device drivers. The following tools and utilities are supplied:

Image and Font Tools

Heber Image File (HIF) Pre-processing Utility

Font Conversion Utility

Audio File Pre-Processing Tool

Heber Audio File Pre-processing Utility
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - HIF Tool

Heber Image File (HIF) Pre-processing Utility

Background

Loading bitmap files from Compact Flash to video memory requires the following operations:

  • Convert the image data from 24 to 16 bit. This is required because the Calypso 32 video processsor will work to a maximum colour depth of 16 bits per pixel which is not a standard bitmap colour depth.
  • Reverse the image data. Bitmap data is stored in reverse (where the top left pixel data is at the end of the file). The image data is reversed when the file is loaded into video memory.

Performing the two operations above in real time presents a considerable overhead when loading files. To reduce the file load time it is possible to pre-process the image files to perform the colour depth conversion and data reversal.

bmp24tohif Pre-processing Tool

The bmp24tohif tool allows the game developer to pre-process 24 bit .bmp files. The tool outputs files in a proprietary Heber image file (.hif). .hif files can be copied on to a Compact Flash card and loaded within a game application running on a Pluto 8 controller using the LoadHIF() API function. Once .hif files have been loaded into video memory they can be used with the Video and Advanced Video API functions.

Usage

To convert an image to .hif format open a DOS window and type one of the following commands:

bmp24tohif [drive:][path]inputfile.bmp | Converts inputfile.bmp to inputfile.hif Note: If no output file name is specified the input file name is used with the .hif extension
bmp24tohif [drive:][path]inputfile.bmp [[drive:][path]outputfile.hif] | Converts inputfile.bmp to outputfile.hif
bmp24tohif [/?] | Displays the help information for the tool
bmp24tohif [/a] Infile Subfile | Set the Alpha bit in output file.

Examples

  1. Convert image1.bmp. The input file is in the current directory.

    bmp24tohif image1.bmp

    This will create output file image1.hif in the current directory.

  2. Convert image2.bmp. The input file is in the directory C:\images\

    bmp24tohif C:\images\image2.bmp C:\images\image3.hif

    This will create output file image3.hif in the directory c:\images\

  3. Execute a hif file with the alpha bit set.

    bmp24tohif /a

  4. Display the help information.

    bmp24tohif /?

    This will display the help information in the DOS window.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software - Tools and Utilities

Video Driver Font Conversion Utility (fontconv.bat)

This utility will convert .ttf true type font files into .c files. The converted font files can be used in game projects.

Using the Utility

  1. Copy the font file that you wish to convert into the your project directory
  2. Open a DOS window and change directory to your project directory
  3. The conversion utilites requires the following parameters:
    filename | - without file extension
    size | - point size of the font
    To convert the font file type fontconv <filename> <size> <unicode page> and press enter

    Example

    To convert the font file comic.ttf at 32 point size type:
    fontconv comic 32 0
    This will create a file called comic32_0.c which can be used in a game project.

Notes:

The Pluto 8 video processor will only support font sizes up to a maximum of 32 points.

This utility will only accept filenames in a DOS 8.3 format. The initial TTF file must only have 6 characters, so when combined with the point size, it does not create a filename greater than 8 characters before the .BDF extension.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Heber Sound File (HSF) Pre-processing Utility

Background

Heber Sound Files need to be pre-processed before they can be used. This pre-processing utility can be used to convert WAV files to HSF format. Before files can be processed using this utility they need to be in the following WAV format:

  • CCITT-ULAW compressed audio data format.
  • 32Khz sample rate.
  • 8 bits per sample.
  • Stereo or mono channels.

There are numerous shareware utilities available which will convert WAVs and other file types (e.g. MP3s) to this particular WAV format, but usually only if the source file uses 16 bits per sample or higher.

Usage

To convert a WAV file to .hsf format open a DOS window and type one of the following commands:

ulawconv [drive:][path]inputfile.wav | Converts inputfile.wav to inputfile.hsf if the input file contains mono audio data. Converts inputfile.wav to inputfile_l.hsf containing left data and inputfile_r.hsf containing right data if the input file contains stereo audio data.
ulawconv [/?] | Displays the help information for the tool.

Examples

  1. Convert mono_ulaw.wav:

    ulawconv mono_ulaw.wav

    If the WAV file is in the correct format as above, the following output is generated:

    File information:
    Compression Code: ULAW
    Channels: MONO
    Sample Rate: 32000Hz

    and the file mono_ulaw.hsf is created in the current directory.

  2. Convert mono_ulaw.wav:

    ulawconv stereo_ulaw.wav

    If the WAV file is in the correct format as above, the following output is generated:

    File information:
    Compression Code: ULAW
    Channels: STEREO
    Sample Rate: 32000Hz

    and the files stereo_ulaw_l.hsf and stereo_ulaw_r.hsf are created in the current directory.

  3. Convert mono_pcm.wav:

    ulawconv mono_pcm.wav

    If the WAV file is in the wrong format (not ULAW data), the following output is generated:

    File information:
    Compression Code: PCM
    Channels: MONO
    Sample Rate: 32000Hz

    This file type is not supported and no files are created.

  4. Display the help information:

    ulawconv

    This will display the help information in the DOS window.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 See Also Topics

See Also Topics

The following links provide further information related to the Pluto 8 software:

  • Third Party Documentation
  • GNU Compiler
  • Software Conventions
  • Software Architecture
  • Source File Types
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Third Party Documentation

Third Party Documentation

The following third party data sheets and technical manuals which are installed as part of the Pluto 8 Develoment Kit provide hardware device specific information for developers

  • Motorola 5475 ColdFire® Data Sheet
  • Motorola 5475 ColdFire® Product Brief
  • Motorola 5475 ColdFire® Hardware Reference Manual
  • Motorola 5475 ColdFire® Device Errata
  • Motorola 5475 ColdFire® Programmers Reference Manual
  • Fujitsu Carmine® Graphics Controller Hardware Manual
  • Fujitsu Carmine® Graphics Controller Hardware Errata
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


GNU Tool Chain

The Pluto 8 control board is supplied with a cross development tool chain built using version 4.1.1 of the GNU C compiler for the Motorola ColdFire® 5475. The compiler produces ELF binary files with DWARF-2 debug data. The compiler and tools are installed as part of the development CD-ROM.

Compilation and Linking

The make utility is used to invoke the GNU C compiler and linker to create a binary file that can be downloaded and executed on the Pluto 8 control board. The Pluto 8 software modules that are supplied with source code have an associated make file to allow the modules to be built. The following modules are supplied with make files:

  • Custom Peripherals Module This make file allows game developers to write their own custom peripheral device drivers and build a library archive file that can be included in games projects.
  • Custom Interface Module This make file allows game developers to write their own custom interface device drivers and build a library archive file that can be included in games projects.
  • Application Module This make file allows game developers to build game projects including the drivers contained in the archive libraries for the other software modules.

Make Files

All make files are named ‘makefile’ (no file extension) and specify which files make up the project or library and how they are to be processed in order to produce the final executable file. Lines beginning with ‘#’ are comments.

The make file for a particular project or library is located in the same directory as the source code for that project or library. The makefiles supplied with the Pluto 8 software contain the following:

Variables

A make file variable associates a single label with a string of characters. This label may then be used in several places in the make file and will be replaced by the string when it is encountered by make. The syntax used to define a make file variable is as follows:

path= c:/MyProject/SourceFiles/

To use the value of the label in a command or dependency the following syntax is used:

gcc $(path)FileName.c

Note: the GNU compiler gcc uses UNIX style forward slashes in its path names.

The following variable declarations are used in the Pluto 8 make files:

Variable | Use | Example
target The name of the target platform the files are to be built for. It is also the name of the subdirectory, which contains the library archive for this platform. #build for Pluto 8
target=pluto8
script The name of the linker script file to be used. #link to run from dram
script=lnkdram.x
output The name of the final output file that will be produced (without a file extension). #output file called demo
output=demo
lhdr The path to the header files, object files, and hardware library archive file. #path the hardware module
lhdw=../../libs/hardware/
lper The path to the header files, object files, and peripherals library archive file. #path the peripherals module
lper=../../libs/peripherals/
lcper The path to the header files, object files, and custom peripherals library archive file. #path the custom peripherals module
lcper=../../libs/customperipherals/
lint The path to the header files, object files, and interface library archive file. #path the interface module
lint=../../libs/interface/
lcint The path to the header files, object files, and interface library archive file. #path the custom interface module
lint=../../libs/custominterface/
lcint The path to the header files, object files, and interface library archive file. #path the custom interface module
lint=../../libs/custominterface/
lsec The path to the header files, object files, and security library archive file. #path the custom interface module
lint=../../libs/custominterface/
lstd | The path to the GNU standard libraries. | #path to the standard C libraries
istd | The path to the GNU standard include header files. | #path to the standard C header files
istdsys | The path to the GNU system include header files. | #path to the GNU system header files
istgcc | The path to the GNU gcc include header files. | #path to the gcc header files
FLAGS Specifies compiler flags. #Compiler flags
-fno-inline -Wcast-align -Wcast-qual -Wall
CFLAGS Specifies additional compiler flags #Compiler flags
CFLAGS= -O3 -mcpu=547x -msoft-float -D__mod2__=void -DIN_GCC=1 -nostdinc -gdwarf-2 -fno-merge-constants
IFLAGS Specifies compiler flags associated with include file paths #Include file path flags
IFLAGS= -I. -I$(lhdr) -I$(lint) -I$(lper) -I$(lcint) -I$(lcper) -I$(lsec) -I$(istd) -I$(istdgcc) -I$(istdsys)
gnu Specifies the standard 'C' libraries to search for unresolved externals #C libraries
gnu= -lc -lhosted -lcf
lib Specifies the Pluto 8 libraries to search for unresolved externals #Pluto 8 libraries
lib= -l$(target) -linterface -lperipherals -lcustominterface -lcustomperipherals -lsecurity
ld Specifies the command that invokes the GNU linker #Invoke the linker
ld = m68k-elf-ld
pp Specifies the command that invokes the cproto utility to generate prototypes for a given 'C' source file #Generate prototypes
pp= cproto
cc Specifies the command that invokes the GNU compiler #Invoke the GNU compiler
cc= m68k-elf-gcc
ar Specifies the command that invokes the GNU librarian #Invoke the librarian
ar= m68k-elf-ar
oc This variable specifies the command that invokes the GNU object file copier. This converts the elf file format into a Motorola s-record file #Invoke the object file copier
oc= m68k-elf-objcopy
objects Specifies the object files to be linked into the executable #Objects to link
objects= game.o config.o devices.o \
game.o config.o fpga.o devices.o idram.o sysram.o demo.o sectest.o

Implicit Rules

Implicit rules are a means of specifying to make how to generate a particular class of file from a different class of file, (for example how to generate object files from ‘C’ files). The following rules are used in the Pluto 8 make files:

Implicit Rule 1 | The first implicit rule specifies how to generate dependency (*.d) files. A dependency file names, for each object file, every source, header, and prototype file it is dependent on. This information is used by make to identify which files must be regenerated.
Implicit Rule 2 | The second rule specifies how to generate a prototype file (*.p) from a 'C' file. The prototype file contains an 'extern' for every public function and variable defined in the 'C' file.
Implicit Rule 3 | The third rule specifies how to generate a static prototype file (*.sp) from a 'C' file. The static prototype file contains a prototype for every local function defined in the 'C' file.
Implicit Rule 4 | The fourth rule specifies how to generate an object file from a 'C' file.

The Default Goal

The default goal is the target of the first non-implicit rule ‘make’ encounters. It is this file that ‘make’ endeavours to keep up to date.

In the case of the application module the default goal is the executable file defined by the variable $(output).

In the case of the custom peripherals module the default goal is the libcustomperipherals.a GNU archive library file.

Dependencies

The make file then includes all the dependency files. This means that make will scan all the dependency files and for each dependency it will make sure that the target is newer than the dependant files.

Linker Scripts

The linker script file specifies the format of the executable file generated by the linker and the addresses of the various RAM and ROM sections.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Conventions

Software Conventions

Throughout the software and documentation the following conventions are used:

Declarations

Type Definitions | All type definitions should be in upper case e.g. typedef unsigned char BYTE;
#defines | #defines will be in upper case e.g. #define TRUE 1
Global Functions | Global function names will consist of one or more words concatenated with the first letter capitalised. e.g. void GlobalFunction( );
Static Functions | Static function names will consist of one or more words concatenated with all letters in lower case. e.g. void staticfunction( );
Global Variables | Global variables names will consist of one or more words concatenated with the first letter capitalised. e.g. BYTE GlobalVariable;
Static Variables | Static variables names will consist of one or more words concatenated with all letters in lower case. e.g. WORD staticvariable;
Local Variables | Local variables names will consist of one or more words concatenated with all letters in lower case. e.g. LONG localvariable;
Structure Elements | Structure element names will consist of one or more words concatenated with all letters in lower case e.g. Structure.element = 0;

Fundamental Data Types and #defines

BYTE | The BYTE is an 8-bit signed integer in the range -127 to +127
UBYTE | The UBYTE is an 8-bit unsigned integer in the range 0 to +255
WORD | The WORD is a 16-bit signed integer in the range -32767 to +32768
UWORD | The UWORD is a 16-bit unsigned integer in the range 0 to +65535
LONG | The LONG is a 32-bit signed integer in the range -2147483647 to +2147483648
ULONG | The ULONG is a 32-bit unsigned integer in the range 0 to +4294967295
TRUE | #define TRUE 1
FALSE | #define FALSE 0
SUCCESS | #define SUCCESS 0
FAIL | #define FAIL -1

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Architecture

The following diagram illustrates the software module architecture and the drivers/functionality implemented in each module:

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Source File Types

The following file types used in the Pluto 8 software either contain, or are related to source code for the system:

.c file | C source file. The source code for the Pluto 8 is structured so that a .c file exists for each system device driver or sub-set of functionality.
.h file | .C header file that contains any defines and type definitions that are associated with in the C file of the same name. The .h file #includes the prototypes file. By including the .h file for a given .c file access is given to all of the functions and variables that are declared public in that .c file.
.p file | Prototype file that is automatically generated by the make utility. The prototype file contains the declarations for all of the public functions and variables in the given .c file.
.sp file | Static prototype file that is automatically generated by the make utility. The static prototype file contains function declarations for all of the local functions for a given .c file. This file should only be #included in the .c file of the same name.
.d file | Dependency file. The dependency file is automatically generated by the make utility, and lists paths to files upon which a .c file may be dependent.
.s file | Motorola assembly source file.
.o file | Compiled object file for a module created by the compiler.
.a file | Archive file. An archive file contains all of the compiled objects for a module, for example, libperipherals.a contains all of the objects for the peripherals module.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Set Comms Mode

Generic Touchscreen Driver

TouchScreenCommsMode

void TouchScreenCommsMode(const DEVICE *dev, BYTE mode)

Description

Set the communication mode with the Touchscreen Controller. In general this function is only used to set the controller to data streaming mode following initialisation. The mode setting sequence for general usage is demonstrated below:

  • Install driver - controller is set to COMMAND_MODE by installation function
  • Configure controller - controller remains in COMMAND_MODE
  • Use touchscreen in application - controller must be explicitly set to TOUCH_DATA_MODE

Parameters

Parameter | Description
dev | Address of the touchscreen device
mode | Communications mode

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Generic Touchscreen Driver Set Scale

Generic Touchscreen Driver

TouchScreenSetScale

void TouchScreenSetScale(WORD xmax, WORD ymax, BYTE xinvert, BYTE yinvert)

Description

Set the screen resolution for the Touchscreen Controller.

Parameters

Parameter | Description
xmax | Touchscreen X Resolution (0 < xmax <= 1024).
ymax | Touchscreen Y Resolution (0 < ymax <= 1024)
xinvert | 0 Screen Left=0, Screen Right= X max. 1 Screen Left=Xmax, Screen Right= 0.
yinvert | 0 Screen Left=0, Screen Right= Y max. 1 Screen Left=Ymax, Screen Right= 0.

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

ATA Driver Dual Device Setup

Dual ATA device usage

A possible advantage of using two ATA devices on the Pluto 8 is to store the game, graphics/animations and audio files on one disk which is used read only, whilst another disk could be used as a read/write device in game to store audit data/statistics via the writing functions in the FAT32 API.
The advantage of this approach is that any unexpected power cycles would not corrupt the game data on the read only disk, ensuring the machine is kept in a bootable/playable state.

Possible hardware configurations

The CompactFlash socket P12 on the Pluto 8 board is hard wired to be the master ATA device. This is because Compact flash cards have no jumpers for master/slave device selection, and so use the chip select line to detect whether they are the master or slave. An offboard device connected to P13 may be master if no compact flash is present. Therefore one of the following setups is recomended:

  • Single ATA device - CompactFlash connected to P12 as master
  • Single ATA device - CompactFlash in CF to IDE adapter (Heber part number 01-16641) connected to P13 and configured as master via adapter jumper
  • Single ATA device - Hard disk connected to P13 and configured as master via jumper
  • Dual ATA devices - CompactFlash connected to P12 as master, CompactFlash in CF to IDE adapter connected to P13 and configured as slave via adapter jumper
  • Dual ATA devices - CompactFlash connected to P12 as master, hard disk connected to P13 and configured as slave or cable select via jumper
  • Dual ATA devices - Hard disk connected to P13 and configured as master, hard disk connected to P13 and configured as slave

Note that only 40 way conductor IDE cable should be used, the above set ups have not been tested with 80 way conductors (E.G. ATA66/ATA100 cables), as they have extra grounded connections to certain pins, and the middle connector on these cables has the CSEL line bypassed to make it slave. The CSEL line is left unconnected on the board at P13, so configuring cable select on offboard ATA devices will only work for slave devices, master devices must be set as master via jumpers.
If only one offboard ATA device is to be used, ensure it is connected at the end connector of the ATA/IDE cable, not the middle. This is to prevent an unconncted "stub" of cable with unterminated signals causing interference.

Software configuration

Ensure that the configuration data for the ATA driver is set up correctly as specified in the ATA configuration data page. Then ensure that the master or both the master and slave devices are enabled in the device list within devices.c of the game code:

const	INSTALLDEVICE	DeviceList[]=
{
    ...
    {&ATA0Device		,0	,0,0},
    {&ATA1Device		,0	,0,0},
    ...
}

If only the master device is to be used the code loads faster if the slave device is commented/removed, however this is not critical as non-interrupt driven timeouts are used.
Use the drive select field in the configuration data structures to ensure that ATA0Device and ATA1Device refer to the master and slave device as appropriate.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 ATA Driver

Achieving maximum ATA performance

The faster PIO modes make read and write operations to the registers within the ATA device faster when the library code accesses them. Due to the loading of the system caused by other drivers accesses to the ATA device in mainline code will not take place as frequently as the devices are capable of handling.

In order to increase the speed of loading of larger files such as audio and graphics, the interrupts may be disabled. This is acceptable because the ATA driver is not interrupt driven, so as long as the rest of the system is not expected to do anything involving interrupt driven drivers (E.G. serial port communication or animated graphics - still images will remain onscreen) the files will load faster.

The need to load files faster without the rest of the system operating could occur when the board is powered on and the game begins booting. The following code can be used to demonstrate the effect:

static void	idefunction(...)
{
    ...

    SetInterruptMask(7);

    if( (FAT32FileOpen(atadevice, filename, &testfiledesc, READ_ONLY) == FAT32_OK)
        && (FAT32FileLoad(atadevice, &testfiledesc, (UWORD*)(channeladdresses[0]))
            == FAT32_OK) )
    {
        SetInterruptMask(0);

        sprintf(str,"\n\rLoaded %s\r", filename);
        TxString(serialdevice, channel, str);
    }
    else
    {
        SetInterruptMask(0);

        sprintf(str,"\n\rFailed to load %s\r", filename);
        TxString(serialdevice, channel, str);
        break;
    }

    ...
}

Code similar to this is available to try out in the demoide() function of the Pluto 8 demonstration project (Heber part number 81-18531) under the IDETIMECMD menu option. The timing of the load in that project uses the 1ms interrupt, which would be disabled using the technique above causing inaccurate timing results. However during testing a HSF file 6.24Mb in size took 2860ms to load from a CompactFlash card operating in PIO mode 3, but with interrupts disabled the load was instantaneous.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Code Example

/*-------------------------------------------------------------------
DECLARATION FORMATS
Type defs........... UPPER CASE
#defines............ UPPER CASE
Global Functions.... GlobalFunction();
Static Functions.... staticfunction();
Global Variables.... GlobalVariable;
Static Variables.... staticvariable;
Local Variables..... localvariable;
Structure Elements.. Structure.element;
-------------------------------------------------------------------*/

/****   Include Files */
#include    "hardware.h"
#include    "game.h"

/****   Local Definitions */
/****   Global Variables */

/****   Local Variables */
/****   Global Constants */

/****   Identity */
/****   Local Constants */

/*-------------------------------------------------------------------
Name......... Game()
Author....... Marc Adams
Date......... 15/09/03
Description.. Libraries initialise system then branch to here
Parameters... None
Return....... None
History...... 15/09/03 - Code tidy up  - MSA
-------------------------------------------------------------------*/
void Game()
{

    BYTE command;
    BYTE error_val;
    /* comms channel connected to RS232A */
    ConfigureSerial(&SerialDevice, 0, BAUD9600, BAUD9600, BITS8, STOP1, PARITYNONE, TXNONE, RXNONE);

    while(1)
    {

        demoinputs(inputcommands, &SerialDevice, 0);

    }
}

/*-------------------------------------------------------------------
Name......... demoinputs()
Author....... Andrew Crosher
Date......... 08/02/06
Description.. Demonstrate the system inputs
Parameters... 1) Commands for the menu section
............. 2) Address of serial ouput device connected to console
............. 3) Serial device output channel
Return....... None
History...... 08/02/06 - written as a demo project
-------------------------------------------------------------------*/
static void demoinputs(const BYTE*const* cmd ,const DEVICE* dev, BYTE channel)
{
    INPUTSCMD    command;
    BYTE loop;
    BYTE str[10];

    while(TRUE)
    {
        command=getCommand(inputcommands,dev,channel);
        switch(command)
        {
            case TESTCMD:

                TxString(&SerialDevice,0,"\rTEST\r");
                /* inputtable[] holds all valid Heber inputs,
                   all these are tested here */
                for(loop = 0; loop < 40; loop++)
                {

                if(Test(inputtable[loop]))
                    {
                        sprintf(str,"%d ",loop);
                        TxString(&SerialDevice,0,str);
                    }
                }
                break;

            case TESTDIRCMD:

                TxString(&SerialDevice,0,"\rTEST DIR\r");
                /* inputtable[] holds all valid Heber inputs,
                   all these are tested here */
                for(loop = 0; loop < 40; loop++)
                {

                    if(TestDir(inputtable[loop]))
                    {
                        sprintf(str,"%d ",loop);
                        TxString(&SerialDevice,0,str);
                    }
                }
                break;

            case PUSHBUTTONCMD:

                if(PushButton()== ON)
                {
                    TxString(&SerialDevice,0,"\rpush button pressed\r");
                }
                else
                {
                    TxString(&SerialDevice,0,"\rpush button not pressed\r");
                }
                break;

            case CURRENTSENSECMD:

                if(CurrentSense()== ON)
                {
                    TxString(&SerialDevice,0,"\rcurrent sensed\r");
                }
                else
                {
                    TxString(&SerialDevice,0,"\rcurrent not sensed\r");
                }
                break;

            case EXITINPUTSCMD:
                return;
        }
    }
}

static BYTE	getCommand(const BYTE*const* cmd,const DEVICE* dev,
                       BYTE channel)
{
    BYTE	str[20];
    BYTE	index;
    BYTE	ch;
    BYTE	command;

    /* Get services */
    ClearRx(dev,channel);
    showCommands(cmd,dev,channel);
    while(TRUE)
    {
        /* Prompt */
        index = 0;
        command = -1;
        TxString(dev,channel,"\r>");

        while(command<0)
        {
            /* get character */
            ch = RxChar(dev, channel);

            while(ch<0)
            {
                ch = RxChar(dev, channel);
            }

            if((ch!='\r') && (ch!='\b'))
            {
                /* Echo character */
                while(!TxChar(dev,channel,ch));
                /* store character in command string */
                str[index++]=ch;
                /* Exceeded buffer size so start again */
                if(index==sizeof(str))
                {
                    break;
                }
            }
            else if(ch == '\b')
            {
                /* check for start of string */
                if(index>0 )
                {
                    /*
                    send backspace to move cursor back
                    one character console
                    */
                    while(!TxChar(dev,channel,ch));
                    /*
                    overwrite character at current cursor
                    position with a space
                    */
                    while(!TxChar(dev,channel,' '));
                    /*
                    send backspace to move cursor back
                    to space character on console
                    */
                    while(!TxChar(dev,channel,ch));

                    /*
                    decrement string pointer so that character
                    that has been deleted is overwritten by
                    next character entered */
                    index--;
                }
            }
            else
            {
                /* Terminate string */
                str[index]=0;
                /* Identify command */
                command=idCommand(cmd,str);
                if(command>0)
                {
                    /* Return valid command */
                    return(command-1);
                    /* Invalid command so prompt again */
                    break;
                }
            }
        }
    }
}

/*-----------------------------------------------------------------------
Author....... J.M.Tarrant
Date......... 21/12/99
Description.. Print the commands available
Limitations..
------------------------------------------------------------------------*/
void	showCommands(const BYTE*const* cmd ,const DEVICE* dev,BYTE channel)
{
ULONG index;

    TxChar(dev,channel,'\r');
    /* Print commands */
    for(index=0;cmd[index];index++)
    {
        TxString(dev,channel,cmd[index]);
        while(!TxChar(dev,channel,'\r')); /* Send CR */
    }
}

/*-----------------------------------------------------------------------
Author....... J.M.Tarrant
Date......... 21/12/99
Description.. Identify command and return command index
Limitations..
------------------------------------------------------------------------*/
BYTE	idCommand(const BYTE*const* cmd,BYTE* str)
{
    BYTE* s;
    BYTE  index;

    s=str;

    while(*s)
    {
        *s++=tolower(*s);
    }

    for(index=0;cmd[index];index++)
    {
        if(!strcmp(cmd[index],str))
        {
            return(index);
        }
    }
}
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software I2C Code Example

/*-------------------------------------------------------------------
DECLARATION FORMATS
Type defs........... UPPER CASE
#defines............ UPPER CASE
Global Functions.... GlobalFunction();
Static Functions.... staticfunction();
Global Variables.... GlobalVariable;
Static Variables.... staticvariable;
Local Variables..... localvariable;
Structure Elements.. Structure.element;
-------------------------------------------------------------------*/

/****   Include Files */
#include    "hardware.h"
#include    "game.h"

/****   Local Definitions */
/****   Global Variables */
/****   Local Variables */
/****   Global Constants */

/****   Identity */
/****   Local Constants */

/*-------------------------------------------------------------------
Name......... Game()
Author....... Marc Adams
Date......... 15/09/03
Description.. Libraries initialise system then branch to here
Parameters... None
Return....... None
History...... 15/09/03 - Code tidy up  - MSA
-------------------------------------------------------------------*/
void Game()
{

    BYTE command;
    BYTE error_val;
    /* comms channel connected to RS232A */
    ConfigureSerial(&SerialDevice, 0, 15, 15, 0x03, 0x07, 0x10, TXNONE, RXNONE);
    //SetRouting(&SerialDevice,1,ROUTEUART1RS232A);

    while(1)
    {
        demooutputs(&SerialDevice, 0);
    }
}

/********************************************************************
*** OUTPUTS
********************************************************************/

/*-------------------------------------------------------------------
Name......... demooutputs()
Author....... Andrew Crosher
Date......... 08/02/06
Description.. Demonstrate the operation of the pluto8 outputs
Parameters... 1) Address of serial ouput device connected to console
............. 2) Serial device output channel
Return....... None
History...... 08/02/06 - written as a demo project
-------------------------------------------------------------------*/

static void demooutputs( const DEVICE* dev, BYTE channel )
{
    BYTE op;
    BYTE loop;
    CMD    command;
    BYTE str[10];

    WORD	MxiStrobeLst[] = {OP0, OP1, OP2, OP3, OP4};

    while(TRUE)
    {
        command=getCommand(output_commands,dev,channel);
        switch(command)
        {
            case ONE_ON:
                TxString(&SerialDevice,0, "\rEnter output number (0-31) to turn ON: ");
                op = getbyte(&SerialDevice,0);
                OutputOn(outputtable[op]);
                break;

            case ONE_OFF:
                TxString(&SerialDevice,0, "\rEnter output number (0-31) to turn OFF: ");
                op = getbyte(&SerialDevice,0);
                OutputOff(outputtable[op]);
                break;

            case ALL_ON:
                for(loop = 0; loop < 32; loop++)
                {

                    if(OutputOn(outputtable[loop]);
                }
                break;

            case ALL_OFF:
                for(loop = 0; loop < 32; loop++)
                {

                    if(OutputOff(outputtable[loop]);
                }
                break;

            case AUX_ON:
                for(loop = 0; loop < 8; loop++)
                {
                    OutputOn(auxtable[loop]);
                }
                break;

            case AUX_OFF:
                for(loop = 0; loop < 8; loop++)
                {
                    OutputOff(auxtable[loop]);
                }
            break;
        }
    }
}

static BYTE	getCommand(const BYTE*const* cmd,const DEVICE* dev,
                       BYTE channel)
{
    BYTE	str[20];
    BYTE	index;
    BYTE	ch;
    BYTE	command;

    /* Get services */
    ClearRx(dev,channel);
    showCommands(cmd,dev,channel);
    while(TRUE)
    {
        /* Prompt */
        index = 0;
        command = -1;
        TxString(dev,channel,"\r>");

        while(command<0)
        {
            /* get character */
            ch = RxChar(dev, channel);

            while(ch<0)
            {
                ch = RxChar(dev, channel);
            }

            if((ch!='\r') && (ch!='\b'))
            {
                /* Echo character */
                while(!TxChar(dev,channel,ch));
                /* store character in command string */
                str[index++]=ch;
                /* Exceeded buffer size so start again */
                if(index==sizeof(str))
                {
                    break;
                }
            }
            else if(ch == '\b')
            {
                /* check for start of string */
                if(index>0 )
                {
                    /*
                    send backspace to move cursor back
                    one character console
                    */
                    while(!TxChar(dev,channel,ch));
                    /*
                    overwrite character at current cursor
                    position with a space
                    */
                    while(!TxChar(dev,channel,' '));
                    /*
                    send backspace to move cursor back
                    to space character on console
                    */
                    while(!TxChar(dev,channel,ch));

                    /*
                    decrement string pointer so that character
                    that has been deleted is overwritten by
                    next character entered */
                    index--;
                }
            }
            else
            {
                str[index]=0;						/* Terminate string */
                command=idCommand(cmd,str);		/* Identify command */
                if(command>0)
                {
                    return(command-1);      	/* Return valid command */
                    break;						/* Invalid command so prompt again */
                }
            }
        }
    }
}

/*-----------------------------------------------------------------------
Author....... J.M.Tarrant
Date......... 21/12/99
Description.. Print the commands available
Limitations..
------------------------------------------------------------------------*/
void	showCommands(const BYTE*const* cmd ,const DEVICE* dev,BYTE channel)
{
ULONG index;

    TxChar(dev,channel,'\r');
    /* Print commands */
    for(index=0;cmd[index];index++)
    {
        TxString(dev,channel,cmd[index]);
        while(!TxChar(dev,channel,'\r')); /* Send CR */
    }
}

/*-----------------------------------------------------------------------
Author....... J.M.Tarrant
Date......... 21/12/99
Description.. Identify command and return command index
Limitations..
------------------------------------------------------------------------*/
BYTE	idCommand(const BYTE*const* cmd,BYTE* str)
{
    BYTE* s;
    BYTE  index;

    s=str;

    while(*s)
    {
        *s++=tolower(*s);
    }

    for(index=0;cmd[index];index++)
    {
        if(!strcmp(cmd[index],str))
        {
            return(index);
        }
    }
}

static BYTE getbyte(const DEVICE* dev,BYTE channel)
{
    BYTE	str[3];
    BYTE	index;
    BYTE	ch;
    BYTE 	value;

    /* Get services */
    ClearRx(dev,channel);

    /* Prompt */
    index = 0;

    while(index0 )
            {
                /*
                send backspace to move cursor back
                one character console
                */
                while(!TxChar(dev,channel,ch));
                /*
                overwrite character at current cursor
                position with a space
                */
                while(!TxChar(dev,channel,' '));
                /*
                send backspace to move cursor back
                to space character on console
                */
                while(!TxChar(dev,channel,ch));

                /*
                decrement string pointer so that character
                that has been deleted is overwritten by
                next character entered */
                index--;
            }
        }
        else if(ch=='\r')
        {
            break;
        }
    }
    value = (BYTE)atoi(str);

    return(value);
}
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicRevision

PIC Driver

GetPicIdentity

BYTE GetPicIdentity(const DEVICE* picdev, PICID* pic_id)

Description

This function will be used to ensure that.

Parameters

Parameter | Description
PICDevice | Pic Device address
revisiondata | Pointer to a byte containing the revision number of the PIC software.

Return Value

SUCCESS - if the operation is successful.
I2C_IN_PROGRESS - if the operation is still in progress.
I2C_TIMEOUT - if any part of the operation timed out and the communication failed.
I2C_SLAVE_ERROR - the address transmitted by the master was not acknowledged by the PIC on the I2C bus.

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software PIC Driver - GetPicRevision

PIC Driver

SetPicIdentity

BYTE GetPicIdentity(const DEVICE* picdev, PICID* pic_id)

Description

This function will be used to ensure that.

Parameters

Parameter | Description
PICDevice | Pic Device address
revisiondata | Pointer to a byte containing the revision number of the PIC software.

Return Value

Returns SUCCESS if the operation is successful
Returns I2C_TIMEOUT if any part of the operation timed out and the communication failed
Returns I2C_SLAVE_ERROR if the address transmitted by the master was not acknowledged by the PIC on the I2C bus

HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Driver

Serial Communications Driver

RxClear

void RxClear(const DEVICE* dev, BYTE channel)

Description

This function clears any data in the receive buffer for the specified UART.

Parameters

Parameter | Description
dev | Coldfire® serial device to configure
channel | This parameter is unused but is present to provide compatibility with previous releases of the Pluto library code.

Return Value

None.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Serial Communications Code Example

/****   Include Files */

#include    "hardware.h"
#include    "game.h"

/*-------------------------------------------------------------------
Name......... Game()
Author....... Andrew Crosher
Date......... 13/01/06
Description.. Libraries initialise system then branch to here
Parameters... None
Return....... None
-------------------------------------------------------------------*/
int Game()
{

    BYTE rx_buf[11];
    BYTE tx_err;

    BYTE a = 'A';
    BYTE x = 'X';
    BYTE count = 0;

    /* comms channel connected to RS232C */

    ConfigureSerial(&SerialDevice,2,BAUD4800,BAUD4800,BITS8,STOP1,PARITYODD,TXNONE,RXNONE);

    SetRouting(&SerialDevice,2,ROUTEUART1RS232C);

    /* Blocking TxChar Function */
    while(TxChar(&SerialDevice,2,'*') != SUCCESS );
    while(TxChar(&SerialDevice,2,'*') != SUCCESS );
    while(TxChar(&SerialDevice,2,'*') != SUCCESS );

    while(1)
    {

        if(RxEmpty(&SerialDevice,2) < SUCCESS)
        {

            rx_buf[count++] = (BYTE)RxChar(&SerialDevice,2);

            ClearRx(&SerialDevice,2);

            if(count == 10)
            {
                TxString(&SerialDevice,2, rx_buf);
                tx_err = TxChar(&SerialDevice,2,a);
                ClearTx(&SerialDevice,2);
                /* comms channel connected to BACTA */
                ConfigureSerial(&SerialDevice,0,BAUD38400,BAUD38400,BITS8,STOP1,PARITYODD,TXNONE,RXNONE);
                TxString(&SerialDevice,0, rx_buf);
                TxChar(&SerialDevice,0,x);

                /* delay until transmit buffer is empty */
                while(TxEmpty(&SerialDevice,0) < SUCCESS);

                ClearTx(&SerialDevice,0);
                count  = 0;
            }

        }

    }

    return (SUCCESS);
}


Pluto 8 Software Serial Communications Implementation

Serial Driver Implementation

The Pluto 8 Serial Communications driver has been implemented using the three UART hardware modules on the FreeScale MCF5271 processsor. The driver uses processor interrupt service routines to transmit/receive data to and from a serial device.

Configuring the Serial Communications Driver

Port Selection

Of the three UART ports only port 0 (SERIAL_A) is connected directly to the BACTA port the other two are connected to the FPGA, which in turn can be configured to direct serial comms through either the RS232, CCTALK or TTL headers. In order to use UART ports 1 and 2 (SERIAL_B and SERIAL_C) we use the function SetRouting().

Baud Rate Selection

Since there is no clock signal on the serial comms channels it is important that both end points use the same baud rate. The list of possible baud rates are shown in a the table ((((((here))))))).

The remaining data to be transmitted is sent by the I2C interrupt service routine. The status of the transmission can be tested by calling the I2cWriteStatus() function. While the transmission is in progress another operation can not be started.

Writing to an I2C slave device

The I2cWrite() function used to send data to an I2C slave device is a non-blocking function. The I2cWrite()function performs the following operations:

  • Test that the bus is free.
  • Set the processer hardware module in transmit mode
  • Send a start condition over the I2C bus
  • Transmit the hardware address of the I2C slave in write mode

If the bus is busy the function will return with a return value of I2C_BUS_BUSY. If the hardware address has been transmitted the function will return SUCCESS.

The remaining data to be transmitted is sent by the I2C interrupt service routine. The status of the transmission can be tested by calling the I2cWriteStatus() function. While the transmission is in progress another operation can not be started.

Reading from an I2C slave device

There are three possible was to read from an I2C slave device using the Pluto 8 driver. The I2C read functions are non-blocking.

Sequential Read

The I2cSeqRead() function allows a specified number of bytes to be read from an I2C slave device. The function is suitable for use a slave device such as an E2PROM where the device maintains a local pointer to the next memory location to begin the read from. The function performs the following operations:

  • Test that the bus is free.
  • Set the processer hardware module in transmit mode
  • Send a start condition over the I2C bus
  • Transmit the hardware address of the I2C slave in read mode

If the bus is busy the function will return with a return value of I2C_BUS_BUSY. If the hardware address has been transmitted the function will return SUCCESS.

The data is read by the I2C interrupt service routine. The status of the read operation can be tested by calling the I2cReadStatus() function. during a read operation another I2C operation can not be started. When the read operation is complete the I2cReadStatus() function will return SUCCESS and pointer set to the read data buffer.

Repeated Start Read

The I2cRead() function allows a specified number of bytes to be read from a specified address on an I2C slave device. The function can be used with I2C slave devices that support repeated start, for example XXXX, or to perform a read from a specified address on an E2PROM device. The function performs the following operations:

  • Test that the bus is free.
  • Set the processer hardware module in transmit mode
  • Send a start condition over the I2C bus
  • Transmit the hardware address of the I2C slave in write mode

If the bus is busy the function will return with a return value of I2C_BUS_BUSY. If the hardware address has been transmitted the function will return SUCCESS.

The following operations are performed in the interrupt service routine:

  • Transmit the internal address that data is to be read from
  • Generate a repeated start condition
  • Transmit the hardware address of the I2C slave device in read mode
  • Read n bytes of data from the I2C slave device.

The status of the read operation can be tested by calling the I2cReadStatus() function. During a read operation another I2C operation can not be started. When the read operation is complete the I2cReadStatus() function will return SUCCESS and pointer set to the read data buffer.

Simulated Repeated Start

If a device does not support repeated start but requires an internal address to be transmitted prior to reading data the following combination of function calls can be used:

  • Use the I2cWrite() function to send out the internal I2C slave address to read from
  • Use the I2cWriteStatus() function to ensure that operation is complete
  • Use the I2cReadSeq() function to read data from the I2C slave device
  • Use the I2cReadStatus() function test that the operation is complete and retrieve the read data

Code Example

Click on this link to open a page containing example code using the I2C driver API functions.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software SPI Driver

Software Serial Peripheral Interface (SPI) Driver

The Software Serial Peripheral Interface (SPI) driver module is a software implementation of the SPI protocol for the Puto 8. The driver is provided to use with SPI peripherals devices with a slow clock rate, for example the Starpoint SEC Meter which supports a maximum clock speed of 5KHz.

An example driver for the SEC Meter is provided in the Customer Peripherals library, the SEC driver provides a high level API for control of the device but uses the Software SPI Module functionality for low level communication. Drivers for other SPI devices requiring a slow clock rate may be added using the SEC driver as a template.

API Functions

The following API functions are provided by this module:

Function | Description
SpiPoll | Prepare data and begin SPI transmission in the next 1ms SPI interrupt routine.
SpiStatus | Check the status of the last SPI transmission.

See Also

    TBD?
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software SPI Driver

Software Serial Peripheral Interface (SPI) Driver

SpiPoll

BYTE SpiPoll(const BYTE *txmessage, BYTE txmessagelength, BYTE rxmessagelength, ULONG delay)

Description

Prepare data and begin SPI transmission in the next 1ms SPI interrupt routine. One bit of data is sent in each following 1ms ISR, providing a clock rate of 1KHz. This function is non-blocking; if multiple transactions are required the state of the SPI bus should be checked before calling this function using SpiStatus, which can also be used to get the data received back from the peripheral.

Parameters

Parameter | Description
txmessage | A pointer to the data to send on the SPI bus.
txmessagelength | The number of bytes of data to send.
rxmessagelength | The number of bytes of data to be received.
delay | The delay in ms between transmitting data to the peripheral and restarting the clock to receive data back.

Return Value

Returns SUCCESS if the transaction was started successfully
Returns SPI_BUSY if the SPI driver is still executing the previous SPI transaction.

Code Example

TBD?

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software SPI Driver

Software Serial Peripheral Interface (SPI) Driver

SpiStatus

BYTE SpiStatus(BYTE *rxmessage, BYTE rxmessagelength)

Description

Check the status of the SPI bus. If the last transaction has completed the data received back from the peripheral is copied into the rxmessage buffer.

Parameters

Parameter | Description
rxmessage | A buffer into which data recieved from the peripheral is copied.
rxmessagelength | The number of bytes of data to be received and copied into the buffer.

Return Value

Returns SPI_COMPLETE if the SPI bus is idle.
Returns SPI_BUSY if the SPI driver is still executing the previous SPI transaction.

Code Example

TBD?

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software SPI function return codes

Software SPI Driver Function Return Codes

The following return codes are returned by the Software SPI API functions.

Return Code | Value | Description
SUCCESS | 0 | The function executed successfully.
SPI_COMPLETE | 0 | The last SPI transaction initiated has completed (data was sent and reply has been received).
SPI_BUSY | 1 | The software SPI bus is busy, due to a transaction is progress.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.
Document No: 80-20013, Issue X Release Date: 02.07.08 Email: support@heber.co.uk www.heber.co.uk


Pluto 8 GIF Loader

GIF Image File Loader

GIFSetImageDelay

void GIFSetImageDelay(GIFIMAGE *gif, ULONG delay_ms)

Description

Force a specified delay between current image and subsequent images.

NOTE: The specified delay will OVERRIDE any delay specified in the GIF file

Parameters

Parameter | Description
gif | Pointer to GIFIMAGE structure
delay_ms | minimum delay in ms

Return Value

None

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Gif Image Functions User Guide

Gif Image Functions User Guide

Graphics Interchange Format (GIF) is an 8-bit-per-pixel bitmap image format introduced by CompuServe in 1987.

The format uses a palette of up to 256 distinct colors from the 24-bit RGB color space. It also supports animations and allows a separate palette of 256 colors for each frame. GIF images contain a single image frame, GIF animations contain multiple image frames.

GIF images are compressed using the Lempel-Ziv-Welch (LZW) lossless data compression technique. This reduces the file size without degrading the visual quality. Compression ratios depend on the nature of the image.

Patents relating to the LZW data compression technique expired in 2004, and the GIF image format can now be freely used without licensing.

GIF images and animations are widely used on the web. There are many commercial and open source applications for creating GIF images and animations, and for converting other image and animation formats into GIF

PLUTO 8 GIF SUPPORT

The Pluto 8 libraries include support for displaying GIF images and animations.

Decompression speeds are sufficient to decompress and display small animations in real time at reasonable frame rates.

The same GIF file can be displayed on screen layers of different colour depth (16 or 24 bit colour)

QUICK START GUIDE

The GIF decompression and display functions require the GIF file to be loaded into system memory. Two techniques are possible:

  • the GIF file is loaded when required from the Compact Flash card filesystem into memory.
  • the GIF file is linked into the game code, and permanently present within the game code binary file.

Every GIF image currently active must be associated with a corresponding GIFIMAGE structure, passed as a 'handle' parameter to all GIF API functions.

The following API functions are used to decompress and display GIF files:

GIFOpen( )

  • associates a GIFIMAGE structure to a GIF file in memory
  • initialises the GIFIMAGE structure
  • starts parsing the GIF file
  • reads the header and logical screen sections of the GIF file
  • stops parsing the GIF file at the beginning of the first image frame

GIFLoadNextImage( )

  • resumes parsing the GIF file
  • reads the next image frame
  • decompresses the image frame
  • writes the image to video memory
  • stops parsing at the beginning of the next image frame if present

GIFRewind( )

  • Rewinds the GIF file back to the first image frame

NOTES

  • GIFLoadNextImage returns GIF_EOF if no more images are present
  • the destination address is normally a non-displayed area of video memory. The image is subsequently blitted to a visible screen layer
  • The same GIF image file can be displayed on target display layers of either supported color depth: 16 bit or 24 bit colour.

Example Code - Displaying a single GIF image

/* display "hourglass.gif" image on  Base Layer at position (100,200) in 16 bit colour  */

#define BYTES_PER_PIXEL 2	/* Display layer is 16 bit colour */
//#define BYTES_PER_PIXEL 4	/* Display layer is 24 bit colour */

extern ULONG image_buffer_start;	/* download buffer in SDRAM */
extern GIFIMAGE gif;			/* gif image structure*/
extern LONG videofree;			/* start of free memory in non-displayed video memory */

FILE_DESCRIPTOR fin;			/* file handle */
LONG filesize;
LONG x=100, y=200;			/* GIF Logical Screen - required screen position */
LONG width, height;			/* GIF Image - width, height */

/* Load GIF file into system memory (SDRAM) */
FAT32FileOpen(&ATA0Device, "hourglass.gif", &fin, READ_ONLY);
FAT32FileLoad(&ATA0Device, &fin, &image_buffer_start);

/* Initialise GIF structure */
filesize = FAT32GetFileSize(&fin);
GIFOpen(&gif, &image_buffer_start, filesize);

/* Decompress image into video memory */
GIFLoadNextImage(&gif, video_free, 0, BYTES_PER_PIXEL);

/* Blit image to display layer */
width = GIFImageWidth(&gif);
height= GIFImageHeight(&gif);
CalypsoPutSprite(&Calypso32Dual0Device, BL_LAYER,0, x, y, video_free, width, height, 0);

FAT32FileClose(fin);

Example Code - Displaying a GIF animation

/* display "apple.gif" animation on Base Layer at position (100,200) in 16 bit colour */

#define BYTES_PER_PIXEL 2	/* Display layer is 16 bit colour */
//#define BYTES_PER_PIXEL 4	/* Display layer is 24 bit colour */

extern ULONG image_buffer_start;	/* download buffer in SDRAM */
extern GIFIMAGE gif;			/* gif image structure*/
extern LONG videofree;			/* start of free memory in non-displayed video memory */

FILE_DESCRIPTOR fin;			/* file handle */
LONG filesize;
LONG x=100, y=200;			/* Display position of GIF Logical Screen Origin */
LONG width, height;			/* Current GIF Image width, height */
LONG xoff, yoff;			/* GIF Image position offset from Logical Screen origin */
LONG state;

/* Load GIF file into SDRAM */
FAT32FileOpen(&ATA0Device, "apple.gif", &fin, READ_ONLY);
FAT32FileLoad(&ATA0Device, &fin, &image_buffer_start);

/* Initialise GIF structure */
filesize = FAT32GetFileSize(&fin);
state = GIFOpen(&gif, &image_buffer_start, filesize);

/* Loop through all image frames in GIF file */
while (state != GIF_EOF) {

    /*Decompress next image into video memory */
    state = GIFLoadNextImage(&gif, video_free, 0, BYTES_PER_PIXEL);

    width = GIFImageWidth(&gif);
    height= GIFImageHeight(&gif);
    xoff  = GIFImageX(&gif);		/* image x offset relative to Logical Screen */
    yoff  = GIFImageY(&gif); 		/* image y offset relative to Logical Screen */

    /*Blit image to display layer */
    CalypsoPutSprite(&Calypso32Dual0Device, BL_LAYER,0, x+xoff, y+yoff, video_free,
                width, height, NORMAL_MODE);

    /*go and do something else between each image frame, for example... */
    if(key_pressed())
        do_something();

}

FAT32FileClose(fin);

GIFIMAGE declaration

Every GIF file active at a given time must be associated with its own GIFIMAGE structure, declared thus:

    /* isdram.c	- variables declared in this file located in SDRAM instead of CPU internal RAM */
    #include "interface.h"

    TRANSLATION_TABLE	cherry_gif_table;
    LINE_BUFFER	cherry_gif_buffer;

    GIFIMAGE 	cherry_gif = { &cherry_gif_table, &cherry_gif_buffer, NULL};

Note that the first three members of the GIFIMAGE structure are initialised:

The first two members are pointers to TRANSLATION_TABLE and LINE_BUFFER. These buffers are used during parsing and decompressing of the GIF file.

The third member is a pointer to the memory location of the GIF file memory image. This should be initialised to NULL.

The linker script provided with the Pluto 8 example projects places global variables in the small CPU internal SRAM. Local function variables are placed on the stack (also in the CPU internal SRAM)

However, the GIFIMAGE and related structures are too large to fit in the CPU SRAM space, especially if multiple GIFIMAGE structures are declared. The translation table alone occupies 12 Kbytes

They must be declared in such a way as to be placed by the linker in SDRAM space. The simplest way is to place the GIFIMAGE declarations in a separate file, and use the linker script to locate the object file in SDRAM space.

    /* Part of linker script lnkdram.x */

    /* Memory map */
    MEMORY
    {
        /*SDRAM 128MBYTE */
        sdram	  : ORIGIN = 0x60000000, LENGTH = 0x03FFFFFF
        etc
    }

    SECTIONS
    {
    .text :
        {
            ...etc
        }  > sdram

    /* area of SDRAM for downloaded image buffers and large GIF data structures */
    .ibuf :
        {
        image_buffer_start	= .; 	/*Downloaded GIF Image SDRAM buffer -   set at 4Mbytes */
        . = . + 0x00400000;
        image_buffer_end	= .;

        *(.ibuf)
        isdram.o(COMMON); 	/*GIF images declared in isdram.c located in SDRAM */
        }  >  sdram

Delay time and animation frame rate

Animated GIF files optionally specify a delay time between successive image frames. This delay time is specified on a frame by frame basis in multiples of 10ms.

The parser in the GIFLoadNextImage( ) function implements this delay time by maintaining an internal timer. The function will only terminate when the elapsed time since the termination of the previous call to the function exceeds the required delay time.

This mechanism works reasonably well, although there are a number of sources of inaccuracy. If the decompression time exceeds the specified delay time, the animation frame rate will inevitably be slower than required.

It is possible to over-ride any delay time specified in the GIF file by using the API function GIFSetImageDelay ( )

For example:

    /*Loop through all image frames in GIF file */
    while (state != GIF_EOF) {

        /*Decompress next image into video memory */
        state = GIFLoadNextImage(&gif, video_free, 0, BYTES_PER_PIXEL);

        width = GIFImageWidth(&gif);
        height= GIFImageHeight(&gif);

        /*Blit image to display layer */
        CalypsoPutSprite(&Calypso32Dual0Device, BL_LAYER,0, x, y, video_free,
                width, height, NORMAL_MODE);

        GIFSetImageDelay(&gif, 100);	/* Set 100ms  delay between image frames */

    }

The required delay time is specified in multiples of 1ms.

A delay time of zero will result in the minimum possible delay time between frames.

Example Code - Displaying multiple simultaneous GIF animations

FAT32FileOpen(&ATA0Device, "apple.gif", &fin1, READ_ONLY);
FAT32FileLoad(&ATA0Device, &fin, &apple_buffer_start);
filesize1 = FAT32GetFileSize(&fin1);

FAT32FileOpen(&ATA0Device, "cherry.gif", &fin2, READ_ONLY);
FAT32FileLoad(&ATA0Device, &fin, &cherry_buffer_start);
filesize2 = FAT32GetFileSize(&fin2);

GIFOpen(&apple_gif, &apple_buffer_start, filesize1);
GIFOpen(&cherry_gif, &cherry_buffer_start, filesize2);

/*Loop forever showing apple and cherry animations */
while (1) {

    state1 = GIFLoadNextImage(apple_gif, video_buffer1, 0, BYTES_PER_PIXEL);
    CalypsoPutSprite(&Calypso32Dual0Device, ML_LAYER, 0, x1, y1, video_buffer1,
                APPLE_WIDTH, APPLE_HEIGHT, NORMAL_MODE);
    if (state1 == GIF_EOF)
        state1 = GIFRewind(&apple_gif);

    state2 = GIFLoadNextImage(cherry_gif, video_buffer2, 0, BYTES_PER_PIXEL);
    CalypsoPutSprite(&Calypso32Dual0Device, ML_LAYER, 0, x2, y2, video_buffer2,
                CHERRY_WIDTH, CHERRY_HEIGHT, NORMAL_MODE);
    if (state2 == GIF_EOF)
        state1 = GIFRewind(&cherry_gif);

}

Transparent processing

The GIF89A specification allows one colour index in the colour table to be designated as transparent.

The GIF file format allows transparency to be enabled or disabled on a frame by frame basis. If transparency is enabled for a particular image frame, then any display image pixels matching the transparent colour should not be modified.

This can be supported by using the transparency option of the CalypsoPutSprite( ) function.

NOTE: The GIFLoadNextImage( ) parser will automatically assign the current BlitBLT transparent colour to the transparent colour index.

Example Code

    /* if ALL frames in GIF animation are transparent: */
    do
    {
        state = GIFLoadNextImage(gif, video_buffer, 0, BYTES_PER_PIXEL);
        CalypsoPutSprite(device, layer, 0, x, y, video_buffer, width, height, TRANSPARENT_MODE);

    } while (state != GIF_EOF);

    /* if only some frames are transparent  */
    do
    {
        state = GIFLoadNextImage(gif, video_buffer, 0, BYTES_PER_PIXEL);

        if (GIFGraphicTransparent(gif))			/*this frame transparent ? */
            mode = TRANSPARENT_MODE;
        else
            mode = NORMAL_MODE;

        CalypsoPutSprite(device, layer, 0, x, y, video_buffer, width, height, mode);

    } while (state != GIF_EOF);

Linking GIF files into Game Code

Normally GIF images can be loaded as required from the Compact Flash filesystem. However, they can also be directly linked into the game code executable.

Step by step example for linking in GIF file apple.gif:

  1. Copy apple.gif to the project directory.
  2. Create the following assembly language file apple.s in the project directory
        .section ".rodata"

    .globl apple_start
    .globl apple_end
    .type apple_start, @object
    .type apple_end, @object

    apple_start:
    .incbin "apple.gif"
    apple_end:
  3. Add the object file apple.o to the objects list in the makefile
        objects =  game.o config.o fpga.o devices.o idram.o sysram.o isdram.o demo.o apple.o
  4. Ensure that the makefile includes a pattern rule invoking the assembler:
        as = m68k-elf-as

    #Pattern rule to generate an object file from an assembly file
    %.o : %.s
        $(as) $< -mcpu=547x -o $@
  5. The linked-in GIF file apple.gif can be accessed by the game code in this way:
        extern LONG apple_start, apple_end;
    LONG apple_gif_size;

    apple_gif_size = 1 + (ULONG) &apple_end - (ULONG) &apple_start;

    GIFOpen(gif, &apple_start, apple_gif_size);

    GIFLoadNextImage(gif, video_buffer, 0, 2);

    CalypsoPutSprite (device, layer, 0, x, y, video_buffer, width,  height, NORMAL_MODE);
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Video Reel Driver User Guide

Video Reel Driver User Guide

The Video Reel Driver is intended to enable simple and rapid development of Video Reel Games on the Pluto 8 video game platform. The driver provides:

  • a set of configuration structures specifying the video reels
  • an API providing functions controlling reel movement

NOTE: After the reel characteristics have been specified, the driver will handle all position calculations and screen updates automatically.

The game code consists of simple commands of general nature

    spin reel 3 to symbol position 7

The driver allows the game developer complete flexibility in specifying:

  • Number of reels in a reel group
  • Number of symbols per reel
  • Symbol image size
  • Reelband composition: the symbol images associated with a reel and their sequence.
  • Screen position
  • The height of the visible part of the displayed reel (Normally 3 x symbol height)
  • The orientation of the reel: vertical or horizontal (for 90 deg rotated screens)
  • The display screen used to show the reel. (The Carmine supports two video displays)
  • The display layer used to show a reel
  • Reel dynamics: maximum speed, rampup and rampdown acceleration, overshoot.

Features

  • alternative set of motion blurred images can be specified: shown at maximum speed.
  • multiple reel groups can be specified. Reels can run simultaneously on both video displays.
  • overshoot can be specified. This gives a realistic wobble effect when the reel stops

Reel Dynamics

The reel position updates are initiated by the video display vertical interrupt.

Therefore all speed variables are defined in terms of steps per video frame. The frame update rate is normally 60 frames per second: a slower frame rate can be set using CalypsoSetFrameRate( )

If the symbol image size is width pixels by height lines:

    Vertical reels:  a movement of height steps corresponds to a reel advance of one symbol
    Horizontal reels:  a movement of width steps corresponds to a reel advance of one symbol

Driver structures

There are three structure types associated with the reel driver:

VIDEOREEL

The videoreel structure defines the parameters of individual reels and their current state.

The structure members are not accessible to the game programmer. They are initialised or modified by API functions, and are updated dynamically by the driver.

REELGROUP

The reelgroup structure defines a set of video reels and their screen presentation.

    typedef struct reelgroup {

    const DEVICE* dev;		/* display device used */
    LONG layer;			/* display layer/frame  */
    BYTE frame;			/* double buffer frame */
    LONG orientation;		/* VERTICAL_ORIENTATION | HORIZONTAL_ORIENTATION */
    ULONG nreels;			/* number of reels = NREELS */
    ULONG visible_height;		/* visible height in lines */
    ULONG winline_offset;		/* offset in lines from start of visible to start of winline symbol */
    VIDEOREEL *reel[NREELS];	/* the individual reels... */
    ULONG x[NREELS];		/* ...and their screen positions (top left x coordinate) */
    ULONG y[NREELS];		/* (top left y coordinate) */

    } REELGROUP;

REELBAND

The reelband structure defines a sequence of symbol images associated with a reel.

    typedef struct reelband {

    ULONG symbols_per_reel;		/* number of symbols */
    ULONG symbol_width; 		/* symbol width in pixels */
    ULONG symbol_height;		/* symbol height in lines */
    ULONG *symbol_addr;		/* symbol image address table */
    ULONG *blur_symbol_addr;	/* alternative symbol image address table - blurred images */
    ULONG *symbol_list;		/* ordered list of symbol table indexes - defines reelband sequence */

    } REELBAND;

Configuration

The Video Reel driver is configurable at game level via the use of a configuration structure in config.c. This structure lists the reel groups used in the game.

    typedef	struct videoreelcfg {
        REELGROUP *reelgroup[MAX_REELGROUPS];
    } VIDEOREELCFG;

Code Example

The following is an example for a game using two sets of reels: reelgroup0 and reelgroup1:

    const VIDEOREELCFG VideoReelCfg[ ] = { { &reelgroup0, &reelgroup1, NULL}. {0} };

Step by step example code

Requirement

A set of five reels displayed vertically on the middle layer of Display 0.

Each reel has ten symbols, selecting from the following set of 160x120 16 bit symbol images.

    cherry, orange, pear, lemon, bell and bar.

The first three reels as they spin present the symbols in the following order:

    cherry pear cherry orange cherry lemon cherry bell cherry bar

The last two reels as they spin present the symbols in a different order:

    lemon pear lemon orange lemon cherry lemon bell lemon bar

Three symbols are visible for each reel: the winline symbol and the symbols before and after it.

Configuration

The reels are defined in file config.c in the project directory.

First, we need to declare five reels:

    (config.c)

    VIDEOREEL reels[5];

Next, we declare a reelgroup containing these five reels:

    (config.c)

    REELGROUP reelgroup = {

    &Calypso32Dual0Device,					/* show reels on first display  */
    ML_LAYER, 						/* show reels on  middle left layer */
    DOUBLEBUFFER_AUTO,					/* automatic double buffering */
    VERTICAL_ORIENTATION,					/* show reels vertically */
    5,							/* 5 reels in group */
    3*SYMBOL_HEIGHT,					/* 3 symbols visible */
    1*SYMBOL_HEIGHT,					/* symbol 1 of 3 is winline */
    {&reels[0],&reels[1],&reels[2],&reels[3],&reels[4]},	/* the 5 reels declared above...*/
    { 30,220,410,600,790},					/* ...and their screen x coordinates */
    {200,200,200,200,200}					/* ...and their screen y coordinates */

    };

    /* defined elsewhere */
    #define SYMBOL_HEIGHT	120

Next we need to specify the two different reelbands required:

    (config.c)

    /* table of image addresses in video memory */
    ULONG image_address[6];

    /* index for above table */
    enum images {
    CHERRY, ORANGE, PEAR, LEMON, BELL, BAR
    };

    const LONG reelband1_table[10] = {
    CHERRY, PEAR, CHERRY. ORANGE. CHERRY, LEMON, CHERRY, BELL, CHERRY, BAR
    };
    REELBAND reelband1 = {
        10,			/* reel has 10 symbols */
        160,			/* symbol width 160 pixels */
        120,			/* symbol height 120 pixels */
        image_address,		/* symbol image address table  */
        image_address,		/* alternative symbol image address table  */
        reelband1_table		/* table indexes - defines reelband symbols */
    };

    const LONG reelband2_table[10] = {
    LEMON, PEAR, LEMON, ORANGE, LEMON, CHERRY, LEMON, BELL, LEMON, BAR
    };
    REELBAND reelband1 = {
        10,			/* reel has 10 symbols */
        160,			/* symbol width 160 pixels */
        120,			/* symbol height 120 pixels */
        image_address,		/* symbol image address table  */
        image_address,		/* alternative symbol image address table  */
        reelband2_table		/* table indexes - defines reelband symbols */
    };

Next, we inform the video reel driver about this reelgroup. This is done via the driver configuration structure, read by the driver on loading

    (config.c)

    const VIDEOREELCFG VideoReelCfg[] = {
        {&reelgroup, NULL}
    };

Driver Installation

Now we must add the driver to the list of drivers in devices.c in the project directory

    (devices.c)

    const	INSTALLDEVICE	DeviceList[ ] =
    {
        ...
        ...
        {&Calypso32Dual0Device	,0,0,0},
        {&Calypso32Dual1Device	,0,0,0},
        {&VideoReelDevice	,0,0,0},
        ...
        ...
        {0,0,0}
    };

Example Video Initialisation

(game code...)

#define DISPLAY_START	(LONG) (0x00000000)
#define LAYER_WIDTH	(LONG) (1024)
#define LAYER_HEIGHT 	(LONG) (768)

const DEVICE* dev;
LONG free_memory_address;
LONG middle_layer_address;

dev = &Calypso32Dual0Device;

/* initialise video memory and define middle layer  */

middlelayer_address 	= DISPLAY_START;
free_memory_address	= CalypsoInitLayer(dev, ML_LAYER, COLOR_16, DOUBLEBUFFER,
0, LAYER_WIDTH, LAYER_HEIGHT, middlelayer_address);

CalypsoSetFrameRate(dev, FRAME_60HZ);
CalypsoClearLayer(dev, ML_LAYER, DOUBLEBUFFER_FRAME0);
CalypsoClearLayer(dev, ML_LAYER, DOUBLEBUFFER_FRAME1);
CalypsoEnableLayer(dev, MIDDLE_SELECT);

Reel Initialisation

(game code...)

#define MAXSPEED	30	/* maximum rotation speed in steps per video frame */
#define INCR		2	/* rampup accn in steps per video frame */
#define DECR		2	/* rampup deaccn in steps per video frame */
#define OVERSHOOT	10	/* overshoot in steps */

/* table of image addresses in video memory */
extern ULONG image_address[ ];

/* images files */
extern const CALYPSOIMAGE cherry, orange, pear, lemon, bell, bar;

REELGROUP *rg;
VIDEOREEL *reel;
REELBAND *reelband;

/* load reel symbol images and fill in table of symbol image addresses */

image_address[CHERRY]	= free_memory_address;
image_address[ORANGE]	= CalypsoLoadSprite(dev, image_address[CHERRY], &cherry);
image_address[PEAR]	= CalypsoLoadSprite(dev, image_address[ORANGE], &orange);
image_address[LEMON]	= CalypsoLoadSprite(dev, image_address[PEAR], &pear);
image_address[BELL]	= CalypsoLoadSprite(dev, image_address[LEMON], &lemon);
image_address[BAR]	= CalypsoLoadSprite(dev, image_address[BELL], &bell);
free_memory_address	= CalypsoLoadSprite(dev, image_address[BAR], &bar);

/* Initialise reels */

rg = &reelgroup;

for(r=0; r < rg -> nreels; r++) {
    reel = rg -> reel[r];

    if(r<3)
        reelband=&reelband1;	/* reels 0-2 use reelband 1 */
    else
        reelband=&reelband2;	/* reels 3-4 use reelband 2 */

    VideoReelSetParameters(rg, reel, reelband, MAXSPEED, INCR, DECR, OVERSHOOT);

    VideoReelInit(reel, 0);		/* initialise reels with first symbol at win line */
    VideoReelShow(rg, r); 		/* and paint reel to display */
}

Reel Movement Code

(game code...)

LONG r. spinning;
LONG winline[5];
REELGROUP *rg;
VIDEOREEL *reel;

reelgroup = &reelgroup0;

reel = rg->reel[0];

VideoReelStep(reel, 2, NORMAL_SPIN);			 /* step reel 0 forwards two symbols */
while(VideoReelStatus(reel) != REEL_IDLE)		/* finished? */
    ;
VideoReelStep(reel, 1, REVERSE_SPIN); 			/* step reel 0 backwards one symbol */
while(VideoReelStatus(reel) != REEL_IDLE)		/* finished? */
    ;

reel = rg->reel[1];

VideoReelSpinToSymbol(reel, 7, 3, NORMAL_SPIN); 	/* spin reel 1 seven revs, stop at symbol 3 */
while(VideoReelStatus(reel) != REEL_IDLE)		/* finished? */
    ;
VideoReelSpinToSymbol(reel, 0, 5, REVERSE_SPIN); 	/* spin reel 1 backwards to symbol 5 */
while(VideoReelStatus(reel) != REEL_IDLE)		/* finished? */
    ;

reel = rg->reel[2];

VideoReelSetSpeed(reel, 10);				/* set reel 2 to a slower speed */
VideoReelStart(reel, NORMAL_SPIN)			/* start reel 2 spinning forwards... */
Wait(400);						/* ...wait a bit */
VideoReelStop(reel);					/* ...and stop reel 2 */
while(VideoReelStatus(reel) != REEL_IDLE)		/* finished? */
    ;
VideoReelSetSpeed(reel, MAXSPEED);			/* restore reel 2 maximum speed */

for(r=0; r < reelgroup->nreels; r++) {			/* spin all reels 3 revolutions forwards */
    reel = rg->reel[r];
    VideoReelSpinToSymbol(reel, 3, 0, NORMAL_SPIN);
}

do {
    reels_spinning=0;
    for(r=0; r < reelgroup->nreels; r++)
        reel = rg->reel[r];
        if(VideoReelStatus(reel != REEL_IDLE)
            reels_spinning=1;
    }
} while(reels_spinning);				/* wait till all reels stopped */

for(r=0; r < reelgroup->nreels; r++) {
    reel = rg->reel[r];
    winline[r] = VideoReelStatus(reel);
}
some_function(winline);			 		/* some function using the win line */
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

DetectStepMotorOptos

LONG DetectStepMotorOptos(const DEVICE* dev)

Description

Read the status of the optical position sensor of each motor.

Parameters

Parameter | Description
dev | Address of the stepper device.

Return Value

Return a 32 bit integer with each bit representing the status of each motor. A 1 means the motor is at its reference position (the sensor is read as active). The least significant bit represents the first motor (motor index = 0). Unused bits are set to zero.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Software Standard Peripherals

Stepper Motor Driver

GetStepMotorPosn

WORD GetStepMotorPosn(const DEVICE* dev, WORD motidx)

Description

Return the current motor position. The relationship between motor position and physical motor steps is contained in the motor type structure.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies which motor to get the position of. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c

Return Value

Returns the current motor position in the range 0 to N-1 (where N is the number of motor position in a complete revolution)

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


config.c

Configuration File

The file config.c in the project directory allows the game developer to provide configuration options for some of the Pluto 6 software drivers. The configuration options are applied to the drivers on installation. In the example projects default configuration options are provided for the configurable drivers.

Pluto 6 Configurable Drivers

The following Pluto 6 drivers are configurable:

Driver | Configuration Information
Advanced Video Driver | Advanced Video Driver Configuration Data
Multiplexed Inputs Driver | MXI Configuration Data
Outputs Driver | Outputs Configuration Data
Serial Communications Drivers | Serial Communications Configuration Data
PIC18 Customer Security Device Driver | PIC18 Customer Security Device Configuration Data
E2ROM Device Driver | E2ROM Device Configuration Data
Vacuum Fluorescent Display Drivers | VFD Configuration Data
ATA Driver | ATA Configuration Data
Timers Driver | Timer Configuration Data
Stepper Motor Driver | Stepper Configuration Data
Touchscreen Driver | Touchscreen Controller Configuration
E2ROM Driver | E2ROM Configuration

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.
Document No: 80-17314, Issue 10 Release Date: 04.01.08 Email: support@heber.co.uk www.heber.co.uk


File Types

The following file types used in the Pluto 8 software either contain, or are related to source code for the system:

.c file | C source file. The source code for the Pluto 8 is structured so that a .c file exists for each system device driver or sub-set of functionality.
.h file | .c header file that contains any defines and type definitions that are associated with in the c source file of the same name. The .h file #includes the prototypes file. By including the .h file for a given .c file access is given to all of the functions and variables that are declared public in that .c file.
.p file | Prototype file that is automatically generated by the make utility. The prototype file contains the declarations for all of the public functions and variables in the given .c file.
.sp file | Static prototype file that is automatically generated by the make utility. The static prototype file contains function declarations for all of the local functions for a given .c file. This file should only be #included in the .c file of the same name.
.d file | Dependency file. The dependency file is automatically generated by the make utility, and lists paths to files upon which a .c file may be dependent.
.s file | Motorola assembly source file.
.elf file | GCC ELF binary executable file output from the compiler.
.o file | Compiled object file for a module created by the compiler.
.a file | Archive file. An archive file contains all of the compiled objects for a module, for example, libperipherals.a contains all of the objects for the peripherals module.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Memory Management

Memory Management

The GNU linker maps the Pluto 8 software to physical locations on the control board using values defined in the linker script.

SDRAM (128Mb)

The Pluto 8 control board is fitted with 128MB of SDRAM used to store application code. The address range of the SDRAM is from 0x60000000 to 0x67FFFFFF.

Non-Volatile SRAM (upto 2Mb)

Pluto 8 is fitted as standard with 1MB of battery backed SRAM with the memory range of 0x10000000 - 0x100FFFFF. It is possible to build boards with 2MB of battery backed SRAM with the memory range of 0x10000000 - 0x101FFFFF.

Stack

The ColdFire® has a 32k byte module of SRAM using the memory range 0xE001_0000 - 0xE001_7FFF. This module has faster access speed than external SDRAM and is used to hold the stack.

© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 8 Memory Map

Memory Map

MCF5475 ®ColdFire Internal Memory

TBD

The ColdFire® has a 32 bit wide data bus.
8Kbytes are organised as 2k x 32 bits.

Fast internal RAM used for the stack runs from address 0x5000 0000 to 0x5000 1fff.

The linker script defines this memory to be:

stacka : ORIGIN = 0x50000000, LENGTH = 0x00001f00
fram : ORIGIN = 0x50001f00, LENGTH = 0x000000ff

Note: The fram area is redundant and is not used.

Video RAM

The Video RAM has a 32 bit wide data bus.
The Video RAM runs from address 0x3000 0000 to 0x31ff ffff (32Mbytes of memory).

The Video driver uses some of this memory from address 0x31fc0000 to the end, to store various registers and display lists.

Memory that is left is user area, which can be used to store, for example, images and screen data.

DRAM

The DRAM has a 16 bit wide data bus.
DRAM is used for code space and contains game code.

The DRAM is 2Mbytes in size and runs from address 0x6000 0000 to 0x601f ffff.

In the Demo Project, the linker script defines this memory to be:

rom : ORIGIN = 0x60000000, LENGTH = 0x0016fefc

Note: You can store data other than code in this area by changing the linker script.

SRAM

The SRAM has an 16 bit wide data bus.
The SRAM runs from address 0x1000 0000 to 0x 1003 FFFF (256Kbytes of memory).

This memory can be subdivided into several areas:

  • Some of the memory is used by the Boot Loader (IDRAM and SYSRAM) as backed up memory (preserved on power down).
  • Some of the memory is used by the game (IDRAM and SYSRAM) as backed up memory (preserved on power down).
  • Some of the memory is used by our libraries as standard RAM.

Most of the SRAM is available to the game code.

The linker script defines this memory to be:

For the Boot Loader:

keepram : ORIGIN = 0x10000000, LENGTH = 0x00000400
ram : ORIGIN = 0x10010400, LENGTH = 0x0002fc00

In the Game Project:

keepram : ORIGIN = 0x10000400, LENGTH = 0x00001000 ram : ORIGIN = 0x10010400, LENGTH = 0x0002fc00

Flash Memory (Boot Flash)

The Boot Flash has an 8 bit wide data bus.
The Boot Flash runs from address 0x0000 0000 to 0x0007 ffff.

In the Boot Loader project, the linker script defines the memory space to be 4Mbytes:

rom : ORIGIN = 0x00000000, LENGTH = 0x003ffefc

The socket U1 on the Pluto 6 board contains a M29W040B Boot Flash device. The M29W040B is a 512Kbyte device.

Alternatively an EPROM plug in memory can be used with Pluto 6 which allows the full 4Mbyte to be implemented.

FPGA

The FPGA space starts at 0x2000 0000 and contains:

  • Lamp multiplex memory
  • Registers for 2 FPGA UARTS
  • Input/output space
  • UART routing control
  • Audio registers
  • Miscellaneous FPGA registers.
© HEBER LTD. 2008. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.