Clover v.2 Instructions

[Slice]

Deprecated features

 

Since Clover v2.4k some technologies will be deprecated, no more supported and will be excluded in future releases.

1. Clover 32bit.   Good bye Clover-32 

2. LegacyBoot. (PBR, PBRTest, PBRSata etc). This is a technology to boot Windows XP from CloverGUI.

It's a pity it rarely works. For my observation the success was only on PATA controllers at ICH7 chipset.

I will recommend to update your Windows  to UEFI one. At least Windows 7-64bit which successfully works on Core2Duo computers 10years old.

I don't think I should bother about more ancient one.

As well the good solution in using Chameleon which boots Windows XP very well.

- install boot1f32alt bootsector which wait 2sec for key press.

- install boot as Clover and boot1 as Chameleon.

- press "1" during boot to switch to Chameleon and boot WindowsXP from him.

3. Installation on Fdisk Partitioning Scheme HDD (also known as MBR table).

I will recommend always format your drive to Guid Partitioning Sheme (also known as GPT). You can install here Windows in UEFI mode even if your computer is PC BIOS based using legacy CloverEFI. (see comp#4 in my signature).

Instructions Post#46 How to install Windows UEFI

4. ATIConnectors patch.

It's a pity this patch can't be OS dependent.

See, for example, connectors for 10.11

Personality: Pithecia
ConnectorInfo count in decimal: 3
Disk offset in decimal 176512
00040000040300000001000021030204 - Dp
04000000140200000001000000000403 - DVI
10000000100000000001000000000001 - VGA

and for 10.12

Pithecia (2) @ 0x1b54e0
DP, DDVI
000400000403000000010000000000002103020400000000
040000001402000000010000000000000000040300000000

So, you should migrate your existing patch from the old form

		<key>#ATIConnectorsController</key>
		<string>6000</string>
		<key>#ATIConnectorsData</key>
		<string>000400000403000000010000210302040400000014020000000100000000040310000000100000000001000000000001</string>
		<key>#ATIConnectorsPatch</key>
		<string>040000001402000000010000000004040004000004030000000100001102010500000000000000000000000000000000</string>

To new form KextPatches

This way you can create several patches for different OSes.

10.6-10.7  ATI6000Controller

10.8-10.12 AMD6000Controller

And different find/replace strings for 10.12

 

5. OldWay DSDT patches.

Since rev4006 the parameter NewWay is excluded.  #52 

It is always NewWay now.

[Slice]

Using  UDK2018

 

We can compile Clover with UDK2018 and not bother about EDK2 beta updates.

Step by step from clear.

1. Install macOS. Preferably 10.13.x at this moment

2. Install Xcode. I am using Xcode 9.3.1 now. Install Command Line Tools. Xcode 10.1 in 10.13.6 is better.

3. Download NASM https://www.nasm.us/pub/nasm/releasebuilds/2.13.03/macosx/nasm-2.13.03-macosx.zip, unpack  and copy to     /opt/local/bin

The folder may be invisible then

sudo chflags nohidden /opt

or it may not exists then

sudo mkdir -p /opt/local/bin

then

sudo cp ~/Downloads/nasm-2.13.03/nasm /opt/local/bin

4. Prepare sources

cd ~
mkdir src
cd src
git clone https://github.com/tianocore/edk2 -b UDK2018 --depth 1 UDK2018
cd UDK2018
svn co svn://svn.code.sf.net/p/cloverefiboot/code/ Clover
make -C BaseTools/Source/C
./edksetup.sh
cd Clover
./buildgettext.sh
./buildmtoc.sh
cp -R Patches_for_UDK2018/* ../
./ebuild.sh -fr

 

Patches_for_EDK2 revision 4472 is compatible with UDK2018, but there is own patch set.

Since 4486 we should use Patches_for_UDK2018.

 

5. And finally create installer

cd ~/src/UDK2018/Clover/CloverPackage/
./makepkg

 

DEPRECATED!

Since moving to GitHub we need no more UDK2018 or EDK2. All those sources included into the Clover repo and we will improve them own way.

 

[Slice]

Device Properties

This is Apple's protocol since many years to provide information from AppleEFI to macOS about used deviced. It is obligatory and present in all hackintosh bootloaders.

The information can be provided also by _DSM methods since OSX 10.5. But ACPI method will work after kernel started and after AppleACPIPlatform started and so may depend on its version. DPProtocol works before kernel and inject properties at boot.efi time.

 

Historically Clover has several methods to fill the database of Device Properties.

1. There is just hex-string injection that can be manually constructed by gfx-util. Not convenience.

2. There are automatic injections or Graphics card, LAN, Sound and USB devices. It is very convenient but very questionable by final results. There are many properties that should be injected or no and we are not sure what values must be injected versus Clover choice.

3. To resolve these question two setting added "NoDefaultProperties" and "AddProperties". This way smart people can cancel all automatically injected properties and inject own properties. This way is not very good as devices chosen by nickname "ATI", "Nvidia", "LAN" etc. which not assumed present of two different videocard, for example, or similar videocards but required different properties.

4. More advanced way is "Arbitrary" properties when you can inject all properties you want for a device chosen by its PCI address. The address of the device is set as 08:00:00. But this is the fault of the method. The bus number (08 in this example) may changed with BIOS changed or with new device inserted. As well this is hard to set device address of device at second bridge (bridge after bridge).

5. More correct way is introduced in Clover since 4497 revision. This is XML dictionary as it created by gfx-util.

Example

    <key>Properties</key>
    <dict>
      <key>PciRoot(0x0)/Pci(0x14,0x0)</key>
      <dict>
        <key>AAPL,clock-id</key>
        <data>AA==</data>
        <key>AAPL,current-available</key>
        <data>sAQ=</data>
        <key>AAPL,current-extra</key>
        <data>vAI=</data>
        <key>AAPL,current-in-sleep</key>
        <data>6AM=</data>
        <key>built-in</key>
        <data>AA==</data>
        <key>device_type</key>
        <string>XHCI</string>
      </dict>
      <key>PciRoot(0x0)/Pci(0x19,0x0)</key>
      <dict>
        <key>built-in</key>
        <data>AQ==</data>
      </dict>

Compared to old and buggy gfxutil Clover also accepted <integer> and </true> </false> types of values. As well you may see <data> array when you know there is <string>.

This method allows you to use properties found in DarwinDumps of real Macs just by copy/paste into your config.plist

 

How to convert your old config.plist to new method of injection?

 

1. Boot macOS with your old Clover and old config.plist.  Assumed there is full success.

2. Use clover-genconfig utility (rev >4508) to produce config-imprint.plist with all properties you previously use by methods 1-4.

$ clover-genconfig > config-imprint.plist

3. Use any editor to copy data from imprint to you working config.plist to make your new config.plist. You have to find

Device->Properties dictionary and make a full copy of it.

4. Then you should switch off any other injection by methods 1-4.

Graphics->Inject->ATI,NVIDIA,Intel=NO

Devices->USB->Inject=NO

Devices->LANInjection=NO

Devices->HDAInjection=NO

Devices->HDMIInjection=NO

AddProperties -> #AddProperties

Arbitrary -> #Arbitrary

5. Install Clover 4497 or up.

6. You may also add new properties to this array by the given sample.

7. Reboot.

8 During reboot you can enter Options menu -> PCI Devices -> Custom and see all properties you may inject. This is good time to enable or disable some of the properties.

 

To temporary disable a property in the config place # sign at the start of the key

<key>#AAPL,clock-id</key>

 

To write a comment to the device you may insert pair

        <key>#Comment</key>
        <string>This is XHCI device</string>

 

There is one special case "ig-platform-id".

To have an ability to change a value of the property Clover gives you an additional setting

  <key>Graphics</key>
  <dict>
    <key>ig-platform-id</key>
    <string>0x01660003</string>

This value will be present in Options menu -> Graphics and changeable here. New value will replace the value from the Properties dictionary.

 

EDITED

Clover-genconfig must be exactly same revision as clover which boot the system. So instructions updated

1. Boot macOS with your old Clover and old config.plist.  Assumed there is full success. ->

1. Install new Clover and boot with old config.plist

 

[Slice]

Scalable Themes

 

The purpose of this new feature is to make Clover GUI looks similar with resolutions 800x600, 1920x1080 or 5k. Existing PNG themes will be too large on small screen or too small on large screen.

To do the view scalable I have to propose graphics to be in vector format. The best choice is SVG.

Scalabe Vector Graphics

 

Instructions for user: nothing new. Just choose a theme that is known to be SVG theme. At this moment there is "Clovy" theme present is main Clover repository.

 

Instructions for artists

The whole theme must be drawn as one picture with name "Theme.svg" instead of theme.plist being in PNG themes.

The picture must be designed as theme preview with invisible elements needed to Clover (checkbox for example, or numerous os icons).

 

SVG file is a text file which you can edit with TextEdit for further improvements.

To create this drawing you have to use one of vector graphics editor on your choice:

1. Adobe Illustrator. Simply the best.

2. Corel Draw in Windows. I have no experience.

3. Inkscape in Windows or in macOS up to 10.10. Officially it is not supported in higher versions.

4. LibreOffice Draw. It is heavy and slow. SVG file contains many dirts.

5. Boxy SVG. Very small application creating very basic SVG file. It can't embed SVG fonts. Anyway it is good and can be recommended.

6. Gravit Designer

7. Or others

https://en.wikipedia.org/wiki/Comparison_of_vector_graphics_editors

If the editor has own graphics format then you have to export graphics as SVG and tune compatibility as

1. SVG 1.1

2. css/style supported, other css features no.

3. embed fonts as SVG fonts.

4. don't export editor specific information if possible

 

Clover requirements (since rev 4730 and up)

The design must consist of separate images gathered into groups with known names.

For example <g id="Banner">

Obligatory group names:
 

Background
Banner
func_about
func_options
func_clover
func_reset
func_shutdown
func_help
tool_shell
pointer
vol_internal
vol_external
vol_optical
vol_internal_hfs
vol_internal_apfs
vol_internal_ntfs
vol_internal_ext3
vol_recovery
selection_small
selection_big
radio_button
radio_button_selected
checkbox
checkbox_checked

As well as OS icons like os_mac, os_win etc

MISC_ICONS OSIconsTable[] = {
  {NULL, "os_mac"},
  {NULL, "os_tiger"},
  {NULL, "os_leo"},
  {NULL, "os_snow"},
  {NULL, "os_lion"},
  {NULL, "os_cougar"},
  {NULL, "os_mav"},
  {NULL, "os_yos"},
  {NULL, "os_cap"},
  {NULL, "os_sierra"},
  {NULL, "os_hsierra"},
  {NULL, "os_moja"},
  {NULL, "os_linux"},
  {NULL, "os_freebsd"},
  {NULL, "os_freedos"},
  {NULL, "os_win"},
  {NULL, "os_vista"},

The design graphics have limited space to draw all of them. So the good trick will be hide most of them using attributes hidden or zero opacity. Samples:

<g id="os_leo" visibility="hidden">

or

<g id="radio_button" opacity=0>

Using these elements Clover automatically make visibility and change opacity to 1.0.

The caveats. visibility may cause the elements not be exported into svg from Illustrator and will not be calculated into final icon size. opacity produces exhasive rendering.

 

Each icons must contain a special invisible element with name "BoundingRect_xxx" example

	<g id="selection_big" transform="translate(528.000000, 320.000000)">
		<rect id="BoundingRect_2_" y="0" class="st0" width="144" height="144"/>
		<g id="icon_5_" transform="translate(8.000000, 8.000000)" class="st15">
			<path id="rrect" class="st6" d="M10,0h108c5.523,0,10,4.477,10,10v108c0,5.523-4.477,10-10,10H10c-5.523,0-10-4.477-10-10V10
				C0,4.477,4.477,0,10,0z"/>
		</g>
	</g>

This <rect> with name containing "BoundingRect" serves to define whole size of the element. In this case it is width=144 and height=144. This rect is invisible because of class="st0" defined as

.st0{fill:none;}

as one of the possibility to hide elements.

NO! All BoundingRect must be visibility="hidden" because it influences on the icon centre. Rev 4733.

 

 

Text support

Although Clover can draw svg text you should not use it. All static text (as "CLOVER" in the picture above) should be converted to pathes. Clover draws dynamic text by itself.

The theme must contain at least one text line with group id="MessageRow". The attributes of the text will be used by Clover to set text size and color and to choose font. So these text must contain such attributes:

	<g id="MessageRow" transform="translate(0.000000, 580.000000)">
		<g class="st5">
			<text transform="matrix(1 0 0 1 494.928 15)" class="st6 st7 st8">Boot macOS from SystemHD</text>
		</g>
	</g>

These text contains styles

	.st6{fill:#FFFFFF;}
	.st7{font-family:Roboto-Medium;}
	.st8{font-size:16px;}

It means Clover will draw text in white color, size=16px and use font "Roboto-Medium"

 

Fonts

Clover may use SVG fonts embedded into theme or external font placed into the same folder.

Embedded font you can see in Clove example.

Font must have attribute horiz-adv-x="2048" or other value. It means maximum char width in virtual space.

font-face must have family, units-per-em, font-style and bbox (bounding box)

<font horiz-adv-x="2048">

<font-face
	font-family="Roboto-Medium"
	units-per-em="2048"
	underline-position="-100"
	underline-thickness="100"
	font-style="normal"
	bbox="0 -100 2048 1948"
	/>

<missing-glyph horiz-adv-x="510"/>

<missing-glyph> is also obligatory.

Without these elements the font will not work.

If a text shows font-family same as embedded font then Clover will render it. Else Clover will search file with the name of font-family. In this case it is "Roboto-Medium.svg".

 

Where to get SVG fonts?

1. Illustrator can export own fonts into your graphics as SVG font. BoxySVG cannot.

2. You may draw own font with FontForge application or others.

3. You may convert your favorite TTF font into SVG using online services. Google will help you.

Anyway be care about font licenses.

 

Special Clover settings

SVG usually don't contain full information needed for Clover to draw GUI so there is a special setting compatible with SVG specification

<svg> element should define clover namespace

<svg version="1.1" id="CloverThemeTemplate2_1_"
	xmlns="http://www.w3.org/2000/svg"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:clover="https://sourceforge.net/projects/cloverefiboot"
	 x="0px" y="0px" viewBox="0 0 1200 768">

These attributes should be accounting as obligatory. Especially "viewBox"!

Clover settings are optional because there are default values

<clover:theme
  SelectionOnTop="0" BadgeOffsetX="0xFFFF" BadgeOffsetY="0xFFFF" NonSelectedGrey="0" CharWidth="16"
  BackgroundDark="1" BackgroundSharp="0x80" Badges="none"
  SelectionColor="0x80808080"
  />

Prefix "clover:" will be checked by other browsers and allowed because we defined xmlns:clover

 

You may safely remove elements with names "inkscape:", "sodipodi:" and others related to vector editor.

 

 

For discussion welcome to Vector Themes thread

[Slice]

How to search Clover mistakes (bisection)

 

Once we moved to Github and join Clover sources with EDK2 sources we got the possibility to do BISECTION.

The method is follow.

1. Take Clover sources from github with full depth.

cd ~/src

git checkout https://github.com/CloverHackyColor/CloverBootloader.git

cd CloverBootloader

2. Make first full build with a script "buildme" including BaseTools and utilities.

3. You should have a quick possibility to test. For example I can test with QEMU. It is special story how to prepare it.

4. Test Clover. Last revision appears to be bad so you begin to search why.

git bisect start

git bisect bad head

5. Then you should tell if any old revision are good. For example it was 5078.

git bisect good 5078

//------

you can type

git tag --list

to see possible revision. Or just set SHA like

git bisect good 7f84770

//----------

6. Now git will switch you to revision somewhere in the middle and you have to build new revision and test it

./buildme

if compilation fails the inform

git bisect skip

else test it.

 

7. Then you have to inform your system the results

git bisect good

or

git bisect bad

The system gives you new revision for you to build and test.

So this is a bisection. Each time you will go to the centre or revision interval between bad and good. So if the interval is 32 revisions then it will be Log2(32)=5 attempts.

 

When finish you will see the message

Dell:CloverHackyColor sergey$ git bisect good
a355a5dad4ec85ae3b15fd9ccd2c3bea767055ac is the first bad commit
commit a355a5dad4ec85ae3b15fd9ccd2c3bea767055ac
Author: Sergey Isakov <********>
Date:   Thu Sep 12 11:37:56 2019 +0300

    fix errors in MemoryAllocationLib
    

It is the result. It is first commit which breaks functionality.

 

8. Finalize

git bisect reset

 

One note.

Build scripts also depends on revision. So I have to make separate script to build Clover.

It is a copy of buildme but without -nb as I tested boot file and with other name to be independent on git.

 

Enjoy!

[Slice]

Deprecated features, part 2

6. KernelCpu. This technology was introduced for system 10.6.2 to prevent panic on non-supported CPU. There is also a patch for kernel don't check SSE3 instructions support by the CPU.

This method will not work in new systems and it was superseded by FakeCPUID method. Anyway check for SSE3 in kernel is surplus. If the CPU not supported the instructions the system will not work.  You need a special kernel with embedded new instructions emulator.

 

7. DropOEM_DSM. This is a good idea but not cover all cases. It is just excluded for users to apply renaming _DSM to ZDSM.

Explanation why it is excluded https://www.insanelymac.com/forum/topic/304530-clover-change-explanations/?do=findComment&amp;comment=2721876

 

 

8. AddProperties and Arbitrary. Many guides based on these methods but sorry, I will insist you to change the instructions to use Properties as old methods will not be supported. They not cover all cases.

 

[Slice]

Programming Code Style

This is for programmers wanted to make own contribution to Clover sources.

Using same code style by all team members keeps code understandable and easy to maintain. As well it will be simpler to adopt external sources to Clover project like it was with nanosvg and lodepng.

Before this year I claimed to use Tiano Code Style required by EDK2 developers. https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C

But sorry I never like it. I may understand why Tiano claims this. They want the sources to be universal for all platforms and all compilers. They want the language to be simplest C without new standards.

But we compile Clover under recent macOS or under recent Linux or under recent Windows with compilers supported new standards.

 

Since shifting to C++ I think we should get out of the style.

C++ sources should look like C++ and not as Fortran. 

1. Use keywords "void", "const", "static" etc. instead of macros "VOID", "STATIC", "CONST". It will be easier also for compiler.

2. Use standard functions like strstr() instead of EDK2 functions like AsciiStrStr(). Just more convenient.

3. Let variables begin from small letters (not CamelCase). Types begin from Capital letter. Classes will begin from  two CApital letters. Let UPPERCASE to be used for macros but C++ ideology tell us to not use macros when possible.

4. Agree about using TABS and braces but relax the requirements. One line operators like

if (found) break;

will be desired instead of Tiano recommended

if (Found) {

  break;

}

5. Use C++ syntax in for() operator

for (int i=0; i<100; ++i)

which is prohibited by Tiano.

6. Don't place extra spaces between function name and parenthesis.

func(void)

Logically it is one construction and should not be splitted into several pieces. It is more convenient to search "func(" than "func (" because a space can be double space or line end or tab etc in which cases the find will fail.

7. Comments must reflect possible doubts of the programmer. No sense to explain what codes do

Example of undesired comment

i += 5;  // increment index by 5

8. Don't use ASSERT(). We compile Release version where this is empty space. Debug version should reflect behaviour of release version.

Instead of ASSERT(Pointer != NULL) you have to explicitly define what to do

if (Pointer == NULL) return; 

if you are sure it can't be NULL then the ASSERT is also not needed. Don't dust the sources!

 

Something else? Write into "Clover General Discussion"