diff --git a/.ci/scripts/test_espressif.sh b/.ci/scripts/test_espressif.sh index ad39d32428a..c6af4d2e444 100644 --- a/.ci/scripts/test_espressif.sh +++ b/.ci/scripts/test_espressif.sh @@ -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 \ diff --git a/.github/workflows/test-espressif.yml b/.github/workflows/test-espressif.yml index 02903d1e878..3b1bca5ebe5 100644 --- a/.github/workflows/test-espressif.yml +++ b/.github/workflows/test-espressif.yml @@ -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/** diff --git a/CMakeLists.txt b/CMakeLists.txt index 85bf43fcd62..2004ebc4e77 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -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 diff --git a/backends/espressif/README.md b/backends/espressif/README.md index 19844b6be7d..516690fbeb5 100644 --- a/backends/espressif/README.md +++ b/backends/espressif/README.md @@ -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 ``` diff --git a/backends/espressif/__init__.py b/backends/espressif/__init__.py index af4bb460967..dd54776ab7c 100644 --- a/backends/espressif/__init__.py +++ b/backends/espressif/__init__.py @@ -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", diff --git a/backends/espressif/scratch/CMakeLists.txt b/backends/espressif/scratch/CMakeLists.txt new file mode 100644 index 00000000000..25f4cf1d8a7 --- /dev/null +++ b/backends/espressif/scratch/CMakeLists.txt @@ -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 + "$<$:-fexceptions;-frtti>" + ) + if(APPLE) + target_link_options(${module} PRIVATE -Wl,-dead_strip) + else() + target_link_options(${module} PRIVATE -Wl,--gc-sections) + endif() +endforeach() diff --git a/backends/espressif/scratch/__init__.py b/backends/espressif/scratch/__init__.py new file mode 100644 index 00000000000..6211cc0b881 --- /dev/null +++ b/backends/espressif/scratch/__init__.py @@ -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 diff --git a/backends/espressif/scratch/bindings.cpp b/backends/espressif/scratch/bindings.cpp new file mode 100644 index 00000000000..5ab76a81aed --- /dev/null +++ b/backends/espressif/scratch/bindings.cpp @@ -0,0 +1,223 @@ +/* + * 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. + */ + +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include + +namespace { + +template +void check_bounds( + const std::array& values, + const char* name, + int32_t minimum = 1, + int32_t maximum = std::numeric_limits::max()) { + if (std::any_of(values.begin(), values.end(), [=](int32_t value) { + return value < minimum || value > maximum; + })) { + throw pybind11::value_error( + std::string(name) + " must be in [" + std::to_string(minimum) + ", " + + std::to_string(maximum) + "]"); + } +} + +int64_t checked_product(std::initializer_list factors) { + int64_t product = 1; + for (const auto factor : factors) { + if (factor > std::numeric_limits::max() / product) { + throw pybind11::value_error( + "scratch query intermediates exceed the int32 range"); + } + product *= factor; + } + return product; +} + +void check_conv_arithmetic( + const std::array& input, + const std::array& filter, + const std::array& output, + const std::array& stride, + const std::array& padding, + int32_t channel_multiplier = 1) { + const int64_t aligned_channels = (int64_t{input[2]} + 15) & ~int64_t{15}; + const int64_t output_channels = + std::max(int64_t{output[2]}, int64_t{input[2]} * channel_multiplier); + std::array extent; + for (std::size_t axis = 0; axis < extent.size(); ++axis) { + extent[axis] = + std::max(int64_t{input[axis]}, int64_t{output[axis]} * stride[axis]) + + 2 * int64_t{padding[axis]} + filter[axis]; + } + // Bound padded copies, aligned filters and coordinates before vendor int32 + // arithmetic. S3 stages 16 windows plus 24 windows of panel work and a 16 KiB + // panel. Four int32 channel arrays and 256 bytes cover parameters and + // alignment. + const auto input_bound = + checked_product({extent[0], extent[1], aligned_channels}); + const auto filter_bound = checked_product( + {int64_t{filter[0]} * aligned_channels + 15, filter[1], output_channels}); + const auto output_bound = checked_product( + {output[0], output[1], std::max(aligned_channels, output_channels)}); + const auto window_bound = + checked_product({filter[0], filter[1], aligned_channels}); + const auto bound = 2 * input_bound + 2 * filter_bound + output_bound + + 40 * window_bound + 16 * std::max(aligned_channels, output_channels) + + 16 * 1024 + 256; + if (bound > std::numeric_limits::max()) { + throw pybind11::value_error( + "scratch query intermediates exceed the int32 range"); + } +} + +int conv2d_scratch_size( + std::array input_dims, + std::array filter_dims, + std::array output_dims, + std::array stride, + std::array padding) { + check_bounds(input_dims, "input_dims"); + check_bounds(filter_dims, "filter_dims"); + check_bounds(output_dims, "output_dims"); + check_bounds(stride, "stride"); + check_bounds(padding, "padding", 0); + check_conv_arithmetic(input_dims, filter_dims, output_dims, stride, padding); + const data_dims_t input{input_dims[0], input_dims[1], input_dims[2], 0}; + const data_dims_t filter{filter_dims[0], filter_dims[1], filter_dims[2], 0}; + const data_dims_t output{output_dims[0], output_dims[1], output_dims[2], 0}; + conv_params_t params{}; + params.stride = {stride[0], stride[1]}; + params.padding = {padding[0], padding[1]}; + params.dilation = {1, 1}; + return esp_nn_get_conv_scratch_size(&input, &filter, &output, ¶ms); +} + +int depthwise_conv2d_scratch_size( + std::array input_dims, + std::array filter_dims, + std::array output_dims, + std::array stride, + std::array padding, + int32_t channel_multiplier) { + check_bounds(input_dims, "input_dims"); + check_bounds(filter_dims, "filter_dims"); + check_bounds(output_dims, "output_dims"); + check_bounds(stride, "stride"); + check_bounds(padding, "padding", 0); + check_bounds(std::array{channel_multiplier}, "channel_multiplier"); + check_conv_arithmetic( + input_dims, + filter_dims, + output_dims, + stride, + padding, + channel_multiplier); + const data_dims_t input{input_dims[0], input_dims[1], input_dims[2], 0}; + const data_dims_t filter{filter_dims[0], filter_dims[1], filter_dims[2], 0}; + const data_dims_t output{output_dims[0], output_dims[1], output_dims[2], 0}; + dw_conv_params_t params{}; + params.ch_mult = channel_multiplier; + params.stride = {stride[0], stride[1]}; + params.padding = {padding[0], padding[1]}; + params.dilation = {1, 1}; + return esp_nn_get_depthwise_conv_scratch_size( + &input, &filter, &output, ¶ms); +} + +int32_t softmax_scratch_size(int32_t width, int32_t height) { + check_bounds( + std::array{width, height}, + "softmax dimensions", + 1, + std::numeric_limits::max()); + checked_product({width, sizeof(int32_t)}); + return esp_nn_get_softmax_scratch_size(width, height); +} + +int32_t mean_scratch_size(int32_t height, int32_t width, int32_t channels) { + check_bounds( + std::array{height, width, channels}, + "mean dimensions", + 1, + std::numeric_limits::max()); + return esp_nn_get_mean_scratch_size(height, width, channels); +} + +int fc_batch_scratch_size(int32_t batches, int32_t row_len, int32_t out_ch) { + check_bounds( + std::array{batches}, "batches", 1, std::numeric_limits::max()); + check_bounds(std::array{row_len}, "row_len"); + check_bounds(std::array{out_ch}, "out_ch"); + if (batches <= std::numeric_limits::max()) { + check_conv_arithmetic( + {1, batches, row_len}, + {1, 1, row_len}, + {1, batches, out_ch}, + {1, 1}, + {0, 0}); + } + return esp_nn_get_fc_batch_scratch_size( + batches, static_cast(row_len), static_cast(out_ch)); +} + +} // namespace + +namespace py = pybind11; + +PYBIND11_MODULE(ESP_NN_SCRATCH_MODULE, m) { + m.doc() = + "ESP-NN scratch sizes in bytes. Dimensions use (width, height, " + "channels); stride and padding use (width, height)."; + m.def( + "conv2d_scratch_size", + &conv2d_scratch_size, + py::arg("input_dims"), + py::arg("filter_dims"), + py::arg("output_dims"), + py::arg("stride"), + py::arg("padding")); + m.def( + "depthwise_conv2d_scratch_size", + &depthwise_conv2d_scratch_size, + py::arg("input_dims"), + py::arg("filter_dims"), + py::arg("output_dims"), + py::arg("stride"), + py::arg("padding"), + py::arg("channel_multiplier")); + m.def( + "softmax_scratch_size", + &softmax_scratch_size, + py::arg("width"), + py::arg("height")); + m.def( + "mean_scratch_size", + &mean_scratch_size, + py::arg("height"), + py::arg("width"), + py::arg("channels")); + m.def("hard_swish_scratch_size", []() { + return esp_nn_get_hard_swish_scratch_size(); + }); + m.def( + "fc_batch_scratch_size", + &fc_batch_scratch_size, + py::arg("batches"), + py::arg("row_len"), + py::arg("out_ch")); + m.def("logistic_scratch_size", &esp_nn_get_logistic_s8_scratch_size); +} diff --git a/backends/espressif/target.py b/backends/espressif/target.py new file mode 100644 index 00000000000..8a2f675a5f7 --- /dev/null +++ b/backends/espressif/target.py @@ -0,0 +1,28 @@ +# 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. + +from enum import Enum + + +class EspTarget(str, Enum): + ESP32 = "esp32" + ESP32S2 = "esp32s2" + ESP32S3 = "esp32s3" + ESP32P4 = "esp32p4" + ESP32S31 = "esp32s31" + ESP32C2 = "esp32c2" + ESP32C3 = "esp32c3" + ESP32C5 = "esp32c5" + ESP32C6 = "esp32c6" + ESP32C61 = "esp32c61" + ESP32H2 = "esp32h2" + ESP32H21 = "esp32h21" + ESP32H4 = "esp32h4" + + +class EspKernelMode(str, Enum): + OPTIMIZED = "optimized" + ANSI = "ansi" diff --git a/backends/espressif/test/test_scratch.py b/backends/espressif/test/test_scratch.py new file mode 100644 index 00000000000..512a92fe348 --- /dev/null +++ b/backends/espressif/test/test_scratch.py @@ -0,0 +1,248 @@ +# 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 os +import sys + +import pytest +from executorch.backends.espressif.scratch import get_scratch_queries +from executorch.backends.espressif.target import EspKernelMode, EspTarget + + +def _scratch_queries(target, kernel_mode): + queries = get_scratch_queries(target, kernel_mode) + if queries is None: + if os.environ.get("EXECUTORCH_REQUIRE_ESP_NN_SCRATCH") == "1": + pytest.fail( + f"Required ESP-NN scratch binding missing: {target}/{kernel_mode}" + ) + pytest.skip("Build with EXECUTORCH_BUILD_ESP_NN_PYBINDS=ON") + return queries + + +@pytest.mark.parametrize("target", list(EspTarget)) +@pytest.mark.parametrize("kernel_mode", list(EspKernelMode)) +def test_vendor_scratch_queries(target, kernel_mode): + queries = _scratch_queries(target, kernel_mode) + if kernel_mode == EspKernelMode.ANSI: + expected = (0, 0, 0, 0, 0, 0, 256) + elif target == EspTarget.ESP32S3: + expected = (4928, 32, 2064, 0, 512, 704, 256) + elif target in (EspTarget.ESP32P4, EspTarget.ESP32S31): + expected = (1808, 0, 2064, 0, 0, 800, 256) + else: + expected = (0, 0, 128, 0, 0, 0, 256) + conv_args = { + "input_dims": (11, 7, 16), + "filter_dims": (3, 2, 16), + "output_dims": (6, 4, 32), + "stride": (2, 2), + "padding": (1, 1), + } + assert ( + queries.conv2d_scratch_size(**conv_args), + queries.depthwise_conv2d_scratch_size(**conv_args, channel_multiplier=2), + queries.softmax_scratch_size(width=32, height=8), + queries.mean_scratch_size(height=8, width=8, channels=16), + queries.hard_swish_scratch_size(), + queries.fc_batch_scratch_size(batches=8, row_len=16, out_ch=32), + queries.logistic_scratch_size(), + ) == expected + + +@pytest.mark.parametrize("dimension", ["row_len", "out_ch"]) +@pytest.mark.parametrize("value", [-1, 0, 65536]) +def test_fc_dimension_bounds(dimension, value): + queries = _scratch_queries(EspTarget.ESP32S3, EspKernelMode.OPTIMIZED) + args = {"batches": 8, "row_len": 16, "out_ch": 32} + args[dimension] = value + with pytest.raises(ValueError, match=dimension): + queries.fc_batch_scratch_size(**args) + + +@pytest.fixture( + params=[ + (EspTarget.ESP32S3, EspKernelMode.OPTIMIZED), + (EspTarget.ESP32P4, EspKernelMode.OPTIMIZED), + (EspTarget.ESP32, EspKernelMode.OPTIMIZED), + (EspTarget.ESP32S3, EspKernelMode.ANSI), + ], + ids=["s3", "pie", "generic", "ansi"], +) +def scratch_queries(request): + return _scratch_queries(*request.param) + + +@pytest.mark.parametrize("depthwise", [False, True], ids=["conv", "depthwise"]) +@pytest.mark.parametrize( + "argument,value", + [ + (argument, value) + for argument in ("input_dims", "filter_dims", "output_dims", "stride") + for value in (-1, 0, 65536) + ] + + [("padding", -1), ("padding", 65536)], +) +def test_convolution_dimension_bounds(scratch_queries, depthwise, argument, value): + args = { + "input_dims": (8, 8, 3), + "filter_dims": (1, 1, 3), + "output_dims": (8, 8, 16), + "stride": (1, 1), + "padding": (0, 0), + } + query = scratch_queries.conv2d_scratch_size + if depthwise: + query = scratch_queries.depthwise_conv2d_scratch_size + args["output_dims"] = (8, 8, 3) + args["channel_multiplier"] = 1 + for axis in range(len(args[argument])): + invalid = list(args[argument]) + invalid[axis] = value + with pytest.raises(ValueError, match=argument): + query(**{**args, argument: tuple(invalid)}) + + +def test_convolution_dimension_boundaries(scratch_queries): + expected = { + "_esp_nn_scratch_esp32s3": (192, 32), + "_esp_nn_scratch_riscv_pie": (84, 0), + "_esp_nn_scratch_generic": (0, 0), + "_esp_nn_scratch_ansi": (0, 0), + }[scratch_queries.__name__.rsplit(".", 1)[-1]] + assert ( + scratch_queries.conv2d_scratch_size( + input_dims=(65535, 1, 1), + filter_dims=(1, 1, 1), + output_dims=(65535, 1, 1), + stride=(1, 1), + padding=(0, 0), + ), + scratch_queries.depthwise_conv2d_scratch_size( + input_dims=(1, 1, 1), + filter_dims=(1, 1, 1), + output_dims=(1, 1, 65535), + stride=(1, 1), + padding=(0, 0), + channel_multiplier=65535, + ), + ) == expected + + +@pytest.mark.parametrize("depthwise", [False, True], ids=["conv", "depthwise"]) +@pytest.mark.parametrize( + "input_dims,filter_dims,output_dims,stride,padding", + [ + ((32766, 32766, 2), (2, 2, 2), (32767, 32767, 1), (1, 1), (1, 1)), + ((65534, 65534, 1), (2, 2, 1), (65535, 65535, 1), (1, 1), (1, 1)), + ((1, 1, 16), (65535, 65535, 16), (1, 1, 16), (1, 1), (0, 0)), + ((1, 1, 1), (2, 2, 1), (65535, 65535, 1), (65535, 65535), (0, 0)), + ], + ids=["negative_size", "positive_wrapped_size", "filter_product", "coordinates"], +) +def test_convolution_arithmetic_bounds( + scratch_queries, depthwise, input_dims, filter_dims, output_dims, stride, padding +): + args = { + "input_dims": input_dims, + "filter_dims": filter_dims, + "output_dims": output_dims, + "stride": stride, + "padding": padding, + } + query = scratch_queries.conv2d_scratch_size + if depthwise: + query = scratch_queries.depthwise_conv2d_scratch_size + args["channel_multiplier"] = 1 + with pytest.raises(ValueError, match="int32 range"): + query(**args) + + +@pytest.mark.parametrize("width", [2**29, 2**30]) +def test_softmax_arithmetic_bounds(scratch_queries, width): + with pytest.raises(ValueError, match="int32 range"): + scratch_queries.softmax_scratch_size(width=width, height=1) + + +@pytest.mark.parametrize("value", [-1, 0]) +def test_scalar_dimension_bounds(scratch_queries, value): + with pytest.raises(ValueError, match="softmax dimensions"): + scratch_queries.softmax_scratch_size(width=value, height=1) + with pytest.raises(ValueError, match="softmax dimensions"): + scratch_queries.softmax_scratch_size(width=1, height=value) + for axis in range(3): + dims = [1, 1, 1] + dims[axis] = value + with pytest.raises(ValueError, match="mean dimensions"): + scratch_queries.mean_scratch_size(*dims) + with pytest.raises(ValueError, match="batches"): + scratch_queries.fc_batch_scratch_size(batches=value, row_len=16, out_ch=32) + + +def test_fc_arithmetic_bounds(scratch_queries): + with pytest.raises(ValueError, match="int32 range"): + scratch_queries.fc_batch_scratch_size(batches=1, row_len=65535, out_ch=32768) + + +def test_fc_batches_without_scratch(scratch_queries): + assert scratch_queries.fc_batch_scratch_size(65536, 16, 32) == 0 + + +@pytest.mark.parametrize("value", [-1, 0, 65536]) +def test_depthwise_multiplier_bounds(scratch_queries, value): + with pytest.raises(ValueError, match="channel_multiplier"): + scratch_queries.depthwise_conv2d_scratch_size( + input_dims=(8, 8, 3), + filter_dims=(1, 1, 3), + output_dims=(8, 8, 3), + stride=(1, 1), + padding=(0, 0), + channel_multiplier=value, + ) + + +def test_missing_binding(monkeypatch): + monkeypatch.setitem( + sys.modules, "executorch.backends.espressif._esp_nn_scratch_esp32s3", None + ) + assert get_scratch_queries(EspTarget.ESP32S3, EspKernelMode.OPTIMIZED) is None + + +@pytest.mark.parametrize( + "error", + [ + ImportError("undefined symbol: esp_nn_get_conv_scratch_size_esp32s3"), + ModuleNotFoundError("missing dependency", name="binding_dependency"), + ], +) +def test_broken_binding_propagates_error(monkeypatch, error): + def broken_import(name): + raise error + + monkeypatch.setattr( + "executorch.backends.espressif.scratch.importlib.import_module", broken_import + ) + with pytest.raises(type(error), match=str(error)): + get_scratch_queries(EspTarget.ESP32S3, EspKernelMode.OPTIMIZED) + + +def test_required_binding_cannot_skip(monkeypatch): + monkeypatch.setenv("EXECUTORCH_REQUIRE_ESP_NN_SCRATCH", "1") + monkeypatch.setitem( + sys.modules, "executorch.backends.espressif._esp_nn_scratch_esp32s3", None + ) + with pytest.raises(pytest.fail.Exception, match="Required ESP-NN scratch binding"): + _scratch_queries(EspTarget.ESP32S3, EspKernelMode.OPTIMIZED) + + +def test_invalid_kernel_mode(): + with pytest.raises(ValueError, match="EspKernelMode"): + get_scratch_queries(EspTarget.ESP32S3, "unknown") + + +def test_invalid_target(): + with pytest.raises(ValueError, match="EspTarget"): + get_scratch_queries("unknown", EspKernelMode.OPTIMIZED) diff --git a/setup.py b/setup.py index 862bd58030b..98d14905b25 100644 --- a/setup.py +++ b/setup.py @@ -173,6 +173,7 @@ def _minimal_cmake_flags() -> List[str]: "-DEXECUTORCH_BUILD_VULKAN=OFF", "-DEXECUTORCH_BUILD_XNNPACK=OFF", "-DEXECUTORCH_BUILD_CMSIS_NN_PYBINDS=OFF", + "-DEXECUTORCH_BUILD_ESP_NN_PYBINDS=OFF", ] @@ -2913,6 +2914,9 @@ def run(self): # noqa C901 if cmake_cache.is_enabled("EXECUTORCH_BUILD_CMSIS_NN_PYBINDS"): cmake_build_args += ["--target", "cmsis_nn"] + if cmake_cache.is_enabled("EXECUTORCH_BUILD_ESP_NN_PYBINDS"): + cmake_build_args += ["--target", "_esp_nn_scratch"] + if cmake_cache.is_enabled("EXECUTORCH_BUILD_CUDA"): # The stream helper is not named here: the delegate links it PUBLIC, so # asking for the delegate builds it. It used to be named under an @@ -3325,6 +3329,19 @@ def iter_distribution_names(self): "EXECUTORCH_BUILD_CMSIS_NN_PYBINDS", ], ), + *[ + BuiltExtension( + src=( + f"_esp_nn_scratch_{profile}.cp*" + if _is_windows() + else f"_esp_nn_scratch_{profile}.*" + ), + src_dir="backends/espressif/scratch/%BUILD_TYPE%/", + modpath=f"executorch.backends.espressif._esp_nn_scratch_{profile}", + dependent_cmake_flags=["EXECUTORCH_BUILD_ESP_NN_PYBINDS"], + ) + for profile in ("esp32s3", "riscv_pie", "generic", "ansi") + ], BuiltExtension( src="extension/llm/runner/_llm_runner.*", # @lint-ignore https://github.com/pytorch/executorch/blob/cb3eba0d7f630bc8cec0a9cc1df8ae2f17af3f7a/scripts/lint_xrefs.sh modpath="executorch.extension.llm.runner._llm_runner", diff --git a/tools/cmake/preset/default.cmake b/tools/cmake/preset/default.cmake index 0053fe7b8ef..19ec66ad7e7 100644 --- a/tools/cmake/preset/default.cmake +++ b/tools/cmake/preset/default.cmake @@ -237,6 +237,10 @@ define_overridable_option( EXECUTORCH_BUILD_CMSIS_NN_PYBINDS "Build the CMSIS-NN Python bindings" BOOL OFF ) +define_overridable_option( + EXECUTORCH_BUILD_ESP_NN_PYBINDS "Build ESP-NN scratch-size Python bindings" + BOOL OFF +) define_overridable_option( EXECUTORCH_BUILD_CUDA "Build the CUDA backend" BOOL OFF )