docs: UML: user_mode_linux_howto_v2 edits
Fix various typos, command syntax, punctuation, capitalization,
and whitespace.
Fixes: 04301bf5b0
("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>
This commit is contained in:
parent
a9d85efb25
commit
e825b29ab8
|
@ -128,7 +128,7 @@ Create a minimal OS installation on the mounted filesystem::
|
||||||
debootstrap does not set up the root password, fstab, hostname or
|
debootstrap does not set up the root password, fstab, hostname or
|
||||||
anything related to networking. It is up to the user to do that.
|
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::
|
mounted image::
|
||||||
|
|
||||||
# chroot /mnt
|
# 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
|
/dev/ubd0 ext4 discard,errors=remount-ro 0 1
|
||||||
|
|
||||||
The image hostname will be set to the same as the host on which you
|
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".
|
"Oh, bummer, I rebooted the wrong machine".
|
||||||
|
|
||||||
UML supports two classes of network devices - the older uml_net ones
|
UML supports two classes of network devices - the older uml_net ones
|
||||||
|
@ -162,7 +162,7 @@ need entries like::
|
||||||
|
|
||||||
# vector UML network devices
|
# vector UML network devices
|
||||||
auto vec0
|
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
|
We now have a UML image which is nearly ready to run, all we need is a
|
||||||
UML kernel and modules for it.
|
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
|
If you have compiled your own kernel, you need to use the usual "install
|
||||||
modules to a location" procedure by running::
|
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.
|
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
|
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
|
between machines using a back-to-back cable) or a connection to a
|
||||||
switch. UML supports a wide variety of means to build these
|
switch. UML supports a wide variety of means to build these
|
||||||
connections to all of: local machine, remote machine(s), local and
|
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
|
* All transports which have multi-packet rx and/or tx can deliver pps
|
||||||
rates of up to 1Mps or more.
|
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
|
* GRE and L2TPv3 allow connections to all of: local machine, remote
|
||||||
machines, remote network devices and remote UML instances.
|
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
|
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
|
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
|
Thenceforth, UML can be run with normal user privilges, along with
|
||||||
full networking.
|
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.
|
* ``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
|
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
|
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
|
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
|
* ``headroom=int`` - adjusts the default headroom (32 bytes) reserved
|
||||||
if a packet will need to be re-encapsulated into for instance VXLAN.
|
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
|
time mode
|
||||||
|
|
||||||
Shared Options
|
Shared Options
|
||||||
|
@ -331,7 +336,7 @@ Example::
|
||||||
This will connect vec0 to tap0 on the host. Tap0 must already exist (for example
|
This will connect vec0 to tap0 on the host. Tap0 must already exist (for example
|
||||||
created using tunctl) and UP.
|
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
|
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.
|
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
|
This is an experimental/demo transport which couples tap for transmit
|
||||||
and a raw socket for receive. The raw socket allows multi-packet
|
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
|
Privileges required: hybrid requires ``CAP_NET_RAW`` capability by
|
||||||
the UML user as well as the requirements for the tap transport.
|
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
|
endpoint at host dst_host. ``GRE`` supports the following additional
|
||||||
options:
|
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
|
``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
|
``rx_key`` must be set too
|
||||||
|
|
||||||
* ``sequence=[0,1]`` - enable GRE sequence
|
* ``sequence=[0,1]`` - enable GRE sequence
|
||||||
|
@ -444,12 +449,12 @@ options:
|
||||||
|
|
||||||
GRE has a number of caveats:
|
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
|
multiplex connections as each GRE tunnel is terminated directly on
|
||||||
the UML instance.
|
the UML instance.
|
||||||
|
|
||||||
* The key is not really a security feature. While it was intended as such
|
* 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.
|
ensure that the tunnel is not misconfigured.
|
||||||
|
|
||||||
An example configuration for a Linux host with a local address of
|
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:
|
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
|
As the tunnel is fixed these are not negotiated and they are
|
||||||
preconfigured on both ends.
|
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
|
functionality as GRE key, more to prevent misconfiguration than provide
|
||||||
actual security
|
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
|
* ``counter=[0,1]`` - enable l2tpv3 counter
|
||||||
|
|
||||||
|
@ -518,12 +523,12 @@ Additionally, L2TPv3 supports the following optional parameters
|
||||||
|
|
||||||
L2TPv3 has a number of caveats:
|
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
|
no way to multiplex connections as each L2TPv3 tunnel is terminated
|
||||||
directly on the UML instance. UDP mode can use different ports for
|
directly on the UML instance. UDP mode can use different ports for
|
||||||
this purpose.
|
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:
|
via L2TPv3:
|
||||||
|
|
||||||
**/etc/network/interfaces**::
|
**/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
|
These add an executable called linux to the system. This is the UML
|
||||||
kernel. It can be run just like any other executable.
|
kernel. It can be run just like any other executable.
|
||||||
It will take most normal linux kernel arguments as command line
|
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.
|
in order to do something useful.
|
||||||
|
|
||||||
Arguments
|
Arguments
|
||||||
|
@ -595,7 +600,7 @@ Arguments
|
||||||
Mandatory 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.
|
also accept K, M or G qualifiers.
|
||||||
|
|
||||||
* ``ubdX[s,d,c,t]=`` virtual disk specification. This is not really
|
* ``ubdX[s,d,c,t]=`` virtual disk specification. This is not really
|
||||||
|
@ -603,7 +608,7 @@ Mandatory Arguments:
|
||||||
specify a root file system.
|
specify a root file system.
|
||||||
The simplest possible image specification is the name of the image
|
The simplest possible image specification is the name of the image
|
||||||
file for the filesystem (created using one of the methods described
|
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
|
* UBD devices support copy on write (COW). The changes are kept in
|
||||||
a separate file which can be discarded allowing a rollback to the
|
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
|
* UBD devices can be set to use synchronous IO. Any writes are
|
||||||
immediately flushed to disk. This is done by adding ``s`` after
|
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
|
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
|
* UBD supports TRIM - asking the Host OS to reclaim any unused
|
||||||
blocks in the image. To turn it off, specify the ``t`` flag after
|
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
|
* ``root=`` root device - most likely ``/dev/ubd0`` (this is a Linux
|
||||||
filesystem image)
|
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
|
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
|
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,
|
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
|
however, the wrong approach if UML is to be used as a testing harness or run
|
||||||
in a text-only environment.
|
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
|
* The null channel - Discard all input or output. Example ``con=null`` will set
|
||||||
all consoles to null by default.
|
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.``
|
``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.
|
* 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).
|
will make UML use the host 8th console (usually unused).
|
||||||
|
|
||||||
* The xterm channel - this is the default - bring up an xterm on this channel
|
* 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
|
have the UML distribution package installed. This usually contains the
|
||||||
port-helper and other utilities needed for UML to communicate with the xterm.
|
port-helper and other utilities needed for UML to communicate with the xterm.
|
||||||
Alternatively, these need to be complied and installed from source. All
|
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 \
|
vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
|
||||||
root=/dev/ubda con=null con0=null,fd:2 con1=fd:0,fd: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.
|
called ``Filesystem.img`` as root. It will connect to the host using tap0.
|
||||||
All consoles except ``con1`` will be disabled and console 1 will
|
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.
|
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,
|
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
|
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
|
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
|
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
|
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::
|
``umid=debian``, you'll see this::
|
||||||
|
|
||||||
mconsole initialized on /home/jdike/.uml/debian/mconsole
|
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
|
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
|
its disks. There is a major caveat in doing this on multisocket NUMA
|
||||||
machines. On such hardware, running many UML instances with a shared
|
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.
|
inter-socket traffic.
|
||||||
|
|
||||||
If you are running UML on high end hardware like this, make sure to
|
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
|
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.
|
``taskset`` command or have a look at the "tuning" section.
|
||||||
|
|
||||||
To add a copy-on-write layer to an existing block device file, simply
|
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
|
# 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
|
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.
|
idle, these threads will be migrated to other processors on a SMP host.
|
||||||
This, unfortunately, will usually result in LOWER performance because of
|
This, unfortunately, will usually result in LOWER performance because of
|
||||||
all of the cache/memory synchronization traffic between cores. As a
|
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
|
especially on a large system. This can result in performance differences
|
||||||
of 5 times or higher on some benchmarks.
|
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
|
opportunities to create and test them without being constrained to
|
||||||
emulating specific hardware.
|
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?
|
devices?
|
||||||
|
|
||||||
Not an issue with UML. At the same time, this is something which
|
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).
|
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
|
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
|
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``
|
For more details see ``Documentation/process/submitting-patches.rst``
|
||||||
|
|
||||||
Note - the list does not accept HTML or attachments, all emails must
|
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,
|
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
|
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
|
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
|
using UML specific approaches such as ptracing the UML kernel process
|
||||||
are significantly more informative.
|
are significantly more informative.
|
||||||
|
|
||||||
Tracing UML
|
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
|
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.
|
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.
|
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
|
The one with the lowest PID number and using most CPU is usually the
|
||||||
kernel thread. The other threads are the disk
|
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::
|
Running ptrace on this thread usually results in the following picture::
|
||||||
|
|
||||||
host$ strace -p 16566
|
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}} ---
|
--- 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)
|
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
|
* UML interrupt controller uses epoll - this is UML waiting for IO
|
||||||
interrupts:
|
interrupts:
|
||||||
|
|
||||||
epoll_wait(4, [{EPOLLIN, {u32=3721159424, u64=3721159424}}], 64, 0) = 1
|
epoll_wait(4, [{EPOLLIN, {u32=3721159424, u64=3721159424}}], 64, 0) = 1
|
||||||
|
|
||||||
* The sequence of ptrace calls is part of MMU emulation and runnin the
|
* The sequence of ptrace calls is part of MMU emulation and running the
|
||||||
UML userspace
|
UML userspace.
|
||||||
* ``timer_settime`` is part of the UML high res timer subsystem mapping
|
* ``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
|
* ``clock_nanosleep`` is UML going into idle (similar to the way a PC
|
||||||
will execute an ACPI idle).
|
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
|
can be very informative when observing IO. It shows the actual IO calls, their
|
||||||
arguments and returns values.
|
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
|
userspace code which maps driver concepts onto actual userspace host
|
||||||
calls.
|
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
|
reuse a lot of kernel concepts, it is generally just another piece of
|
||||||
userspace code. This portion needs some matching "kernel" code which
|
userspace code. This portion needs some matching "kernel" code which
|
||||||
resides inside the UML image and which implements the Linux kernel part.
|
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*.
|
*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
|
try to emulate a specific architecture or bus. UML's "kernel" and
|
||||||
"user" can share memory, code and interact as needed to implement
|
"user" can share memory, code and interact as needed to implement
|
||||||
whatever design the software developer has in mind. The only
|
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.
|
which includes and libraries they are trying to refer to.
|
||||||
|
|
||||||
As a result a lot of userspace code consists of simple wrappers.
|
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
|
which ensures that the userspace function close does not clash
|
||||||
with similarly named function(s) in the kernel part.
|
with similarly named function(s) in the kernel part.
|
||||||
|
|
||||||
|
@ -1188,7 +1193,7 @@ Security Considerations
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
Drivers or any new functionality should default to not
|
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.
|
which can affect the host from inside the UML instance.
|
||||||
For example, specifying the socket used for IPC communication
|
For example, specifying the socket used for IPC communication
|
||||||
between a driver and the host at the UML command line is OK
|
between a driver and the host at the UML command line is OK
|
||||||
|
|
Loading…
Reference in New Issue