Add microkernel/mach/mig/documentation/mig-mutate page

* microkernel/mach/mig/documentation.mdwn: add a link pointing to mig-mutate page
* .../mach/mig/documentation/mig-mutate.mdwn: new file. Introduction to a mig-mutate.h file

Signed-off-by: Zhaoming Luo <zhmingluo@163.com>
Message-ID: <20241211033007.536408-2-zhmingluo@163.com>

2 files changed, 139 insertions, 1 deletions

diff --git a/microkernel/mach/mig/documentation.mdwn b/microkernel/mach/mig/documentation.mdwn
index 06536386..4c800e6b 100644
--- a/microkernel/mach/mig/documentation.mdwn
+++ b/microkernel/mach/mig/documentation.mdwn
@@ -85,7 +85,7 @@ pp. 67--77."
 
   * MIG *in action*: [[hurd/io_path]].
 
-  * [*Introduction to a mig-mutate.h file*](https://mail.gnu.org/archive/html/bug-hurd/2024-11/msg00045.html), a text by Sergey Bugaev
+  * [[What is mig-mutate.h?|mig-mutate]]
 
 ## IRC, freenode, #hurd, 2013-09-04
 
diff --git a/microkernel/mach/mig/documentation/mig-mutate.mdwn b/microkernel/mach/mig/documentation/mig-mutate.mdwn
new file mode 100644
index 00000000..dd027a04
--- /dev/null
+++ b/microkernel/mach/mig/documentation/mig-mutate.mdwn
@@ -0,0 +1,138 @@
+[[!meta copyright="Copyright © 2024 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+The text in this page is based on the following code (from `$(hurd)/rtc/mig-mutate.h`):
+
+	#define IO_INTRAN trivfs_protid_t trivfs_begin_using_protid (io_t)
+	#define IO_INTRAN_PAYLOAD trivfs_protid_t trivfs_begin_using_protid_payload
+	#define IO_DESTRUCTOR trivfs_end_using_protid (trivfs_protid_t)
+	#define IO_IMPORTS import "libtrivfs/mig-decls.h";
+
+First, a brief description of what a protid is. Hurd translators
+typically represent "files" internally with three kinds of distinct
+structures:
+
+1. **node** -- these are filesystem nodes, same concept as an "inode".
+2. **peropen** -- this keeps the data "per open" of the file and
+corresponds to an "open file description" in POSIX. Things like
+current I/O offset and the open mode (`O_READ | O_WRITE` ...) live here.
+3. **protid** (or "credential") -- describes a specific "user" (UIDs/GIDs)
+on behalf of whom the file is being accessed.
+
+A protid has a pointer to the peropen, and the peropen has a pointer
+to the node. A node can have multiple peropens referring to it (when
+the file has been opened multiple times), and a peropen can have
+multiple protids referring to it (when processes running as different
+users share an open file description, e.g. your shell and a sudo
+invocation share the pts). In trivfs, there's only a single node, so
+the concept is deemphasized.
+
+The concept of protid doesn't exist in classic Unix, since a
+monolithic kernel can just directly see which UID the current process
+runs as. But Mach IPC is (intentionally) designed in a way that it's
+inherently impossible to see "who's asking", so instead we represent
+differently-privileged callers with different handles (protids) that
+refer to the same peropen, and then we check which protid the request
+was made on.
+
+It is a protid that corresponds to an Mach port (`io_t`, `file_t`, ...),
+though the client side doesn't need to care.
+
+When an incoming request arrives, the thing you actually receive in a
+message is the port name (ignoring protected payloads for now). What
+you actually want is the protid that it corresponds to.
+
+trivfs has the API to look up the protid given the port, namely
+`trivfs_begin_using_protid` (which wraps `ports_lookup_port` from
+libports), and you could call that yourself:
+
+	kern_return_t
+	rtc_S_foobar (io_t port, int foo, int *bar)
+	{
+	  error_t err = 0;
+	  struct trivfs_protid *cred = trivfs_begin_using_protid (port);
+	
+	  if (!cred)
+	    /* The request came in on a port that we listen for incoming
+	     * messages on, but it doesn't correspond to a protid. Must
+	     * be some other kind of port. */
+	    return EOPNOTSUPP;
+	
+	  if (!(cred->po->openmodes & O_READ))
+	    {
+	      err = EBADF;
+	      goto out;
+	    }
+
+  do something with cred...
+
+	out:
+	  trivfs_end_using_protid (cred);
+	  return err;
+	}
+
+But since we already have a code generator (MIG), why not make it
+generate the conversion logic for us as well. And so, in MIG, when
+defining a type, you can provide `intran` and `outtran` and
+`destructor` function names, and MIG will generate the calls for you.
+
+So the proper MIG way to (but see below about the Hurd way) to do the
+thing that you're trying to do would be to define your own flavor of
+Mach ports, say `rtc_port_t`, like this:
+
+	type rtc_port_t = mach_port_t
+	  intran: trivfs_protid_t trivfs_begin_using_protid (io_t)
+	  destructor: trivfs_end_using_protid (trivfs_protid_t);
+
+and then use that type in the routine definitions. MIG would then call
+`trivfs_begin_using_protid` and `trivfs_end_using_protid` in the server-side
+generated functions, only passing `trivfs_protid_t` (which is a typedef
+for `struct trivfs_protid *`, since MIG can't deal with the full C type
+notation) to your implementation. The downside of this is that it the
+implementation details of the server leak into the API definition, and
+for instance you'd have to edit the `.defs` if you switch the server
+from trivfs to netfs.
+
+You can find some documentation about this MIG feature under "Type
+Translation Information" on page 17 of the [Mach 3 Server Writer’s
+Guide](http://shakthimaan.com/downloads/hurd/server_writer.pdf),
+but of course keep in mind that the guide was written a long time
+ago, about a much older version of MIG, without any of the Hurd
+additions/specifics/best practices.
+
+Then, `hurd_types.defs` has this:
+
+	type io_t = mach_port_copy_send_t
+	#ifdef IO_INTRAN
+	intran: IO_INTRAN
+	intranpayload: IO_INTRAN_PAYLOAD
+	#else
+	#ifdef HURD_DEFAULT_PAYLOAD_TO_PORT
+	intranpayload: io_t HURD_DEFAULT_PAYLOAD_TO_PORT
+	#endif
+	#endif
+	#ifdef IO_OUTTRAN
+	outtran: IO_OUTTRAN
+	#endif
+	#ifdef IO_DESTRUCTOR
+	destructor: IO_DESTRUCTOR
+	#endif
+	;
+
+(and same for all the other types of ports, e.g. `FILE_INTRAN`,
+`SHUTDOWN_DESTRUCTOR` etc)
+
+which lets you use the standard `io_t` type while plugging in your own
+`intran/intranpayload/outtran/destructor` functions, in a way that
+doesn't leak into the `defs`. You only have to define the macros in your
+local `mig-mutate.h` header in your server.
+
+The content in this page is from [bug-hurd mail list](https://mail.gnu.org/archive/html/bug-hurd/2024-11/msg00045.html) with some modifications.