Skip to content

Commit 050c544

Browse files
CopilotlrudyX
Copilot
and
lrudyX
authored
Merge origin/main into 1.4-stable
Co-authored-by: lrudyX <102149194+lrudyX@users.noreply.github.com>
2 parents 7605252 + 182294e commit 050c544

4,320 files changed

Lines changed: 596416 additions & 154212 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agent/rules/commit_style.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Agent Commit Rules
6+
7+
The user requires all commit messages generated by the agent to follow a specific style and include a proper sign-off.
8+
9+
## Commit Message Style
10+
11+
Commit messages must be formatted with a subject line and a body, following this format:
12+
```
13+
<feature/subsystem>: <one line description>
14+
15+
<body>
16+
```
17+
18+
* **`<feature/subsystem>`**: A short name or tag representing the feature or component being modified.
19+
* **`<one line description>`**: A succinct one-line description of the change.
20+
* **`<body>`**: A detailed description of the changes made in the commit. The body must be at least one sentence describing the changes.
21+
22+
## Sign-off
23+
24+
Every commit message must end with a `Signed-off-by:` line using the patch author's name and email (from the local git config):
25+
26+
```
27+
Signed-off-by: <author name> <author email>
28+
```

‎.agent/rules/documentation.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Documentation Rules
2+
3+
The user expects all new features and in-code documentation to adhere to Doxygen standards.
4+
5+
## Doxygen Requirements
6+
7+
1. **Mandatory Documentation:** All new features, functions, and structures must include Doxygen comments describing their purpose, parameters, and return values.
8+
2. **Clean Build:** Any in-code documentation added or modified must build with Doxygen without producing any new errors or warnings.
9+
3. **Format:** Use standard Doxygen formatting tags (e.g., `@brief`, `@param`, `@return` or `\brief`, `\param`, `\return`). Ensure the styling matches the existing codebase conventions.
10+
11+
## Directory Documentation
12+
13+
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.

