helia-platforms 0.1.0__tar.gz

helia_platforms-0.1.0/LICENSE.md

@@ -0,0 +1,67 @@
+Ambiq Apollo SDK License
+
+========================
+
+Copyright (c) 2026, Ambiq
+
+ All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+
+ of this software and associated documentation files (the “Software”), to use,
+
+ copy, modify, and distribute the Software **solely** for incorporation into,
+
+ and execution on, computing platforms that include an Ambiq-manufactured CPU
+
+ (including but not limited to the Apollo series). Use, reproduction,
+
+ modification, or distribution of the Software on any CPU not manufactured by
+
+ Ambiq is strictly prohibited, subject to the following conditions:
+
+1.  Redistributions of source code must retain the above copyright notice,
+
+     this list of conditions, and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+
+     this list of conditions, and the following disclaimer in the documentation
+
+     and/or other materials provided with the distribution.
+
+3.  Neither the name “Ambiq” nor the names of its contributors may be used to
+
+     endorse or promote products derived from this Software without specific
+
+     prior written permission.
+
+4.  **Field-of-Use Restriction.** The Software and any derivative works
+
+     thereof (in source or binary form) **may only** be executed on a CPU
+
+     manufactured by Ambiq. Execution on any non-Ambiq CPU, even as part of a
+
+     multi-CPU system, is expressly forbidden.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+
+ ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+
+ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+
+ POSSIBILITY OF SUCH DAMAGE.

helia_platforms-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: helia-platforms
+Version: 0.1.0
+Summary: Shared catalog of Ambiq SoC and board facts (cores, memories, clocks, NPU, debug-probe identifiers) consumed by heliaAOT, helia-profiler and helia-estimator.
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.16
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/AmbiqAI/helia-platforms
+Description-Content-Type: text/markdown
+
+# helia-platforms
+
+`helia-platforms` is the shared catalog of Ambiq SoC and board facts (cores,
+memories, clocks, NPU, debug-probe identifiers) consumed by heliaAOT,
+helia-profiler and helia-estimator. Every value carries a provenance record:
+the datasheet page, SDK file or measurement it came from, and who checked it.
+
+- Import name: `helia_platforms`
+- CLI entry point: `helia-platforms`
+
+## Status
+
+Alpha. The built-in data covers apollo3, apollo3p, apollo4l, apollo4p,
+apollo510, apollo510b, apollo510L, apollo330P and atomiq110, with their parts
+and boards; `helia-platforms list` prints what it holds. The file format, the
+Python API and the CLI may change between 0.x releases.
+
+Linker windows, the regions an SDK's linker scripts declare, are not in this
+package. It gives the hardware facts they sit within: physical memory regions,
+boot reservations, image slots and the NVM left for an application
+(`Target.usable_nvm()`).
+
+## Install
+
+```sh
+pip install helia-platforms
+```
+
+or, in a uv project, `uv add helia-platforms`. Python 3.11 or later.
+
+## Use
+
+From the CLI:
+
+```sh
+helia-platforms list
+helia-platforms show apollo510_evb               # every value with its provenance status
+helia-platforms show apollo510_evb --provenance  # and the full record under each row
+helia-platforms show my_board --overlay my_board.yaml
+```
+
+From Python:
+
+```python
+from helia_platforms import resolve
+
+target = resolve("apollo510_evb")
+target.soc.id  # "apollo510"
+target.jlink_device  # "AP510NFA-CBR"
+target.cpu_mhz()  # 96, at the default operating point
+target.flash_load_address()  # 0x410000
+target.placement_ranges()  # {"itcm": (0x0, 0x40000), ...}: base and size per region
+```
+
+A private catalog, such as a board of your own, loads over the built-in one
+with `--overlay` on the CLI or `load_overlay` in Python.
+
+## Upgrade notes
+
+- apollo510b_evb's `jlink_device` is `AP510BFA-CBR`, the Apollo510B ordering
+  number, which SEGGER lists as its own J-Link device. SEGGER added it in J-Link
+  V8.94 (2025-12-10), so update an older J-Link, or pass the SDK's default
+  `AP510NFA-CBR` yourself.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync --group dev && uv run pre-commit install && uv run pytest
+```
+
+In the repository:
+
+- `docs/rfcs/`: design RFCs (the model and API are RFC 0002)
+- `docs/adr/`: architecture decision records
+- `docs/research/`: source inventories
+- `HANDOFF.md`: current state of in-flight work
+
+See `CONTRIBUTING.md` to contribute, and report security issues as described
+in `SECURITY.md`.

helia_platforms-0.1.0/README.md

@@ -0,0 +1,81 @@
+# helia-platforms
+
+`helia-platforms` is the shared catalog of Ambiq SoC and board facts (cores,
+memories, clocks, NPU, debug-probe identifiers) consumed by heliaAOT,
+helia-profiler and helia-estimator. Every value carries a provenance record:
+the datasheet page, SDK file or measurement it came from, and who checked it.
+
+- Import name: `helia_platforms`
+- CLI entry point: `helia-platforms`
+
+## Status
+
+Alpha. The built-in data covers apollo3, apollo3p, apollo4l, apollo4p,
+apollo510, apollo510b, apollo510L, apollo330P and atomiq110, with their parts
+and boards; `helia-platforms list` prints what it holds. The file format, the
+Python API and the CLI may change between 0.x releases.
+
+Linker windows, the regions an SDK's linker scripts declare, are not in this
+package. It gives the hardware facts they sit within: physical memory regions,
+boot reservations, image slots and the NVM left for an application
+(`Target.usable_nvm()`).
+
+## Install
+
+```sh
+pip install helia-platforms
+```
+
+or, in a uv project, `uv add helia-platforms`. Python 3.11 or later.
+
+## Use
+
+From the CLI:
+
+```sh
+helia-platforms list
+helia-platforms show apollo510_evb               # every value with its provenance status
+helia-platforms show apollo510_evb --provenance  # and the full record under each row
+helia-platforms show my_board --overlay my_board.yaml
+```
+
+From Python:
+
+```python
+from helia_platforms import resolve
+
+target = resolve("apollo510_evb")
+target.soc.id  # "apollo510"
+target.jlink_device  # "AP510NFA-CBR"
+target.cpu_mhz()  # 96, at the default operating point
+target.flash_load_address()  # 0x410000
+target.placement_ranges()  # {"itcm": (0x0, 0x40000), ...}: base and size per region
+```
+
+A private catalog, such as a board of your own, loads over the built-in one
+with `--overlay` on the CLI or `load_overlay` in Python.
+
+## Upgrade notes
+
+- apollo510b_evb's `jlink_device` is `AP510BFA-CBR`, the Apollo510B ordering
+  number, which SEGGER lists as its own J-Link device. SEGGER added it in J-Link
+  V8.94 (2025-12-10), so update an older J-Link, or pass the SDK's default
+  `AP510NFA-CBR` yourself.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync --group dev && uv run pre-commit install && uv run pytest
+```
+
+In the repository:
+
+- `docs/rfcs/`: design RFCs (the model and API are RFC 0002)
+- `docs/adr/`: architecture decision records
+- `docs/research/`: source inventories
+- `HANDOFF.md`: current state of in-flight work
+
+See `CONTRIBUTING.md` to contribute, and report security issues as described
+in `SECURITY.md`.

