Skip to content
Merged
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
13 changes: 12 additions & 1 deletion packages/embeddedci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,7 +374,18 @@ properties `can_gpio`, `can_trigger`, `can_spi`, `can_profile_power`, `can_calib
`can_current_out`, `can_reset_target` and `can_analog` name the common ones (`can_config` …
`can_disable` stay the CAN bus commands). A call the pod cannot serve raises
`UnsupportedFeatureError` (see [Errors](#errors)), before anything is sent when the capabilities
already say so:
already say so.

Where those come from: firmware after 3.10.10 no longer lists its features. The SDK asks for its
`status` without the list (`"caps":false`) and gets `capabilities.features_rev`, the revision of
the features table the firmware is built from, plus the running image (`capabilities.fpga_image`)
and a few hardware facts. The SDK ships that table (`embeddedci.benchpod.feature_map`, a copy of
benchpod-firmware's `features/features.json`), so this needs no network: `capabilities.features`
is every feature the table gives the pod, and `bp.supports()` also takes table names without a
flag of their own (`"la_dir"`, `"i2c_master"`, `"diag"`, `"wiring_store"`, ...). Older firmware
sends its list as before and gets the same answers. A pod with a higher `features_rev` than the
SDK knows logs a warning once: update the SDK (`pip install -U embeddedci`) to use those features.


```python
import pytest
Expand Down
53 changes: 52 additions & 1 deletion packages/embeddedci/src/embeddedci/benchpod/capabilities.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@

import re
from dataclasses import dataclass, field
from typing import Any, Dict, Mapping, Optional, Tuple
from typing import Any, Dict, FrozenSet, Mapping, Optional, Tuple

from . import feature_map as _feature_map

# Built-in nominal front-end calibration per board — the affine fit ``volts = a + b*count``
# for boards whose analog front-end is inverting (so the naive count/full-scale model would
Expand Down Expand Up @@ -205,6 +207,17 @@ class Capabilities:
uart_hd: bool = False
#: The running gateware version (``status`` ``gateware``); 0 when not reported.
gateware: int = 0
#: The features-table revision the pod's firmware is built from (``status`` with
#: ``"caps":false``, firmware after 3.10.10); 0 for older firmware, which sends a ``caps``
#: list instead.
features_rev: int = 0
#: With :attr:`features_rev`: every feature the table gives this pod
#: (:mod:`~embeddedci.benchpod.feature_map`), including ones with no flag here (``la_dir``,
#: ``i2c_master``, ``diag``, ...). Empty for older firmware.
features: FrozenSet[str] = frozenset()
#: The running gateware image: ``"loop"``, ``"deep"``, ``"emu"``, ``"unknown"``; ``""`` when the
#: firmware does not say.
fpga_image: str = ""
#: The pod can calibrate its own ADC and keeps the result: :meth:`BenchPod.calibrate`.
calibrate: bool = False
#: ``calibrate`` also takes the DMM-guided forms (firmware 3.9.4+): this pod's own DAC line
Expand Down Expand Up @@ -384,6 +397,13 @@ def from_status(cls, status: Mapping[str, Any]) -> "Capabilities":
setattr(c, attr, True)
if "analog" in names:
c.analog = True
# Firmware after 3.10.10, asked with "caps":false: no list, the features table instead.
if (rev := _as_int(status, "features_rev")) is not None and rev > 0:
c.features_rev = rev
c.fpga_image = str(status.get("fpga_image", "") or "")
facts = _feature_map.facts_from_status(status)
c.features = _feature_map.resolve(rev, c.gateware, facts)
c._apply_features(facts)
c.safe_mode = _as_bool(status, "safe_mode") is True
c.safe_reason = str(status.get("safe_reason", "") or "") if c.safe_mode else ""
c.last_crash = _crash_text(status.get("last_crash", status.get("crash")))
Expand All @@ -392,6 +412,28 @@ def from_status(cls, status: Mapping[str, Any]) -> "Capabilities":
c._apply_range(status)
return c

def _apply_features(self, facts: Mapping[str, Any]) -> None:
"""Set the flags of :attr:`features` (a table name is the flag's name, except the two
below) and the hardware facts."""
for name in self.features:
attr = _TABLE_ALIASES.get(name, name)
if attr in _BOOL_FIELDS:
setattr(self, attr, True)
for fact in ("usb_cc", "pod_current", "nrst_pin"):
if facts.get(fact) is True:
setattr(self, fact, True)

def has(self, feature: str) -> bool:
"""Whether the pod has ``feature``: a table name (``"la_dir"``, ``"i2c_master"``, ...)
when the pod announced :attr:`features_rev`, else the flag of that name (older firmware)."""
if self.features_rev and feature in _feature_map.feature_map().get("features", {}):
return feature in self.features
if feature == "la_dir":
return self.la_dir
if feature in ("i2c_master", "spi_modes_1_2"):
return self.bus_master
return bool(getattr(self, _TABLE_ALIASES.get(feature, feature), False))

