Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
| docs:techref:image.format [2019/08/04 11:42] – someothertime | docs:techref:image.format [2020/12/14 14:04] (current) – ↷ Links adapted because of a move operation tmomas | ||
|---|---|---|---|
| Line 3: | Line 3: | ||
| You can help to improve this page by adding explanations for the different firmware types below.\\ | You can help to improve this page by adding explanations for the different firmware types below.\\ | ||
| </ | </ | ||
| + | |||
| + | If you are confused by the many different firmware types and extensions in the [[toh: | ||
| ===== Standard formats ===== | ===== Standard formats ===== | ||
| + | ==== factory (.img/.bin) ==== | ||
| + | Use when flashing from OEM ( non-openwrt ) (([[docs: | ||
| - | ==== sysupgrade | + | If only a sysupgrade image is available for your router, either the router |
| - | Previously know as //trx image//, // | + | |
| - | + | ||
| - | ==== factory ==== | + | |
| - | Designed to be flashed by the bootloader flasher or stock firmware | + | |
| + | ==== sysupgrade ( or trx ) ==== | ||
| + | Previously known as //trx image//, // | ||
| ===== Specific formats ===== | ===== Specific formats ===== | ||
| + | ==== ext4 ==== | ||
| + | This firmware contains a regular ext4 Linux partition. Mostly used in x86 and x86_x64 systems. | ||
| + | |||
| + | ==== squashfs ==== | ||
| + | This firmware contains a type of partition that is compressed and mounts read-only. All modifications (file edit, new files, deleted files) are committed to an overlay. | ||
| + | .bin/ | ||
| + | * See also [[docs: | ||
| ==== initramfs ==== | ==== initramfs ==== | ||
| - | Usually first part of a multi-stage installation, | + | Can be loaded from an arbitrary location |
| - | ==== u-boot or uImage ==== | + | An initramfs |
| - | <color # | + | |
| - | ==== ext4 ==== | + | The initramfs-kernel image is used for development or special situations as a one-time boot as a stepping stone toward installing the regular |
| - | This firmware contains | + | |
| - | ==== squashfs | + | initramfs-uImage.bin: |
| - | This firmware contains | + | initramfs-kernel.bin: |
| + | |||
| + | ==== sdcard.img.gz | ||
| + | Used by few devices ( mvebu/RPi etc. ), most often a multi partition | ||
| ==== rootfs ==== | ==== rootfs ==== | ||
| - | Only the root filesystem | + | Only the root filesystem. |
| ==== kernel ==== | ==== kernel ==== | ||
| - | <color # | + | Linux core, generally without compression or appended headers. |
| ==== ubifs ==== | ==== ubifs ==== | ||
| Line 40: | Line 50: | ||
| ==== tftp ==== | ==== tftp ==== | ||
| - | <color # | + | <color # |
| + | ==== u-boot ==== | ||
| + | <color # | ||
| + | ==== ubinized.bin ==== | ||
| + | |||
| + | ==== uImage ==== | ||
| + | This is an image format designed for U-Boot loader, generally consisting of a kernel with a header for information. Often a zImage with a 64 byte uImage header, which contains the load address & entry point of the zImage, so that uBoot knows what to do with it. Further is contains a description of the actual contents (linux kernel, version, …) | ||
| + | |||
| + | ==== zImage ==== | ||
| + | zImage is a compressed plain kernel with a ‘pyggyback’. Some extra code which can decompress the kernel before booting it. | ||
| ===== Subformats ===== | ===== Subformats ===== | ||
| - | |||
| ==== bin, img, elf, dtb, chk, dlf ==== | ==== bin, img, elf, dtb, chk, dlf ==== | ||
| These are raw binary data of the firmware file | These are raw binary data of the firmware file | ||
| Line 50: | Line 68: | ||
| ==== xz, gz, tar, lzma ==== | ==== xz, gz, tar, lzma ==== | ||
| These are compressed images | These are compressed images | ||
| - | |||
| ===== Developer files ===== | ===== Developer files ===== | ||
| - | |||
| ==== sdk ==== | ==== sdk ==== | ||
| SDK Toolchain for compiling single userspace packages ((https:// | SDK Toolchain for compiling single userspace packages ((https:// | ||
| Line 63: | Line 79: | ||
| Linux kernel for build ((https:// | Linux kernel for build ((https:// | ||
| - | + | ====== | |
| - | + | ||
| - | ====== Firmware image names ====== | + | |
| - | ~~NOTOC~~ | + | |
| - | + | ||
| - | If you are confused by the many different firmware types and extensions in the [[toh: | + | |
| - | + | ||
| - | <WRAP center round info 50%> | + | |
| - | You can help to improve this page by adding explanations for the different firmware types below.\\ | + | |
| - | </ | + | |
| - | + | ||
| - | + | ||
| - | <WRAP group> | + | |
| - | <WRAP half column> | + | |
| ===== Firmware types ===== | ===== Firmware types ===== | ||
| - | ^ Target | + | ^ Target ^ Install ^ Upgrade ^ |
| - | | adm5120 | + | | adm5120 | squashfs.bin | squashfs.bin | |
| - | | apm821xx | + | | apm821xx | squashfs-factory.img\\ initramfs-kernel.bin | squashfs-sysupgrade.tar\\ ext4-rootfs.img.gz | |
| - | | ar7 | squashfs.bin\\ squashfs-code.bin | + | | ar7 | squashfs.bin\\ squashfs-code.bin | squashfs.bin | |
| - | | ar71xx | + | | ar71xx | factory.img\\ factory.bin | sysupgrade.bin | |
| - | | at91 | + | | at91 | | | |
| - | | atheros | + | | atheros | squashfs-factory.bin | squashfs-sysupgrade.tar | |
| - | | brcm2708 | + | | brcm2708 | ext4-sdcard.img.gz | - | |
| - | | brcm47xx | + | | brcm47xx | squashfs.bin\\ squashfs.chk\\ squashfs.trx | squashfs.bin\\ squashfs.chk\\ squashfs.trx | |
| - | | bcm53xx | + | | bcm53xx | squashfs.bin\\ squashfs.chk\\ squashfs.trx | \\ squashfs.chk\\ squashfs.trx | |
| - | | brcm63xx | + | | brcm63xx | squashfs-cfe.bin\\ squashfs-factory.chk | squashfs-sysupgrade.bin | |
| - | | cns3xxx | + | | cns3xxx | - | sysupgrade.bin | |
| - | | imx6 | + | | imx6 | ? | ? | |
| - | | ipq806x | + | | ipq806x | factory.img | sysupgrade.tar | |
| - | | ixp4xx | + | | ixp4xx | squashfs.bin\\ squashfs.img\\ zImage | squashfs-sysupgrade.bin | |
| - | | kirkwood | + | | kirkwood | squashfs-factory.bin | squashfs-sysupgrade.bin | |
| - | | lantiq | + | | lantiq | initramfs-kernel.bin\\ squashfs-factory.bin | squashfs-sysupgrade.bin | |
| - | | layerscape | + | | layerscape | squashfs-firmware.bin | - | |
| - | | mpc85xx | + | | mpc85xx | squashfs-factory.bin | squashfs-sysupgrade.bin | |
| - | | mvebu | sdcard.img.gz\\ squashfs-factory.img | + | | mvebu | sdcard.img.gz\\ squashfs-factory.img | \\ squashfs-sysupgrade.bin | |
| - | | mxs | ? | + | | mxs | ? | ? | |
| - | | orion | not supported | + | | orion | not supported | not supported | |
| - | | oxnas | squashfs-ubinized.bin\\ ubifs-ubinized.bin | + | | oxnas | squashfs-ubinized.bin\\ ubifs-ubinized.bin | squashfs-sysupgrade.tar\\ ubifs-sysupgrade.tar | |
| - | | ramips | + | | ramips | initramfs-kernel.bin\\ squashfs-factory.bin\\ squashfs-factory.dlf\\ initramfs-uImage.bin | squashfs-sysupgrade.bin\\ squashfs-sysupgrade.tar | |
| - | | sunxi | ext4-sdcard.img.gz \\ squashfs-sdcard.img.gz | + | | sunxi | ext4-sdcard.img.gz \\ squashfs-sdcard.img.gz | | |
| - | | x86 | combined-ext4.img | + | | x86 | combined-ext4.img | combined-ext4.img.gz | |
| - | </ | + | |
| - | + | ||
| - | <WRAP half column> | + | |
| - | ===== Explanations ===== | + | |
| - | + | ||
| - | ==== factory.img/ | + | |
| - | + | ||
| - | ==== initramfs ==== | + | |
| - | + | ||
| - | An initramfs and initrd are basically the same. It’s a filesystem in memory, which contains userland software. In an embedded environment it might contain the whole distro, on bigger systems it can contain tools& | + | |
| - | + | ||
| - | The initramfs-kernel image is used for development or special situations as a one-time boot as a stepping stone toward installing the regular sysupgrade version. Since the initramfs version runs entirely from RAM, it does not store any settings in flash, so it is not suitable for operational use. | + | |
| - | + | ||
| - | ==== initramfs-uImage.bin ==== | + | |
| - | + | ||
| - | ==== initramfs-kernel.bin ==== | + | |
| - | + | ||
| - | ==== sdcard.img.gz ==== | + | |
| - | + | ||
| - | ==== sysupgrade / factory ==== | + | |
| - | + | ||
| - | There are basically two potential reasons why only a sysupgrade image is available for your router, either the router is already running some kind of OpenWrt fork (which understands the sysupgrade format natively) or there simply is no known way to assemble a factory image accepted by the router.\\ | + | |
| - | < | + | |
| - | + | ||
| - | ==== sysupgrade.bin/ | + | |
| - | + | ||
| - | + | ||
| - | ==== squashfs.bin/ | + | |
| - | + | ||
| - | * See also [[docs: | + | |
| - | + | ||
| - | ==== ubinized.bin ==== | + | |
| - | + | ||
| - | ==== uImage ==== | + | |
| - | + | ||
| - | uImage is (in most cases) a zImage with a 64 byte uImage header, which contains the load address & entry point of the zImage, so that uBoot knows what to do with it. Further is contains a description of the actual contents (linux kernel, version, …) | + | |
| - | + | ||
| - | ==== zImage ==== | + | |
| - | + | ||
| - | zImage is a compressed plain kernel with a ‘pyggyback’. Some extra code which can decompress the kernel before booting it. | + | |
| - | + | ||
| - | </ | + | |
| - | </ | + | |
| - | + | ||
| - | + | ||
| - | + | ||
| ====== Image Formats General ====== | ====== Image Formats General ====== | ||
| Line 160: | Line 116: | ||
| ===== Known Formats ===== | ===== Known Formats ===== | ||
| - | |||
| by extension: | by extension: | ||
| * BIN | * BIN | ||
| Line 169: | Line 124: | ||
| ===== Other Formats ===== | ===== Other Formats ===== | ||
| - | |||
| * see [[docs: | * see [[docs: | ||
| - | * see [[docs: | + | * see [[docs: |