FreeBSD host notes
==================

- Needs to set net.link.tap.user_open sysctl in order to use /dev/tap*
  networking as non-root.  Don't forget to adjust device node permissions in
  /etc/devfs.rules.

- slirp (usermode networking) is fixed now in cvs, on FreeSBIE 1.0 guests you
  still have to manually do: echo nameserver 10.0.2.3 >/etc/resolv.conf but
  i've been told that that's normal.  (fixed on FreeSBIE 1.1.) And you have
  to wait a bit for dhclient to do its thing; traffic to address 10.0.2.2 is
  routed to 127.1 on the host.

- Expect timer problems when guest kernel HZ is > hosts, for example time
  sleep 1 takes 49 seconds and booting sleeps for minutes at the acd0 probe
  with a FreeSBIE 1.0 guest, thats because its kernel is built with HZ=5000,
  and FreeBSD's default is 100...  (no longer a problem with FreeSBIE 1.1.)
  The linux 2.6 kernel uses 1000 by default btw.  (changed to 250 later, and
  recent linux kernels now no longer have a fixed HZ, aka `tickless
  kernel'...)  Enabling /dev/rtc doesn't seem to help either (not included
  since it needs a patch to emulators/rtc.)

- Update: the above problem has gotten worse with FreeBSD guests
  somewhere before 8.0, mainly since the kernel now usually wants
  double or even quadruple number of timer irqs compared to HZ if
  it detects an apic (and at least early versions of FreeBSD 8 had
  a bug that essentially halved qemu's clock rate too); the only
  reason you usually don't see symptoms of this with FreeBSD 8
  guests is they automatically reduce their HZ to 100 when running
  in a VM while the default for the host kernel is still HZ=1000.
  Workaround: you can disable the apic clock in the guest by setting

	hint.apic.0.clock="0"

  in loader.conf(5) (or manually at the loader prompt), if that
  doesn't work the only things you can do is either reduce the
  guest's HZ to, say, 100 by setting e.g.

	kern.hz="100"

  from the loader as above (which usually is a good idea in a VM
  anyway and FreeBSD 8 now does by itself as mentioned), or otherwise
  increase the host's HZ to 2000 or even 4000 from the loader in
  the same way.

- The -smb option (smb-export local dir to guest using the default
  slirp networking) needs the net/samba36 port/package installed
  in addition to qemu. (SAMBA knob.)

- If you want to use usb devices connected to the host in the guest
  (usb_add host:... monitor command; this doesn't work on FreeBSD 8 and
  -current atm because of the new usb stack - help updating the usb-bsd.c code
  is more than welcome here!) you need to make sure the host isn't claiming
  them, e.g. for umass devices (like memory sticks or external harddrives)
  make sure umass isn't in the kernel (you can then still load it as a kld
  when needed), also unless you are running qemu as root you then need to fix
  permissions for /dev/ugen* device nodes: if you are on 5.x or later (devfs)
  put a rule in /etc/devfs.rules, activate it in /etc/rc.conf and run
  /etc/rc.d/devfs restart.  Example devfs.rules:

	[ugen_ruleset=20]
	add path 'ugen*' mode 660 group operator

  corresponding rc.conf line:

	devfs_system_ruleset="ugen_ruleset"

- Still usb: since the hub is no longer attached to the uchi controller and
  the wakeup mechanism, resume interrupt is not implemented yet linux guests
  will suspend the bus, i.e. they wont see devices usb_add'ed after its
  (linux') uhci module got loaded.  Workaround: either add devices before
  linux loads the module or rmmod and modprobe it afterwards.

- To avoid panics or non-working re(4) nics with FreeBSD guests if you use
  qemu -net nic,model=rtl8139 -net user or tap ... enable the emulated rtl8139
  timer by building the port with RTL8139_TIMER enabled.   (The rtl8139c+ that
  model=rtl8139 emulates needs less cpu than qemu's default ne2k nic which is
  driven by ed(4), it has not been made default only because it may not work
  with all guests yet.  Btw qemu now also can emulate a few intel eepro100 and
  e1000 nics which seem to be a tad more efficient even, and at least i82557b
  and e1000 work without tweaks for FreeBSD guests - driven by fxp(4) and
  em(4) repectively - and Linux guests too.)

- If you get repeated `atapi_poll called!' console messages with FreeBSD
  guests or other weird cdrom problems then thats probably because the guest
  has atapicam loaded, which for reasons still to be determined has problems
  with qemu's now by default enabled cdrom dma.  You can build the port with
  CDROM_DMA disabled to disable it.  [Looks like this is fixed in recent
  FreeBSD guest versions.]

- If you build qemu wihout SDL and then get crashes running it try passing it
  -nographic.  This should probably be default in that case...

- If you use kqemu make sure your kqemu.ko is always in sync with your kernel
  (like with any kld installed outside of base), i.e. rebuild its port
  whenever you update the kernel - especially if you are switching branches or
  are following a -stable or even -current branch!

- You can enable autoloading of kqemu at boot by adding a line

	kqemu_enable=YES

  to /etc/rc.conf

- qemu's network boot roms (-boot n) have a bug when bootfiles sizes are a
  multiple of blksize, if this affects you (like with FreeBSD's /boot/pxeboot)
  you can do like

	cp /boot/pxeboot pxeboot-qemu && chmod +w pxeboot-qemu && echo >>pxeboot-qemu

  and then use pxeboot-qemu.  Actually you need recent btx code
  (from after 7.0 was released) because of the real mode boot
  problem, so use at least pxeboot from there.  And I just did that
  for the pxeboot extracted out of

	ftp://ftp.freebsd.org/pub/FreeBSD/snapshots/200805/7.0-STABLE-200805-i386-bootonly.iso

  and placed it here:

	http://people.freebsd.org/~nox/qemu/pxeboot-qemu

- If you use slirp (usernet, the default) and want to mount nfs into the guest
  and you are not running qemu as root, then mountd(8) on the exporting box
  needs to be run with -n in order to accept requests from ports >= 1024.

- Unfortunately there can still be guests that don't run correctly with kqemu
  and -kernel-kqemu especially on amd64 - not much you can do about that other
  than help debugging (k)qemu... (well or falling back to unaccellerated
  qemu/using only -enable-kqemu if its that what's causing the problems.  note
  however that kqemu now can also be used with the 32 bit qemu even on amd64
  hosts as of the 20080620 update.)

- kqemu passes the host tsc to the guest as-is so depending on your cpu and
  guest you _may_ need to tell the guest to avoid relying on the tsc (notsc
  kernel parameter with linux), or if that doesn't work force qemu onto a
  single cpu by doing e.g. `cpuset -l 0 qemu ..' (see the cpuset(1) manpage
  for details; cpuset isn't avalable before 7.1.  This can only be a problem
  on smp hosts.)

- (not FreeBSD-specific:) There have been reports of qcow2 corruption with (at
  least) win2k guests on recent kvm (which uses similar qcow2 code than qemu
  now, see this thread:

	http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg00713.html -

  the consensus on that thread seems to be that qcow(2) code has always been
  experimental and you should use raw images if you want reliability; raw is
  also usually faster.)  You should be able to migrate existing images to raw
  using qemu-img(1)'s convert function; raw doesn't support advanced features
  like snapshots tho.  [a few important qcow2 bugfixed have been committed in
  the meantime so this _might_ be less of an issue now.]

- (also not FreeBSD-specific:)  It is recommended to pass raw images using the
  new -drive syntax, specifying format=raw explicitly in order to avoid
  malicious guests being able to exploit the format autodetection thats
  otherwise getting used.  (Not that you should run malicious guests anyway,
  but this eleminates at least a known attack vector.)

- qemu now has improved physical cdrom support, but still there still is at
  least one known problem: you need to have the guest eject the disc if you
  want to change it/take it out, or otherwise the guest may continue using
  state (like size) of the old disc.  (You can also do like `change ide1-cd0
  /dev/acd0' in the monitor after taking out the disc if a guest cannot eject
  it itself.)

- The default configuration location (qemu-ifup script etc.) has been changed
  from /etc to PREFIX/etc (usually /usr/local/etc).  Move your files
  accordingly.

- The pcap code (-net nic... -net pcap,ifname=...) should work properly now,
  with only one exception:  Advanced features like TSO used on the host
  interface can cause oversize packets which now do get truncated to avoid
  confusing/panicing guests but of course still will cause retransmissions.
  So if you see slow throughput and `pcap_send: packet size > ..., truncating'
  messages on qemu's tty try disabling TSO etc on the host interface at least
  while using pcap.

- kqemu still works in the 0.11 branch, but is disabled by default now so
  you'll have to pass -enable-kqemu (or -kernel-kqemu as with the previous
  versions) if you want to use it.