| BCOS Home » The BCOS Project » BCOS Programmer's Documentation » BCOS Utility Documentation |
"Gen CD" ISO9660 Image Generator Utility Documentation |
| Project Map |
The ISO9660 Image Generator Utility is a utility that has been designed to convert a set of normal files into a ISO9660 image, imcluding:
The ISO9660 Image Generator Utility has 2 command line arguments, and several command line flags.
The 2 (required) command line arguments are the name of the index file, then the name of the output ISO9660 image.
If the "-c" flag is present, an extra argument specifying the maximum capacity of the target media in sectors will be expected (e.g. the command "gencd -c 1234 index out.iso" will create an ouput file that is not larger than 1234 sectors or 2468 KiB). The default value is 333000 sectors (corresponding to a standard 650 MB CD). The value 0 disables all size limits.
The command line flags are described in Table 2-1. Command Line Flags.
| Flag | Description |
|---|---|
| -c | Set the maximum capacity of target media (see Section 2.1. Command Line Arguments) |
| -f | Force the output file to be updated without checking if any source files (or the utility itself) changed |
| -s | Create the smallest ISO9660 image (by disabling redundancy) |
| -t | Do everything needed to generate the ISO9660 image (including building a FAT file system for UEFI boot loaders), but then only output the FAT file system image (for testing) |
| -v | Enable verbose mode |
The ISO9660 Image Generator Utility processes an index file that describes what the output ISO9660 image should contain. The index file is parsed one line at a time, where the first (non-whitespace) character determines the type of line.
All comments start with a ';' character and continue until the end of the line. Comments are treated as white space.
Lines containing nothing or white space (including a comment) are ignored.
Lines beginning with a 'b' or 'B'character are lines describing a CD-ROM boot loader designed for BIOS. For these lines, the type character must be followed by:
If an optional destination file name is given, the utility will ensure that the sectors refered to by the boot record are the sectors used by the destination file (the utility does not waste space by using different sectors for two copies of the file).
Lines beginning with a 'u' or 'U'character are lines describing a boot loader designed for UEFI. For these lines, the type character must be followed by:
For UEFI boot loaders, the utility will auto-generate a suitable FAT file system containing the requested file (for use as the UEFI system partition), and corresponding boot record will refer to the resulting FAT file system.
The utility will also auto-detect an appropriate file name for use within the UEFI system partition by using the "Machine Type" field from the file's (PE excutable) headers. This allows you to use a different name for file in the ISO9660 file system (e.g. for a line like "u foo.bin bar.efi", if the "Machine Type" field in foo.bin says the file is for 64-bit 80x86, then the file will be called \EFI\BOOT\BOOT\BOOTx64.EFI in the UEFI system partition and will have the name bar.efi in the ISO9660 file system.
If the index file contains multiple UEFI boot loader lines; then all of the files will be added to the same FAT file system and only one boot record will be used. This is to allow multiple UEFI boot loaders for different architectures (e.g. \EFI\BOOT\BOOT\BOOTIA32.EFI, \EFI\BOOT\BOOT\BOOTx64.EFI and \EFI\BOOT\BOOT\BOOTARM.EFI in the same UEFI system partition).
If an optional destination file name is given, the utility will ensure that the sectors used by the file in the FAT file system (used by the boot record) are the same sectors used by the destination file (the utility does not waste space by using different sectors for two copies of the file).
Lines beginning with a '*', 'f' or 'F character are lines describing a normal file. For these lines, the type character must be followed by:
These files are simply copied to the ISO9660.
Lines beginning with a 'd' or 'D'character are lines describing a directory structure. For these lines, the type character must be followed by:
For directories, the utility scans the source directory recursively (to include all sub-directories, their sub-directories, etc) and ignores all files with names beginning with a '.' character. The remaining files are copied to the specified destination directioin of the ISO9660 image.
For directory and file names used in both the ISO9660 and FAT file systems, characters that are invalid for the file system are silenty ignored, then names are truncated to fit any size requirments, to get a final name. If the final name is empty (e.g. all characters were invalid and ignored), or if there is multiple files with the same final name (because invalid characters were ignored and/or the original names clashed, and/or because the utility autogenerated the same name when creating a UEFI system partition because two or more UEFI boot loader files had the same value in their "Machine Type" field) the utility considers it a user error.
Where possible (if the resulting ISO9660 image would be smaller than the target media's maximum capacity, if none of the files used the BACKUP directory name, and if it's not disabled by the use of the -s command line flag) the utility auto-generates a redundant copies of directories and files and puts them in a directory called "BACKUP" (for example, if the ISO9660 image would contain a file called "FOO.TXT" then it may also contain a copy of the file called "BACKUP/FOO.TXT". This is primarily intended for fault tolerance (and intended to be used and supported by boot loaders).
When creating redundant backups; the utility creates copies of priority groups in order of priority, stopping if duplicating the next priority group would cause the size of the image would exceed 600 MiB. For example, if the image would've been 500 MiB without any redundant copies, the highest priority group consists of 50 MiB of data and the second highest priority group consists of 100 MiB of data; then the utility will create redundant copies for all data in the highest priority group (taking final the image size up to 550 MiB) and then won't create copies of any other data because the second highest priority group is too large for all of it to fit within the target media's maximum capacity (even if some files from the second highest priority group would have fit, and even if the entire third highest priority group would've fit). In addition (to reduce image size for data that was deemed "unimportant"), the utility never creates redundant copies of data using the lowest priority group.
For the purpose of redundancy, there are 6 priority levels which are derived from the "type" character used in the index file:
| Type character | Priority |
|---|---|
| * | 0 (highest) |
| B | 1 |
| U | 1 |
| F | 2 |
| D | 3 |
| b | 4 |
| u | 4 |
| f | 5 (lowest, redundant copies never created) |
| d | 5 (lowest, redundant copies never created) |