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 <zhming...@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
