summaryrefslogtreecommitdiff
path: root/docs/PORTING
diff options
context:
space:
mode:
Diffstat (limited to 'docs/PORTING')
-rw-r--r--docs/PORTING135
1 files changed, 0 insertions, 135 deletions
diff --git a/docs/PORTING b/docs/PORTING
deleted file mode 100644
index d04f3b4f5..000000000
--- a/docs/PORTING
+++ /dev/null
@@ -1,135 +0,0 @@
-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
-
-====================
-=== pthread deps ===
-====================
-
-TODO: nptl / linuxthreads / linuxthreads.old
-
-====================
-=== 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-debug.h dl-startup.h dl-syscalls.h dl-sysdep.h elfinterp.c resolve.S
-
-- dl-debug.h: define string versions of all the relocations of your arch in the
- _dl_reltypes_tab array ... the index should match the actual reloc type, so
- if the value of say R_X86_64_PC16 is 13, then "R_X86_64_PC16" better be at
- index 13 of the array
-
-- 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 libc/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 libc/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 libc/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.