-
Notifications
You must be signed in to change notification settings - Fork 2.1k
/
Configuration.tex
executable file
·8881 lines (7551 loc) · 408 KB
/
Configuration.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[]{article}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{upquote}
\usepackage{microtype}
\usepackage[unicode=true]{hyperref}
\usepackage{longtable,booktabs}
\usepackage{footnote}
\usepackage{listings}
\usepackage{mathtools}
\usepackage{parskip}
\usepackage[margin=0.7in]{geometry}
\usepackage{titlesec}
\usepackage[yyyymmdd,hhmmss]{datetime}
\usepackage{textcomp}
\usepackage{tikz}
\setcounter{tocdepth}{2}
\usetikzlibrary{trees}
\tikzstyle{every node}=[draw=black,thick,anchor=west]
\tikzstyle{selected}=[draw=blue]
\tikzstyle{optional}=[dashed,fill=gray!50]
\renewcommand{\dateseparator}{.}
\makeatletter
\newcommand*{\bdiv}{%
\nonscript\mskip-\medmuskip\mkern5mu%
\mathbin{\operator@font div}\penalty900\mkern5mu%
\nonscript\mskip-\medmuskip
}
\makeatother
% Newer LaTeX versions should not add ligatures to listings, but for some reason
% it is not the case for me. As a result, certain PDF viewers copy wrong data.
\lstdefinestyle{ocbash}{
language=bash,
frame=tb,
columns=fullflexible,
captionpos=b,
basicstyle=\ttfamily\normalsize,
keepspaces=true,
morekeywords={git, make, build, ioreg, grep, nvram, sort, sudo, diskutil, gfxutil, strings, dd, cut, python3},
literate =
{"}{{\textquotedbl}}1
{'}{{\textquotesingle}}1
{-}{{-}}1
{~}{{\texttildelow}}1
{*}{{*}}1
{fl}{{f{}l}}2
{fi}{{f{}i}}2
,
}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
\PassOptionsToPackage{hyphens}{url} % url is loaded by hyperref
\makesavenoteenv{long table} % Fix footnotes in tables
% set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\newcommand{\sectionbreak}{\clearpage}
% Fix spacing for subsections in table of contents.
\makeatletter
\renewcommand{\l@subsection}{\@dottedtocline{2}{1.5em}{2.8em}}
\makeatother
\begin{document}
\begin{titlepage}
\begin{center}
\vspace*{2.0in}
\Huge
\IfFileExists{Logos/Logo.pdf}
{\includegraphics[width=160pt, height=160pt]{Logos/Logo.pdf}}
{\includegraphics[width=160pt, height=160pt]{../Logos/Logo.pdf}}
\sffamily
\textbf{OpenCore}
\vspace{0.2in}
Reference Manual (0.8.0)
\vspace{0.2in}
{[}\today{]}
\normalsize
\vfill
\rmfamily
Copyright \textcopyright 2018-2022 vit9696
\end{center}
\end{titlepage}
\tableofcontents
\section{Introduction}\label{introduction}
This document provides information on the format of the
\href{https://github.com/acidanthera/OpenCorePkg}{OpenCore} user
configuration file used to set up the correct functioning of the macOS
operating system. It is to be read as the official clarification of expected
OpenCore behaviour. All deviations, if found in published OpenCore releases,
shall be considered to be documentation or implementation issues which should be
reported via the \href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}.
An errata sheet is available in
\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/Errata/Errata.pdf}{OpenCorePkg repository}.
This document is structured as a specification and is not meant to provide a step-by-step
guide to configuring an end-user Board Support Package (BSP). The intended audience
of the document is anticipated to be programmers and engineers with a basic understanding of macOS internals
and UEFI functionality. For these reasons, this document is available exclusively in English,
and all other sources or translations of this document are unofficial and may
contain errors.
Third-party articles, utilities, books, and similar, may be more useful for a wider audience as
they could provide guide-like material. However, they are subject to their authors' preferences,
misinterpretations of this document, and unavoidable obsolescence.
In cases of using such sources, such as \href{https://dortania.github.io}{Dortania}'s
\href{https://dortania.github.io/OpenCore-Install-Guide}{OpenCore Install Guide}
and \href{https://dortania.github.io/getting-started}{related material},
please refer back to this document on every decision made and re-evaluate potential implications.
Please note that regardless of the sources used, users are required to fully understand every
OpenCore configuration option, and the principles behind them, before posting issues to the
\href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}.
\emph{Note}: Creating this document would not have been possible without the invaluable
contributions from other people: Andrey1970, Goldfish64, dakanji, PMheart, and several others,
with the full list available in
\href{https://github.com/acidanthera/OpenCorePkg/commits/master/Docs}{OpenCorePkg history}.
\subsection{Generic Terms}\label{generic-terms}
\begin{itemize}
\item
\texttt{plist} --- Subset of ASCII Property List format written in
XML, also know as XML plist format version 1. Uniform Type Identifier
(UTI): \texttt{com.apple.property-list}. Plists consist of
\texttt{plist\ objects}, which are combined to form a hierarchical
structure. Due to plist format not being well-defined, all the
definitions of this document may only be applied after plist is
considered valid by running \texttt{plutil\ -lint}. External
references: https://www.apple.com/DTDs/PropertyList-1.0.dtd,
\texttt{man\ plutil}.
\item
\texttt{plist\ type} --- plist collections (\texttt{plist\ array},
\texttt{plist\ dictionary}, \texttt{plist\ key}) and primitives
(\texttt{plist\ string}, \texttt{plist\ data}, \texttt{plist\ date},
\texttt{plist\ boolean}, \texttt{plist\ integer},
\texttt{plist\ real}).
\item
\texttt{plist\ object} --- definite realisation of
\texttt{plist\ type}, which may be interpreted as value.
\item
\texttt{plist\ array} --- array-like collection, conforms to
\texttt{array}. Consists of zero or more \texttt{plist\ objects}.
\item
\texttt{plist\ dictionary} --- map-like (associative array)
collection, conforms to \texttt{dict}. Consists of zero or more
\texttt{plist\ keys}.
\item
\texttt{plist\ key} --- contains one \texttt{plist\ object} going by
the name of \texttt{plist\ key}, conforms to \texttt{key}. Consists of
printable 7-bit ASCII characters.
\item
\texttt{plist\ string} --- printable 7-bit ASCII string, conforms to
\texttt{string}.
\item
\texttt{plist\ data} --- base64-encoded blob, conforms to
\texttt{data}.
\item
\texttt{plist\ date} --- ISO-8601 date, conforms to \texttt{date},
unsupported.
\item
\texttt{plist\ boolean} --- logical state object, which is either true
(1) or false (0), conforms to \texttt{true} and \texttt{false}.
\item
\texttt{plist\ integer} --- possibly signed integer number in base 10,
conforms to \texttt{integer}. Fits in 64-bit unsigned integer in two's
complement representation, unless a smaller signed or unsigned
integral type is explicitly mentioned in specific
\texttt{plist\ object} description.
\item
\texttt{plist\ real} --- floating point number, conforms to
\texttt{real}, unsupported.
\item
\texttt{plist\ multidata} --- value cast to data by the implementation.
Permits passing \texttt{plist\ string}, in which case the result is
represented by a null-terminated sequence of bytes (C string),
\texttt{plist\ integer}, in which case the result is represented by
\emph{32-bit} little endian sequence of bytes in two's complement
representation, \texttt{plist\ boolean}, in which case the value is
one byte: \texttt{01} for \texttt{true} and \texttt{00} for
\texttt{false}, and \texttt{plist\ data} itself. All other types or
larger integers invoke undefined behaviour.
\end{itemize}
\section{Configuration}\label{configuration-overview}
\subsection{Configuration Terms}\label{configuration-terms}
\begin{itemize}
\item
\texttt{OC\ config} --- OpenCore Configuration file in \texttt{plist}
format named \texttt{config.plist}. It provides an extensible way
to configure OpenCore and is structured to be separated into multiple
named sections situated under the root \texttt{plist\ dictionary}. These
sections may have \texttt{plist\ array} or
\texttt{plist\ dictionary} types and are described in corresponding
sections of this document.
\item
\texttt{valid\ key} --- \texttt{plist\ key} object of
\texttt{OC\ config} described in this document or its future
revisions. Besides explicitly described \texttt{valid\ keys}, keys
starting with the \texttt{\#} symbol (e.g. \texttt{\#Hello}) are also
considered \texttt{valid\ keys} and while they behave as comments, effectively
discarding their values, they are still required to be valid
\texttt{plist\ objects}. All other \texttt{plist\ keys} are not valid,
and their presence results in \texttt{undefined\ behaviour}.
\item
\texttt{valid\ value} --- valid \texttt{plist\ object} of
\texttt{OC\ config} described in this document that matches all the
additional requirements in specific \texttt{plist\ object} descriptions
if any.
\item
\texttt{invalid\ value} --- valid \texttt{plist\ object} of
\texttt{OC\ config} described in this document that is of other
\texttt{plist\ type}, does not conform to additional requirements
found in specific \texttt{plist\ object} descriptions (e.g.~value
range), or missing from the corresponding collection.
\texttt{Invalid\ values} are read with or without an error message as
any possible value of this \texttt{plist\ object} in an undetermined
manner (i.e.~the values may not be same across the reboots). Whilst
reading an \texttt{invalid\ value} is equivalent to reading certain
defined \texttt{valid\ values}, applying incompatible values to the host
system may result in \texttt{undefined\ behaviour}.
\item
\texttt{optional\ value} --- \texttt{valid\ value} of
\texttt{OC\ config} described in this document that reads in a certain
defined manner provided in specific \texttt{plist\ object} description
(instead of \texttt{invalid\ value}) when not present in
\texttt{OC\ config}. All other cases of \texttt{invalid\ value} do
still apply. Unless explicitly marked as \texttt{optional\ value}, any
other value is required to be present and reads to
\texttt{invalid\ value} if missing.
\item
\texttt{fatal\ behaviour} --- behaviour leading to boot termination.
Implementations shall prevent the boot process from continuing until
the host system is restarted. It is permitted, but not required, to
execute cold reboots or to show warning messages in such cases.
\item
\texttt{undefined\ behaviour} --- behaviour not prescribed by this
document. Implementations may take any measures including, but not
limited to, measures associated with \texttt{fatal\ behaviour}, assumptions
of any state or value, or disregarding any associated states or values. This is
however subject to such measures not negatively impacting upon system integrity.
\end{itemize}
\subsection{Configuration Processing}\label{configuration-processing}
The \texttt{OC\ config} file is guaranteed to be processed at least once if found.
Subject to the OpenCore bootstrapping mechanism, the presence of multiple
\texttt{OC\ config} files may lead to the reading of any of them. It is
permissible for no \texttt{OC\ Config} file to be present on disk. In such cases,
if the implementation does not abort the boot process, all values shall follow the
rules of \texttt{invalid\ values} and \texttt{optional\ values}.
The \texttt{OC\ config} file has restrictions on size, nesting levels, and number of keys:
\begin{itemize}
\tightlist
\item
The \texttt{OC\ config} file size shall not exceed \texttt{32\ MBs}.
\item
The \texttt{OC\ config} file shall not have more than \texttt{32} nesting levels.
\item
The \texttt{OC\ config} file may have up to \texttt{32,768} XML nodes within
each \texttt{plist\ object}.
\begin{itemize}
\tightlist
\item One \texttt{plist\ dictionary} item is counted as a pair of nodes
\end{itemize} \medskip
\end{itemize}
Reading malformed \texttt{OC\ config} files results in
\texttt{undefined\ behaviour}. Examples of malformed \texttt{OC\ config} files
include the following:
\begin{itemize}
\tightlist
\item
\texttt{OC\ config} files that do not conform to \texttt{DTD PLIST 1.0}.
\item
\texttt{OC\ config} files with unsupported or non-conformant \texttt{plist\ objects} found
in this document.
\item
\texttt{OC\ config} files violating restrictions on size, nesting levels, and number of keys.
\end{itemize}
It is recommended, but not required, to abort loading malformed
\texttt{OC\ config} files and to continue as if an \texttt{OC\ config} file is
not present. For forward compatibility, it is recommended, but not required,
for the implementation to warn about the use of \texttt{invalid\ values}.
The recommended approach to interpreting \texttt{invalid\ values}
is to conform to the following convention where applicable:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Type} & \textbf{Value} \\
\hline
\texttt{plist\ string} & Empty string
(\texttt{\textless{}string\textgreater{}\textless{}/string\textgreater{}}) \\
\hline
\texttt{plist\ data} & Empty data
(\texttt{\textless{}data\textgreater{}\textless{}/data\textgreater{}}) \\
\hline
\texttt{plist\ integer} & 0
(\texttt{\textless{}integer\textgreater{}0\textless{}/integer\textgreater{}}) \\
\hline
\texttt{plist\ boolean} & False
(\texttt{\textless{}false/\textgreater{}}) \\
\hline
\texttt{plist\ tristate} & False
(\texttt{\textless{}false/\textgreater{}}) \\
\hline
\end{tabular}
\end{center}
\subsection{Configuration Structure}\label{configuration-structure}
The \texttt{OC\ config} file is separated into subsections, as described in
separate sections of this document, and is designed so as to attempt not to
enable anything by default as well as to provide kill switches via an \texttt{Enable}
property for \texttt{plist dict} entries that represent optional plugins and similar.
The file is structured to group related elements in subsections as follows:
\begin{itemize}
\tightlist
\item
\texttt{Add} provides support for data addition. Existing data will
not be overridden, and needs to be handled separately with
\texttt{Delete} if necessary.
\item
\texttt{Delete} provides support for data removal.
\item
\texttt{Patch} provides support for data modification.
\item
\texttt{Quirks} provides support for specific workarounds.
\end{itemize}
Root configuration entries consist of the following:
\begin{itemize}
\tightlist
\item
\hyperref[acpi]{\texttt{ACPI}}
\item
\hyperref[booter]{\texttt{Booter}}
\item
\hyperref[devprops]{\texttt{DeviceProperties}}
\item
\hyperref[kernel]{\texttt{Kernel}}
\item
\hyperref[misc]{\texttt{Misc}}
\item
\hyperref[nvram]{\texttt{NVRAM}}
\item
\hyperref[platforminfo]{\texttt{PlatformInfo}}
\item
\hyperref[uefi]{\texttt{UEFI}}
\end{itemize}
Basic validation of an \texttt{OC\ config} file is possible using
the \texttt{ocvalidate} utility. Please note that the version of \texttt{ocvalidate}
used must match the OpenCore release and that nothwithstanding this, it may not
detect all configuration issues present in an \texttt{OC\ config} file.
\emph{Note}: To maintain system integrity, properties typically have predefined values even
when such predefined values are not specified in the \texttt{OC\ config} file. However, all
properties must be explicitly specified in the \texttt{OC\ config} file and this behaviour
should not be relied on.
\section{Setup}\label{setup-overview}
\subsection{Directory Structure}\label{directory-structure}
\begin{center}
\begin{tikzpicture}[%
grow via three points={one child at (0.5,-0.6) and
two children at (0.5,-0.6) and (0.5,-1.2)},
edge from parent path={(\tikzparentnode.south) |- (\tikzchildnode.west)}]
\node {ESP}
child { node {EFI}
child { node {BOOT}
child { node [selected] {BOOTx64.efi}}
}
child [missing] {}
child { node {OC}
child { node {ACPI}
child { node [optional] {DSDT.aml}}
child { node [optional] {SSDT-1.aml}}
child { node [optional] {MYTABLE.aml}}
}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child { node {Drivers}
child { node [optional] {MyDriver.efi}}
child { node [optional] {OtherDriver.efi}}
}
child [missing] {}
child [missing] {}
child { node {Kexts}
child { node [optional] {MyKext.kext}}
child { node [optional] {OtherKext.kext}}
}
child [missing] {}
child [missing] {}
child { node [optional] {Resources}
child { node [optional] {Audio}}
child { node [optional] {Font}}
child { node [optional] {Image}}
child { node [optional] {Label}}
}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child { node {Tools}
child { node [optional] {Tool.efi}}
}
child [missing] {}
child { node [selected] {OpenCore.efi}}
child { node {config.plist}}
child { node [optional] {vault.plist}}
child { node [optional] {vault.sig}}
}
}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child [missing] {}
child { node {Kernels}
child { node [optional] {kernel}}
child { node [optional] {kernelcache}}
child { node [optional] {prelinkedkernel}}
}
child [missing] {}
child [missing] {}
child [missing] {}
child { node [optional] {boot}}
child { node [optional] {nvram.plist}}
child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}}
child { node [optional] {panic-YYYY-MM-DD-HHMMSS.txt}}
child { node [optional] {SysReport}}
;
\end{tikzpicture}
\break
\label{fig:DS}
Figure 1. Directory Structure
\end{center}
When directory boot is used, the directory structure used should follow
the descriptions in the \hyperref[fig:DS]{Directory Structure} figure.
Available entries include:
\begin{itemize}
\tightlist
\item
\texttt{BOOTx64.efi} or \texttt{BOOTIa32.efi} \\
Initial bootstrap loaders, which load \texttt{OpenCore.efi}. \texttt{BOOTx64.efi}
is loaded by the firmware by default consistent with the UEFI specification. However,
it may also be renamed and put in a custom location to allow OpenCore coexist alongside
operating systems, such as Windows, that use \texttt{BOOTx64.efi} files as their loaders.
Refer to the \texttt{LauncherOption} property for details.
\item
\texttt{boot} \\
Duet bootstrap loader, which initialises the UEFI environment on legacy BIOS firmware
and loads \texttt{OpenCore.efi} similarly to other bootstrap loaders. A modern Duet
bootstrap loader will default to \texttt{OpenCore.efi} on the same partition when
present.
\item
\texttt{ACPI} \\
Directory used for storing supplemental ACPI information
for the \hyperref[acpi]{\texttt{ACPI}} section.
\item
\texttt{Drivers} \\
Directory used for storing supplemental \texttt{UEFI}
drivers for \hyperref[uefi]{\texttt{UEFI}} section.
\item
\texttt{Kexts} \\
Directory used for storing supplemental kernel information
for the \hyperref[kernel]{\texttt{Kernel}} section.
\item
\texttt{Resources} \\
Directory used for storing media resources such as audio files
for screen reader support. Refer to the \hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}}
section for details. This directory also contains image files
for graphical user interface. Refer to the \hyperref[ueficanopy]{OpenCanopy} section for details.
\item
\texttt{Tools} \\
Directory used for storing supplemental tools.
\item
\texttt{OpenCore.efi} \\
Main booter application responsible for operating system loading. The directory
\texttt{OpenCore.efi} resides in is called the \texttt{root directory}, which is
set to \texttt{EFI\textbackslash OC} by default. When launching \texttt{OpenCore.efi}
directly or through a custom launcher however, other directories containing
\texttt{OpenCore.efi} files are also supported.
\item
\texttt{config.plist} \\
\texttt{OC Config}.
\item
\texttt{vault.plist} \\
Hashes for all files potentially loadable by \texttt{OC Config}.
\item
\texttt{vault.sig} \\
Signature for \texttt{vault.plist}.
\item
\texttt{SysReport} \\
Directory containing system reports generated by \texttt{SysReport} option.
\item
\texttt{nvram.plist} \\
OpenCore variable import file.
\item
\texttt{opencore-YYYY-MM-DD-HHMMSS.txt} \\
OpenCore log file.
\item
\texttt{panic-YYYY-MM-DD-HHMMSS.txt} \\
Kernel panic log file.
\end{itemize}
\emph{Note}: It is not guaranteed that paths longer than
\texttt{OC\_STORAGE\_SAFE\_PATH\_MAX} (128 characters including
the \texttt{\\0}-terminator) will be accessible within OpenCore.
\subsection{Installation and Upgrade}\label{configuration-install}
To install OpenCore, replicate the
\hyperref[configuration-structure]{Configuration Structure} described
in the previous section in the EFI volume of a GPT partition. While
corresponding sections of this document provide some information
regarding external resources such as ACPI tables, UEFI drivers,
or kernel extensions (kexts), completeness of the matter is out of
the scope of this document. Information about kernel extensions may
be found in a separate
\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/Kexts.md}{Kext List}
document available in the OpenCore repository. Vaulting information is provided in
the \hyperref[miscsecurityprops]{Security Properties} section of this document.
The \texttt{OC\ config} file, as with any property list file, can be edited with
any text editor, such as nano or vim. However, specialised software
may provide a better experience. On macOS, the preferred GUI application is
\href{https://developer.apple.com/xcode}{Xcode}. The
\href{https://github.com/corpnewt/ProperTree}{ProperTree} editor
is a lightweight, cross-platform and open-source alternative.
It is strongly recommended to avoid configuration creation tools that are aware of the
internal configuration structure as this may result in invalid configurations (since the
structure gets constantly updated). If such tools are to be used despite this warning,
ensure that only stable versions of OpenCore explicitly supported by such tools are used.
In such cases, the use of open-source implementations with transparent binary generation
(such as \href{https://github.com/ic005k/QtOpenCoreConfig}{OCAT}) is encouraged, given
that other tools may contain malware. In addition, configurations created for a specific
hardware setup should never be used on different hardware setups.
For BIOS booting, a third-party UEFI environment provider is required and
\texttt{OpenDuetPkg} is one such UEFI environment provider for legacy systems.
To run OpenCore on such a legacy system, \texttt{OpenDuetPkg} can be installed
with a dedicated tool --- BootInstall (bundled with OpenCore).
\href{https://github.com/corpnewt/gibMacOS}{Third-party utilities} can be used
to perform this on systems other than macOS.
For upgrade purposes, refer to the \texttt{Differences.pdf} document which provides
information about changes to the configuration (as compared to the previous release)
as well as to the \texttt{Changelog.md} document (which contains a list of
modifications across all published updates).
\subsection{Contribution}\label{configuration-comp}
OpenCore can be compiled as a standard
\href{https://github.com/tianocore/tianocore.github.io/wiki/EDK-II}{EDK II}
package and requires the
\href{https://github.com/tianocore/tianocore.github.io/wiki/EDK-II#stable-tags}{EDK II Stable}
package. The currently supported EDK II release is hosted in
\href{https://github.com/acidanthera/audk}{acidanthera/audk}. Required patches
for this package can be found in the \texttt{Patches} directory.
When updating the LaTeX documentation (e.g. \texttt{Configuration.tex}) please
do \textit{not} rebuild the PDF files till merging to master happens. This avoids
unnecessary merge conflicts:
\begin{itemize}
\tightlist
\item External contributors using the pull-request approach should request
the maintainers to handle the PDF rebuild in the pull-request message.
\item Internal contributors should rebuild the documentation at merge time
in the same or in a separate commit. One can ask another maintainer to
rebuild the documentation when lacking the necessary tools
in the pull-request message.
\end{itemize}
The only officially supported toolchain is \texttt{XCODE5}. Other toolchains
might work but are neither supported nor recommended. Contributions of clean
patches are welcome. Please do follow
\href{https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C}{EDK II C Codestyle}.
To compile with \texttt{XCODE5}, besides \href{https://developer.apple.com/xcode}{Xcode},
users should also install \href{https://www.nasm.us}{NASM} and
\href{https://github.com/acidanthera/ocbuild/tree/master/external}{MTOC}.
The latest Xcode version is recommended for use despite the toolchain name.
An example command sequence is as follows:
\begin{lstlisting}[caption=Compilation Commands, label=compile, style=ocbash]
git clone --depth=1 https://github.com/acidanthera/audk UDK
cd UDK
git submodule update --init --recommend-shallow
git clone --depth=1 https://github.com/acidanthera/OpenCorePkg
. ./edksetup.sh
make -C BaseTools
build -a X64 -b RELEASE -t XCODE5 -p OpenCorePkg/OpenCorePkg.dsc
\end{lstlisting}
For IDE usage Xcode projects are available in the root of the repositories. Another
approach could be using \href{https://microsoft.github.io/language-server-protocol}{Language Server Protocols}. For example, \href{https://www.sublimetext.com}{Sublime Text} with
\href{https://lsp.sublimetext.io}{LSP for Sublime Text} plugin.
Add \texttt{compile\_flags.txt} file with similar content to the UDK root:
\begin{lstlisting}[caption=ECC Configuration, label=eccfile, style=ocbash]
-I/UefiPackages/MdePkg
-I/UefiPackages/MdePkg/Include
-I/UefiPackages/MdePkg/Include/X64
-I/UefiPackages/MdeModulePkg
-I/UefiPackages/MdeModulePkg/Include
-I/UefiPackages/MdeModulePkg/Include/X64
-I/UefiPackages/OpenCorePkg/Include/AMI
-I/UefiPackages/OpenCorePkg/Include/Acidanthera
-I/UefiPackages/OpenCorePkg/Include/Apple
-I/UefiPackages/OpenCorePkg/Include/Apple/X64
-I/UefiPackages/OpenCorePkg/Include/Duet
-I/UefiPackages/OpenCorePkg/Include/Generic
-I/UefiPackages/OpenCorePkg/Include/Intel
-I/UefiPackages/OpenCorePkg/Include/Microsoft
-I/UefiPackages/OpenCorePkg/Include/Nvidia
-I/UefiPackages/OpenCorePkg/Include/VMware
-I/UefiPackages/OvmfPkg/Include
-I/UefiPackages/ShellPkg/Include
-I/UefiPackages/UefiCpuPkg/Include
-IInclude
-include
/UefiPackages/MdePkg/Include/Uefi.h
-fshort-wchar
-Wall
-Wextra
-Wno-unused-parameter
-Wno-missing-braces
-Wno-missing-field-initializers
-Wno-tautological-compare
-Wno-sign-compare
-Wno-varargs
-Wno-unused-const-variable
-DOC_TARGET_NOOPT=1
-DNO_MSABI_VA_FUNCS=1
\end{lstlisting}
\emph{Note}: \texttt{/UefiPackages} in the sample file denotes an absolute path.
\textbf{Warning}: Tool developers modifying \texttt{config.plist} or any other OpenCore
files must ensure that their tools check the \texttt{opencore-version} NVRAM variable
(see the \hyperref[miscdebugprops]{Debug Properties} section below) and warn users
if the version listed is unsupported or prerelease. The OpenCore configuration may change
across releases and such tools shall ensure that they carefully follow this document. Failure
to do so may result in such tools being considered to be malware and blocked by any means.
\subsection{Coding conventions}\label{configuration-conv}
As with any other project, we have conventions that we follow during development.
All third-party contributors are advised to adhere to the conventions listed below
before submitting patches. To minimise abortive work and the potential rejection of
submissions, third-party contributors should initially raise issues to the
\href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}
for feedback before submitting patches.
\textbf{Organisation}. The codebase is contained in the \texttt{OpenCorePkg} repository,
which is the primary EDK II package.
\begin{itemize}
\tightlist
\item Whenever changes are required in multiple repositories, separate pull requests should
be sent to each.
\item Committing the changes should happen firstly to dependent repositories, secondly to
primary repositories to avoid automatic build errors.
\item Each unique commit should compile with \texttt{XCODE5} and preferably with other
toolchains. In the majority of the cases it can be checked by accessing the
\href{https://travis-ci.com/acidanthera}{CI interface}. Ensuring that static analysis finds
no warnings is preferred.
\item External pull requests and tagged commits must be validated. That said, commits in
master may build but may not necessarily work.
\item Internal branches should be named as follows: \texttt{author-name-date}, e.g.
\texttt{vit9696-ballooning-20191026}.
\item Commit messages should be prefixed with the primary module (e.g. library or code module) the
changes were made in. For example, \texttt{OcGuardLib: Add OC\_ALIGNED macro}. For non-library changes
\texttt{Docs} or \texttt{Build} prefixes are used.
\end{itemize}
\textbf{Design}. The codebase is written in a subset of freestanding C11 (C17) supported by
most modern toolchains used by EDK II. Applying common software development practices or requesting
clarification is recommended if any particular case is not discussed below.
\begin{itemize}
\tightlist
\item Never rely on undefined behaviour and try to avoid implementation defined behaviour unless
explicitly covered below (feel free to create an issue when a relevant case is not present).
\item Use \texttt{OcGuardLib} to ensure safe integral arithmetics avoiding overflows. Unsigned
wraparound should be relied on with care and reduced to the necessary amount.
\item Check pointers for correct alignment with \texttt{OcGuardLib} and do not rely on the architecture
being able to dereference unaligned pointers.
\item Use flexible array members instead of zero-length or one-length arrays where necessary.
\item Use static assertions (\texttt{STATIC\_ASSERT}) for type and value assumptions, and runtime
assertions (\texttt{ASSERT}) for precondition and invariant sanity checking. Do not use runtime
assertions to check for errors as they should never alter control flow and potentially be excluded.
\item Assume \texttt{UINT32}/\texttt{INT32} to be \texttt{int}-sized and use \texttt{\%u},
\texttt{\%d}, and \texttt{\%x} to print them.
\item Assume \texttt{UINTN}/\texttt{INTN} to be of unspecified size, and cast them to
\texttt{UINT64}/\texttt{INT64} for printing with \texttt{\%Lu}, \texttt{\%Ld} and so on as normal.
\item Do not rely on integer promotions for numeric literals. Use explicit casts when the type is
implementation-dependent or suffixes when type size is known. Assume \texttt{U} for \texttt{UINT32}
and \texttt{ULL} for \texttt{UINT64}.
\item Do ensure unsigned arithmetics especially in bitwise maths, shifts in particular.
\item \texttt{sizeof} operator should take variables instead of types where possible to be error prone.
Use \texttt{ARRAY\_SIZE} to obtain array size in elements. Use \texttt{L\_STR\_LEN} and
\texttt{L\_STR\_SIZE} macros from \texttt{OcStringLib} to obtain string literal sizes to ensure compiler
optimisation.
\item Do not use \texttt{goto} keyword. Prefer early \texttt{return}, \texttt{break}, or \texttt{continue}
after failing to pass error checking instead of nesting conditionals.
\item Use \texttt{EFIAPI}, force UEFI calling convention, only in protocols, external callbacks between
modules, and functions with variadic arguments.
\item Provide inline documentation to every added function, at least describing its inputs, outputs,
precondition, postcondition, and giving a brief description.
\item Do not use \texttt{RETURN\_STATUS}. Assume \texttt{EFI\_STATUS} to be a matching superset that is
to be always used when \texttt{BOOLEAN} is not enough.
\item Security violations should halt the system or cause a forced reboot.
\end{itemize}
\textbf{Codestyle}. The codebase follows the
\href{https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C}{EDK II codestyle}
with a few changes and clarifications.
\begin{itemize}
\tightlist
\item Write inline documentation for the functions and variables only once: in headers, where a header prototype
is available, and inline for \texttt{static} variables and functions.
\item Use line length of 120 characters or less, preferably 100 characters.
\item Use spaces after casts, e.g. \texttt{(VOID *)(UINTN) Variable}.
\item Use two spaces to indent function arguments when splitting lines.
\item Prefix public functions with either \texttt{Oc} or another distinct name.
\item Do not prefix private \texttt{static} functions, but prefix private \texttt{non-static} functions with \texttt{Internal}.
\item Use SPDX license headers as shown in
\href{https://github.com/acidanthera/bugtracker/issues/483}{acidanthera/bugtracker\#483}.
\end{itemize}
\subsection{Debugging}\label{configuration-debug}
The codebase incorporates EDK II debugging and few custom features to improve the experience.
\begin{itemize}
\tightlist
\item Use module prefixes, 2-5 letters followed by a colon (\texttt{:}), for debug messages. For \texttt{OpenCorePkg}
use \texttt{OC:}, for libraries and drivers use their own unique prefixes.
\item Do not use dots (\texttt{.}) in the end of debug messages and separate \texttt{EFI\_STATUS}, printed by
\texttt{\%r}, with a hyphen (e.g. \texttt{OCRAM: Allocation of \%u bytes failed - \%r\textbackslash n}).
\item Use \texttt{DEBUG\_CODE\_BEGIN ()} and \texttt{DEBUG\_CODE\_END ()} constructions to guard debug checks
that may potentially reduce the performance of release builds and are otherwise unnecessary.
\item Use \texttt{DEBUG} macro to print debug messages during normal functioning, and \texttt{RUNTIME\_DEBUG} for
debugging after \texttt{EXIT\_BOOT\_SERVICES}.
\item Use \texttt{DEBUG\_VERBOSE} debug level to leave debug messages for future debugging of the code, which
are currently not necessary. By default \texttt{DEBUG\_VERBOSE} messages are ignored even in \texttt{DEBUG} builds.
\item Use \texttt{DEBUG\_INFO} debug level for all non critical messages (including errors)
and \texttt{DEBUG\_BULK\_INFO}
for extensive messages that should not appear in NVRAM log that is heavily limited in size.
These messages are ignored in \texttt{RELEASE} builds.
\item Use \texttt{DEBUG\_ERROR} to print critical human visible messages that may potentially halt the boot process,
and \texttt{DEBUG\_WARN} for all other human visible errors, \texttt{RELEASE} builds included.
\end{itemize}
The \href{https://git-scm.com/docs/git-bisect}{\texttt{git-bisect}} functionality may be useful when trying
to find problematic changes. Unofficial sources of \texttt{per-commit} OpenCore binary builds,
such as \href{https://dortania.github.io/builds}{Dortania}, may also be useful.
\section{ACPI}\label{acpi}
\subsection{Introduction}\label{acpiintro}
ACPI (Advanced Configuration and Power Interface) is an open standard to
discover and configure computer hardware.
The \href{https://uefi.org/specifications}{ACPI specification} defines
standard tables (e.g.~\texttt{DSDT}, \texttt{SSDT}, \texttt{FACS}, \texttt{DMAR})
and various methods (e.g. \texttt{\_DSM}, \texttt{\_PRW}) for implementation.
Modern hardware needs few changes to maintain ACPI compatibility and some
options for such changes are provided as part of OpenCore.
To compile and disassemble ACPI tables, the \href{https://github.com/acpica/acpica}{iASL compiler}
developed by \href{https://www.acpica.org}{ACPICA} can be used. A GUI front-end to iASL compiler
can be downloaded from \href{https://github.com/acidanthera/MaciASL/releases}{Acidanthera/MaciASL}.
ACPI changes apply globally (to every operating system) with the following effective order:
\begin{itemize}
\tightlist
\item \texttt{Patch} is processed.
\item \texttt{Delete} is processed.
\item \texttt{Add} is processed.
\item \texttt{Quirks} are processed.
\end{itemize}
Applying the changes globally resolves the problems of incorrect operating system
detection (consistent with the ACPI specification, not possible before the operating
system boots), operating system chainloading, and difficult ACPI debugging. Hence,
more attention may be required when writing changes to \texttt{\_OSI}.
Applying the patches early makes it possible to write so called ``proxy'' patches,
where the original method is patched in the original table and is implemented in
the patched table.
There are several sources of ACPI tables and workarounds. Commonly used
ACPI tables are provided with OpenCore, VirtualSMC, VoodooPS2, and WhateverGreen
releases. Besides those, several third-party instructions may be found on
the AppleLife \href{https://applelife.ru/forums/xakintosh.67}{Laboratory}
and \href{https://applelife.ru/forums/dsdt.129}{DSDT} subforums
(e.g. \href{https://applelife.ru/posts/498967}{Battery register splitting} guide).
A slightly more user-friendly explanation of some tables included with OpenCore
can also be found in \href{https://dortania.github.io}{Dortania}'s
\href{https://dortania.github.io/Getting-Started-With-ACPI}{Getting started with ACPI} guide.
For more exotic cases, there are several alternatives such as
\href{https://github.com/daliansky}{daliansky}'s
\href{https://github.com/daliansky/OC-little}{ACPI sample collection}
(\href{https://github.com/5T33Z0/OC-Little-Translated}{English Translation by 5T33Z0 et al}).
Please note however, that suggested solutions from third parties may be outdated or may contain errors.
\subsection{Properties}\label{acpiprops}
\begin{enumerate}
\item
\texttt{Add}\\
\textbf{Type}: \texttt{plist\ array}\\
\textbf{Failsafe}: Empty\\
\textbf{Description}: Load selected tables from the \texttt{OC/ACPI}
directory.
To be filled with \texttt{plist\ dict} values, describing each add entry.
Refer to the \hyperref[acpipropsadd]{Add Properties} section below for details.
\item
\texttt{Delete}\\
\textbf{Type}: \texttt{plist\ array}\\
\textbf{Failsafe}: Empty\\
\textbf{Description}: Remove selected tables from the ACPI stack.
To be filled with \texttt{plist\ dict} values, describing each delete entry.
Refer to the \hyperref[acpipropsdelete]{Delete Properties} section below for details.
\item
\texttt{Patch}\\
\textbf{Type}: \texttt{plist\ array}\\
\textbf{Failsafe}: Empty\\
\textbf{Description}: Perform binary patches in ACPI tables before
table addition or removal.
To be filled with \texttt{plist\ dictionary} values describing each patch entry.
Refer to the \hyperref[acpipropspatch]{Patch Properties} section below for details.
\item
\texttt{Quirks}\\
\textbf{Type}: \texttt{plist\ dict}\\
\textbf{Description}: Apply individual ACPI quirks described
in the \hyperref[acpipropsquirks]{Quirks Properties} section below.
\end{enumerate}
\subsection{Add Properties}\label{acpipropsadd}
\begin{enumerate}
\item
\texttt{Comment}\\
\textbf{Type}: \texttt{plist\ string}\\
\textbf{Failsafe}: Empty\\
\textbf{Description}: Arbitrary ASCII string used to provide human readable
reference for the entry. Whether this value is used is implementation defined.
\item
\texttt{Enabled}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Set to \texttt{true} to add this ACPI table.
\item
\texttt{Path}\\
\textbf{Type}: \texttt{plist\ string}\\
\textbf{Failsafe}: Empty\\
\textbf{Description}: File paths meant to be loaded as ACPI tables.
Example values include \texttt{DSDT.aml}, \texttt{SubDir/SSDT-8.aml},
\texttt{SSDT-USBX.aml}, etc.
The ACPI table load order follows the item order in the array. ACPI tables
are loaded from the \texttt{OC/ACPI} directory.
\textbf{Note}: All tables apart from tables with a \texttt{DSDT} table identifier
(determined by parsing data, not by filename) insert new tables into the ACPI stack.
\texttt{DSDT} tables perform a replacement of DSDT tables instead.
\end{enumerate}
\subsection{Delete Properties}\label{acpipropsdelete}
\begin{enumerate}
\item
\texttt{All}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false} (Only delete the first matched table)\\
\textbf{Description}: Set to \texttt{true} to delete all ACPI tables matching the
condition.
\item
\texttt{Comment}\\
\textbf{Type}: \texttt{plist\ string}\\
\textbf{Failsafe}: Empty\\
\textbf{Description}: Arbitrary ASCII string used to provide human readable
reference for the entry. Whether this value is used is implementation defined.
\item
\texttt{Enabled}\\
\textbf{Type}: \texttt{plist\ boolean}\\
\textbf{Failsafe}: \texttt{false}\\
\textbf{Description}: Set to \texttt{true} to remove this ACPI table.
\item
\texttt{OemTableId}\\
\textbf{Type}: \texttt{plist\ data}, 8 bytes\\
\textbf{Failsafe}: All zero (Match any table OEM ID)\\
\textbf{Description}: Match table OEM ID equal to this value.
\item
\texttt{TableLength}\\
\textbf{Type}: \texttt{plist\ integer}\\
\textbf{Failsafe}: \texttt{0} (Match any table size)\\
\textbf{Description}: Match table size equal to this value.
\item
\texttt{TableSignature}\\
\textbf{Type}: \texttt{plist\ data}, 4 bytes\\
\textbf{Failsafe}: All zero (Match any table signature)\\
\textbf{Description}: Match table signature equal to this value.
\emph{Note}: Do not use table signatures when the sequence
must be replaced in multiple places. This is particularly relevant
when performing different types of renames.
\end{enumerate}
\subsection{Patch Properties}\label{acpipropspatch}