[deliverable/binutils-gdb.git] / ld / PORTING

Some incomplete notes about porting GNU ld
-----------------------------------------

Before porting ld itself, you will need to port the BFD library.

We tarlk about the 'host' system as the machine and software
nevironment where ld runs (generates an execuitble *on*),
while the 'target' is the machine ld generates an executable *for*.
Most often, host==target, but ld supports cross-linking
(and to some extent the same ld binary can be used a linker
for multiple target rachitectures).

Doing a 'host' port means working around broken or missing
include files or libraries. ...

Porting to a new target
-----------------------

Writing a new script script
---------------------------

You may need to write a new script file for your emulation.

The variable RELOCATING is only set if relocation is happening
(i.e. unless the linker is invoked with -r).
Thus your script should has an action ACTION
that should only be done when relocating,
express that as:
	${RELOCATING+ ACTION}
In general, this is the case for most assignments, which should look like:
	${RELOCATING+ _end = .}

Also, you should assign absolute addresses to sections only
when relocating, so:
	  .text ${RELOCATING+ ${TEXT_START_ADDR}}:

The forms:
	 .section { ... } > section
should be:
	 .section { ... } > ${RELOCATING+ section}

Old Makefile comments (re-write - FXIME!)
-----------------------------------------

# The .xn script is used if the -n flag is given (write-protect text)..
# Sunos starts the text segment for demand-paged binaries at 0x2020
# and other binaries at 0x2000, since the exec header is paged in
# with the text.  Some other Unix variants do the same.
# For -n and -N flags the offset of the exec header must be removed.
# This sed script does this if the master script contains
# a line of the form ".text 0xAAAA BLOCK(0xBBBB):" - the
# output will contain ".text 0xBBBB:".  (For Sunos AAAA=2020 and BBBB=2000.)
.x.xn:
	sed -e '/text/s/\.text .* BLOCK(\([^)]*\)):/.text \1:/' < $< >$*.xn

# The .xN script is used if the -N flag is given (don't write-protect text).
# This is like -n, except that the data segment need not be page-aligned.
# So get rid of commands for page-alignment:  We assume these use ALIGN
# with a hex constant that end with 00, since any normal page size is be
# at least divisible by 256.  We use the 00 to avoid matching
# anything that tries to align of (say) 8-byte boundaries.
.xn.xN:
	sed -e '/ALIGN/s/ALIGN( *0x[0-9a-fA-F]*00 *)/./' < $< >$*.xN
Commit	Line	Data
7e5c1057 PB	1	Some incomplete notes about porting GNU ld
	2	-----------------------------------------
	3
	4	Before porting ld itself, you will need to port the BFD library.
	5
	6	We tarlk about the 'host' system as the machine and software
	7	nevironment where ld runs (generates an execuitble on),
	8	while the 'target' is the machine ld generates an executable for.
	9	Most often, host==target, but ld supports cross-linking
	10	(and to some extent the same ld binary can be used a linker
	11	for multiple target rachitectures).
	12
	13	Doing a 'host' port means working around broken or missing
	14	include files or libraries. ...
	15
	16	Porting to a new target
	17	-----------------------
	18
	19	Writing a new script script
	20	---------------------------
	21
	22	You may need to write a new script file for your emulation.
	23
	24	The variable RELOCATING is only set if relocation is happening
	25	(i.e. unless the linker is invoked with -r).
	26	Thus your script should has an action ACTION
	27	that should only be done when relocating,
	28	express that as:
	29	${RELOCATING+ ACTION}
	30	In general, this is the case for most assignments, which should look like:
	31	${RELOCATING+ _end = .}
	32
	33	Also, you should assign absolute addresses to sections only
	34	when relocating, so:
	35	.text ${RELOCATING+ ${TEXT_START_ADDR}}:
	36
	37	The forms:
	38	.section { ... } > section
	39	should be:
	40	.section { ... } > ${RELOCATING+ section}
	41
	42	Old Makefile comments (re-write - FXIME!)
	43	-----------------------------------------
	44
	45	# The .xn script is used if the -n flag is given (write-protect text)..
	46	# Sunos starts the text segment for demand-paged binaries at 0x2020
	47	# and other binaries at 0x2000, since the exec header is paged in
	48	# with the text. Some other Unix variants do the same.
	49	# For -n and -N flags the offset of the exec header must be removed.
	50	# This sed script does this if the master script contains
	51	# a line of the form ".text 0xAAAA BLOCK(0xBBBB):" - the
	52	# output will contain ".text 0xBBBB:". (For Sunos AAAA=2020 and BBBB=2000.)
	53	.x.xn:
	54	sed -e '/text/s/\.text .* BLOCK(\([^)]\)):/.text \1:/' < $< >$.xn
	55
	56	# The .xN script is used if the -N flag is given (don't write-protect text).
	57	# This is like -n, except that the data segment need not be page-aligned.
	58	# So get rid of commands for page-alignment: We assume these use ALIGN
	59	# with a hex constant that end with 00, since any normal page size is be
	60	# at least divisible by 256. We use the 00 to avoid matching
	61	# anything that tries to align of (say) 8-byte boundaries.
	62	.xn.xN:
	63	sed -e '/ALIGN/s/ALIGN( 0x[0-9a-fA-F]00 )/./' < $< >$.xN