[COMMITTED] poke: add support for /r flag in .file dot-command

[Jose E. Marchesi]

It is important for performance to open files we don't intend to
modify in read-only mode.  This patch makes it easier to open files in
read-only mode by adding a new flag /r that can be appended to .file,
like int:

(poke) .file/r foo.o

Documentation updated and tests added.

2024-09-19  Jose E. Marchesi  <jemarch@gnu.org>

        * poke/pk-cmd-ios.c (PK_FILE_F_RDONLY): Define.
        (pk_cmd_file): Acknowledge /r flag in file dot-command.
        * poke/pk-cmd-ios.pk (pk_cmd_file): Likewise.
        * poke/pk-cmd-help.pk: Document /r flag in online documentation.
        * testsuite/poke.cmd/file-rdonly-1.pk: New test.
        * testsuite/Makefile.am (EXTRA_DIST): Add new test.
        * doc/poke.texi (Files as IO Spaces): Document /r.
        (file command): Likewise.
---
 ChangeLog                           | 11 +++++++++++
 doc/poke.texi                       | 18 ++++++++++++++----
 poke/pk-cmd-help.pk                 |  6 +++++-
 poke/pk-cmd-ios.c                   |  9 ++++++---
 poke/pk-cmd-ios.pk                  |  8 ++++++--
 testsuite/Makefile.am               |  1 +
 testsuite/poke.cmd/file-rdonly-1.pk |  6 ++++++
 7 files changed, 49 insertions(+), 10 deletions(-)
 create mode 100644 testsuite/poke.cmd/file-rdonly-1.pk

diff --git a/ChangeLog b/ChangeLog
index af3bd80b..06ebd28c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2024-09-19  Jose E. Marchesi  <jemarch@gnu.org>
+
+       * poke/pk-cmd-ios.c (PK_FILE_F_RDONLY): Define.
+       (pk_cmd_file): Acknowledge /r flag in file dot-command.
+       * poke/pk-cmd-ios.pk (pk_cmd_file): Likewise.
+       * poke/pk-cmd-help.pk: Document /r flag in online documentation.
+       * testsuite/poke.cmd/file-rdonly-1.pk: New test.
+       * testsuite/Makefile.am (EXTRA_DIST): Add new test.
+       * doc/poke.texi (Files as IO Spaces): Document /r.
+       (file command): Likewise.
+
 2024-09-19  Jose E. Marchesi  <jemarch@gnu.org>
 
        * libpoke/pvm-val.h: Remove spurious definition of
diff --git a/doc/poke.texi b/doc/poke.texi
index 523076c9..67f21dfa 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -1159,15 +1159,22 @@ Finally, the asterisk character at the left of the 
entry for
 clearly, let's open another file:
 
 @example
-(poke) .file bar.o
+(poke) .file/r bar.o
 The current IOS is now `./bar.o'.
 (poke) .info ios
   Id    Type    Volatile   Mode    Bias            Size            Name
-* 1     FILE    no         rw      0x00000000#B    0x00000398#B    ./bar.o
+* 1     FILE    no         r       0x00000000#B    0x00000398#B    ./bar.o
   0     FILE    no         rw      0x00000000#B    0x00000398#B    ./foo.o
 @end example
 
-Ah, there we have both @file{foo.o} and @file{bar.o}.  Now the current
+Ah, there we have both @file{foo.o} and @file{bar.o}.  Note how
+@file{bar.o} is opened in read-only mode rather than read-write.  This
+is because we used the @command{/r} flag when invoking the
+@command{.file} dot-command.  In poke it is important to open files in
+read-only mode if we don't plan to update them, because the program
+can work much faster.
+
+Now the current
 IO space (the entry featuring the asterisk at the left) is the file
 that we just opened, @file{bar.o}.  This is because poke always sets
 the most recently open file as the current one.  We can switch back to
@@ -1179,7 +1186,7 @@ an IO space as an argument:
 The current IOS is now `./foo.o'.
 (poke) .info ios
   Id    Type    Volatile   Mode    Bias            Size            Name
-  1     FILE    no         rw      0x00000000#B    0x00000398#B    ./bar.o
+  1     FILE    no         r       0x00000000#B    0x00000398#B    ./bar.o
 * 0     FILE    no         rw      0x00000000#B    0x00000398#B    ./foo.o
 @end example
 
@@ -8457,6 +8464,9 @@ If the specified file path doesn't exist then poke emits 
an error.
 However, the flag @command{/c} ( for ``create'') can be passed to the
 command to tell poke it should create a new file.
 
+A file can be opened in read-only mode by specifying the flag
+@command{/r}.
+
 @node mem command
 @section @code{.mem}
 @cindex @code{.mem}
