docs: UML: user_mode_linux_howto_v2 edits

Fix various typos, command syntax, punctuation, capitalization,
and whitespace.

Fixes: 04301bf5b072 ("docs: replace the old User Mode Linux HowTo with a new one")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jeff Dike <jdike@addtoit.com>
Cc: Richard Weinberger <richard@nod.at>
Cc: Anton Ivanov <anton.ivanov@cambridgegreys.com>
Cc: linux-um@lists.infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Acked-By: anton ivanov <anton.ivanov@cambridgegreys.com>
Link: https://lore.kernel.org/r/20211010064827.3405-1-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

1 files changed, 62 insertions, 57 deletions

diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst
index 312e431695d9..2cafd3c3c6cb 100644
--- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst
+++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst
@@ -128,7 +128,7 @@ Create a minimal OS installation on the mounted filesystem::
 debootstrap does not set up the root password, fstab, hostname or
 anything related to networking. It is up to the user to do that.
 
-Set the root password -t he easiest way to do that is to chroot into the
+Set the root password - the easiest way to do that is to chroot into the
 mounted image::
 
    # chroot /mnt
@@ -144,7 +144,7 @@ will be empty and it needs an entry for the root file system::
    /dev/ubd0   ext4    discard,errors=remount-ro  0       1
 
 The image hostname will be set to the same as the host on which you
-are creating it image. It is a good idea to change that to avoid
+are creating its image. It is a good idea to change that to avoid
 "Oh, bummer, I rebooted the wrong machine".
 
 UML supports two classes of network devices - the older uml_net ones
@@ -162,7 +162,7 @@ need entries like::
 
    # vector UML network devices
    auto vec0
-   iface eth0 inet dhcp
+   iface vec0 inet dhcp
 
 We now have a UML image which is nearly ready to run, all we need is a
 UML kernel and modules for it.
@@ -179,7 +179,12 @@ directory to the mounted UML filesystem::
 If you have compiled your own kernel, you need to use the usual "install
 modules to a location" procedure by running::
 
-  # make install MODULES_DIR=/mnt/lib/modules
+  # make INSTALL_MOD_PATH=/mnt/lib/modules modules_install
+
+This will install modules into /mnt/lib/modules/$(KERNELRELEASE).
+To specify the full module installation path, use::
+
+  # make MODLIB=/mnt/lib/modules modules_install
 
 At this point the image is ready to be brought up.
 
@@ -188,7 +193,7 @@ Setting Up UML Networking
 *************************
 
 UML networking is designed to emulate an Ethernet connection. This
