PORTING 6.1 KB

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