Release Notes 
*************

This note is about the Hitachi H8/300 Developer's Kit: what's in it
and how to install it.


Release Contents 
****************

The programs in this Developer's Kit are shipped as binaries,
preconfigured to run on i386 and i486 IBM-PCs and PC clones running 
standard MS/DOS.

The individual programs in the Developer's Kit are:
   
   * AR.EXE             the library maintainer
   * AS.EXE             the assembler
   * CC1.EXE            the compiler backend
   * CPP.EXE            the C preprocessor
   * GDB.EXE            the GNU debugger
   * EMU387             the 80387 emulator
   * GCC.EXE            the H8/300 C compiler driver
   * GO32.EXE           the DOS extender
   * LD.EXE             the H8/300 linker
   * NM.EXE             print symbols in object file
   * INFO.EXE           the documentation browser
   * RUN.EXE            the H8/300 simulator
   * OBJDUMP.EXE        analyse object file
   * RANLIB.EXE         build library table of contents
   * SIZE.EXE           print size of sections in object file
   * STRIP.EXE          remove symbols from object file
   
Supported Platforms 
*******************

*Intel i386 and i486 DOS machines.*
     Release h8300--8 of the Hitachi Developer's Kit is supported on 
     any 80386-based IBM compatible PC or PS/2 with 512K RAM (though at 
     least 4Mb of RAM is recommended) and a hard disk.
     
     Up to 128M of extended memory will be used if present, and up to 
     128M of disk space can be used for swapping. Disk caching programs 
     will speed compilation greatly.
     
*Other Platforms*
     The Developer's Kit is also available on the Sun-4.
     
     
Testing the Installation 
========================

Your Developer's Kit includes a `test' batch file and subdirectory
which you can use to perform a quick "sanity check" on the installation.

Type the following (but remember to type the name of your hard disk
where we show "c:", and the path to your installation directory where 
we show "\h8300"):

     C:\> cd \h8300\test 
     C:\H8300\TEST> test c:\h8300
     
If the Developer's Kit is correctly installed, you should see output
like this:

     C:\H8300\TEST> set PATH=c:\h8300\bin;\DOS;... 
     C:\H8300\TEST> set GO32=emu c:\h8300\bin\emu387 
     C:\H8300\TEST> set C_INCLUDE_PATH=c:\h8300\include 
     C:\H8300\TEST> set LIBRARY_PATH=c:\h8300\lib 
     C:\H8300\TEST> set TMPDIR=c:\h8300\tmp 
     C:\H8300\TEST> set GO32TMP=c:\h8300\tmp 
     C:\H8300\TEST> mkdir c:\h8300\tmp
     C:\H8300\TEST> gcc -g -S t.c 
     C:\H8300\TEST> as -o t.o t.s
     C:\H8300\TEST> ld -o t.x c:\h8300\lib\crt0.o 
			  t.o c:\h8300\lib\libc.a
     C:\H8300\TEST> ld -relax -o t.xs c:\h8300\lib\crt0.o
			       t.o c:\h8300\lib\libc.a
     C:\H8300\TEST> size t.x
     text    data    bss     dec     hex     filename 
     7462    338     1362    9162    23ca    t.x 
     C:\H8300\TEST> size t.xs
     text    data    bss     dec     hex     filename 
     7466    338     1362    9066    236a    t.xs
     
     
Running the on-line help information
************************************

To run the on-line help files, you need to execute the command:

     C:\H8300\BIN> info -d c:\h8300\info

This will execute the on-line help program.


Running the Programs 
********************

   Some preliminary steps are needed to run the DOS to H8/300
cross-compiler and debugger effectively.

Environment Variables 
=====================

   To run the compiler at all, you first have to set some environment
