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