From: Tom Hughes <tom@compton.nu>
Date: Fri, 30 Sep 2005 16:09:12 +0000 (+0000)
Subject: Document mmap insanity in a comment.
X-Git-Tag: svn/VALGRIND_3_1_0~388
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9bddb4c14131a895bafe0c9fec1970d445fe8a13;p=thirdparty%2Fvalgrind.git

Document mmap insanity in a comment.


git-svn-id: svn://svn.valgrind.org/valgrind/trunk@4840
---

diff --git a/coregrind/m_syswrap/syswrap-generic.c b/coregrind/m_syswrap/syswrap-generic.c
index 7f7629cdd8..c0030036d4 100644
--- a/coregrind/m_syswrap/syswrap-generic.c
+++ b/coregrind/m_syswrap/syswrap-generic.c
@@ -1713,6 +1713,31 @@ ML_(generic_POST_sys_shmctl) ( ThreadId tid,
    Generic handler for mmap
    ------------------------------------------------------------------ */
 
+/*
+ * Although mmap is specified by POSIX and the argument are generally
+ * consistent across platforms the precise details of the low level
+ * argument passing conventions differ. For example:
+ *
+ * - On x86-linux there is mmap (aka old_mmap) which takes the
+ *   arguments in a memory block and the offset in bytes; and
+ *   mmap2 (aka sys_mmap2) which takes the arguments in the normal
+ *   way and the offset in pages.
+ *
+ * - On ppc32-linux there is mmap (aka sys_mmap) which takes the
+ *   arguments in the normal way and the offset in bytes; and
+ *   mmap2 (aka sys_mmap2) which takes the arguments in the normal
+ *   way and the offset in pages.
+ *
+ * - On amd64-linux everything is simple and there is just the one
+ *   call, mmap (aka sys_mmap)  which takes the arguments in the
+ *   normal way and the offset in bytes.
+ *
+ * To cope with all this we provide a generic handler function here
+ * and then each platform implements one or more system call handlers
+ * which call this generic routine after extracting and normalising
+ * the arguments.
+ */
+
 SysRes
 ML_(generic_PRE_sys_mmap) ( ThreadId tid,
                             UWord arg1, UWord arg2, UWord arg3,