Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileGEMDOSProcessesThe GEMDOS call Pexec() is responsible for launching executable files. The
process which calls Pexec() is called the parent and the file launched
becomes the child. Each process may have more than one child process.
Depending on the mode used with Pexec(), the child may share data and
address space and/or run concurrently (under MultiTOS) with the parent.
GEMDOS executable files (GEM and TOSapplications or desk accessories)
contain the following file header:
Name Offset Contents
PRG_magic 0x00 This WORD contains the magic value (0x601A).
PRG_tsize 0x02 This LONG contains the size of the TEXT
segment in bytes.
PRG_dsize 0x06 This LONG contains the size of the DATA
segment in bytes.
PRG_bsize 0x0A This LONG contains the size of the BSS
segment in bytes.
PRG_ssize 0x0E This LONG contains the size of the symbol
table in bytes.
PRG_res1 0x12 This LONG is unused and is currently
reserved.
PRGFLAGS 0x16 This LONG contains flags which define
certain process characteristics (as
defined below).
ABSFLAG 0x1A This WORD flag should be non-zero to
indicate that the program has no fixups or
0 to indicate it does. Since some versions of TOS handle files with this value being
non-zero incorrectly, it is better to
represent a program having no fixups with
0 here and placing a 0 longword as the
fixup offset.
Text Segment 0x1C This area contains the program's TEXT
segment. A process is started by JMP'ing
to BYTE 0 of this segment with the address
of your processes basepage at 4(sp).
Data Segment PRG_tsize This area contains the program's DATA
+ 0x1C segment (if one exists).
Symbol Segment PRG_tsize This area contains the program's symbol
+ PRG_dsize table (if there is one). The symbol table
+ 0x1C area is used differently by different
compiler vendors. Consult them for the
format.
Fixup Offset PRG_tsize This LONG indicates the first location in
+ PRG_dsize the executable (as an offset from the
+ PRG_ssize beginning) containing a longword needing
+ 0x1C a fixup. A 0 means there are no fixups.
Fixup Information PRG_tsize This area contains a stream of BYTEs
+ PRG_dsize containing fixup information. Each byte
+ PRG_ssize has a significance as follows:
+ 0x20
Value Meaning
0 End of list.
1 Advance 254 bytes.
2-254 (even) Advance this many bytes and
fixup the longword there.
PRGFLAGS is a bit field defined as follows:
Definition Bits Meaning
PF_FASTLOAD 0 If set, clear only the BSS area on program load,
otherwise clear the entire heap.
PF_TTRAMLOAD 1 If set, the program may be loaded into alternative
RAM, otherwise it must be loaded into standard RAM.
PF_TTRAMMEM 2 If set, the program's Malloc() requests may be
satisfied from alternative RAM, otherwise they must
be satisfied from standard RAM.
- 3 Currently unused.
See left. 4 & 5 If these bits are set to 0 (PF_PRIVATE), the
processes' entire memory space will be considered
private (when memory protection is enabled). If these
bits are set to 1 (PF_GLOBAL), the processes' entire
memory space will be readable and writable by any
process (i.e. global). If these bits are set to 2
(PF_SUPERVISOR), the processes' entire memory space
will only be readable and writable by itself and any
other process in supervisor mode. If these bits are
set to 3 (PF_READABLE), the processes' entire memory
space will be readable by any application but only
writable by itself.
- 6-15 Currently unused.
When a process is started by GEMDOS, it allocates all remaining memory,
loads the process into that memory, and JMP's to the first byte of the
application's TEXT segment with the address of the program's basepage at
4(sp). An application should use the basepage information to decide upon
the amount of memory it actually needs and Mshrink() to return the rest to
the system. The exception to this is that desk accessories are only given
as much space as they need (as indicated by their program header) and
their stack space is pre-assigned.
The following code illustrates the proper way to release system memory
and allocate your stack (most 'C' startup routines do this for you):
stacksize = $2000 ; 8K
.text
_start:
move.l 4(sp),a0 ; Obtain pointer to basepage
move.l a0,basepage ; Save a copy
move.l $18(a0),a1 ; BSS Base address
adda.l $1C(a0),a1 ; Add BSS size
adda.l #stacksize,a1 ; Add stack size
move.l a1,sp ; Move your stack pointer to
; your new stack.
suba.l basepage,a1 ; TPA size
move.l a1,-(sp)
move.l basepage,-(sp)
clr.w -(sp)
move.w #$4a,-(sp) ; Mshrink() trap #1
lea 12(sp),sp ; Fix up stack
; and fall through to main_main:
...
.bss
basepage: ds.l 1
.end
The GEMDOSBASEPAGE structure has the following members:
Name Offset Meaning
p_lowtpa 0x00 This LONG contains a pointer to the Transient Program
Area (TPA).
p_hitpa 0x04 This LONG contains a pointer to the top of the TPA + 1.
p_tbase 0x08 This LONG contains a pointer to the base of the text
segment
p_tlen 0x0C This LONG contains the length of the text segment.
p_dbase 0x10 This LONG contains a pointer to the base of the data
segment.
p_dlen 0x14 This LONG contains the length of the data segment.
p_bbase 0x18 This LONG contains a pointer to the base of the BSS
segment.
p_blen 0x1C This LONG contains the length of the BSS segment.
p_dta 0x20 This LONG contains a pointer to the processes' DTA.
p_parent 0x24 This LONG contains a pointer to the processes'
parent's basepage.
p_reserved 0x28 This LONG is currently unused and is reserved.
p_env 0x2C This LONG contains a pointer to the processes'
environment string.
p_undef 0x30 This area contains 80 unused, reserved bytes.
p_cmdlin 0x80 This area contains a copy of the 128 byte command line
image.
Processes terminate themselves with either Pterm0(), Pterm(), or
Ptermres(). Ptermres() allows a segment of a file to remain behind in
memory after the file itself terminates (this is mainly useful for TSRTermitate and Stay Resident programm
utilities).
The Atari Extended Argument SpecificationWhen a process calls Pexec() to launch a child, the child may receive
a command line up to 125 characters in length. The command line does not
normally contain information about the process itself (what goes in
argv[0] in 'C'). The Atari Extended Argument Specification (ARGV) allows
command lines of any length and correctly passes the child the command
that started it. The ARGV specification works by passing the command tail
in the child's environment rather than in the command line buffer.
Both the parent and child have responsibilities when wanting to correctly
handle the ARGV specification. If a process wishes to launch a child with
a command line of greater than 125 characters it should follow these
steps:
1. Allocate a block of memory large enough to hold the existing
environment, the string 'ARGV=' and its terminating NULL, a string
containing the complete path and filename of the child process and its
terminating NULL, and a string containing the child's command line
arguments and its terminating NULL.
2. Next, copy these elements into the reserved block in the order given
above.
3. Finally, call Pexec() with this environment string and a command line
containing a length byte of 127 and the first 125 characters of the
command line with a terminating NULL.
For a child to correctly establish that a parent process is using ARGV it
should check for the length byte of 127 and the ARGV variable. Some parents
may assign a value to ARGV (found between the 'ARGV=' and the terminating
NULL byte). It should be skipped over and ignored. If a child detects that
its parent is using ARGV, it then has the responsibility of breaking down
the environment into its components to properly obtain its command line
elements.
It should be noted that many compilers include ARGV parsing in their basic
startup stubs. In addition, applications running under MultiTOS should use
the AES call shel_write() as it automatically creates an ARGV environment
string.