-connection may be either a point-to-point (similar to a connection
+connection may be either point-to-point (similar to a connection
 between machines using a back-to-back cable) or a connection to a
 switch. UML supports a wide variety of means to build these
 connections to all of: local machine, remote machine(s), local and
@@ -231,7 +236,7 @@ remote UML and other VM instances.
 * All transports which have multi-packet rx and/or tx can deliver pps
   rates of up to 1Mps or more.
 
-* All legacy transports are generally limited to ~600-700MBit and 0.05Mps
+* All legacy transports are generally limited to ~600-700MBit and 0.05Mps.
 
 * GRE and L2TPv3 allow connections to all of: local machine, remote
   machines, remote network devices and remote UML instances.
@@ -255,7 +260,7 @@ raw sockets where needed.
 
 This can be achieved by granting the user a particular capability instead
 of running UML as root.  In case of vector transport, a user can add the
-capability ``CAP_NET_ADMIN`` or ``CAP_NET_RAW``, to the uml binary.
+capability ``CAP_NET_ADMIN`` or ``CAP_NET_RAW`` to the uml binary.
 Thenceforth, UML can be run with normal user privilges, along with
 full networking.
 
@@ -286,7 +291,7 @@ These options are common for all transports:
 
 * ``mac=XX:XX:XX:XX:XX`` - sets the interface MAC address value.
 
-* ``gro=[0,1]`` - sets GRO on or off. Enables receive/transmit offloads.
+* ``gro=[0,1]`` - sets GRO off or on. Enables receive/transmit offloads.
   The effect of this option depends on the host side support in the transport
   which is being configured. In most cases it will enable TCP segmentation and
   RX/TX checksumming offloads. The setting must be identical on the host side
@@ -301,7 +306,7 @@ These options are common for all transports:
 * ``headroom=int`` - adjusts the default headroom (32 bytes) reserved
   if a packet will need to be re-encapsulated into for instance VXLAN.
 
-* ``vec=0`` - disable multipacket io and fall back to packet at a
+* ``vec=0`` - disable multipacket IO and fall back to packet at a
   time mode
 
 Shared Options
@@ -331,7 +336,7 @@ Example::
 This will connect vec0 to tap0 on the host. Tap0 must already exist (for example
 created using tunctl) and UP.
 
-tap0 can be configured as a point-to-point interface and given an ip
+tap0 can be configured as a point-to-point interface and given an IP
 address so that UML can talk to the host. Alternatively, it is possible
 to connect UML to a tap interface which is connected to a bridge.
 
@@ -358,7 +363,7 @@ Example::
 
 This is an experimental/demo transport which couples tap for transmit
 and a raw socket for receive. The raw socket allows multi-packet
-receive resulting in significantly higher packet rates than normal tap
+receive resulting in significantly higher packet rates than normal tap.
 
 Privileges required: hybrid requires ``CAP_NET_RAW`` capability by
 the UML user as well as the requirements for the tap transport.
@@ -426,10 +431,10 @@ This will configure an Ethernet over ``GRE`` (aka ``GRETAP`` or
 endpoint at host dst_host. ``GRE`` supports the following additional
 options:
 
-* ``rx_key=int`` - GRE 32 bit integer key for rx packets, if set,
+* ``rx_key=int`` - GRE 32-bit integer key for rx packets, if set,
   ``txkey`` must be set too
 
-* ``tx_key=int`` - GRE 32 bit integer key for tx packets, if set
+* ``tx_key=int`` - GRE 32-bit integer key for tx packets, if set
   ``rx_key`` must be set too
 
 * ``sequence=[0,1]`` - enable GRE sequence
@@ -444,12 +449,12 @@ options:
 
 GRE has a number of caveats:
 
-* You can use only one GRE connection per ip address. There is no way to
+* You can use only one GRE connection per IP address. There is no way to
   multiplex connections as each GRE tunnel is terminated directly on
   the UML instance.
 
 * The key is not really a security feature. While it was intended as such
-  it's "security" is laughable. It is, however, a useful feature to
+  its "security" is laughable. It is, however, a useful feature to
   ensure that the tunnel is not misconfigured.
 
 An example configuration for a Linux host with a local address of
@@ -489,22 +494,22 @@ the L2TPv3 UDP flavour and UDP destination port $dst_port.
 
 L2TPv3 always requires the following additional options:
 
-* ``rx_session=int`` - l2tpv3 32 bit integer session for rx packets
+* ``rx_session=int`` - l2tpv3 32-bit integer session for rx packets
 
-* ``tx_session=int`` - l2tpv3 32 bit integer session for tx packets
+* ``tx_session=int`` - l2tpv3 32-bit integer session for tx packets
 
 As the tunnel is fixed these are not negotiated and they are
 preconfigured on both ends.
 
-Additionally, L2TPv3 supports the following optional parameters
+Additionally, L2TPv3 supports the following optional parameters.
 
-* ``rx_cookie=int`` - l2tpv3 32 bit integer cookie for rx packets - same
+* ``rx_cookie=int`` - l2tpv3 32-bit integer cookie for rx packets - same
   functionality as GRE key, more to prevent misconfiguration than provide
   actual security
 
-* ``tx_cookie=int`` - l2tpv3 32 bit integer cookie for tx packets
+* ``tx_cookie=int`` - l2tpv3 32-bit integer cookie for tx packets
 
-* ``cookie64=[0,1]`` - use 64 bit cookies instead of 32 bit.
+* ``cookie64=[0,1]`` - use 64-bit cookies instead of 32-bit.
 
 * ``counter=[0,1]`` - enable l2tpv3 counter
 
@@ -518,12 +523,12 @@ Additionally, L2TPv3 supports the following optional parameters
 
 L2TPv3 has a number of caveats:
 
-* you can use only one connection per ip address in raw mode. There is
+* you can use only one connection per IP address in raw mode. There is
   no way to multiplex connections as each L2TPv3 tunnel is terminated
   directly on the UML instance. UDP mode can use different ports for
   this purpose.
 
-Here is an example of how to configure a linux host to connect to UML
+Here is an example of how to configure a Linux host to connect to UML
 via L2TPv3:
 
 **/etc/network/interfaces**::
@@ -586,7 +591,7 @@ distribution or a custom built kernel has been installed on the host.
 These add an executable called linux to the system. This is the UML
 kernel. It can be run just like any other executable.
 It will take most normal linux kernel arguments as command line
-arguments.  Additionally, it will need some UML specific arguments
+arguments.  Additionally, it will need some UML-specific arguments
 in order to do something useful.
 
 Arguments
@@ -595,7 +600,7 @@ Arguments
 Mandatory Arguments:
 --------------------
 
-* ``mem=int[K,M,G]`` - amount of memory. By default bytes. It will
+* ``mem=int[K,M,G]`` - amount of memory. By default in bytes. It will
   also accept K, M or G qualifiers.
 
 * ``ubdX[s,d,c,t]=`` virtual disk specification. This is not really
@@ -603,7 +608,7 @@ Mandatory Arguments:
   specify a root file system.
   The simplest possible image specification is the name of the image
   file for the filesystem (created using one of the methods described
-  in `Creating an image`_)
+  in `Creating an image`_).
 
   * UBD devices support copy on write (COW). The changes are kept in
     a separate file which can be discarded allowing a rollback to the
@@ -613,15 +618,15 @@ Mandatory Arguments:
 
   * UBD devices can be set to use synchronous IO. Any writes are
     immediately flushed to disk. This is done by adding ``s`` after
-    the ``ubdX`` specification
+    the ``ubdX`` specification.
 
-  * UBD performs some euristics on devices specified as a single
+  * UBD performs some heuristics on devices specified as a single
     filename to make sure that a COW file has not been specified as
-    the image. To turn them off, use the ``d`` flag after ``ubdX``
+    the image. To turn them off, use the ``d`` flag after ``ubdX``.
 
   * UBD supports TRIM - asking the Host OS to reclaim any unused
     blocks in the image. To turn it off, specify the ``t`` flag after
-    ``ubdX``
+    ``ubdX``.
 
 * ``root=`` root device - most likely ``/dev/ubd0`` (this is a Linux
   filesystem image)
@@ -631,7 +636,7 @@ Important Optional Arguments
 
 If UML is run as "linux" with no extra arguments, it will try to start an
 xterm for every console configured inside the image (up to 6 in most
-linux distributions). Each console is started inside an
+Linux distributions). Each console is started inside an
 xterm. This makes it nice and easy to use UML on a host with a GUI. It is,
 however, the wrong approach if UML is to be used as a testing harness or run
 in a text-only environment.