variables so that the compiler can find its supporting programs and 
files.  (Most of the output from the `test' batch file showed setting 
these variables).  The environment variables need to refer to the 
directory where you installed the Developer's Kit; we'll refer to that 
path as INSTALLDIR.

First of all, add `INSTALLDIR\bin' to your `PATH' variable.
   
Then set these other variables:
   * C_INCLUDE_PATH, where the C compiler looks for include files.  (Set
     this to `INSTALLDIR\include'.)
   * LIBRARY_PATH, where the linker looks for the C libraries.  (Set
     this to `INSTALLDIR\lib'.)
   * TMPDIR, where the compiler builds temporary files.  (Set this to
     any convenient directory on a hard drive with space available.)
   * GO32, telling the DOS extender where to find the 387 emulator.
     (Set this to `INSTALLDIR\bin\em387'.  If you have floating point 
     hardware, the emulator will use that instead, regardless of whether 
     you set this value.)
   * GO32TMP, where the DOS extender keeps its temporary files.  (You
     can usually set this to the same path as TMPDIR.)
     
For example, something like this could go into the `AUTOEXEC.BAT'
initialization file if you installed into `c:\h8300':

     PATH=....; c:\h8300\bin 
     C_INCLUDE_PATH=c:\h8300\include 
     LIBRARY_PATH=c:\h8300\lib 
     INFOPATH=c:\h8300\info 
     TMPDIR=c:\h8300\tmp
     set GO32=emu c:\h8300\bin\em387 
     set GO32TMP=c:\h8300\tmp
     
Remember that the commands in the `AUTOEXEC.BAT' file will not take
effect until you reboot your machine.

Disk Cache 
==========

While not strictly necessary to run the cross-compiler, using a good
disk cache will noticeably reduce the time the compiler spends building 
your H8/300 programs.  `SMARTdrive', for example, is a cache program 
that comes with DOS from version 5 onwards; refer to your DOS manual 
for details on how to use it.

Communicating With Your H8/300 
==============================

The GNU debugger, `gdb', depends on an auxiliary
terminate-and-stay-resident program `asynctsr' to communicate with the 
H8/300 development board through a serial port.   You must also use the 
DOS `mode' command to set up the serial port on the DOS side.

The following sample session uses the H8/300 program `t.x' generated
by the `test' batch file (*note Testing the Installation: Testing.).

First hook up your H8/300 development board.  In the example, we use
a board attached to serial port `COM2'; if you use a different serial 
port, substitute its name in the argument of the `mode' command. When 
you call `asynctsr', the auxiliary comms program used by the degugger, 
you give it just the numeric part of the serial port's name; for 
example, `asyncstr 2' below runs `asyncstr' on `COM2'.

     C:\H8300\TEST> mode com2:9600,n,8,1,p
     
     Resident portion of MODE loaded
     
     COM2: 9600, n, 8, 1, p
     
     C:\H8300\TEST> asynctsr 2
     
*Warning:* We have noticed a bug in PC-NFS that conflicts with 
`asynctsr'.  If you also run PC-NFS on your DOS host, you may need 
to disable it, or even boot without it, to use `asynctsr' to 
control your H8/300 board.
     
Now that serial communications are set up, and the H8/300 is
connected, you can start up `gdb'.  Call `gdb' with the name of your 
program as the argument.  `gdb' prompts you, as usual, with the prompt 
`(gdb)'.  Use two special commands to begin your debugging session: 
`target hms' to specify cross-debugging to the Hitachi board, and the 
`load' command to download your program to the board. `load' displays 
information about your program's section layout as it downloads the
code:

     C:\H8300\TEST> gdb t.x
     GDB is free software and you are welcome to distribute copies
      of it under certain conditions; type "show copying" to see 
      the conditions.
     There is absolutely no warranty for GDB; type "show warranty" 
     for details.
     GDB 4.5, Copyright 1992 Free Software Foundation, Inc... 
     (gdb) target hms
     Connected to remote H8/300 HMS system. 
     (gdb) load t.x
     .text   : 0x8000 .. 0xabde *********** 
     .data   : 0xabde .. 0xad30 *
     .stack  : 0xf000 .. 0xf014 *
     
At this point, you're ready to run or debug your program.  From here
on, you can use all the usual `gdb' commands, as described in `Using 
GDB: the GNU Debugger'.  The `break' command sets breakpoints; the 
`run' command starts your program; the `continue' command resumes 
execution after stopping at a breakpoint.  You can use the `help' 
command at any time to find out more about `gdb' commands.

One final note-use the RESET button on the H8/300 board
   * to interrupt your program (don't use `ctl-C' on the DOS host-it
     has no way to pass an interrupt signal to the H8/300); and
     
   * to return to the `gdb' command prompt after your program finishes
     normally.  The communications protocol provides no other way for 
     `gdb' to detect program completion.
     
     
Where to report bugs 
********************

If you find a bug in this release, please report it to Hitachi 
America, Ltd. or to Cygnus Support. You may report the bug through 
many methods (telephone call, US mail, or through Internet electronic 
mail). 

To send something via US Mail, please send it to the following
locations:

     Hitachi America, Ltd.              
     2000 Sierra Point Parkway          
     MS-260
     Brisbane, CA 94005, USA            
     phone: +1 415 589 8300                    
     email: `app-eng@halsp.hitachi.com' 
     fax: +1 415 583 44207              

     Cygnus Support
     814 University Avenue 
     Palo Alto, CA 94301, USA
     +1 415 322 3811
     hotline: +1 415 322 7836 
     email: `bugs@cygnus.com' 
     fax: +1 415 322 3270


Cygnus and FSF Releases 
***********************

The subroutine library provided in the release comes from many
sources. Parts are from a BSD release; these parts are copyright 
Regents of the University of California.  Some other parts have been 
generously donated to Cygnus by Tadpole Technology plc.  Some parts 
have been developed by Cygnus.  In all cases, you can use the 
subroutines without restriction.

Many of the programs in this Developer's Kit are originally from the
Free Software Foundation, and versions of all these tools can be 
obtained from the FSF as well as from Cygnus.  Cygnus improves FSF 
materials in these ways:

   * Commercial support is available.  Cygnus adds value to FSF
     releases in large measure by offering outstanding support services.
     
   * Bug fixes.  Cygnus performs necessary repairs to bugs discovered
     during testing, and also tracks and includes bug fixes developed 
     for other Cygnus customers or distributed over the Internet.
     
   * Documentation.  Cygnus has revised and added to available FSF
     documentation to give you better descriptions of all the software 
     tools.
     
   * Coordination.  The tools in your Developer's Kit are certified to
     work together; you need not worry about one tool being ahead of 
     another.
     
     
Cygnus Support 
**************

Cygnus Support was founded in 1989 to provide commercial support for
free software.  Cygnus supplies products and services that benefit 
advanced development groups by allowing them to use state-of-the-art 
tools without having to maintain them.  With Cygnus Support, sites that 
once were forced to do their own tool support can recover that valuable 
staff time.  Former users of proprietary software now may choose 
supported free software, combining the advantages of both worlds.

Free software is faster, more powerful, and more portable than its
proprietary counterparts.  It evolves faster because users who want to 
make improvements are free to do so.  Cygnus tracks these improvements 
and integrates them into tested, stable versions ready for commercial 
use, then backs this software with comprehensive support.

With Cygnus Support as your partner, you will have the software and
the support you need to meet your business objectives better.  Cygnus 
is intimately familiar with this software from extensive experience 
using, debugging, and implementing it.  You get direct access to the 
most qualified support people: the authors of the software.

We provide "vintage" releases-the most stable versions, which have
been though even more extensive use and testing-or up-to-the minute 
"progressive" releases, for those who need the very latest version.

Because all our improvements are also free software, you can
distribute them widely within your organization, or to your customers, 
without extra cost.

     Cygnus Support
     814 University Avenue 
     Palo Alto, CA 94301, USA
     +1 415 322 3811
     hotline: +1 415 322 7836 
     email: `info@cygnus.com' 
     fax: +1 415 322 3270

