feat(ffv)!: rename PowerMode → ListeningMode + terminology/HFP fixes (stacked on #177)

[Ulrond]

Stacked review-feedback PR targeting #177's branch — applies the mechanical changes from my proposal comment. Merge into your branch (feature/23-task-far-field-voice-hal) if it looks right; reject items individually if not.

@lucienkennedylamb

What's in this PR

Renames — PowerMode → ListeningMode, with values renamed to listening-capability vocabulary that doesn't overlap with system power state names:

• FULL_POWER → ACTIVE_LISTEN
• STANDBY → KEYWORD_ALERT
• DEEP_SLEEP → POWERED_OFF
• NONE kept as-is
• PowerMode.aidl → ListeningMode.aidl (git-mv preserves history)
• All callers updated: IFarFieldVoiceController.setPowerMode() → setListeningMode(), IFarFieldVoiceEventListener.onEnteredPowerMode() → onEnteredListeningMode(), Status.powerMode → Status.listeningMode, CMakeLists.txt source list updated.

Terminology consistency — every reference to a channel uses the "Audio" suffix so it's unambiguous:

• "Keyword channel" → "Keyword Audio channel"
• "Continual channel" → "Continual Audio channel"
• "Microphones channel" → "Microphones Audio channel"

Endian order pinned — replaced "host processor's native endian order" with "16-bit signed little-endian PCM" throughout the channel docs so consumers don't need per-platform byte-swap logic. (Pick a different value if 16-bit LE is wrong for the platform — the point is to define one, not to specifically pick LE.)

Capabilities extended — added ListeningMode[] supportedListeningModes so platforms that only support a subset (e.g. KEYWORD_ALERT + POWERED_OFF, no ACTIVE_LISTEN) can advertise that.

Callback docstrings rewritten — onKeywordDetected() and onEndOfCommand() got clearer descriptions including what zero offset means.

HFP YAML reworked — hfp-ffv.yaml:

• camelCase keys mirroring the AIDL field names exactly (microphoneChannelCount, not microphone_channel_count)
• dropped fields that are runtime status, not static caps: power_state, privacy_mode, hardware_failure, noise_reduction, beamforming, beamforming_type, noise_reduction_type — these belong in Status / IFarFieldVoiceEventListener callbacks, not in HFP
• added supportedListeningModes and the canonical channelTypes enumeration
• restructured under a capabilities: block that maps 1:1 with the Capabilities parcelable

What's NOT in this PR (deliberately left for you)

These items from my proposal needed FFV-team judgement and I didn't want to guess:

• Fields with no clear consumer / vendor-defined units — items 16, 17 from the proposal. Several fields described as "vendor-defined units" need concrete HAL units (dB, 0..100, 0.0..1.0) or removal — needs domain knowledge of how they're consumed.
• Module overview doc — docs/halif/ffv/current/far_field_voice.md per the interface template — not done.
• State.aidl simplification — file is already module-local, but mirrors the common State pattern verbatim (9 values). If FFV genuinely doesn't need FLUSHING / STARTING / STOPPING, you can trim. I didn't touch it.
• KeywordDetectInfo parcelable — this didn't exist in the current branch (already removed?), so the related comments in my proposal are moot. If it's coming back later, the unit/zero-meaning concerns from items 13-17 still apply.

Test plan

• AIDL compiler accepts the renamed types and imports
• No external callers depend on the old PowerMode / setPowerMode / onEnteredPowerMode names (pre-1.0, but worth a grep across consumer repos)
• HFP validator (if any) accepts the new key shape

[Copilot]

Pull request overview

This PR updates the FFV (Far Field Voice) HAL surface to use clearer “listening mode” terminology (renaming PowerMode → ListeningMode and related APIs), aligns channel terminology (“Keyword/Continual/Microphones Audio channel”), pins the documented PCM endianness, and refactors the FFV HFP YAML to mirror the Capabilities parcelable (including adding supportedListeningModes).

Changes:

• Rename PowerMode enum/file/fields/methods/callbacks to ListeningMode across FFV AIDL and build wiring.
• Extend Capabilities with ListeningMode[] supportedListeningModes and update HFP YAML shape/keys to match Capabilities.
• Documentation/terminology updates for channel naming and PCM encoding/endian wording.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
ffv/current/hfp-ffv.yaml	Restructures FFV HFP to a capabilities: block mirroring Capabilities and adds supportedListeningModes / canonical channel types.
ffv/current/com/rdk/hal/farfieldvoice/Status.aidl	Renames powerMode field to listeningMode and updates related docs/imports.
ffv/current/com/rdk/hal/farfieldvoice/PowerMode.aidl	Removes the old PowerMode enum definition (replaced by ListeningMode).
ffv/current/com/rdk/hal/farfieldvoice/ListeningMode.aidl	Adds the new ListeningMode enum with updated terminology and mapping notes.
ffv/current/com/rdk/hal/farfieldvoice/IFarFieldVoiceEventListener.aidl	Renames callback to onEnteredListeningMode and updates parameter/docs.
ffv/current/com/rdk/hal/farfieldvoice/IFarFieldVoiceControllerListener.aidl	Clarifies wake-word / end-of-command callback docstrings and parameter descriptions.
ffv/current/com/rdk/hal/farfieldvoice/IFarFieldVoiceController.aidl	Renames setPowerMode → setListeningMode and updates channel docs (including endian/PCM wording).
ffv/current/com/rdk/hal/farfieldvoice/IFarFieldVoice.aidl	Updates top-level interface documentation to use Audio-channel terminology consistently.
ffv/current/com/rdk/hal/farfieldvoice/Capabilities.aidl	Adds supportedListeningModes and updates channel-type documentation language.
ffv/current/CMakeLists.txt	Updates the FFV AIDL source list to build ListeningMode.aidl instead of PowerMode.aidl.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.