OpenCoreUefiAudio: Implement UEFI audio `SetupDelay`

closes acidanthera/bugtracker#971

Changelog.md

@@ -13,6 +13,7 @@ OpenCore Changelog
 - Fixed macserial crashes when processing invalid serials
 - Fixed macserial issues when processing 2021 year serials
 - Added advanced error checking in ocvalidate utility
+- Added `SetupDelay` to configure audio setup delay
 
 #### v0.6.4
 - Added `BlacklistAppleUpdate` to fix macOS 11 broken update optout

Docs/Configuration.tex

@@ -5923,6 +5923,16 @@ functioning. Feature highlights:
   \emph{Note}: \texttt{Enabled} can be used in separate from \texttt{StartupMute}
   NVRAM variable to avoid conflicts when the firmware is able to play boot chime.
 
+\item
+  \texttt{SetupDelay}\\
+  \textbf{Type}: \texttt{plist\ integer}\\
+  \textbf{Failsafe}: \texttt{0}\\
+  \textbf{Description}: Audio codec reconfiguration delay in microseconds.
+
+  Some codecs require a vendor-specific delay after the reconfiguration
+  (e.g. volume setting). This option makes it configurable. In general
+  the necessary delay may be as long as 0.5 seconds.
+
 \item
   \texttt{VolumeAmplifier}\\
   \textbf{Type}: \texttt{plist\ integer}\\

Docs/Differences/Differences.tex

 \documentclass[]{article}
 %DIF LATEXDIFF DIFFERENCE FILE
 %DIF DEL PreviousConfiguration.tex   Wed Dec 16 19:38:04 2020
-%DIF ADD ../Configuration.tex        Wed Dec 23 00:33:29 2020
+%DIF ADD ../Configuration.tex        Sat Dec 26 11:23:56 2020
 
 \usepackage{lmodern}
 \usepackage{amssymb,amsmath}
@@ -5984,7 +5984,19 @@ functioning. Feature highlights:
   NVRAM variable to avoid conflicts when the firmware is able to play boot chime.
 
 \item
-  \texttt{VolumeAmplifier}\\
+  \DIFaddbegin \texttt{\DIFadd{SetupDelay}}\\
+  \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\
+  \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{0}}\\
+  \textbf{\DIFadd{Description}}\DIFadd{: Audio codec reconfiguration delay in microseconds.
+}
+
+  \DIFadd{Some codecs require a vendor-specific delay after the reconfiguration
+  (e.g. volume setting). This option makes it configurable. In general
+  the necessary delay may be as long as 0.5 seconds.
+}
+
+\item
+  \DIFaddend \texttt{VolumeAmplifier}\\
   \textbf{Type}: \texttt{plist\ integer}\\
   \textbf{Failsafe}: \texttt{0}\\
   \textbf{Description}: Multiplication coefficient for system volume to raw volume linear translation

Docs/Sample.plist

@@ -1068,6 +1068,8 @@
 			<integer>0</integer>
 			<key>AudioSupport</key>
 			<false/>
+			<key>SetupDelay</key>
+			<integer>0</integer>
 			<key>MinimumVolume</key>
 			<integer>20</integer>
 			<key>PlayChime</key>

Docs/SampleCustom.plist

@@ -1263,6 +1263,8 @@
 			<integer>0</integer>
 			<key>AudioSupport</key>
 			<false/>
+			<key>SetupDelay</key>
+			<integer>0</integer>
 			<key>MinimumVolume</key>
 			<integer>20</integer>
 			<key>PlayChime</key>

Include/Acidanthera/Library/OcConfigurationLib.h

@@ -579,6 +579,7 @@ typedef enum {
 #define OC_UEFI_AUDIO_FIELDS(_, __) \
   _(OC_STRING                   , AudioDevice        ,     , OC_STRING_CONSTR ("", _, __)  , OC_DESTR (OC_STRING)) \
   _(OC_STRING                   , PlayChime          ,     , OC_STRING_CONSTR ("", _, __)  , OC_DESTR (OC_STRING)) \
+  _(UINTN                       , SetupDelay         ,     , 0                             , ()) \
   _(UINT16                      , VolumeAmplifier    ,     , 0                             , ()) \
   _(BOOLEAN                     , AudioSupport       ,     , FALSE                         , ()) \
   _(UINT8                       , AudioCodec         ,     , 0                             , ()) \

Include/Acidanthera/Protocol/OcAudio.h

@@ -18,7 +18,7 @@
 #include <Protocol/AppleVoiceOver.h>
 #include <Protocol/DevicePath.h>
 
-#define OC_AUDIO_PROTOCOL_REVISION  0x010000
+#define OC_AUDIO_PROTOCOL_REVISION  0x020000
 
 //
 // OC_AUDIO_PROTOCOL_GUID
@@ -217,6 +217,21 @@ EFI_STATUS
   IN     BOOLEAN                    Wait
   );
 
+/**
+  Set playback delay.
+
+  @param[in,out] This         Audio protocol instance.
+  @param[in]     Delay        Delay after audio configuration in microseconds.
+
+  @return previous delay, defaults to 0.
+**/
+typedef
+UINTN
+(EFIAPI* OC_AUDIO_SET_DELAY) (
+  IN OUT OC_AUDIO_PROTOCOL          *This,
+  IN     UINTN                      Delay
+  );
+
 //
 // Includes a revision for debugging reasons.
 //
