summaryrefslogtreecommitdiff
path: root/docs/porting.txt
diff options
context:
space:
mode:
authorWaldemar Brodkorb <wbx@openadk.org>2017-06-23 23:56:56 +0200
committerWaldemar Brodkorb <wbx@openadk.org>2017-06-23 23:57:01 +0200
commitdc7ad97385c940c0a0d67b924c1b78159da5549d (patch)
tree8a2aeab9793e9bf101e8e328e73f6765ff853eec /docs/porting.txt
parent041cdc2769407c4d3869b218ad7ee7638e1c306e (diff)
docs: cleanup directory, fix some porting information
Diffstat (limited to 'docs/porting.txt')
-rw-r--r--docs/porting.txt124
1 files changed, 124 insertions, 0 deletions
diff --git a/docs/porting.txt b/docs/porting.txt
new file mode 100644
index 000000000..380645801
--- /dev/null
+++ b/docs/porting.txt
@@ -0,0 +1,124 @@
+Some notes to help future porters. Replace 'ARCH' with whatever arch
+you are hacking on.
+
+====================
+=== Config Files ===
+====================
+- create extra/Configs/Config.ARCH
+ See the other arch files for some good examples. powerpc/sparc/alpha
+ should be pretty simple templates.
+- add ARCH to the 'Target Architecture' list in extra/Configs/Config.in
+- Initially you will want to disable shared libraries, since making
+ the shared library loader work requires you first have basic architecture
+ support working. Thus you should add ARCH_HAS_NO_SHARED and
+ ARCH_HAS_NO_LDSO to Config.ARCH's TARGET_ARCH
+
+====================
+=== libc sysdeps ===
+====================
+(note: if glibc has already been ported to your arch, you can usually just
+ copy a lot of files from them rather than coding from scratch)
+- create libc/sysdeps/linux/ARCH
+- copy Makefile and Makefile.arch from libc/sysdeps/linux/i386/
+- set CSRC and SSRC to nothing in Makefile.arch for now
+
+- create crt1.S which defines the _start function ... you will probably want
+ to clear the frame pointer to make gdb happy, and then you will want to call
+ the funcion __uClibc_main() which takes these parameters:
+ __uClibc_main(main(), argc, argv, _init(), _fini())
+ Initially if you wish to make things easier on yourself, you can disable the
+ UCLIBC_CTOR_DTOR option and just set the init/fini arguments to NULL.
+ glibc generally stores this function in libc/sysdeps/ARCH/elf/start.S
+
+- create these additional files in ARCH/bits/
+
+ (template versions can be found in common/bits/ for you to tweak)
+ endian.h fcntl.h setjmp.h stackinfo.h uClibc_arch_features.h wordsize.h
+
+ kernel_types.h should be created based upon linux asm-ARCH/posix_types.h
+
+ copy linux asm-ARCH/stat.h to bits/kernel_stat.h
+
+ create syscalls.h based upon linux's unistd.h / glibc's sysdeps.h ... really
+ you just want to define the _syscall[0-6] macros. It is important that
+ these syscalls should be PIC safe (or you should provide a PIC and non-PIC
+ version) if you wish to properly support shared libraries.
+
+- at this point, you should have enough to generate a working HELLO WORLD
+ static binary
+
+- if you want UCLIBC_CTOR_DTOR support, you will need to create crti.S and
+ crtn.S files which define function prologues/epilogues.
+
+- for a more stable static port, you will need to create these files (and
+ update the Makefile.arch values accordingly)
+ __longjmp bsd-_setjmp bsd-setjmp brk clone setjmp syscall vfork
+ usually these are written in assembler, but you may be able to cheat and
+ write them in C ... see other ports for more information
+
+====================
+=== ldso sysdeps ===
+====================
+- elf.h - presumably you've already taught binutils all about the random ELF
+ relocations your arch needs, so now you need to make sure the defines exist
+ for uClibc. make sure the EM_### define exists and all of the R_###_###
+ reloc defines.
+
+- enable ldso/shared options in your extra/Configs/Config.ARCH file
+- you will need to create the following files in ldso/ldso/ARCH/
+ dl-startup.h dl-syscalls.h dl-sysdep.h elfinterp.c resolve.S
+
+- dl-startup.h:
+ - define the _start function which should call _dl_start which takes just one
+ parameter ... a pointer to argc (usually on the stack)
+ glibc stores this function in sysdeps/ARCH/dl-machine.h as RTLD_START
+ - define the GET_ARGV() macro which calculates the value of argv based upon
+ the parameter passed to _dl_start (usually it's simply just ARGS+1)
+ - define PERFORM_BOOTSTRAP_RELOC() macro which will handle just the relocs
+ that the ldso itself will generate
+
+- dl-syscalls.h:
+ if you wrote your bits/syscalls.h file correctly in the libc step above, you
+ can simply copy this file from another arch and be done ... otherwise you
+ will have to define the syscall[0-6] macros again, but this time setting
+ _dl_errno instead of just errno
+
+- dl-sysdep.h:
+ misc cruft goes in here ... you want to:
+ - either define or undefine ELF_USES_RELOCA
+ - define the INIT_GOT macro
+ - define MAGIC1 to the EM_### value your ELF arch uses
+ - define ELF_TARGET to a string name for your arch
+ - define the do_rem() macro
+ - define misc ALIGN macro's
+ - define elf_machine_type_class() macro
+ - define the inline functions elf_machine_dynamic, elf_machine_load_address,
+ and elf_machine_relative
+ glibc stores a bunch of these values in sysdeps/ARCH/dl-machine.h
+
+- elfinterp.c:
+ define all the relocation functions ... it's best if you just copy from
+ another arch which uses the same type of relocations (REL or RELA) and
+ start from there.
+
+- resolve.S:
+ front end of lazy relocation ... define the _dl_linux_resolve symbol which
+ is called by a PLT entry which has yet to be setup ... you will want to:
+ - set up arguments for _dl_linux_resolver()
+ - call _dl_linux_resolver()
+ - clean up after call
+ - jump to function address now stored in PLT
+ glibc stores this function in sysdeps/ARCH/dl-trampoline.S
+
+- utils/ldd.c - if you want support for ldso cache files (spoiler: you do),
+ then you'll need to teach ldd a little. generally, the fallback code
+ should be smart and "just work", but you should be explicit. just pop
+ it open and add an appropriate ifdef for your arch and set MATCH_MACHINE()
+ and ELFCLASSM. there are plenty examples and you're (hopefully) smart.
+
+====================
+=== Misc Cruft ===
+====================
+- MAINTAINERS - presumably you're going to submit this code back to mainline
+ and since you're the only one who cares about this arch (right now), you
+ should add yourself to the toplevel MAINTAINERS file. do it.