linux_emul_base/README

   1 INTRO
   2
   3 Linuxemu is a program that can execute Linux/i386 ELF binaries on
   4 Plan9.  It was started by Russ Cox and development was continued by
   5 me.  Its opensource, I dont care what you are doing with it, but maybe
   6 Russ does, i don't know :-)
   7
   8 If you found some bugs or have some other improvements/ideas send a
   9 email to:
  10
  11 cinap_lenrek AT gmx DOT de
  12
  13
  14 SOURCE
  15
  16 linuxemu is available on sources. On Plan9 do:
  17
  18 % 9fs sources
  19 % cp /n/sources/contrib/cinap_lenrek/linuxemu3.tgz .
  20
  21 Another source is my server on the web:
  22
  23 % hget http://9hal.ath.cx/usr/cinap_lenrek/linuxemu3.tgz >linuxemu3.tgz
  24
  25
  26 DOCUMENTATION
  27
  28 documentation is provided in the doc directory:
  29
  30 doc/linuxemu.txt
  31 doc/todo.txt
  32
  33
  34 COMPILE
  35
  36 % tar xzf linuxemu3.tgz
  37 % cd linuxemu3
  38 % mk
  39
  40
  41 INSTALL
  42
  43 % mk install
  44
  45
  46 BOOTSTRAP
  47
  48 You need a linux rootfilesystem packed in a tarball. Go!
  49 get some linux rootfs:
  50
  51 http://9hal.ath.cx/usr/cinap_lenrek/mroot.tbz
  52 http://9hal.ath.cx/usr/cinap_lenrek/mroot-linuxemu.tbz
  53
  54 the -linuxemu version contains no symlinks and can be extracted with
  55 plain plan9 tools bunzip/tar so you can skip the BOOTSTRAP section.
  56 :-)
  57
  58 You can create your own with debootstrap on debian linux...  or help
  59 me write a installer that unpacks and installs slackware on plan9...
  60 In any case, linuxemu is not hardwared to any linux distribution!
  61
  62 Extract your linux rootfilesystem with the static linked gnutar from
  63 the bootstrap directory.  (This will create all the fake symlinks for
  64 you)
  65
  66 % 8.out bootstrap/tar xf /tmp/mroot.tar
  67
  68
  69 RUNNING
  70
  71 Then you can use the linux script to "chroot" into your linux
  72 rootfs. the linux script is neccesary because for linux programs
  73 to run shared libraries from your linux root have to appear at /lib
  74 and /usr/lib and configuration files are expected to be in /etc.
  75 the script will build a private namespace and bind the linuxroot
  76 over the plan9 root. the original plan9 namespace is mounted to /9.
  77
  78 % linux -r ./mroot /bin/bash -i
  79
  80 if you omit the -r option, the linuxroot defaults to /sys/lib/linux. you
  81 may put your linux root there or add a bind to your $home/lib/profile.
  82
  83 You should change /etc/resolv.conf to match your network nameserver
  84 setup.  Also, you may want to edit /etc/apt/sources.list to change the
  85 debian mirror.
  86
  87
  88 DEBUGGING
  89
  90 If linuxemu crashes, use acid to figure out whats going on:
  91
  92 % mk acid
  93 % acid -l linuxemu.acid <pid>
  94
  95 then you can issue the following commands:
  96
  97 ustk()                          dump a (userspace) stacktrace for the current thread
  98 umem(Current())         dump the memory mappings
  99 ufds(Current())                 dump the filedescriptor table
 100 utrace(Current())               dump the internal tracebuffer (enabled by -d option)
 101
 102 use xasm()/xcasm() for disassembly for linux code.
 103
 104 You can also enable full trace logging:
 105
 106 % linux -r ./mroot -dd /bin/bash -i >[2]/tmp/linuxemu.log
 107
 108 This slows linuxemu down.  In case of race conditions, it often
 109 happens that the bug disapears when doing full trace logging!
 110
 111
 112 NPTL/thread-local storage
 113
 114 If you get one of these errors:
 115
 116 "cannot set up thread-local storage: cannot set up LDT for thread-local storage"
 117
 118 this is glibc/libpthread complaining!  the problem is the following:
 119 glibc on i386 decided at some point to use the extra segment registers
 120 GS and FS as an indirection pointer for thread local storage.  the
 121 operating system kernel therfor must have a mechanism to let userspace
 122 change descriptor table entries and swap them in/out on context
 123 switch.
 124
 125 to make it work here are several options:
 126
 127 1) recompile and link the program with a pre NPTL version of glibc.
 128
 129 2) on some distributions, a non-tls version of libc/libpthread is available.
 130 in my debian mroot, the NPTL version is in /lib/tls, the older version
 131 is in /lib. by renaming /lib/tls to /lib/_tls_disabled_ the loader will
 132 use the non-tls version.
 133
 134 3) i made a kernel patch that adds support for per process descriptors to
 135 plan9:
 136 /n/sources/contrib/cinap_lenrek/segdescpatch
 137 http://9hal.ath.cx/usr/cinap_lenrek/segdescpatch.tgz
 138 it will add the files gdt and ldt to devarch (#P).