docs/porting.txt

   1 Some notes to help future porters.  Replace 'ARCH' with whatever arch
   2 you are hacking on.
   3
   4 ====================
   5 === Config Files ===
   6 ====================
   7 - create extra/Configs/Config.ARCH
   8    See the other arch files for some good examples.  powerpc/sparc/alpha
   9    should be pretty simple templates.
  10 - add ARCH to the 'Target Architecture' list in extra/Configs/Config.in
  11 - Initially you will want to disable shared libraries, since making
  12    the shared library loader work requires you first have basic architecture
  13    support working.  Thus you should add ARCH_HAS_NO_SHARED and
  14    ARCH_HAS_NO_LDSO to Config.ARCH's TARGET_ARCH
  15 - When static pie support is added this TARGET_arch can be appended to the
  16    list in extra/Configs/Config.in
  17
  18 ====================
  19 === libc sysdeps ===
  20 ====================
  21 (note: if glibc has already been ported to your arch, you can usually just
  22        copy a lot of files from them rather than coding from scratch)
  23 - create libc/sysdeps/linux/ARCH
  24 - copy Makefile and Makefile.arch from libc/sysdeps/linux/i386/
  25 - set CSRC and SSRC to nothing in Makefile.arch for now
  26
  27 - create crt1.S which defines the _start function ... you will probably want
  28   to clear the frame pointer to make gdb happy, and then you will want to call
  29   the funcion __uClibc_main() which takes these parameters:
  30    __uClibc_main(main(), argc, argv, _init(), _fini())
  31   Initially if you wish to make things easier on yourself, you can disable the
  32   UCLIBC_CTOR_DTOR option and just set the init/fini arguments to NULL.
  33   glibc generally stores this function in libc/sysdeps/ARCH/elf/start.S
  34
  35 - create these additional files in ARCH/bits/
  36
  37   (template versions can be found in common/bits/ for you to tweak)
  38   endian.h  fcntl.h  setjmp.h  stackinfo.h  uClibc_arch_features.h  wordsize.h
  39
  40   kernel_types.h should be created based upon linux asm-ARCH/posix_types.h
  41
  42   copy linux asm-ARCH/stat.h to bits/kernel_stat.h
  43
  44   create syscalls.h based upon linux's unistd.h / glibc's sysdeps.h ... really
  45   you just want to define the _syscall[0-6] macros.  It is important that
  46   these syscalls should be PIC safe (or you should provide a PIC and non-PIC
  47   version) if you wish to properly support shared libraries.
  48
  49 - at this point, you should have enough to generate a working HELLO WORLD
  50   static binary
  51
  52 - if you want UCLIBC_CTOR_DTOR support, you will need to create crti.S and
  53   crtn.S files which define function prologues/epilogues.
  54
  55 - for a more stable static port, you will need to create these files (and
  56   update the Makefile.arch values accordingly)
  57     __longjmp  bsd-_setjmp  bsd-setjmp  brk  clone  setjmp  syscall  vfork
  58   usually these are written in assembler, but you may be able to cheat and
  59   write them in C ... see other ports for more information
  60
  61 - Once static and pie executables are stable, static-pie support can be
  62   added by modifying crt1.S to calculate the address that the kernel loaded
  63   the main elf. Once the elf load address is found, call reloc_static_pie to
  64   perform all the dynamic relocations normally handled by ldso. This new
  65   code should be placed at the begining of _start and surrounded by defines
  66   so that it is only compiled into rcrt1.o and not the static or shared
  67   versions. This is usually done by using the special L_rcrt1 preprocessor
  68   define. i386 and x86_64 have good reference implementations.
  69
  70 ====================
  71 === ldso sysdeps ===
  72 ====================
  73 - elf.h - presumably you've already taught binutils all about the random ELF
  74   relocations your arch needs, so now you need to make sure the defines exist
  75   for uClibc.  make sure the EM_### define exists and all of the R_###_###
  76   reloc defines.
  77
  78 - enable ldso/shared options in your extra/Configs/Config.ARCH file
  79 - you will need to create the following files in ldso/ldso/ARCH/
  80   dl-startup.h  dl-syscalls.h  dl-sysdep.h  elfinterp.c  resolve.S
  81
  82 - dl-startup.h:
  83   - define the _start function which should call _dl_start which takes just one
  84     parameter ... a pointer to argc (usually on the stack)
  85     glibc stores this function in sysdeps/ARCH/dl-machine.h as RTLD_START
  86   - define the GET_ARGV() macro which calculates the value of argv based upon
  87     the parameter passed to _dl_start (usually it's simply just ARGS+1)
  88   - define PERFORM_BOOTSTRAP_RELOC() macro which will handle just the relocs
  89     that the ldso itself will generate
  90
  91 - dl-syscalls.h:
  92   if you wrote your bits/syscalls.h file correctly in the libc step above, you
  93   can simply copy this file from another arch and be done ... otherwise you
  94   will have to define the syscall[0-6] macros again, but this time setting
  95   _dl_errno instead of just errno
  96
  97 - dl-sysdep.h:
  98   misc cruft goes in here ... you want to:
  99   - either define or undefine ELF_USES_RELOCA
 100   - define the INIT_GOT macro
 101   - define MAGIC1 to the EM_### value your ELF arch uses
 102   - define ELF_TARGET to a string name for your arch
 103   - define the do_rem() macro
 104   - define misc ALIGN macro's
 105   - define elf_machine_type_class() macro
 106   - define the inline functions elf_machine_dynamic, elf_machine_load_address,
 107     and elf_machine_relative
 108   glibc stores a bunch of these values in sysdeps/ARCH/dl-machine.h
 109
 110 - elfinterp.c:
 111   define all the relocation functions ... it's best if you just copy from
 112   another arch which uses the same type of relocations (REL or RELA) and
 113   start from there.
 114
 115 - resolve.S:
 116   front end of lazy relocation ... define the _dl_linux_resolve symbol which
 117   is called by a PLT entry which has yet to be setup ... you will want to:
 118   - set up arguments for _dl_linux_resolver()
 119   - call _dl_linux_resolver()
 120   - clean up after call
 121   - jump to function address now stored in PLT
 122   glibc stores this function in sysdeps/ARCH/dl-trampoline.S
 123
 124 - utils/ldd.c - if you want support for ldso cache files (spoiler: you do),
 125   then you'll need to teach ldd a little.  generally, the fallback code
 126   should be smart and "just work", but you should be explicit.  just pop
 127   it open and add an appropriate ifdef for your arch and set MATCH_MACHINE()
 128   and ELFCLASSM.  there are plenty examples and you're (hopefully) smart.
 129
 130 ====================
 131 ===  Misc Cruft  ===
 132 ====================
 133 - MAINTAINERS - presumably you're going to submit this code back to mainline
 134   and since you're the only one who cares about this arch (right now), you
 135   should add yourself to the toplevel MAINTAINERS file.  do it.