For the fully functional OS, there is a notion of 2 types of running sessions: those, running before the installation happens, further just "installation" ones (also known as "live") and those, after the installation, further just "installed" ones. Downloaded is the installation set. For now, the difference between 2, almost doesn't exist, but it will change and this manual is written with this in mind, bear with description's seemingly exaggerated scope. Even though live sessions may have value on their own, the main scenario is to drive to the installed case. Hence, a common flow is: downloading the set, preparing an installation medium, then launching the OS, having a quick look at the OS in the live session and then starting the setup program, that will create an installation of Lybid on the machine. All the following sessions will be installed ones.
Lybid hasn't gotten yet the setup program and thus full installation procedure as well. But, there is a possibility to create an installation manually. No matter how lame it might seem at the first glance, it's fine for the development (actually needed) and it might be interesting for early outside testings. And because the file set is quite small and there is not much of configuration whatsoever, it would be trivial to turn a live set into an installed set. With one noticeable exception though: on UEFI, the installed case implies having a Load (aka Boot) option for its installation, that is, we need to create it, and in reality, it's not necessarily "trivial".
Lybid doesn't rely on any loading intermediaries, it uses its own loader, which is a UEFI OS Loader, whose sole purpose is to load ANT, according to its boot protocol, and nothing else. This means, that if we want to create an installation, we need to create the Load Option (LO) for it. UEFI allows to create such and if the firmware implementation of your machine is not totally screwed up by alien logic or "improvements" from the vendor, this could be achieved relatively easy. For this purpose — aiding in manual Lybid installation, the clo utility is provided. Its name stands for "Create Load Option". It's a simple, interactive UEFI application, for running in the UEFI CLI (aka UEFI Shell) and it does, in the area of interfacing with the firmware, what later, the setup program will be doing. But there the necessary warning comes: you must be careful when using it. Even though clo is not harmful per se, bugs and deviations in firmwares might, potentially, give unwanted results. In short, the utility writes into the UEFI persistent storage, but only by using SetVariable() UEFI runtime service and only for setting up its own newly created BootN variable and adding its index to the variable-list BootOrder. How correctly this writing to the storage is being done and if this change will be visible to you, depends solely on how conformant and correct machine's firmware is. For detail on how to use clo, read below.
As for author's own experience with using clo, for the OVMF and Gallium, clo's work was successful. Not only LO was created, but also added correctly to the BootOrder and visible in UEFI Boot Manager's Load Option Menu. And it worked, antload started. About the menu, it only goes to OVMF though, since Gallium doesn't have such, or, rather, what it does, doesn't work like a menu for picking an option to launch: you can only change their order in there, so it's rather an option order editing menu, the option menu itself isn't present and, if you set the timer up, say, to 10 seconds, then Gallium's firmware will be showing a black screen for 10 seconds, before launching the first option.
For Iridium, LO was created "successfully" only in the sense, that SetVariable() reported success, both on storing the newly created BootN and modifying BootOrder (for adding an index of the new variable). But the load option didn't appear in the UEFI Boot Manager Menu neither after return from clo nor even next startup. Although, interestingly, seems, it was set up in the firmware database. Thanks to Windows Boot Manager, that makes a backup of all BootN firmware variables in the BCD registry hive, we can easily inspect these variables and that inspection shows our LO present. However, UEFI doesn't show it. Iridium's firmware reports some fake BootOrder. It doesn't contain all BootN variables, present on the machine, not even Windows' one; it lists only 2, that are BBS (BIOS Boot Specification) typed (Device Path is the node type 5) and represent laptops' hard drive and CD/DVD drive as seen by their description fields. How did Windows manage to make bootmgfw.efi's LO visible in that mess, remains to be a mystery. But it's a 2011 year laptop, when UEFI only was making its first steps on the customer PC land and HP warned that UEFI on the laptop is an experimental feature. Analyzing this messy behavior of laptop's Boot Manager makes an impression, that it doesn't really rely on BootN variables in showing its Load Option Menu. For example for Windows, laptop's Manager menu entry says "OS Boot Manager", whereas Windows' Boot Manager load option description field (that one, that defines LO's text for the UEFI Boot Manager to show in its GUI) says "Windows Boot Manager". Looks like laptop's Boot Manager just provided a special entry for Windows or Linux and ignored everything else. The laptop came with preinstalled Linux, but it was in BIOS mode then.
As for now, apart from the load option creation, you just need to rearrange where set's content goes, according to where its files would be placed during the installation. There are 2 storage units, where Lybid puts its files:
Home Volume is a small partition. As said, conventionally, in the "release" case, it's ESP, but not necessarily. For making the process easier, you can place HV on an ordinary FAT partition just as well. Boot Volume is a normal "main" partition of the OS, e.g. what in Windows is drive C.
In virtual environments, we create a somewhat bigger, than for the live case, .vhd and partition it with a small FAT partition for the Home Volume, a bigger one for the Boot Volume, plus we make Boot Volumes with JFS and BFS for the future. Needless to say, in case you decide to make the same arrangement, you'll need to copy the Lybid directory in all the Boot Volume partitions, you've created. Every such a partition will thus be a different installation and will require its own load option. However, the loader image remains the same, in one sample, you don't need to make a per installation copy.
In the real hardware testings, as described earlier and on the other page, I wasn't fully successful with load options on Gallium and Iridium, due to different reasons. Gallium could be used for the manual installation case, however, it would be way inconvenient, as explained above and here (click the "show" button). As of Rhodium, since this laptop was bought in September 2024, only 2 months ago, so far, only "live" tests were made. We'll report on its installed case success. There, we are going to put antload in machine's ESP, it's already there and there is enough room on it, and Lybid will go to the USB stick, so it will be an "install to removable storage" case, what technically doesn't differ from a normal case.
For the case of testing on real arm64 hardware, where the only option for storage is SD card, then there is no need to split the card into 2 partitions, remember, SD Association says "no" to that, only 1 FAT partition (FAT type depends on the card size) with the MBR scheme. For this case, HV and BV get combined and the difference between live and installed cases for now is that the latter has its load option. I'd not recommend installed case for the uboot case yet. uboot requires ESP (for saving the BootN), SD card's FAT shouldn't be marked as ESP, so if you don't have ESP on eMMC module or don't want to use it for the tests, better just test it in the live case for now. In fact, given the early stage of support for EDK2 ports on ARM SBCs, better to try installed case only on x86 PCs with not whimsy firmware.
Also called Boot Volume System Root Descriptor (BVSRD), is a structure, holding
the necessary information for the loader to find from which storage to boot Lybid.
It contains a very minumum data and so, doesn't take much of the firmware storage.
Namely, it contains a relative Device Path to the Boot Volume, starting with an
HD() node (type 4, subtype 1), followed by a File node (type 4, subtype 4).
The former describes a partition and the latter — a path to the directory on
the partition, that is the System Root of ANT. Thus, in the UEFI Device Path text notation,
BVD would be something like this real example:
HD(4, GPT, ec384e7e-0d93-4bd3-9740-e889eb00b3e5, 50080, 2f000)\Lybid
Also, a 2 byte of load configuration flags follow. This structure is around 64 bytes.
It goes into a so called "Optional Data" part of the UEFI Boot Manager Load Option
Descriptor, of which the contents of a BootN variable for the Load Option comprises.
This is what clo will create and write to the firmware storage, while the setup program isn't ready. Again, use it carefully, thoroughly reading through what it is asking you and making sure, you've understood it before proceeding.
If you decided to create a Lybid installation manually, you need to create its Load Option. As said, for the virtual environments, it works and it's safe. You could familiarize with clo in there. Of course, trying on real hardware is the main goal. To collect knowledge about how easy this process happens on a variety of machines from different vendors and times. Just be careful. It's not "dangerous", but you wouldn't probably want to create broken variables in machine's flash memory even if those variables don't interfere with the rest of the system, take around two hundred bytes and even if it's on a machine, dedicated for testing. Also, clo doesn't provide removal functionality. We didn't even try this, knowing all the mess in the firmwares. If the latter provide "remove load options" function in their menu, that's the way to go, if you need that.
You start clo the same as antload, either via "Load from file" or via UEFI CLI. Its path: efi\Upptech\clo.efi. Again, it's a development tool, simplistic and thus a bit tough. If you type an obviously wrong input, it'll just exit, printing in red about the error. Nothing will be written to the storage until you confirm it. Only at the very end, after all the steps were made and checked, it will tell that it's ready to write it to the storage and only if you confirm that, it will try.
This screenshot shows the described above process.
In the above flow, at the step 5, clo asks about the FS type of the Boot Volume. There FAT was picked. If you pick a different FS, by hitting "n" to that question, then clo
Further steps are the same as previously. Below screenshot visualizes this case.
If the firmware did its job correctly, your Load Option will appear in Boot Manager's Load Option Menu. clo will append the LO to the end of the BootOrder list, so your default boot OS will stay intact. You can change the boot order in the Boot Manager manually if you want and if it lets. Now, when you start the machine, you either hit a key to stop booting the default option and enter the Boot Manager of this presumably multi boot setup or the Boot Manager will allow you to set the timer up, in Manager's settings, for the ability to visit the menu without the need of hitting a key on powerup. Sometimes, it's not possible to set the timer up, e.g. with OVMF it doesn't work, getting reset to default 0 every new startup, so you need to hit the key to enter the menu. Real hardware cases often allow you to set the timer. Experiences of interfacing with the Boot Manager vary, as you know. Anyway, you go in the Load Option Menu and start Lybid by picking its load option and pressing <Enter>. Putting Lybid's LO at the top, will launch it automatically, if you won't intervene.
Now, having Lybid installed and gotten its Load Option on the machine, if you go in UEFI CLI and type:
where fsN is the Home Volume of your installed OS instance (and not HV of the installation medium, which at this point you should've removed), you'll get an error from antload about missing SystemRoot directory. That's because with the installed case, you should launch Lybid via its load option. In this case, the loader doesn't know which disk (partition) the OS is installed on. In the installing case, the partition is inferred from the obvious principle, that the OS resides in the same place, where the loader does — on the installation medium. With the installed Lybid, the Boot Volume partition and the SystemRoot name should be told to the loader. This is what Boot Volume Descriptor does. However, it's still possible to launch an installed Lybid instance without its original load option. As a special case, for recovery, for example, if somehow the load option got deleted, but the installation is valid. It can be done from the UEFI CLI and, in some cases, from the Boot Manager.
For this you provide a text representation of BVD as an argument to antload during its launch in UEFI CLI, like in this example of a GPT Boot Volume:
or, if your BV is MBR:
The syntax of this line for GPT is:
For MBR it is:
where:
The whole line should be without spaces between elements and without wrapping in quotation marks. All numbers, except <PARLBA> are fixed length; there shouldn't be any hexadecimal specifiers appended. As of GUID's Data4. As you know, this element is an array of 8 bytes, it's not a 64 bit integer, unfortunately, worse, for some reasons, in text representations, this element is torn apart into 2 pieces: 2 first bytes come together and the rest 6 follow after yet another dash. Still, those first 2 bytes should not be treated as a 16 bit integer, what, for example, <Data2> and <Data3> are; these 2 bytes are separate bytes, so no need to swap them in the text, thinking that the lowest ordered should go as the second. We keep this messy kind of representing GUIDs for the sake of consistency between tools, for example, UEFI CLI will print out them the same way. Just treat Data4 as an array of 8 bytes, forgetting about big endianness' relics over there and in our way of representing numbers in text.
This alternative launch via passing the BVD text form will work in environments, that provide means to pass this information to the loader, like UEFI Shell or via a manually created Load Option in the Boot Manager menu, if the latter allows that and allows specifying "Optional Data", what, for example, EDK2's Boot Maintenance Manager does. On contrary, it won't work with the Boot Manager "Load from file" option obviously, since this way, you can't pass arguments to the loader.
With UEFI shell and others, implementing UEFI Shell specification, use it as described above. Additionally, there is a chance, that if the firmware implementation allows you to create a load option in its Boot Manager menu manually, with specifying "Optional Data", then you can make this option work too. Apparently, only text data can be set in "Optional Data" this way, so it would be another way of passing BVD to the loader via its text form as in the CLI case. For this case, use the provided mechanism in the Manager menu. In the EDK2, it was tested, it allows to insert, as "Optional Data", a text, specify BVD in its text form there, exactly as in the CLI case. Whether this works for other environments, remains to be clarified. For example in uboot, would this:
work as expected or work at all, needs to be figured out. I don't have hardware to test so far. Your participation is appreciated.
Making such options would take a bit more space in the firmware storage, than the native, binary form of BVD, so it's only for recovery or mitigation purposes, where the original Load Option got lost, but the installation is perfectly valid. In future, Lybid will provide a Load Option recreation mechanism, so only one time recovery start via the shell is really needed if at all. clo creates a Load Option, where BVD is in its "native", most compact, binary form. With the alternative launch via CLI, nothing is stored in the firmware storage, but you need to enter a pretty inconvenient line on every start. You might provide a simple script doing it for you though. The script would be stored in HV.
Where do you get this BVD text from? For the manual installation, you should take care of this, writing out essential parts somewhere and keeping it. During the manual Load Option creation with clo, you'll need to know these data anyway. This is how you recognized correct partitions, BV's FS and now that is how you give the same needed information to the loader. UEFI shell, that prints these data out on its start, partitioning and other tools, you used for making or choosing a partition are your friends. For the later, not so tough development stages, the setup program will provide this text for the user.
By the way, with this method, it's possible to launch live session as well (if there is will to enter additional data and add work for the loader). We split sessions in installing and installed and talk about these different cases, but how does the loader distinguish them? It follows the algorithm, which first figures if the information about Boot Volume Descriptor has been passed to it and if so, uses it. If nothing has been passed, it assumes Boot Volume to be the same volume where it was loaded from by the firmware (Home Volume that is). This algorithm targets the main, installed scenario, but it doesn't do some discrimination between session kinds. That information about Boot Volume mentioned will be either BVD in the binary form, if the launch was via Lybid's original load option, this is the main case, or it will be BVD in the text form, this is the "alternative" launch method or there will be no BVD specified, this is, commonly, the installing session, for example, Boot Manager's "Load from file" logically doesn't pass anything, and the shell, in case of a "bare" antload launch, without parameters, passes only the path to the loader (Argv[0] in terms of CLI's parameters). If the loader gets BVD, it searches the specified volume and if finds it on the machine, opens the specified directory in it, and reads ANT components from it. If there was no BVD, it assumes BV to be the same as HV and as the SystemRoot directory, it assumes the directory Lybid in the root of the volume. Exactly that way the installed set is arranged, but not necessarily only it, for example, if your machine is an arm SBC, with only an SD card as the persistent storage, then in this case as well, the boot and home volumes will match. If to think about it, for this case, it's possible to even not have a load option, however only if you haven't picked some other name for the SystemRoot directory, than default Lybid on the OS installation and if you are fine with starting OS via UEFI shell. And exactly because of this, for the installing case, most logically, it would be to not specify BVD on the loader start, but if one strongly wishes so and during the launch enters the BVD text form for the installation medium volume, it will work too. As you can see, the distinguishing goes more by the fact if BVD has been specified.