Agents.md

gistfile1.txt

# Agent Guidelines for Automotive Linux BSP Development

Guidelines for AI agents and humans working on automotive Linux embedded BSP codebases.

This file is focused on source-code development, code review, static analysis, local builds, and unit tests. It does not cover board bring-up, flashing, lab equipment, HIL benches, in-vehicle testing, or operations that require physical test devices unless the user explicitly asks for that separate scope.

## At a Glance

- Start with code and build context: repo type, target component, branch, toolchain, and intended change.
- Prefer focused, reviewable changes that match the existing project style.
- Treat hardware-touching actions as out of scope by default.
- Do not flash, erase, repartition, change boot environment, or operate test equipment unless explicitly requested.
- For code review, lead with concrete risks: build breaks, regressions, resource leaks, race conditions, ABI/API changes, and missing tests.
- For development, keep behavior changes isolated and covered by local or host-runnable tests where practical.
- For unit tests, prefer deterministic tests that do not require a board, bus analyzer, vehicle network, or external device.
- Run available formatters, static checks, local builds, and unit tests for the files or components changed.
- If a verification step needs hardware, state that it was not run and suggest the minimal manual validation separately.

## Scope

Use these guidelines for:

- Linux kernel driver changes.
- Device tree and binding changes.
- U-Boot or bootloader source changes, excluding flashing or environment modification.
- Yocto, Buildroot, or vendor SDK recipe and configuration changes.
- User-space BSP services, scripts, diagnostics, and low-level utilities.
- HAL, board-support libraries, and platform abstraction code.
- Code reviews, refactors, bug fixes, and unit-test additions.

Do not assume this file authorizes:

- Flashing images to boards.
- Running commands against connected devices.
- Changing U-Boot environment variables on hardware.
- Using fastboot, adb, dfu-util, uuu, JTAG, SWD, CAN tools, or lab equipment.
- Modifying secure boot keys, fuses, EEPROM, NVRAM, partition tables, or production calibration data.
- Performing HIL, SIL, bench, in-vehicle, or long-duration stability testing.

If such work is needed, stop and ask for explicit permission and target details.

## Project Discovery

Before changing code, identify the local project shape:

- Kernel tree, out-of-tree module, U-Boot, Yocto layer, Buildroot tree, vendor SDK, or user-space component.
- Target architecture, SoC family, board or machine name, and relevant hardware revision if visible in code or docs.
- Build entry points: Makefile, Kconfig, defconfig, bitbake recipe, CMake, Meson, Cargo, or shell scripts.
- Existing style and review expectations from local docs, CI files, and recent commits.
- Existing test framework and how it is normally invoked.

Prefer `rg` and existing project scripts over broad manual searches.

## Working Rules

- Make one logical change at a time. Keep unrelated cleanup out of the patch.
- Preserve user and human-authored changes. Do not revert unrelated files.
- Follow the local style first, then the relevant upstream style.
- Do not reformat entire files unless the project expects it.
- Avoid speculative rewrites. Fix the observed issue and the directly related test gap.
- Document non-obvious hardware assumptions in code comments, commit notes, or review notes.
- Use comments to explain constraints, errata, ordering requirements, and workarounds, not obvious control flow.
- Keep public interfaces, device tree bindings, ABI, sysfs, ioctl, netlink, and userspace-visible behavior backward compatible unless the change explicitly requires a break.

## Code Review Priorities

When reviewing BSP code, prioritize findings in this order:

- Build failures, missing dependencies, or broken configuration paths.
- Boot-critical regressions in init order, clocks, regulators, resets, pinctrl, memory, or storage paths.
- Resource lifetime bugs: leaks, double free, missing unwind, use-after-free, stale pointers, and unmanaged IRQs.
- Concurrency bugs: races, missing locks, sleeping in atomic context, interrupt/thread interaction, workqueue lifetime, and deadlocks.
- Error-path bugs: ignored return values, partial initialization failures, bad cleanup ordering, and misleading error codes.
- Power-management bugs: suspend/resume ordering, runtime PM imbalance, wakeup handling, and clock/regulator state mismatch.
- Device tree or binding mistakes: invalid compatible strings, missing required properties, wrong units, bad address/size cells, and undocumented properties.
- Security and robustness issues: unchecked input, integer overflow, unsafe permissions, shell injection, world-writable files, and excessive privileges.
- ABI/API compatibility issues: sysfs names, ioctl structs, netlink messages, DT bindings, exported symbols, and recipe package names.
- Test gaps for changed logic, boundary conditions, and error paths.

Lead review responses with actionable findings and file/line references.

## Linux Kernel and Driver Development

- Follow Linux kernel coding style and the project's local conventions.
- Keep driver probe paths simple and auditable.
- Validate device tree properties and fail with clear errors when required data is missing.
- Prefer managed resource helpers such as `devm_*` where appropriate.
- If resources are not managed, implement complete cleanup for every failure path.
- Check return values from clock, regulator, reset, GPIO, IRQ, DMA, IOMMU, and memory APIs.
- Avoid fixed delays unless required by hardware documentation. Prefer polling with timeouts where possible.
- Be explicit about endianness, register widths, alignment, and memory barriers.
- Avoid global mutable state unless it is required and synchronized.
- Keep interrupt handlers minimal. Defer slow work to threaded IRQs, workqueues, or tasklets as appropriate for the kernel version.
- Use runtime PM and system sleep callbacks consistently when the driver controls power or clocks.
- Keep logging useful but not noisy. Include device context and actionable failure details.