@@ -656,10 +661,10 @@ one is input, the second one output.
 * The null channel - Discard all input or output. Example ``con=null`` will set
   all consoles to null by default.
 
-* The fd channel - use file descriptor numbers for input/out. Example:
+* The fd channel - use file descriptor numbers for input/output. Example:
   ``con1=fd:0,fd:1.``
 
-* The port channel - listen on tcp port number. Example: ``con1=port:4321``
+* The port channel - listen on TCP port number. Example: ``con1=port:4321``
 
 * The pty and pts channels - use system pty/pts.
 
@@ -667,7 +672,7 @@ one is input, the second one output.
   will make UML use the host 8th console (usually unused).
 
 * The xterm channel - this is the default - bring up an xterm on this channel
-  and direct IO to it. Note, that in order for xterm to work, the host must
+  and direct IO to it. Note that in order for xterm to work, the host must
   have the UML distribution package installed. This usually contains the
   port-helper and other utilities needed for UML to communicate with the xterm.
   Alternatively, these need to be complied and installed from source. All
@@ -685,7 +690,7 @@ We can now run UML.
     vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
     root=/dev/ubda con=null con0=null,fd:2 con1=fd:0,fd:1
 
-This will run an instance with ``2048M RAM``, try to use the image file
+This will run an instance with ``2048M RAM`` and try to use the image file
 called ``Filesystem.img`` as root. It will connect to the host using tap0.
 All consoles except ``con1`` will be disabled and console 1 will
 use standard input/output making it appear in the same terminal it was started.
