VirtualBox

Changeset 56442 in vbox for trunk/doc/manual/en_US


Ignore:
Timestamp:
Jun 16, 2015 9:29:47 AM (10 years ago)
Author:
vboxsync
Message:

updates

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/en_US/man_VBoxManage_debugvm.xml

    r56344 r56442  
    2222
    2323  <refmeta>
     24    <refentrytitle>VBoxManage-debugvm</refentrytitle>
    2425    <manvolnum>1</manvolnum>
    2526  </refmeta>
    … …  
    2728  <refnamediv>
    2829    <refname>VBoxManage-debugvm</refname>
    29     <refpurpose>extension package management</refpurpose>
     30    <refpurpose>introspection and guest debugging</refpurpose>
    3031    <refclass>Oracle VM VirtualBox</refclass>
    3132  </refnamediv>
    3233
    3334  <refsynopsisdiv>
    34     <cmdsynopsis id="synopsis-vboxmanage-debugvm-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. -->
    35       <command>VBoxManage debugvm install</command>
    36       <arg>--replace</arg>
    37       <arg choice="req"><replaceable>tarball</replaceable></arg>
    38     </cmdsynopsis>
    39     <cmdsynopsis id="synopsis-vboxmanage-debugvm-uninstall">
    40       <command>VBoxManage debugvm uninstall</command>
    41       <arg>--force</arg>
    42       <arg choice="req"><replaceable>name</replaceable></arg>
    43     </cmdsynopsis>
    44     <cmdsynopsis id="synopsis-vboxmanage-debugvm-cleanup">
    45       <command>VBoxManage debugvm cleanup</command>
     35    <cmdsynopsis id="synopsis-vboxmanage-debugvm-dumpguestcore">
     36      <command>VBoxManage debugvm</command>
     37      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     38      <arg choice="plain">dumpguestcore</arg>
     39      <arg>--filename <replaceable>name</replaceable></arg>
     40    </cmdsynopsis>
     41    <cmdsynopsis id="synopsis-vboxmanage-debugvm-info">
     42      <command>VBoxManage debugvm</command>
     43      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     44      <arg choice="plain">info</arg>
     45      <arg choice="req"><replaceable>item</replaceable></arg>
     46      <arg rep="repeat"><replaceable>args</replaceable></arg>
     47    </cmdsynopsis>
     48    <cmdsynopsis id="synopsis-vboxmanage-debugvm-injectnmi">
     49      <command>VBoxManage debugvm</command>
     50      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     51      <arg choice="plain">injectnmi</arg>
     52    </cmdsynopsis>
     53    <cmdsynopsis id="synopsis-vboxmanage-debugvm-log">
     54      <command>VBoxManage debugvm</command>
     55      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     56      <arg choice="plain">log</arg>
     57      <group><arg>--release</arg><arg>--debug</arg></group>
     58      <arg rep="repeat"><replaceable>group-settings</replaceable></arg>
     59    </cmdsynopsis>
     60    <cmdsynopsis id="synopsis-vboxmanage-debugvm-logdest">
     61      <command>VBoxManage debugvm</command>
     62      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     63      <arg choice="plain">logdest</arg>
     64      <group><arg>--release</arg><arg>--debug</arg></group>
     65      <arg rep="repeat"><replaceable>destinations</replaceable></arg>
     66    </cmdsynopsis>
     67    <cmdsynopsis id="synopsis-vboxmanage-debugvm-logflags">
     68      <command>VBoxManage debugvm</command>
     69      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     70      <arg choice="plain">logflags</arg>
     71      <group><arg>--release</arg><arg>--debug</arg></group>
     72      <arg rep="repeat"><replaceable>flags</replaceable></arg>
     73    </cmdsynopsis>
     74    <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdetect">
     75      <command>VBoxManage debugvm</command>
     76      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     77      <arg choice="plain">osdetect</arg>
     78    </cmdsynopsis>
     79    <cmdsynopsis id="synopsis-vboxmanage-debugvm-osinfo">
     80      <command>VBoxManage debugvm</command>
     81      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     82      <arg choice="plain">osinfo</arg>
     83    </cmdsynopsis>
     84    <cmdsynopsis id="synopsis-vboxmanage-debugvm-getregisters">
     85      <command>VBoxManage debugvm</command>
     86      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     87      <arg choice="plain">getregisters</arg>
     88      <arg>--cpu <replaceable>id</replaceable></arg>
     89      <arg rep="repeat"><replaceable>reg-set.reg-name</replaceable></arg>
     90    </cmdsynopsis>
     91    <cmdsynopsis id="synopsis-vboxmanage-debugvm-setregisters">
     92      <command>VBoxManage debugvm</command>
     93      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     94      <arg choice="plain">setregisters</arg>
     95      <arg>--cpu <replaceable>id</replaceable></arg>
     96      <arg rep="repeat"><replaceable>reg-set.reg-name=value</replaceable></arg>
     97    </cmdsynopsis>
     98    <cmdsynopsis id="synopsis-vboxmanage-debugvm-show">
     99      <command>VBoxManage debugvm</command>
     100      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     101      <arg choice="plain">show</arg>
     102      <group><arg>--human-readable</arg><arg>--sh-export</arg><arg>--sh-eval</arg><arg>--cmd-set</arg></group>
     103      <arg rep="repeat"><replaceable>settings-item</replaceable></arg>
     104    </cmdsynopsis>
     105    <cmdsynopsis id="synopsis-vboxmanage-debugvm-statistics">
     106      <command>VBoxManage debugvm</command>
     107      <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     108      <arg choice="plain">statistics</arg>
     109      <arg>--reset</arg>
     110      <arg>--descriptions</arg>
     111      <arg>--pattern <replaceable>pattern</replaceable></arg>
    46112    </cmdsynopsis>
    47113  </refsynopsisdiv>
    48 
    49114  <refsect1>
    50115    <title>Description</title>
    51116
    52     <refsect2 id="vboxmanage-debugvm-install">
    53       <cmdsynopsis>
    54         <command>VBoxManage debugvm install</command>
    55         <arg>--replace</arg>
    56         <arg choice="req"><replaceable>tarball</replaceable></arg>
    57       </cmdsynopsis>
    58       <para>
    59         Installs a new extension pack on the system.  This command will fail if an older
    60         version of the same extension pack is already installed.  The
    61         <option>--replace</option> option can be used to uninstall any
    62         old package before the new one is installed.
    63       </para>
    64       <variablelist>
    65         <varlistentry>
    66           <term><option>--replace</option></term><listitem><para>Uninstall existing extension pack version.</para></listitem>
    67         </varlistentry>
    68         <varlistentry>
    69           <term><replaceable>tarball</replaceable></term>
     117    <para>The "debugvm" commands are for experts who want to tinker with the
     118      exact details of virtual machine execution.  Like the VM debugger<remark role="help-manual">
     119      described in <xref linkend="ts_debugger" /></remark>, these commands are only useful if you are
     120      very familiar with the details of the PC architecture and how to debug
     121      software.</para>
     122
     123    <refsect2 id="vboxmanage-debugvm-common-options">
     124      <title>Common options</title>
     125      <remark role="help-scope" condition="GLOBAL"/>
     126      <para>The subcommands of <command>debugvm</command> all operate on a running virtual
     127      machine:</para>
     128      <variablelist>
     129        <varlistentry>
     130          <term><replaceable>uuid|vmname</replaceable></term>
     131          <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem>
     132        </varlistentry>
     133      </variablelist>
     134    </refsect2>
     135
     136    <refsect2 id="vboxmanage-debugvm-dumpguestcore">
     137      <cmdsynopsis>
     138        <command>VBoxManage debugvm</command>
     139        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     140        <arg choice="plain">dumpguestcore</arg>
     141        <arg>--filename <replaceable>name</replaceable></arg>
     142      </cmdsynopsis>
     143      <para>
     144        Creates a system dump file of the specified VM.  This file will have
     145        the standard ELF core format (with custom sections)<remark role="help-manual">; see
     146        <xref linkend="ts_guest-core-format" /></remark>.
     147      </para>
     148      <para>
     149        This corresponds to the <command>writecore</command> command in the debugger.
     150      </para>
     151      <variablelist>
     152        <varlistentry>
     153          <term><option>--filename <replaceable>filename</replaceable></option></term>
     154          <listitem><para>The name of the output file.</para></listitem>
     155        </varlistentry>
     156      </variablelist>
     157    </refsect2>
     158
     159    <refsect2 id="vboxmanage-debugvm-info">
     160      <cmdsynopsis>
     161        <command>VBoxManage debugvm</command>
     162        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     163        <arg choice="plain">info</arg>
     164        <arg choice="req"><replaceable>item</replaceable></arg>
     165        <arg rep="repeat"><replaceable>args</replaceable></arg>
     166      </cmdsynopsis>
     167      <para>
     168        Displays info items relating to the VMM, device emulations and
     169        associated drivers.
     170      </para>
     171      <para>
     172        This corresponds to the <command>info</command> command in the debugger.
     173      </para>
     174      <variablelist>
     175        <varlistentry>
     176          <term><replaceable>info</replaceable></term>
    70177          <listitem>
    71             <para>The file containing the extension pack to be installed.</para>
    72           </listitem>
    73         </varlistentry>
    74       </variablelist>
    75     </refsect2>
    76 
    77     <refsect2 id="vboxmanage-debugvm-uninstall">
    78       <cmdsynopsis>
    79         <command>VBoxManage debugvm uninstall</command>
    80         <arg>--force</arg>
    81         <arg choice="req"><replaceable>name</replaceable></arg>
    82       </cmdsynopsis>
    83       <para>
    84         Uninstalls an extension pack from the system.  The subcommand will also succeed
    85         in the case where the specified extension pack is not present on the system.
    86         You can use <computeroutput>VBoxManage list debugvms</computeroutput> to show
    87         the names of the extension packs which are currently installed.
    88       </para>
    89       <variablelist>
    90         <varlistentry>
    91           <term><option>--force</option></term>
     178            <para>Name of the info item to display.  The special name
     179            <option>help</option> will list all the available info items and
     180            hints about optional arguments.</para>
     181          </listitem>
     182        </varlistentry>
     183        <varlistentry>
     184          <term><replaceable>args</replaceable></term>
    92185          <listitem>
    93             <para>Overrides most refusals to uninstall an extension pack</para>
    94           </listitem>
    95         </varlistentry>
    96         <varlistentry>
    97           <term><replaceable>name</replaceable></term>
    98           <listitem>
    99             <para>The name of the extension pack to be uninstalled.</para>
    100           </listitem>
    101         </varlistentry>
    102       </variablelist>
    103     </refsect2>
    104 
    105     <refsect2 id="vboxmanage-debugvm-cleanup">
    106       <cmdsynopsis>
    107         <command>VBoxManage debugvm cleanup</command>
    108       </cmdsynopsis>
    109       <para>
    110         Used to remove temporariy files and directories that may have been left behind
    111         if a previous install or uninstall command failed.
    112       </para>
     186            <para>Optional argument string for the info item handler.  Most info items
     187            does not take any extra arguments.  Arguments not recognized are generally
     188            ignored.</para>
     189          </listitem>
     190        </varlistentry>
     191      </variablelist>
     192    </refsect2>
     193
     194    <refsect2 id="vboxmanage-debugvm-injectnmi">
     195      <cmdsynopsis>
     196        <command>VBoxManage debugvm</command>
     197        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     198        <arg choice="plain">injectnmi</arg>
     199      </cmdsynopsis>
     200      <para>
     201        Causes a non-maskable interrupt (NMI) to be injected into the guest. This
     202        might be useful for certain debugging scenarios. What happens exactly is
     203        dependent on the guest operating system, but an NMI can crash the whole
     204        guest operating system. Do not use unless you know what you're doing.
     205      </para>
     206    </refsect2>
     207
     208    <refsect2 id="vboxmanage-debugvm-log">
     209      <cmdsynopsis>
     210        <command>VBoxManage debugvm</command>
     211        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     212        <arg choice="plain">log</arg>
     213        <group><arg>--release</arg><arg>--debug</arg></group>
     214        <arg rep="repeat"><replaceable>group-settings</replaceable></arg>
     215      </cmdsynopsis>
     216      <para>
     217        TODO
     218      </para>
     219    </refsect2>
     220
     221    <refsect2 id="vboxmanage-debugvm-logdest">
     222      <cmdsynopsis>
     223        <command>VBoxManage debugvm</command>
     224        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     225        <arg choice="plain">logdest</arg>
     226        <group><arg>--release</arg><arg>--debug</arg></group>
     227        <arg rep="repeat"><replaceable>destinations</replaceable></arg>
     228      </cmdsynopsis>
     229      <para>
     230        TODO
     231      </para>
     232    </refsect2>
     233
     234    <refsect2 id="vboxmanage-debugvm-logflags">
     235      <cmdsynopsis>
     236        <command>VBoxManage debugvm</command>
     237        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     238        <arg choice="plain">logflags</arg>
     239        <group><arg>--release</arg><arg>--debug</arg></group>
     240        <arg rep="repeat"><replaceable>flags</replaceable></arg>
     241      </cmdsynopsis>
     242      <para>
     243        TODO
     244      </para>
     245    </refsect2>
     246
     247    <refsect2 id="vboxmanage-debugvm-osdetect">
     248      <cmdsynopsis>
     249        <command>VBoxManage debugvm</command>
     250        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     251        <arg choice="plain">osdetect</arg>
     252      </cmdsynopsis>
     253      <para>
     254        Make the VMM's debugger facility (re)-detect the guest operating system (OS).
     255      </para>
     256      <para>
     257        This corresponds to the <command>detect</command> command in the debugger.
     258      </para>
     259    </refsect2>
     260
     261    <refsect2 id="vboxmanage-debugvm-osinfo">
     262      <cmdsynopsis>
     263        <command>VBoxManage debugvm</command>
     264        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     265        <arg choice="plain">osinfo</arg>
     266      </cmdsynopsis>
     267      <para>
     268        Displays information about the guest operating system (OS) previously
     269        detected by the VMM's debugger facility.
     270      </para>
     271    </refsect2>
     272
     273    <refsect2 id="vboxmanage-debugvm-getregisters">
     274      <cmdsynopsis>
     275        <command>VBoxManage debugvm</command>
     276        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     277        <arg choice="plain">getregisters</arg>
     278        <arg>--cpu <replaceable>id</replaceable></arg>
     279        <arg rep="repeat"><replaceable>reg-set.reg-name</replaceable></arg>
     280      </cmdsynopsis>
     281      <para>
     282        Retrieves register values for guest CPUs and emulated devices.
     283      </para>
     284      <variablelist>
     285        <varlistentry>
     286          <term><replaceable>reg-set.reg-name</replaceable></term>
     287          <listitem><para>One of more registers, each having one of the following forms:
     288            <itemizedlist>
     289              <listitem><computeroutput>register-set.register-name.sub-field</computeroutput></listitem>
     290              <listitem><computeroutput>register-set.register-name</computeroutput></listitem>
     291              <listitem><computeroutput>cpu-register-name.sub-field</computeroutput></listitem>
     292              <listitem><computeroutput>cpu-register-name</computeroutput></listitem>
     293              <listitem><computeroutput>all</computeroutput></listitem>
     294            </itemizedlist>
     295            The <replaceable>all</replaceable> form will cause all registers
     296            to be shown (no sub-fields).  The registers names are case-insensitive.
     297          </para></listitem>
     298        </varlistentry>
     299        <varlistentry>
     300          <term><option>--cpu <replaceable>id</replaceable></option></term>
     301          <listitem><para>Selects the CPU register set when specifying just a
     302            CPU register (3rd and 4th form).  The default is 0.</para>
     303          </listitem>
     304        </varlistentry>
     305      </variablelist>
     306    </refsect2>
     307
     308    <refsect2 id="vboxmanage-debugvm-logdest-setregisters">
     309      <cmdsynopsis>
     310        <command>VBoxManage debugvm</command>
     311        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     312        <arg choice="plain">setregisters</arg>
     313        <arg>--cpu <replaceable>id</replaceable></arg>
     314        <arg rep="repeat"><replaceable>reg-set.reg-name=value</replaceable></arg>
     315      </cmdsynopsis>
     316      <para>
     317        Changes register values for guest CPUs and emulated devices.
     318      </para>
     319      <variablelist>
     320        <varlistentry>
     321          <term><replaceable>reg-set.reg-name=value</replaceable></term>
     322          <listitem><para>One of more register assignment, each having one of the following forms:
     323            <itemizedlist>
     324              <listitem><computeroutput>register-set.register-name.sub-field=value</computeroutput></listitem>
     325              <listitem><computeroutput>register-set.register-name=value</computeroutput></listitem>
     326              <listitem><computeroutput>cpu-register-name.sub-field=value</computeroutput></listitem>
     327              <listitem><computeroutput>cpu-register-name=value</computeroutput></listitem>
     328            </itemizedlist>
     329            The value format should be in the same style as what <command>getregisters</command>
     330            displays, with the exception that both octal and decimal can be used instead of
     331            hexadecimal.
     332          </para></listitem>
     333        </varlistentry>
     334        <varlistentry>
     335          <term><option>--cpu <replaceable>id</replaceable></option></term>
     336          <listitem><para>Selects the CPU register set when specifying just a
     337            CPU register (3rd and 4th form).  The default is 0.</para>
     338          </listitem>
     339        </varlistentry>
     340      </variablelist>
     341    </refsect2>
     342
     343    <refsect2 id="vboxmanage-debugvm-show">
     344      <cmdsynopsis>
     345        <command>VBoxManage debugvm</command>
     346        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     347        <arg choice="plain">show</arg>
     348        <group><arg>--human-readable</arg><arg>--sh-export</arg><arg>--sh-eval</arg><arg>--cmd-set</arg></group>
     349        <arg rep="repeat"><replaceable>settings-item</replaceable></arg>
     350      </cmdsynopsis>
     351      <para>
     352        TODO
     353      </para>
     354    </refsect2>
     355
     356    <refsect2 id="vboxmanage-debugvm-statistics">
     357      <cmdsynopsis>
     358        <command>VBoxManage debugvm</command>
     359        <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
     360        <arg choice="plain">statistics</arg>
     361        <arg>--reset</arg>
     362        <arg>--descriptions</arg>
     363        <arg>--pattern <replaceable>pattern</replaceable></arg>
     364      </cmdsynopsis>
     365      <para>
     366        Displays or resets VMM statistics.
     367      </para>
     368      <para>
     369        Retrieves register values for guest CPUs and emulated devices.
     370      </para>
     371      <variablelist>
     372        <varlistentry>
     373          <term><option>--pattern <replaceable>pattern</replaceable></option></term>
     374          <listitem><para>DOS/NT-style wildcards patterns for selecting statistics.  Multiple
     375            patterns can be specified by using the '|' (pipe) character as separator.</para>
     376          </listitem>
     377        </varlistentry>
     378        <varlistentry>
     379          <term><option>--reset</option></term>
     380          <listitem><para>Select reset instead of display mode.</para></listitem>
     381        </varlistentry>
     382      </variablelist>
     383
    113384    </refsect2>
    114385
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette