[deliverable/binutils-gdb.git] / gas / NOTES

-*- text -*-

PORTING:

Sorry, no description of the interfaces is written up yet.  Look at existing
back ends and work from there.

New hosts: The configure script, which is generated by autoconf,
should handle all host specific configuration.

New target formats: Look at the BFD_ASSEMBLER code.  The a.out or ELF
code might be a fair example.  There are no "good" examples yet,
unfortunately, nor any good documentation of the changes.

New target processors: Check first to see if the BFD_ASSEMBLER interface is
supported by the file format code you need to use.

DOCUMENTATION:

The internals of gas need documenting.

The documentation should also contain a "Trouble" section similar to gcc's
manual: real bugs, common problems, incompatibilities, etc.

Anyone want to offer to maintain a man page?

BFD CONVERSION:

The "#ifdef BFD_ASSEMBLER" code is on its way in; the "#ifndef BFD_ASSEMBLER"
code is on its way out.  The new code uses BFD data structures, and calls BFD
for anything that needs to be written to the output file.  The old code did all
the writing itself, or in a couple of cases, used BFD as a slightly higher
level than stdio (i.e., bfd_seek, bfd_write -- these are not the preferred
interface).

Because of this, some of this code is messy.  Lots of ifdef's, and the
non-BFD_ASSEMBLER version often has multiple conditional tests inside it for
various processors or formats.  As the various targets get converted over,
these will gradually go away.

TO DO:

Remove DONTDEF code, commented-out code.

Eliminate, as much as possible, anything not in config that is conditionalized
on a CPU, format, or environment.

Merge COFF support into one version, supporting all the pseudo-ops used in
either versions now, but using BFD for high-level operations.  (See second
following item.)  Currently there are two versions (plus the new BFD code),
which support different features, and are used on different targets.

Convert remaining a.out/b.out targets to using the BFD_ASSEMBLER code by
default.

Finish conversion to using BFD for all object file writing.  (This is the
BFD_ASSEMBLER code, not BFD or BFD_HEADERS.)  VMS might be the tough one here,
since there's no BFD support for it at all yet.  Eliminate the old code.  Some
of this can be done target by target, so doing a target where the CPU or
format already supports BFD_ASSEMBLER mode may be easiest.

Fix lots of uses of empty strings to use null pointers.  Will improve
efficiency, and should make code clearer too.

