This file documents the routines available from UNIT_HCS08Z.DLL in both
C++ and PASCAL format. The routines are explained here and are
prototyped for ease of use in the following files:

   INSTALLDIR\msvc50\unit_hcs08.h      - For MSVC 5.0+
   INSTALLDIR\Delphi20\headerhcs08.pas  - For Delphi 2.0+

If you add the above mentioned interface file (and associated .CPP
file for the C++ compilers) to your own application, you will be able
to directly access all the HCS08 BDM routines.

For C++ applications: The unit_hcs08.cpp file contains a load_dll()
routine which will load the DLL into memory and allow you to access
all the following routines. For Pascal applications, the DLL loading
is transparent to the user.

To make sure the interface cable firmware is up to date, make sure to place
the latest firmware update files in the same directory as you application. These
files are documented in the DEPLOYHCS08.TXT file.

The following calls are now legacy calls. They are still valid but are not the
recommended method for initializing P&E debug interfaces:

init_port
init_port_usb
query_number_of_usb_devices
query_number_of_parallel_ports
get_usb_port_device_serial_number

Note : Before unloading the library, the close_port function should be called.

Note : A "bool" is a 1-byte variable.

NOTE : When using the USB or Ethernet as a communications medium, it
       is important to make use of the block data transfer calls to
       obtain the best possible performance.

Note : The firmware upgrade files must reside in the same directory as
       your final application. The upgrade files are necessary to
       insure that the hardware interface is of a sufficient firmware
       revision to enable all debug functionality. The following firmware
       files should be distributed:

**********************************************************************
And here they are...
**********************************************************************

bool load_dll;
/* For C/C++ applications. Loads the DLL into memory and gives the user
   access to all the following functions.  This routine must be called
   before any of the other routines can be called. The unit library
   DLL (application extension) must be in either the current application's
   directory, or the Windows System directory. Returns TRUE if
   successful. */

reenumerate_all_port_types
/*
This call rescans the USB and Ethernet ports to enumerate all the P&E
hardware interfaces which are connected via these mediums. This call also
scans the system for the number of serial ports and parallel ports without
actually attempting any communications with these ports (so as not to disturb
any running hardware). The number of each type of port or device may be
read via the "get_enumerated_number_of_ports" call, and a description of a
specific port/device may be read via the "get_port_descriptor" call. The
port/device may be opened with the "open_port" call and closed with the
"close_port" call. */

get_enumerated_number_of_ports
/*
This returns the number of ports/devices of a certain port type which have been
enumerated either by loading the DLL or by a call to the
"reenumerate_all_port_types" function. The result depends on which porttype
constant is passed to the routine.


get_port_descriptor
/*
Returns a pointer to a null terminated string which describes the port indicated
by the PortType and PortNum. The PortType indicates the type of port/device and
the Portnum should be a value from 1 to the number of enumerated devices for
this port type (see "get_enumerated_number_of_ports"). The resultant value is
good until the next call to the P&E DLL.
*/


function get_port_descriptor_short
/*
Returns a very short description of the port. The following information is
reported:
  PortType_ParallelPortCable     : Address of port string
  PortType_PCIBDMLightning       : Address of lightning card string
  PortType_USBMultilink          : Serial number string
  PortType_CycloneProMaxSerial   : port number string
  PortType_CycloneProMaxUSB      : Cyclone Pro Name
  PortType_CycloneProMaxEthernet : IP number string.
*/

function open_port
/*
Opens a communication channel to the appropriate interface device/port. Returns
whether an error occured during this process. This does not necessarily indicate
positive communications between the PC and attached P&E interface. After this
routine is called, the "reset_cable" routine may be used to establish
communications with the P&E interface (the result of which can be tested with
the "check_cable_error" function). The PortType parameter indicates the type of
port/device and the Portnum parameter should be a value from 1 to the number
of enumerated devices for this port type (see "get_enumerated_number_of_ports").
After all communications have completed, and before this DLL is unloaded, the
calling application should call the "close_port" call.
*/

version 
/* Returns a char pointer to a null-terminated string containing the
   version number of the interface library. */


reset_cable
/* resets the cable*/

force_background_mode
/*Forces target into background  */

read_data_long
/* Reads data in the CPU address space  */

read_data_word 
/* Reads data in the CPU address space  */

read_data_byte
function read_data_byte(address : longint) : byte;  
/* Reads data in the CPU address space  */

write_data_long
/* Writes the data into the CPU address space */

write_data_word 
/* Writes the data into the CPU address space */

write_data_byte
/* Writes the least significant byte of DATA into the specified CPU address.  */

resume;  
/* Causes the cpu to resume execution at the current program counter.
   Execution continues until something forces the CPU into the background
   debug mode. */

single_step;  
/* Causes the CPU to execute a single instruction at the current program
   counter. */

data_from_cpu_value
/* Contains the value of the data most recently shifted in from the
   processor. Used for compatibility with 16-bit unit library version. */

load_bin_file
/* Loads binary information from filename a file. */

load_srec_file
/* Loads S records from a file */

test_for_freeze
/* checks whether or not the target is stopped */

go_to_background
/* Tries to place the CPU into the background mode via the background
   command (without resetting the target).  */


procedure put_cpu_values
/* Write the HCS08 CPU Registers with new values */



get_cpu_values

/* Returns the current values of the CPU registers */


check_cable_error
/* This flag indicates whether we are not communicating with the BDM 
Interface cable. 
*/


read_status
/*
This returns the value of the BDCSCR status and control register
*/

write_control
/*
This allows the user to set the value of the BDCSCR register. Note that not
all bits are writable.
*/


do_sync_and_set_io_delay_cnt
/*
   This routine uses a SYNC pulse to time how fast the target is running and sets the
   io_delay_cnt accordingly, both on the PC and in the BDM interface cable. This routine
   can be called at any time and does not attempt a reset of the target. The OB1, OB2
   parameters are not used, and are included for cross platform compatibility. The
   SYNC_PULSE_WIDTH_IN_MS is the length of the SYNC command that the BDC cable uses in
   order to get a sync response from the target. A value of 10 (10 milliseconds) should
   work for most any target frequency. This function results with whether a proper
   response to the SYNC pulse was detected or not.
*/


set_protocol_options
/*
The set_CLKSW_bit_on_reset determines whether P&E automatically boost up the
connection speed on reset. The do_sync_during_step determines whether P&E does
a SYNC function after each and every single_step is called and before P&E
attempts to read the status register to see if it is done. The default of both
of these functions is true;
*/

write_breakpoint
/* Writes the unsigned short value into the BDCBKPT register */

short read_breakpoint
/* The result is the value read from the BDCBKPT register */

get_dll_version
/*
Returns the DLL version
*/

get_cable_version
/*
Returns the cable firmware version 
*/

read_voltage
/*
Returns the voltage of the Vdd pin on the BDC header.

*/

read_bdc_frequency
/* This queries the cable for the current BDC frequency in hz. */.


put_data_byte_block
/*
This routine uses a special download mode in the BDC debug protocol
to write a block of memory down into the target without much overhead. 
*/


get_data_byte_block
/*
This routine uses a special blocking mode in the BDC debug protocol
to read a block of memory from the target into a buffer on the PC. 
*/

close_port; 
/*
   Close the port opened with the open_port call.
*/

(C)opyright 2005, P&E Microcomputer Systems, Inc. All rights reserved.
Visit us at http://www.pemicro.com