path: root/cpu-docs/espressif-software/esptool_firmware-image-format_esp32p4_v5.3.1.html

<!DOCTYPE html>
<html class="writer-html5" lang="en">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Firmware Image Format - ESP32-P4 -  &mdash; esptool latest documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=a60756f2" />
      <link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css?v=851bd809" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js?v=becddca3"></script>
        <script src="../_static/doctools.js?v=888ff710"></script>
        <script src="../_static/sphinx_highlight.js?v=4825356b"></script>
    <script src="../_static/js/theme.js"></script>

    
        

    <script type="text/javascript">
        DOCUMENTATION_OPTIONS.PAGENAME = 'advanced-topics/firmware-image-format';
        DOCUMENTATION_OPTIONS.PROJECT_SLUG = 'esptool';
        DOCUMENTATION_OPTIONS.LATEST_BRANCH_NAME = 'master';
        DOCUMENTATION_OPTIONS.VERSIONS_URL = '.././_static/esptool_versions.js';
        DOCUMENTATION_OPTIONS.LANGUAGES = ["en"];
        DOCUMENTATION_OPTIONS.IDF_TARGET = 'esp32p4';
        DOCUMENTATION_OPTIONS.HAS_IDF_TARGETS = ["esp8266", "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32h2", "esp32h4", "esp32p4", "esp32c5", "esp32c61", "esp32h21", "esp32s31"]
        DOCUMENTATION_OPTIONS.RELEASE = 'latest';
        DOCUMENTATION_OPTIONS.LANGUAGE_URL = 'en';

    </script>

    <script type="text/javascript" src=".././_static/esptool_versions.js"></script>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Serial Protocol" href="serial-protocol.html" />
    <link rel="prev" title="Advanced Topics" href="index.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            esptool
              <img src="../_static/espressif-logo.svg" class="logo" alt="Logo"/>
          </a>

          
            <div class="selectors">
              <select id="target-select" style="width: 150px;" hidden>
                <option value="" disabled selected>Choose target...</option>
              </select>
            </div>
          

          <div class="selectors">
            <select id="version-select" style="width: 150px;" hidden>
              <option value="" disabled selected>Choose version...</option>
            </select>
          </div>

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../esptool/index.html">Esptool</a></li>
<li class="toctree-l1"><a class="reference internal" href="../espefuse/index.html">Espefuse</a></li>
<li class="toctree-l1"><a class="reference internal" href="../espsecure/index.html">Espsecure</a></li>
<li class="toctree-l1"><a class="reference internal" href="../remote-serial-ports.html">Remote Serial Ports</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Advanced Topics</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Firmware Image Format</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#file-header">File Header</a></li>
<li class="toctree-l3"><a class="reference internal" href="#extended-file-header">Extended File Header</a></li>
<li class="toctree-l3"><a class="reference internal" href="#segment">Segment</a></li>
<li class="toctree-l3"><a class="reference internal" href="#footer">Footer</a></li>
<li class="toctree-l3"><a class="reference internal" href="#analyzing-a-binary-image">Analyzing a Binary Image</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="serial-protocol.html">Serial Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="spi-flash-modes.html">SPI Flash Modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="boot-mode-selection.html">Boot Mode Selection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../troubleshooting.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">Contribute</a></li>
<li class="toctree-l1"><a class="reference internal" href="../versions.html">Versions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../migration-guide.html">Migration Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">esptool</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Advanced Topics</a></li>
      <li class="breadcrumb-item active">Firmware Image Format</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/espressif/esptool/blob/90e9560f/docs/en/advanced-topics/firmware-image-format.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="firmware-image-format">
<span id="image-format"></span><h1>Firmware Image Format<a class="headerlink" href="#firmware-image-format" title="Permalink to this heading"></a></h1>
<p>This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by <code class="docutils literal notranslate"><span class="pre">esptool</span> <span class="pre">elf2image</span></code>.</p>
<figure class="align-center" id="id1">
<div><img height="320" src="../_images/packetdiag-42b115aba712a6574ed718ca9d74eb4fd1142025.png" width="928" /></div><figcaption>
<p><span class="caption-text">Firmware image format</span><a class="headerlink" href="#id1" title="Permalink to this image"></a></p>
</figcaption>
</figure>
<p>The firmware file consists of a header, an extended header, a variable number of data segments and a footer. Multi-byte fields are little-endian.</p>
<section id="file-header">
<h2>File Header<a class="headerlink" href="#file-header" title="Permalink to this heading"></a></h2>
<figure class="align-center" id="id2">
<div><img height="170" src="../_images/packetdiag-1f7336eac0eac9530b7dd0073def52e90038c424.png" width="928" /></div><figcaption>
<p><span class="caption-text">Firmware image header</span><a class="headerlink" href="#id2" title="Permalink to this image"></a></p>
</figcaption>
</figure>
<p>The image header is 8 bytes long:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 15.0%" />
<col style="width: 85.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Byte</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>0</p></td>
<td><p>Magic number (always <code class="docutils literal notranslate"><span class="pre">0xE9</span></code>)</p></td>
</tr>
<tr class="row-odd"><td><p>1</p></td>
<td><p>Number of segments</p></td>
</tr>
<tr class="row-even"><td><p>2</p></td>
<td><p>SPI Flash Mode (<code class="docutils literal notranslate"><span class="pre">0</span></code> = QIO, <code class="docutils literal notranslate"><span class="pre">1</span></code> = QOUT, <code class="docutils literal notranslate"><span class="pre">2</span></code> = DIO, <code class="docutils literal notranslate"><span class="pre">3</span></code> = DOUT)</p></td>
</tr>
<tr class="row-odd"><td><p>3</p></td>
<td><p>High four bits - Flash size (<code class="docutils literal notranslate"><span class="pre">0</span></code> = 1MB, <code class="docutils literal notranslate"><span class="pre">1</span></code> = 2MB, <code class="docutils literal notranslate"><span class="pre">2</span></code> = 4MB, <code class="docutils literal notranslate"><span class="pre">3</span></code> = 8MB, <code class="docutils literal notranslate"><span class="pre">4</span></code> = 16MB, <code class="docutils literal notranslate"><span class="pre">5</span></code> = 32MB, <code class="docutils literal notranslate"><span class="pre">6</span></code> = 64MB)</p>
<p>Low four bits - Flash frequency (<code class="docutils literal notranslate"><span class="pre">0</span></code> = 40MHz, <code class="docutils literal notranslate"><span class="pre">1</span></code> = 26MHz, <code class="docutils literal notranslate"><span class="pre">2</span></code> = 20MHz, <code class="docutils literal notranslate"><span class="pre">0xf</span></code> = 80MHz)</p>
</td>
</tr>
<tr class="row-even"><td><p>4-7</p></td>
<td><p>Entry point address</p></td>
</tr>
</tbody>
</table>
<p><code class="docutils literal notranslate"><span class="pre">esptool</span></code> overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line options (see <a class="reference internal" href="../esptool/flash-modes.html#flash-modes"><span class="std std-ref">Flash Modes</span></a>).
These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of 0x2000).
In this case, the appended SHA256 digest, which is a cryptographic hash used to verify the integrity of the image, is also updated to reflect the header changes.
Generating images without SHA256 digest can be achieved by running <code class="docutils literal notranslate"><span class="pre">esptool</span> <span class="pre">elf2image</span></code> with the <code class="docutils literal notranslate"><span class="pre">--dont-append-digest</span></code> argument.</p>
</section>
<section id="extended-file-header">
<h2>Extended File Header<a class="headerlink" href="#extended-file-header" title="Permalink to this heading"></a></h2>
<figure class="align-center" id="id3">
<div><img height="170" src="../_images/packetdiag-027e6c21fd476653802b64490edef0a0e57462d2.png" width="928" /></div><figcaption>
<p><span class="caption-text">Extended File Header</span><a class="headerlink" href="#id3" title="Permalink to this image"></a></p>
</figcaption>
</figure>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Byte</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>0</p></td>
<td><p>WP pin when SPI pins set via eFuse (read by ROM bootloader)</p></td>
</tr>
<tr class="row-odd"><td><p>1-3</p></td>
<td><p>Drive settings for the SPI flash pins (read by ROM bootloader)</p></td>
</tr>
<tr class="row-even"><td><p>4-5</p></td>
<td><p>Chip ID (which ESP device is this image for)</p></td>
</tr>
<tr class="row-odd"><td><p>6</p></td>
<td><p>Minimal chip revision supported by the image (deprecated, use the following field)</p></td>
</tr>
<tr class="row-even"><td><p>7-8</p></td>
<td><p>Minimal chip revision supported by the image (in format: major * 100 + minor)</p></td>
</tr>
<tr class="row-odd"><td><p>9-10</p></td>
<td><p>Maximal chip revision supported by the image (in format: major * 100 + minor)</p></td>
</tr>
<tr class="row-even"><td><p>11-14</p></td>
<td><p>Reserved bytes in additional header space, currently unused</p></td>
</tr>
<tr class="row-odd"><td><p>15</p></td>
<td><p>Hash appended (If 1, SHA256 digest is appended after the checksum)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="segment">
<h2>Segment<a class="headerlink" href="#segment" title="Permalink to this heading"></a></h2>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Byte</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>0-3</p></td>
<td><p>Memory offset</p></td>
</tr>
<tr class="row-odd"><td><p>4-7</p></td>
<td><p>Segment size</p></td>
</tr>
<tr class="row-even"><td><p>8…n</p></td>
<td><p>Data</p></td>
</tr>
</tbody>
</table>
</section>
<section id="footer">
<h2>Footer<a class="headerlink" href="#footer" title="Permalink to this heading"></a></h2>
<p>The file is padded with zeros until its size is one byte less than a multiple of 16 bytes. A last byte (thus making the file size a multiple of 16) is the checksum of the data of all segments. The checksum is defined as the xor-sum of all bytes and the byte <code class="docutils literal notranslate"><span class="pre">0xEF</span></code>.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">hash</span> <span class="pre">appended</span></code> in the extended file header is <code class="docutils literal notranslate"><span class="pre">0x01</span></code>, a SHA256 digest “simple hash” (of the entire image) is appended after the checksum. This digest is separate to secure boot and only used for detecting corruption. The SPI flash info cannot be changed during flashing if hash is appended after the image.</p>
<p>If secure boot is enabled, a signature is also appended (and the simple hash is included in the signed data). This image signature is <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v1.html#image-signing-algorithm">Secure Boot V1</a> and <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html#signature-block-format">Secure Boot V2</a> specific.</p>
</section>
<section id="analyzing-a-binary-image">
<h2>Analyzing a Binary Image<a class="headerlink" href="#analyzing-a-binary-image" title="Permalink to this heading"></a></h2>
<p>To analyze a binary image and get a complete summary of its headers and segments, use the <a class="reference internal" href="../esptool/basic-commands.html#image-info"><span class="std std-ref">image-info</span></a> command.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="index.html" class="btn btn-neutral float-left" title="Advanced Topics" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="serial-protocol.html" class="btn btn-neutral float-right" title="Serial Protocol" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd.</p>
  </div>

  <ul class="footer">
        <li>
	    
            
            Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/espressif/sphinx_idf_theme">theme</a>  based on <a href="https://github.com/readthedocs/sphinx_rtd_theme">Read the Docs Sphinx Theme</a>.
         </li>

  </ul> 

</footer>
        </div>
      </div>
    </section>
  </div>

  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>