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 | |
njn | 7df470b | 2005-05-29 18:46:38 +0000 | [diff] [blame] | 4 | [29-May-2005: the stuff about the locations of files is now badly out of |
| 5 | date. --njn] |
| 6 | |
njn | 4452e60 | 2004-11-30 19:27:02 +0000 | [diff] [blame] | 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 | |
njn | a6dbb3f | 2009-01-22 01:13:16 +0000 | [diff] [blame] | 20 | - Update configure.in (use x86 and x86-linux as a guide). |
njn | 4452e60 | 2004-11-30 19:27:02 +0000 | [diff] [blame] | 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 | |
njn | 107bc57 | 2009-02-16 00:42:10 +0000 | [diff] [blame] | 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. |
njn | 4452e60 | 2004-11-30 19:27:02 +0000 | [diff] [blame] | 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). |
njn | 4452e60 | 2004-11-30 19:27:02 +0000 | [diff] [blame] | 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 | |