.title ^^CP/M-68K Cross Software for VMS
.nofill

.bl 4
.c
CP/M-68K Cross Software for VMS
.c
-------------------------------
.bl 2
.c
Revision 01.04
.c
--------------
.bl 2
.c
August 28, 1983
.c
---------------
.bl 12
.c
Digital Research, Inc
.c
P.O. Box 579
.c
Pacific Grove, CA  93950
.c
(408) 649-3896
.c
TWX 910 360 5001
.bl 4
.c
************************
.c
* Company Confidential *
.c
************************
.bl 4
.fill
Note:  This document contains Digital Research proprietary information, and
must not be copied or distributed for any purpose whatsoever, without prior
written permission of Digital Research, Inc.
.bl 2
Address Comments to: Steve Williams, x6082
.subtitle Introduction
.page
.hl 1 Introduction
.i 5
This document describes the installation and execution procedures for the
Digital Research 68000 cross development software for VAX/VMS.  This software
includes the C compiler, assembler, linker, archiver, symbol table print
utility, object module size utility, and S-Record conversion utility.  These
tools execute in much the same fashion as they do under CP/M-68K, as 
documented in the CP/M-68K Programmer's Guide.
.subtitle Installation Procedures
.hl 1 Installation Procedures
.i 5
The tools are distributed on a 9-track FLX format mag tape (either 800 or
1600 bpi is available).  To bring up the software on VMS, perform the
following steps:
.ls
.le;Login to a valid account.
.le;Create directories for four ersatz devices: "bin:" (.exe files), "com:"
(command files), "lib:" (library files), and "cpm:" 
(CP/M-68K files).
.le;Enter VMS "ASSIGN" commands for these directories in LOGIN.COM,
e.g:
.bl 1
.nofill
$ assign drb0:[c.bin] bin:
$ assign drb0:[c.com] com:
$ assign drb0:[c.lib] lib:
$ assign drb0:[c.cpm] cpm:
.bl 1
.fill
Note that the full path name must be specified.
.le;Perform the above assignments manually, re-login or re-execute LOGIN.COM
to make the device names valid.
.le;Read the tape as follows:
.bl 1
.nofill
$ allocate mt:
$ mount mt:/foreign
$ set def lib:
$ mcr flx /rs=mt:[1,1]*.*/do/im
$ mcr flx /rs=mt:[1,2]*.*/do
$ set def bin:
$ mcr flx /rs=mt:[1,3]*.*/do
$ set def cpm:
$ mcr flx /rs=mt:[1,4]*.*/do/im
$ mcr flx /rs=mt:[1,5]*.*/do
$ set def com:
$ mcr flx /rs=mt:[1,6]*.*/do
$ _@install
$ dismount mt:
$ deallocate mt:
.fill
.bl 1
You may need to replace the "mt:" device name above with a different device
name, depending on the type of tape drive you have.  Consult your system
administrator for details.
.le;Add the statements in the file "xlogin.com" to LOGIN.COM so that the
proper command definitions are performed at login time.
.els
Once the above steps have been performed, the software is ready to use on 
VMS.
.subtitle Operating Instructions
.hl 1 Operating Instructions
.i 5
The following sections describe how to run the installed cross software on
VMS.
.hl 2 C compilation
.i 5
A C compilation is performed using the 'c68' command as follows:
.bl 1
.i 8
$ c68 file
.bl 1
The ".c" extension is implied and must not be specified.  The 'c68' command
is extremely similar to the 'C' SUBMIT file on CP/M-68K.
Default floating point format is Motorola FFP using the "c68" command. 
The "ce68" command causes the compiler to use IEEE format floating point
numbers.
.hl 2 Assembly
.i 5
The assembler is invoked in exactly the same manner as on CP/M-68K.  The 
output (listing and errors) can be redirected to a file or device using the
">filename" construct.  A sample command is:
.bl 1
.i 8
$ as68 -l -u -p file.s >file.lis
.bl 1
This command assembles "file.s" and places the object in "file.o".  The 
listing is output to "file.lis".  All assembler options valid under CP/M-68K
may be used on VMS as well.
.hl 2 Linking
.i 5
The LO68 program is used with the same options and command line syntax as on
CP/M-68K.  For example,
.bl 1
.i 5
$ lo68 -r -o file.rel file1.o file2.o
.bl 1
links "file1.o" with "file2.o", creating "file.rel", a relocatable format
file.
.bl 1
.i 5
C programs are linked using the "clink" command, as with CP/M-68K:
.bl 1
.i 5
$ clink file1
.bl 1
This links "file1.o" with the C runtime software to produce "file1.rel", a 
relocatable format 68000 load module.
Separately compiled modules may be linked in the following way:
.bl 1
.i 5
$ clink file1 file2 file3 file4 ...
.bl 1
All of the object files are linked to produce "file1.rel".  A limit of 9 such
files is imposed by the command file.
.bl 1
.i 5
The "clink" command procedure assumes that the program being linked does not
use floating point.  To link a program using FFP floating point, use
"clinkf" instead of "clink".  IEEE floating point programs (those compiled
with the "ce68" command) are linked using "clinke".
.hl 2 Archive Files
.i 5
The CP/M-68K archive program (AR68) can be used under VMS exactly in the same
fashion as under CP/M-68K.  For example, to create a library file:
.bl 1
.i 8
$ ar68 r lib a.o b.o c.o 
.bl 1
This command creates a library called "lib" containing the three files "a.o",
"b.o", and "c.o".
.subtitle Building CP/M-68K
.hl 1 Building CP/M-68K
.i 5
Using the VAX cross tools to build CP/M-68K is similar to building the
operating system on CP/M.  You link the BIOS with CPMLIB to produce a
relocatable image file (CPM.REL).  Use the RELOC utility to create the 
absolute load image (CPM.SYS).  The CP/M-68K SUBMIT files "LCPM.SUB" and
"RELCPM.SUB" have been adapted to VMS procedure files to make this process
easier.
.bl 1
.i 5
For example, to create the EXORmacs distribution system, use the following
sequence of commands:
.bl 1
.nofill
.lm +8
$ set def cpm:
$ _@normbios	 !Create "bios.o"
$ _@lcpm	 !Create "cpm.rel"
$ _@relcpm 15000 !Create CPM.SYS at 15000 hex.
.lm -8
.fill
.bl 1
The boot loader for CP/M-68K is generated in a similar fashion, as documented
in the CP/M-68K System Guide.
.subtitle File Transfer Techniques
.hl 1 File Transfer Techniques
.hl 2 S-records
.i 5
The normal method of transferring files to a 68000 target is via Motorola 
S-records.  The SENDC68 program converts a load module file from binary format
to S-record format.  The command syntax for this program is:
.bl 1
.i 8
SENDC68 [-] file.68k >file.sr
.bl 1
Where "file.68k" is an absolute format CP/M-68K load module, and "file.sr"
is the created S-record file.  This form of the load module may be created
using the linker "-t" switch or the reloc utility.  The RELCPM command used
in the CP/M-68K generation procedure generates an absolute file.
The "-" option specifies that S-records are
not to be created for the ".bss" segment.  The default is to create S-records
that zero all locations in the ".bss".  
.bl 1
.i 5
The resulting S-record file may be downloaded via the VMS "TYPE" command into
a target system with a PROM debugger, such as the MACSbug program on the
EXORmacs.  
.hl 2 Other Transfer Techniques
.i 5
Other techniques such as binary download utilities or CP/M file transfer
utilities may be used to transfer CP/M-68K load modules to the 68000 target.
When such a technique is used, the bytes in the file must be swapped, and
the words of all longword quantities in the load module header must be 
swapped.  Library modules may not be transferred using this technique without
extensive rearrangement of the headers.  The symbol table in object and
load module files will have the symbol names byte swapped in this type of
transfer.
.hl 1 Trademarks
.i 5
VAX, VMS, and FLX are trademarks of Digital Equipment Corporation.  EXORmacs,
and MACSbug are trademarks of Motorola, Inc.  CP/M-68K is a trademark of
Digital Research, Inc.