@@ -702,7 +707,7 @@ The UML Management Console
 ============================
 
 In addition to managing the image from "the inside" using normal sysadmin tools,
-it is possible to perform a number of low level operations using the UML
+it is possible to perform a number of low-level operations using the UML
 management console. The UML management console is a low-level interface to the
 kernel on a running UML instance, somewhat like the i386 SysRq interface. Since
 there is a full-blown operating system under UML, there is much greater
@@ -726,7 +731,7 @@ kernel.  When you boot UML, you'll see a line like::
 
    mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
 
-If you specify a unique machine id one the UML command line, i.e. 
+If you specify a unique machine id on the UML command line, i.e.
 ``umid=debian``, you'll see this::
 
    mconsole initialized on /home/jdike/.uml/debian/mconsole
@@ -881,11 +886,11 @@ be able to cache the shared data using a much smaller amount of memory,
 so UML disk requests will be served from the host's memory rather than
 its disks.  There is a major caveat in doing this on multisocket NUMA
 machines.  On such hardware, running many UML instances with a shared
-master image and COW changes may caise issues like NMIs from excess of
+master image and COW changes may cause issues like NMIs from excess of
 inter-socket traffic.
 
-If you are running UML on high end hardware like this, make sure to
-bind UML to a set of logical cpus residing on the same socket using the
+If you are running UML on high-end hardware like this, make sure to
+bind UML to a set of logical CPUs residing on the same socket using the
 ``taskset`` command or have a look at the "tuning" section.
 
 To add a copy-on-write layer to an existing block device file, simply
@@ -986,7 +991,7 @@ specify a subdirectory to mount with the -o switch to mount::
 
    # mount none /mnt/home -t hostfs -o /home
 
-will mount the hosts's /home on the virtual machine's /mnt/home.
+will mount the host's /home on the virtual machine's /mnt/home.
 
 hostfs as the root filesystem
 -----------------------------
@@ -1035,7 +1040,7 @@ The UBD driver, SIGIO and the MMU emulation do that. If the system is
 idle, these threads will be migrated to other processors on a SMP host.
 This, unfortunately, will usually result in LOWER performance because of
 all of the cache/memory synchronization traffic between cores. As a
-result, UML will usually benefit from being pinned on a single CPU
+result, UML will usually benefit from being pinned on a single CPU,
 especially on a large system. This can result in performance differences
 of 5 times or higher on some benchmarks.
 
@@ -1061,7 +1066,7 @@ filesystems, devices, virtualization, etc. It provides unrivalled
 opportunities to create and test them without being constrained to
 emulating specific hardware.
 
-Example - want to try how linux will work with 4096 "proper" network
+Example - want to try how Linux will work with 4096 "proper" network
 devices?
 
 Not an issue with UML. At the same time, this is something which
@@ -1070,10 +1075,10 @@ constrained by the number of devices allowed on the hardware bus
 they are trying to emulate (for example 16 on a PCI bus in qemu).
 
 If you have something to contribute such as a patch, a bugfix, a
-new feature, please send it to ``linux-um@lists.infradead.org``
+new feature, please send it to ``linux-um@lists.infradead.org``.
 
 Please follow all standard Linux patch guidelines such as cc-ing
-relevant maintainers and run ``./sripts/checkpatch.pl`` on your patch.
+relevant maintainers and run ``./scripts/checkpatch.pl`` on your patch.
 For more details see ``Documentation/process/submitting-patches.rst``
 
 Note - the list does not accept HTML or attachments, all emails must