helia_platforms-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "helia-platforms"
+version = "0.1.0"
+description = "Shared catalog of Ambiq SoC and board facts (cores, memories, clocks, NPU, debug-probe identifiers) consumed by heliaAOT, helia-profiler and helia-estimator."
+readme = "README.md"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.11"
+dependencies = [
+    "pyyaml>=6.0",
+    "typer>=0.16",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+helia-platforms = "helia_platforms.cli:main"
+
+[project.urls]
+Repository = "https://github.com/AmbiqAI/helia-platforms"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.11",
+    "ty",
+    "pre-commit>=4",
+    "jsonschema>=4.23",
+    { include-group = "extract" },
+]
+extract = ["pcpp>=1.30"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = [
+    "src",
+    "tests",
+    "scripts",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+    "PL",
+]
+ignore = [
+    "PLR2004",
+    "PLR0913",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "PLR2004",
+    "S101",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+exclude = ["docs/**"]
+
+[tool.ty.environment]
+python-version = "3.11"
+extra-paths = ["scripts"]
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+    "scripts",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["scripts"]
+addopts = "-ra -q"
+
+[tool.coverage.run]
+source = [
+    "helia_platforms",
+    "scripts",
+]

helia_platforms-0.1.0/pyproject.toml.orig

@@ -0,0 +1,72 @@
+[project]
+name = "helia-platforms"
+version = "0.1.0"
+description = "Shared catalog of Ambiq SoC and board facts (cores, memories, clocks, NPU, debug-probe identifiers) consumed by heliaAOT, helia-profiler and helia-estimator."
+readme = "README.md"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0", "typer>=0.16"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+helia-platforms = "helia_platforms.cli:main"
+
+[project.urls]
+Repository = "https://github.com/AmbiqAI/helia-platforms"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.11",
+    "ty",
+    "pre-commit>=4",
+    "jsonschema>=4.23",
+    { include-group = "extract" },
+]
+# The snapshot extractor's dependencies (ADR 0006), outside the wheel's runtime ones.
+extract = ["pcpp>=1.30"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "PL"]
+ignore = ["PLR2004", "PLR0913"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLR2004", "S101"]
+
+[tool.ruff.format]
+quote-style = "double"
+exclude = ["docs/**"]
+
+[tool.ty.environment]
+python-version = "3.11"
+extra-paths = ["scripts"]
+
+[tool.ty.src]
+include = ["src", "tests", "scripts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["scripts"]
+addopts = "-ra -q"
+
+[tool.coverage.run]
+source = ["helia_platforms", "scripts"]

helia_platforms-0.1.0/src/helia_platforms/__init__.py

@@ -0,0 +1,45 @@
+"""Shared catalog of Ambiq SoC and board facts."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("helia-platforms")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+# Imported after __version__, which catalog reads at import.
+from helia_platforms.catalog import (
+    Catalog,
+    CatalogIdentity,
+    SourceIdentity,
+    builtin,
+    load_overlay,
+)
+from helia_platforms.errors import (
+    AmbiguousPlatform,
+    FormatError,
+    PlatformError,
+    PlatformWarning,
+    UnknownPlatform,
+)
+from helia_platforms.resolve import resolve, resolve_board, resolve_soc
+from helia_platforms.target import IsaFeatures, Target
+
+__all__ = [
+    "AmbiguousPlatform",
+    "Catalog",
+    "CatalogIdentity",
+    "FormatError",
+    "IsaFeatures",
+    "PlatformError",
+    "PlatformWarning",
+    "SourceIdentity",
+    "Target",
+    "UnknownPlatform",
+    "__version__",
+    "builtin",
+    "load_overlay",
+    "resolve",
+    "resolve_board",
+    "resolve_soc",
+]