[PATCH] ASoC: es9039q2m: Document the FIR coefficient payload format

[PATCH] ASoC: es9039q2m: Document the FIR coefficient payload format

[Karl Asseily]

The programmable FIR controls are TLV byte controls whose payload is the
raw coefficient data, with no type/length header. Nothing in the driver
says so, and the in-tree precedents differ - wm_adsp takes raw data, SOF
expects a header of its own - so user space is left to guess.

The driver cannot catch a wrong guess either.
snd_soc_bytes_tlv_callback() clamps the byte count to .max before
calling .put, and .max is exactly the size es9039_fir_put() checks for,
so an over-long write with a header in front is cut to a valid length
and loads the header as the first taps.

Document the format at the control definition. No functional change.

Link: https://lore.kernel.org/all/CA+gvwbqrav5C9e=9Jx1i31nrEZGDko73tAAhGzzexeRa1f72LQ@mail.gmail.com/
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Karl Asseily <karl@asseily.com>
---
 sound/soc/codecs/es9039q2m.c | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/sound/soc/codecs/es9039q2m.c b/sound/soc/codecs/es9039q2m.c
index 4e9f86cb7..bf206bf95 100644
--- a/sound/soc/codecs/es9039q2m.c
+++ b/sound/soc/codecs/es9039q2m.c
@@ -632,6 +632,20 @@ static struct es9039_fir_ctl es9039_fir4x = {
 	.stage_4x = true,
 };
 
+/*
+ * The FIR coefficient controls take raw coefficients and nothing else:
+ * tlv[] carries taps * ES9039_COEFF_BYTES bytes with no type/length header.
+ * snd_soc_bytes_tlv_callback() passes the user pointer to .put unchanged,
+ * so a header would be loaded as coefficients. wm_adsp uses the same
+ * convention and SOF embeds a header of its own, so the choice is stated
+ * here rather than left to be inferred.
+ *
+ * The driver cannot enforce it. The callback clamps the count it passes on
+ * to .max, which is exactly taps * ES9039_COEFF_BYTES, so the size check in
+ * es9039_fir_put() can only reject a short write. An over-long one - a
+ * header followed by a full coefficient set - arrives truncated to .max,
+ * passes the check, and loads the header words as the first taps.
+ */
 #define ES9039_FIR(xname, xctl)						\
 {									\
 	.iface	= SNDRV_CTL_ELEM_IFACE_MIXER,				\
-- 
2.47.3