Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .ci/scripts/test_espressif.sh
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,16 @@ for entry in json.load(open(sys.argv[1])):
' "${build_dir}/espnn-tests/manifest.json")

if [[ "${espnn_kernels}" == optimized ]]; then
esp_python_dir=$(python -c 'import executorch.backends.espressif as esp; print(next(iter(esp.__path__)))')
logged "scratch-configure.log" cmake -S . \
-B "${build_dir}/scratch-sizing" -DCMAKE_BUILD_TYPE=Release \
-DEXECUTORCH_BUILD_ESP_NN_PYBINDS=ON -DEXECUTORCH_OPTIMIZE_SIZE=ON \
-DESPNN_LOCAL_PATH="${PWD}/examples/espressif/project/managed_components/espressif__esp-nn" \
-DCMAKE_LIBRARY_OUTPUT_DIRECTORY="${esp_python_dir}"
logged "scratch-build.log" cmake --build "${build_dir}/scratch-sizing" \
--target _esp_nn_scratch
logged "scratch-tests.log" env EXECUTORCH_REQUIRE_ESP_NN_SCRATCH=1 \
python -m pytest -q backends/espressif/test/test_scratch.py
# Stop on failure so later cases cannot overwrite its firmware and logs.
ESPRESSIF_BUILD_DIR="${build_dir}" python -m pytest \
-x -v --tb=short backends/espressif/test/ops -k implementation \
Expand Down
5 changes: 5 additions & 0 deletions .github/workflows/test-espressif.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ on:
# Read for the torch the component's VERSION and README name.
- install_requirements.py
- install_utils.py
# Build and package the optional ESP-NN scratch bindings.
- setup.py
- CMakeLists.txt
- tools/cmake/preset/default.cmake
- third-party/pybind11
# Exported by the consumer test.
- examples/models/mlperf_tiny/**
- devtools/bundled_program/**
Expand Down
4 changes: 4 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -895,6 +895,10 @@ if(EXECUTORCH_BUILD_CORTEX_M OR EXECUTORCH_BUILD_CMSIS_NN_PYBINDS)
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/backends/cortex_m)
endif()

if(EXECUTORCH_BUILD_ESP_NN_PYBINDS)
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/backends/espressif/scratch)
endif()

# Find Torch at root scope when any enabled component needs it so imported
# targets (e.g. MKL::MKL) aren't created independently in child scopes.
if(EXECUTORCH_BUILD_CUDA
Expand Down
54 changes: 54 additions & 0 deletions backends/espressif/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,60 @@ Spatial operators use contiguous NHWC tensors; model inputs and outputs
retain their original layout. Layout copies remain visible in the
operator-library report.

## Scratch-size queries

Optional Python bindings expose ESP-NN 1.5.0's convolution, depthwise, softmax,
mean, hard-swish, batched fully connected, and logistic scratch-size queries:

```bash
CMAKE_ARGS="-DEXECUTORCH_BUILD_ESP_NN_PYBINDS=ON" pip install -e . --no-build-isolation
```

The host libraries retain only sizing code. CMake fetches the pinned ESP-NN
sources; `ESP_NN_LOCAL_PATH` can reuse an existing 1.5.0 checkout or ESP-IDF
managed component. The host build uses GNU-style compiler section flags and
linker garbage collection (`--gc-sections`, or `-dead_strip` on Apple platforms);
MSVC-style toolchains fail at configuration. Downloaded sources are checked
against the pinned SHA-256, and a local source tree must declare version 1.5.0.

Select the device's `EspTarget` and `EspKernelMode` to match its ESP-NN build:

```python
from executorch.backends.espressif import EspKernelMode, EspTarget
from executorch.backends.espressif.scratch import get_scratch_queries

queries = get_scratch_queries(EspTarget.ESP32P4, EspKernelMode.OPTIMIZED)
if queries is not None:
scratch_bytes = queries.conv2d_scratch_size(
input_dims=(8, 8, 16),
filter_dims=(3, 3, 16),
output_dims=(8, 8, 32),
stride=(1, 1),
padding=(1, 1),
)
```

Convolution queries use `(width, height, channels)` for dimensions,
`(width, height)` for stride and padding, and unit dilation. Dimensions,
strides, and depthwise channel multipliers must be in `[1, 65535]`; padding must be in
`[0, 65535]`. Conservative bounds on padded tensors, aligned filters, staging,
and coordinates reject shapes that could overflow the vendor's int32 arithmetic
before calling the sizing query. These bounds also apply to the fully connected
query's `row_len` and `out_ch`. Softmax and mean dimensions, and fully connected
`batches`, must be positive int32 values; softmax width must also fit an int32
byte count for four bytes per element. Invalid bounds raise `ValueError`.
Sizes are in bytes, including zero for kernels that need no scratch. The vendor
fully connected query also returns zero for batches above 65535.
`get_scratch_queries` returns `None` only when the selected module is absent;
errors loading an installed binding propagate to the caller.

Optimized mode selects S3 queries for ESP32-S3, shared PIE queries for
ESP32-P4/ESP32-S31, and generic queries for other `EspTarget` values. ANSI mode
selects ANSI queries for every chip. Query results are checked on the host for
all configurations; device execution tests currently cover ESP32-S3.
CI sets `EXECUTORCH_REQUIRE_ESP_NN_SCRATCH=1` when running `test_scratch.py`, so
all four profiles and all seven query families must be available and pass.

## Contents

```
Expand Down
3 changes: 3 additions & 0 deletions backends/espressif/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,15 @@
)
from .partition import EspNNPartitioner
from .quantizer import EspNNQuantizer, get_esp_fused_quant_quantizer
from .target import EspKernelMode, EspTarget

__all__ = [
"EspNNBackend",
"EspNNPartitioner",
"EspNNQuantizer",
"get_esp_fused_quant_quantizer",
"EspTarget",
"EspKernelMode",
"to_espnn_edge",
"get_esp_fused_quant_recipe",
"get_operator_library_report",
Expand Down
86 changes: 86 additions & 0 deletions backends/espressif/scratch/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.
#
# This source code is licensed under the BSD-style license found in the
# LICENSE file in the root directory of this source tree.

cmake_minimum_required(VERSION 3.24)
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
project(esp_nn_scratch LANGUAGES C CXX)
endif()

if(MSVC
OR CMAKE_C_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC"
OR CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC"
)
message(
FATAL_ERROR
"ESP-NN scratch bindings require GNU-style section flags; MSVC-style toolchains are unsupported."
)
endif()

include(${CMAKE_CURRENT_LIST_DIR}/../esp_nn_sources.cmake)

find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
if(NOT TARGET pybind11::module)
add_subdirectory(
"${CMAKE_CURRENT_SOURCE_DIR}/../../../third-party/pybind11"
"${CMAKE_CURRENT_BINARY_DIR}/pybind11"
)
endif()
set(common_sources
src/convolution/esp_nn_conv_ansi.c
src/convolution/esp_nn_depthwise_conv_ansi.c
src/softmax/esp_nn_softmax_ansi.c
src/common/esp_nn_mean_ansi.c
src/activation_functions/esp_nn_hard_swish_ansi.c
src/logistic/esp_nn_logistic_ansi.c
src/fully_connected/esp_nn_fully_connected_ansi.c
)
set(esp32s3_sources
src/convolution/esp_nn_scratch_sizes_esp32s3.c
src/common/esp_nn_mean_s8_esp32s3.c
src/activation_functions/esp_nn_hard_swish_s8_esp32s3.c
)
set(riscv_pie_sources src/convolution/esp_nn_scratch_sizes_riscv_pie.c)
set(generic_sources
src/convolution/esp_nn_conv_opt.c
src/convolution/esp_nn_depthwise_conv_opt.c
src/softmax/esp_nn_softmax_opt.c
)

add_custom_target(_esp_nn_scratch)
foreach(profile esp32s3 riscv_pie generic ansi)
set(sources ${common_sources} ${${profile}_sources})
list(TRANSFORM sources PREPEND "${espnn_source_dir}/")
set(module "_esp_nn_scratch_${profile}")
pybind11_add_module(${module} MODULE bindings.cpp ${sources})
target_compile_features(${module} PRIVATE cxx_std_17)
add_dependencies(_esp_nn_scratch ${module})
target_include_directories(
${module}
PRIVATE "${espnn_source_dir}/include" "${espnn_source_dir}/src/common"
"${espnn_source_dir}/src/convolution"
)
target_compile_definitions(${module} PRIVATE ESP_NN_SCRATCH_MODULE=${module})
if(NOT profile STREQUAL "ansi")
target_compile_definitions(${module} PRIVATE CONFIG_NN_OPTIMIZED=1)
endif()
if(profile STREQUAL "esp32s3")
target_compile_definitions(${module} PRIVATE CONFIG_IDF_TARGET_ESP32S3=1)
elseif(profile STREQUAL "riscv_pie")
target_compile_definitions(${module} PRIVATE CONFIG_IDF_TARGET_ESP32P4=1)
endif()

# Some getters share a source file with kernels; retain only the sizing code.
set_target_properties(${module} PROPERTIES C_VISIBILITY_PRESET hidden)
target_compile_options(
${module} PRIVATE -ffunction-sections -fdata-sections
"$<$<COMPILE_LANGUAGE:CXX>:-fexceptions;-frtti>"
)
if(APPLE)
target_link_options(${module} PRIVATE -Wl,-dead_strip)
else()
target_link_options(${module} PRIVATE -Wl,--gc-sections)
endif()
endforeach()
33 changes: 33 additions & 0 deletions backends/espressif/scratch/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.
#
# This source code is licensed under the BSD-style license found in the
# LICENSE file in the root directory of this source tree.

import importlib
from types import ModuleType

from executorch.backends.espressif.target import EspKernelMode, EspTarget


def get_scratch_queries(
target: EspTarget, kernel_mode: EspKernelMode
) -> ModuleType | None:
"""Load the vendor getters selected by ESP-NN's device configuration."""
target = EspTarget(target)
kernel_mode = EspKernelMode(kernel_mode)
if kernel_mode == EspKernelMode.ANSI:
profile = "ansi"
else:
profile = {
EspTarget.ESP32S3: "esp32s3",
EspTarget.ESP32P4: "riscv_pie",
EspTarget.ESP32S31: "riscv_pie",
}.get(target, "generic")
module_name = f"executorch.backends.espressif._esp_nn_scratch_{profile}"
try:
return importlib.import_module(module_name)
except ModuleNotFoundError as error:
if error.name == module_name:
return None
raise
Loading
Loading