[PATCH Web] Improve the introduction to mig-mutate.h and *mutations.h

[Zhaoming Luo]

Remove the mail list content from the wiki page because of the style
issue. Add the link to the mail list content in the 'Further Relevant
Documentation' section.

* microkernel/mach/mig/documentation.mdwn: Link to the new page.
* .../mach/mig/documentation/mig-mutate.mdwn: Delete it.
* .../documentation/type_translation_file.mdwn: New page.

Signed-off-by: Zhaoming Luo <zhmingluo@163.com>
---
 microkernel/mach/mig/documentation.mdwn       |   2 +-
 .../mach/mig/documentation/mig-mutate.mdwn    | 138 ------------------
 .../documentation/type_translation_file.mdwn  |  19 +++
 3 files changed, 20 insertions(+), 139 deletions(-)
 delete mode 100644 microkernel/mach/mig/documentation/mig-mutate.mdwn
 create mode 100644 
microkernel/mach/mig/documentation/type_translation_file.mdwn

diff --git a/microkernel/mach/mig/documentation.mdwn 
b/microkernel/mach/mig/documentation.mdwn
index 4c800e6b..8bf67351 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]].
 
-  * [[What is mig-mutate.h?|mig-mutate]]
+  * [[What is mig-mutate.h/mutations.h?|type_translation_file]]
 
 ## IRC, freenode, #hurd, 2013-09-04
 
diff --git a/microkernel/mach/mig/documentation/mig-mutate.mdwn 
b/microkernel/mach/mig/documentation/mig-mutate.mdwn
deleted file mode 100644
index dd027a04..00000000
--- a/microkernel/mach/mig/documentation/mig-mutate.mdwn
+++ /dev/null
@@ -1,138 +0,0 @@
-[[!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.
diff --git a/microkernel/mach/mig/documentation/type_translation_file.mdwn 
b/microkernel/mach/mig/documentation/type_translation_file.mdwn
new file mode 100644
index 00000000..0d001df4
--- /dev/null
+++ b/microkernel/mach/mig/documentation/type_translation_file.mdwn
@@ -0,0 +1,19 @@
+[[!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]]."]]"""]]
+
+In the Hurd repository, a server directory may have a file storing the type
+translation information; that file is either `mig-mutate.h` or `*mutations.h`.
+
+# Further Relevant Documentation
+
+The "Type Translation Information" section on page 17 of the [Mach 3 Server 
Writer's Guide](http://shakthimaan.com/downloads/hurd/server_writer.pdf).
+
+[https://mail.gnu.org/archive/html/bug-hurd/2024-11/msg00045.html](https://mail.gnu.org/archive/html/bug-hurd/2024-11/msg00045.html).
-- 
2.47.1