@@ -1082,21 +1087,21 @@ be formatted as plain text.
 Developing always goes hand in hand with debugging. First of all,
 you can always run UML under gdb and there will be a whole section
 later on on how to do that. That, however, is not the only way to
-debug a linux kernel. Quite often adding tracing statements and/or
+debug a Linux kernel. Quite often adding tracing statements and/or
 using UML specific approaches such as ptracing the UML kernel process
 are significantly more informative.
 
 Tracing UML
 =============
 
-When running UML consists of a main kernel thread and a number of
+When running, UML consists of a main kernel thread and a number of
 helper threads. The ones of interest for tracing are NOT the ones
 that are already ptraced by UML as a part of its MMU emulation.
 
 These are usually the first three threads visible in a ps display.
 The one with the lowest PID number and using most CPU is usually the
 kernel thread. The other threads are the disk
-(ubd) device helper thread and the sigio helper thread.
+(ubd) device helper thread and the SIGIO helper thread.
 Running ptrace on this thread usually results in the following picture::
 
    host$ strace -p 16566
@@ -1121,21 +1126,21 @@ Running ptrace on this thread usually results in the following picture::
    --- SIGALRM {si_signo=SIGALRM, si_code=SI_TIMER, si_timerid=0, si_overrun=0, si_value={int=1631716592, ptr=0x614204f0}} ---
    rt_sigreturn({mask=[PIPE]})             = -1 EINTR (Interrupted system call)
 
-This is a typical picture from a mostly idle UML instance
+This is a typical picture from a mostly idle UML instance.
 
 * UML interrupt controller uses epoll - this is UML waiting for IO
   interrupts:
 
    epoll_wait(4, [{EPOLLIN, {u32=3721159424, u64=3721159424}}], 64, 0) = 1
 
-* The sequence of ptrace calls is part of MMU emulation and runnin the
-  UML userspace
+* The sequence of ptrace calls is part of MMU emulation and running the
+  UML userspace.
 * ``timer_settime`` is part of the UML high res timer subsystem mapping
-  timer requests from inside UML onto the host high resultion timers.
+  timer requests from inside UML onto the host high resolution timers.
 * ``clock_nanosleep`` is UML going into idle (similar to the way a PC
   will execute an ACPI idle).
 
-As you can see UML will generate quite a bit of output even in idle.The output
+As you can see UML will generate quite a bit of output even in idle. The output
 can be very informative when observing IO. It shows the actual IO calls, their
 arguments and returns values.
 
@@ -1164,14 +1169,14 @@ in order to really leverage UML, one needs to write a piece of
 userspace code which maps driver concepts onto actual userspace host
 calls.
 
-This forms the so called "user" portion of the driver. While it can
+This forms the so-called "user" portion of the driver. While it can
 reuse a lot of kernel concepts, it is generally just another piece of
 userspace code. This portion needs some matching "kernel" code which
 resides inside the UML image and which implements the Linux kernel part.
 
 *Note: There are very few limitations in the way "kernel" and "user" interact*.
 
-UML does not have a strictly defined kernel to host API. It does not
+UML does not have a strictly defined kernel-to-host API. It does not
 try to emulate a specific architecture or bus. UML's "kernel" and
 "user" can share memory, code and interact as needed to implement
 whatever design the software developer has in mind. The only
@@ -1180,7 +1185,7 @@ variables having the same names, the developer should be careful
 which includes and libraries they are trying to refer to.
 
 As a result a lot of userspace code consists of simple wrappers.
-F.e. ``os_close_file()`` is just a wrapper around ``close()``
+E.g. ``os_close_file()`` is just a wrapper around ``close()``
 which ensures that the userspace function close does not clash
 with similarly named function(s) in the kernel part.
 
@@ -1188,7 +1193,7 @@ Security Considerations
 -----------------------
 
 Drivers or any new functionality should default to not
-accepting arbitrary filename, bpf code or other  parameters
+accepting arbitrary filename, bpf code or other parameters
 which can affect the host from inside the UML instance.
 For example, specifying the socket used for IPC communication
 between a driver and the host at the UML command line is OK