From 4d9a34c5fb5811b6498bfa531402ac77c2711aec Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Tue, 18 Apr 2023 23:42:23 +1000
Subject: [PATCH] Adding mmap API with test and documentation.

---
 lsp-dbus-test.lsp |  3 +--
 lsp-misc.a.8.adoc | 37 ++++++++++++++++++++++++++++++++++++-
 lsp-misc/mmap.lsp | 11 +++++++++--
 3 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/lsp-dbus-test.lsp b/lsp-dbus-test.lsp
index dd71083..94981b5 100644
--- a/lsp-dbus-test.lsp
+++ b/lsp-dbus-test.lsp
@@ -23,8 +23,7 @@
 (Dbus:process-all-pending)
 
 (println (setf org.bluez (Dbus "/" "org.bluez")))
-(println (if (:invoke org.bluez
-                      (println (:m ObjectManager "GetManagedObjects()")))
+(println (if (:invoke org.bluez (:m ObjectManager "GetManagedObjects()"))
              ($it -1 -1 -1) ; Return value
            ))
 
diff --git a/lsp-misc.a.8.adoc b/lsp-misc.a.8.adoc
index 5dd0b04..7f8a5d0 100644
--- a/lsp-misc.a.8.adoc
+++ b/lsp-misc.a.8.adoc
@@ -28,7 +28,7 @@ packnl _main.lsp_ *-A lsp-misc.a*
 The *prog1* function is like a *begin* function except that it returns
 the value of the first term rather than the last.
 
-(die [_N_ [_term_]])::
+(die _N_ [_term_]*)::
 
 The *die* function printes to stderr the join of term values as
 strings with space separation, and if _N_ is a number, then the
@@ -93,6 +93,41 @@ the respective naming formats (:%name obj) and (:!name obj value).
 --> A = (EX 1 4 3)
 ----
 
+=== mmap.lsp API
+
+This newlisp module implements a small FOOP model based memory mapping
+API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and
+_lseek_.
+
+(*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]])::
+
+This function creates a FOOP object that represents the memory mapping
+of the given file descriptor. _FD_ may be the pathname string of a
+file to memory map or an already opened file descriptor. The MMap
+object represents the memory block starting at (:%base) and (%len)
+bytes in length where the file is memory mapped.
++
+.Access example (from test.lsp)
+[caption=""]
+----
+(println (setf X (MMap "mmap.lsp")))
+(println (get-string (:%base X)))
+----
++
+Note that only a plain text file would be accessed with _get-string_.
+A binary file would rather be accessed with _unpack_. The memory
+mapping provides read-only "random access" to the file content.
++
+To set up read-write acces requires an _OFFSET_ and the _PROT_
+argument 0x3, and writing should be accompanied by _MMap:msync_ calls
+so as to synchronize with the backing file.
++
+The FOOP object includes get and set methods for the fields (in
+order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_.
+
+=== test.lsp
+
+This file is a small test of the MMap memory mapping.
 
 == SEE ALSO
 
diff --git a/lsp-misc/mmap.lsp b/lsp-misc/mmap.lsp
index 639b1c9..bb3f3be 100644
--- a/lsp-misc/mmap.lsp
+++ b/lsp-misc/mmap.lsp
@@ -28,19 +28,26 @@
         "int" ; int whence
         )
 
+(import LIBC "msync" "int"
+        "void*" ; void *addr
+        "long" ; size_t length
+        "int" ; int flags
+        )
+
 (constant
  'PROT_READ 0x01
+ 'PROT_WRITE 0x2
  'MAP_SHARED 0x01
  'SEEK_END 2
  )
 
 ;; Creates a new mapping in the virtual address space of the calling
 ;; process.
-(define (MMap:MMap FD LENGTH (OFFSET 0))
+(define (MMap:MMap FD LENGTH (OFFSET 0) (PROT PROT_READ))
   (when (string? FD) (setf FD (open FD "r")))
   (let ((D (list (context) nil LENGTH 0 0 FD OFFSET)))
     (when (< LENGTH) (setf (D 2) (lseek FD 0 SEEK_END)))
-    (setf (D 1) (mmap 0 (D 2) PROT_READ MAP_SHARED FD OFFSET))
+    (setf (D 1) (mmap 0 (D 2) PROT MAP_SHARED FD OFFSET))
     D))
 
 (define (Unmap)
-- 
2.39.2