docs/PORTING

   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 - for now, disable shared libraries
  12    add HAVE_NO_SHARED and ARCH_HAS_NO_LDSO to Config.ARCH's HAVE_ELF
  13
  14 ====================
  15 === libc sysdeps ===
  16 ====================
  17 (note: if glibc has already been ported to your arch, you can usually just
  18        copy a lot of files from them rather than coding from scratch)
  19 - create libc/sysdeps/linux/ARCH
  20 - copy Makefile and Makefile.arch from libc/sysdeps/linux/i386/
  21 - set CSRC and SSRC to nothing in Makefile.arch for now
  22
  23 - create crt1.S which defines the _start function ... you will probably want
  24   to clear the frame pointer to make gdb happy, and then you will want to call
  25   the funcion __uClibc_main() which takes these parameters:
  26    __uClibc_main(main(), argc, argv, _init(), _fini())
  27   for now, you can disable the UCLIBC_CTOR_DTOR option and just set those two
  28   arguments to NULL
  29   glibc stores this function in libc/sysdeps/ARCH/elf/start.S
  30
  31 - create these additional files in ARCH/bits/
  32
  33   (template versions can be found in common/bits/ for you to tweak)
  34   endian.h  fcntl.h  setjmp.h  stackinfo.h  uClibc_arch_features.h  wordsize.h
  35
  36   kernel_types.h should be created based upon linux asm-ARCH/posix_types.h
  37
  38   copy linux asm-ARCH/stat.h to bits/kernel_stat.h
  39
  40   create syscalls.h based upon linux's unistd.h / glibc's sysdeps.h ... really
  41   you just want to define the _syscall[0-6] macros
  42
  43 - at this point, you should have enough to generate a working HELLO WORLD
  44   static binary (see test/silly/*.c files)
  45
  46 - if you want UCLIBC_CTOR_DTOR support, you will need to create crti.S and
  47   crtn.S files which define function prologues/epilogues
  48
  49 - for a more stable static port, you will need to create these files (and
  50   update the Makefile.arch values accordingly)
  51     __longjmp  bsd-_setjmp  bsd-setjmp  brk  clone  setjmp  syscall  vfork
  52   usually these are written in assembler, but you may be able to cheat and
  53   write them in C ... see other ports for more information
  54
  55 ====================
  56 === pthread deps ===
  57 ====================
  58
  59 TODO: nptl / linuxthreads / linuxthreads.old
  60
  61 ====================
  62 === ldso sysdeps ===
  63 ====================
  64 - enable ldso/shared options in your extra/Configs/Config.ARCH file
  65 - you'll need to create these files in ldso/ldso/ARCH/
  66   dl-debug.h  dl-startup.h  dl-syscalls.h  dl-sysdep.h  elfinterp.c  resolve.S
  67
  68 - dl-debug.h: define string versions of all the relocations of your arch in the
  69   _dl_reltypes_tab array ... the index should match the actual reloc type, so
  70   if the value of say R_X86_64_PC16 is 13, then "R_X86_64_PC16" better be at
  71   index 13 of the array
  72
  73 - dl-startup.h:
  74   - define the _start function which should call _dl_start which takes just one
  75     parameter ... a pointer to argc (usually on the stack)
  76   - define the GET_ARGV() macro which calculates the value of argv based upon
  77     the parameter passed to _dl_start (usually it's simply just ARGS+1)
  78   - define PERFORM_BOOTSTRAP_RELOC() macro which will handle just the relocs
  79     that the ldso itself will generate
  80
  81 - dl-syscalls.h:
  82   if you wrote your bits/syscalls.h file correctly in the libc step above, you
  83   can simply copy this file from another arch and be done ... otherwise you
  84   will have to define the syscall[0-6] macros again, but this time setting
  85   _dl_errno instead of just errno
  86
  87 - dl-sysdep.h:
  88   misc cruft goes in here ... you want to:
  89   - either define or undefine ELF_USES_RELOCA
  90   - define the INIT_GOT macro
  91   - define MAGIC1 to the EM_### value your ELF arch uses
  92   - define ELF_TARGET to a string name for your arch
  93   - define the do_rem() macro
  94   - define misc ALIGN macro's
  95   - define elf_machine_type_class() macro
  96   - define the inline functions elf_machine_dynamic, elf_machine_load_address,
  97     and elf_machine_relative
  98   glibc stores a bunch of these values in libc/sysdeps/ARCH/dl-machine.h
  99
 100 - elfinterp.c:
 101   define all the relocation functions ... it's best if you just copy from
 102   another arch which uses the same type of relocations (REL or RELA) and
 103   start from there.
 104
 105 - resolve.S:
 106   front end of lazy relocation ... define the _dl_linux_resolve symbol which
 107   is called by a PLT entry which has yet to be setup ... you will want to:
 108   - set up arguments for _dl_linux_resolver()
 109   - call _dl_linux_resolver()
 110   - clean up after call
 111   - jump to function address now stored in PLT