docs/internals/porting-HOWTO.txt

   1 This is a rough guide to porting Valgrind to a new architecture, or a new
   2 operating system.  It's quite preliminary, but should get you started.
   3
   4 [29-May-2005: the stuff about the locations of files is now badly out of
   5 date.  --njn]
   6
   7 -----------------------------------------------------------------------------
   8 Porting Valgrind to a new architecture
   9 -----------------------------------------------------------------------------
  10 Note that this implies both a new architecture, and a new platform (ie. arch/OS
  11 combination).  Please add to this list if it is missing anything.
  12
  13 To begin:
  14
  15 - Create necessary subdirs (copy x86/ and x86-linux/ subdirs).  Yes, even the
  16   test subdirectories.  (You should make arch-specific tests later to be
  17   thorough!)  Put in Makefile.am files for them, edit them for the new
  18   architecture name.
  19
  20 - Update configure.in (use x86 and x86-linux as a guide).
  21
  22 Once it configures ok, get it to compile:
  23
  24 - Create the Vex guest state type, VexGuest<ARCH>State
  25
  26 - Copy all the arch-specific and platform-specific files into the new
  27   directories, eg. from x86 and x86-linux.  Files like (this list is not
  28   exhaustive!):
  29
  30     include/x86/core_arch.h
  31     include/x86-linux/core_platform.h
  32     coregrind/x86/core_arch.h
  33     coregrind/x86-linux/core_platform.h
  34     coregrind/x86-linux/vki_arch.h
  35     coregrind/x86-linux/vki_arch_posixtypes.h
  36
  37   Edit obvious things like the file headers, and the #ifdef __X86_TOOL_ARCH_H
  38   guards, so they refer to the new architecture, rather than x86.
  39
  40   Comment all their contents out.
  41
  42 - Try compiling.  When it falls over on missing functions/types/constants, just
  43   uncomment and fix up the copied ones.  Just use stubs that fail (immediately
  44   and obviously! -- use the "I_die_here" macro) for functions and macros to get
  45   things compiling.
  46
  47   For the kernel types, you'll have to copy the types from the kernel source.
  48   Use a recent kernel source, please.  Don't just pull in all the
  49   corresponding types/macros that x86 provides, otherwise you might end up
  50   providing more types/macros than the core actually needs;  only pull in types
  51   as the compiler asks for them.  You'll need a lot of the types in
  52   vki_arch_posixtypes.h early on.
  53
  54   You'll need to update the Makefile.am files if you add/remove files.
  55
  56 Once it compiles ok, get it to run:
  57
  58 - Try running.  When it falls over on stub function/macros, implement them
  59   properly.  The syscall table and syscall wrappers will be painful;  do them
  60   individually, on demand.
  61
  62 - A lot of the arch-specific stuff has been abstracted out of the core, but
  63   there undoubtedly remains some arch-specific stuff in there.  Abstract it out
  64   as necessary, updating the other archs appropriately.
  65
  66 - If it crashes without telling you why, use lots of diagnostic printfs (or
  67   OINKs) to track down the exact location of the crash.
  68
  69 Once it runs ok:
  70
  71 - Add the arch to the tests/arch_test.c file so the reg test script will work.
  72   (Don't forget to add it to all_archs[].)  Likewise for os_test.in and
  73   platform_test.
  74
  75 - Ensure the regression tests work, and add some arch-specific tests to
  76   none/tests directory.
  77
  78 - Add the relevant entries to valgrind.spec.in (copy the x86 and x86-linux
  79   ones).
  80
  81 -----------------------------------------------------------------------------
  82 Porting Valgrind to a new OS
  83 -----------------------------------------------------------------------------
  84 Similarly to above, this implies both a new OS, and a new platform.
  85
  86 - Create necessary subdirs (copy linux/ and x86-linux/ subdirs).
  87
  88 - Update configure.in (use linux and x86-linux as a guide).
  89
  90 - Implement all the necessary OS-specific and platform-specific types,
  91   functions, and macros... use the following as templates:
  92
  93     include/linux/core_os.h
  94     include/x86-linux/core_platform.h
  95     coregrind/linux/core_os.h
  96     coregrind/x86-linux/core_platform.h
  97
  98 - You'll need to copy appropriate kernel types into vki*.h.
  99   You'll have to ensure that everywhere that vki_*/VKI_* types and constants
 100   are used, that they are suitable for your new OS, otherwise factor their
 101   usage out somehow.  This will be painful.
 102
 103 - In particular, you'll need to implement the VGA_(syscall_table).  You may be
 104   able to reuse some of the generic (eg. POSIX) syscall wrappers, if the types
 105   match.  Otherwise, you'll have to write your own new wrappers.  Do this
 106   incrementally, as system calls are hit, otherwise you'll go crazy.
 107
 108 - Probably lots more things;  this list should be added to!
 109
 110