__
 (___()'`;  Rusty's Remarkably Unreliable Guide to Lguest
 /,    /`      - or, A Young Coder's Illustrated Hypervisor
 \\"--\\    http://lguest.ozlabs.org

Lguest is designed to be a minimal 32-bit x86 hypervisor for the Linux kernel,
for Linux developers and users to experiment with virtualization with the
minimum of complexity.  Nonetheless, it should have sufficient features to
make it useful for specific tasks, and, of course, you are encouraged to fork
and enhance it (see drivers/lguest/README).

Features:

- Kernel module which runs in a normal kernel.
- Simple I/O model for communication.
- Simple program to create new guests.
- Logo contains cute puppies: http://lguest.ozlabs.org

Developer features:

- Fun to hack on.
- No ABI: being tied to a specific kernel anyway, you can change anything.
- Many opportunities for improvement or feature implementation.

Running Lguest:

- The easiest way to run lguest is to use same kernel as guest and host.
  You can configure them differently, but usually it's easiest not to.

  You will need to configure your kernel with the following options:

  "Processor type and features":
     "Paravirtualized guest support" = Y
        "Lguest guest support" = Y
     "High Memory Support" = off/4GB
     "Alignment value to which kernel should be aligned" = 0x100000
        (CONFIG_PARAVIRT=y, CONFIG_LGUEST_GUEST=y, CONFIG_HIGHMEM64G=n and
         CONFIG_PHYSICAL_ALIGN=0x100000)

  "Device Drivers":
     "Block devices"
        "Virtio block driver" = M/Y
     "Network device support"
        "Universal TUN/TAP device driver support" = M/Y
        "Virtio network driver" = M/Y
           (CONFIG_VIRTIO_BLK=m, CONFIG_VIRTIO_NET=m and CONFIG_TUN=m)

  "Virtualization"
     "Linux hypervisor example code" = M/Y
        (CONFIG_LGUEST=m)

- A tool called "lguest" is available in this directory: type "make"
  to build it.  If you didn't build your kernel in-tree, use "make
  O=<builddir>".

- Create or find a root disk image.  There are several useful ones
  around, such as the xm-test tiny root image at
	  http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img

  For more serious work, I usually use a distribution ISO image and
  install it under qemu, then make multiple copies:

	  dd if=/dev/zero of=rootfile bs=1M count=2048
	  qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d

  Make sure that you install a getty on /dev/hvc0 if you want to log in on the
  console!

- "modprobe lg" if you built it as a module.

- Run an lguest as root:

      tools/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 \
        --block=rootfile root=/dev/vda

   Explanation:
    64: the amount of memory to use, in MB.

    vmlinux: the kernel image found in the top of your build directory.  You
       can also use a standard bzImage.

    --tunnet=192.168.19.1: configures a "tap" device for networking with this
       IP address.

    --block=rootfile: a file or block device which becomes /dev/vda
       inside the guest.

    root=/dev/vda: this (and anything else on the command line) are
       kernel boot parameters.

- Configuring networking.  I usually have the host masquerade, using
  "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 >
  /proc/sys/net/ipv4/ip_forward".  In this example, I would configure
  eth0 inside the guest at 192.168.19.2.

  Another method is to bridge the tap device to an external interface
  using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest
  to obtain an IP address.  The bridge needs to be configured first:
  this option simply adds the tap interface to it.

  A simple example on my system:

    ifconfig eth0 0.0.0.0
    brctl addbr lg0
    ifconfig lg0 up
    brctl addif lg0 eth0
    dhclient lg0

  Then use --tunnet=bridge:lg0 when launching the guest.

  See:
  
    http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge
    
  for general information on how to get bridging to work.

- Random number generation. Using the --rng option will provide a
  /dev/hwrng in the guest that will read from the host's /dev/random.
  Use this option in conjunction with rng-tools (see ../hw_random.txt)
  to provide entropy to the guest kernel's /dev/random.

There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest

Good luck!
Rusty Russell rusty@rustcorp.com.au.
><td class='ctrl'><noscript><input type='submit' value='reload'/></noscript></td></tr></table></form></div><table summary='commit info' class='commit-info'>
<tr><th>author</th><td>Douglas Miller &lt;dougmill@linux.vnet.ibm.com&gt;</td><td class='right'>2017-01-28 06:42:20 -0600</td></tr>
<tr><th>committer</th><td>Tejun Heo &lt;tj@kernel.org&gt;</td><td class='right'>2017-01-28 07:49:42 -0500</td></tr>
<tr><th>commit</th><td colspan='2' class='oid'><a href='/cgit.cgi/linux/net-next.git/commit/net/core/fib_rules.c?id=966d2b04e070bc040319aaebfec09e0144dc3341'>966d2b04e070bc040319aaebfec09e0144dc3341</a> (<a href='/cgit.cgi/linux/net-next.git/patch/net/core/fib_rules.c?id=966d2b04e070bc040319aaebfec09e0144dc3341'>patch</a>)</td></tr>
<tr><th>tree</th><td colspan='2' class='oid'><a href='/cgit.cgi/linux/net-next.git/tree/?id=966d2b04e070bc040319aaebfec09e0144dc3341'>4b96156e3d1dd4dfd6039b7c219c9dc4616da52d</a> /<a href='/cgit.cgi/linux/net-next.git/tree/net/core/fib_rules.c?id=966d2b04e070bc040319aaebfec09e0144dc3341'>net/core/fib_rules.c</a></td></tr>
<tr><th>parent</th><td colspan='2' class='oid'><a href='/cgit.cgi/linux/net-next.git/commit/net/core/fib_rules.c?id=1b1bc42c1692e9b62756323c675a44cb1a1f9dbd'>1b1bc42c1692e9b62756323c675a44cb1a1f9dbd</a> (<a href='/cgit.cgi/linux/net-next.git/diff/net/core/fib_rules.c?id=966d2b04e070bc040319aaebfec09e0144dc3341&amp;id2=1b1bc42c1692e9b62756323c675a44cb1a1f9dbd'>diff</a>)</td></tr></table>
<div class='commit-subject'>percpu-refcount: fix reference leak during percpu-atomic transition</div><div class='commit-msg'>percpu_ref_tryget() and percpu_ref_tryget_live() should return
"true" IFF they acquire a reference. But the return value from
atomic_long_inc_not_zero() is a long and may have high bits set,
e.g. PERCPU_COUNT_BIAS, and the return value of the tryget routines
is bool so the reference may actually be acquired but the routines
return "false" which results in a reference leak since the caller
assumes it does not need to do a corresponding percpu_ref_put().

This was seen when performing CPU hotplug during I/O, as hangs in
blk_mq_freeze_queue_wait where percpu_ref_kill (blk_mq_freeze_queue_start)
raced with percpu_ref_tryget (blk_mq_timeout_work).
Sample stack trace:

__switch_to+0x2c0/0x450
__schedule+0x2f8/0x970
schedule+0x48/0xc0
blk_mq_freeze_queue_wait+0x94/0x120
blk_mq_queue_reinit_work+0xb8/0x180
blk_mq_queue_reinit_prepare+0x84/0xa0
cpuhp_invoke_callback+0x17c/0x600
cpuhp_up_callbacks+0x58/0x150
_cpu_up+0xf0/0x1c0
do_cpu_up+0x120/0x150
cpu_subsys_online+0x64/0xe0
device_online+0xb4/0x120
online_store+0xb4/0xc0
dev_attr_store+0x68/0xa0
sysfs_kf_write+0x80/0xb0
kernfs_fop_write+0x17c/0x250
__vfs_write+0x6c/0x1e0
vfs_write+0xd0/0x270
SyS_write+0x6c/0x110
system_call+0x38/0xe0

Examination of the queue showed a single reference (no PERCPU_COUNT_BIAS,
and __PERCPU_REF_DEAD, __PERCPU_REF_ATOMIC set) and no requests.
However, conditions at the time of the race are count of PERCPU_COUNT_BIAS + 0
and __PERCPU_REF_DEAD and __PERCPU_REF_ATOMIC set.

The fix is to make the tryget routines use an actual boolean internally instead
of the atomic long result truncated to a int.

Fixes: e625305b3907 percpu-refcount: make percpu_ref based on longs instead of ints
Link: https://bugzilla.kernel.org/show_bug.cgi?id=190751
Signed-off-by: Douglas Miller &lt;dougmill@linux.vnet.ibm.com&gt;
Reviewed-by: Jens Axboe &lt;axboe@fb.com&gt;
Signed-off-by: Tejun Heo &lt;tj@kernel.org&gt;
Fixes: e625305b3907 ("percpu-refcount: make percpu_ref based on longs instead of ints")
Cc: stable@vger.kernel.org # v3.18+
</div><div class='diffstat-header'><a href='/cgit.cgi/linux/net-next.git/diff/?id=966d2b04e070bc040319aaebfec09e0144dc3341'>Diffstat</a> (limited to 'net/core/fib_rules.c')</div><table summary='diffstat' class='diffstat'>