{"id":15060437,"url":"https://github.com/alexfru/bootprog","last_synced_at":"2025-04-10T05:51:01.623Z","repository":{"id":33752388,"uuid":"37407571","full_name":"alexfru/BootProg","owner":"alexfru","description":"FAT12/16/32 Bootsector for .COMs/.EXEs","archived":false,"fork":false,"pushed_at":"2023-04-16T00:43:35.000Z","size":35,"stargazers_count":101,"open_issues_count":0,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-24T07:04:36.467Z","etag":null,"topics":["512-bytes","assembly-language","bios","boot","boot-sector","bootloader","fat12","fat16","fat32","x86"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexfru.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-14T10:01:51.000Z","updated_at":"2025-03-06T17:48:51.000Z","dependencies_parsed_at":"2025-02-16T19:43:14.594Z","dependency_job_id":null,"html_url":"https://github.com/alexfru/BootProg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfru%2FBootProg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfru%2FBootProg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfru%2FBootProg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfru%2FBootProg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexfru","download_url":"https://codeload.github.com/alexfru/BootProg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166926,"owners_count":21058480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["512-bytes","assembly-language","bios","boot","boot-sector","bootloader","fat12","fat16","fat32","x86"],"created_at":"2024-09-24T22:58:41.503Z","updated_at":"2025-04-10T05:51:01.614Z","avatar_url":"https://github.com/alexfru.png","language":"Assembly","readme":"# The \"BootProg\" Boot Sector\n\n\n## What is BootProg?\n\nBootProg is a collection of 512-byte boot sectors (for the x86 PC) capable of\nloading and executing a program from a\n[FAT](https://en.wikipedia.org/wiki/File_Allocation_Table)12-formatted floppy\nor a FAT16/32-formatted hard disk (bootable USB sticks and CDs can also be made\nwith BootProg).\n\nBootProg understands programs in the MS-DOS\n[.COM](https://en.wikipedia.org/wiki/COM_file) or\n[.EXE](https://en.wikipedia.org/wiki/DOS_MZ_executable) format. This makes it\npossible to use existing 16-bit compilers such as Borland/Turbo C/C++,\nSybase/Open Watcom C/C++ and Smaller C and a variety of assemblers such as\n[NASM](https://nasm.us/), FASM, TASM and MASM among the others.\n\nBootProg doesn't require that the program occupy a contiguous span of sectors\nor FAT clusters or reside at a specific fixed location on the disk. BootProg\nfaithfully parses the root directory and the chain of FAT clusters in order to\nlocate the program contents. The only requirement is that the program be named\n\"STARTUP.BIN\" (without quotes). This makes updating the program easy. You just\nneed to update the file and you can reboot and execute it immediately.\n\nBtw, you can flexibly boot your HDD partitions containning BootProg and some\nother OSes using the [MBiRa](https://github.com/alexfru/MBiRa) boot manager.\n\n\n## What can BootProg be used for?\n\nYou can make a boot loader for your OS. The program that BootProg loads can be\nyour 2nd stage boot loader. Or, if your OS is relatively small, STARTUP.BIN\ncould contain the entire OS.\n\nYou can write low-level utilities to work with your PC's hardware and load them\nwith BootProg without having to jump through the hoops with your Windows, Linux\nor even DOS.\n\nYou can make cool graphics demos or games that run on bare hardware.\n\n\n## What can't BootProg be used for?\n\nMany things. Most importantly, if you make a DOS program that uses any MS-DOS\nservice functions (e.g. [int](http://www.delorie.com/djgpp/doc/rbinter/) 21h)\nor data structures, it will not work when loaded by BootProg. It must use either\nBIOS services (e.g. int 10h, int 16h, int 13h and such) or access hardware\ndirectly or both.\n\nHowever, it is possible to create universal/hybrid programs that would work both\nin DOS and when loaded by BootProg. BootProg will set registers si, di and bp to\nthe values 16381, 32749 and 65521 respectively before transferring control to\nyour program. Your program can then check the values in these registers and use\nDOS services in DOS or something else instead on bare hardware. You can also\nchoose to make the program run with reduced functionality if not on DOS or vice\nversa.\n\n\n## How does it work?\n\nNothing special. It just finds STARTUP.BIN, loads it, performs any relocations\nnecessary for the .EXE type of programs, sets the dl register to the BIOS boot\ndrive number (e.g. 0, 80H), sets the magic numbers 16381, 32749 and 65521 in\nregisters si, di and bp respectively and passes control to your program.\n\nIf BootProg can't find STARTUP.BIN, it will print \"NoFile\" or \"NF\" to the\nscreen. If it fails to load the file due to a read error, it will print\n\"ReadErr\" or \"RE\".\n\n\n## Compilation\n\nYou'll need [NASM](https://nasm.us/) 2.10 or newer.\n\nThen just do one or more of these as appropriate:\n\n    $ nasm boot12.asm -f bin -o boot12.bin\n    $ nasm boot16.asm -f bin -o boot16.bin\n    $ nasm boot16.asm -f bin -o boot16l.bin -dUSE_LBA\n    $ nasm boot32.asm -f bin -o boot32.bin\n    $ nasm boot32.asm -f bin -o boot32c.bin -dUSE_CHS\n\n\n## How do I put BootProg on my disk?\n\nIf you have a 1.44MB 3\"5 floppy, just format it regularly with FAT12 in DOS or\nWindows and then write flp144.bin to the very first sector of the floppy with\nwhatever tools you find/have for that. After that you can copy STARTUP.BIN to\nthe floppy using any regular means and off you go.\n\nIf you want to create an image of a 1.44MB 3\"5 floppy, it might be even easier.\nCompile the mkimg144.c program contained here with your favorite C compiler and\nuse it:\n\n    mkimg144 [option(s)] [file(s)]\n    \n    Options:\n    \n    -bs \u003cfile\u003e  Specifies the boot sector to use, e.g. \"-bs flp144.bin\"\n    \n    -o \u003cfile\u003e   Specifies the name of the output file (\"floppy.img\" is the\n                default, if this option isn't specified)\n    \n    -us         Uses the current time to set the volume ID of the FAT to a unique\n                value (the volume ID is used to distinguish between different\n                removable disks and detect disk change more accurately)\n\nE.g: \"mkimg144 -bs flp144.bin -o flp144.img -us startup.bin\".\nBtw, you can rename the supplied file \"demo1.com\" to \"startup.bin\" to try it\nout.\n\nFor all other cases you'll need to become a little more familiar with FAT and a\nlittle more intimate with disk tools and BootProg's source code.\n\nYou will need to populate the\n[BPB](https://en.wikipedia.org/wiki/BIOS_parameter_block)'s of boot12.asm,\nboot16.asm and boot32.asm with the values appropriate to the type and size of\nthe file system that you already have on a disk or that you intend to create on\nthe disk. See the source code, the BPB variables are located between comments\nlike these:\n\n    ;;;;;;;;;;;;;;;;;;;;;\n    ;; BPB starts here ;;\n    ;;;;;;;;;;;;;;;;;;;;;\n    ...\n    ;;;;;;;;;;;;;;;;;;;\n    ;; BPB ends here ;;\n    ;;;;;;;;;;;;;;;;;;;\n\nNote, there are two BPB parts in FAT32.\n\nThe best is to format your disk with some standard tools (e.g. FORMAT.COM in\nDOS), extract the BPB values from the FAT-formatted disk, put them into BootProg\nand then write thusly adjusted BootProg over the original boot sector.\n\nYou may find a disk editor handy when manipulating BPB values and/or reading/\nwriting boot sectors.\n\n### Linux\n\nOn Linux you could use the dd tool to install BootProg. If you need to install\nBootProg on /dev/sda1 (it could be /dev/hda1 or some such, you need to figure\nout which it is), first, save the existing VBR to the sda1_old.vbr file:\n\n    $ sudo dd if=/dev/sda1 of=sda1_old.vbr bs=1b count=1\n\n**BACKUP THE sda1_old.vbr FILE TO BE ABLE TO RESTORE THE ORIGINAL VBR!**\n\nNow install BootProg as the new VBR on /dev/sda1...\n\nIf you're doing it for FAT32 LBA:\n\n    $ sudo cp boot32.bin sda1.vbr\n    $ sudo dd if=sda1_old.vbr of=sda1.vbr bs=1 skip=3 seek=3 count=87 conv=notrunc\n    $ sudo dd if=sda1.vbr of=/dev/sda1 bs=1b count=1\n\n(Use boot32c.bin for FAT32 CHS.)\n\nIf you're doing it for FAT16 CHS:\n\n    $ sudo cp boot16.bin sda1.vbr\n    $ sudo dd if=sda1_old.vbr of=sda1.vbr bs=1 skip=3 seek=3 count=59 conv=notrunc\n    $ sudo dd if=sda1.vbr of=/dev/sda1 bs=1b count=1\n\n(Use boot16l.bin for FAT16 LBA.)\n\nSimilarly, if you're doing it for FAT12:\n\n    $ sudo cp boot12.bin sda1.vbr\n    $ sudo dd if=sda1_old.vbr of=sda1.vbr bs=1 skip=3 seek=3 count=59 conv=notrunc\n    $ sudo dd if=sda1.vbr of=/dev/sda1 bs=1b count=1\n\nEssentially, this preserves the VBR's BPB while replacing the VBR's code.\n\nTo uninstall BootProg from /dev/sda1 using the previously saved file\nsda1_old.vbr:\n\n    $ sudo dd if=sda1_old.vbr of=/dev/sda1 bs=1b count=1\n\n\n## Limitations and implementation details\n\nboot12.asm (flp144.asm) and boot16.asm require an i8086/i8088 or a better CPU.\nboot32.asm naturally requires an i80386 or a better CPU.\n\nboot12.asm (flp144.asm) was primarily written for floppies but may also be used\non hard disks on FAT12 primary partitions (\n[file system ID](https://en.wikipedia.org/wiki/Partition_type) 1). On HDDs its\nexpected use is the boot sector of the partition (AKA\n[VBR](https://en.wikipedia.org/wiki/Volume_boot_record)) and not the\n[MBR](https://en.wikipedia.org/wiki/Master_boot_record).\n\nboot16.asm was written for and tested on primary FAT16 partitions (file system\nIDs 4, 6 and 0Eh). Its expected use is the boot sector of the partition (AKA\nVBR) and not the MBR. By default boot16.asm assembles to operate using BIOS int\n13h function 2, that is,\n[CHS](https://en.wikipedia.org/wiki/Cylinder-head-sector)-based sector reads,\nIOW, for old systems supporting only small HDDs, smaller than 8GB (or even\nsmaller than 504MB).\nPass \"-dUSE_LBA\" to NASM to assemble boot16.asm to operate using BIOS int 13h\nfunction 42h, that is,\n[LBA](https://en.wikipedia.org/wiki/Logical_block_addressing)-based sector\nreads, IOW, for newer systems supporting HDDs larger than 8GB.\n\nboot32.asm was written for and tested on primary FAT32 partitions (file system\nIDs 0Bh and 0Ch). Its expected use is the boot sector of the partition (AKA VBR)\nand not the MBR. By default boot32.asm assembles to operate using BIOS int 13h\nfunction 42h, that is, LBA-based sector reads, IOW, for newer systems supporting\nHDDs larger than 8GB.\nPass \"-dUSE_CHS\" to NASM to assemble boot32.asm to operate using BIOS int 13h\nfunction 2, that is, CHS-based sector reads, IOW, for old systems supporting\nonly small HDDs, smaller than 8GB (or even smaller than 504MB).\n\nNote that when BootProg is assembled to operate using CHS-based reads, on HDDs\nit will first request the drive parameters (AKA disk geometry) using BIOS int\n13h function 8. If a drive is moved between different systems, its geometry may\ndiffer in the eyes of the different BIOSes, more so when it's a disk image for\na VM. Using function 8 helps in the situations when the disk is moved and its\nBPB values for Sectors per Track and Heads per Cylinder cease to be appropriate.\n\nAlso, when using CHS-based reads, BootProg does its best to detect whether the\nnecessary sectors are reachable using CHS addressing, that is, their equivalent\nLBA fits into 24 bits (less than some 16 million) and doesn't result in cylinder\nnumbers larger than 1023. If a sector isn't reachable, a read error is reported\ninstead of mysterious behavior. This should help identifying mistakes such as\nwhen the partition is too big or is too far away from the HDD's start for CHS-\nbased reads to work. Move and/or resize the partition or use LBA-based BootProg\nif you run into this problem.\n\nBootProg does not check the size of STARTUP.BIN and reads into memory all of its\nclusters, which means that up to 32767 extra bytes may be read from the disk and\nwritten to the memory after the last byte of STARTUP.BIN (max cluster size is\n32KB). It also means that you may append data to your program and it will be\nloaded. You may create oversized .COM-style STARTUP.BIN larger than ~64KB,\nhowever, note that the stack will naturally overwrite its contents from offset\n65535 of the program segment (offset 65279 of the file) downwards.\n\nIf your PC has the full 640KB of conventional/DOS memory, you should be able to\nsafely load program files of sizes of up to 590KB (don't forget to include .EXE\nstack size!). Calculation:\n\n    (640*1024 - 600h (reserved at memory address 0) - 2048 (BootProg's stack) -\n     512 (BootProg) - 6144 (FAT12 copy) - 32768 (max cluster size)) / 1024 =\n    598KB\n\n\n## Resources, links\n\n*   [Master boot record](https://en.wikipedia.org/wiki/Master_boot_record)\n*   [Volume boot record](https://en.wikipedia.org/wiki/Volume_boot_record)\n*   [Partition type](https://en.wikipedia.org/wiki/Partition_type)\n*   [Logical block addressing](https://en.wikipedia.org/wiki/Logical_block_addressing)\n*   [Cylinder-head-sector](https://en.wikipedia.org/wiki/Cylinder-head-sector)\n*   [File Allocation Table](https://en.wikipedia.org/wiki/File_Allocation_Table)\n*   [FAT: General Overview of On-Disk Format Version 1.03](https://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/fatgen103.doc)\n*   [BIOS parameter block](https://en.wikipedia.org/wiki/BIOS_parameter_block)\n*   [DOS MZ executable](https://en.wikipedia.org/wiki/DOS_MZ_executable)\n*   [COM file](https://en.wikipedia.org/wiki/COM_file)\n*   [MBiRa](https://github.com/alexfru/MBiRa)\n*   [NASM](https://nasm.us/)\n*   [Ralf Brown's Interrupt List](http://www.delorie.com/djgpp/doc/rbinter/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexfru%2Fbootprog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexfru%2Fbootprog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexfru%2Fbootprog/lists"}