## Device Tree and Bindings

- Treat DTS as source code, not board-test notes.
- Keep board-specific data in board DTS files and reusable SoC data in DTSI files.
- Check `compatible`, `reg`, `interrupts`, `clocks`, `resets`, `power-domains`, `pinctrl`, `dmas`, and `iommus` carefully.
- Do not invent binding properties without updating or referencing schema documentation.
- Prefer schema validation with `dt_binding_check` and `dtbs_check` when available.
- Avoid encoding software policy in device tree unless it describes hardware or stable firmware interfaces.

## U-Boot and Bootloader Code

- Keep source changes separate from flashing or environment changes.
- Be careful with SPL size, init order, memory layout, storage offsets, and device model dependencies.
- Avoid changing default environment, boot targets, partition layout, or secure boot behavior without explicit request.
- Validate build-only changes locally when the toolchain and board config are available.

## Yocto, Buildroot, and SDK Work

- Follow existing layer and recipe organization.
- Keep machine configuration, distro policy, image contents, and package recipes separated.
- Pin or document source revisions according to project practice.
- Check license metadata, dependencies, installed files, systemd units, and package splits.
- Avoid broad clean builds unless needed. Prefer targeted recipe builds first.
- Do not assume generated images should be flashed or deployed.

## Unit Testing Strategy

Prefer tests that run without hardware:

- Kernel logic: use KUnit for helper functions, parsers, state machines, and error handling.
- User-space C/C++: use the repository's existing test framework such as CTest, GoogleTest, Unity, CMocka, or custom runners.
- Scripts: use shellcheck plus Bats or the project's existing script tests when available.
- Python utilities: use pytest or the existing project runner.
- Yocto metadata: use recipe parsing, targeted builds, ptest where applicable, and project CI checks.
- Device tree: use schema checks and compile checks rather than board boot tests.

Good unit tests should cover:

- Normal behavior.
- Boundary values.
- Invalid inputs.
- Error paths and cleanup behavior.
- Compatibility cases for public interfaces.
- Regression cases tied to the bug being fixed.

Do not create tests that require a connected board, live vehicle bus, lab instrument, proprietary server, or manual physical setup unless the user explicitly requests that scope.

## Local Verification Commands

Choose commands based on the project and only run commands that are available locally.

General checks:

```sh
git diff --check
rg "TODO|FIXME" <changed-paths>
```

Linux kernel examples:

```sh
make ARCH=<arch> CROSS_COMPILE=<prefix> <defconfig>
make ARCH=<arch> CROSS_COMPILE=<prefix> Image modules dtbs
make ARCH=<arch> CROSS_COMPILE=<prefix> W=1 <target>
make dt_binding_check
make dtbs_check
./scripts/checkpatch.pl --strict <patch-or-files>
./tools/testing/kunit/kunit.py run
```

Out-of-tree module examples:

```sh
make -C <kernel-build-dir> M=$PWD modules
make -C <kernel-build-dir> M=$PWD clean
```

Yocto examples:

```sh
bitbake <recipe> -c compile
bitbake <recipe> -c package
bitbake <image>
bitbake-layers show-layers
bitbake-layers show-appends
```

User-space examples:

```sh
cmake --build <build-dir>
ctest --test-dir <build-dir>
meson test -C <build-dir>
pytest
shellcheck <scripts>
```

If a command needs unavailable toolchains, missing SDK setup, network access, or hardware, report the limitation instead of guessing the result.

## Automotive Code Concerns

For automotive BSP code, pay extra attention to:

- Deterministic behavior during boot and shutdown.
- Watchdog interaction and failure recovery paths.
- Persistent logging boundaries and log volume.
- Power state transitions, wake sources, and resume ordering.
- Time synchronization and monotonic vs wall-clock assumptions.
- Network interface naming, MAC address handling, and firewall exposure.
- CAN, LIN, Ethernet, PCIe, USB, I2C, SPI, UART, GPIO, PWM, ADC, and storage configuration at the code-review level.
- Security boundaries, privilege separation, and update/rollback compatibility.
- Safety-relevant assumptions, without claiming compliance unless the project evidence supports it.

## Documentation

- Update docs when behavior, configuration, build steps, public interfaces, or test procedures change.
- Keep documentation short, concrete, and tied to the code.
- Record important assumptions such as supported kernel versions, SoC variants, and configuration dependencies.
- For device tree bindings, prefer schema documentation over free-form notes.

## Agent Behavior

- For read-only code inspection, proceed without asking unless target scope is unclear.
- Ask before changing public interfaces, build system behavior, generated artifacts, or large cross-tree patterns.
- Ask before any hardware-touching command or device-dependent test.
- When asked for a review, report findings first, ordered by severity, with file and line references.
- When asked to implement, make the minimal code and test changes needed to satisfy the request.
- When verification is incomplete, state exactly what was run and what remains unverified.

## Code Review Checklist

- Scope is code-only unless hardware work was explicitly requested.
- Change is focused and follows local project style.
- Build configuration and dependencies are correct.
- Error paths release resources in the right order.
- Locks, IRQs, workqueues, timers, and PM state are balanced.
- Device tree changes match bindings and compile cleanly.
- Public interfaces remain compatible or the break is explicit and documented.
- Unit tests or static checks cover changed logic where practical.
- No unrelated formatting, generated files, or broad refactors are included.
- Verification results and skipped hardware-dependent checks are clearly reported.