mirror of
https://github.com/autc04/Retro68.git
synced 2024-12-26 00:32:02 +00:00
documentation update
This commit is contained in:
Wolfgang Thaller
parent
21969fb358
commit
a993bd3f7f
@ -20,7 +20,7 @@
|
||||
|
||||
# ########### A real Mac connected via a serial cable
|
||||
|
||||
# Prerequisited:
|
||||
# Prerequisites:
|
||||
# - A Mac with a modem port, and any classic Mac system software
|
||||
# - The LaunchAPPLServer application
|
||||
# (`Retro68-build/build-target/LaunchAPPL/Server/`) running on that Mac
|
||||
@ -36,6 +36,25 @@
|
||||
# serial-baud = 19200
|
||||
|
||||
|
||||
# ########### A real Mac running Mac OS X
|
||||
|
||||
# Prerequisites
|
||||
# - A Mac running Mac OS X that is reachable via ssh
|
||||
# - LaunchAPPL compiled for that Mac
|
||||
|
||||
# ########### A real Mac connected via TCP/IP
|
||||
|
||||
# Prerequisites:
|
||||
# - An old Mac connected to your local TCP/IP network
|
||||
# - System Software that supports MacTCP or OpenTransport
|
||||
# - LanchAPPLServer compiled by Retro68 for your old Mac
|
||||
# - A firewall that protects your Mac from the open internet
|
||||
# (LaunchAPPLServer opens an unsecured TCP port and executes any application it receives there!)
|
||||
|
||||
# emulator = tcp
|
||||
# tcp-address = 192.168.0.42 # IP address of your mac
|
||||
|
||||
|
||||
# ########### Mini vMac (old 68K Macs)
|
||||
|
||||
# To use Mini vMac with LaunchAPPL, you need to supply the ROM file,
|
||||
@ -87,4 +106,3 @@
|
||||
|
||||
# executor-option = -appearance # uncommenting these two lines
|
||||
# executor-option = windows # is seriously not recommended.
|
||||
|
||||
|
||||
14
README.md
14
README.md
@ -16,7 +16,7 @@ Installing/Building
|
||||
|
||||
- Linux, Mac OS X or Windows (via Cygwin)
|
||||
- boost
|
||||
- CMake 2.8
|
||||
- CMake 3.8 or later
|
||||
- GCC dependencies: GMP 4.2+, MPFR 2.3.1+ and MPC 0.8.0+
|
||||
- bison version 3.0.2 or later
|
||||
- Apple Universal Interfaces (version 3.x; version 3.4 is tested)
|
||||
@ -106,7 +106,7 @@ to add that to your `PATH`.
|
||||
If you're building this on a PowerMac running Mac OS X 10.4, tell the build script
|
||||
to use the gcc you've installed via tigerbrew:
|
||||
|
||||
../Retro68/build-toolchain.bash --host-cxx-compiler=g++-5 --host-c-compiler=gcc-5
|
||||
../Retro68/build-toolchain.bash --host-cxx-compiler=g++-7 --host-c-compiler=gcc-7
|
||||
|
||||
### Build options and recompiling
|
||||
|
||||
@ -234,13 +234,6 @@ GNU assembler (`powerpc-apple-macos-as`). Well, as long as the .o file does not
|
||||
use global variables or non-local function calls. Used to import glue code from
|
||||
MPW's `Interface.o` library.
|
||||
|
||||
### MakeAPPL
|
||||
|
||||
Reads a FLAT executable as output by elf2flt and converts it to
|
||||
a MacBinary file containing a classic Macintosh application.
|
||||
The CMake setup for the sample programs no longer uses this, but rather uses
|
||||
Rez to generate the appropriate resources.
|
||||
|
||||
### PEFTools
|
||||
|
||||
Tools supporting the Apple's PEF format, the Preferred Executable Format
|
||||
@ -334,6 +327,7 @@ Currently, LaunchAPPL supports the following methods for launching Mac applicati
|
||||
* executor - launch using Executor
|
||||
* ssh - Invoke the `LaunchAPPL` tool remotely via ssh
|
||||
* serial - Connect to a real Mac running the `LaunchAPPLServer` application via a null modem cable
|
||||
* tcp - Connect to a real Mac running the `LaunchAPPLServer` application via a completely insecure TCP connection
|
||||
|
||||
If you're running on a Mac that's old enough to use the `classic` or `carbon` backends,
|
||||
they will work out of the box, just launch an application as follows
|
||||
@ -347,7 +341,7 @@ copy the file `Retro68/LaunchAPPL/LaunchAPPL.cfg.example` to `~/.LaunchAPPL.cfg`
|
||||
and edit to taste (documentation is provided in comments).
|
||||
|
||||
**CONTRIBUTION OPPORTUNITY** - This tool can easily be extended with further backends,
|
||||
so make it work with your favourtite emulator. Just add new subclasses for the
|
||||
so make it work with your favourite emulator. Just add new subclasses for the
|
||||
`LaunchMethod` and `Launcher` classes, they're documented.
|
||||
|
||||
### The Test Suite
|
||||
|
||||
BIN
docs/BFLT.pdf
BIN
docs/BFLT.pdf
Binary file not shown.
@ -1,225 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>uClinux - BFLT Binary Flat Format</title>
|
||||
<META name="description" content="Setting up a development system for uClinux from scratch is not hard. This article covers the uClinux Kernel 2.0.38, m68k-coff, m68k-pic-coff, m68k-pic32-coff and m68k-elf Tool Chains, coff2flt converter, uC-libc and uC-libm libraries, gdb and the new uClinux 2.4.0 kernel. All the sources are downloadable,with links provided.">
|
||||
<META name="keywords" content="uClinux, m68k-pic-coff, m68k-coff, m68k-elf, coff2flt, elf2flt, arm-linux-elf, bFLT, Binary Flat, Relocations, GOT Global Offset Table">
|
||||
</head>
|
||||
|
||||
<body leftmargin="0" topmargin="0" marginheight="0" marginwidth="0" background="/bgyellow.gif" BASEFONT FACE=ARIAL>
|
||||
<STYLE TYPE="text/css">
|
||||
#TITLEBLOCK { text-decoration: none; color:#FFFFFF }
|
||||
TD,P,FONT,A,LI,B {font-family : Arial}
|
||||
PRE,TT {color:#100080}
|
||||
</STYLE>
|
||||
|
||||
<BR><CENTER>
|
||||
<TABLE BOARDER=0 WIDTH="95%"><TR>
|
||||
<TD WIDTH="25%"><CENTER><a href="http://www.beyondlogic.org"><img src="/beyondsmall.gif" alt="Beyond Logic" border=0></a></CENTER></TD>
|
||||
<TD WIDTH="50%"><CENTER>
|
||||
|
||||
<script type="text/javascript"><!--
|
||||
google_ad_client = "pub-7725444460812017";
|
||||
google_ad_width = 468;
|
||||
google_ad_height = 60;
|
||||
google_ad_format = "468x60_as";
|
||||
google_ad_type = "text_image";
|
||||
google_ad_channel ="";
|
||||
google_color_border = "0033FF";
|
||||
google_color_bg = "FFFFFF";
|
||||
google_color_link = "0000FF";
|
||||
google_color_url = "008000";
|
||||
google_color_text = "000000";
|
||||
//--></script>
|
||||
<script type="text/javascript"
|
||||
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
|
||||
</script>
|
||||
<NOSCRIPT><FONT COLOR=RED>This page is optimised with JavaScript 1.2. Currently your browser has JavaScript switched off.</NOSCRIPT>
|
||||
</CENTER></TD>
|
||||
<TD ALIGN=RIGHT VALIGN=CENTER><BR><FONT FACE=ARIAL>
|
||||
<script language=javascript src="http://www.beyondlogic.org/menu/beyondmenu_plain.js"></script>
|
||||
<NOSCRIPT></TD></TR></TABLE></CENTER></noscript>
|
||||
|
||||
<TABLE WIDTH="95%"><TR><TD>
|
||||
<BR>
|
||||
<CENTER><FONT COLOR=GREEN SIZE=5>uClinux - BFLT Binary Flat Format</FONT></CENTER>
|
||||
</CENTER>
|
||||
<UL>
|
||||
<P>
|
||||
uClinux uses a Binary Flat format commonly known as BFLT. It is a relatively simple
|
||||
and lightweight executable format based on the original a.out format. It has seen
|
||||
two major revisions, version 2 and more recently version 4. Version 2 is used by the
|
||||
m68k-coff compilers and is still in use with the ARM elf2flt converter while version
|
||||
4 is used with the m68k elf2flt converter. Like many open source projects worked on
|
||||
by many individuals, little features have creped into versions without the revision
|
||||
field changing. As a consequence what we detail in each version may not strictly be
|
||||
the case in all circumstances. Both the 2.0.x and 2.4.x kernels’ bFLT loaders in the
|
||||
CVS support both formats. Earlier kernels may need to have binfmt_flat.c and flat.c
|
||||
patched to support version 4, should version 4 binaries report the following message
|
||||
when loading
|
||||
</P>
|
||||
<UL><PRE>
|
||||
bFLT:not found.
|
||||
bad magic/rev(4,need 2)
|
||||
</PRE></UL>
|
||||
<TABLE>
|
||||
<TR><TD>
|
||||
<P>
|
||||
Each flat binary is preceded by a header of the structure shown below in listing 1. It starts
|
||||
with 4 ASCII bytes, “bFLT” or 0x62, 0x46, 0x4C, 0x54 which identifies the binary
|
||||
as conforming to the flat format. The next field designates the version number of
|
||||
the flat header. As mentioned there are two major versions, version 2 and version
|
||||
4. Each version differs by the supported flags and the format of the relocations.
|
||||
</P>
|
||||
<P>
|
||||
The next group of fields in the header specify the starting address of each segment
|
||||
relative to the start of the flat file. Most files start the .text segment at 0x40
|
||||
(immediately after the end of the header).
|
||||
The data_start, data_end and bss_end fields specify the start or finish of the
|
||||
designated segments. With the absence of text_end and bss_start fields, it is
|
||||
assumed that the text segment comes first, followed immediately by the data segment.
|
||||
While the comments for the flat file header would suggest there is a bss segment
|
||||
somewhere in the flat file, this is not true. bss_end is used to represent the
|
||||
length of the bss segment, thus should be set to data_end + size of bss.
|
||||
</P>
|
||||
</TD><TD>
|
||||
<CENTER><img src="bflt.gif" alt="bFLT File Format" border=0><BR><I>Figure 1 : Flat File Format</I></CENTER>
|
||||
</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
<UL><PRE>
|
||||
struct flat_hdr {
|
||||
char magic[4];
|
||||
unsigned long rev; /* version */
|
||||
unsigned long entry; /* Offset of first executable instruction
|
||||
with text segment from beginning of file */
|
||||
unsigned long data_start; /* Offset of data segment from beginning of
|
||||
file */
|
||||
unsigned long data_end; /* Offset of end of data segment
|
||||
from beginning of file */
|
||||
unsigned long bss_end; /* Offset of end of bss segment from beginning
|
||||
of file */
|
||||
|
||||
/* (It is assumed that data_end through bss_end forms the bss segment.) */
|
||||
|
||||
unsigned long stack_size; /* Size of stack, in bytes */
|
||||
unsigned long reloc_start; /* Offset of relocation records from
|
||||
beginning of file */
|
||||
unsigned long reloc_count; /* Number of relocation records */
|
||||
unsigned long flags;
|
||||
unsigned long filler[6]; /* Reserved, set to zero */
|
||||
};
|
||||
</PRE></UL>
|
||||
<P>
|
||||
<CENTER><I>Listing 1 : The bFLT header structure extracted from flat.h</I></CENTER>
|
||||
</P>
|
||||
<P>
|
||||
Following the segments’ start and end pointers comes the stack size field specified
|
||||
in bytes. This is normally set to 4096 by the m68k bFLT converters and can be
|
||||
changed by passing an argument (-s) to the elf2flt / coff2flt utility.
|
||||
</P>
|
||||
<P>
|
||||
The next two fields specify the details of the relocations. Each relocation is a
|
||||
long (32 bits) with the relocation table following the data segment in the flat
|
||||
binary file. The relocation entries are different per bFLT version.
|
||||
</P>
|
||||
<P>
|
||||
Version 2 specified a 2 bit type and 30 bit offset per relocation. This causes a
|
||||
headache with endianess problems. The 30 bit relocation is a pointer relative to
|
||||
zero where an absolute address is used. The type indicates whether the absolute
|
||||
address points to .text, .data or .bss.
|
||||
</P>
|
||||
<UL><PRE>
|
||||
#define FLAT_RELOC_TYPE_TEXT 0
|
||||
#define FLAT_RELOC_TYPE_DATA 1
|
||||
#define FLAT_RELOC_TYPE_BSS 2
|
||||
|
||||
struct flat_reloc {
|
||||
#if defined(__BIG_ENDIAN_BITFIELD) /* bit fields, ugh ! */
|
||||
unsigned long type : 2;
|
||||
signed long offset : 30;
|
||||
#elif defined(__LITTLE_ENDIAN_BITFIELD)
|
||||
signed long offset : 30;
|
||||
unsigned long type : 2;
|
||||
#endif
|
||||
</PRE></UL>
|
||||
<P>
|
||||
<CENTER><I>Listing 2 : Version 2 relocation structures - Not for use in new code.</I></CENTER>
|
||||
</P>
|
||||
<P>
|
||||
This enables the flat loader to fix-up absolute addressing at runtime by jumping
|
||||
to the absolute address specified by the relocation entry and adding the loaded
|
||||
base address to the existing address.
|
||||
</P>
|
||||
<P>
|
||||
Version 4 removed the need of specifying a relocation type. Each relocation entry
|
||||
simply contains a pointer to an absolute address in need of fix-up. As the bFLT
|
||||
loader can determine the length of the .text segment at runtime (data_start -
|
||||
entry) we can use this to determine what segment the relocation is for. If the
|
||||
absolute address before fix-up is less that the text length, we can safety
|
||||
assume the relocation is pointing to the text segment and this add the base address
|
||||
of this segment to the absolute address.
|
||||
</P>
|
||||
<P>
|
||||
On the other hand if the absolute address before fix-up is greater than the text
|
||||
length, then the absolute address must be pointing to .data or .bss. As .bss
|
||||
always immediately follows the data segment there is no need to have a distinction,
|
||||
we just add the base address of the data segment and subtract the length of the
|
||||
text segment. We subtract the text segment as the absolute address in version 4
|
||||
is relative to zero and not to the start of the data segment.
|
||||
</P>
|
||||
<P>
|
||||
Now you could say we may take it one step further. As every absolute address is
|
||||
referenced to zero, we can simply add the base address of the text segment to
|
||||
each address needing fix-up. This would be true if the data segment immediately
|
||||
follows the text segment, but we now have complications of -msep-data where the
|
||||
text segment can be in ROM and the data segment in another location in RAM.
|
||||
Therefore we can no longer assume that the .data+.bss segment and text segment
|
||||
will immediately follow each other.
|
||||
</P>
|
||||
<P>
|
||||
The last defined field in the header is the flags. This appeared briefly in some
|
||||
version 2 headers (Typically ARM) but was cemented in place with version 4. The
|
||||
flags are defined as follows
|
||||
</P>
|
||||
<UL><PRE>
|
||||
#define FLAT_FLAG_RAM 0x0001 /* load program entirely into RAM */
|
||||
#define FLAT_FLAG_GOTPIC 0x0002 /* program is PIC with GOT */
|
||||
#define FLAT_FLAG_GZIP 0x0004 /* all but the header is compressed */
|
||||
</PRE></UL>
|
||||
<P>
|
||||
<CENTER><I>Listing 3 : New flags defined in Version 4</I></CENTER>
|
||||
</P>
|
||||
<P>
|
||||
Early version 2 binaries saw both the .text and .data segments loaded into RAM
|
||||
regardless. XIP (eXecute in Place) was later introduced allowing programs to
|
||||
execute from ROM with only the data segment being copied into RAM. In version
|
||||
4, it is now assumed that each binary is loaded from ROM if GOTPIC is true and
|
||||
FLAT_FLAG_GZIP and FLAT_FLAG_RAM is false. A binary can be forced to load into
|
||||
RAM by forcing the FLAT_FLAG_RAM flag.
|
||||
</P>
|
||||
<P>
|
||||
The FLAT_FLAG_GOTPIC informs the loader that a GOT (Global Offset Table) is
|
||||
present at the start of the data segment. This table includes offsets that
|
||||
need to be relocated at runtime and thus allows XIP to work. (Data is accessed
|
||||
through the GOT, thus relocations need not be made to the .text residing in ROM.) The
|
||||
GOT is terminated with a -1, followed immediately by the data segment.
|
||||
</P>
|
||||
<P>
|
||||
The FLAT_FLAG_GZIP indicates the binary is compressed with the GZIP algorithm.
|
||||
The header is left untouched, but the .text, .data and relocations are
|
||||
compressed. Some bFLT loaders do not support GZIP and will report an error
|
||||
at loading.
|
||||
</P>
|
||||
|
||||
<P>
|
||||
<BR>
|
||||
<FONT SIZE=-1><I>Acknowledgments to Pauli from Lineo for pointing out some minor errors.</I></FONT>
|
||||
</P>
|
||||
|
||||
</UL>
|
||||
</TD></TR></TABLE>
|
||||
<BR>
|
||||
<CENTER><FONT SIZE=2>Copyright 2001-2005 <A href="/about.htm">Craig Peacock </a> - 15th June 2005.</FONT></CENTER>
|
||||
<BR>
|
||||
</BODY>
|
||||
</HTML>
|
||||
Loading…
Reference in New Issue
Block a user