def _apply_range(self, src: Mapping[str, Any], prefix: str = "") -> None:
"""The ADC input range the fit is for (firmware 3.9.5+)."""
rng = src.get(prefix + "adc_range")
Expand Down Expand Up @@ -525,12 +567,16 @@ def boot_warning(self) -> Optional[str]:
def la_dir(self) -> bool:
"""The pod takes pin directions (``la_dir``, firmware 3.10.4+). False when the firmware
version is unknown."""
if self.features_rev:
return "la_dir" in self.features
v = _version_tuple(self.firmware_version)
return v is not None and v >= LA_DIR_FIRMWARE

@property
def bus_master(self) -> bool:
"""The I2C master, SPI modes 1 and 2 and send-and-capture (gateware v55+)."""
if self.features_rev:
return "i2c_master" in self.features
return self.gateware >= BUS_MASTER_GATEWARE

@property
Expand Down Expand Up @@ -572,3 +618,8 @@ def merge(self, other: "Capabilities") -> "Capabilities":


_FIELD_NAMES = tuple(f for f in Capabilities().__dict__.keys())
_BOOL_FIELDS = frozenset(f for f, v in Capabilities().__dict__.items() if isinstance(v, bool))

#: Table names whose flag here has another name: the table's ``uart`` and ``la`` are the old
#: ``serial`` and ``analyzer`` flags.
_TABLE_ALIASES = {"uart": "serial", "la": "analyzer"}
24 changes: 19 additions & 5 deletions packages/embeddedci/src/embeddedci/benchpod/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
from . import dsp as _dsp
from . import esp as _esp
from . import expansion as _expansion
from . import feature_map as _feature_map
from . import flash as _flash
from . import i2c as _i2c
from . import i2c_master as _i2c_master
Expand Down Expand Up @@ -465,6 +466,12 @@ def status(self) -> Dict[str, Any]:
"""The pod's status report: firmware version, board, network and advertised features."""
return _dict(self._transport.status())

def _caps_status(self) -> Dict[str, Any]:
"""``status`` for the capabilities: without the ``caps`` list where the firmware has the
features table (:mod:`~embeddedci.benchpod.feature_map`)."""
read = getattr(self._transport, "status_without_caps", None)
return _dict(read() if callable(read) else self._transport.status())

def diag(self) -> Dict[str, Any]:
"""The pod's health counters: ``heap_free``, ``heap_min``, ``stack_min``, per-task
``stacks``, the network stack's ``lwip_mem_*`` and ``pbuf_pool_*`` high-water marks,
Expand Down Expand Up @@ -526,7 +533,7 @@ def capabilities(self) -> Capabilities:
if self._caps is None:
status_ok = True
try:
status = self.status()
status = self._caps_status()
except FirmwareError as exc:
# Firmware 3.10.4's status can be too large for the cloud channel. Reading it again
# will not help: use the server's capabilities alone, and keep them.
Expand All @@ -538,6 +545,11 @@ def capabilities(self) -> Capabilities:
if status_ok and status.get("short_form") and self._direct_network():
status = self._full_status(status)
caps = Capabilities.from_status(status)
if caps.features_rev > _feature_map.revision():
_log.warning(
"this pod's firmware has features this SDK does not know (features table "
"revision %d, the SDK has %d): update the SDK (pip install -U embeddedci) to use them",
caps.features_rev, _feature_map.revision())
api = self._try_server_api()
if api is not None and self._device_name:
try:
Expand All @@ -563,7 +575,7 @@ def _full_status(self, status: Dict[str, Any]) -> Dict[str, Any]:
short form leaves out then come from embeddedci.com when this computer is signed in,
else from the board's defaults."""
try:
again = self.status()
again = self._caps_status()
except BenchPodError:
again = status
if not again.get("short_form"):
Expand All @@ -582,9 +594,11 @@ def refresh_capabilities(self) -> Capabilities:

def supports(self, feature: str) -> bool:
"""Whether this pod has ``feature``, a :class:`Capabilities` flag (``"spi_master"``,
``"capture_trigger"``, ``"can"``, ...). Reads the capabilities once; ``False`` for a
flag this SDK does not know. The ``can_*`` properties name the common ones."""
return bool(getattr(self.capabilities, feature, False))
``"capture_trigger"``, ``"can"``, ...) or a name in the features table
(:mod:`~embeddedci.benchpod.feature_map`: ``"la_dir"``, ``"i2c_master"``, ``"diag"``, ...).
Reads the capabilities once; ``False`` for a name this SDK does not know. The ``can_*``
properties name the common ones."""
return self.capabilities.has(feature)

@property
def can_gpio(self) -> bool:
Expand Down
Loading