Amiga Executable Loading Help

[KennyOfTrains]

I'm trying to work out how some of the low-level CLI executable loading works on the Amiga, but I've hit several unknowns that I'm hoping someone on here can point me in the right direction for. I'm disassembling the original 'echo' command from Workbench 1.3.2 as a test case to understand how it works, but I've hit snags.

First up, the executable contains two HUNK_CODE sections, but no relocations. I thought relocations were needed to update the code in each section to be able to find the other. How does this work without them?

To try to find clues, I disassembled the first few instructions from each of the two sections, but they both read registers immediately. It's as if the code expects the loader to have left the processor in a specific state, but I can't find what that is.

I haven't done any development on the Amiga, but I'm familiar with C and x86 assembly on other platforms.

If someone could point me toward a good reference for the machine state when a CLI program starts, that'd be brilliant. I've skimmed the Amiga Assembly Language Programming book by Jake Commander, but it doesn't go into that level of detail, and searching the AKRM docs on amigadev.elowar.com hasn't found anything yet.

Many thanks

[a/b]

Before each hunk in memory, there is a 32-bit b-ptr to the next hunk, so they can be deallocated after exiting (bcpl ptr, have to multiply by 4 before you use it). So the first code hunk 'knows' where the second hunk is in memory, eg:

	move.l	(first_code_hunk_start-4,pc),d0
	lsl.l	#2,d0
; d0=second_code_hunk_start

edit:
As for the initial register values, you get:
a0=cmd line (LF terminated)
d0=cmd line length (LF included)
Anything else shouldn't be relied upon (or Thomas will come shotgunning after you :P ) as far as I can remember.

[KennyOfTrains]

Fantastic, thanks for your help. I'll check this against my disassembly.

Searching that has also brought up some more hits to read through as well, including "Executables and initial register values" http://eab.abime.net/showthread.php?t=71908 on here. Irked that I didn't find that before.

Many thanks

[Exodous]

CLI startup is covered in the AmigaDOS Developer's Manual, section 1.3.1 "Initial Environment In Assembler".

I've got a paper copy, but a quick Google has come up with the following scanned PDF which has a few OCR errors, but is generally readable.

https://retro-commodore.eu/files/dow...0eBook-ENG.pdf

[ross]

uh, I wanted to answer this thread and instead I answered a very old one simply because I had done a search to see if there was something public and useful (and the page remained open..)

Well, just check my message here:
http://eab.abime.net/showthread.php?t=71908

[KennyOfTrains]

Exodus, thanks for that document, it looks like it gives a load of information that'll be useful to understanding the structure.


Ross, that post you put in the other thread actually lines up really well with what I'm looking at, which is good as I thought I had done the disassembly completely wrong. I don't suppose you have a neat source reference where you found that out?

Specifically, the first few commands from the "echo" command were:

movea.l (356,a2), a4	; 28 6A 01 64 	= moveal %a2@(356),%a4   Moves a value into A4
moveq #12, d0		; 70 0C 	= moveq #12,%d0  	Moves the low byte from SEAOW into a D-reg
jsr (a5)		; 4E 95 	= jsr %a5@		JumpSubroutine to A5 (what's in A5?)

Hence why I thought I was missing something big. The code jumps straight to using the value in A2, and then jumping to the value in A5. However, with your information, A2 being the BCPL Global Vector and A5 being a pointer to a service routine actually makes a lot of sense.

I'll dig around more, but that at least that suggests I'm not completely barking up the wrong tree.

One more thing, I've been assuming that the entry point into the executable is the first byte in the first HUNK_CODE, can someone confirm or correct that?

Many thanks all the help

[ross]

No neat reference sorry, only old snippets from BCPL and TripOS sources (and memory..).
(you can probably find information online)

About this code:

movea.l (356,a2), a4	; 28 6A 01 64 	= moveal %a2@(356),%a4   Moves a value into A4
moveq #12, d0		; 70 0C 	= moveq #12,%d0  	Moves the low byte from SEAOW into a D-reg
jsr (a5)		; 4E 95 	= jsr %a5@		JumpSubroutine to A5 (what's in A5?)

It extract from BCPL Global Vector the ptr to a Function and insert it in "entry address" register.
Then set d0 to a 'minimal' BCPL stack displacement (I seem to remember a lower value than that is not possible).
Then it calls service routine (execute the Function).
No parameters required (d1~d4 not set).

About what the Function is: I think this too can be found somewhere on old dos.library re-sourced code.

--

Yes, Amiga exe starts from the first instruction of the first hunk.

[hooverphonique]

Originally Posted by KennyOfTrains

One more thing, I've been assuming that the entry point into the executable is the first byte in the first HUNK_CODE, can someone confirm or correct that?

Depending on how you look at it, yes - the first byte of the first code hunk content is the starting instruction, but each hunk starts with 2 longs which are the size of the hunk and a pointer to the next hunk/segment. You can find out more about this by looking up info on seglist.

[Thomas Richter]

Originally Posted by KennyOfTrains

Specifically, the first few commands from the "echo" command were:

movea.l (356,a2), a4    ; 28 6A 01 64     = moveal %a2@(356),%a4   Moves a value into A4
moveq #12, d0        ; 70 0C     = moveq #12,%d0      Moves the low byte from SEAOW into a D-reg
jsr (a5)        ; 4E 95     = jsr %a5@        JumpSubroutine to A5 (what's in A5?)

Hence why I thought I was missing something big.

Yes, but please ignore that junk. This is the old BCPL startup code. If you want to look at the internals of the echo command, pick the one from 2.0 onwards.


a5 is the BCPL "call a subroutine" function, a2 is the BCPL global value, a4 is the BCPL function to be called, and d0 is the number of bytes to reserve on the BCPL call stack. I could check what the GV entry 356 does, but in the end, it does not matter. This is obsolete junk - but indeed, the code starts from there, with registers pre-defined by Tripos.

[nogginthenog]

Originally Posted by Thomas Richter

Yes, but please ignore that junk. This is the old BCPL startup code. If you want to look at the internals of the echo command, pick the one from 2.0 onwards.

I agree with Thomas. Please skip 1.x. TripOS has some nice features that AmigaDOS inherited but the API is not one.

I really enjoyed Dr Tim King's TripOS speech at Amiga32. Shame I didn't get a chance to speak to him.

[KennyOfTrains]

Ok, to say I was missing something big was actually an understatement with regards to the Global Vector table.

While I was searching, I found a nice reference at https://www.pagetable.com/?p=193 which has side-by-side comparisons of the TripOS documentation to the AmigaDOS documentation and highlights how similar they are.

I have to admit, despite being a developer and Amiga owner for around 30 years, I had never heard of TripOS or knew of its part in the AmigaOS history until this thread. Even the familiar "Amiga Original File System" is an almost verbatim copy of the TripOS file structure https://www.pagetable.com/docs/amiga...s.pdf#page=485

Just because I know my curiosity won't let it go, I found a rough disassembly of the dos.library to get an idea what the global vector functions do, so I'll dig though that.

Many thanks all

References:

• http://megaburken.net/~patrik/BCPL/bcpl.doc.txt
• https://www.pagetable.com/?p=193

[Thomas Richter]

There are a couple of unofficial documentations about the GV and its contents -thrust only half it what you read there. In 1.3, there were some useful functions in there, like WriteF for formatted printing, a co-routine switcher and ReadArgs() which is really a miss in 1.3. However, compared to 2.0, there is nothing else in there you need, and believe me, it looks much less impressive from the inside than from the outside. What this command line startup code does is that it performs the "runtime linking" of the binary as BCPL code is not "statically linked". It takes the system segments from the dos.library (mlib, blib) and the CLI globals (the struct CommandLineInterface), and then parses the binaries itself by the BCPL runtime linkage structure to build the GV of the program, then launches it through the start() vector at offset +4. But, again, this is arcane magic you shouldn't really bother about. The only place for that magic are "BCPL linkage" handlers (i.e. those with GlobVec = 0 in the mount entry). FFS, the Port Handler and the console (CON: handler) are for "hysterical raisons", but they are all written in assembler or C and rather emulate this startup process. They have been long replaced by non-BCPL code. The last remaining BCPL dinosaur with native GlobVec=0 linkage was the AUX-Handler in 3.1, but it got finally extinct in 3.1.4 and was replaced by a C version. Finally, 3.2. will get rid of it completely and replace it by a small stub, the work now being done by the console all over.

[jotd]

I've used the 1.3 ReadArgs version for JST. It's not as good as ReadArgs but is a lifesaver.

[ross]

@Thomas: Just to clarify, has support for GV been or will be eliminated in 3.1.4 / 3.2?
This to understand if JST (or similar that rely on TripOS ReadArgs) will continue to work or will have to split code depending on the KS.

[jotd]

Originally Posted by ross

@Thomas: Just to clarify, has support for GV been or will be eliminated in 3.1.4 / 3.2?
This to understand if JST (or similar that rely on TripOS ReadArgs) will continue to work or will have to split code depending on the KS.

JST checks for kickstart and has 2 command line parsing routines depending on the version. Yes, this is tedious. Maybe it works on kick 2.0 but the kick 2.0 command line parsing was here first and is better.

[Thomas Richter]

Originally Posted by ross

@Thomas: Just to clarify, has support for GV been or will be eliminated in 3.1.4 / 3.2?
This to understand if JST (or similar that rely on TripOS ReadArgs) will continue to work or will have to split code depending on the KS.

You really should not depend on the GV. This was never documented, and it was not documented for a reason. It's nice to know such historical artefacts, but that doesn't make software that depend on this valid and robust. The GV will go at some point, as all Os components that depended on it are gone. It did not go *right now*.

Note, however, that the GV and now it is used from 2.04 onwards is different from how it worked in 1.3 - there are some subtle differences.

If you want a good argument parser for 1.3: Look into "arp" - the amiga replacement project. Actually, this library was the basis for the v37 dos.library.

[ross]

Originally Posted by Thomas Richter

You really should not depend on the GV. This was never documented, and it was not documented for a reason. It's nice to know such historical artefacts, but that doesn't make software that depend on this valid and robust. The GV will go at some point, as all Os components that depended on it are gone. It did not go *right now*.

Note, however, that the GV and now it is used from 2.04 onwards is different from how it worked in 1.3 - there are some subtle differences.

If you want a good argument parser for 1.3: Look into "arp" - the amiga replacement project. Actually, this library was the basis for the v37 dos.library.

It was just to clarify whether some 'adventurous' programs would stop working in the future.
But in the case of JST everything is already in place regardless

Thanks for the 'arp' tip.

[alkis]

Originally Posted by Thomas Richter

You really should not depend on the GV. This was never documented, and it was not documented for a reason. It's nice to know such historical artefacts, but that doesn't make software that depend on this valid and robust. The GV will go at some point, as all Os components that depended on it are gone. It did not go *right now*.

Note, however, that the GV and now it is used from 2.04 onwards is different from how it worked in 1.3 - there are some subtle differences.

If you want a good argument parser for 1.3: Look into "arp" - the amiga replacement project. Actually, this library was the basis for the v37 dos.library.

Or, you guys working at AmigaOS could make a new library for 1.2/1.3 and have the _exact_ ReadArgs in it?