From: Nicholas Nethercote Date: Tue, 30 Nov 2004 19:27:02 +0000 (+0000) Subject: Added a short document about how to port to a new arch or OS. X-Git-Tag: svn/VALGRIND_3_0_0~1148 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f14fd8b2a14a57edce5a17823b4258ca2637fc3e;p=thirdparty%2Fvalgrind.git Added a short document about how to port to a new arch or OS. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@3170 --- diff --git a/docs/Makefile.am b/docs/Makefile.am index cfcb98d200..da4abb9bce 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,6 +1,6 @@ SUBDIRS = xml lib images -EXTRA_DIST = README +EXTRA_DIST = README porting-HOWTO ##------------------------------------------------------------------- ## Below here is more ordinary make stuff... diff --git a/docs/porting-HOWTO b/docs/porting-HOWTO new file mode 100644 index 0000000000..22254055c8 --- /dev/null +++ b/docs/porting-HOWTO @@ -0,0 +1,108 @@ +This is a rough guide to porting Valgrind to a new architecture, or a new +operating system. It's quite preliminary, but should get you started. + +----------------------------------------------------------------------------- +Porting Valgrind to a new architecture +----------------------------------------------------------------------------- +Note that this implies both a new architecture, and a new platform (ie. arch/OS +combination). Please add to this list if it is missing anything. + +To begin: + +- Create necessary subdirs (copy x86/ and x86-linux/ subdirs). Yes, even the + test subdirectories. (You should make arch-specific tests later to be + thorough!) Put in Makefile.am files for them, edit them for the new + architecture name. + +- Update configure.in (use x86 and x86-linux as a guide). Don't forget to + update VG_ARCH_ALL, VG_PLATFORM_ALL. + +Once it configures ok, get it to compile: + +- Create the Vex guest state type, VexGuestState + +- Copy all the arch-specific and platform-specific files into the new + directories, eg. from x86 and x86-linux. Files like (this list is not + exhaustive!): + + include/x86/core_arch.h + include/x86-linux/core_platform.h + coregrind/x86/core_arch.h + coregrind/x86-linux/core_platform.h + coregrind/x86-linux/vki_arch.h + coregrind/x86-linux/vki_arch_posixtypes.h + + Edit obvious things like the file headers, and the #ifdef __X86_TOOL_ARCH_H + guards, so they refer to the new architecture, rather than x86. + + Comment all their contents out. + +- Try compiling. When it falls over on missing functions/types/constants, just + uncomment and fix up the copied ones. Just use stubs that fail (immediately + and obviously! -- use the "I_die_here" macro) for functions and macros to get + things compiling. + + For the kernel types, you'll have to copy the types from the kernel source. + Use a recent kernel source, please. Don't just pull in all the + corresponding types/macros that x86 provides, otherwise you might end up + providing more types/macros than the core actually needs; only pull in types + as the compiler asks for them. You'll need a lot of the types in + vki_arch_posixtypes.h early on. + + You'll need to update the Makefile.am files if you add/remove files. + +Once it compiles ok, get it to run: + +- Try running. When it falls over on stub function/macros, implement them + properly. The syscall table and syscall wrappers will be painful; do them + individually, on demand. + +- A lot of the arch-specific stuff has been abstracted out of the core, but + there undoubtedly remains some arch-specific stuff in there. Abstract it out + as necessary, updating the other archs appropriately. + +- If it crashes without telling you why, use lots of diagnostic printfs (or + OINKs) to track down the exact location of the crash. + +Once it runs ok: + +- Add the cpu to the tests/cputest.c file so the reg test script will work. + (Don't forget to add it to all_archs[].) + +- Ensure the regression tests work, and add some arch-specific tests to + none/tests directory. + +- Add the relevant entries to valgrind.spec.in (copy the x86 and x86-linux + ones). + +----------------------------------------------------------------------------- +Porting Valgrind to a new OS +----------------------------------------------------------------------------- +Similarly to above, this implies both a new OS, and a new platform. + +- Create necessary subdirs (copy linux/ and x86-linux/ subdirs). + +- Update configure.in (use linux and x86-linux as a guide). + Don't forget to update VG_OS_ALL, VG_PLATFORM_ALL. + +- Implement all the necessary OS-specific and platform-specific types, + functions, and macros... use the following as templates: + + include/linux/core_os.h + include/x86-linux/core_platform.h + coregrind/linux/core_os.h + coregrind/x86-linux/core_platform.h + +- You'll need to copy appropriate kernel types into vki*.h. + You'll have to ensure that everywhere that vki_*/VKI_* types and constants + are used, that they are suitable for your new OS, otherwise factor their + usage out somehow. This will be painful. + +- In particular, you'll need to implement the VGA_(syscall_table). You may be + able to reuse some of the generic (eg. POSIX) syscall wrappers, if the types + match. Otherwise, you'll have to write your own new wrappers. Do this + incrementally, as system calls are hit, otherwise you'll go crazy. + +- Probably lots more things; this list should be added to! + +