@@ -226,6 +241,7 @@ struct OC_AUDIO_PROTOCOL_ {
   OC_AUDIO_SET_PROVIDER   SetProvider;
   OC_AUDIO_PLAY_FILE      PlayFile;
   OC_AUDIO_STOP_PLAYBACK  StopPlayback;
+  OC_AUDIO_SET_DELAY      SetDelay;
 };
 
 extern EFI_GUID gOcAudioProtocolGuid;

Library/OcAudioLib/OcAudio.c

@@ -352,6 +352,14 @@ InternalOcAudioPlayFile (
     Channels
     );
   if (!EFI_ERROR (Status)) {
+    //
+    // We are required to wait for some time after codec setup on some systems.
+    // REF: https://github.com/acidanthera/bugtracker/issues/971
+    //
+    if (Private->PlaybackDelay > 0) {
+      gBS->Stall (Private->PlaybackDelay);
+    }
+
     Status = Private->AudioIo->StartPlaybackAsync (
       Private->AudioIo,
       RawBuffer,
@@ -467,3 +475,21 @@ InternalOcAudioStopPlayBack (
 
   return EFI_SUCCESS;
 }
+
+UINTN
+EFIAPI
+InternalOcAudioSetDelay (
+  IN OUT OC_AUDIO_PROTOCOL          *This,
+  IN     UINTN                      Delay
+  )
+{
+  OC_AUDIO_PROTOCOL_PRIVATE       *Private;
+  UINTN                           PreviousDelay;
+
+  Private = OC_AUDIO_PROTOCOL_PRIVATE_FROM_OC_AUDIO (This);
+
+  PreviousDelay = Private->PlaybackDelay;
+  Private->PlaybackDelay = Delay;
+
+  return PreviousDelay;
+}

Library/OcAudioLib/OcAudioGenBeep.c

@@ -143,6 +143,14 @@ InternalOcAudioGenBeep (
     return EFI_ABORTED;
   }
 
+  //
+  // We are required to wait for some time after codec setup on some systems.
+  // REF: https://github.com/acidanthera/bugtracker/issues/971
+  //
+  if (Private->PlaybackDelay > 0) {
+    gBS->Stall (Private->PlaybackDelay);
+  }
+
   for (Index = 0; Index < ToneCount; ++Index) {
     Status = Private->AudioIo->StartPlayback (
       Private->AudioIo,

Library/OcAudioLib/OcAudioInternal.h

@@ -48,6 +48,7 @@ typedef struct {
   VOID                                  *ProviderContext;
   VOID                                  *CurrentBuffer;
   EFI_EVENT                             PlaybackEvent;
+  UINTN                                 PlaybackDelay;
   UINT8                                 Language;
   UINT8                                 OutputIndex;
   UINT8                                 Volume;
@@ -90,6 +91,13 @@ InternalOcAudioStopPlayBack (
   IN     BOOLEAN                    Wait
   );
 
+UINTN
+EFIAPI
+InternalOcAudioSetDelay (
+  IN OUT OC_AUDIO_PROTOCOL          *This,
+  IN     UINTN                      Delay
+  );
+
 EFI_STATUS
 EFIAPI
 InternalOcAudioGenBeep (

Library/OcAudioLib/OcAudioLib.c

@@ -47,6 +47,7 @@ mAudioProtocol = {
   .ProviderContext = NULL,
   .CurrentBuffer   = NULL,
   .PlaybackEvent   = NULL,
+  .PlaybackDelay   = 0,
   .Language        = AppleVoiceOverLanguageEn,
   .OutputIndex     = 0,
   .Volume          = 100,
@@ -56,6 +57,7 @@ mAudioProtocol = {
     .SetProvider        = InternalOcAudioSetProvider,
     .PlayFile           = InternalOcAudioPlayFile,
     .StopPlayback       = InternalOcAudioStopPlayBack,
+    .SetDelay           = InternalOcAudioSetDelay
   },
   .BeepGen         = {
     .GenBeep            = InternalOcAudioGenBeep,

Library/OcConfigurationLib/OcConfigurationLib.c

@@ -707,6 +707,7 @@ mUefiAudioSchema[] = {
   OC_SCHEMA_BOOLEAN_IN ("AudioSupport",       OC_GLOBAL_CONFIG, Uefi.Audio.AudioSupport),
   OC_SCHEMA_INTEGER_IN ("MinimumVolume",      OC_GLOBAL_CONFIG, Uefi.Audio.MinimumVolume),
   OC_SCHEMA_STRING_IN  ("PlayChime",          OC_GLOBAL_CONFIG, Uefi.Audio.PlayChime),
+  OC_SCHEMA_INTEGER_IN ("SetupDelay",         OC_GLOBAL_CONFIG, Uefi.Audio.SetupDelay),
   OC_SCHEMA_INTEGER_IN ("VolumeAmplifier",    OC_GLOBAL_CONFIG, Uefi.Audio.VolumeAmplifier),
 };
 

Platform/OpenCore/OpenCoreUefiAudio.c

@@ -447,6 +447,11 @@ OcLoadUefiAudioSupport (
     return;
   }
 
+  OcAudio->SetDelay (
+    OcAudio,
+    Config->Uefi.Audio.SetupDelay
+    );
+
   OcSetVoiceOverLanguage (NULL);
 
   if (OcShouldPlayChime (OC_BLOB_GET (&Config->Uefi.Audio.PlayChime))