Documentation request - boot files

[Gringo Vermelho]

Gentlemen,

We need a pinned topic here with a short description of the various boot files along with example scenarios.
A quick introduction to the terminology used when talking about a boot loader, what does stage 1 and stage 2 mean, why each of the three files goes where it goes, when to use chain0, etc.

I'm not thinking about MBR vs GUID or the pros and cons of various ways to install Chameleon, just the basic facts about each boot file, and under which scenario one would use it. Most people have no idea what their options are and it's not documented anywhere that I can find.

Distemperus' .rtf does have this:

   boot & cdboot - stage2 booters; Chameleon binaries; cdboot is used to boot DVDs
   boot0 - locates active partition & loads the partition booter for MBR & GUID/MBR hybrids
   chain0 - loaded by another booter to jump booting yet another booter
   boot1h - partition booter for HFS+ that loads the stage2 booter
   boot1f32 - booter for FAT32 partitions on MBR
   boot1he - booter for extended sectors
   boot1hp - partition booter for HFS+ that finds a boot1h extended loader

Extended sectors, extended loader? partition booter? It's not clear from the above, for example in which scenario one would use boot1hp or boot1he.

And Rocksteady wrote this in the Chameleon FAQ:

• You install boot0 (or chain0) file to the MBR. [This is stage 0, responsible for loading stage 1]
• You install the boot1h file to your partition's bootsector. [This is stage 1, responsible for finding the boot file]
• You install the boot file to your partition's root directory (/). [This is stage 2, the main bootloader that loads kernel, KEXTs and other Chameleon-related files]

I believe that this is all we have.

I'd write it myself if I could, but I have only ever used cdboot and boot1h..I'm following install guides without really understanding what I'm doing, I could never get boot1f32 to work and I have no idea what the others do, besides a very vague idea about the new boot0md and Windows.
So..please, if anyone who understands about this and is not busy coding could lay down the law it would be very much appreciated.
 

[Blackosx]

Hi Gringo

Chameleon documentation....  The number of times I've said to myself - Right, sit down and make a start with something. I've still never done anything about it. 

I agree that documentation is needed for Chameleon and not just for the boot files but something to encompass everything about Chameleon. We have both posted before about this, as have many others but I feel that until somebody kickstarts the process then nothing is going to happen. So maybe this post of yours can build in to something?

One good place for ideas as to how to start might be the GRUB documentation.  Or maybe a wiki would be a better idea, where people could register and correct/update the text as and when they see fit. This way, over time, the wiki could contain accurate information rather than speculative quotes that maybe I would offer in certain areas where I may be uncertain. I wonder if Zef would want to host one on his server?

As you know, there is much information in this forum that could answer many users questions - it just needs to be assembled in to an organised manor. But then again a lot of the new additions/features might not be as well documented as some of the older ones from a couple of years back.

But I guess it all comes down to time. I'm finding I have less available these days than I used to and when I do have some spare time I already have a list of things to fill it. For example, I asked rocksteady the other day to up the max character limit for posts here because I need to update the creating themes guide which had previously reached the limit. Rock changed the limit for me, but I have yet to even start to look at writing revised content.

For now though, maybe you and I could both start by contributing what we know to this topic? Even adding links to / or copying and pasting stuff from other wiki sites to help explain examples etc. would be a start. If we did it in small steps, taking time to correct the posts if necessary then slowly but surely a document would grow. But as you posted, our own knowledge only comes from what we've tried/used. Like you, I have never used boot1he or boot1hp.

Blimey!, thinking about it - in the time it took me to write this I could have probably put down the first quote. lol

I'll chip in when I can with bits.. 

[Blackosx]

Okay, here's something to start off. I've tried to keep it simple but if more info is needed or it needs correcting then feel free to edit.

Stage 0
• A traditional PC will have a BIOS (though recent motherboards may now ship with UEFI which I haven't used).
• One thing a BIOS will do is try to find a bootable device.
• A bootable device has the last 2 bytes of first sector set to 0xAA55.
• Generally, the first 512 byte sector is known as the master boot record (MBR).
• The first 446 bytes are free for containing boot code (Note: bytes 441-446 can contain a Windows disk signature)
• Chameleon's stage 0 boot code is written to the first 440 bytes using a modded fdisk named fdisk440.

The purpose of the Chameleon stage 0 code is to find and load the stage 1 partition loader.
The stage 0 code is written in assembly language and is available in the forge - here.
There are three variations of Chameleon's stage 0 code and these are known as boot0, boot0hfs and boot0md.

boot0 seeks the stage 1 partition loader on the first active partition on the disk.
This is ideally used when you have a single or multiple OS X installations on one disk. The remaining Chameleon files would be written to one partition on the disk, either a system one or a small separate one. That partition is then flagged active so boot0 finds it. In the situation of a secondary installation of Chameleon files on the same disk, the one set for booting can be controlled by setting the active flag .

boot0hfs seeks the stage 1 partition loader on the first HFS partition.
This is ideally used if you have Windows Vista/7 installed on the same HDD as OS X. Windows Vista/7 needs to be the active partition on a disk for it to behave properly, so in this case the boot0 code will skip the active partition. More info.

boot0md seeks the stage 1 partition loader on the first HFS partition of all disks, then looks for active partition.
This is ideally used in multi disk setups and can be installed to the MBR of a Windows Vista/7 disk. It will search many disks for the Chameleon stage 1 partition loader on an HFS partition and if not found will then search again for the first active partition. It can also be used perfectly well as a boot0hfs replacement. More info.

dmazar posted a comprehensive breakdown of the steps each code version takes and describes the possibility of using boot0md as a master boot0 to cover all situations (which I think it pretty much does) here.

Reason for edit: Fix a typo in paragraph for Boot0hfs

[Gringo Vermelho]

This is great Black, I always wanted to understand the stages terminology better. :thumbsup:

Looks like we should just be using boot0md from here on in, like you said it seems to cover most cases.

[danimal]

The one thing that always leaves me guessing is certain boot flags. It would be great to see documentation that not only explains what they do (which is done already) but whether or not they are needed, what the default is, and possibly how to verify they are working. For example I never can figure out if I need GenerateCStates-Yes, GeneratePStates-Yes. I have a Sandy Bridge i5 2500k and if I delete those from my plist I still seem to have P/C states according to HWMonitor. So do I need them or not?

For example the existing documentation says this, it would be nice to have added what is in red

  GenerateCStates=Yes     Enable auto generation of processor idle sleep states
                                         (C-States).
                                         Optional - Not needed for i series processors
                                         Default is No
                                         Use dmesg or HWmonitor to verify
  GeneratePStates=Yes     Enable auto generation of processor power performance
                                         states (P-States).
                                         Optional - Not needed for i series processors
                                         Default is No
                                         Use dmesg or HWmonitor to verify
  CSTUsingSystemIO=Yes    New C-State _CST generation method using SystemIO
                                          registers instead of FixedHW.

  EnableC2State=Yes       Enable specific Processor power state, C2.
                                         Optional - must be enabled in bios
                                         Default is No
                                         Use ... to verify
  EnableC3State=Yes       Enable specific Processor power state, C3.
  EnableC4State=Yes       Enable specific Processor power state, C4.