VirtualBox

Changeset 59523 in vbox for trunk/doc


Ignore:
Timestamp:
Jan 29, 2016 4:36:26 PM (9 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
105312
Message:

Devices/PC/DevPit-i8254.cpp: update PC speaker passthrough, make it more configurable and improve logging
doc/manual: update for PC speaker passthrough, plus a tweak for the table layouts (doubling the minimum column width as it frequently happens that it makes them too narrow)

Location:
trunk/doc/manual
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/docbook2latex.xsl

    r58442 r59523  
    120120\usepackage{scrextend}
    121121\definecolor{darkgreen}{rgb}{0,0.6,0}
     122\tymin=21pt
    122123
    123124</xsl:text>

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

    r59514 r59523  
    17731773
    17741774      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
    1775 
    1776     </sect2>
    1777 
     1775    </sect2>
    17781776  </sect1>
    17791777
    … …  
    30953093
    30963094      <para>This is a global setting.</para>
    3097 
    3098     </sect2>
    3099 
     3095    </sect2>
    31003096  </sect1>
    31013097
    … …  
    35093505      documentation.</para>
    35103506    </sect2>
    3511 
    35123507  </sect1>
    35133508
    … …  
    37183713       </glosslist>
    37193714     </para>
    3720 
    37213715   </sect1>
    37223716
    … …  
    37503744      command to remove the extra data. This is a per-VM setting and it is disabled by default.
    37513745    </para>
    3752 
    37533746  </sect1>
    37543747
    … …  
    37773770    To enable it for the OHCI or XHCI controller replace <computeroutput>usb-ehci</computeroutput>
    37783771    with <computeroutput>usb-ohci</computeroutput> or <computeroutput>usb-xhci</computeroutput> respectively.</para>
    3779 
    37803772  </sect1>
    37813773
    … …  
    38143806      <emphasis>VMMDev: GuestHeartBeat: Guest is alive.</emphasis>
    38153807    </para>
    3816 
    38173808  </sect1>
    38183809
    … …  
    41794170      </sect3>
    41804171    </sect2>
    4181 
    41824172  </sect1>
    41834173
    … …  
    41874177    <para>As an experimental feature (primarily due to being limited to Linux
    41884178    host only and unknown Linux distribution coverage) VirtualBox supports
    4189     passing through the PC speaker to the host, again as PC speaker. This has
    4190     nothing to do with regular audio/sound card support. The PC speaker
    4191     (sometimes called system speaker) is a much older and separate way to
    4192     produce audible feedback like beeps.</para>
    4193 
    4194     <para>The PC speaker passthrough feature handles beeps only. More advanced
    4195     PC speaker use by the VM (such as PCM audio) will not work, resulting in
    4196     undefined PC speaker behavior on the host.</para>
     4179    passing through the PC speaker to the host. The PC speaker (sometimes
     4180    called system speaker) is a way to produce audible feedback such as beeps
     4181    without the need for regular audio/sound card support.</para>
     4182
     4183    <para>The PC speaker passthrough feature in VirtualBox handles beeps only.
     4184    Advanced PC speaker use by the VM (such as PCM audio) will not work,
     4185    resulting in undefined host behavior.</para>
     4186
     4187    <para>Producing beeps on Linux is unfortunately a very complex topic.
     4188    VirtualBox offers a collection of options, in an attempt to make this work
     4189    deterministically and reliably on as many Linux distributions and system
     4190    configurations as possible:
     4191      <table>
     4192        <title>PC speaker configuration options</title>
     4193        <tgroup cols="3">
     4194          <thead>
     4195            <row>
     4196              <entry><emphasis role="bold">Code</emphasis></entry>
     4197              <entry><emphasis role="bold">Device</emphasis></entry>
     4198              <entry><emphasis role="bold">Notes</emphasis></entry>
     4199            </row>
     4200          </thead>
     4201          <tbody>
     4202            <row>
     4203              <entry>1</entry>
     4204              <entry><computeroutput>/dev/input/ by-path/platform- pcspkr-event-spkr</computeroutput></entry>
     4205              <entry>Direct host PC speaker use.</entry>
     4206            </row>
     4207            <row>
     4208              <entry>2</entry>
     4209              <entry><computeroutput>/dev/tty</computeroutput></entry>
     4210              <entry>Uses the terminal association of the VM process. VM needs
     4211              to be started on a virtual console.</entry>
     4212            </row>
     4213            <row>
     4214              <entry>3</entry>
     4215              <entry><computeroutput>/dev/tty0</computeroutput> or
     4216              <computeroutput>/dev/vc/0</computeroutput></entry>
     4217              <entry>Can only be used by user <computeroutput>root</computeroutput>
     4218              or users with capability <computeroutput>cap_sys_tty_config</computeroutput></entry>
     4219            </row>
     4220            <row>
     4221              <entry>9</entry>
     4222              <entry>user specified console or evdev device path</entry>
     4223              <entry>Like 1-3, just with a custom device path.</entry>
     4224            </row>
     4225            <row>
     4226              <entry>70</entry>
     4227              <entry><computeroutput>/dev/tty</computeroutput></entry>
     4228              <entry>Standard beep only. Loses frequency and length. See code
     4229              2.</entry>
     4230            </row>
     4231            <row>
     4232              <entry>79</entry>
     4233              <entry>user specified terminal device path</entry>
     4234              <entry>Like 70, just with a custom device path.</entry>
     4235            </row>
     4236            <row>
     4237              <entry>100</entry>
     4238              <entry>all of the above</entry>
     4239              <entry>Tries all above codes.</entry>
     4240            </row>
     4241          </tbody>
     4242        </tgroup>
     4243      </table>
     4244    </para>
    41974245
    41984246    <para>To enable PC speaker passthrough use the following command:
    4199       <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" 1</screen>
    4200     Changing this setting will take effect when the VM is started next. It is
    4201     safe to enable PC speaker passthrough on all host OSes. It will only have
    4202     an effect on Linux.</para>
    4203 
    4204     <para>The VM log file, VBox.log, will contain some lines with the prefix
    4205     <computeroutput>PIT: speaker:</computeroutput> showing the PC speaker
    4206     passthrough setup activities. It gives hints which emulation mode it
    4207     picked.</para>
    4208 
    4209     <para>Enabling PC speaker passthrough is usually the simple part. The real
    4210     difficulty is making sure that VirtualBox can access the necessary device.
    4211     PC speaker passthrough tries these devices:
    4212     <screen>/dev/input/by-path/platform-pcspkr-event-spkr
    4213 /dev/tty0
    4214 /dev/vc/0</screen>
    4215     The first one is the most reliable way to control the host PC speaker and
    4216     not some beep emulation through the sound card (showing as emulation mode
    4217     <computeroutput>evdev</computeroutput>. The other two would show as
    4218     emulation mode <computeroutput>console</computeroutput>. In any case, the
    4219     devices are in most linux distributions only accessible by root, and not by
    4220     the user running an X11 session. You need to find out how your distribution
    4221     allows changing this. Since there are countless variants, we can only give
    4222     the general hints that there is either an explicit way to give the X11
    4223     session user access to additional devices, or you need to find a working
    4224     solution using a udev configuration file. If everything fails you might
    4225     try setting the access rights using a script which is run late in the
    4226     startup.</para>
    4227 
    4228     <para>As a final fallback if none of the devices above are accessible,
    4229     VirtualBox will try to get access to the controlling terminal
    4230     <computeroutput>/dev/tty</computeroutput> and trigger standard beeps. This
    4231     loses the beep length and frequency, and is often not producing any beeps,
    4232     because X11 applications frequently have no controlling terminal.</para>
     4247      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N</screen>
     4248    Replace <computeroutput>N</computeroutput> with the code representing the
     4249    case you want to use. Changing this setting will take effect when the VM is
     4250    started next. It is safe to enable PC speaker passthrough on all host OSes.
     4251    It will only have an effect on Linux.</para>
     4252
     4253    <para>The VM log file, <computeroutput>VBox.log</computeroutput>, will
     4254    contain lines with the prefix <computeroutput>PIT: speaker:</computeroutput>
     4255    showing the PC speaker passthrough setup activities. It gives hints which
     4256    device it picked or why it failed.</para>
     4257
     4258    <para>Enabling PC speaker passthrough for the VM is usually the simple
     4259    part. The real difficulty is making sure that VirtualBox can access the
     4260    necessary device, because in a typical Linux install most of them can only
     4261    be accessed by user <computeroutput>root</computeroutput>. You should
     4262    follow the preferred way to persistently change this, e.g by referring to
     4263    your distribution's documentation. Since there are countless Linux
     4264    distribution variants, we can only give the general hints that there is
     4265    often a way to give the X11 session user access to additional devices, or
     4266    you need to find a working solution using a udev configuration file. If
     4267    everything fails you might try setting the permissions using a script
     4268    which is run late enough in the host system startup.</para>
     4269
     4270    <para>Sometimes additional rules are applied by the kernel to limit access
     4271    (e.g. that the VM process must have the same controlling terminal as the
     4272    device configured to be used for beeping, something which is often very
     4273    difficult to achieve for GUI applications such as VirtualBox). The table
     4274    above contains some hints, but generally refer to the Linux
     4275    documentation.</para>
    42334276
    42344277    <para>If you have trouble getting any beeps even if the device permissions
    42354278    are set up and VBox.log confirms that it uses evdev or console for the
    42364279    PC speaker control, check if your system has a PC speaker. Some systems do
    4237     not have a PC speaker. Other complications can arise from Linux rerouting
    4238     the PC speaker output to a sound card. Check if the beeps are audible if
    4239     you (temporarily) connect speakers to your sound card. Today almost all
    4240     systems have one. Finally, check if the audio mixer control has a channel
    4241     named "beep" (could be hidden in the mixer settings) and that it isn't
    4242     muted.</para>
     4280    not have one. Other complications can arise from Linux rerouting the PC
     4281    speaker output to a sound card. Check if the beeps are audible if you
     4282    connect speakers to your sound card. Today almost all systems have one.
     4283    Finally, check if the audio mixer control has a channel named "beep"
     4284    (could be hidden in the mixer settings) and that it isn't muted.</para>
    42434285  </sect1>
    42444286
Note: See TracChangeset for help on using the changeset viewer.

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