README: tell people how to execute the built files

          --- old/./README.xbuild
          +++ new/./README.xbuild

   1    1   _ _ _                                                                
   2    2  (_) | |_   _ _ __ ___   ___  ___    ___  _ __     __ _ _ __ _ __ ___  
   3    3  | | | | | | | '_ ` _ \ / _ \/ __|  / _ \| '_ \   / _` | '__| '_ ` _ \ 
   4    4  | | | | |_| | | | | | | (_) \__ \ | (_) | | | | | (_| | |  | | | | | |
   5    5  |_|_|_|\__,_|_| |_| |_|\___/|___/  \___/|_| |_|  \__,_|_|  |_| |_| |_|
   6    6  
   7    7  
   8    8  Welcome brave fool. Don't Panic! The writer of this README is an even bigger
   9    9  fool than you could be (even if old Ben wonders if those who follow fools are
  10   10  more foolish).
  11   11  
  12   12  So here's where you get started building illumos on ARM.
  13   13  
  14   14  Step 1) You need to get a build environment set up. There's the easy way and the
  15   15  fun way.
  16   16  
  17   17  Easy way:
  18   18  
  19   19  cd $HOME
  20   20  curl -O https://fingolfin.org/illumos/arm/armtc.tar.gz
  21   21  pfexec tar xvzf armtc.tar.gz -C /
  22   22  find /opt/armtc
  23   23  
  24   24  Fun way:
  25   25  
  26   26  Using a normal i386 on i386 build:
  27   27  cd usr/src
  28   28  dmake setup
  29   29  cd cmd/sgs
  30   30  dmake install
  31   31  
  32   32  mkdir -p /opt/armtc/lib/amd64 /opt/armtc/usr/bin/amd64
  33   33  cd /opt/armtc/lib/
  34   34  ln -s amd64 64
  35   35  cd ../usr/bin
  36   36  ln -s amd64 64
  37   37  
  38   38  Then from your proto area, install the following:
  39   39   o /usr/bin/ld
  40   40   o /usr/bin/amd64/ld
  41   41   o /lib/libld.so.4
  42   42   o /lib/amd64/libld.so.4
  43   43   o /lib/liblddbg.so.4
  44   44   o /lib/amd64/liblddb.so.4
  45   45   o /lib/libelf.so.1
  46   46   o /lib/amd64/libelf.so.1
  47   47  
  48   48  Now that's all set go grab illumos-arm-extra (git clone
  49   49  gitosis@zelgadis.fingolfin.org:illumos-arm-extra.git) and build that. You'll
  50   50  need something like:
  51   51  
  52   52  gmake ARCH=arm STRAP=strap LD_ALTEXEC=/opt/armtc/usr/bin/ld install
  53   53  
  54   54  Once that's done, you'll need to fix up the rpath there. so from the root of
  55   55  that workspace run:
  56   56  
  57   57  ./tools/setrpath proto-arm/usr/ /opt/armtc/usr/lib:/opt/gcc/4.4.4/lib:/lib:/usr/lib
  58   58  
  59   59  Finally, you can copy all of that into your arm compiler toolchain directory
  60   60  (use pfexec / sudo as appropriate):
  61   61  
  62   62  cp -r proto-arm/usr /opt/armtc/
  63   63  
  64   64  Step 2) Set up illumos.sh
  65   65  
  66   66  In a fresh workspace, you're going to want to set up your illumos.sh with the
  67   67  following:
  68   68  
  69   69  # Enable GCC 4 default
  70   70  export __GNUC="";
  71   71  export CW_NO_SHADOW=1
  72   72  export MACH=arm;
  73   73  export NATIVE_MACH=i386;
  74   74  export BUILD64="#"
  75   75   
  76   76  # Re-set all this MACH-based crud
  77   77  REF_PROTO_LIST=$PARENT_WS/usr/src/proto_list_${MACH}; export REF_PROTO_LIST
  78   78  ROOT="$CODEMGR_WS/proto/root_${MACH}"; export ROOT
  79   79  PARENT_ROOT=$PARENT_WS/proto/root_$MACH; export PARENT_ROOT
  80   80  PKGARCHIVE="${CODEMGR_WS}/packages/${MACH}/nightly"; export PKGARCHIVE
  81   81  unset GCC_ROOT GNU_ROOT CW_GCC_DIR
  82   82  export i386_GCC_ROOT=/opt/gcc/4.4.4
  83   83  export arm_GCC_ROOT=/opt/armtc/usr
  84   84  export i386_GNU_ROOT=/usr/sfw
  85   85  export arm_GNU_ROOT=/opt/armtc/usr/gnu
  86   86  
  87   87  #
  88   88  # XXX our gcc isn't called ./usr/bin/gcc fix it up via CW env vars for now.
  89   89  #
  90   90  export CW_arm_GCC=/opt/armtc/usr/bin/arm-pc-solaris2.11-gcc-4.6.3
  91   91  
  92   92  #
  93   93  # XXX We need to set CPP to our specific cpp, not the generic /usr/ccs/lib/cpp
  94   94  # as that's rather, well, x86.
  95   95  #
  96   96  export CPP=/opt/armtc/usr/lib/cpp
  97   97  export AW_CPP=/opt/armtc/usr/lib/cpp
  98   98  export LD_ALTEXEC=/opt/armtc/usr/bin/ld
  99   99  
 100  100  Step 3) Start your build engines
 101  101  
 102  102  Once you've done that, you're doing to need to need to use the *new* bldenv to
 103  103  get started building. For the first time you can go ahead and do something like: 
 104  104  
 105  105  cd usr/src
 106  106  ksh93 ./tools/scripts/bldenv.sh ../../illumos.sh
 107  107  
 108  108  This is really just a bit of a bootstrapping weirdness. Once that's done you can
 109  109  go ahead and continue on.
 110  110  
 111  111  As a part of this you should see an important two lines:
 112  112  
 113  113  Cross-building enabled
 114  114  Targeting arm on i386
 115  115  
 116  116  If you don't, stop. illumos.sh is not configured correctly.

 117  117  
 118  118  
 119  119  Once you have that you can get going. Start off with a resounding:
 120  120  
 121  121  dmake setup
 122  122  
 123  123  Following this, you can build the kernel as far as we have it for ARM
 124  124  
 125  125  cd uts; dmake install
 126  126  
 127      -You now have a lovely unix and boot_archive pair in bcm2835/unix (raspberry
 128      -pi) and qvpb/unix (qemu versatilepb).  These should be booted with a kernel
 129      -command line mimicing that of the boot_archive (regardless of the path of the
 130      -unix you actually provide).  For example: kernel /platform/bcm2835/kernel/unix
 131      --Bconsole=text
      127 +You now have a lovely unix and boot_archive pair in bcm2835/unix (Raspberry
      128 +Pi) and qvpb/unix (qemu versatilepb).
 132  129  
      130 +Step 4) Boot
      131 +
      132 +Now that you have the gate built, you can try to boot the kernel.  This is
      133 +where things diverge between qemu and the Raspberry Pi.
      134 +
      135 +Booting qemu is very easy:
      136 +
      137 +qemu-system-arm \
      138 +        -kernel $PROTO/platform/qvpb/kernel/loader \
      139 +        -initrd $PROTO/platform/qvpb/kernel/initrd \
      140 +        -machine versatilepb \
      141 +        -cpu arm1176 \
      142 +        -m 512 \
      143 +        -no-reboot \
      144 +        -nographic \
      145 +        -append 'kernel /platform/qvpb/kernel/unix -Bconsole=uart'
      146 +
      147 +The loader and kernel messages should appear in the same terminal.
      148 +
      149 +Booting on real hardware is a bit more involved.
      150 +
      151 +  a) Create a FAT16 or FAT32 partition on the SD card.  You'll want it to be
      152 +     at least 40 MB.
      153 +
      154 +  b) Create a config.txt on the partition:
      155 +
      156 +        gpu_mem=64
      157 +        kernel=loader
      158 +        initramfs initrd 0x00800000
      159 +
      160 +  c) Create a cmdline.txt on the partition:
      161 +
      162 +        kernel /platform/bcm2835/kernel/unix -Bconsole=uart
      163 +
      164 +  d) Place Raspberry Pi firmware onto the partition.  You can download
      165 +     latest firmware from
      166 +     https://github.com/raspberrypi/firmware/tree/master/boot. The firmware
      167 +     from January 24th, 2015 is known to work.
      168 +
      169 +        0e52c8cdbfd21631746d6fcdc8f2750af39f4287  bootcode.bin
      170 +        aba25d795eaddafd5c8ece3de18873b9928eb6f7  fixup_cd.dat
      171 +        38e55d60f896738eec30d0ca4f62b68e48e99184  fixup.dat
      172 +        4867e6eab84bb4138e812993112b6a05b7930b89  fixup_x.dat
      173 +        fa993851acba366d9e37d59a1d9e9de84b19173f  start_cd.elf
      174 +        356060e0f44742d8835294a211b812efcac29f66  start.elf
      175 +        b7f01f90d995a36c9d765fd1f4d95a5fcdfd7e41  start_x.elf
      176 +
      177 +  e) Copy $PROTO/platform/bcm2835/kernel/{loader,initrd} onto the partition.
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX