Changeset 59523 in vbox for trunk

Timestamp:

Jan 29, 2016 4:36:26 PM (9 years ago)

Author:

vboxsync

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

Files:

• doc/manual/docbook2latex.xsl (modified) (1 diff)
• doc/manual/en_US/user_AdvancedTopics.xml (modified) (9 diffs)
• src/VBox/Devices/PC/DevPit-i8254.cpp (modified) (10 diffs)

trunk/doc/manual/docbook2latex.xsl

@@ -120 +120 @@
 \usepackage{scrextend}
 \definecolor{darkgreen}{rgb}{0,0.6,0}
+\tymin=21pt
 
 </xsl:text>

trunk/doc/manual/en_US/user_AdvancedTopics.xml

@@ -1773 +1773 @@
 
       <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
-
-    </sect2>
-
+    </sect2>
   </sect1>
 
@@ -3095 +3093 @@
 
       <para>This is a global setting.</para>
-
-    </sect2>
-
+    </sect2>
   </sect1>
 
@@ -3509 +3505 @@
       documentation.</para>
     </sect2>
-
   </sect1>
 
@@ -3718 +3713 @@
        </glosslist>
      </para>
-
    </sect1>
 
@@ -3750 +3744 @@
       command to remove the extra data. This is a per-VM setting and it is disabled by default.
     </para>
-
   </sect1>
 
@@ -3777 +3770 @@
     To enable it for the OHCI or XHCI controller replace <computeroutput>usb-ehci</computeroutput>
     with <computeroutput>usb-ohci</computeroutput> or <computeroutput>usb-xhci</computeroutput> respectively.</para>
-
   </sect1>
 
@@ -3814 +3806 @@
       <emphasis>VMMDev: GuestHeartBeat: Guest is alive.</emphasis>
     </para>
-
   </sect1>
 
@@ -4179 +4170 @@
       </sect3>
     </sect2>
-
   </sect1>
 
@@ -4187 +4177 @@
     <para>As an experimental feature (primarily due to being limited to Linux
     host only and unknown Linux distribution coverage) VirtualBox supports
-    passing through the PC speaker to the host, again as PC speaker. This has
-    nothing to do with regular audio/sound card support. The PC speaker
-    (sometimes called system speaker) is a much older and separate way to
-    produce audible feedback like beeps.</para>
-
-    <para>The PC speaker passthrough feature handles beeps only. More advanced
-    PC speaker use by the VM (such as PCM audio) will not work, resulting in
-    undefined PC speaker behavior on the host.</para>
+    passing through the PC speaker to the host. The PC speaker (sometimes
+    called system speaker) is a way to produce audible feedback such as beeps
+    without the need for regular audio/sound card support.</para>
+
+    <para>The PC speaker passthrough feature in VirtualBox handles beeps only.
+    Advanced PC speaker use by the VM (such as PCM audio) will not work,
+    resulting in undefined host behavior.</para>
+
+    <para>Producing beeps on Linux is unfortunately a very complex topic.
+    VirtualBox offers a collection of options, in an attempt to make this work
+    deterministically and reliably on as many Linux distributions and system
+    configurations as possible:
+      <table>
+        <title>PC speaker configuration options</title>
+        <tgroup cols="3">
+          <thead>
+            <row>
+              <entry><emphasis role="bold">Code</emphasis></entry>
+              <entry><emphasis role="bold">Device</emphasis></entry>
+              <entry><emphasis role="bold">Notes</emphasis></entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>1</entry>
+              <entry><computeroutput>/dev/input/ by-path/platform- pcspkr-event-spkr</computeroutput></entry>
+              <entry>Direct host PC speaker use.</entry>
+            </row>
+            <row>
+              <entry>2</entry>
+              <entry><computeroutput>/dev/tty</computeroutput></entry>
+              <entry>Uses the terminal association of the VM process. VM needs
+              to be started on a virtual console.</entry>
+            </row>
+            <row>
+              <entry>3</entry>
+              <entry><computeroutput>/dev/tty0</computeroutput> or
+              <computeroutput>/dev/vc/0</computeroutput></entry>
+              <entry>Can only be used by user <computeroutput>root</computeroutput>
+              or users with capability <computeroutput>cap_sys_tty_config</computeroutput></entry>
+            </row>
+            <row>
+              <entry>9</entry>
+              <entry>user specified console or evdev device path</entry>
+              <entry>Like 1-3, just with a custom device path.</entry>
+            </row>
+            <row>
+              <entry>70</entry>
+              <entry><computeroutput>/dev/tty</computeroutput></entry>
+              <entry>Standard beep only. Loses frequency and length. See code
+              2.</entry>
+            </row>
+            <row>
+              <entry>79</entry>
+              <entry>user specified terminal device path</entry>
+              <entry>Like 70, just with a custom device path.</entry>
+            </row>
+            <row>
+              <entry>100</entry>
+              <entry>all of the above</entry>
+              <entry>Tries all above codes.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </para>
 
     <para>To enable PC speaker passthrough use the following command:
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" 1</screen>
-    Changing this setting will take effect when the VM is started next. It is
-    safe to enable PC speaker passthrough on all host OSes. It will only have
-    an effect on Linux.</para>
-
-    <para>The VM log file, VBox.log, will contain some lines with the prefix
-    <computeroutput>PIT: speaker:</computeroutput> showing the PC speaker
-    passthrough setup activities. It gives hints which emulation mode it
-    picked.</para>
-
-    <para>Enabling PC speaker passthrough is usually the simple part. The real
-    difficulty is making sure that VirtualBox can access the necessary device.
-    PC speaker passthrough tries these devices:
-    <screen>/dev/input/by-path/platform-pcspkr-event-spkr
-/dev/tty0
-/dev/vc/0</screen>
-    The first one is the most reliable way to control the host PC speaker and
-    not some beep emulation through the sound card (showing as emulation mode
-    <computeroutput>evdev</computeroutput>. The other two would show as
-    emulation mode <computeroutput>console</computeroutput>. In any case, the
-    devices are in most linux distributions only accessible by root, and not by
-    the user running an X11 session. You need to find out how your distribution
-    allows changing this. Since there are countless variants, we can only give
-    the general hints that there is either an explicit way to give the X11
-    session user access to additional devices, or you need to find a working
-    solution using a udev configuration file. If everything fails you might
-    try setting the access rights using a script which is run late in the
-    startup.</para>
-
-    <para>As a final fallback if none of the devices above are accessible,
-    VirtualBox will try to get access to the controlling terminal
-    <computeroutput>/dev/tty</computeroutput> and trigger standard beeps. This
-    loses the beep length and frequency, and is often not producing any beeps,
-    because X11 applications frequently have no controlling terminal.</para>
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N</screen>
+    Replace <computeroutput>N</computeroutput> with the code representing the
+    case you want to use. Changing this setting will take effect when the VM is
+    started next. It is safe to enable PC speaker passthrough on all host OSes.
+    It will only have an effect on Linux.</para>
+
+    <para>The VM log file, <computeroutput>VBox.log</computeroutput>, will
+    contain lines with the prefix <computeroutput>PIT: speaker:</computeroutput>
+    showing the PC speaker passthrough setup activities. It gives hints which
+    device it picked or why it failed.</para>
+
+    <para>Enabling PC speaker passthrough for the VM is usually the simple
+    part. The real difficulty is making sure that VirtualBox can access the
+    necessary device, because in a typical Linux install most of them can only
+    be accessed by user <computeroutput>root</computeroutput>. You should
+    follow the preferred way to persistently change this, e.g by referring to
+    your distribution's documentation. Since there are countless Linux
+    distribution variants, we can only give the general hints that there is
+    often a way to give the X11 session user access to additional devices, or
+    you need to find a working solution using a udev configuration file. If
+    everything fails you might try setting the permissions using a script
+    which is run late enough in the host system startup.</para>
+
+    <para>Sometimes additional rules are applied by the kernel to limit access
+    (e.g. that the VM process must have the same controlling terminal as the
+    device configured to be used for beeping, something which is often very
+    difficult to achieve for GUI applications such as VirtualBox). The table
+    above contains some hints, but generally refer to the Linux
+    documentation.</para>
 
     <para>If you have trouble getting any beeps even if the device permissions
     are set up and VBox.log confirms that it uses evdev or console for the
     PC speaker control, check if your system has a PC speaker. Some systems do
-    not have a PC speaker. Other complications can arise from Linux rerouting
-    the PC speaker output to a sound card. Check if the beeps are audible if
-    you (temporarily) connect speakers to your sound card. Today almost all
-    systems have one. Finally, check if the audio mixer control has a channel
-    named "beep" (could be hidden in the mixer settings) and that it isn't
-    muted.</para>
+    not have one. Other complications can arise from Linux rerouting the PC
+    speaker output to a sound card. Check if the beeps are audible if you
+    connect speakers to your sound card. Today almost all systems have one.
+    Finally, check if the audio mixer control has a channel named "beep"
+    (could be hidden in the mixer settings) and that it isn't muted.</para>
   </sect1>
 

trunk/src/VBox/Devices/PC/DevPit-i8254.cpp

@@ -5 +5 @@
 
 /*
- * Copyright (C) 2006-2015 Oracle Corporation
+ * Copyright (C) 2006-2016 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -276 +276 @@
 
 
+#ifdef IN_RING3
+# ifdef RT_OS_LINUX
+static int pitTryDeviceOpen(const char *pszPath, int flags)
+{
+    int fd = open(pszPath, flags);
+    if (fd == -1)
+        LogRel(("PIT: speaker: cannot open \"%s\", errno=%d\n", pszPath, errno));
+    else
+        LogRel(("PIT: speaker: opened \"%s\"\n", pszPath));
+    return fd;
+}
+
+static int pitTryDeviceOpenSanitizeIoctl(const char *pszPath, int flags)
+{
+    int fd = open(pszPath, flags);
+    if (fd == -1)
+        LogRel(("PIT: speaker: cannot open \"%s\", errno=%d\n", pszPath, errno));
+    else
+    {
+        int errno_eviocgsnd0 = 0;
+        int errno_kiocsound = 0;
+        if (ioctl(fd, EVIOCGSND(0)) != -1)
+        {
+            errno_eviocgsnd0 = errno;
+            if (ioctl(fd, KIOCSOUND, 1) == -1)
+                errno_kiocsound = errno;
+            else
+                ioctl(fd, KIOCSOUND, 0);
+        }
+        if (errno_eviocgsnd0 && errno_kiocsound)
+        {
+            LogRel(("PIT: speaker: cannot use \"%s\", ioctl failed errno=%d/errno=%d\n", pszPath, errno_eviocgsnd0, errno_kiocsound));
+            close(fd);
+            fd = -1;
+        }
+        else
+            LogRel(("PIT: speaker: opened \"%s\"\n", pszPath));
+    }
+    return fd;
+}
+# endif /* RT_OS_LINUX */
+#endif /* IN_RING3 */
 
 static int pit_get_count(PPITCHANNEL pChan)
@@ -884 +926 @@
                         if (res == -1)
                         {
-                            LogRel(("PIT: speaker: ioctl failed errno=%d\n", errno));
+                            LogRel(("PIT: speaker: ioctl failed errno=%d, disabling emulation\n", errno));
                             pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_NONE;
                         }
@@ -901 +943 @@
                         break;
                     default:
-                        Log2Func(("unknown speaker emulation %d\n", pThis->enmSpeakerEmu));
+                        Log2Func(("unknown speaker emulation %d, disabling emulation\n", pThis->enmSpeakerEmu));
                         pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_NONE;
                 }
@@ -911 +953 @@
                 {
                     case PIT_SPEAKER_EMU_CONSOLE:
+                        /* No error checking here. The Linux device driver
+                         * implementation considers it an error (errno=22,
+                         * EINVAL) to stop sound if it hasn't been started.
+                         * Of course we could detect this by checking only
+                         * for enabled->disabled transitions and ignoring
+                         * disabled->disabled ones, but it's not worth the
+                         * effort. */
                         ioctl(pThis->hHostSpeaker, KIOCSOUND, 0);
                         break;
@@ -925 +974 @@
                         break;
                     default:
-                        Log2Func(("unknown speaker emulation %d\n", pThis->enmSpeakerEmu));
+                        Log2Func(("unknown speaker emulation %d, disabling emulation\n", pThis->enmSpeakerEmu));
                         pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_NONE;
                 }
@@ -1256 +1305 @@
      * Validate configuration.
      */
-    if (!CFGMR3AreValuesValid(pCfg, "Irq\0" "Base\0" "SpeakerEnabled\0" "PassthroughSpeaker\0" "R0Enabled\0"))
+    if (!CFGMR3AreValuesValid(pCfg, "Irq\0" "Base\0"
+                                    "SpeakerEnabled\0" "PassthroughSpeaker\0" "PassthroughSpeakerDevice\0"
+                                    "R0Enabled\0" "GCEnabled\0"))
         return VERR_PDM_DEVINS_UNKNOWN_CFG_VALUES;
 
@@ -1277 +1328 @@
                                 N_("Configuration error: Querying \"SpeakerEnabled\" as a bool failed"));
 
-    bool fPassthroughSpeaker;
-    rc = CFGMR3QueryBoolDef(pCfg, "PassthroughSpeaker", &fPassthroughSpeaker, false);
+    uint8_t uPassthroughSpeaker;
+    char *pszPassthroughSpeakerDevice = NULL;
+    rc = CFGMR3QueryU8Def(pCfg, "PassthroughSpeaker", &uPassthroughSpeaker, 0);
     if (RT_FAILURE(rc))
         return PDMDEV_SET_ERROR(pDevIns, rc,
-                                N_("Configuration error: failed to read PassthroughSpeaker as boolean"));
+                                N_("Configuration error: failed to read PassthroughSpeaker as uint8_t"));
+    if (uPassthroughSpeaker)
+    {
+        rc = CFGMR3QueryStringAllocDef(pCfg, "PassthroughSpeakerDevice", &pszPassthroughSpeakerDevice, NULL);
+        if (RT_FAILURE(rc))
+            return PDMDEV_SET_ERROR(pDevIns, rc,
+                                    N_("Configuration error: failed to read PassthroughSpeakerDevice as string"));
+    }
 
     rc = CFGMR3QueryBoolDef(pCfg, "GCEnabled", &fGCEnabled, true);
@@ -1296 +1355 @@
     pThis->IOPortBaseCfg   = u16Base;
     pThis->fSpeakerCfg     = fSpeaker;
-    if (fPassthroughSpeaker)
+    pThis->enmSpeakerEmu   = PIT_SPEAKER_EMU_NONE;
+    if (uPassthroughSpeaker)
     {
         /** @todo r=klaus move this to a (system-specific) driver */
 #ifdef RT_OS_LINUX
-        int fd;
-        fd = open("/dev/input/by-path/platform-pcspkr-event-spkr", O_WRONLY);
-        if (fd == -1)
-            fd = open("/dev/tty0", O_WRONLY);
-        if (fd == -1)
-            fd = open("/dev/vc/0", O_WRONLY);
-        if (fd == -1)
+        int fd = -1;
+        if ((uPassthroughSpeaker == 1 || uPassthroughSpeaker == 100) && fd == -1)
+            fd = pitTryDeviceOpenSanitizeIoctl("/dev/input/by-path/platform-pcspkr-event-spkr", O_WRONLY);
+        if ((uPassthroughSpeaker == 2 || uPassthroughSpeaker == 100) && fd == -1)
+            fd = pitTryDeviceOpenSanitizeIoctl("/dev/tty", O_WRONLY);
+        if ((uPassthroughSpeaker == 3 || uPassthroughSpeaker == 100) && fd == -1)
         {
-            LogRel(("PIT: speaker: could not open console/speaker device\n"));
-            fd = open("/dev/tty", O_WRONLY);
+            fd = pitTryDeviceOpenSanitizeIoctl("/dev/tty0", O_WRONLY);
             if (fd == -1)
-            {
-                pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_NONE;
-                LogRel(("PIT: speaker: no emulation possible\n"));
-            }
-            else
-            {
-                pThis->hHostSpeaker = fd;
-                pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_TTY;
-                LogRel(("PIT: speaker: emulation mode tty\n"));
-            }
+                fd = pitTryDeviceOpenSanitizeIoctl("/dev/vc/0", O_WRONLY);
         }
-        else
+        if ((uPassthroughSpeaker == 9 || uPassthroughSpeaker == 100) && pszPassthroughSpeakerDevice && fd == -1)
+            fd = pitTryDeviceOpenSanitizeIoctl(pszPassthroughSpeakerDevice, O_WRONLY);
+        if (pThis->enmSpeakerEmu == PIT_SPEAKER_EMU_NONE && fd != -1)
         {
             pThis->hHostSpeaker = fd;
@@ -1336 +1387 @@
             }
         }
+        if ((uPassthroughSpeaker == 70 || uPassthroughSpeaker == 100) && fd == -1)
+            fd = pitTryDeviceOpen("/dev/tty", O_WRONLY);
+        if ((uPassthroughSpeaker == 79 || uPassthroughSpeaker == 100) && pszPassthroughSpeakerDevice && fd == -1)
+            fd = pitTryDeviceOpen(pszPassthroughSpeakerDevice, O_WRONLY);
+        if (pThis->enmSpeakerEmu == PIT_SPEAKER_EMU_NONE && fd != -1)
+        {
+            pThis->hHostSpeaker = fd;
+            pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_TTY;
+            LogRel(("PIT: speaker: emulation mode tty\n"));
+        }
+        if (pThis->enmSpeakerEmu == PIT_SPEAKER_EMU_NONE)
+        {
+            Assert(fd == -1);
+            LogRel(("PIT: speaker: no emulation possible\n"));
+        }
 #else
-        pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_NONE;
+        LogRel(("PIT: speaker: emulation deactivated\n"));
 #endif
-    }
-    else
-        pThis->enmSpeakerEmu = PIT_SPEAKER_EMU_NONE;
+        RTStrFree(pszPassthroughSpeakerDevice);
+        pszPassthroughSpeakerDevice = NULL;
+    }
     pThis->channels[0].irq = u8Irq;
     for (i = 0; i < RT_ELEMENTS(pThis->channels); i++)