{"id":29675707,"url":"https://github.com/oxidecomputer/phbl","last_synced_at":"2025-07-22T23:38:05.589Z","repository":{"id":96756940,"uuid":"493048128","full_name":"oxidecomputer/phbl","owner":"oxidecomputer","description":"Pico Host Boot Loader","archived":false,"fork":false,"pushed_at":"2025-07-22T15:50:52.000Z","size":166,"stargazers_count":111,"open_issues_count":0,"forks_count":8,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-07-22T17:41:14.843Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxidecomputer.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,"zenodo":null}},"created_at":"2022-05-17T01:02:08.000Z","updated_at":"2025-07-22T15:50:50.000Z","dependencies_parsed_at":"2023-12-01T23:25:24.206Z","dependency_job_id":"a941578f-ce83-4c25-9df9-bb74b9ea2b8c","html_url":"https://github.com/oxidecomputer/phbl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/phbl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fphbl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fphbl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fphbl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fphbl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/phbl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fphbl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266591230,"owners_count":23953082,"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","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-07-22T23:38:01.508Z","updated_at":"2025-07-22T23:38:05.581Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pico Host Boot Loader\n\n`phbl` (pronounced \"foible\") is the program run from the x86\nreset vector that loads and invokes the phase1 host operating\nsystem package, consisting of the host kernel and phase1 cpio\narchive.\n\nIt is loaded from SPI flash by the PSP, and execution starts in\n16-bit real mode.  It is responsible for:\n\n* bringing the bootstrap core up into 64-bit long mode with\n  paging enabled\n* decompressing the phase1 cpio archive into physical memory\n* locating the kernel executable ELF image inside the archive\n* loading the binary image into physical memory mapped at its\n  linked addresses,\n* and finally invoking the kernel's ELF entry point\n\nThe ZLIB compressed phase1 archive is compiled into `phbl` as a\nbinary blob of bytes.\n\nThe implementation and steps that `phbl` takes are described in\ndetail in [rfd284][1].\n\n## Building phbl\n\nWe use `cargo` and the [`xtask`][2] pattern for builds.  Note\nthat the compressed cpio archive containing the phase1 bootstrap\nis used as part of the build process, and so one must build that\nand compress it first before building `phbl`: the process for\nbuilding a phase1 archive is beyond the scope of this document;\nrefer to the [Helios][3] documentation for details.  But note\nthat the [pinprick][4] utility is suitable for compressing a\nphase1 archive so that it is compatible with `phbl`.\n\nLet us assume that the compressed cpio archive is in a file\ncalled `phase1.cpio.z` and that the `$CPIOZ` environment\nvariable points to it.  Then we may build `phbl` with:\n\n```\ncargo xtask build --cpioz=$CPIOZ\n```\n\nThis generates a \"Debug\" binary in the file\n`target/x86_64-oxide-none-elf/debug/phbl`.\n\n**Note**: Linking `phbl` requires using the GNU linker.\nBy default, Oxide's build systems install GNU ld as `gld`, which is\nconfigured in `x86_64-oxide-none-elf.json`. If your OS installation\ncalls it something else, set the [environment variable](\nhttps://doc.rust-lang.org/cargo/reference/environment-variables.html)\n`CARGO_TARGET_X86_64_OXIDE_NONE_ELF_LINKER` to use yours. On most GNU\nsystems, that will be `CARGO_TARGET_X86_64_OXIDE_NONE_ELF_LINKER=ld`.\n\n## Phbl development\n\nModifying `phbl` follows the typical development patterns of\nmost Rust programs, and we have several `cargo xtask` targets to\nhelp with common tasks.  Typically, one might use:\n\n* `cargo xtask test` to run unit tests\n* `cargo xtask clippy` to run the linter\n* `cargo xtask clean` to remove build artifacts and intermediate\n  files.\n* `cargo xtask expand` to expand macros\n* `cargo xtask disasm` to build the phbl image and dump a\n  disassembly listing of it\n\n`cargo check` is fully supported for e.g. editor integration,\nand formatting should be kept consistent via `cargo fmt`.\n\nMost targets will also accept either a `--release` or `--debug`\nargument to get either an optimized or debugging build; debug\nis the default.  To build a release version for production, run:\n\n```\ncargo xtask build --cpioz=$CPIOZ --release\n```\n\nThis will produce an optimized standalone binary named\n`target/x86_64-oxide-none-elf/release/phbl`.  If one builds\na debug binary, as in the previous section, it will be named,\n`target/x86_64-oxide-none-elf/debug/phbl`.\n\nThese binaries are suitable for use with the\n[amd-host-image-builder][5] tool.  For example, to create an\nimage suitable for writing to flash on a gimlet from a debug\n`phbl` binary, one may change to the `amd-host-image-builder`\nrepository and run:\n\n```\ncargo run -- \\\n    -B amd-firmware/GN/1.0.0.1 \\\n    -B amd-firmware/GN/1.0.0.6 \\\n    -c etc/milan-gimlet-b.efs.json5 \\\n    -r ${PHBL_REPO_ROOT}/target/x86_64-oxide-none-elf/debug/phbl \\\n    -o milan-gimlet-b-phbl.img\n```\n\nThe resulting `milan-gimlet-b-phbl.img` is suitable for writing\ninto a gimlet's SPI ROM.\n\nChanges are submitted and reviewed using the GitHub pull request\nmodel.  Because `phbl` is load bearing, all changes must be\nreviewed.  CI triggered by github actions ensures that tests\npass.\n\n[1]: https://rfd.shared.oxide.computer/rfd/0284\n[2]: https://github.com/matklad/cargo-xtask\n[3]: https://github.com/oxidecomputer/helios\n[4]: https://github.com/oxidecomputer/pinprick/\n[5]: https://github.com/oxidecomputer/amd-host-image-builder/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fphbl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Fphbl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fphbl/lists"}