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