HOWTO

This text tries to explain the steps to port binutils 2.16.1 from original sources to a working MiNT port. Current patches from 2.13.2.1 does not work, so a bit of rework is needed. Thanks to Mark Duckworth for his help.

Step 1: Get the necessary archives

$ tar xvzf binutils-2.16.1.tar.gz

Step 2: First try

Note: TARGETPATH is a directory where binutils-mint will be installed.

$ mkdir binutils-2.16.1-mint
$ cd binutils-2.16.1-mint
$ ../binutils-2.16.1/configure --prefix=$TARGETPATH --target=m68k-atari-mint
$ make

First error:

*** BFD does not support target m68k-atari-mint.
*** Look in bfd/config.bfd for supported targets.

Step 3: Patch BFD library to accept m68k-atari-mint target

BFD means binary file descriptor, and this is a library of functions used by all binutils tools to read/process/write files in various format (a.out, elf, coff and many others).
In current patches, there are 2 things needed for the MiNT target: a custom object file format (aout-mint) and a custom executable format (prg-mint).
The object file format seems to be needed.
The custom executable format is the well-known GEMDOS executable format, with its TEXT, DATA, BSS and relocation sections.

Step 3.1: Makefile and configure stuff

Let's try to also add ELF object format. First, the configure/makefile stuff:

• bfd/config.bfd file:

  We add our aout and prg "vectors", and also add elf32 for m68k.

  m68*-*-mint*)
    targ_defvec=m68kmint_aout_vec
    targ_selvecs="m68kmint_prg_vec m68kmint_aout_vec bfd_elf32_m68k_vec"
    targ_underscore=yes
    ;;
  

• bfd/configure.in file:

  Here we define which files are need to build our custom vectors.

    m68kmint_aout_vec)  tb="$tb aout-mint.lo aout32.lo" ;;
    m68kmint_prg_vec)   tb="$tb prg-mint.lo aout32.lo" ;;
  

• bfd/Makefile.am file:

  And the files for each section. First in BFD32_BACKENDS, we add:

    aout-mint.lo
    prg-mint.lo
  

  and in BFD32_BACKENDS_CFILES, we add:

    aout-mint.c
    prg-mint.c
  

• bfd/targets.c file:

  And now for the libbfd part:

  extern const bfd_target m68kmint_aout_vec;
  extern const bfd_target m68kmint_prg_vec;
  

Don't forget to run automake; autoconf in bfd subdir. Now aout-mint.c and prg-mint.c are missing, to build the BFD library:

make[3]: *** No rule to make target `aout-mint.c', needed by `aout-mint.lo'.  Stop.

Step 3.2: bfd/aout-mint.c

The current aout-mint.c from binutils-2.13.2.1. Using it for compilation in binutils-2.16.1 seem to work. The question is: do we really need this object file format, could be use ELF object file format instead?

aout-mint.c (binutils-2.13.2.1 version).

Now it is prg-mint.c's turn.

make[3]: *** No rule to make target `prg-mint.c', needed by `prg-mint.lo'.  Stop.

Step 3.3: bfd/prg-mint.c

prg-mint backend support both GNU and DRI file formats. I wonder if there are still people building DRI objects with previous C compilers (Lattice, Pure). Here is binutils-2.13.2.1's version:

prg-mint.c (binutils-2.13.2.1 version).

It does not work, we have many errors:

• boolean is undefined, replaced by bfd_boolean.
• false and true are undefined, replaced by FALSE and TRUE.
• relocateable field in bfd_link_info has been renamed to relocatable.
• _raw_size field in asection has been renamed to rawsize.
• discard_sec_merge (a new value) not handled in switch at line 1449.

Note: in m68kmint_prg_final_link_relocate(), a check is done against rawsize at beginning of the function and return bfd_reloc_outofrange if failing. In binutils 2.16.1 it seems that an offset (or object size) is passed instead of needed value, hence out of range. This check must be disabled.

Now we have something missing:

• bfd_m68kmint_set_extended_flags, a function to set program flags.
• obj_aout_ext macro, used to hold some specific information for our custom a.out format.

Step 3.4: bfd_m68kmint_set_extended_flags function

This one is defined in prg-mint.c. The declaration is missing from bfd/bfd-in.h. You need to run 'make headers' in bfd build subdir.

Step 3.5: aout.x file

This file needs to be modified, in its emit_stringtab() function:

/* The MiNT backend writes past the string table.  It therefore has to
   know about the table size.  */
obj_aout_external_string_size (abfd) = _bfd_stringtab_size (tab) +
  BYTES_IN_WORD;

Step 3.6: obj_aout_ext macro

This time, we need to modify the aoutdata structure in libaout.h file, by adding a new ext field:

  /* A pointer for data used by aout extensions.  (Currently only used
     by MiNT executables (see prg-mint.c).  */
  PTR ext;

obj_aout_ext() is a macro to access this new field.

#define obj_aout_ext(bfd)                  (adata (bfd).ext)

Good, now BFD library builds correctly.

prg-mint.c (binutils-2.16.1 updated version).

Next tool is GAS:

configure: error: GAS does not know what format to use for target m68k-atari-mint

Step 4: GAS tool

Just need to add a line for m68k-atari-mint in gas/configure.tgt, in the m68k section of 'case ${generic_target} in':

  m68k-*-mint*)				fmt=aout ;;

Step 5: LD tool

Same problem as GAS, first we need to add a line for m68k-atari-mint in ld/configure.tgt, in the m68k section of 'case "${targ}" in'. I also added support for ELF files.

  m68k-*-mint*)				targ_emul=m68kmint
                            targ_extra_emuls=m68kelf ;;

Note: We could also add m68kelf as targets that ld could understand.

Step 5.1: m68kmint ld target

We have defined a m68kmint target for ld, now we must write the needed stuff. ld needs some em68kmint.* file. First, there is necessary Makefile.am stuff.
We need to add em68kmint.o to ALL_EMULATIONS variable.

	em68kmint.o	\

Then adding the stuff needed to generate our target:

em68kmint.c: $(srcdir)/emulparams/m68kmint.sh \
  $(srcdir)/emultempl/mint.em $(srcdir)/scripttempl/m68kmint.sc ${GEN_DEPENDS}
	${GENSCRIPTS} m68kmint "$(tdir_m68kmint)"

Now we need to write emulparams/m68kmint.sh, emultempl/mint.em and scripttempl/m68kmint.sc.

Step 5.2: emulparams/m68kmint.sh

0xe4 is the length of the header, before the TEXT section in executable. TARGET_PAGE_SIZE is 2, so I guess it allows aligning sections on this multiple. We also need to add a TEMPLATE_NAME value, otherwise it will default to generic template, which we do not want (see ld/ldint.texinfo for infos).

SCRIPT_NAME=m68kmint
OUTPUT_FORMAT="a.out-mintprg"
TEXT_START_ADDR=0xe4
TARGET_PAGE_SIZE=2
NONPAGED_TEXT_START_ADDR=${TEXT_START_ADDR}
ARCH=m68k
TEMPLATE_NAME=mint

Step 5.2: emultempl/mint.em

The purpose of this file is to allow ld to set the program flags in the executable header at link stage. Some new fields appears in 2.16.1 version in ld_emulation_xfer_struct structure.

Like for prg-mint.c, many fields/defines have their name changed:

• relocateable field renamed to relocatable.
• true and false renamed to TRUE and FALSE.
• ldfile_set_output_arch() now has a second parameter, which is the cpu architecture.

Step 5.3: scripttempl/m68kmint.sc

The purpose of this file is to describe in which order the various sections are written to the executable file.

Step 6: Time to test and debug!

Apparently the build is ok, but we must be sure the code generated/linked by all these tools is right. That's the hard part. Most of these tools have testsuite, but maybe it requires writing MiNT tests as well.

Here is the final patch:
binutils-2.16.1-mint-4.diff.gz