Final commit for the initial modularisation pass:
- Broke part of m_scheduler off into a new module m_threadstate. It
contains ThreadState, VG_(threads)[] and some basic operations on the
thread table. All simple stuff, the complex stuff stays in m_scheduler.
This avoids lots of circular dependencies between m_scheduler and other
modules.
- Managed to finally remove core.h and tool.h, double hurrah!
- Introduced pub_tool_basics.h and pub_core_basics.h, one of which is
include by every single C file.
- Lots of little cleanups and changes related to the above.
- I even did a small amount of documentation updating.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@3944 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/directory-structure b/docs/directory-structure
index e8a6e40..a03e3fd 100644
--- a/docs/directory-structure
+++ b/docs/directory-structure
@@ -1,16 +1,14 @@
-------------------------------------------------------------------
Guide to the directory structure
-------------------------------------------------------------------
-[16-May-2005: a lot of the stuff about arch/OS/platform specific code
- is out of date in here. Hopefully, things have gotten simpler. --njn]
+[This should be merged with coregrind/README_MODULES.txt]
Valgrind has 2 main levels of genericity.
1. Multiple tools, plus the core.
2. Multiple architectures, OSes, and platforms (arch/OS combinations).
-This requires a moderately complex directory structure. This file is a
-guide to where different things live.
+This file is a guide to where different things live.
Basic layout
@@ -18,7 +16,8 @@
1. Core stuff lives in:
- include/ for declarations that must be seen by tools
- coregrind/ for code that need not be seen by tools
- - coregrind/demangle/ the demangler
+
+ Some subdirs of coregrind/ hold modules that consist of multiple files.
Tool stuff lives in:
- $TOOL/ main files
@@ -33,49 +32,41 @@
2. Generic things go in the directory specified in (1).
- Arch-specific, OS-specific, or platform-specific things go within a
- subdirectory of the directory specified by step (1) above.
+ Arch-specific, OS-specific, or platform-specific things are sprinkled
+ throughout the code -- there is no single place for all the
+ architecture-specific things, for example.
+
+ Sometimes we have a whole file holding things specific to a particular
+ arch/OS/platform. Such files have an appropriate suffix, eg.
+ sigframe-x86-linux.c.
- For example:
- - Cachegrind's main generic code goes in cachegrind/.
- - Cachegrind's x86-specific code goes in cachegrind/x86/.
- - Cachegrind's x86-specific tests go in cachegrind/tests/x86/.
- - x86/Linux-specific declarations that must be visible to tools go in
- include/x86-linux/.
+ More often we use #ifdefs inside source files to specify the different
+ cases for different archs/OSes/platforms. It's pretty straightforward.
+
+ A final case: arch-specific regression tests for tools go in a
+ subdirectory, eg. cachegrind/tests/x86/.
Guide to headers
----------------
-Finding declarations in headers is not always easy. The above rules dictate
-which directory something should go in. As well as that, there are some things
-that must be visible in both C and assembly code files, but most things only be
-visible in C files; things that must be both C-visible and asm-visible go in
-files called *_asm.h.
+See coregrind/README_MODULES.txt for details of the core/tool header file
+split.
-The most important header files are (at the time of writing):
-- include/tool.h (auto-generated from tool.h.base + toolfuncs.def)
-- include/tool_asm.h
-- $ARCH/tool_arch.h
-- $OS/vki.h
-- $PLATFORM/vki*.h
-- coregrind/{core.h,core_asm.h}
-- $ARCH/{core_arch.h,core_arch_asm.h}
-- $OS/core_os.h
-- $PLATFORM/{core_platform.h,vki_unistd.h}
+Note that every single C file will #include pub_basics.h. Every single asm
+file will #include pub_basics_asm.h.
-There are a few others, but that is most of them.
-
-Having read the above text, it should be clear what is found in each of them.
-For example, coregrind/core_asm.h contains all the generic
-(non-arch/OS/platform-specific) declarations which should not be seen by
-tools and must be visible to both C and asm code.
+Our versions of kernel types are in the vki*.h headers.
When searching for something, rgrep is very useful. If you don't have a
version of rgrep, use a command something like this:
find . -name '*.h' | xargs grep <pattern>
-The comment at the top of coregrind/core.h has some additional information
-about the exact hierarchy of the header files, but those details aren't
-important for just finding and placing things.
+ find . -name '*.h' \
+ -type f \
+ -not -path '*.svn\/*' | xargs grep "$1"
+
+The -name option gives the file wildcard, the -type says "look in normal
+files only" and the -not -path tells it to not look in Subversions hidden
+directories.