{"id":18368708,"url":"https://github.com/openbmc/phosphor-ipmi-flash","last_synced_at":"2025-09-21T21:08:03.898Z","repository":{"id":74554818,"uuid":"140630477","full_name":"openbmc/phosphor-ipmi-flash","owner":"openbmc","description":"OpenBMC IPMI Library (Handler) for In-Band Firmware Update","archived":false,"fork":false,"pushed_at":"2025-02-02T11:42:45.000Z","size":2311,"stargazers_count":7,"open_issues_count":5,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-22T04:02:22.230Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openbmc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2018-07-11T21:44:07.000Z","updated_at":"2025-02-02T11:42:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"8468fd53-4894-4699-8720-736132f47803","html_url":"https://github.com/openbmc/phosphor-ipmi-flash","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-ipmi-flash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-ipmi-flash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-ipmi-flash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-ipmi-flash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openbmc","download_url":"https://codeload.github.com/openbmc/phosphor-ipmi-flash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522415,"owners_count":20952544,"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":[],"created_at":"2024-11-05T23:27:07.191Z","updated_at":"2025-09-21T21:08:03.892Z","avatar_url":"https://github.com/openbmc.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Secure Flash Update Mechanism\n\nThis document describes the OpenBmc software implementing the secure flash\nupdate mechanism.\n\nThe primary details are in\n[OpenBMC docs](https://github.com/openbmc/docs/blob/master/designs/firmware-update-via-blobs.md).\n\n## Building and using the host-tool\n\nThis repo contains a host-tool implementation for talking to the corresponding\nBMC blob handler.\n\n### Building the host-tool\n\nThe host-tool depends on ipmi-blob-tool and pciutils.\n\n#### Building libpciaccess\n\nCheck out the\n[xorg-macros source](https://gitlab.freedesktop.org/xorg/util/macros).\n\nThen run these commands in the source directory.\n\n```sh\n./autogen.sh --prefix=/usr\nmake install\n```\n\nCheck out the\n[libpciaccess source](https://gitlab.freedesktop.org/xorg/lib/libpciaccess).\n\nThen run these commands in the source directory.\n\n```sh\n./autogen.sh\nmake\nmake install\n```\n\n#### Building ipmi-blob-tool\n\nCheck out the\n[ipmi-blob-tool source](https://github.com/openbmc/ipmi-blob-tool).\n\nThen run these commands in the source directory.\n\n```sh\n./bootstrap.sh\n./configure\nmake\nmake install\n```\n\n#### Building stdplus\n\nCheck out the [stdplus source](https://github.com/openbmc/stdplus).\n\nThen run these commands in the source directory.\n\n```sh\nmeson setup -Dexamples=false -Dtests=disabled builddir\nninja -C builddir\nninja -C builddir install\n```\n\n#### Building burn_my_bmc (the host-tool)\n\nCheck out the\n[phosphor-ipmi-flash source](https://github.com/openbmc/phosphor-ipmi-flash).\n\nThen run these commands in the source directory.\n\n```sh\n./bootstrap.sh\n./configure --disable-build-bmc-blob-handler\nmake\nmake install\n```\n\n_NOTE:_ When building from the OpenBMC SDK your configuration call will be:\n\n```sh\n./configure --enable-oe-sdk --host \"$(uname -m)\" --disable-build-bmc-blob-handler AR=x86_64-openbmc-linux-gcc-ar RANLIB=x86_64-openbmc-linux-gcc-ranlib\n```\n\n### Parameters\n\nThe host-tool has parameters that let the caller specify every required detail.\n\nThe required parameters are:\n\n| Parameter   | Options                                                                  | Meaning                                                                                                                                  |\n| ----------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| `command`   | `update`                                                                 | The tool should try to update the BMC firmware.                                                                                          |\n| `interface` | `ipmibt`, `ipmilpc`, `ipmipci`, `ipminet`, `ipmipci-skip-bridge-disable` | The data transport mechanism, typically `ipmilpc`. The `ipmipci-skip-bridge-disable` is `ipmipci` but does not disable the bridge after. |\n| `image`     | path                                                                     | The BMC firmware image file (or tarball)                                                                                                 |\n| `sig`       | path                                                                     | The path to a signature file to send to the BMC along with the image file.                                                               |\n| `type`      | blob ending                                                              | The ending of the blob id. For instance `/flash/image` becomes a type of `image`.                                                        |\n\nIf you're using an LPC data transfer mechanism, you'll need two additional\nparameters: `address` and `length`. These values indicate where on the host\nyou've reserved memory to be used for the transfer window.\n\nIf you're using a net data transfer mechanism, you'll also need two additional\nparameters: `hostname` and `port`. These specify which address and port the tool\nshould attempt to connect to the BMC using. If unspecified, the `port` option\ndefaults to 623, the same port as IPMI LAN+.\n\n## Introduction\n\nThis supports three methods of providing the image to stage. You can send the\nfile over IPMI packets, which is a very slow process. A 32-MiB image can take ~3\nhours to send via this method. This can be done in \u003c1 minutes via the PCI or net\nbridge, or just a few minutes via LPC depending on the size of the mapped area.\n\nThis is implemented as a phosphor blob handler.\n\nThe image must be signed via the production or development keys, the former\nbeing required for production builds. The image itself and the image signature\nare separately sent to the BMC for verification. The verification package source\nis beyond the scope of this design.\n\nBasically the IPMI OEM handler receives the image in one fashion or another and\nthen triggers the `verify_image` service. Then, the user polls until the result\nis reported. This is because the image verification process can exceed 10\nseconds.\n\n### Using Legacy Images\n\nThe image flashing mechanism itself is the initramfs stage during reboot. It\nwill check for files named \"`image-*`\" and flash them appropriately for each\nname to section. The IPMI command creates a file `/run/initramfs/bmc-image` and\nwrites the contents there. It was found that writing it in /tmp could cause OOM\nerrors moving it on low memory systems, whereas renaming a file within the same\nfolder seems to only update the directory inode's contents.\n\n### Using UBI\n\nThe staging file path can be controlled via software configuration. The image is\nassumed to be the tarball contents and is written into `/tmp/{tarball_name}.gz`\n\nTODO: Flesh out the UBI approach.\n\n## Configuration\n\nTo use `phosphor-ipmi-flash` a platform must provide a configuration. A platform\ncan configure multiple interfaces, such as both lpc and pci. However, a platform\nshould only configure either static layout updates, or ubi. If enabling lpc, the\nplatform must specify either aspeed or nuvoton. The system also supports\nreceiving BIOS updates.\n\nThe following are the two primary configuration options, which control how the\nupdate is treated.\n\n| Option                   | Meaning                                                 |\n| ------------------------ | ------------------------------------------------------- |\n| `--enable-static-layout` | Enable treating the update as a static layout update.   |\n| `--enable-tarball-ubi`   | Enable treating the update as a tarball for UBI update. |\n| `--enable-host-bios`     | Enable receiving the update for a host bios update.     |\n\nThe following are configuration options for how the host and BMC are meant to\ntransfer the data. By default, the data-in-IPMI mechanism is enabled.\n\nThere are three configurable data transport mechanisms, either staging the bytes\nvia the LPC memory region, the PCI-to-AHB memory region, or sending over a\nnetwork connection. Because there is only one `MAPPED_ADDRESS` variable at\npresent, a platform should not configure LPC and P2A at the same time. The\nplatform's device-tree may have the region locked to a specific driver\n(lpc-aspeed-ctrl), preventing the region from other use.\n\n**_NOTE:_** It will likely be possible to configure both LPC and P2A in the near\nfuture.\n\n| Variable         | Default | Meaning                                                              |\n| ---------------- | ------- | -------------------------------------------------------------------- |\n| `MAPPED_ADDRESS` | 0       | The address used for mapping P2A or LPC into the BMC's memory-space. |\n\nThere are two kinds of PCI device-id for NPCM7xx and NPCM8xx respectively. For\nNPCM7xx the device-id is using 0x0750 and NPCM8xx is using 0x0850. Use this\nvariable that can help to build host tool burn_my_bmc compatible with different\nplatforms and make in-band firmware update work well.\n\n| Variable          | Default | Meaning                               |\n| ----------------- | ------- | ------------------------------------- |\n| `NUVOTON_PCI_DID` | 0x0750  | The device-id for Nuvoton PCI bridge. |\n\nIf a platform enables p2a as the transport mechanism, a specific vendor must be\nselected via the following configuration option. Currently, only one is\nsupported.\n\n| Option                | Meaning                |\n| --------------------- | ---------------------- |\n| `--enable-aspeed-p2a` | Use with ASPEED parts. |\n\nIf a platform enables lpc as the transport mechanism, a specific vendor must be\nselected via the following configuration option. Currently, only two are\nsupported.\n\n| Option                 | Meaning                 |\n| ---------------------- | ----------------------- |\n| `--enable-aspeed-lpc`  | Use with ASPEED parts.  |\n| `--enable-nuvoton-lpc` | Use with Nuvoton parts. |\n\nA platform may also enable the network transport mechanism.\n\nNOTE: This mechanism is only intended to be used in-band and not exposed\nexternally, as it doesn't implement any encryption or integrity verification.\n\n| Option                | Meaning                     |\n| --------------------- | --------------------------- |\n| `--enable-net-bridge` | Enable net transport bridge |\n\nThere are also options to control an optional clean up mechanism.\n\n| Option                    | Meaning                                          |\n| ------------------------- | ------------------------------------------------ |\n| `--enable-cleanup-delete` | Provide a simple blob id that deletes artifacts. |\n\nIf the update mechanism desired is simply a BMC reboot, a platform can just\nenable that directly.\n\n| Option                   | Meaning                                |\n| ------------------------ | -------------------------------------- |\n| `--enable-reboot-update` | Enable use of reboot update mechanism. |\n\nIf you would like the update status to be tracked with a status file, this\noption can be enabled. Note that `--enable-update-status` option and the above\n`--enable-reboot-update` option cannot be enabled at the same time.\n\n| Option                   | Meaning                           |\n| ------------------------ | --------------------------------- |\n| `--enable-update-status` | Enable use of update status file. |\n\nIf you would like to use host memory access to update on a PPC platform, this\nconfiguration option needs to be enabled.\n\n| Option         | Meaning                        |\n| -------------- | ------------------------------ |\n| `--enable-ppc` | Enable PPC host memory access. |\n\n### Internal Configuration Details\n\nThe following variables can be set to whatever you wish, however they have\nusable default values.\n\n| Variable                      | Default                                   | Meaning                                                                   |\n| ----------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- |\n| `STATIC_HANDLER_STAGED_NAME`  | `/run/initramfs/bmc-image`                | The filename where to write the staged firmware image for static updates. |\n| `TARBALL_STAGED_NAME`         | `/tmp/image-update.tar`                   | The filename where to write the UBI update tarball.                       |\n| `HASH_FILENAME`               | `/tmp/bmc.sig`                            | The file to use for the hash provided.                                    |\n| `PREPARATION_DBUS_SERVICE`    | `phosphor-ipmi-flash-bmc-prepare.target`  | The systemd target started when the host starts to send an update.        |\n| `VERIFY_STATUS_FILENAME`      | `/tmp/bmc.verify`                         | The file checked for the verification status.                             |\n| `VERIFY_DBUS_SERVICE`         | `phosphor-ipmi-flash-bmc-verify.target`   | The systemd target started for verification.                              |\n| `UPDATE_DBUS_SERVICE`         | `phosphor-ipmi-flash-bmc-update.target`   | The systemd target started for updating the BMC.                          |\n| `UPDATE_STATUS_FILENAME`      | `/tmp/bmc.update`                         | The file checked for the update status.                                   |\n| `BIOS_STAGED_NAME`            | `/tmp/bios-image`                         | The file to use for staging the bios firmware update.                     |\n| `BIOS_VERIFY_STATUS_FILENAME` | `/tmp/bios.verify`                        | The file checked for the verification status.                             |\n| `PREPARATION_BIOS_TARGET`     | `phosphor-ipmi-flash-bios-prepare.target` | The systemd target when the host starts to send an update.                |\n| `VERIFY_BIOS_TARGET`          | `phosphor-ipmi-flash-bios-verify.target`  | The systemd target started for verification.                              |\n| `UPDATE_BIOS_TARGET`          | `phosphor-ipmi-flash-bios-update.target`  | The systemd target started for updating the BIOS.                         |\n\n## JSON Configuration\n\nRead the [details](bmc_json_config.md) of the json configuration. The json\nconfigurations are used to configure the BMC's flash handler behaviors.\n\n## Flash State Machine Details\n\n[This document](ipmi_flash.md) describes the details of the state machine\nimplemented and how different interactions with it will respond. This also\ndescribes how a host-side tool is expected to talk to it (triggering different\nstates and actions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenbmc%2Fphosphor-ipmi-flash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenbmc%2Fphosphor-ipmi-flash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenbmc%2Fphosphor-ipmi-flash/lists"}