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
31 changes: 30 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1038,11 +1038,40 @@ stderr with a `[benchpod]` prefix.
| `3` | Refused: the pod refused the command (a locked LAN, a missing role, a bad request). |
| `4` | Busy: the pod or one of its engines is in use (a cloud job's lease, another session). |
| `5` | Unreachable: nothing answered on the pod's address, no pod was found on USB, or the pod is offline on embeddedci.com. |
| `6` | Update the CLI: the pod's firmware needs a newer benchpod CLI (see [Firmware newer than the CLI](#firmware-newer-than-the-cli)). |

`benchpod ci` has its own exit codes (a CI result, not a command's): see
[Exit codes of `benchpod ci`](#exit-codes-of-benchpod-ci).

A refusal is printed word for word as the pod sent it. For a `locked:` (LAN policy),
#### Firmware newer than the CLI

Every JSON command the CLI sends to the pod (on the LAN, over USB networking and through
embeddedci.com) carries `"client_api"`, the pod API level this CLI was built for, and
`"client"`, its name and version (`"cli 0.9.5"`). Firmware 3.10.13 and older ignores both.
Newer firmware announces its own level in `status`; it goes up only when the firmware changes
a reply in a way an older CLI would misread. When the pod's level is above this CLI's (a pod
without one counts as level 1), a command that reads the pod's status stops with exit code
`6` and says so. `status`, `flash-self`, `install-blobs`, `dfu`, `bootsel`, `discover` and
`identity` still run: `status` prints the same line as a warning, and the firmware commands are
how such a pod is updated or rolled back.

```text
[benchpod] la voltage: this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod, or download the latest release from https://github.com/embeddedci-com/benchpod-cli/releases/latest
```

A pod that no longer takes commands from a CLI this old refuses them with `BP0030`, which
the CLI reports the same way. Update the CLI as you installed it (see
[Installation](#installation)). Commands that only talk to embeddedci.com or work locally are
not affected, and neither is the USB console.

Firmware 3.10.8 and later sends more and more refusals with a stable error code (`BP0001` and up).
The CLI then shows the code, what went wrong and what to run, from the error catalog it ships
with, plus a link to the code's page; `benchpod explain <code>` prints the whole entry. The
exit code follows the code: a session, the bus engine, the storage or a lease in use
(`BP0003`, `BP0004`, `BP0005`, `BP0016`, `BP0025`) is `4`, every other code `3`.

A refusal without a code (older firmware, or one that has no code yet) is printed word for
word as the pod sent it. For a `locked:` (LAN policy),
`busy:` (cloud lease) or `forbidden:` (missing role) refusal the CLI adds what to do next.
So it does for `la voltage not set` (run `benchpod la voltage 3.3V` or 1.8V, or set it on
the web app's Wiring tab) and for a `pin conflict: LA4 is in use by ...`, where the raw
Expand Down
2 changes: 1 addition & 1 deletion cmd/benchpod-cli/adcrange.go
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ func adcRange(ctx context.Context, c podCommander, via, action, what string, out
}
data, err := c.Command(ctx, req)
if err != nil {
if strings.Contains(err.Error(), "unknown cmd") {
if isUnknownCommand(err) {
return errors.New(adcRangeMissing)
}
if pe, ok := tcpclient.AsPodError(err); ok {
Expand Down
10 changes: 6 additions & 4 deletions cmd/benchpod-cli/adcrange_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,11 @@ func TestADCRangeSelfTest(t *testing.T) {
}

func TestADCRangeOnOlderFirmware(t *testing.T) {
addr, _ := fakeLANPod(t, `{"status":"error","message":"unknown cmd"}`)
err := runADCRange(&globalFlags{connection: addr}, "show", &bytes.Buffer{})
if err == nil || !strings.Contains(err.Error(), "3.9.5 or later") {
t.Fatalf("err = %v", err)
for _, reply := range unknownCmdReplies {
addr, _ := fakeLANPod(t, reply)
err := runADCRange(&globalFlags{connection: addr}, "show", &bytes.Buffer{})
if err == nil || !strings.Contains(err.Error(), "3.9.5 or later") {
t.Fatalf("err = %v", err)
}
}
}
3 changes: 1 addition & 2 deletions cmd/benchpod-cli/blobs_target.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ import (
"time"

"github.com/embeddedci-com/benchpod-cli/internal/serialconsole"
"github.com/embeddedci-com/benchpod-cli/internal/tcpclient"
)

// blobTarget is where install-blobs reads the pod's W25Q slots and sends blobs: the pod's network
Expand Down Expand Up @@ -105,7 +104,7 @@ func (l lanBlobs) Blobs(ctx context.Context) ([]serialconsole.BlobSlot, error) {
} `json:"blobs"`
}
if err := l.lan.cmd(ctx, map[string]any{"cmd": "blob_status"}, &rep); err != nil {
if pe, ok := tcpclient.AsPodError(err); ok && strings.Contains(pe.Reason, "unknown cmd") {
if isUnknownCommand(err) {
return nil, serialconsole.ErrNoBlobSlots
}
return nil, err
Expand Down
6 changes: 3 additions & 3 deletions cmd/benchpod-cli/busmaster.go
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,12 @@ func tooOldForBusMaster(feature string) string {
}

// busCommand sends one command and words the reply for the user: a firmware without the command
// ("unknown cmd") says which update it needs, other refusals get the usual hints.
// (BP0002, "unknown cmd" before codes) says which update it needs, other refusals get the usual hints.
func busCommand(ctx context.Context, t *podTarget, what, feature string, req map[string]any, out any) error {
raw, err := t.client.Command(ctx, req)
if err != nil {
if pe, ok := tcpclient.AsPodError(err); ok {
if strings.TrimSpace(pe.Reason) == "unknown cmd" {
if isUnknownCommand(err) {
return &shownRefusal{msg: what + ": " + tooOldForBusMaster(feature), pe: pe}
}
return refusedError(what, pe, !t.spec.IsCloud())
Expand Down Expand Up @@ -574,7 +574,7 @@ type laPinsCommander interface {
func laPinsFetch(ctx context.Context, c laPinsCommander, pins []int) (json.RawMessage, error) {
if pins == nil {
raw, err := c.Command(ctx, map[string]any{"cmd": "la_pins"})
if err == nil || !strings.Contains(err.Error(), "reply too large") {
if err == nil || !strings.Contains(err.Error(), "reply too large") { // no code yet
return raw, err
}
first, err1 := laPinsQuery(ctx, c, []int{1, 2, 3, 4, 5, 6, 7})
Expand Down
10 changes: 7 additions & 3 deletions cmd/benchpod-cli/ci_lease.go
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ const (
)

func isLeaseBusy(pe *tcpclient.PodError) bool {
return pe.Code == codeLeaseBusy || pe.Kind() == tcpclient.Busy
return pe.Code == codeLeaseBusy || pe.Kind() == tcpclient.Busy // Kind: the text fallback without a code
}

// busyText is "<holder> holds this pod (<purpose>, N s left)" from a lease_busy refusal.
Expand All @@ -285,6 +285,7 @@ func busyText(pe *tcpclient.PodError) string {
}
return s
}
// fallback: BP0025's holder/purpose/left_s args replace it (firmware without codes)
return strings.TrimPrefix(strings.TrimSpace(pe.Reason), "busy: ")
}

Expand All @@ -301,8 +302,11 @@ func leaseLostText(pe *tcpclient.PodError) string {

// isLeaseLost is a command refused because the run's lease was stopped (BP0026) or expired (BP0027).
func isLeaseLost(pe *tcpclient.PodError) bool {
r := strings.TrimSpace(pe.Reason)
return pe.Code == codeLeaseLost || pe.Code == codeLeaseNotHeld || strings.HasPrefix(r, "lease lost")
if pe.Code == codeLeaseLost || pe.Code == codeLeaseNotHeld {
return true
}
// fallback: BP0026 / BP0027 replace it (firmware without codes)
return strings.HasPrefix(strings.TrimSpace(pe.Reason), "lease lost")
}

// ── the server's lease (embeddedci.com) ─────────────────────────────────────
Expand Down
4 changes: 2 additions & 2 deletions cmd/benchpod-cli/cloudcfg.go
Original file line number Diff line number Diff line change
Expand Up @@ -414,8 +414,8 @@ func cloudCfgError(what, missing string, lan bool, err error) error {
if errors.Is(err, serialconsole.ErrUnknownCommand) {
return errors.New(missing)
}
msg := err.Error()
if strings.Contains(msg, "unknown cmd") || strings.Contains(msg, "unknown target") {
// "unknown target": no code yet (a cloud_ca / cloud_proxy target older firmware lacks)
if isUnknownCommand(err) || strings.Contains(err.Error(), "unknown target") {
return errors.New(missing)
}
if pe, ok := tcpclient.AsPodError(err); ok {
Expand Down
61 changes: 44 additions & 17 deletions cmd/benchpod-cli/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,12 @@ import (
// ── refusals ────────────────────────────────────────────────────────────────
//
// Every refusal from the pod, over the LAN JSON API or the USB console, is a *tcpclient.PodError.
// The policy refusals carry a firmware prefix (locked:, busy:, forbidden:; internal/fwrefusals
// pins the texts) and explainRefusal is the one place that says what to do about each.
// A refusal with a stable code (BP0001...) is classified by tcpclient's code table (the exit code)
// and worded from the catalog (internal/errcatalog: its message and fix.cli, codedRefusal). A
// refusal without one (older firmware, or a refusal with no code yet) falls back to its text: the
// policy refusals carry a firmware prefix (locked:, busy:, forbidden:; internal/fwrefusals pins
// the texts) and explainRefusal is the one place that says what to do about each. Each text match
// below names what replaces it: a code, or "no code yet".

const (
lockedUSBHint = "the pod's external LAN policy is locked; run this over USB with --connection usb"
Expand Down Expand Up @@ -69,28 +73,29 @@ var i2cPullupRE = regexp.MustCompile(`^(I2C needs pull-ups): switch on LA(\d+)'s
// text to show and the hint to add ("" for none). Other refusals come back unchanged with no hint.
func translateRefusal(msg string) (shown, hint string) {
msg = strings.TrimSpace(msg)
if strings.HasPrefix(msg, "la voltage not set") {
if strings.HasPrefix(msg, "la voltage not set") { // fallback: BP0001 replaces it
return msg, laVoltageUnsetHint
}
if m := i2cPullupRE.FindStringSubmatch(msg); m != nil {
if m := i2cPullupRE.FindStringSubmatch(msg); m != nil { // no code yet
return m[1], fmt.Sprintf("pull LA%s up with `benchpod la pull %s up`, or pass --pullups external "+
"when the board has its own", m[2], m[2])
}
// fallback: BP0017 (gateware_too_old) replaces it
if strings.HasSuffix(msg, "need gateware v55+: update the pod's firmware") ||
strings.HasSuffix(msg, "needs gateware v55+: update the pod's firmware") {
return msg, "update it with `benchpod flash-self`"
}
if m := emulationImageRE.FindStringSubmatchIndex(msg); m != nil {
if m := emulationImageRE.FindStringSubmatchIndex(msg); m != nil { // no code yet
image := msg[m[2]:m[3]]
return strings.TrimSuffix(strings.TrimSpace(msg[:m[0]]), ":"), fmt.Sprintf(
"stop the sensors with `benchpod sensor stop`, then switch with `benchpod sensor image %s`", image)
}
if strings.HasPrefix(msg, "image switch refused:") {
if strings.HasPrefix(msg, "image switch refused:") { // no code yet
if i := strings.Index(msg, "; stop them first ("); i > 0 {
return msg[:i], "stop them with `benchpod sensor stop` first"
}
}
if m := pinConflictRE.FindStringSubmatch(msg); m != nil {
if m := pinConflictRE.FindStringSubmatch(msg); m != nil { // no code yet
owner := m[2]
if m[3] != "" {
owner += " (" + m[3] + ")"
Expand All @@ -109,36 +114,52 @@ func translateRefusal(msg string) (shown, hint string) {
return msg, ""
}

// explainRefusal returns the hint for a policy refusal, or "" when the message says it all.
// overLAN is whether the refusal came over the LAN JSON API: only the LAN refuses with locked:
// or a cloud lease, so elsewhere those texts stand alone.
// explainRefusal returns the hint for a refusal without a code, by its text, or "" when the
// message says it all. overLAN is whether the refusal came over the LAN JSON API: only the LAN
// refuses with locked: or a cloud lease, so elsewhere those texts stand alone. A coded refusal
// gets the catalog's fix.cli instead (refusalHint).
func explainRefusal(msg string, overLAN bool) string {
msg = strings.TrimSpace(msg)
switch tcpclient.ClassifyRefusal(msg) {
case tcpclient.Locked:
case tcpclient.Locked: // no code yet
if overLAN {
return lockedUSBHint
}
case tcpclient.Busy:
switch {
case overLAN && strings.HasPrefix(msg, "busy: a cloud job holds"):
case overLAN && strings.HasPrefix(msg, "busy: a cloud job holds"): // fallback: BP0025 replaces it
return leaseBusyHint
case msg == "busy":
case msg == "busy": // no code yet
return heavyBusyHint
}
case tcpclient.Forbidden:
case tcpclient.Forbidden: // no code yet
return forbiddenHint
}
_, hint := translateRefusal(msg)
return hint
}

// refusalHint is what to do about a refusal: the catalog's fix.cli for a coded one, else
// explainRefusal's hint from the text ("" for none).
func refusalHint(pe *tcpclient.PodError, overLAN bool) string {
if pe.Code != "" {
if e, ok := errcatalog.Lookup(pe.Code); ok {
return errcatalog.Fill(e.Fix["cli"], pe.Args)
}
}
return explainRefusal(pe.Reason, overLAN)
}

// refusedError is the one line for a refusal from a command: "<what>: the pod refused: <why>",
// plus explainRefusal's hint.
// plus refusalHint's hint (a coded refusal: the catalog's message and fix.cli).
func refusedError(what string, pe *tcpclient.PodError, overLAN bool) error {
return refusedWithHint(what, pe, explainRefusal(pe.Reason, overLAN))
return refusedWithHint(what, pe, refusalHint(pe, overLAN))
}

// isUnknownCommand says the pod does not know the command it was sent: its firmware is older
// than the command. BP0002, else (firmware without codes) the text "unknown cmd".
func isUnknownCommand(err error) bool { return tcpclient.IsUnknownCommand(err) }

// refusedWithHint is refusedError with the hint given ("" for none).
func refusedWithHint(what string, pe *tcpclient.PodError, hint string) error {
if coded, ok := codedRefusal(pe); ok {
Expand Down Expand Up @@ -223,6 +244,7 @@ const (
exitRefused = 3 // the pod refused the command (locked LAN, missing role, bad request)
exitBusy = 4 // the pod or one of its engines is in use (a cloud lease, another session)
exitUnreachable = 5 // the pod did not answer on its address, no pod on USB, or offline on embeddedci.com
exitUpdateCLI = 6 // the pod's firmware needs a newer CLI (its API level is above this CLI's, or BP0030)
)

// exitCodesHelp is the exit-code table for the root command's help.
Expand All @@ -233,7 +255,8 @@ const exitCodesHelp = "Exit codes:\n" +
" 3 refused: the pod refused the command (a locked LAN, a missing role, a bad request)\n" +
" 4 busy: the pod or one of its engines is in use (a cloud job's lease, another session)\n" +
" 5 unreachable: nothing answered on the pod's address, no pod found on USB, or the\n" +
" pod is offline on embeddedci.com"
" pod is offline on embeddedci.com\n" +
" 6 update the CLI: the pod's firmware needs a newer benchpod CLI"

// usageError marks a command-line mistake (exit code 2).
type usageError struct{ err error }
Expand All @@ -259,6 +282,10 @@ func exitCode(err error) int {
if strings.HasPrefix(err.Error(), "unknown command ") {
return exitUsage
}
var upd *tcpclient.UpdateRequiredError
if errors.As(err, &upd) {
return exitUpdateCLI
}
if pe, ok := tcpclient.AsPodError(err); ok {
if pe.Kind() == tcpclient.Busy {
return exitBusy
Expand Down
Loading