ASoC: SDCA: Minor formatting and naming tweaks

Fix up some variable/struct member naming, add some missing kerneldoc
and fix some minor formatting/whitespace issues.

Signed-off-by: Charles Keepax <ckeepax@opensource.cirrus.com>
Reviewed-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.dev>
Link: https://patch.msgid.link/20250205113801.3699902-2-ckeepax@opensource.cirrus.com
Signed-off-by: Mark Brown <broonie@kernel.org>

diff --git a/include/sound/sdca.h b/include/sound/sdca.h
index 973252d0adac10bec956861b85045bc1ca3928c6..31b39f2297b9c36995195af2c8c6b109c2acf882 100644 (file)
--- a/include/sound/sdca.h
+++ b/include/sound/sdca.h
@@ -17,10 +17,10 @@ struct sdw_slave;
 #define SDCA_MAX_FUNCTION_COUNT 8
 
 /**
- * sdca_device_desc - short descriptor for an SDCA Function
- * @adr: ACPI address (used for SDCA register access)
- * @type: Function topology type
- * @name: human-readable string
+ * struct sdca_function_desc - short descriptor for an SDCA Function
+ * @name: Human-readable string.
+ * @type: Function topology type.
+ * @adr: ACPI address (used for SDCA register access).
  */
 struct sdca_function_desc {
        const char *name;
@@ -29,17 +29,17 @@ struct sdca_function_desc {
 };
 
 /**
- * sdca_device_data - structure containing all SDCA related information
- * @sdca_interface_revision: value read from _DSD property, mainly to check
- * for changes between silicon versions
- * @num_functions: total number of supported SDCA functions. Invalid/unsupported
+ * struct sdca_device_data - structure containing all SDCA related information
+ * @interface_revision: Value read from _DSD property, mainly to check
+ * for changes between silicon versions.
+ * @num_functions: Total number of supported SDCA functions. Invalid/unsupported
  * functions will be skipped.
- * @sdca_func: array of function descriptors
+ * @function: Array of function descriptors.
  */
 struct sdca_device_data {
        u32 interface_revision;
        int num_functions;
-       struct sdca_function_desc sdca_func[SDCA_MAX_FUNCTION_COUNT];
+       struct sdca_function_desc function[SDCA_MAX_FUNCTION_COUNT];
 };
 
 enum sdca_quirk {

diff --git a/include/sound/sdca_function.h b/include/sound/sdca_function.h
index c051c17903e8363a2a06cede1fefa211a94b61ce..1d1d3a1da52ddb321bd61775f017b32836ac3c40 100644 (file)
--- a/include/sound/sdca_function.h
+++ b/include/sound/sdca_function.h
@@ -11,39 +11,57 @@
 
 #include <linux/bits.h>
 
-/*
+/**
+ * enum sdca_function_type - SDCA Function Type codes
+ * @SDCA_FUNCTION_TYPE_SMART_AMP: Amplifier with protection features.
+ * @SDCA_FUNCTION_TYPE_SIMPLE_AMP: Subset of SmartAmp.
+ * @SDCA_FUNCTION_TYPE_SMART_MIC: Smart microphone with acoustic triggers.
+ * @SDCA_FUNCTION_TYPE_SIMPLE_MIC: Subset of SmartMic.
+ * @SDCA_FUNCTION_TYPE_SPEAKER_MIC: Combination of SmartMic and SmartAmp.
+ * @SDCA_FUNCTION_TYPE_UAJ: 3.5mm Universal Audio jack.
+ * @SDCA_FUNCTION_TYPE_RJ: Retaskable jack.
+ * @SDCA_FUNCTION_TYPE_SIMPLE_JACK: Subset of UAJ.
+ * @SDCA_FUNCTION_TYPE_HID: Human Interface Device, for e.g. buttons.
+ * @SDCA_FUNCTION_TYPE_IMP_DEF: Implementation-defined function.
+ *
  * SDCA Function Types from SDCA specification v1.0a Section 5.1.2
- * all Function types not described are reserved
+ * all Function types not described are reserved.
+ *
  * Note that SIMPLE_AMP, SIMPLE_MIC and SIMPLE_JACK Function Types
  * are NOT defined in SDCA 1.0a, but they were defined in earlier
  * drafts and are planned for 1.1.
  */
-
 enum sdca_function_type {
-       SDCA_FUNCTION_TYPE_SMART_AMP    = 0x01, /* Amplifier with protection features */
-       SDCA_FUNCTION_TYPE_SIMPLE_AMP   = 0x02, /* subset of SmartAmp */
-       SDCA_FUNCTION_TYPE_SMART_MIC    = 0x03, /* Smart microphone with acoustic triggers */
-       SDCA_FUNCTION_TYPE_SIMPLE_MIC   = 0x04, /* subset of SmartMic */
-       SDCA_FUNCTION_TYPE_SPEAKER_MIC  = 0x05, /* Combination of SmartMic and SmartAmp */
-       SDCA_FUNCTION_TYPE_UAJ          = 0x06, /* 3.5mm Universal Audio jack */
-       SDCA_FUNCTION_TYPE_RJ           = 0x07, /* Retaskable jack */
-       SDCA_FUNCTION_TYPE_SIMPLE_JACK  = 0x08, /* Subset of UAJ */
-       SDCA_FUNCTION_TYPE_HID          = 0x0A, /* Human Interface Device, for e.g. buttons */
-       SDCA_FUNCTION_TYPE_IMP_DEF      = 0x1F, /* Implementation-defined function */
+       SDCA_FUNCTION_TYPE_SMART_AMP                    = 0x01,
+       SDCA_FUNCTION_TYPE_SIMPLE_AMP                   = 0x02,
+       SDCA_FUNCTION_TYPE_SMART_MIC                    = 0x03,
+       SDCA_FUNCTION_TYPE_SIMPLE_MIC                   = 0x04,
+       SDCA_FUNCTION_TYPE_SPEAKER_MIC                  = 0x05,
+       SDCA_FUNCTION_TYPE_UAJ                          = 0x06,
+       SDCA_FUNCTION_TYPE_RJ                           = 0x07,
+       SDCA_FUNCTION_TYPE_SIMPLE_JACK                  = 0x08,
+       SDCA_FUNCTION_TYPE_HID                          = 0x0A,
+       SDCA_FUNCTION_TYPE_IMP_DEF                      = 0x1F,
 };
 
 /* Human-readable names used for kernel logs and Function device registration/bind */
-#define        SDCA_FUNCTION_TYPE_SMART_AMP_NAME       "SmartAmp"
-#define        SDCA_FUNCTION_TYPE_SIMPLE_AMP_NAME      "SimpleAmp"
-#define        SDCA_FUNCTION_TYPE_SMART_MIC_NAME       "SmartMic"
-#define        SDCA_FUNCTION_TYPE_SIMPLE_MIC_NAME      "SimpleMic"
-#define        SDCA_FUNCTION_TYPE_SPEAKER_MIC_NAME     "SpeakerMic"
-#define        SDCA_FUNCTION_TYPE_UAJ_NAME             "UAJ"
-#define        SDCA_FUNCTION_TYPE_RJ_NAME              "RJ"
-#define        SDCA_FUNCTION_TYPE_SIMPLE_NAME          "SimpleJack"
-#define        SDCA_FUNCTION_TYPE_HID_NAME             "HID"
-#define        SDCA_FUNCTION_TYPE_IMP_DEF_NAME         "ImplementationDefined"
+#define        SDCA_FUNCTION_TYPE_SMART_AMP_NAME               "SmartAmp"
+#define        SDCA_FUNCTION_TYPE_SIMPLE_AMP_NAME              "SimpleAmp"
+#define        SDCA_FUNCTION_TYPE_SMART_MIC_NAME               "SmartMic"
+#define        SDCA_FUNCTION_TYPE_SIMPLE_MIC_NAME              "SimpleMic"
+#define        SDCA_FUNCTION_TYPE_SPEAKER_MIC_NAME             "SpeakerMic"
+#define        SDCA_FUNCTION_TYPE_UAJ_NAME                     "UAJ"
+#define        SDCA_FUNCTION_TYPE_RJ_NAME                      "RJ"
+#define        SDCA_FUNCTION_TYPE_SIMPLE_NAME                  "SimpleJack"
+#define        SDCA_FUNCTION_TYPE_HID_NAME                     "HID"
+#define        SDCA_FUNCTION_TYPE_IMP_DEF_NAME                 "ImplementationDefined"
 
+/**
+ * enum sdca_entity0_controls - SDCA Controls for Entity 0
+ *
+ * Control Selectors for Entity 0 from SDCA specification v1.0 Section
+ * 6.7.1.1.
+ */
 enum sdca_entity0_controls {
        SDCA_CTL_ENTITY_0_COMMIT_GROUP_MASK             = 0x01,
        SDCA_CTL_ENTITY_0_FUNCTION_SDCA_VERSION         = 0x04,

diff --git a/sound/soc/sdca/sdca_device.c b/sound/soc/sdca/sdca_device.c
index b6399b773986c01f812496f630507fca327a4f2b..0244cdcdd109a7e0b326e791bdc78a7d9fb16d49 100644 (file)
--- a/sound/soc/sdca/sdca_device.c
+++ b/sound/soc/sdca/sdca_device.c
@@ -48,8 +48,7 @@ static bool sdca_device_quirk_rt712_vb(struct sdw_slave *slave)
                return false;
 
        for (i = 0; i < slave->sdca_data.num_functions; i++) {
-               if (slave->sdca_data.sdca_func[i].type ==
-                   SDCA_FUNCTION_TYPE_SMART_MIC)
+               if (slave->sdca_data.function[i].type == SDCA_FUNCTION_TYPE_SMART_MIC)
                        return true;
        }
 

diff --git a/sound/soc/sdca/sdca_functions.c b/sound/soc/sdca/sdca_functions.c
index 38071bc838b950ce0f3d6760d64f8b7f15d6763d..00d6d044c816bbf9e6d6e363e28861afec4a5bf2 100644 (file)
--- a/sound/soc/sdca/sdca_functions.c
+++ b/sound/soc/sdca/sdca_functions.c
@@ -10,6 +10,7 @@
 
 #include <linux/acpi.h>
 #include <linux/device.h>
+#include <linux/dev_printk.h>
 #include <linux/module.h>
 #include <linux/property.h>
 #include <linux/soundwire/sdw.h>
@@ -21,7 +22,7 @@ static int patch_sdca_function_type(u32 interface_revision, u32 *function_type)
 {
        /*
         * Unfortunately early SDCA specifications used different indices for Functions,
-        * for backwards compatibility we have to reorder the values found
+        * for backwards compatibility we have to reorder the values found.
         */
        if (interface_revision < 0x0801) {
                switch (*function_type) {
@@ -85,7 +86,7 @@ static int find_sdca_function(struct acpi_device *adev, void *data)
        struct fwnode_handle *control5; /* used to identify function type */
        const char *function_name;
        u32 function_type;
-       int func_index;
+       int function_index;
        u64 addr;
        int ret;
 
@@ -145,24 +146,35 @@ static int find_sdca_function(struct acpi_device *adev, void *data)
                 function_name, function_type, addr);
 
        /* store results */
-       func_index = sdca_data->num_functions;
-       sdca_data->sdca_func[func_index].adr = addr;
-       sdca_data->sdca_func[func_index].type = function_type;
-       sdca_data->sdca_func[func_index].name = function_name;
+       function_index = sdca_data->num_functions;
+       sdca_data->function[function_index].adr = addr;
+       sdca_data->function[function_index].type = function_type;
+       sdca_data->function[function_index].name = function_name;
        sdca_data->num_functions++;
 
        return 0;
 }
 
+/**
+ * sdca_lookup_functions - Parse sdca_device_desc for each Function
+ * @slave: SoundWire slave device to be processed.
+ *
+ * Iterate through the available SDCA Functions and fill in a short
+ * descriptor (struct sdca_function_desc) for each function, this
+ * information is stored along with the SoundWire slave device and
+ * used for adding drivers and quirks before the devices have fully
+ * probed.
+ */
 void sdca_lookup_functions(struct sdw_slave *slave)
 {
        struct device *dev = &slave->dev;
        struct acpi_device *adev = to_acpi_device_node(dev->fwnode);
 
        if (!adev) {
-               dev_info(dev, "No matching ACPI device found, ignoring peripheral\n");
+               dev_info(dev, "no matching ACPI device found, ignoring peripheral\n");
                return;
        }
+
        acpi_dev_for_each_child(adev, find_sdca_function, &slave->sdca_data);
 }
 EXPORT_SYMBOL_NS(sdca_lookup_functions, "SND_SOC_SDCA");