sys/man/1/5e

   1 .TH 5E 1
   2 .SH NAME
   3 5e \- user-mode ARM emulation
   4 .SH SYNOPSIS
   5 .B 5e
   6 [
   7 .B -npb
   8 ]
   9 .I text
  10 [
  11 .I arguments
  12 ]
  13 .SH DESCRIPTION
  14 .I 5e
  15 simulates the execution of an ARM binary in a Plan 9 environment.
  16 Unlike its predecessor
  17 .IR vi (1)
  18 it supports, among others, the syscalls
  19 .IR rfork (2)
  20 and
  21 .IR exec (2),
  22 which allows for the execution of threaded programs (e.g.,
  23 .IR rio (1)
  24 or
  25 .IR catclock (1)).
  26 .PP
  27 .I 5e
  28 executes the specified binary
  29 .IR text ,
  30 which is prepended by
  31 .B /bin
  32 if it does not begin with a slash, dot or hash sign.
  33 Unless
  34 .B -n
  35 is specified,
  36 .B /bin
  37 is replaced by the union of
  38 .B /arm/bin
  39 and
  40 .BR /rc/bin .
  41 .PP
  42 Unlike
  43 .IR vi (1),
  44 .IR 5e (1)
  45 does not provide built-in debugging facilities.
  46 It
  47 .I does
  48 provide emulation of the
  49 .B /proc
  50 directory, if the
  51 .B -p
  52 flag is specified, to attach a proper debugger like
  53 .IR acid (1).
  54 There is no equivalent of the profiling facilities, no caches or TLBs are simulated, either.
  55 .PP
  56 .IR 5e (1)
  57 currently has three options.
  58 .TP
  59 .B -n
  60 By default,
  61 .IR 5e (1)
  62 replaces
  63 .B /bin
  64 as mentioned above and also sets the variables
  65 .B cputype
  66 and
  67 .B objtype
  68 to
  69 .BR arm.
  70 Supplying the
  71 .B -n
  72 option suppresses this behaviour.
  73 .TP
  74 .B -p
  75 The
  76 .B -p
  77 option activates emulation of a
  78 .B /proc
  79 file system, which is mounted at
  80 .B /proc
  81 and also posted as
  82 .BR /srv/armproc ,
  83 cf.
  84 .IR srv (3).
  85 .TP
  86 .B -b
  87 Supplying
  88 .B -b
  89 causes failing processes to call
  90 .IR abort (2)
  91 instead of
  92 .I sysfatal.
  93 See below.
  94 .SH SOURCE
  95 .B /sys/src/cmd/5e
  96 .SH SEE ALSO
  97 .IR vi (1)
  98 .SH BUGS
  99 The host is required to be little endian and is assumed to have a floating point implementation conforming to IEEE 754.
 100
 101 Broken processes are simulated in a rather unsatisfactory manner.
 102 The
 103 .B -b
 104 option leaks memory.
 105 The emulator does not post
 106 .B sys:
 107 notes.
 108
 109 Obscure opcodes, in particular uncommon operations on R15, are not implemented.
 110 Careless use of the
 111 .B LDREX
 112 and
 113 .B STREX
 114 instructions can lead to deadlock, while the
 115 .I ARM Architecture Reference Manual
 116 indicates a real processor will exhibit undefined behavior in these cases.
 117
 118 Accesses spanning segment boundaries will be treated as page faults.
 119 Many syscalls such as
 120 .IR pread (2)
 121 will shuffle data around (in most cases unnecessarily) if invoked on potentially shared segments of variable length, in particular the bss segment.
 122
 123 FPA emulation leaves much to be desired, rounding modes are ignored, all calculations are performed at extended precision.
 124 Floating point exceptions crash the emulator.
 125
 126 Several syscalls, most notably the
 127 .IR segattach (2)
 128 family, are not implemented (this should not be hard to fix).
 129 The emulator notes the value of
 130 .IR errstr (2)
 131 only under obvious circumstances; with most syscalls only if the return value is negative.
 132
 133 .B /proc
 134 emulation is more than unsatisfactory.
 135
 136 The
 137 .I text
 138 argument should behave more like it would if it had been entered as an argument to
 139 .IR rc (1).