{"id":29675761,"url":"https://github.com/oxidecomputer/amd-host-image-builder","last_synced_at":"2025-08-30T18:21:45.301Z","repository":{"id":288667978,"uuid":"410019438","full_name":"oxidecomputer/amd-host-image-builder","owner":"oxidecomputer","description":"Builds Flash image for our AMD host system","archived":false,"fork":false,"pushed_at":"2025-07-08T20:03:53.000Z","size":684,"stargazers_count":5,"open_issues_count":24,"forks_count":1,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-07-22T23:56:34.747Z","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":"2021-09-24T15:46:48.000Z","updated_at":"2025-07-08T20:03:55.000Z","dependencies_parsed_at":"2025-05-08T20:21:20.352Z","dependency_job_id":"a46a9641-d2a8-46e7-b77b-c8bd7303f404","html_url":"https://github.com/oxidecomputer/amd-host-image-builder","commit_stats":null,"previous_names":["oxidecomputer/amd-host-image-builder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/amd-host-image-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Famd-host-image-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Famd-host-image-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Famd-host-image-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Famd-host-image-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/amd-host-image-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Famd-host-image-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269672458,"owners_count":24457114,"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-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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:27.429Z","updated_at":"2025-08-10T03:37:05.089Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amd-host-image-builder\n\nThis tool builds flash images for AMD Zen systems.\n\n# Setup\n\nWe use the `cargo xtask` for building.\n\nYou will need to have either the LLVM `ld.lld` or GNU linkers\ninstalled in order to build.  If you are building on illumos,\nGNU `ld` is installed as `gld`; set `LD=gld` before running\n`cargo xtask` if you get errors from `build.rs`.\n\n# Usage\n\nSelect a configuration file for the system and firmware version\nthat you are using, e.g., `etc/milan-gimlet-b-1.0.0.a.efs.json5`\nand customize it according to your application if necessary.\n\nTo build an image for a Milan-based Gimlet, run the following,\nspecifying the `make` variable `PAYLOAD` to point to the reset\nimage payload you want in the result:\n\n    cargo xtask gen \\\n        --payload /path/to/phbl \\\n        --amd-firmware /path/to/amd-firmware/blobs \\\n        --app apps/milan-gimlet-b-1.0.0.a.toml \\\n        --image out/milan-gimlet-b-1.0.0.a.img\n\n\nThis will create an image file in the `out/` subdirectory of\nthe current directory, with the name that you specified, e.g.,\n`milan-gimlet-b-1.0.0.a.img`, with the production `phbl`\nloader as the payload.\n\nTo use the development loader, one may run:\n\n    cargo xtask gen \\\n        --payload /path/to/bldb/target/x86_64-oxide-none-elf/release/bldb \\\n        --amd-firmware /path/to/amd-firmware/blobs \\\n        --app apps/turin-ruby-1.0.0.3-p1.toml \\\n        --image out/turin-ruby-1.0.0.3-p1-bldb.img\n\nAlternatively, one may run `cargo run` directory, and not use\nthe `xtask` wrapper.  For example:\n\n    cargo run -- \\\n        -B /path/to/amd-firmware/GN/1.0.0.a \\\n        -c etc/milan-gimlet-b-1.0.0.a.efs.json5 \\\n        -r /path/to/target/x86_64-oxide-none-elf/release/bldb \\\n        -o milan-gimlet-b-1.0.0.a.img\n\nHere, the following are given as arguments:\n\n* `/path/to/amd-firmware/GN/1.0.0.a` is in the search path for blobs,\n* The configuration file used is `etc/milan-gimlet-b-1.0.0.a.efs.json5`,\n* The reset image is `bldb`.  Note that there are restrictions on the\n  contents of the ELF file given to the image builder.\n  `amd-host-image-builder` extracts the segments that need to\n  be in the reset image from the ELF file and stores them into the\n  appropriate flash entries.  Those entries will automatically be created\n  and should _not_ be specified in the JSON configuration file.\n* The output file name is given as `milan-gimlet-b-1.0.0.a.img`.\n\n`amd-host-image-builder` will incorporate a number of\n(necessary) blobs named in the configuration file.  These blobs\nare located by searching directories specified via the `-B\n\u003cdirectory\u003e` option, which can be given multiple times.  If a\nblob is named by an absolute path in the configuration file,\nthen that will be used. Otherwise, the directories will be\nsearched in the order they were specified.\n\nThe resulting image will be in `milan-gimlet-b-1.0.0.a.img` and\ncan be flashed using\n[humility qspi](https://github.com/oxidecomputer/humility) or\na hardware flasher (CH341A etc).\n\nThe PSP will print debug messages to the serial port that can be\nconfigured in the settings below, see [PSP configuration](#psp-configuration).\n\n# Configuration\n\nThe configuration file syntax is JSON5.\n\nThe configuration file contents specify:\n* Processor generation,\n* PSP directory contents,\n* BHD directory contents,\n\nSee the subsections below for more details.\n\nRunning `cargo xtask schema` builds the schema and stores it\ninto `/out/efs.schema.json`.\n\nWe recommend using an editor that can match the document against\na schema when editing the configuration.  For example, IntelliJ\nIDEA is known to work by setting a mapping between the file\nsuffix `.efs.json5` and the file `efs.schema.json` in `JSON\nSchema Mappings` in its global settings.\n\n## Directory Configuration\n\nEach directory has any number of entries.  Each entry has a\n`source` and a `target` field.\n\nThe `source` field specifies how to construct the payload\ndata for that entry.  Possible fields in `source` are:\n\n* `Value` and an immediate value to use\n* `ApcbJson` and the inline configuration for the PSP\n* `BlobFile` and the name of a file to load and use as payload\n\nUse the `target` field to specify where in the flash to put the\nresult.  The only mandatory field is `type` to specify the\ncorresponding entry kind.\n\n## PSP configuration\n\nThe PSP can be configured using one or multiple entries in the\nBhd directory with the type `ApcbBackup` and/or `Apcb`.  For\nnow, it is recommended to have exactly one entry of type\n`ApcbBackup`, and to store it into `sub_program` 1.  Note that\n`sub_program` an optional field in the `target` that defaults to\n0.\n\nWe represent the PSP configuration as JSON5, too. The format is\nvery close to the actual APCB, with some reserved fields hidden\nif they are empty anyway.  The checksum will automatically be\nupdated by amd-host-image-builder and doesn't need to be\nmanually updated.\n\nFor extra possible entries that you can add to the Apcb, be sure\nto validate against the JSON schema.\n\nThe Apcb contains (about 3) groups. Each group contains several\ndozen entries.  Each entry is either a \"struct\" or a \"tokens\"\nentry.  Struct entries are denoted by the keyword `Struct`, and\nare an older mechanism.  AMD is in the process of replacing them\nwith tokens entries, denoted by `tokens`.  Settings should be\nmade using `tokens` entries, not `Struct` entries, if possible.\n\nFor example, there's an entry `ErrorOutControl` which you can\nuse to configure PSP error messages, and `ConsoleOutControl`\nwhich you can use to configure early PSP messages. You can\nconfigure target and verbosity.\n\nUnder `tokens`, there's are tokens to configure later PSP\nmessages.  For example, the token `AblSerialBaudRate` configures\nthe baud rate of the UART, `FchConsoleOutMode` to set whether\nPSP prints to a UART or not (0), `FchConsoleOutSerialPort` to\nset which UART to use (`SuperIo`, `Uart0Mmio`, or `Uart1Mmio`;\nsupposedly moved to `FchConsoleMode` in Milan.\n\n# Preparation of ELF files\n\nThis tool generates its output such that, when the PSP loads the\nreset image into memory, it is laid out as specified in the\nsource ELF file.  Execution will start at the ELF entry point.\n\nWhen the system starts, the PSP holds the x86 cores in reset\nwhile loading the image.  Eventually, it starts the x86 \"boot\"\nCPU (called the \"Boot Support Core\", \"Bootstrap Core\", or BSC in\nAMD's documentation) in 16-bit real mode.  That CPU will start\nexecuting 16 Byte below the end of the aligned 16-bit real-mode\nsegment at the end of the reset image.  Thus, the ELF entry\npoint must contain valid 16-bit real-mode code exactly 16 bytes\nfrom the end of the last segment in the file.\n\nAlso, the ELF file needs to be linked in a way that it actually\nspecifies _physical_ addresses: there is no MMU configured, let\nalone enabled, when execution starts at the reset vector.\n\nThe ELF file must also expose three symbols:\n* `__sloader` marking the start of the reset image\n* `__eloader` marking the end of the reset image\n* `_BL_SPACE` giving the amount of memory required for\n  the image, in bytes.\n\nThe values of those special symbols are validated by\n`amd-host-image-builder`, which will fail if they do not\nmatch a set of hardcoded criteria.  See the tool's source\ncode for the exact rules.\n\nFor the special case of facilitating bring-up work, it is also\npossible to specify a non-ELF file that is interpreted basically\nas a blob. In that case, it will be loaded into RAM such that it\nends at address 0x8000_0000.  Validation checks are not\nperformed in this case.  Further, we make no claims of stability\nfor this feature and reserve the right to change or remove it at\nany point--you are on your own.\n\n# Firmware Blobs\n\nFirmware blobs come from AMD, and we do not redistribute them\nhere.  However, the `dump` subcommand of this tool can extract\nthem from an existing image.  If you have, say, a ROM image with\nAGESA for your board, you can use this to extract the blobs that\nare embedded with that image, and then use those with\n`amd-host-image-builder` to build your own image with a\ndifferent payload.\n\n# License\n\nAMD host image builder uses the Mozilla Public License, 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Famd-host-image-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Famd-host-image-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Famd-host-image-builder/lists"}