man2/vm86.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   4 .\" Copyright 1997 Andries E. Brouwer (aeb@cwi.nl)
   5 .\" Copyright 2009 Samuel Bronson <naesten@gmail.com>
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\"
  27 .TH VM86 2 2009-05-07 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 vm86old, vm86 \- enter virtual 8086 mode
  30 .SH SYNOPSIS
  31 .B #include <sys/vm86.h>
  32 .sp
  33 .BI "int vm86old(struct vm86_struct *" info );
  34 .sp
  35 .BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 );
  36 .SH DESCRIPTION
  37 These calls cause the process to enter VM86 mode (virtual-8086 in Intel
  38 literature), and are used by
  39 .BR dosemu (1).
  40 .PP
  41 VM86 mode is an emulation of real mode within a protected mode task.
  42 .PP
  43 .BR vm86 ()
  44 performs one of the following operations based on the function code given in
  45 .IR fn .
  46 .SS Checking Availability
  47 .TP
  48 .B VM86_PLUS_INSTALL_CHECK
  49 For testing if the new
  50 .BR vm86 ()
  51 call is available.
  52 If so, returns 0.
  53 If the architecture is wrong or
  54 .BR vm86 ()
  55 was left out of the kernel to save a few k, returns \-1 and sets errno
  56 to
  57 .B ENOSYS.
  58 .\" Comments in the source describe using VM86_PLUS_INSTALL_CHECK
  59 .\" also to make sure that it's the *new* vm86 that got called, but
  60 .\" that hardly seems relevant today
  61
  62 .SS IRQ Management
  63 .\" The information in this section was gleaned from a combination of
  64 .\"  * The kernel sources
  65 .\"  * An email from Bart Oldeman
  66 .\"      http://sourceforge.net/mailarchive/message.php?msg_name=c3d607cc0905011152o384ee165t986a96c56b7c868c%40mail.gmail.com
  67 .\"    (at least one other email in this thread was used for other
  68 .\"    portions of what I've added to this page)
  69 .\"  * Dosemu's
  70 .\"      src/arch/linux/async/signal.c
  71 .\"    which Bart pointed me to in the above email
  72 .\" -- Sam
  73 The function codes
  74 .BR VM86_REQUEST_IRQ ", " VM86_FREE_IRQ ", "
  75 .BR VM86_GET_IRQ_BITS ", and " VM86_GET_AND_RESET_IRQ
  76 are used to intercept real hardware IRQs from interrupt vectors 3
  77 through 15.
  78 They treat the second argument to
  79 .BR vm86()
  80 as an integer;
  81 the rest of this subsection will act as if it were declared as
  82 .BI "unsigned\ long\ " irqnumber \fR.
  83 .LP
  84 The
  85 .B VM86_REQUEST_IRQ
  86 function code requires the
  87 .B CAP_SYS_ADMIN
  88 capability
  89 (superuser for Linux versions before the introduction of
  90 capabilities in 2.1.100);
  91 since none of the other function codes actually do anything without
  92 being preceded by a successful
  93 .BR VM86_REQUEST_IRQ ,
  94 this effectively limits the entire facility to programs running with
  95 that capability.
  96 .LP
  97 This facility actually has little to do with VM86 mode;
  98 you can use it independantly to e.g. implement hardware drivers in
  99 userspace.
 100 The main thing the two have in common is that
 101 .BR dosemu (1)
 102 can use them both, which is probably why this facility included in this
 103 system call rather than implemented as a seperate system call.
 104
 105 .TP
 106 .B VM86_REQUEST_IRQ
 107 Arrange for hardware interrupt
 108 .I irq
 109 to be delivered as signal
 110 .IR sig ,
 111 where
 112
 113 .in +4n
 114 .IR irqnumber "\ =\ " sig "\ <<\ 8 +\ " irq .
 115 .in
 116
 117 .I sig
 118 may be one of
 119 .BR SIGUSR1 ", "
 120 .BR SIGUSR2 ", "
 121 .BR SIGIO ", "
 122 .BR SIGURG ", "
 123 .BR SIGUNUSED ","
 124 or, if no signal should be generated for this IRQ, 0.
 125
 126 Upon receipt of this interrupt, the kernel will send the requested
 127 signal (if any) to the requesting process and disable the interrupt
 128 pending a
 129 .B VM86_GET_AND_RESET_IRQ
 130 from that process.
 131 The kernel may become displeased if the interrupt is not handled in a
 132 timely fashion.
 133
 134 .TP
 135 .B VM86_FREE_IRQ
 136 End delivery of interrupt
 137 .I irqnumber
 138 to this process, and allow other processes to request it.
 139
 140 .TP
 141 .B VM86_GET_IRQ_BITS
 142 Returns a bitmap where 1 <<
 143 .I intno
 144 is set if interrupt
 145 .I intno
 146 has been recieved on behalf of, but not handled by,
 147 a process that requested it with
 148 .BR VM86_REQUEST_IRQ .
 149
 150 .TP
 151 .B VM86_GET_AND_RESET_IRQ
 152 Check if interrupt
 153 .I irqnumber
 154 since the last time either
 155 .B VM86_REQUEST_IRQ
 156 or this function code was called on it
 157 and, if so, clear it's bit in the bitmap returned by
 158 .BR VM86_GET_IRQ_BITS
 159 and re-enable the IRQ.
 160
 161 The above assumes that the calling process has requested the given
 162 interrupt with
 163 .B VM86_REQUEST_IRQ
 164 without having subsequently released it with
 165 .BR VM86_FREE_IRQ .
 166 If this is not the case, this function code just returns 0.
 167
 168 .SS Entering VM86 mode
 169 The
 170 .B VM86_ENTER
 171 and
 172 .B VM86_ENTER_NO_BYPASS
 173 function codes are used to enter VM86 mode.
 174 They use the passed
 175 .I "struct\ vm86plus_struct"
 176 both to control operation and to maintain the virtual machine's
 177 register values.
 178 This structure is defined as follows:
 179 .ft CR
 180 .in +4n
 181 .nf
 182
 183 struct vm86_regs {
 184 /*
 185  * normal regs, with special meaning for the segment descriptors..
 186  */
 187         long ebx;
 188         long ecx;
 189         long edx;
 190         long esi;
 191         long edi;
 192         long ebp;
 193         long eax;
 194         long __null_ds;
 195         long __null_es;
 196         long __null_fs;
 197         long __null_gs;
 198         long orig_eax;
 199         long eip;
 200         unsigned short cs, __csh;
 201         long eflags;
 202         long esp;
 203         unsigned short ss, __ssh;
 204
 205 /*
 206  * these are specific to v86 mode:
 207  */
 208         unsigned short es, __esh;
 209         unsigned short ds, __dsh;
 210         unsigned short fs, __fsh;
 211         unsigned short gs, __gsh;
 212 };
 213
 214 struct revectored_struct {
 215         unsigned long __map[8];                 /* 256 bits */
 216 };
 217
 218 struct vm86plus_info_struct {
 219         unsigned long force_return_for_pic:1;
 220         unsigned long vm86dbg_active:1;       /* for debugger */
 221         unsigned long vm86dbg_TFpendig:1;     /* for debugger */
 222         unsigned long unused:28;
 223         unsigned long is_vm86pus:1;           /* for vm86 internal use */
 224         unsigned char vm86dbg_intxxtab[32];   /* for debugger */
 225 };
 226 struct vm86plus_struct {
 227         struct vm86_regs regs;
 228         unsigned long flags;
 229         unsigned long screen_bitmap;
 230         unsigned long cpu_type;
 231         struct revectored_struct int_revectored;
 232         struct revectored_struct int21_revectored;
 233         struct vm86plus_info_struct vm86plus;
 234 };
 235
 236 .in
 237 .fi
 238 The
 239 .I vm86_regs
 240 structure holds the register values of the virtual machine.
 241 The
 242 .IR __null_ds ", " __null_es ", " __null_fs ", and " __null_gs
 243 fields are generally zero, since the CPU clears these registers
 244 (after saving them to the stack)
 245 when leaving VM86 mode in order to allow the OS to safely save and
 246 restore these registers in interrupt/exception handlers regardless of
 247 whether the interrupted process was running in VM86 mode \(em it is not
 248 safe to load arbitrary values into these registers in protected mode.
 249 The real segment register values are kept in fields
 250 .IR es ", " ds ", " fs ", and " gs .
 251 The CS and SS segment registers, on the other hand, get pushed on the
 252 kernel stack on exit from VM86 mode "before" being loaded with new
 253 values from the IDT and TSS, respectively.
 254 (Not
 255 .B quite
 256 before, since the CPU needs to use the new SS to do the push, but it
 257 is the old value that is pushed.)
 258 Because valid protected-mode values for these registers are loaded by
 259 the CPU, there is no
 260 .IR __null_cs " or " __null_ss
 261 field.
 262
 263 .PP
 264 FIXME: Document more of the fields.
 265
 266 .SH "RETURN VALUE"
 267 The return value of a successful
 268 .BR vm86old ()
 269 call consists of a type code, accessed using the macro
 270 .BR VM86_TYPE "(\fIretval\fP),"
 271 and an argument, accessed using the macro
 272 .BR VM86_ARG "(\fIretval\fP)."
 273 The type code is one of the following:
 274 .TP
 275 .BR "VM86_SIGNAL = 0" " (no argument)"
 276 The process left VM86 mode because it recieved a signal.
 277 .TP
 278 .BR VM86_UNKNOWN " (no argument)"
 279 There was a GP fault that the kernel did not not know how to handle.
 280 .\" There is presumably no exception error code, since that is only
 281 .\" relevent for GP faults when triggered by a bad segment selector
 282 .TP
 283 .BR VM86_INTx " (interrupt number)"
 284 The VM encountered an INT instruction.
 285 CS:IP points to the following instruction.
 286 .TP
 287 .BR VM86_STI " (no argument)"
 288 An instruction (sti/popf/iret) enabled interrupts for the VM, and
 289 the VIP (virtual interrupt pending) flag was set in EFLAGS.
 290 (Neither the kernel nor the CPU set VIP directly, so this can only
 291 happen if it is set by the application in the passed structure.
 292 Also, as of
 293 .IR v2.6.30-rc4 ,
 294 the kernel still does not actually use the VME extension in which VIP
 295 is defined to implement this, though that shouldn't affect the behaviour.)
 296 .PP
 297 The return value of a successful
 298 .BR vm86 ()
 299 call depends on the function code:
 300 .TP
 301 .B VM86_PLUS_INSTALL_CHECK
 302 Zero.
 303 .TP
 304 .B VM86_ENTER
 305 As for
 306 .BR vm86old (),
 307 except that the following additional return types are possible:
 308 .RS
 309 .TP
 310 .BR VM86_PICRETURN " (no argument)"
 311 The VM encountered a PUSHF, POPF, IRET, STI, or CLI instruction, and the
 312 .I v86->vm86plus.force_return_for_pic
 313 field was set.
 314 .TP
 315 .BR VM86_TRAP " (exception number)"
 316 The VM generated exception number 1 (DB \(en debug exception) or 3 (BP
 317 \(en breakpoint).
 318 .RE
 319
 320 .LP
 321 On error, \-1 is returned, and
 322 .I errno
 323 is set appropriately.
 324 .SH ERRORS
 325 .TP
 326 .B EFAULT
 327 This return value is specific to i386 and indicates a problem with getting
 328 userspace data.
 329 .TP
 330 .B ENOSYS
 331 This return value indicates the call is not implemented on the present
 332 architecture (or that the kernel was built without support for it).
 333 .TP
 334 .B EPERM
 335 Saved kernel stack exists.
 336 (This is a kernel sanity check; the saved
 337 stack should only exist within vm86 mode itself.)
 338 .SH "VERSIONS"
 339 The system call
 340 .BR vm86 ()
 341 was introduced in Linux 0.97p2.
 342 In Linux 2.1.15 and 2.0.28 it was renamed to
 343 .BR vm86old (),
 344 and a new
 345 .BR vm86 ()
 346 was introduced.
 347 The definition of \fIstruct vm86_struct\fP was changed
 348 in 1.1.8 and 1.1.9.
 349 .SH "CONFORMING TO"
 350 This call is specific to Linux on 32-bit Intel processors,
 351 and should not be used in programs intended to be portable.
 352 .SH "SEE ALSO"
 353 .BR capabilities (7),
 354 \fIIA-32 Intel\*[R] Architecture Software Developer's Manual\fP