diff --git a/poke/pk-cmd-help.pk b/poke/pk-cmd-help.pk
index b8ce1f40..d0d5241c 100644
--- a/poke/pk-cmd-help.pk
+++ b/poke/pk-cmd-help.pk
@@ -176,12 +176,16 @@ pk_help_add_topic
   :entry Poke_HelpEntry {
       category = "dot-commands",
       topic = ".file",
-      synopsis = ".file[/c] FILE",
+      synopsis = ".file[/cr] FILE",
       summary = "open a file",
       description = "\
 Open the given file as a new IO space and switch to it.  The
 open flags will be inferred from the permissions of the file.
 
+If the /r flag is used then the file is opened read-only.  Opening
+files that won't be modified in read-only mode is recommended because
+they don't require remaps.
+
 If the /c flag is used and no file with the given name exists,
 a new empty file will be created using the current UMASK and
 opened."
diff --git a/poke/pk-cmd-ios.c b/poke/pk-cmd-ios.c
index 21d0ad4e..14fc0bf0 100644
--- a/poke/pk-cmd-ios.c
+++ b/poke/pk-cmd-ios.c
@@ -201,8 +201,9 @@ pk_cmd_proc (int argc, struct pk_cmd_arg argv[], uint64_t 
uflags)
 #endif /* HAVE_PROC */
 }
 
-#define PK_FILE_UFLAGS "c"
+#define PK_FILE_UFLAGS "cr"
 #define PK_FILE_F_CREATE 0x1
+#define PK_FILE_F_RDONLY 0x2
 
 static int
 pk_cmd_file (int argc, struct pk_cmd_arg argv[], uint64_t uflags)
@@ -220,6 +221,7 @@ pk_cmd_file (int argc, struct pk_cmd_arg argv[], uint64_t 
uflags)
   const char *arg_str = PK_CMD_ARG_STR (argv[1]);
   const char *filename = arg_str;
   int create_p = uflags & PK_FILE_F_CREATE;
+  int rdonly_p = uflags & PK_FILE_F_RDONLY;
 
   if (access (filename, F_OK) == 0
       && create_p)
@@ -227,9 +229,10 @@ pk_cmd_file (int argc, struct pk_cmd_arg argv[], uint64_t 
uflags)
     create_p = 0;
 
   if (pk_call (poke_compiler, pk_cmd_file, &retval, &exit_exception,
-               2,
+               3,
                pk_make_string (poke_compiler, filename),
-               pk_make_int (poke_compiler, create_p, 32)) == PK_ERROR
+               pk_make_int (poke_compiler, create_p, 32),
+               pk_make_int (poke_compiler, rdonly_p, 32)) == PK_ERROR
       || exit_exception != PK_NULL)
     PK_UNREACHABLE (); /* This shouldn't happen.  */
 
diff --git a/poke/pk-cmd-ios.pk b/poke/pk-cmd-ios.pk
index 98458621..9b58e5dc 100644
--- a/poke/pk-cmd-ios.pk
+++ b/poke/pk-cmd-ios.pk
@@ -49,13 +49,17 @@ fun pk_openset_handler = (string handler, uint<64> flags = 
0) int<32>:
    FILENAME is the name of the file to open.
    CREATE_P is a flag indicating whether to create an empty file
    with the given name, if it doesn't exist.
+   RDONLY_P is a flag indicating whether the file has to be opened
+   read-only.
 
    If the specified file cannot be opened then this function raises an
    exception.  Otherwise returns the ID of the created IO space.  */
 
-fun pk_cmd_file = (string filename, int<32> create_p) int<32>:
+fun pk_cmd_file = (string filename, int<32> create_p, int<32> rdonly_p) 
int<32>:
 {
-  var flags = (create_p ? IOS_F_READ | IOS_F_WRITE | IOS_F_CREATE : 0);
+  var flags = (create_p ? IOS_F_READ | IOS_F_WRITE | IOS_F_CREATE
+               : rdonly_p ? IOS_F_READ
+               : 0);
 
   return pk_openset_handler (filename, flags);
 }
diff --git a/testsuite/Makefile.am b/testsuite/Makefile.am
index fda60303..8799dd32 100644
--- a/testsuite/Makefile.am
+++ b/testsuite/Makefile.am
@@ -83,6 +83,7 @@ EXTRA_DIST = \
   poke.cmd/file-bias-1.pk \
   poke.cmd/file-bias-2.pk \
   poke.cmd/file-mode.pk \
+  poke.cmd/file-rdonly-1.pk \
   poke.cmd/file-relative.pk \
   poke.cmd/ios-1.pk \
   poke.cmd/ios-2.pk \
diff --git a/testsuite/poke.cmd/file-rdonly-1.pk 
b/testsuite/poke.cmd/file-rdonly-1.pk
new file mode 100644
index 00000000..00516f5c
--- /dev/null
+++ b/testsuite/poke.cmd/file-rdonly-1.pk
@@ -0,0 +1,6 @@
+/* { dg-do run } */
+/* { dg-data {c*} {0x10 0x20 0x30 0x40 0x50 0x60 0x70 0x80} foo.data } */
+
+/* { dg-command { .file/r foo.data } } */
+/* { dg-command { ioflags & IOS_F_WRITE } } */
+/* { dg-output "0UL" } */
-- 
2.30.2