Skip to content

O
OpenCorePKG_MOD

btwise / OpenCorePKG_MOD

通知 26
Star 0
Fork 0
O
OpenCorePKG_MOD

体验新版 GitCode，发现更多精彩内容 >>

提交 bbdbb5fe 编写于 作者: V vit9696
浏览文件
操作

Docs: Provide initial audio documentation

上级 55fd59b2
展开全部 隐藏空白更改
内联 并排
Showing with 675 addition and 244 deletion
Docs/Configuration.tex
浏览文件 @ bbdbb5fe
......@@ -396,6 +396,10 @@ be relied upon, and all fields must be properly specified in the configuration.
}
child [missing] {}
child [missing] {}
child { node [optional] {Resources}
child { node [optional] {Audio}}
}
child [missing] {}
child { node {Tools}
child { node [optional] {Tool.efi}}
}
......@@ -425,6 +429,8 @@ be relied upon, and all fields must be properly specified in the configuration.
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child { node [optional] {nvram.plist}}
child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}}
;
......@@ -460,6 +466,12 @@ entries include:
\break
Directory used for storing supplemental kernel information
for \hyperref[kernel]{\texttt{Kernel}} section.
\item
\texttt{Resources}
\break
Directory used for storing media resources, such as audio files
for screen reader support. See \hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}}
section for more details.
\item
\texttt{Tools}
\break
......@@ -1093,8 +1105,8 @@ list of checks to do first. Prior to starting please ensure that you have:
notes for more details.
\item \texttt{CSM} (Compatibility Support Module) disabled in firmware settings
if present. You may need to flash GOP ROM on NVIDIA 6xx/AMD 2xx or older. Use
\href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html}{GopUpdate} (See the second post)
or \href{http://www.insanelymac.com/forum/topic/299614-asus-eah6450-video-bios-uefi-gop-upgrade-and-gop-uefi-binary-in-efi-for-many-ati-cards/page-1#entry2042163}{AMD UEFI GOP MAKER}
\href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html}{GopUpdate}
(see the second post) or \href{http://www.insanelymac.com/forum/topic/299614-asus-eah6450-video-bios-uefi-gop-upgrade-and-gop-uefi-binary-in-efi-for-many-ati-cards/page-1#entry2042163}{AMD UEFI GOP MAKER}
in case you are not sure how.
\item \texttt{EHCI/XHCI Hand-off} enabled in firmware settings \texttt{only} if boot
stalls unless USB devices are disconnected.
......@@ -2128,6 +2140,23 @@ behaviour that does not go to any other sections
\emph{Note}: This option may not work well with \texttt{System} text renderer.
Setting a background different from black could help testing proper GOP functioning.
\item
\texttt{PickerAudioAssist}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Enable screen reader by default in boot picker.
For macOS bootloader screen reader preference is set in \texttt{preferences.efires}
archive in \texttt{isVOEnabled.int32} file and is controlled by the operating system.
For OpenCore screen reader support this option is an independent equivalent.
Toggling screen reader support in both OpenCore boot picker and macOS bootloader
FileVault 2 login window can also be done with \texttt{Command} + \texttt{F5} key
combination.
\emph{Note}: screen reader requires working audio support, see
\hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}}
section for more details.
\item
\texttt{PollAppleHotKeys}\\
\textbf{Type}: \texttt{plist\ boolean}\\
......@@ -2970,6 +2999,21 @@ troubleshooting:
\break
NVIDIA Web Driver control variable. Takes ASCII digit \texttt{1} or \texttt{0}
to enable or disable installed driver.
\item
\texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:StartupMute}
\break
Mute startup chime sound in firmware audio support. 8-bit integer.
The value of \texttt{0x00} means unmuted. Missing variable or any
other value means muted. This variable only affects Gibraltar
machines (T2).
\item
\texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume}
\break
System audio volume level for firmware audio support. 8-bit integer.
The bit of \texttt{0x80} means muted. Lower bits are used to encode
volume range specific to installed audio codec. The value is capped
by \texttt{MaximumBootBeepVolume} AppleHDA layout value to avoid
too loud audio playback in the firmware.
\end{itemize}
\section{PlatformInfo}\label{platforminfo}
......@@ -3657,16 +3701,58 @@ and supplementary utilities can be used.
\subsection{Properties}\label{uefiprops}
\begin{enumerate}
\item
\texttt{Audio}\\
\textbf{Type}: \texttt{plist\ dict}\\
\textbf{Failsafe}: None\\
\textbf{Description}: Configure audio backend support described
in \hyperref[uefiaudioprops]{Audio Properties} section below.
Audio support provides a way for upstream protocols to interact with the
selected hardware and audio resources. All audio resources should reside
in \texttt{\textbackslash EFI\textbackslash OC\textbackslash Resources\textbackslash Audio}
directory. Currently the only supported audio file format is WAVE PCM. While it is
driver-dependent which audio stream format is supported, most common audio cards
support 16-bit signed stereo audio at 44100 or 48000 Hz.
Audio file path is determined by audio type, audio localisation, and audio path. Each filename
looks as follows: \texttt{[audio type]\_[audio localisation]\_[audio path].wav}. For unlocalised
files filename does not include the language code and looks as follows:
\texttt{[audio type]\_[audio path].wav}.
\begin{itemize}
\tightlist
\item Audio type can be \texttt{OCEFIAudio} for OpenCore audio files or
\texttt{AXEFIAudio} for macOS bootloader audio files.
\item Audio localisation is a two letter language code (e.g. \texttt{en})
with an exception for Chinese, Spanish, and Portuguese. Refer to
\href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_LANGUAGE\_CODE} definition}
for the list of all supported localisations.
\item Audio path is the base filename corresponding to a file identifier. For macOS bootloader audio paths refer to
\href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_AUDIO\_FILE} definition}.
For OpenCore audio paths refer to
\href{https://github.com/acidanthera/OcSupportPkg/blob/master/Include/Protocol/OcAudio.h}{\texttt{OC\_VOICE\_OVER\_AUDIO\_FILE} definition}.
The only exception is OpenCore boot chime file, which is \texttt{OCEFIAudio\_VoiceOver\_Boot.wav}.
\end{itemize}
Audio localisation is determined separately for macOS bootloader and OpenCore.
For macOS bootloader it is set in \texttt{preferences.efires} archive in
\texttt{systemLanguage.utf8} file and is controlled by the operating system.
For OpenCore the value of \texttt{prev-lang:kbd} variable is used.
When native audio localisation of a particular file is missing, English language
(\texttt{en}) localisation is used. Sample audio files can be found in
\href{https://github.com/acidanthera/OcBinaryData}{OcBinaryData repository}.
\item
\texttt{ConnectDrivers}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Perform UEFI controller connection after driver loading.
This option is useful for loading filesystem drivers, which
usually follow UEFI driver model, and may not start by themselves.
While effective, this option may not be necessary for drivers performing
automatic connection, and may slightly slowdown the boot.
This option is useful for loading drivers following UEFI driver model
as they may not start by themselves. Examples of such drivers are filesystem
or audio drivers. While effective, this option may not be necessary for drivers
performing automatic connection, and may slightly slowdown the boot.
\emph{Note}: Some firmwares, made by Apple in particular, only connect the boot
drive to speedup the boot process. Enable this option to be able to see all the
......@@ -3689,10 +3775,14 @@ and supplementary utilities can be used.
\item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{ApfsDriverLoader}}
--- APFS file system bootstrap driver adding the support of embedded APFS drivers
in bootable APFS containers in UEFI firmwares.
\item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{AudioDxe}}
--- HDA audio support driver in UEFI firmwares for most Intel and some other controllers.
Refer to \href{https://github.com/acidanthera/bugtracker/issues/740}{acidanthera/bugtracker\#740}
for known issues in AudioDxe.
\item \href{https://github.com/acidanthera/OcSupportPkg}{\texttt{FwRuntimeServices}}
--- \texttt{OC\_FIRMWARE\_RUNTIME} protocol implementation that increases the security
of OpenCore and Lilu by supporting read-only and write-only NVRAM variables. Some
quirks, like \texttt{RequestBootVarRouting}, require this driver for proper function.
of \mbox{OpenCore} and Lilu by supporting read-only and write-only NVRAM variables. Some
commonly used quirks, e.g. \texttt{RequestBootVarRouting}, require this driver for proper function.
Due to the nature of being a runtime driver, i.e. functioning in parallel with the
target operating system, it cannot be implemented within OpenCore itself, but is bundled
with OpenCore releases.
......@@ -3768,6 +3858,108 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
\end{enumerate}
\subsection{Audio Properties}\label{uefiaudioprops}
\begin{enumerate}
\item
\texttt{AudioCodec}\\
\textbf{Type}: \texttt{plist\ integer}\\
\textbf{Failsafe}: empty string\\
\textbf{Description}: Codec address on the specified audio controller for audio support.
Normally this contains first audio codec address on the builtin analog audio controller (\texttt{HDEF}).
Audio codec addresses, e.g. \texttt{2}, can be found in the debug log (marked in bold):
\texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(<redacted>,\textbf{00000000}) (4 outputs)}\\
\texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(<redacted>,\textbf{00000000}) (1 outputs)}\\
\texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(<redacted>,\textbf{02000000}) (7 outputs)}
As an alternative this value can be obtained from \texttt{IOHDACodecDevice} class in I/O Registry
containing it in \texttt{IOHDACodecAddress} field.
\item
\texttt{AudioDevice}\\
\textbf{Type}: \texttt{plist\ string}\\
\textbf{Failsafe}: \texttt{0}\\
\textbf{Description}: Device path of the specified audio controller for audio support.
Normally this contains builtin analog audio controller (\texttt{HDEF}) device path,
e.g. \texttt{PciRoot(0x0)/Pci(0x1b,0x0)}. The list of recognised audio controllers can be
found in the debug log (marked in bold):
\texttt{OCAU: 1/3 \textbf{PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)}/VenMsg(<redacted>,00000000) (4 outputs)}\\
\texttt{OCAU: 2/3 \textbf{PciRoot(0x0)/Pci(0x3,0x0)}/VenMsg(<redacted>,00000000) (1 outputs)}\\
\texttt{OCAU: 3/3 \textbf{PciRoot(0x0)/Pci(0x1B,0x0)}/VenMsg(<redacted>,02000000) (7 outputs)}
As an alternative \texttt{gfxutil -f HDEF} command can be used in macOS. Specifying empty device
path will result in the first available audio controller to be used.
\item
\texttt{AudioOut}\\
\textbf{Type}: \texttt{plist\ integer}\\
\textbf{Failsafe}: \texttt{0}\\
\textbf{Description}: Index of the output port of the specified codec starting from 0.
Normally this contains the index of the green out of the builtin analog audio controller (\texttt{HDEF}).
The number of output nodes in the debug log (marked in bold):
\texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(<redacted>,00000000) (\textbf{4 outputs})}\\
\texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(<redacted>,00000000) (\textbf{1 outputs})}\\
\texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(<redacted>,02000000) (\textbf{7 outputs})}
\item
\texttt{AudioSupport}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Activate audio support by connecting to a backend driver.
Enabling this setting routes audio playback from builtin protocols to a dedicated
audio port (\texttt{AudioOut}) of the specified codec (\texttt{AudioCodec}) located
on the audio controller (\texttt{AudioDevice}).
\item
\texttt{MinimumVolume}\\
\textbf{Type}: \texttt{plist\ integer}\\
\textbf{Failsafe}: \texttt{0}\\
\textbf{Description}: Minimal heard volume level from \texttt{0} to \texttt{100}.
Screen reader will use this volume level, when the calculated volume level is
less than \texttt{MinimumVolume}. Boot chime sound will not play if the calculated
volume level is less than \texttt{MinimumVolume}.
\item
\texttt{PlayChime}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Play chime sound at startup.
Enabling this setting plays boot chime through builtin audio support. Volume level
is determined by \texttt{MinimumVolume} and \texttt{VolumeAmplifier} settings and
\texttt{SystemAudioVolume} NVRAM variable.
\emph{Note}: this setting is separate from \texttt{StartupMute} NVRAM variable
to avoid conflicts when the firmware is able to play boot chime.
\item
\texttt{VolumeAmplifier}\\
\textbf{Type}: \texttt{plist\ integer}\\
\textbf{Failsafe}: \texttt{0}\\
\textbf{Description}: Multiplication coefficient for system volume to raw volume linear translation
from \texttt{0} to \texttt{1000}.
Volume level range read from \texttt{SystemAudioVolume} varies depending on the codec.
To transform read value in \texttt{[0, 127]} range into raw volume range \texttt{[0, 100]}
the read value is scaled to \texttt{VolumeAmplifier} percents:
\begin{align*}
RawVolume &= MIN(\frac{SystemAudioVolume * VolumeAmplifier}{100}, 100)
\end{align*}
\emph{Note}: the transformation used in macOS is not linear, but it is very close
and this nuance is thus ignored.
\end{enumerate}
\subsection{Input Properties}\label{uefiinputprops}
\begin{enumerate}
......@@ -4070,6 +4262,27 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
\begin{enumerate}
\item
\texttt{AppleAudio}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Reinstalls Apple audio protocols with builtin
versions.
Apple audio protocols allow macOS bootloader and OpenCore to play
sounds and signals for screen reading or audible error reporting.
Supported protocols are beep generation and VoiceOver. VoiceOver protocol
is specific to Gibraltar machines (T2) and is not supported before
macOS High Sierra (10.13). Instead older macOS versions use AppleHDA protocol,
which is currently not implemented.
Only one set of audio protocols can be available at a time, so in order
to get audio playback in OpenCore user interface on Mac system implementing some
of these protocols this setting should be enabled.
\emph{Note}: Backend audio driver needs to be configured in \texttt{UEFI Audio}
section for these protocols to be able to stream audio.
\item
\texttt{AppleBootPolicy}\\
\textbf{Type}: \texttt{plist\ boolean}\\
......
Docs/Differences/Differences.tex
浏览文件 @ bbdbb5fe
此差异已折叠。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或