diff --git a/.agent/rules/commit_style.md b/.agent/rules/commit_style.md new file mode 100644 index 000000000000..668bbbbde84e --- /dev/null +++ b/.agent/rules/commit_style.md @@ -0,0 +1,28 @@ +--- +trigger: always_on +--- + +# Agent Commit Rules + +The user requires all commit messages generated by the agent to follow a specific style and include a proper sign-off. + +## Commit Message Style + +Commit messages must be formatted with a subject line and a body, following this format: +``` +: + + +``` + +* **``**: A short name or tag representing the feature or component being modified. +* **``**: A succinct one-line description of the change. +* **``**: A detailed description of the changes made in the commit. The body must be at least one sentence describing the changes. + +## Sign-off + +Every commit message must end with a `Signed-off-by:` line using the patch author's name and email (from the local git config): + +``` +Signed-off-by: +``` diff --git a/.agent/rules/documentation.md b/.agent/rules/documentation.md new file mode 100644 index 000000000000..5d88e6aa3dd4 --- /dev/null +++ b/.agent/rules/documentation.md @@ -0,0 +1,13 @@ +# Documentation Rules + +The user expects all new features and in-code documentation to adhere to Doxygen standards. + +## Doxygen Requirements + +1. **Mandatory Documentation:** All new features, functions, and structures must include Doxygen comments describing their purpose, parameters, and return values. +2. **Clean Build:** Any in-code documentation added or modified must build with Doxygen without producing any new errors or warnings. +3. **Format:** Use standard Doxygen formatting tags (e.g., `@brief`, `@param`, `@return` or `\brief`, `\param`, `\return`). Ensure the styling matches the existing codebase conventions. + +## Directory Documentation + +When creating a new file or modifying an existing one, check if there is an `architecture.md` or `readme.md` (or `README.md`) file in the same directory. If present, evaluate whether the code changes require an update to these documentation files and make the necessary updates to keep them synchronized with the code. diff --git a/.agent/workflows/build_and_validate.md b/.agent/workflows/build_and_validate.md new file mode 100644 index 000000000000..7a3614fc8254 --- /dev/null +++ b/.agent/workflows/build_and_validate.md @@ -0,0 +1,22 @@ +--- +description: Build and validate new C code features +--- + +This workflow describes the process for building and validating any new C code features in the SOF repository. + +**Note:** The QEMU build targets must be used for both building and testing. The user requires the build must be error and warning free and the ztests must all pass. + +// turbo-all +1. Build the new C code feature using the `xtensa-build-zephyr.py` script. + ```bash + source ../.venv/bin/activate + ./scripts/xtensa-build-zephyr.py qemu_xtensa + ``` + +2. Validate the feature with a ztest run using the `sof-qemu-run.sh` script. + ```bash + source ../.venv/bin/activate + ./scripts/sof-qemu-run.sh build-qemu_xtensa + ``` + +3. Ensure that all new features and functions have appropriate Doxygen comments and that the Doxygen documentation builds without errors or warnings. \ No newline at end of file diff --git a/.agent/workflows/module_development.md b/.agent/workflows/module_development.md new file mode 100644 index 000000000000..6036da58034d --- /dev/null +++ b/.agent/workflows/module_development.md @@ -0,0 +1,22 @@ +--- +description: Develop and validate new audio processing modules +--- + +This workflow describes the expected steps to create and validate a new audio processing module within the SOF repository. + +// turbo-all +1. **(Optional)** Generate the module skeleton using the `sdk-create-module.py` script. + ```bash + # Run the script with relevant arguments to create a new module template + ./scripts/sdk-create-module.py --name --version + ``` + +2. Develop the module logic within the generated skeleton. + +3. Validate the module by executing the module within the host testbench. This ensures that the module functions as expected outside of full system simulations. + ```bash + # Configure and run the testbench against the developed module + ./scripts/host-testbench.sh -l + ``` + +4. Document the new module using Doxygen comments. Validate that the Doxygen build completes without errors or warnings. Add a README.md for the module. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..17410b23d4b7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# Sound Open Firmware (SOF) Agent Workflows and Rules + +This document outlines the rules AI agents must follow when checking out branches, writing code, documenting features, and running the development environment. Follow these rules carefully: + +## Development Standards + +### Commitment and Sign-off Rules +* **Commit Subject:** Must follow the format `feature: descriptive title`. +* **Commit Body:** Should describe the changes in detail in the commit message body. +* **Sign-off:** All commits must be signed off by the developer (`Signed-off-by: Name `) using the identity from the local git config. + +### Documentation Requirements +* **Doxygen Comments:** Any new C code or features must include Doxygen comments. +* **Documentation Builds:** Integration of new code must not introduce any new Doxygen errors or warnings. Code additions should be verified against a clean documentation build. +* **Architectural Consistency:** When adding or updating a file, any `architecture.md` or `README.md` in the same directory must be reviewed. The agent is responsible for ensuring documentation stays in sync with code logic changes. + +### Codestyle and Linting +* **Standard:** Use `clangd` instead of `checkpatch` for codestyle verification. +* **Rationale:** `checkpatch` is prone to confusion with assembly and non-standard C; `clangd` provides better integration with IDEs and AI tools and is easier to maintain. diff --git a/scripts/sdk-create-module.py b/scripts/sdk-create-module.py index b9193a57f942..bc80db16dfe9 100755 --- a/scripts/sdk-create-module.py +++ b/scripts/sdk-create-module.py @@ -362,9 +362,12 @@ def main(): print("--- SOF SDK New Module Creator ---") # Argument Validation --- - if len(sys.argv) != 2: + if len(sys.argv) == 2 and sys.argv[1] in ['-h', '--help']: + print("Usage: sdk-create-module.py ") + sys.exit(0) + elif len(sys.argv) != 2: print("\n[ERROR] Invalid number of arguments.") - print("Usage: sdk_create_module.py ") + print("Usage: sdk-create-module.py ") sys.exit(1) # Configuration --- paths are with respect to script dir