readme: add readme for each audio directory#10591
readme: add readme for each audio directory#10591lgirdwood wants to merge 3 commits intothesofproject:mainfrom
Conversation
Add a high level readme describing each audio directory to help new users understand what each modules does. This large patch of high level text that can be a starting point for further refinement by module authors.
lgirdwood
requested review from
a team,
RanderWang,
abonislawski,
dbaluta,
fkwasowi,
jxstelter,
kv2019i,
lbetlej,
mmaka1,
pblaszko,
plbossart,
ranj063,
singalsu and
tlissows
as code owners
There was a problem hiding this comment.
Pull request overview
This PR adds high-level README documentation files for each audio component directory in the SOF (Sound Open Firmware) codebase, plus a top-level architecture.md. The goal is to help new contributors quickly understand the purpose, architecture, and build configuration of each audio module.
Changes:
- Adds a
readme.mdin each of ~30 audio component subdirectories describing their purpose, architecture diagrams, and configuration/build scripts. - Adds a top-level
architecture.mdproviding a high-level SOF firmware architecture overview.
Reviewed changes
Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
architecture.md |
New top-level overview doc covering SOF firmware layers, IPC, pipelines, and memory management |
src/audio/aria/readme.md |
Documents the ARIA automatic regressive input amplifier component |
src/audio/asrc/readme.md |
Documents the Asynchronous Sample Rate Converter component |
src/audio/buffers/readme.md |
Documents the core audio buffer management module |
src/audio/codec/readme.md |
Documents the codec abstraction and DTS adapter |
src/audio/copier/readme.md |
Documents the Copier data-movement component |
src/audio/crossover/readme.md |
Documents the Crossover filter component |
src/audio/dcblock/readme.md |
Documents the DC Blocking filter component |
src/audio/drc/readme.md |
Documents the Dynamic Range Compressor component |
src/audio/eq_fir/readme.md |
Documents the FIR Equalizer component |
src/audio/eq_iir/readme.md |
Documents the IIR Equalizer component |
src/audio/google/readme.md |
Documents Google-specific audio components |
src/audio/igo_nr/readme.md |
Documents the Intelligo Noise Reduction component |
src/audio/level_multiplier/readme.md |
Documents the Level Multiplier gain component |
src/audio/mfcc/readme.md |
Documents the MFCC feature extractor |
src/audio/mic_privacy_manager/readme.md |
Documents the Microphone Privacy Manager |
src/audio/mixin_mixout/readme.md |
Documents the Mix-In/Mix-Out routing endpoints |
src/audio/mixer/readme.md |
Documents the Mixer component |
src/audio/module_adapter/readme.md |
Documents the Module Adapter IPC4 wrapper |
src/audio/multiband_drc/readme.md |
Documents the Multi-Band DRC component |
src/audio/mux/readme.md |
Documents the Multiplexer/Demultiplexer component |
src/audio/nxp/readme.md |
Documents NXP-specific DSP components |
src/audio/pcm_converter/readme.md |
Documents the PCM format converter |
src/audio/pipeline/readme.md |
Documents the core pipeline engine with detailed state/sequence diagrams |
src/audio/rtnr/readme.md |
Documents the Realtek Real-Time Noise Reduction component |
src/audio/selector/readme.md |
Documents the Channel Selector component |
src/audio/smart_amp/readme.md |
Documents the Smart Amplifier component |
src/audio/sound_dose/readme.md |
Documents the Sound Dose hearing protection component |
src/audio/src/readme.md |
Documents the Synchronous SRC component |
src/audio/stft_process/readme.md |
Documents the STFT Process component |
src/audio/tdfb/readme.md |
Documents the Time Domain Filter Bank / beamformer |
src/audio/template/readme.md |
Documents the Template component stub |
src/audio/tensorflow/readme.md |
Documents the TensorFlow Lite Micro integration |
src/audio/tone/readme.md |
Documents the Tone Generator component |
src/audio/up_down_mixer/readme.md |
Documents the Up/Down channel mixer |
src/audio/volume/readme.md |
Documents the Volume control component |
Comments suppressed due to low confidence (1)
src/audio/tdfb/readme.md:1
- The title says 'Time Domain Filter Bank' but the Kconfig bullet on line 11 names it 'Time Domain Fixed Beamformer'. These two names are inconsistent; the title (and directory name
tdfb) should match the component's actual full name, which is 'Time Domain Fixed Beamformer'.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Fix grammer. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Liam Girdwood <lgirdwood@gmail.com>
Add a more descriptive content. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Liam Girdwood <lgirdwood@gmail.com>
kv2019i
left a comment
kv2019i
left a comment
There was a problem hiding this comment.
Only big question is why readme.md, that seems unusual convention, why not use README.md like everybody else?
Otherwise, I think this is very welcome. Our sof-docs flow is too cumbersome and the our documentation has started to become stale as we've lost some maintainers. I think light in-line documentation (like this) is much better and easier to keep up-to-date (even if not as polished).
I do wonder how detailed this should be. I'd prefer to keep this at relatively high level as i is unlikely the details will be kept up-to-date. People can use AI help to generate more detailed, more specific documentation for their specific needs.
Given above, I do think this PR strikes a pretty good balance. I'm not super fond of listing the UUIDs in the docs, but OTOH, these aren't likely to change, so not a big problem either.
This PR
| @@ -4,7 +4,7 @@ This directory contains the implementation of the Aria audio component. | |||
|
|
|||
There was a problem hiding this comment.
@lgirdwood why readme.md and not README.md which seems by far the most used convention in github?
|
|
||
| - **Kconfig**: Selects the Crossover Filter (`COMP_CROSSOVER`), which splits signals into driver-specific frequencies. Also automatically selects `COMP_BLOB` and `MATH_IIR_DF2T` math functions for its internal filters. | ||
| - **CMakeLists.txt**: Handles modular builds (`llext`). Selects `crossover.c` and generic implementations, and chooses the correct IPC file (`crossover_ipc3.c` or `crossover_ipc4.c`) based on the active IPC major version. | ||
| - **crossover.toml**: Topology parameters for the Crossover module. Sets `init_config = 1` so that `base_cfg_ext` is appended to the IPC payload, which is required up-front to identify output pin indices. Defines UUID, pins, and memory requirements. |
There was a problem hiding this comment.
init_config is IPC4 only, so this is a bit misleading.
Add a high level readme describing each audio directory to help new users understand what each modules does.
This large patch of high level text that can be a starting point for further refinement by module authors.