socpuppet 0.0.1rc1__tar.gz

socpuppet-0.0.1rc1/.clang-format

@@ -0,0 +1,31 @@
+BasedOnStyle: Google
+
+# Include order: the related header, then C system headers, then the C++
+# standard library, then third-party libraries, then our own headers. Stock
+# Google style would sort <gtest/gtest.h> above the standard library and
+# <systemc> in with it.
+IncludeBlocks: Regroup
+IncludeCategories:
+  # C system headers: the C standard library, and the POSIX ones we are
+  # likely to meet. cpplint keeps its own list of these (CPPLINT.cfg), so a
+  # header it knows and this does not would be sorted where cpplint objects;
+  # add it here.
+  - Regex: '^<(assert|complex|ctype|errno|fenv|float|inttypes|iso646|limits|locale|math|setjmp|signal|stdalign|stdarg|stdatomic|stdbit|stdbool|stdckdint|stddef|stdint|stdio|stdlib|stdnoreturn|string|tgmath|threads|time|uchar|wchar|wctype)\.h>$'
+    Priority: 1
+  - Regex: '^<(dirent|dlfcn|fcntl|glob|poll|pthread|sched|semaphore|strings|syslog|termios|unistd)\.h>$'
+    Priority: 1
+  - Regex: '^<(sys|arpa|netinet)/.*\.h>$'
+    Priority: 1
+  # SystemC's and CCI's extensionless headers look like standard library
+  # ones.
+  - Regex: '^<(systemc|tlm|cci_configuration)>$'
+    Priority: 3
+  # Third-party: anything in angle brackets with a directory or an extension.
+  - Regex: '^<.*[/.].*>$'
+    Priority: 3
+  # The standard library.
+  - Regex: '^<.*>$'
+    Priority: 2
+  # Ours.
+  - Regex: '.*'
+    Priority: 4

socpuppet-0.0.1rc1/.clang-tidy

@@ -0,0 +1,99 @@
+# clang-tidy's checks for our C++. Run them with the build's `tidy` target:
+#   uv run cmake --build --preset dev --target tidy
+#
+# A new clang-tidy's new checks are adopted: the code changes to pass them,
+# and a check is switched off only with its reason written beside its name,
+# as below. The net grows over time. 🚧 Families not yet on, the candidates
+# for more: cert-*, cppcoreguidelines-*, misc-*, concurrency-*.
+Checks:
+  - bugprone-*
+  - clang-analyzer-*
+  - google-*
+  - modernize-*
+  - performance-*
+  - portability-*
+  - readability-*
+
+  # Switched off, each for a reason:
+
+  # Any two parameters of one type "could be swapped". True of most functions
+  # that take an address and a value.
+  - -bugprone-easily-swappable-parameters
+  # `auto f() -> int` everywhere is not Google style.
+  - -modernize-use-trailing-return-type
+  # [[nodiscard]] on every getter is noise.
+  - -modernize-use-nodiscard
+  # Asks for a one-byte base type on every small enum.
+  - -performance-enum-size
+  # Google style allows `if (done) return;` on one line with no braces. The
+  # google- version of this check allows it too, and stays on.
+  - -readability-braces-around-statements
+  # A method that does not touch `this` is often still part of an interface
+  # that someone else calls on an object: a coroutine's promise, a TLM
+  # target. Platform's methods act on the one SystemC kernel, not on members.
+  - -readability-convert-member-functions-to-static
+  # Short names such as `it` and `id` are fine.
+  - -readability-identifier-length
+  # Addresses, sizes and test data are numbers; naming each one would bury
+  # the code.
+  - -readability-magic-numbers
+  # A virtual function called from a constructor or a destructor that is
+  # not pure, and so merely does not reach an override. A pure one, which
+  # is undefined behaviour, is clang-analyzer-cplusplus.PureVirtualCall's,
+  # and stays on. The analyzer follows a path from the QBox CPU's adapter
+  # into QBox's own destructor, which calls one of its own, and reports it
+  # there, in a header nothing here can mark (docs/upstream.md).
+  - -clang-analyzer-optin.cplusplus.VirtualCall
+  # Leaving a parameter unnamed is how C++ says it is unused.
+  - -readability-named-parameter
+
+# Every finding fails the run. A check that is not worth failing for is not
+# worth having on.
+WarningsAsErrors: '*'
+
+# The register maps' headers are left alone. They are generated
+# (tools/regs.py), and they are C, because the Zephyr drivers include the
+# same files: nothing but #define, which is what these checks would have
+# us replace. So are the headers under src/vpvper/, which are written in
+# MINRES's style for VPV-Peripherals, to be offered upstream; its one source
+# file, rvi/iommu.cpp, is in the tidy target with ours.
+ExcludeHeaderFilterRegex: '.*/zephyr_module/include/socpuppet/regs/.*|.*/src/vpvper/.*'
+
+CheckOptions:
+  # Count the complexity a person reads, not what gtest's EXPECT_ macros
+  # expand to.
+  readability-function-cognitive-complexity.IgnoreMacros: true
+
+  # Google's names. Types and functions are CamelCase, variables are
+  # lower_case, a private member ends in an underscore, and a constant is a
+  # k followed by CamelCase.
+  readability-identifier-naming.NamespaceCase: lower_case
+  readability-identifier-naming.ClassCase: CamelCase
+  readability-identifier-naming.StructCase: CamelCase
+  readability-identifier-naming.EnumCase: CamelCase
+  readability-identifier-naming.TypeAliasCase: CamelCase
+  readability-identifier-naming.TypedefCase: CamelCase
+  readability-identifier-naming.TemplateParameterCase: CamelCase
+  readability-identifier-naming.ConceptCase: CamelCase
+  readability-identifier-naming.FunctionCase: CamelCase
+  # Names we do not get to choose:
+  #   - TLM-2.0 calls a target's transport functions by these names, and
+  #     anyone who has met TLM elsewhere knows them.
+  #   - The compiler calls a coroutine's promise and awaiters by these names
+  #     (see core/script.h).
+  #   - SystemC's library calls sc_main (platform/sc_main_stub.cpp).
+  readability-identifier-naming.FunctionIgnoredRegexp: '^(sc_main|b_transport|nb_transport_fw|nb_transport_bw|transport_dbg|get_direct_mem_ptr|invalidate_direct_mem_ptr|get_return_object|initial_suspend|final_suspend|return_void|return_value|unhandled_exception|await_transform|await_ready|await_suspend|await_resume|yield_value)$'
+  readability-identifier-naming.StructIgnoredRegexp: '^promise_type$'
+  readability-identifier-naming.VariableCase: lower_case
+  readability-identifier-naming.ParameterCase: lower_case
+  readability-identifier-naming.MemberCase: lower_case
+  readability-identifier-naming.PrivateMemberSuffix: _
+  readability-identifier-naming.ProtectedMemberSuffix: _
+  readability-identifier-naming.EnumConstantCase: CamelCase
+  readability-identifier-naming.EnumConstantPrefix: k
+  readability-identifier-naming.ConstexprVariableCase: CamelCase
+  readability-identifier-naming.ConstexprVariablePrefix: k
+  readability-identifier-naming.GlobalConstantCase: CamelCase
+  readability-identifier-naming.GlobalConstantPrefix: k
+  readability-identifier-naming.ClassConstantCase: CamelCase
+  readability-identifier-naming.ClassConstantPrefix: k

socpuppet-0.0.1rc1/.claude/skills/software-design-review/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: software-design-review
+description: "Review application code (not tests) for design quality: is it a good design, does it do only what the current tests demand, and does it fit the code around it. Runs in its own subagent."
+argument-hint: [files or paths]
+context: fork
+background: false
+---
+
+# Software Design Review
+
+Review the application code named under "Code to review" below, or if none is named, the non-test changes in the working tree at the end of this document. Read enough of the surrounding code to judge fit. Do not edit files; report only.
+
+Review it as a senior engineer would in a thoughtful design review, using your own judgment. Weigh:
+
+- Is this a good design? Judge it on its own terms: are responsibilities in the right place, is coupling low and the interface clear, would it still be the right shape once the rest of the agreed specifications land? Say what you would design differently and why.
+- Does it do only what the tests currently demand? Flag speculative or defensive code: branches, parameters, checks, or abstractions no test exercises.
+- Does it fit the concepts, naming, and conventions already in this area, or would a small refactor make it fit?
+- Would a reader understand it without the commit message?
+
+Ignore formatting and anything a linter enforces.
+
+Report each finding with the code and a concrete suggestion. If nothing warrants a change, say so in one line; don't invent findings.
+
+## Code to review
+
+$ARGUMENTS
+
+## Working tree
+
+!`git status --porcelain`
+
+## Diff
+
+!`git diff HEAD`

socpuppet-0.0.1rc1/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: tdd
+description: "Implement a change with test-driven development (Canon TDD): specify, encode each spec as a test, watch it fail, fulfill it."
+argument-hint: [specification]
+---
+
+# Test-Driven Development
+
+## Initial Specification
+
+$ARGUMENTS
+
+## The loop (Kent Beck's [Canon TDD](https://tidyfirst.substack.com/p/canon-tdd))
+
+1. List the specifications in scope for this session, as "under scenario A, X happens; under scenario B, Y happens".
+2. Encode one item as an automated test.
+3. Change the code just barely enough to make the current failure go away. No speculative or defensive code: anything beyond what the failing test demands is code no test exercises.
+4. Optionally refactor, but only after committing the behavior change. Never mix the two.
+5. Until the list is empty, go back to 2.
+
+## Clarifying specifications
+
+Before writing tests: repeat my specifications back in your own words, ask me to confirm or correct, and loop until confirmed. For how to shape a spec and name its test, see [test-design-review/SKILL.md](../test-design-review/SKILL.md).
+
+## Workflow
+
+1. I invoke /tdd with a draft specification.
+2. We clarify until we agree on the list in scope.
+3. Clean the kitchen if needed (below).
+4. Take the next specification and write just one test for it. Run it and confirm it fails the way the specification predicts. Don't pause for me here. A compile or import error for a symbol that doesn't exist yet is the first failure; add only the declaration needed to reach the assertion failure. Stop and tell me only if the test passes with no code change (the behavior already exists, or the test doesn't test what we think) or fails for an unrelated reason.
+5. Run /test-design-review on the test and address its findings. Show me the test, the failure output, and any finding you disagreed with, and ask for approval before continuing.
+6. Write only enough application code to make the failure go away. Run the test, then the project's normal test command. Run /software-design-review on the application code and address its findings. Show me the code and the green run, and ask for approval before committing.
+7. Commit the behavior change. If a refactor is called for, propose it now; it goes in its own commit.
+8. Back to step 4 until the list is empty. Then I provide the next specification and we start over from step 2.
+
+### Cleaning the kitchen
+
+Before writing a test, picture it and where it will live. If the new behavior does not slot tidily into the conceptual framework of that area of the code, and a reconceptualizing of the current behavior would make the end result more elegant, suggest it. If I approve, abandon the current change, get to a clean working state, and perform the refactoring on a new branch. Then pause and consult me and we begin again.
+
+### Don't be sloppy
+
+This kind of thinking is bad:
+
+> That failure is pre-existing (unrelated to our change, it's in send_results). Our 6 new + existing tests pass. Want me to commit and push?
+
+We don't make dinner in a dirty kitchen. On discovering a pre-existing failure: pause, stash our changes, fix it, then resume.
+
+### Don't be lazy
+
+This is stupid and bad:
+
+> pytest isn't on the PATH in this environment and the project's virtualenv wasn't activated. The tests can't run here, but the change is straightforward: removed the re-tagging and made preload_app_image return the image name.
+
+Don't abandon tests upon encountering the slightest difficulty.

socpuppet-0.0.1rc1/.claude/skills/test-design-review/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: test-design-review
+description: Review tests for design quality against the test design guidelines. Runs in its own subagent.
+argument-hint: [test files or paths]
+context: fork
+background: false
+---
+
+# Test Design Review
+
+Review the tests named under "Tests to review" below, or if none are named, the test changes in the working tree at the end of this document. Read any untracked test files the status listing shows. Do not edit files; report only.
+
+For each violation found, show the offending code and suggest a fix. Group by guideline and skip guidelines with no violations. If nothing violates any guideline, say so in one line; don't invent findings.
+
+## Tests to review
+
+$ARGUMENTS
+
+## Guidelines
+
+Tests are executable specifications: "in scenario X, Y happens".
+
+### Name the scenario and the expected behavior
+
+The scenario and the outcome both appear in the test name or its enclosing group (pytest class, gtest suite, Rust `mod`). "It works correctly", "handles errors", "validates input" specify nothing.
+
+Bad:
+
+```python
+class TestScopeFailed:
+    def test_returns_the_correct_value(self):
+```
+
+Good:
+
+```python
+class TestRerunningOnlyFailedTests:
+    def test_when_status_is_passed_returns_passed(self):
+```
+
+```rust
+mod when_a_particle_touches_a_grid_cell {
+    #[test]
+    fn the_cell_turns_the_particles_color() { ... }
+}
+```
+
+### Test behavior, not implementation
+
+Assert on the observable end result, never on the means: no `assert_called_once_with`, `EXPECT_CALL`, cache keys, current URL, or a specific internal field. Stub only what you must (external services) and let real code run. One pair covers the whole family:
+
+Bad:
+
+```python
+def test_queues_the_task(mocker, task):
+    worker_pool = mocker.patch("jobs.WorkerPool").return_value
+    QueueUnqueuedTasksJob().perform()
+    worker_pool.queue_task.assert_called_once_with(task)
+
+def test_caches_the_result(test_suite_run):
+    test_suite_run.duration()
+    assert cache.get(f"test_suite_run/{test_suite_run.id}/duration") is not None
+```
+
+Good:
+
+```python
+def test_queues_the_task(task):
+    QueueUnqueuedTasksJob().perform()
+    assert TaskEvent.count(name="queued") == 1
+
+def test_does_not_query_the_database_on_subsequent_calls(test_suite_run):
+    test_suite_run.duration()
+    with count_queries() as second_call:
+        test_suite_run.duration()
+    assert second_call.count == 0
+```
+
+The same applies to setup: drive state through the public path the code under test uses (`task.update(exit_code=0)`), not by poking the internal representation it derives from (`task.update(json_output=...)`). Parse helpers the way a user would (find the link by its text), not by regex over markup.
+
+### Assert only what is essential
+
+Drop assertions implied by others (a body check already fails on a bad status code), incidental details, and noise.
+
+### Don't pick records by position
+
+`[0]`, `[-1]`, `.first()`, `.last()` depend on ordering. Query for the record you mean, or assert on the change (`count == before + 1`).
+
+### Keep one level of abstraction
+
+A test that reads at the level of pages and buttons does not set env vars or patch permissions inline; that plumbing goes in a fixture or nowhere. Dense incidental mechanics (listeners, try/finally) go in a helper defined after the test, so the test shows only its essence. Define fixtures before their users, or hard-code the value:
+
+```python
+def test_when_task_id_is_a_non_empty_string_returns_task_prefixed_id(self):
+    worker = Worker(Mock(task_id="123"))
+    assert worker.docker_compose_project_name == "task-123"
+```
+
+### Never reach into private state
+
+No `obj._helper()`, `setattr(obj, "_state", ...)`, `obj.__dict__`, `mocker.patch.object(obj, "_private")`, `#define private public`, `FRIEND_TEST`, or friend classes. If a private method needs a test, make it public, or treat the urge as a design smell and suggest a specific refactor.
+
+### No speculative values
+
+A `timeout=3000`, `time.sleep(3)`, or retry count needs a reason; if it was cargo culted, cut it.
+
+### Hard-code what the spec says, look up what the environment says
+
+Inputs that are part of the specification are hard-coded (`"123"` in, `"task-123"` out). Values the test does not own are not: anything copied from generated code, a config file, a schema, or the environment (a register address from a generated header, a port number from a config file, an ID from a seeded database). Copying such a value couples the test to something that changes for unrelated reasons. Read it from the same source the code under test uses, or shape the assertion so the exact value does not matter.
+
+Bad:
+
+```python
+def test_when_a_byte_is_written_to_the_data_register_the_uart_holds_it(bus, uart):
+    bus.write(0x4000_1000, 0x41)  # copied from the generated memory map
+    assert uart.data_register == 0x41
+```
+
+Good:
+
+```python
+def test_when_a_byte_is_written_to_the_data_register_the_uart_holds_it(bus, uart):
+    bus.write(memory_map.UART0.data, 0x41)
+    assert uart.data_register == 0x41
+```
+
+## Working tree
+
+!`git status --porcelain`
+
+## Diff
+
+!`git diff HEAD`

socpuppet-0.0.1rc1/.coveragerc

@@ -0,0 +1,13 @@
+# What coverage.py measures when the tests run under it, which the build's
+# `coverage` target arranges.
+[run]
+source = python
+# Measure the processes a test starts as well. A test marked
+# @pytest.mark.platform runs in a process of its own, and so does anything
+# launched with subprocess.
+patch = subprocess
+# Each process writes a data file of its own, to be combined afterwards.
+parallel = true
+
+[report]
+show_missing = true

socpuppet-0.0.1rc1/.devcontainer/Dockerfile

@@ -0,0 +1,38 @@
+# The same environment CI uses by default: Ubuntu 26.04 with GCC 15. Built
+# with --build-arg UBUNTU=24.04 (tools/devcontainer.py --ubuntu 24.04), it is
+# the oldest Ubuntu socpuppet supports, with GCC 13.
+ARG UBUNTU=26.04
+FROM ubuntu:${UBUNTU}
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        acpica-tools \
+        bc \
+        bison \
+        build-essential \
+        ca-certificates \
+        curl \
+        device-tree-compiler \
+        e2fsprogs \
+        flex \
+        gdb \
+        git \
+        uuid-dev \
+        zlib1g-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# What tools/build_qbox.py needs to build QBox and its QEMU, for the
+# qbox_cpu (docs/setup.md).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        bison flex libasio-dev libelf-dev libepoxy-dev libglib2.0-dev \
+        libjpeg-turbo8-dev libpixman-1-dev libsdl2-dev libslirp-dev \
+        libvirglrenderer-dev libzip-dev lld llvm meson ninja-build \
+        ocl-icd-opencl-dev pkg-config python3-dev python3-pip python3-venv \
+    && rm -rf /var/lib/apt/lists/*
+
+# uv supplies Python, cmake and ninja (see pyproject.toml).
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+# Keep the virtual environment out of the mounted workspace so it does not
+# collide with a .venv created on the host.
+ENV UV_PROJECT_ENVIRONMENT=/opt/socpuppet-venv \
+    UV_LINK_MODE=copy

socpuppet-0.0.1rc1/.devcontainer/devcontainer.json

@@ -0,0 +1,30 @@
+{
+  "name": "socpuppet",
+  "build": { "dockerfile": "Dockerfile" },
+  // The repository at /workspace, and the container's own trees kept apart
+  // from the host's in the Docker volumes tools/devcontainer.py mounts on a
+  // Mac, which says why. Their names end in the image's Ubuntu: change them
+  // with the Dockerfile's ARG UBUNTU (a test holds them to the script). Their
+  // mount points are made first, on the host: Docker makes a missing one,
+  // and on Linux makes it root's.
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
+  "workspaceFolder": "/workspace",
+  "initializeCommand": "mkdir -p build/linux build/container/ubuntu-26.04/linux build/qbox build/qbox-dev build/firmware/linux-aarch64 build/firmware/linux-x86_64",
+  "mounts": [
+    // The linux preset's tree, a folder of the host's as the script has it,
+    // so that tools/ci.py on the host looks after its dependencies.
+    "source=${localWorkspaceFolder}/build/container/ubuntu-26.04/linux,target=/workspace/build/linux,type=bind",
+    "source=socpuppet-qbox-ubuntu-26.04,target=/workspace/build/qbox,type=volume",
+    "source=socpuppet-qbox-dev-ubuntu-26.04,target=/workspace/build/qbox-dev,type=volume",
+    // Linux's firmware tools, in build/firmware/linux-<processor>: this file
+    // cannot ask which processor it is on, so both are mounted.
+    "source=socpuppet-firmware-linux-ubuntu-26.04,target=/workspace/build/firmware/linux-aarch64,type=volume",
+    "source=socpuppet-firmware-linux-ubuntu-26.04,target=/workspace/build/firmware/linux-x86_64,type=volume"
+  ],
+  "postCreateCommand": "uv sync",
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-vscode.cmake-tools", "ms-vscode.cpptools", "ms-python.python"]
+    }
+  }
+}

socpuppet-0.0.1rc1/.editorconfig

@@ -0,0 +1,25 @@
+# Editor settings that match what the linters enforce (tools/lint.py), so a
+# file starts out right. See https://editorconfig.org.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.{h,cpp}]
+max_line_length = 80
+
+[*.{py,pyi}]
+indent_size = 4
+max_line_length = 80
+
+[*.toml]
+indent_size = 4
+
+[*.md]
+# One paragraph per line, however long: the editor wraps it for display.
+max_line_length = off

socpuppet-0.0.1rc1/.git-blame-ignore-revs

@@ -0,0 +1,9 @@
+# Commits that only reformat or rename, so that git blame looks past them.
+# Use it with: git config blame.ignoreRevsFile .git-blame-ignore-revs
+# (GitHub's blame view reads this file by itself.)
+
+# Reformat all C++ with clang-format (Google style, 80 columns)
+c5a96eaac06e2d8be3be8c04df7bc90b90752dd8
+
+# Rename C++ functions to CamelCase and constants to kName
+83e82d687cee599a95c26f1c6ee985e00a8a94c7

socpuppet-0.0.1rc1/.github/actionlint.yaml

@@ -0,0 +1,7 @@
+# GitHub's own Ubuntu 26.04 runners, which actionlint 1.7.12 does not know
+# yet and so takes for a self-hosted runner's labels (docs/upstream.md).
+# Goes once a release of actionlint names them.
+self-hosted-runner:
+  labels:
+    - ubuntu-26.04
+    - ubuntu-26.04-arm