1	Preliminary Notes on Porting BFD
2	--------------------------------
3
4The 'host' is the system a tool runs *on*.
5The 'target' is the system a tool runs *for*, i.e.
6a tool can read/write the binaries of the target.
7
8Porting to a new host
9---------------------
10Pick a name for your host. Call that <host>.
11(<host> might be sun4, ...)
12Create a file hosts/<host>.mh.
13
14Porting to a new target
15-----------------------
16Pick a name for your target. Call that <target>.
17Call the name for your CPU architecture <cpu>.
18You need to create <target>.c and config/<target>.mt,
19and add a case for it to a case statements in bfd/configure.host and
20bfd/config.bfd, which associates each canonical host type with a BFD
21host type (used as the base of the makefile fragment names), and to the
22table in bfd/configure.ac which associates each target vector with
23the .o files it uses.
24
25config/<target>.mt is a Makefile fragment.
26The following is usually enough:
27DEFAULT_VECTOR=<target>_vec
28SELECT_ARCHITECTURES=bfd_<cpu>_arch
29
30See the list of cpu types in archures.c, or "ls cpu-*.c".
31If your architecture is new, you need to add it to the tables
32in bfd/archures.c, opcodes/configure.ac, and binutils/objdump.c.
33
34For more information about .mt and .mh files, see config/README.
35
36The file <target>.c is the hard part.  It implements the
37bfd_target <target>_vec, which includes pointers to
38functions that do the actual <target>-specific methods.
39
40Porting to a <target> that uses the a.out binary format
41-------------------------------------------------------
42
43In this case, the include file aout-target.h probaby does most
44of what you need. The program gen-aout generates <target>.c for
45you automatically for many a.out systems.  Do:
46	make gen-aout
47	./gen-aout <target> > <target>.c
48(This only works if you are building on the target ("native").
49If you must make a cross-port from scratch, copy the most
50similar existing file that includes aout-target.h, and fix what is wrong.)
51
52Check the parameters in <target>.c, and fix anything that is wrong.
53(Also let us know about it; perhaps we can improve gen-aout.c.)
54
55TARGET_IS_BIG_ENDIAN_P
56	Should be defined if <target> is big-endian.
57
58N_HEADER_IN_TEXT(x)
59	See discussion in ../include/aout/aout64.h.
60
61BYTES_IN_WORD
62	Number of bytes per word. (Usually 4 but can be 8.)
63
64ARCH
65	Number of bits per word.  (Usually 32, but can be 64.)
66
67ENTRY_CAN_BE_ZERO
68	Define if the extry point (start address of an
69	executable program) can be 0x0.
70
71TEXT_START_ADDR
72	The address of the start of the text segemnt in
73	virtual memory.  Normally, the same as the entry point.
74
75TARGET_PAGE_SIZE
76
77SEGMENT_SIZE
78        Usually, the same as the TARGET_PAGE_SIZE.
79        Alignment needed for the data segment.
80
81TARGETNAME
82	The name of the target, for run-time lookups.
83	Usually "a.out-<target>"
84
85Copyright (C) 2012-2016 Free Software Foundation, Inc.
86
87Copying and distribution of this file, with or without modification,
88are permitted in any medium without royalty provided the copyright
89notice and this notice are preserved.
90