diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 0000000..b6d8dc3 --- /dev/null +++ b/.codespellrc @@ -0,0 +1,2 @@ +[codespell] +write-changes = false diff --git a/.cz.toml b/.cz.toml new file mode 100644 index 0000000..bdff0ce --- /dev/null +++ b/.cz.toml @@ -0,0 +1,21 @@ +[tool.commitizen] +version = "1.0.0" +update_changelog_on_bump = true +tag_format = "v$version" +changelog_start_rev = "v1.0.0" +changelog_merge_prerelease = true +annotated_tag = true +bump_message = "change: Update version to $new_version" +change_type_order = [ + "BREAKING CHANGE", + "New Features", + "Bug Fixes", + "Code Refactoring", + "Performance Improvements" +] + +[tool.commitizen.change_type_map] +feat = "New Features" +fix = "Bug Fixes" +refactor = "Code Refactoring" +perf = "Performance Improvements" diff --git a/.github/workflows/build_and_release.yml b/.github/workflows/build_and_release.yml new file mode 100644 index 0000000..680f8a9 --- /dev/null +++ b/.github/workflows/build_and_release.yml @@ -0,0 +1,77 @@ +name: Build and release + +on: [push] + +jobs: + build_stubs: + runs-on: ubuntu-latest + + steps: + - name: Checkout ref commit + uses: actions/checkout@master + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install esptool + + - name: Build stub + run: | + export TOOLCHAIN_DIR=$HOME/toolchain + + export ESP8266_BINDIR=$TOOLCHAIN_DIR/xtensa-lx106-elf/bin + export ESP32_BINDIR=$TOOLCHAIN_DIR/xtensa-esp32-elf/bin + export ESP32S2_BINDIR=$TOOLCHAIN_DIR/xtensa-esp32s2-elf/bin + export ESP32S3_BINDIR=$TOOLCHAIN_DIR/xtensa-esp32s3-elf/bin + export ESP32C3_BINDIR=$TOOLCHAIN_DIR/riscv32-esp-elf/bin + + export PATH=$PATH:$ESP8266_BINDIR:$ESP32_BINDIR:$ESP32S2_BINDIR:$ESP32S3_BINDIR:$ESP32C3_BINDIR + + ./ci/setup_ci_build_env.sh + make -C flasher_stub V=1 + + - name: Upload stub JSONs + uses: actions/upload-artifact@v4 + with: + path: flasher_stub/build/esp*.json + if-no-files-found: error + retention-days: 3 + + create_release: + name: Create GitHub release + needs: build_stubs + if: startsWith(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Get version + id: get_version + run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT + shell: bash + - name: Checkout + uses: actions/checkout@master + with: + fetch-depth: 0 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install --user commitizen + - name: Generate changelog + run: | + cz changelog ${{ steps.get_version.outputs.VERSION }} --template ci/gh_changelog_template.md.j2 --file-name changelog_body.md + cat changelog_body.md + - name: Download stub JSONs + uses: actions/download-artifact@v4 + - name: Create release + id: create_release + uses: softprops/action-gh-release@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + body_path: changelog_body.md + name: Version ${{ steps.get_version.outputs.VERSION }} + draft: true + prerelease: false + fail_on_unmatched_files: true + files: artifact/esp*.json diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml new file mode 100644 index 0000000..2f0f34f --- /dev/null +++ b/.github/workflows/checks.yml @@ -0,0 +1,23 @@ +name: pre-commit checks + +on: [push] + +jobs: + pre_commit_checks: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Set up Python 3.12 + uses: actions/setup-python@master + with: + python-version: 3.12 + + - name: Run pre-commit hooks + run: | + pip install pre-commit + pre-commit run --show-diff-on-failure --from-ref origin/master --to-ref HEAD diff --git a/.github/workflows/dangerjs.yml b/.github/workflows/dangerjs.yml new file mode 100644 index 0000000..2b077cf --- /dev/null +++ b/.github/workflows/dangerjs.yml @@ -0,0 +1,23 @@ +name: DangerJS Pull Request linter + +on: + pull_request_target: + types: [opened, edited, reopened, synchronize] + +permissions: + pull-requests: write + contents: write + +jobs: + pull-request-style-linter: + runs-on: ubuntu-latest + steps: + - name: Check out PR head + uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha }} + + - name: DangerJS pull request linter + uses: espressif/shared-github-dangerjs@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..17fc34f --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +flasher_stub/build/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..5570e40 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,12 @@ +repos: + - repo: https://github.com/codespell-project/codespell + rev: v2.2.5 + hooks: + - id: codespell + - repo: https://github.com/espressif/conventional-precommit-linter + rev: v1.4.0 + hooks: + - id: conventional-precommit-linter + stages: [commit-msg] +default_stages: [commit] +default_install_hook_types: [pre-commit, commit-msg] diff --git a/README.md b/README.md index 9bbe11c..9b39ffd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # esptool-legacy-flasher-stub -This project is based on the original flasher stub of [esptool](https://github.com/espressif/esptool). It will be deprecated in the near future. It is not advised to base projects on it because it won't receive official support from Espressif Systems. The new and supported flasher stub will the [esp-flasher-stub](https://github.com/esp-rs/esp-flasher-stub) project. +This project is based on the original flasher stub of [esptool](https://github.com/espressif/esptool). It will be deprecated in the near future. It is not advised to base projects on it because it won't receive official support from Espressif Systems. The new and supported flasher stub will be the [esp-flasher-stub](https://github.com/esp-rs/esp-flasher-stub) project. + +# How To Use + +1. Install esptool in [development mode](https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html#development-setup). +2. Obtain the flasher stub binaries as JSON files either from the [releases page](https://github.com/espressif/esptool-legacy-flasher-stub/releases) or from the artifacts of your pull request. +3. Replace the esptool's JSONs files in the `esptool/targets/stub_flasher` directory with the obtained JSON files. ## Issue Tracker @@ -10,6 +16,28 @@ Please report issues in [the esptool repository](https://github.com/espressif/es This flasher stub was initially part of the [esptool](https://github.com/espressif/esptool) project. +## Contributing + +Please install the [pre-commit](https://pre-commit.com/) hooks to ensure that your commits are properly formatted: + +```bash +pip install pre-commit +pre-commit install -t pre-commit -t commit-msg +``` + +# How To Release (For Maintainers Only) + +```bash +pip install commitizen +git fetch +git checkout -b update/release_v1.1.0 +git reset --hard origin/master +cz bump +git push -u +git push --tags +``` +Create a pull request and edit the automatically created draft [release notes](https://github.com/espressif/esptool-legacy-flasher-stub/releases). + ## License This document and the attached source code are released as Free Software under GNU General Public License Version 2 or later. See the accompanying [LICENSE file](https://github.com/espressif/esptool-legacy-flasher-stub/blob/master/LICENSE) for a copy. diff --git a/ci/gh_changelog_template.md.j2 b/ci/gh_changelog_template.md.j2 new file mode 100644 index 0000000..80c33be --- /dev/null +++ b/ci/gh_changelog_template.md.j2 @@ -0,0 +1,20 @@ +{# This changelog template is used for automatically generated GH release notes. #} +{# It is passed to commitizen's --template option in a GH Actions workflow run. #} + +{% for entry in tree %} + +{% for change_key, changes in entry.changes.items() %} + +{% if change_key %} +### {{ change_key }} +{% endif %} + +{% for change in changes %} +{% if change.scope %} +- **{{ change.scope }}**: {{ change.message }} +{% elif change.message %} +- {{ change.message }} +{% endif %} +{% endfor %} +{% endfor %} +{% endfor %} diff --git a/ci/setup_ci_build_env.sh b/ci/setup_ci_build_env.sh new file mode 100755 index 0000000..178bd0e --- /dev/null +++ b/ci/setup_ci_build_env.sh @@ -0,0 +1,44 @@ +#!/bin/bash + +set -exuo pipefail + +ESP8266_TOOLCHAIN_URL="https://dl.espressif.com/dl/xtensa-lx106-elf-linux64-1.22.0-92-g8facf4c-5.2.0.tar.gz" +ESP32_TOOLCHAIN_URL="https://github.com/espressif/crosstool-NG/releases/download/esp-2022r1/xtensa-esp32-elf-gcc11_2_0-esp-2022r1-linux-amd64.tar.xz" +ESP32S2_TOOLCHAIN_URL="https://github.com/espressif/crosstool-NG/releases/download/esp-2022r1/xtensa-esp32s2-elf-gcc11_2_0-esp-2022r1-linux-amd64.tar.xz" +ESP32S3_TOOLCHAIN_URL="https://github.com/espressif/crosstool-NG/releases/download/esp-2022r1/xtensa-esp32s3-elf-gcc11_2_0-esp-2022r1-linux-amd64.tar.xz" +ESP32C3_TOOLCHAIN_URL="https://github.com/espressif/crosstool-NG/releases/download/esp-2022r1/riscv32-esp-elf-gcc11_2_0-esp-2022r1-linux-amd64.tar.xz" + +# Setup shell script to download & configure ESP8266 & ESP32 toolchains +# for building the flasher stub program + +mkdir -p ${TOOLCHAIN_DIR} +cd ${TOOLCHAIN_DIR} + +if ! [ -d ${ESP8266_BINDIR} ]; then + wget --continue --no-verbose "${ESP8266_TOOLCHAIN_URL}" + tar zxf $(basename ${ESP8266_TOOLCHAIN_URL}) +fi + +if ! [ -d ${ESP32_BINDIR} ]; then + # gitlab CI image may already have this file + wget --continue --no-verbose "${ESP32_TOOLCHAIN_URL}" + tar Jxf $(basename ${ESP32_TOOLCHAIN_URL}) +fi + +if ! [ -d ${ESP32S2_BINDIR} ]; then + # gitlab CI image may already have this file + wget --continue --no-verbose "${ESP32S2_TOOLCHAIN_URL}" + tar Jxf $(basename ${ESP32S2_TOOLCHAIN_URL}) +fi + +if ! [ -d ${ESP32S3_BINDIR} ]; then + # gitlab CI image may already have this file + wget --continue --no-verbose "${ESP32S3_TOOLCHAIN_URL}" + tar Jxf $(basename ${ESP32S3_TOOLCHAIN_URL}) +fi + +if ! [ -d ${ESP32C3_BINDIR} ]; then + # gitlab CI image may already have this file + wget --continue --no-verbose "${ESP32C3_TOOLCHAIN_URL}" + tar Jxf $(basename ${ESP32C3_TOOLCHAIN_URL}) +fi diff --git a/flasher_stub/Makefile b/flasher_stub/Makefile index 1d78f4d..0eeb7f9 100644 --- a/flasher_stub/Makefile +++ b/flasher_stub/Makefile @@ -50,27 +50,27 @@ ifneq ("$(V)","1") Q = @ endif -STUB = stub_flasher +STUB = esp SRCS = stub_flasher.c slip.c stub_commands.c stub_write_flash.c stub_io.c SRCS_8266 = miniz.c BUILD_DIR = build -ESPTOOL_STUBS_DIR = ../esptool/targets/stub_flasher - -STUB_ELF_8266 = $(BUILD_DIR)/$(STUB)_8266.elf -STUB_ELF_32 = $(BUILD_DIR)/$(STUB)_32.elf -STUB_ELF_32S2 = $(BUILD_DIR)/$(STUB)_32s2.elf -STUB_ELF_32S3_BETA_2 = $(BUILD_DIR)/$(STUB)_32s3beta2.elf -STUB_ELF_32S3 = $(BUILD_DIR)/$(STUB)_32s3.elf -STUB_ELF_32C3 = $(BUILD_DIR)/$(STUB)_32c3.elf -STUB_ELF_32C6BETA = $(BUILD_DIR)/$(STUB)_32c6beta.elf -STUB_ELF_32H2_BETA_1 = $(BUILD_DIR)/$(STUB)_32h2beta1.elf -STUB_ELF_32H2_BETA_2 = $(BUILD_DIR)/$(STUB)_32h2beta2.elf -STUB_ELF_32C2 = $(BUILD_DIR)/$(STUB)_32c2.elf -STUB_ELF_32C6 = $(BUILD_DIR)/$(STUB)_32c6.elf -STUB_ELF_32C5_BETA_3 = $(BUILD_DIR)/$(STUB)_32c5beta3.elf -STUB_ELF_32H2 = $(BUILD_DIR)/$(STUB)_32h2.elf -STUB_ELF_32P4 = $(BUILD_DIR)/$(STUB)_32p4.elf +ESPTOOL_STUBS_DIR = .. + +STUB_ELF_8266 = $(BUILD_DIR)/$(STUB)8266.elf +STUB_ELF_32 = $(BUILD_DIR)/$(STUB)32.elf +STUB_ELF_32S2 = $(BUILD_DIR)/$(STUB)32s2.elf +STUB_ELF_32S3_BETA_2 = $(BUILD_DIR)/$(STUB)32s3beta2.elf +STUB_ELF_32S3 = $(BUILD_DIR)/$(STUB)32s3.elf +STUB_ELF_32C3 = $(BUILD_DIR)/$(STUB)32c3.elf +STUB_ELF_32C6BETA = $(BUILD_DIR)/$(STUB)32c6beta.elf +STUB_ELF_32H2_BETA_1 = $(BUILD_DIR)/$(STUB)32h2beta1.elf +STUB_ELF_32H2_BETA_2 = $(BUILD_DIR)/$(STUB)32h2beta2.elf +STUB_ELF_32C2 = $(BUILD_DIR)/$(STUB)32c2.elf +STUB_ELF_32C6 = $(BUILD_DIR)/$(STUB)32c6.elf +STUB_ELF_32C5_BETA_3 = $(BUILD_DIR)/$(STUB)32c5beta3.elf +STUB_ELF_32H2 = $(BUILD_DIR)/$(STUB)32h2.elf +STUB_ELF_32P4 = $(BUILD_DIR)/$(STUB)32p4.elf STUBS_ELF = ifneq ($(WITHOUT_ESP8266),1) diff --git a/flasher_stub/compare_stubs.py b/flasher_stub/compare_stubs.py deleted file mode 100755 index 74843f0..0000000 --- a/flasher_stub/compare_stubs.py +++ /dev/null @@ -1,97 +0,0 @@ -#!/usr/bin/env python -# -# SPDX-FileCopyrightText: 2014-2022 Fredrik Ahlberg, Angus Gratton, -# Espressif Systems (Shanghai) CO LTD, other contributors as noted. -# -# SPDX-License-Identifier: GPL-2.0-or-later - -import os -import sys - -import esptool - -# Compare the esptool stub loaders to freshly built ones in the build directory -# -# (Used by CI to verify the stubs are up to date.) - -THIS_SCRIPT_DIR = os.path.dirname(__file__) -STUB_DIR = "../esptool/targets/stub_flasher/" -BUILD_DIR = "build/" -JSON_NAME = "stub_flasher_{}.json" - - -def diff(path_to_new, path_to_old): - output = "" - new = esptool.loader.StubFlasher(path_to_new) - old = esptool.loader.StubFlasher(path_to_old) - - if new.data_start != old.data_start: - output += " Data start: New {:#x}, old {:#x} \n".format( - new.data_start, old.data_start - ) - if new.text_start != old.text_start: - output += " Text start: New {:#x}, old {:#x} \n".format( - new.text_start, old.text_start - ) - if new.entry != old.entry: - output += " Entrypoint: New {:#x}, old {:#x} \n".format(new.entry, old.entry) - - # data - if new.data != old.data: - if len(new.data) == len(old.data): - for i, (new_b, old_b) in enumerate(zip(new.data, old.data)): - if new_b != old_b: - output += " Data byte {:#x}: new {:#04x} old {:#04x} \n".format( - i, new_b, old_b - ) - else: - output += " Data length: New {} bytes, old {} bytes \n".format( - len(new.data), len(old.data) - ) - - # text - if new.text != old.text: - if len(new.text) == len(old.text): - for i, (new_b, old_b) in enumerate(zip(new.text, old.text)): - if new_b != old_b: - output += " Text byte {:#x}: new {:#04x} old {:#04x} \n".format( - i, new_b, old_b - ) - else: - output += " Text length: New {} bytes, old {} bytes \n".format( - len(new.text), len(old.text) - ) - return output - - -if __name__ == "__main__": - same = True - for chip in esptool.CHIP_LIST: - print("Comparing {} stub: ".format(chip), end="") - # TODO: [ESP32C5] ESPTOOL-825 remove when supported stub flasher - # TODO: [ESP32C61] IDF-9241 remove when supported stub flasher - if chip in ["esp32c5", "esp32c61"]: - print(f"{chip} has not supported stub yet, skipping...") - continue - - chip = chip.replace("esp", "") - old = os.path.join(THIS_SCRIPT_DIR, STUB_DIR, JSON_NAME.format(chip)) - new = os.path.join(THIS_SCRIPT_DIR, BUILD_DIR, JSON_NAME.format(chip)) - - output = diff(new, old) - if output != "": - same = False - print("FAIL") - print( - " Mismatch: {} json file in esptool/targets/stub_flasher/ differs " - "from the just-built stub".format("esp" + chip) - ) - print(output) - else: - print("OK") - - if not same: - sys.exit(1) - else: - print("Stub flasher json files are the same") - sys.exit(0)