‎.agent/rules/topology2_design.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
trigger: glob
3+
glob: tools/topology/topology2/**
4+
---
5+
6+
# Topology2 Design Rule
7+
8+
When working in tools/topology/topology2, follow the canonical guidance in
9+
.github/instructions/topology2-design.instructions.md.
10+
11+
Apply those instructions for topology structure, ID assignment, routing,
12+
platform overrides, and topology target registration.

‎.agent/workflows/build_and_validate.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: Build and validate new C code features
3+
---
4+
5+
This workflow describes the process for building and validating any new C code features in the SOF repository.
6+
7+
**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.
8+
9+
// turbo-all
10+
1. Build the new C code feature using the `xtensa-build-zephyr.py` script.
11+
```bash
12+
source ../.venv/bin/activate
13+
./scripts/xtensa-build-zephyr.py qemu_xtensa
14+
```
15+
16+
2. Validate the feature with a ztest run using the `sof-qemu-run.sh` script.
17+
```bash
18+
source ../.venv/bin/activate
19+
./scripts/sof-qemu-run.sh build-qemu_xtensa
20+
```
21+
22+
3. Ensure that all new features and functions have appropriate Doxygen comments and that the Doxygen documentation builds without errors or warnings.

‎.agent/workflows/module_development.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: Develop and validate new audio processing modules
3+
---
4+
5+
This workflow describes the expected steps to create and validate a new audio processing module within the SOF repository.
6+
7+
// turbo-all
8+
1. **(Optional)** Generate the module skeleton using the `sdk-create-module.py` script.
9+
```bash
10+
# Run the script with relevant arguments to create a new module template
11+
./scripts/sdk-create-module.py --name <module_name> --version <version>
12+
```
13+
14+
2. Develop the module logic within the generated skeleton.
15+
16+
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.
17+
```bash
18+
# Configure and run the testbench against the developed module
19+
./scripts/host-testbench.sh -l <path_to_module_library>
20+
```
21+
22+
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.

‎.clang-format‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
#
3+
# Note: The list of ForEachMacros can be obtained using:
4+
#
5+
# git grep -h '^#define [^[:space:]]*FOR_EACH[^[:space:]]*(' include/ \
6+
# | sed "s,^#define \([^[:space:]]*FOR_EACH[^[:space:]]*\)(.*$, - '\1'," \
7+
# | sort | uniq
8+
#
9+
# References:
10+
# - https://clang.llvm.org/docs/ClangFormatStyleOptions.html
11+
#
12+
# Based on https://github.com/zephyrproject-rtos/zephyr/blob/main/.clang-format
13+
14+
---
15+
BasedOnStyle: LLVM
16+
AlignConsecutiveMacros: AcrossComments
17+
AllowShortBlocksOnASingleLine: Never
18+
AllowShortCaseLabelsOnASingleLine: false
19+
AllowShortEnumsOnASingleLine: false
20+
AllowShortFunctionsOnASingleLine: None
21+
AllowShortIfStatementsOnASingleLine: false
22+
AllowShortLoopsOnASingleLine: false
23+
AttributeMacros:
24+
- __aligned
25+
- __deprecated
26+
- __packed
27+
- __printf_like
28+
- __syscall
29+
- __syscall_always_inline
30+
- __subsystem
31+
BitFieldColonSpacing: After
32+
BreakBeforeBraces: Linux
33+
ColumnLimit: 100
34+
ConstructorInitializerIndentWidth: 8
35+
ContinuationIndentWidth: 8
36+
ForEachMacros:
37+
- 'ARRAY_FOR_EACH'
38+
- 'ARRAY_FOR_EACH_PTR'
39+
- 'FOR_EACH'
40+
- 'FOR_EACH_FIXED_ARG'
41+
- 'FOR_EACH_IDX'
42+
- 'FOR_EACH_IDX_FIXED_ARG'
43+
- 'FOR_EACH_NONEMPTY_TERM'
44+
- 'FOR_EACH_FIXED_ARG_NONEMPTY_TERM'
45+
- 'RB_FOR_EACH'
46+
- 'RB_FOR_EACH_CONTAINER'
47+
- 'SYS_DLIST_FOR_EACH_CONTAINER'
48+
- 'SYS_DLIST_FOR_EACH_CONTAINER_SAFE'
49+
- 'SYS_DLIST_FOR_EACH_NODE'
50+
- 'SYS_DLIST_FOR_EACH_NODE_SAFE'
51+
- 'SYS_SEM_LOCK'
52+
- 'SYS_SFLIST_FOR_EACH_CONTAINER'
53+
- 'SYS_SFLIST_FOR_EACH_CONTAINER_SAFE'
54+
- 'SYS_SFLIST_FOR_EACH_NODE'
55+
- 'SYS_SFLIST_FOR_EACH_NODE_SAFE'
56+
- 'SYS_SLIST_FOR_EACH_CONTAINER'
57+
- 'SYS_SLIST_FOR_EACH_CONTAINER_SAFE'
58+
- 'SYS_SLIST_FOR_EACH_NODE'
59+
- 'SYS_SLIST_FOR_EACH_NODE_SAFE'
60+
- '_WAIT_Q_FOR_EACH'
61+
- '_WAIT_Q_FOR_EACH_SAFE'
62+
- 'Z_FOR_EACH'
63+
- 'Z_FOR_EACH_ENGINE'
64+
- 'Z_FOR_EACH_EXEC'
65+
- 'Z_FOR_EACH_FIXED_ARG'
66+
- 'Z_FOR_EACH_FIXED_ARG_EXEC'
67+
- 'Z_FOR_EACH_IDX'
68+
- 'Z_FOR_EACH_IDX_EXEC'
69+
- 'Z_FOR_EACH_IDX_FIXED_ARG'
70+
- 'Z_FOR_EACH_IDX_FIXED_ARG_EXEC'
71+
- 'Z_GENLIST_FOR_EACH_CONTAINER'
72+
- 'Z_GENLIST_FOR_EACH_CONTAINER_SAFE'
73+
- 'Z_GENLIST_FOR_EACH_NODE'
74+
- 'Z_GENLIST_FOR_EACH_NODE_SAFE'
75+
- 'STRUCT_SECTION_FOREACH'
76+
- 'STRUCT_SECTION_FOREACH_ALTERNATE'
77+
- 'TYPE_SECTION_FOREACH'
78+
- 'K_SPINLOCK'
79+
- 'COAP_RESOURCE_FOREACH'
80+
- 'COAP_SERVICE_FOREACH'
81+
- 'COAP_SERVICE_FOREACH_RESOURCE'
82+
- 'HTTP_RESOURCE_FOREACH'
83+
- 'HTTP_SERVER_CONTENT_TYPE_FOREACH'
84+
- 'HTTP_SERVICE_FOREACH'
85+
- 'HTTP_SERVICE_FOREACH_RESOURCE'
86+
- 'I3C_BUS_FOR_EACH_I3CDEV'
87+
- 'I3C_BUS_FOR_EACH_I3CDEV_SAFE'
88+
- 'I3C_BUS_FOR_EACH_I2CDEV'
89+
- 'I3C_BUS_FOR_EACH_I2CDEV_SAFE'
90+
- 'MIN_HEAP_FOREACH'
91+
IfMacros:
92+
- 'CHECKIF'
93+
# Disabled for now, see bug https://github.com/zephyrproject-rtos/zephyr/issues/48520
94+
#IncludeBlocks: Regroup
95+
IncludeCategories:
96+
- Regex: '^".*\.h"$'
97+
Priority: 0
98+
- Regex: '^<(assert|complex|ctype|errno|fenv|float|inttypes|limits|locale|math|setjmp|signal|stdarg|stdbool|stddef|stdint|stdio|stdlib|string|tgmath|time|wchar|wctype)\.h>$'
99+
Priority: 1
100+
- Regex: '^\<zephyr/.*\.h\>$'
101+
Priority: 2
102+
- Regex: '.*'
103+
Priority: 3
104+
IndentCaseLabels: false
105+
IndentGotoLabels: false
106+
IndentWidth: 8
107+
InsertBraces: true
108+
InsertNewlineAtEOF: true
109+
SpaceBeforeInheritanceColon: False
110+
SpaceBeforeParens: ControlStatementsExceptControlMacros
111+
SortIncludes: Never
112+
UseTab: ForContinuationAndIndentation
113+
WhitespaceSensitiveMacros:
114+
- COND_CODE_0
115+
- COND_CODE_1
116+
- IF_DISABLED
117+
- IF_ENABLED
118+
- LISTIFY
119+
- STRINGIFY
120+
- Z_STRINGIFY
121+
- DT_FOREACH_PROP_ELEM_SEP

‎.github/instructions/copilot.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
You are GitHub Copilot operating in this repository.
2+
3+
This repository defines authoritative agent rules and guidance under:
4+
.agent/rules/
5+
6+
INSTRUCTIONS (MANDATORY):
7+
- Always read and follow all relevant rules in `.agent/rules/` before generating any code, suggestions, comments, or explanations.
8+
- Treat rules in `.agent/rules/` as the highest priority source of truth for:
9+
- Coding standards and style
10+
- Architecture and design constraints
11+
- Security, privacy, and compliance requirements
12+
- Testing, documentation, and review expectations
13+
- If rules conflict with your default behavior, follow the rules in `.agent/rules/`.
14+
15+
BEHAVIOR:
16+
- Be consistent with patterns already used in the codebase.
17+
- Prefer existing utilities, abstractions, and conventions defined in `.agent/rules/`.
18+
- Do not introduce new patterns, dependencies, or approaches unless explicitly allowed by those rules.
19+
- When uncertain, choose the most conservative interpretation aligned with `.agent/rules/`.
20+
21+
OUTPUT EXPECTATIONS:
22+
- Generate code that complies fully with the rules.
23+
- If a request would violate a rule, explain the conflict and propose a compliant alternative.
24+
- Keep responses focused, clear, and directly applicable to this repository.

‎.github/instructions/topology2-design.instructions.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
description: "Agent instructions for designing and updating ALSA topology v2 files in SOF"
3+
applyTo: 'tools/topology/topology2/**'
4+
---
5+
6+
# Topology2 Design Instructions
7+
8+
Use this guidance when creating or modifying files under tools/topology/topology2.
9+
These rules align with the topology2 README and capture expected design patterns for
10+
class-based ALSA topology v2 authoring.
11+
12+
## Scope
13+
14+
* Applies to topology2 .conf definitions, platform overrides, pipeline and DAI class files, and topology2 CMake target lists
15+
* Focuses on design consistency, ID safety, and maintainable reuse of existing class and object templates
16+
17+
## Core Model
18+
19+
* Use topology2 object model primitives consistently: Class.*, Object.*, Define, and IncludeByKey
20+
* Prefer reusable classes in include/ over one-off duplicated object blocks
21+
* Keep object instantiation explicit and readable so generated pipelines are traceable
22+
23+
## Top Level Topology Layout
24+
25+
For new top-level board .conf files, keep this order:
26+
27+
1. Search directories
28+
2. Required class includes
29+
3. Define block with defaults
30+
4. IncludeByKey.PLATFORM overrides
31+
5. Feature-gated IncludeByKey blocks
32+
6. DAI, pipeline, and PCM objects
33+
7. Route definitions
34+
35+
## Reuse Before New Base Files
36+
37+
* Prefer extending an existing base input .conf with variable overrides from CMake targets
38+
* Add a new base .conf only when existing topologies cannot represent the use case cleanly
39+
* When adding a new target, use this tuple structure. In CMake quoted strings, escape each semicolon as `\;`.
40+
41+
```text
42+
Logical tuple format:
43+
"input-conf;output-name;variable1=value1,variable2=value2"
44+
45+
CMake string form:
46+
"input-conf\;output-name\;variable1=value1,variable2=value2"
47+
```
48+
49+
## ID Conventions and Safety
50+
51+
* Keep PCM IDs unique within a single topology
52+
* Keep pipeline indexes unique within a single topology
53+
* Pair FE and BE pipelines as N and N+1 where applicable
54+
* For SoundWire pipelines, follow index equals PCM ID times 10 unless a documented topology-specific exception exists
55+
* For HDMI pipelines, keep stride-10 layout with host at N0 and DAI at N1
56+
* When combining features such as SDW, PCH DMIC, HDMI, deep buffer, or compress, verify there are no ID collisions after overrides
57+
58+
## Routing Rules
59+
60+
* Connect FE mixin outputs to BE mixout inputs using Object.Base.route
61+
* Keep route naming and widget references aligned with topology naming patterns
62+
* Validate that each route endpoint maps to a declared widget in the same compiled topology
63+
64+
## Widget Naming
65+
66+
* Follow naming pattern type.pipeline-index.instance
67+
* Keep naming stable and descriptive for easier graph inspection and debug
68+
69+
## Platform Overrides
70+
71+
* Use IncludeByKey.PLATFORM for platform-specific Define overrides
72+
* Restrict platform-specific tuning to platform/intel/*.conf instead of duplicating board-level logic
73+
* Ensure platform keys remain consistent with the authoritative in-tree overrides under tools/topology/topology2/platform/intel/*.conf; current examples include tgl, adl, mtl, lnl, ptl, and nvl
74+
75+
## CMake Target Placement
76+
77+
Register targets in the correct file for platform generation:
78+
79+
* Tiger Lake and Alder Lake: production/tplg-targets-cavs25.cmake
80+
* Meteor Lake: production/tplg-targets-ace1.cmake
81+
* Lunar Lake: production/tplg-targets-ace2.cmake
82+
* Panther Lake: production/tplg-targets-ace3.cmake
83+
* Nova Lake / sof-nvl-*: production/tplg-targets-ace4.cmake
84+
* i.MX8 platforms: production/tplg-targets-imx8.cmake
85+
* SDCA generic topologies: production/tplg-targets-sdca-generic.cmake
86+
* HDA generic: production/tplg-targets-hda-generic.cmake
87+
* Development and test topologies: development/tplg-targets.cmake
88+
89+
If a target family is not listed above, use the existing tplg-targets-*.cmake
90+
file that already contains similar topologies as the source of truth, and keep new
91+
targets grouped with the same platform or product family in either production/ or
92+
development/.
93+
94+
## Validation Expectations
95+
96+
* Keep topology2 buildable through the topologies2 target
97+
* Preserve compatibility with alsatplg pre-processing mode used by the build system
98+
* Ensure topology edits remain synchronized with nearby architecture or README documentation when design behavior changes

‎.github/workflows/SPDX-README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
Read this section if there are some SPDX warnings above.
2+
Adding correct SPDX headers to new files can be tricky because:
3+
4+
- a different SPDX style is expected for .c versus .h files.
5+
This is because some .h files are included in linker scripts or
6+
assembly code.
7+
- Some SOF reviewers reject C99 comments starting with //
8+
9+
A trick is to keep the SPDX separate, see solution below.
10+
11+
References:
12+
- https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/license-rules.rst#n71
13+
- https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9f3a89926d6d
14+
15+
16+
Start .h files like this:
17+
```
18+
/* SPDX-License-Identifier: ... */
19+
/*
20+
* Copyright(c) ...
21+
*
22+
* Author: ...
23+
*/
24+
```
25+
26+
Start .c files like this:
27+
```
28+
// SPDX-License-Identifier: ...
29+
/*
30+
* Copyright(c) ...
31+
*
32+
* Author: ...
33+
*/
34+
```

0 commit comments

Comments
 (0)