Pure C
4/18/92
Pure C English Overview
(or, "What Your 'Mutter' Never Told You About Pure C")
by Dan Wilga
Document Copyright (c) 1992 by Gribnif Software
The Pure C package comes, as you have probably noticed by this time, with
German documentation. As this is not likely to change in the near future, we
have decided to present people who purchase the package from us with a
description of the important features of the programs in English.
Certainly, the information in this document is far from the content of the full
manuals. However, careful attention has been paid to covering those details
which would not normally be obvious without understanding the manuals.
We strongly suggest that you read as much of this document as possible. While
you may never use some of the information covered, many important features of
the package may be revealed to you by reading it fully.
Installation
------------
Probably the easiest way to install Pure C is in the format in which it is
provided. Simply create a PURE_C folder somewhere on one of your hard drives
(with about 2 Mb free) and copy the contents of all three disks into it.
This is a description of the major files in the distribution:
PC.PRG Programming environment
PC.CFG Default configuration file
CPP.TTP Pure C compiler pre-processor
PCC.TTP Pure C compiler
PCC.CFG Pure C compiler default configuration
PD.PRG Pure Debugger
PD.CFG Default configuration file
BGIOBJ.TTP Converts BGI fonts to .O files
DISPOBJ.TTP Display object files
HC.TTP Help compiler
PASM.TTP Pure Assembler
PLINK.TTP Object file linker
C.HLP C language help
LIB.HLP C libraries help
PASM.HLP Pure Assembler help
PD.HLP Pure Debugger help
FONTS\ Fonts used by BGI routines
PC_FSEL\ Replacement file selector
PC_HELP\ Help desk accessory
INCLUDE\ Header files
LIB\
PC881LIB.LIB 68881/2 floating point library
PCBGILIB.LIB Borland Graphics Interface library
PCEXTLIB.LIB Pure C extensions library (see: ext.h)
PCFLTLIB.LIB Floating point library
PCGEMLIB.LIB AES/VDI library
PCLNALIB.LIB Line A library
PCSTDLIB.LIB Standard library (stdio, etc.)
PCTOSLIB.LIB BIOS/XBIOS/GEMDOS library
PCSTART.S Source for default runtime module
PCSTART.O Object file for same
PCVSTART.S Source for runtime module with extended argument (ARGV)
passing
PCVSTART.O Object file for same
PCXSTART.S Source for runtime module with i/o redirection as part of
commandline
PCXSTART.O Object file for same
The Pure C Environment (PC.PRG)
-------------------------------
While the separate parts of the Pure C compiler/assembler/debugger can all be
used independently, the easiest way to manage a large project is by using the
integrated environment, PC.PRG.
Editing Keys
------------
Shift up arrow Scroll up one page
Shift down arrow Scroll down one page
Shift left arrow Move to start of line
Shift right arrow Move to end of line
Control left arrow Move to start of word
Control right arrow Move to start of next word
Backspace Delete character to left of cursor
Delete Delete character to right of cursor
Home Start of file
Shift Home End of file
Control Y Yank (cut) current line
Click Move cursor
Shift click Add to selection
Double-click Select word
Shift double-click Select an entire line
Undo Undo last keystroke
Insert Same as Paste
Note that using the scroll bar does not affect the cursor location. This
means that if you use the scroll bar to reposition the file being edited and
then type a character, that character will appear where the cursor was (and
still is) before the window was scrolled.
If a block is selected when a normal key is pressed on the keyboard, that
entire block will be replaced with the one character, so caution should be
used.
Error Message Windows
---------------------
A second type of window, which cannot be edited, appears when the compiler
generates error messages. The contents of this window can be viewed like
other text windows, but they cannot be changed. To quickly jump to a
particular error in the appropriate source file, simply double-click anywhere
on an error message. This action is similar to the "Find Error" menu entry.
Pure C's Help System
--------------------
Yet another type of window which can be opened is for help messages. There
are two ways to access the help, either directly from the menu or by pressing
the Help key. In the case of the Help key, the help libraries will be
searched for an entry which matches the word currently under the cursor. This
can be especially helpful for situations where you cannot remember what
parameters to pass to a library function.
Help Window Controls
--------------------
Double-click on an underlined word or phrase Jump to that help reference
Help key while cursor is at underlined word Jump to that help reference
Undo key Back up to previous help
screen
Another use of the help system is to point out the declaration of a
variable, constant, or function *within your own source code*. For instance,
if you are working on a program which uses a number of header files to define
variables and you want to find out how the variable "MaxValue" is defined,
you simply have to place the edit cursor on the word "MaxValue" somewhere in
the source code and press the Help key. If you have just recently compiled
your program (and Pure C's internal caches have not been flushed) then the
header file in which "MaxValue" is declared will be opened and the
appropriate line will be shown. Note that this feature cannot work if you
quit Pure C and then re-run it, because the caches are flushed; you must
re-compile the program.
The Item Selector
-----------------
Pure C employs (yet another!) enhanced item selector which offers many
advantages to the standard Atari item selector. All of its operations can be
controlled from the keyboard:
Alt <drive letter> Select disk drive
Up/Down arrows Change selected file/folder
Return Open selected folder/file
Insert New filename
Delete Delete selected file
Esc Swap disks (update file list)
Undo Back up one directory level
Control-U Exit item selector (like Cancel button)
Extensions (*.C, *.H, etc.) See page 15 of your Pure C Compiler manual
One other nice feature of the item selector is the ability to select a file
or folder from a long list by simply typing the first few characters of its
name. For instance, suppose you have the following items:
*BIN
*LIB
BAR.C
FOO.C
FOX.C
ZZZ.C
To open the LIB folder, you merely have to press 'L' (select the folder) and
then hit the Return key (Open it). To open the file FOX.C, in this case, you
can either press 'F' and then move the selection down one line with the down
arrow key, or you can type 'OX' to narrow the search. In either case,
pressing Return will cause the file FOX.C to be opened.
Modifications of Menu Commands
------------------------------
Two menu commands have alternate forms which are not otherwise obvious:
Control Shift Q Quit without autosaving configuration
Shift Alt D Debug, removing PC.PRG from memory first
Compiler Options
----------------
Some of the compiler options are explained in more detail here. The remainder
can be found in the "Compiler..." dropdown menu entry.
-2 Generate 68020 code. Resulting program will not run on a 68000 CPU!
-8 Generate 68881 code.
-A Non-ANSI keywords "cdecl" and "pascal" will generate errors.
-B Write objects (.O) in DRI format, instead of Pure C format. If this
switch is on, then the Pure Debugger will not be able to use a
source file window because the DRI format does not permit extended
debugging information.
-E# Maximum number of error messages before break.
-F# Maximum number of warning messages before break.
-H Force "cdecl"-style function calling. Passes parameters on stack
instead of in CPU registers.
-L# Maximum identifier length.
-M No string merging. Normally, Pure C checks to see if part of one
string can actually be defined as being the tail end of another. An
example would be the two strings "nobody" and "body", which could
be merged into one string. This option can be disabled if your code
needs to modify static string contents without affecting other
strings.
-Nname Output file directory.
-Oname Output file name.
-P Use absolute calls (JSR's) instead of PC-relative ones. If you get
a linker error which says there is a "16-bit PC-relative overflow",
this option must be used.
-S Standard stackframes, using LINK and UNLINK instructions.
-T Stack checking. An error message will be produced if insufficient
stack space has been reserved.
-Wxxx Disable (-W-xxx) or enable (-Wxxx) a compiler warning message.
Similar to the #pragma warn preprocessor directive. Options:
Adherance to ANSI standards:
-Wdup Redefinition of XXX is not identical. (default: ON)
-Wret Both return and return of a value used. (ON)
-Wstr XXX not part of a structure. (ON)
-Wstu Structure XXX is not defined. (ON)
-Wsus Suspicious pointer conversion. (ON)
-Wvoi Void functions may not return a value. (ON)
-Wzst Zero length structure. (ON)
Common Warning Messages:
-Waus XXX is assigned a value which is never used. (ON)
-Wdef Possible use of XXX before definition. (ON)
-Weff Code has no effect. (ON)
-Wpar Parameter XXX is never used. (ON)
-Wpia Possibly incorrect assignment. (ON)
-Wrch Unreachable code. (ON)
-Wrvl Function should return a value. (ON)
Less Common Warnings:
-Wamb Ambiguous operators need parentheses. (OFF)
-Wamp Superfluous & with function or array. (OFF)
-Wnod No declaration for function XXX. (OFF)
-Wpro Call to function with no prototype. (ON)
-Wstv Structure passed by value. (OFF)
-Wuse XXX declared but never used. (OFF)
Portability Warnings:
-Wapt Non-portable pointer assignment. (ON)
-Wcln Constant is long. (OFF)
-Wcpt Non-portable pointer comparison. (ON)
-Wrng Constant out of range in comparison. (ON)
-Wsig Conversion may lose significant digits. (OFF)
-Wucp Mixing poiners to signed and unsigned char. (OFF)
-Wrpt Non-portable pointer conversion. (ON)
-X Generate underbars. All identifier names are preceded with a "_"
character. This is mostly for compatibility with Mark Williams C
modules.
-Y Add debug information for use with the Pure Debugger. This option must
be set in order to get a C-source window within the debugger.
Preprocessor
------------
The only unusual preprocessor directive supported by Pure C is #pragma. In
this implementation, the only option is "warn", for enabling or disabling
certain compiler warnings. The syntax is always one of these:
#pragma warn -w (enable all warnings)
#pragma warn -xxx (where "xxx" is a warning type to disable)
#pragma warn +xxx (where "xxx" is a warning type to enable)
For a list of the warning types, refer to the -W compiler option.
Pure C defines several preprocessor constants:
__LINE__ Line number.
__FILE__ Name of file being compiled.
__DATE__ File compilation date.
__TIME__ File compilation time.
__STDC__ True (1) if the "ANSI keywords only" (-A) option is used.
__PUREC__ Contains the version number of the compiler. Useful
as a check to see if the Pure C compiler is being used.
__TURBOC__ Same as __PUREC__.
__TOS__ Always 1.
Assembler Options
-----------------
The -1, -2, -3, -4, -5, and -8 options can be used to prevent an error
message when the assembler encounters an instruction which is not part of the
standard 68000 instruction set. Similarly, the -S option prevents errors from
being generated when a supervisor mode instruction is encountered.
The -U option forces all undefined symbols to be considered external. This
avoids having to use the IMPORT and EXPORT assembler directives.
Linker Options
--------------
The stack size for a program depends on many factors, such as the number and
size of local variables, the level to which function calls are nested, and
the number of parameters passed in function calls. The -T (stack checking)
compiler switch can be helpful for determining the correct stack size for a
particular program. Note that because Pure C normally passes function
arguments in CPU registers, the amount of stack space required by a Pure C
program can be significantly less than that required by other compilers.
Options G, L, and Y should always be set if you intend to use the resulting
program with the Pure Debugger. The program should be re-linked without these
options to produce the final version, as this consumes much less disk space.
The -F option prevents the FastLoad bit from being set in the program's
header. This attribute only affects programs which are run by TOS versions
1.4 or newer. This attribute must NOT be set (that is, you should use the -F
option) for any program which can be run as a desk accessory, since the
operating system can crash when a desk accessory has this attribute set.
The -J option generates a new object file. This can also be used to create a
linkable library from several .O files.
The -R and -M options affect operation on the Atari TT computer, which has
both fast RAM and normal ST RAM. If your program will be performing raw disk
i/o or setting the screen display base to a block of memory it receives by
way of the Malloc call, then the -M flag should be set so that the Malloc
will return a block of memory in ST RAM rather than Fast RAM.
The segment addresses should normally be left blank. They are intended for
linking position-dependent code, such as something that will be burned into
ROM.
Project (.PRJ) Files
--------------------
The syntax for Project files follows. Items in braces {} are optional. A bar
| denotes a choice between two options.
{ output_file | * }
{ .L [ <linker_options> ] }
{ .C [ <compiler_options> ] }
{ .S [ <assembler_options> ] }
=
<module_name1> { ( <dependent_files> ) }
<module_name2> { ( <dependent_files> ) }
...
Each module_name can either be an asterisk "*", to represent the topmost
source file window, or one of the following:
<assembler_file> { [ <assembler_options> ] }
<C_source_file> { [ <compiler_options> ] }
<object_file>
<library_file>
<project_file>
The order in which modules appear in the list dictates the order in which
they are linked. For this reason, the startup module should always come first
and the libraries should usually come last.
This sample project file will compile the files MYACC1.C (which is the
topmost window), MYACC2.C, MYACC3.S, and will link the standard and GEM
libraries. The compiler switch for 68020 code is enabled for MYACC2.C, and
the assembler switch for priviledged instructions (-S) is set globally. The
file MYACC1.C depends on the file HEADER.H not having changed since the last
compilation. The output file is MYACC1.ACC.
*.ACC ; topmost window name with ACC extension
.S[-S] ; assembler options
=
PCSTART.O ; startup module comes first
* (HEADER.H) ; compile topmost window MYACC1 if it or
; HEADER.H has changed
MYACC2.C [-2] ; compile MYACC2.C with 68020 code generation
MYACC3.S ; assemble with options above
PCSTDLIB.LIB ; link standard library
PCGEMLIB.LIB ; link AES/VDI library
The Runtime Startup Modules
---------------------------
Pure C includes several different compiler startup modules, for different
purposes. Most likely, you will probably want to use the default, PCSTART.S.
Essentially, these startups all perform the same actions:
Find out how much memory the program requires and return (Mshrink) unused
memory.
Parse the commandline and prepare a list of pointers to the individual
parameters.
Prepare a list of pointers to the environmental variables.
Determine if the computer has a floating point math coprocessor.
Call the main portion of the program.
Clean-up any malloc'd blocks and open files.
Terminate.
A program's "main" function receives three parameters: argc, argv, and envp.
The first two are common to most C compilers. The envp parameter is a pointer
to a null-termianted array of pointers to environmental variables. For
example, to display a program's environment, you could use:
int main( int argc, char *argv[], char *envp[] )
{
while( *envp )
{
printf( *envp );
envp++;
}
}
Please note that since the runtime startups all look at the return value from
"main" and return this to the process which executed the program, it is a
good practice to always return something, most likely zero. In the case of
the sample program above, a line with "return 0;" should be added.
Writing Desk Accessories
------------------------
Pure C's startup modules all contain a test to see if a particular program is
running as a desk accessory or as a regular program. The int "_app", which is
defined in AES.H, is zero if the program is running as a desk accessory.
Helpful Hints
-------------
Using CFG and PRJ files:
Whenever you begin a new project, it is a good idea to start by establishing
a new configuration (CFG) file. This can be done by selecting the "Load..."
option in the "Options" drop-down menu. If you press the New button in the
item selector, you will be asked for the name of a new CFG file.
From this point, you should set the compiler and assembler options to the
way you will want them for the particular program you are compiling. You
should also create a new project (PRJ) file or select an exisiting one. Be
sure to Save Configuration if you do not have the Autosave option turned on.
Now, whenever you want to work on the program further, you can simply call up
the "Load..." menu entry and give it the name of the CFG file. Another method
is to use the desktop's Install Application feature to install PC.PRG for the
extension CFG. This way, you simply have to double-click on the CFG file to
get PC.PRG to come up with the correct files loaded.
Using warning level 1:
In the Compiler Options dialog, there are three warning levels which can be
used:
0 Ignore all warning messages
1 Produce some warning messages
2 Produce all warning messages
Experience has shown that, for most applications, number 1 is probably the
best choice. This level corresponds to the ON/OFF defaults listed in the
section of this document which describes the -W compiler switch. Level 0
ignores so many warnings that the code which is generated may not be runable
if the -H compiler switch is not used.
Pre-defined Data Types
----------------------
Type sizeof Bits Range
---- ------ ---- -----
unsigned char 1 8 0 to 255
char 1 8 -128 to 127
enum 2 16 -32768 to 32767
unsigned short 2 16 0 to 65535
short 2 16 -32768 to 32767
unsigned int 2 16 0 to 65535
int 2 16 -32768 to 32767
unsigned long 4 32 0 to 4294967295
long 4 32 -2147483648 to 2147483647
<pointer> 4 32
float 4 32 (+-)3.4E-38 to (+-)3.4E+38
double 10 80 (+-)3.3E-4932 to (+-)1.2E+4932
long double 10 80 (+-)3.3E-4932 to (+-)1.2E+4932
Zeiger 4 32 0 to 4294967295
The format for floating point numbers is IEEE-standard.
The Help Compiler
-----------------
Pure C includes a help compiler program (HC.TTP) which can be used to create
your own help files.
HC accepts the name of a file as its only parameter. This file must be in the
following format:
<options>
<HLP_file_name>
<source_file1>
<source_file2>
...
The options available are:
L Produce a log file
N Parse source file, but do not generate help file
T=n Expand tabs to "n" characters, where 0 < n <= 9. The default is 4.
V Verbose message output
W Break on warnings
Here is a sample command file:
-LVT=8 ; log file on, verbose output, tab size=8
USR.HLP ; Help file name
USR.TXT ; Source file
The source files for the help compiler contain blocks of separated text. The
basic format is:
screen( "<first screen name>" )
Help text here
more help text
\end
screen( "<second screen name>" )
Help text
\end
The screen names are the index entries which trigger the help text which
follows. More than one screen name can also be specified for the same text:
screen( "Cat", "Dog", "Fish" )
Household pets
\end
Context-sensitive help (which can be accessed with the Help key) can also be
generated by using the directives "sensitive" and "capsensitive":
screen( "Index entry #1", sensitive( "keyword" ) )
This text will display for "Keyword", "KEYWORD", or even "kEYwoRd"
\end
screen( "Index entry #2", capsensitive( "Key" ) )
This text will only display for the word "Key"
\end
Help screens can also be linked by using the sequence \#. The following two
help messages are linked together:
screen( "First" )
This is some text.
\end
screen( "Second" )
Double-click on the underlined part to go to the \#First\# text.
\end
The use of \# depends on the contents of the text between the markers.
Another directive, \link, can also be used so that the name of the actual
help screen need not appear:
screen( "Second" )
\link( "First" ) Double-click here\# to go to the first screen.
\end
Both the PC_HELP desk accessory and the on-line help in the Pure C
environment look for a file called USR.HLP. This file can contain your own
help messages which will be scanned whenever the help system is accessed by
either of these two methods.
The Pure Debugger
-----------------
The majority of the options in the Pure Debugger should be self-evident.
However, a few things should be pointed out.
First of all, probably the most useful thing of all is the double-click. It
can be used to change breakpoints, file contents, variables, memory, and just
about everything else. When the Inspect option is displaying the value of an
array or structure, you can even double-click on a portion of the variable to
get another window with a full display of its value. Try this with a nested
structure to see for yourself.
Setting a simple breakpoint can be accomplished by clicking once with the
mouse within the narrow column on the left side of a source file or assembly
listing window. Double-clicking will bring up a dialog with more detailed
options. Remember that you can use any combination of these options; you can
even have a global breakpoint (which will break anywhere in the program) by
turning off the "Breakpoint at:" option. The program will execute much more
slowly, but this can be very useful nonetheless.
When a program is running, you can get back to the debugger at any time by
pressing Alt-Help.
The main difference between a Watched value and an Inspection is that when a
pointer is being examined, a Watch tends to change more often. This is
because an Inspection deals with indirected values, whereas a Watch deals
with the actual value before indirection, and the actual value is more likely
to change than the place it points to.
The following reserved names for CPU registers (as well as a program's
variable names) can be used as part of an expression for most addresses, even
things like the address at which to Dump memory:
Pseudo Variable Data Type
D0-D7 unsigned long
A0-A7 char *
PC char *
FP0-FP7 long double
USP char *
SSP char *
Remember that if you want the Pure Debugger to use the source code in its
displays, you must not only compile C modules with the -Y option, but you
must also link using the -G, -L, and -Y options.
One hint: if your program intercepts system vectors, you should always try
to make sure that you allow it to finish before quitting the debugger.
Otherwise, very nasty things can happen.
Pure Assembler
--------------
The format used by Pure C's assembler is essentially the same which is used
by other assemblers, such as Atari's MADMAC. The following directives are
implemented. Each can be preceded with a period ("."), though this is not
required. Directives which take a "size" can have one of the following
values:
symbol type length (bytes)
.b byte 1
.w word 2
.l long 4
.s single precision real 4
.x extended precision real 10
.p packed BCD 12
Constants can begin with various prefixes:
$ hexadecimal
0x hexadecimal
0X hexadecimal
% binary
@ octal
<none> decimal
A constant can also contain underscores (_) to separate its digits for
clarity. For instance, one million could be written 1_000_000. Floating point
numbers can be written in the same formats that a C compiler understands.
String constants an begin with ' or ". A string constant must end with the
same character it begins with. A constant can even be used in normal
instructions:
move.b #'A', d0 ; set d0.b to 65
Directives:
expression = value Assign a value. For instance: ROM_base = $fc0000
*= expression Set position forward. For instance, to leave a gap of
256 bytes: *= $100
ALIGN [expression] Fills with null bytes until the next address divisible
by "expression" is encountered. The default value for
"expression" is 2 (word alignment).
ALINE #expression Generates a Line A instruction. Ex:
ALINE $10 ; generates opcode $A010
ASCII string[,string...]
A string of characters, without a NUL at the end. Ex:
hello: ASCII "Hello there!", "How are you?"
ASCIIL string[,string...]
A string of characters, preceded by a length byte. Ex.:
these two are equivalent:
ASCIIL "Hello World!"
; and
DC.B 12
ASCII "Hello World!"
ASCIIZ string[,string...]
A string of characters followed by a NUL byte. Ex.:
these two are equivalent:
ASCIIZ "Hello World!"
; and
ASCII "Hello World!"
DC.B 0
BSS [expression] Enter the BSS segment. All subsequent instructions
BSS "name" will become part of this segment, until a DATA or TEXT
directive is encountered. "expression" can be the
number of a segment, from 0 to 3. A "name" for a
segment can also be given. When the linker links the
segments, it always goes in order from 0 to 3.
COMM label,expression
Defines a block of "expression" NUL-filled bytes in
the BSS segment.
DATA [expression] Enter the DATA segment. All subsequent instructions
DATA "name" will become part of this segment, until a BSS or TEXT
directive is encountered. "expression" can be the
number of a segment, from 0 to 3. A "name" for a
segment can also be given. When the linker links the
segments, it always goes in order from 0 to 3.
DC[.size] expression[,expression...]
Defines a constant in the current segment. Each
"expression" in the list is "size" bytes long.
DCB[.size] count[,expression...]
Defines "count" repetitions of the remaining
expressions. Ex.:
dcb.l 2,-2 ; result: $FFFFFFFEFFFFFFFE
dcb.w 2,3,4 ; $0003000400030004
dcb.b 3,"ABC" ; $414243414243414243
DS[.size] expression
Reserves "expression" NULL bytes. Used primarily in
the BSS segment.
ELSE See IF.
END End assembly. Text following END is not evaluated.
ENDC See IF.
ENDIF Same as ENDC. See IF.
ENDM End macro definition. See REPT and MACRO.
ENDMOD Ends a module. See MODULE.
EQU label, expression
label EQU expression
This performs the same function as using = or SET.
ERROR "message" Terminate the assembler with an error message.
EVEN Perform word-alignment by inserting a NUL byte, if
necessary.
EXITM Exits a macro without processing it any further.
EXPORT label[,label...]
Defines a label as being global. This is necessary for
the linker to resolve external references to a label.
FLINE #expression Generates a Line F instruction. Ex:
FLINE $10 ; generates opcode $F010
GLOBL label[,label...]
Defines one or more labels as being imported into the
assembly module, or as being exported out of it.
IFcc expression Conditional assembly. The condition code, "cc" can be
<statements> one of the following:
[ELSE IF exp exp != 0
<statements>] IFF exp exp == 0
ENDIF IFB arg macro arg is not supplied
IFNB arg macro arg is supplied
IF1 first assembler pass
IF2 second pass
IFEQ exp exp == 0
IFNE exp exp != 0
IFLE exp exp <= 0
IFLT exp exp < 0
IFGE exp exp >= 0
IFGT exp exp > 0
IMPORT label[,label...]
Defines a label as being contained in another module.
This is necessary for the linker to resolve external
references to a label.
INCLUDE "filename" Includes (assembles) a secondary file.
INCLUDE 'filename'
LCOMM label,expression
Reserves "expression" bytes in the BSS segment with the
"label".
LIST All text following a LIST directive appears in the
listing file generated during assembly. Use NOLIST to
disable the list.
LOCAL label[,label...]
Defines a local label within a macro in the form
____XXXX, where "XXXX" is from 0000 to 9999. For
example:
macro absolute
local end
tst.w d0
bge end
neg.w d0
end:
endm
absolute ; uses label ____0000
absolute ; uses label ____0001
MACRO name[.size] [[param1],param2...]
<statements>
ENDM
Define a macro with name "name". For example:
macro Push.size parm
move.size parm,-(sp)
endm
Push.l d0 ; generates move.l d0,-(sp)
Push d0 ; generates move d0,-(sp)
To substitute a parameter within a macro in a place
which is not preceded with a separator, the & can be
used:
macro PushData RegNumber
move.l D&RegNumber, -(sp) ; move.l Dx, -(sp)
endm
MC68000 Selects the specific type of code to be generated by
MC68010 the assembler.
MC68020
MC68030
MC68040
MC68851
MC68851 -
MC68881 [expression]
MC68881 -
MODULE label Defines a module with name "label". A module serves as
a convenient way of preventing the linker from treating
different occurences of the same label within one
source file as the same occurence. This is similar to
the behavior which occurs when multiple assembly source
files are used. Note that for library creation, all
the individual routines should either be declared as
independent MODULEs, or they should be in separate
source files. A MODULE should end with ENDMOD.
NOLIST Turn off the listing feature. See LIST.
OFFSET [expression] Generate constants which define the number of bytes
from the start of the OFFSET block. An OFFSET block is
terminated by changing segments with TEXT, DATA, or BSS
directives:
; Generate offsets for the elements of the C
; structure:
; struct list
; {
; struct list *next;
; char name[20];
; }
OFFSET
next: ds.l 1 ; next gets 0
name: ds.b 20 ; name gets 4
EVEN
TEXT
move.l next(a0), a0
lea name(a0), a1
ORG expression Advance position by "expression" bytes. Same as *=.
PAGE [expression] Set the page length for listings to "expression". If no
value is given, a form feed is generated.
PRINT ["message"] Prints a message within a listing. If no message is
given, a newline is generated.
REG label,registerlist
label REG registerlist
Defines a register list for the MOVEM instruction. Ex.:
SavedRegs REG A2-A4/D3
movem.l #SavedRegs, -(sp)
...
movem.l (sp)+, #SavedRegs
REPT expression Repeat statements "expression" times.
<statements>
ENDM
SET label, expression
label SET expression
Same as = and EQU.
TEXT [expression] Enter the TEXT segment. All subsequent instructions
TEXT "name" will become part of this segment, until a DATA or BSS
directive is encountered. "expression" can be the
number of a segment, from 0 to 3. A "name" for a
segment can also be given. When the linker links the
segments, it always goes in order from 0 to 3.
SUPER Select the supervisor instruction set.
TTL "title" Define the title for a listing file. The name of the
source file can be included in "title" by using %f.
Ex.: TTL "Listing for source file %f."
USER Select the user instruction set.
XDEF label[,label...]
Exports labels for use in external modules. See EXPORT.
XREF label[,label...]
Imports labels from external modules. See IMPORT.
The Pure Assembler will normally try to optimize certain instructions. For a
list of which instructions are optimized, see pages 189-190 of the Pure
Assembler manual.
Assembly Language Considerations: Parameter Passing
---------------------------------------------------
The Pure C compiler passes function parameters in CPU registers to improve
performance. The data registers D0, D1, and D2 are for passing char's, int's,
and long's. The address registers A0 and A1 are for passing pointers. Any
parameters which cannot fit into the correct set of registers are passed on
the stack. This includes data types such as "double" and all structures.
To determine which parameter is passed in which register, the function should
be evaluated from left to right. For instance, say we have the following
function prototype:
int foo( char d1, char *p1, struct xx *p2, long *p3, int d2, GRECT g1,
long d3 )
and this function was being called as follows:
foo( 'A', string, xxptr, longptr, val, grect,
43L )
In this case, the compiler might generate code which looks something like
this:
moveq.l #43, D2 ; parameter d3 into D2 register
lea grect+8(pc), a0 ; get address of end of grect structure
move.l -(a0), -(a7) ; push last two elements
move.l -(a0), -(a7) ; push first two elements
move val, D1 ; parameter d2 into D1 register
move.l longptr, -(a7) ; goes on stack because A0 and A1 to be used
move.l xxptr, A1 ; parameter p2 into A1 register
move.l string, A0 ; parameter p1 into A0 register
move #'A', D0 ; parameter d1 into D0 register
jsr foo ; call foo
This type of parameter passing can be defeated in two ways: either with the
-H compiler switch, or by declaring the function to be of type "cdecl". For
example, to pass all parameters to the function above on the stack, you could
use:
int cdecl foo( ...
Certain system vector routines (like the critical error handler) can be
directly replaced by a Pure C function if the "cdecl" type is used in the
function's declaration.
Another implicit case when all parameters are passed on the stack is when
the ANSI C ellipses operator ("...") is used. One example of this is the
printf function:
int printf( const char *format, ... )
The compiler uses D0-D2/A0-A2 for parameter passing and for temporary
storage. This not only means that any assembly module MUST save any other
registers it uses, it also means that any routine which calls a routine
compiled by Pure C will most likely have these registers destroyed. For this
reason, special care must be taken when writing interrupt handlers using Pure
C.
Assembly Language Considerations: Return Values
-----------------------------------------------
Return values of type char, int, and long are always returned in the D0 CPU
register. Pointers are always returned in the A0 register. More complex data
types, such as "double" actually return their values using a pointer to a
variable of that type which is passed on the stack. For instance, the
following function:
double donothing(void)
{
return 1.0;
}
when called might generate something like this:
lea 10(a7), a0 ; a pre-defined storage space on the stack
move.l a0, -(a7) ; push it
jsr donothing
The function "donothing" simply takes this pointer and modifies it:
donothing: move.l 4(a7), a0 ; get pointer to return
move.l #..., (a0)+ ; set the value...
move.l #..., (a0)+
move #..., (a0)
rts