Clean up comments; lots of 'em are one previous maintainer griping about
another previous maintainer, unrelated to the code.  (And with no names,
they're not so fun to read. :-)

For sparc: "call 0" becomes "jmpl %g0,%l7", and similarly for absolute
addresses in -4096...4095.  (Solaris assembler does this.  No
relocation required, no absolute symbol needed.)  For addresses
outside the range, for COFF, keep generating an absolute symbol to use
for relocs.

Get Steve to document H8/500 stuff (and others).

Improve test suite.  Incorporate more reported net bugs, and non-confidential
Cygnus customer bugs, and anything else.

Add support for i386/i486 16-bit mode, so operating system initialization code
doesn't require a separate assembler nor lots of `.byte' directives.

See if it's more maintainable (and not too much of a performance loss) to use
a yacc grammar for parsing input.  The lexer will have to be flexible, and the
grammar will have to contain any construct used on any platform, but it may be
easier to maintain, instead of having code in most of the back ends.

PIC support.

Torbjorn Granlund <tege@cygnus.com> writes, regarding alpha .align:

   Please make sure the .align directive works as in digital's assembler.
   They fill the space with a sequence of "bis $31,$31,$31;ldq_u $31,0($30)"
   since these two instructions can dual-issue.  Since .align is ued a lot by
   gcc, it is an important optimization.

(From old "NOTES" file to-do list, not really reviewed:)

fix relocation types for i860, perhaps by adding a ref pointer to fixS?

remove the ifdef's from fx_callj tests?

space tighten sparc alignment?

md_ => tc_

share b.out with a.out.
Commit	Line	Data
	1	-- text --
	2
	3	PORTING:
	4
	5	Sorry, no description of the interfaces is written up yet. Look at existing
	6	back ends and work from there.
	7
	8	New hosts: The configure script, which is generated by autoconf,
	9	should handle all host specific configuration.
	10
	11	New target formats: Look at the BFD_ASSEMBLER code. The a.out or ELF
	12	code might be a fair example. There are no "good" examples yet,
	13	unfortunately, nor any good documentation of the changes.
	14
	15	New target processors: Check first to see if the BFD_ASSEMBLER interface is
	16	supported by the file format code you need to use.
	17
	18	DOCUMENTATION:
	19
	20	The internals of gas need documenting.
	21
	22	The documentation should also contain a "Trouble" section similar to gcc's
	23	manual: real bugs, common problems, incompatibilities, etc.
	24
	25	Anyone want to offer to maintain a man page?
	26
	27	BFD CONVERSION:
	28
	29	The "#ifdef BFD_ASSEMBLER" code is on its way in; the "#ifndef BFD_ASSEMBLER"
	30	code is on its way out. The new code uses BFD data structures, and calls BFD
	31	for anything that needs to be written to the output file. The old code did all
	32	the writing itself, or in a couple of cases, used BFD as a slightly higher
	33	level than stdio (i.e., bfd_seek, bfd_write -- these are not the preferred
	34	interface).
	35
	36	Because of this, some of this code is messy. Lots of ifdef's, and the
	37	non-BFD_ASSEMBLER version often has multiple conditional tests inside it for
	38	various processors or formats. As the various targets get converted over,
	39	these will gradually go away.
	40
	41	TO DO:
	42
	43	Remove DONTDEF code, commented-out code.
	44
	45	Eliminate, as much as possible, anything not in config that is conditionalized
	46	on a CPU, format, or environment.
	47
	48	Merge COFF support into one version, supporting all the pseudo-ops used in
	49	either versions now, but using BFD for high-level operations. (See second
	50	following item.) Currently there are two versions (plus the new BFD code),
	51	which support different features, and are used on different targets.
	52
	53	Convert remaining a.out/b.out targets to using the BFD_ASSEMBLER code by
	54	default.
	55
	56	Finish conversion to using BFD for all object file writing. (This is the
	57	BFD_ASSEMBLER code, not BFD or BFD_HEADERS.) VMS might be the tough one here,
	58	since there's no BFD support for it at all yet. Eliminate the old code. Some
	59	of this can be done target by target, so doing a target where the CPU or
	60	format already supports BFD_ASSEMBLER mode may be easiest.
	61
	62	Fix lots of uses of empty strings to use null pointers. Will improve
	63	efficiency, and should make code clearer too.
	64
	65	Clean up comments; lots of 'em are one previous maintainer griping about
	66	another previous maintainer, unrelated to the code. (And with no names,
	67	they're not so fun to read. :-)
	68
	69	For sparc: "call 0" becomes "jmpl %g0,%l7", and similarly for absolute
	70	addresses in -4096...4095. (Solaris assembler does this. No
	71	relocation required, no absolute symbol needed.) For addresses
	72	outside the range, for COFF, keep generating an absolute symbol to use
	73	for relocs.
	74
	75	Get Steve to document H8/500 stuff (and others).
	76
	77	Improve test suite. Incorporate more reported net bugs, and non-confidential
	78	Cygnus customer bugs, and anything else.
	79
	80	Add support for i386/i486 16-bit mode, so operating system initialization code
	81	doesn't require a separate assembler nor lots of `.byte' directives.
	82
	83	See if it's more maintainable (and not too much of a performance loss) to use
	84	a yacc grammar for parsing input. The lexer will have to be flexible, and the
	85	grammar will have to contain any construct used on any platform, but it may be
	86	easier to maintain, instead of having code in most of the back ends.
	87
	88	PIC support.
	89
	90	Torbjorn Granlund <tege@cygnus.com> writes, regarding alpha .align:
	91
	92	Please make sure the .align directive works as in digital's assembler.
	93	They fill the space with a sequence of "bis $31,$31,$31;ldq_u $31,0($30)"
	94	since these two instructions can dual-issue. Since .align is ued a lot by
	95	gcc, it is an important optimization.
	96
	97	(From old "NOTES" file to-do list, not really reviewed:)
	98
	99	fix relocation types for i860, perhaps by adding a ref pointer to fixS?
	100
	101	remove the ifdef's from fx_callj tests?
	102
	103	space tighten sparc alignment?
	104
	105	md_ => tc_
	106
	107	share b.out with a.out.