CRAS: iodev - Rename internal_capture_gain

Commit 11467d6 have changed the `capture_gain` field on a node
to be never changed by client. However it's still not clear enough
and could cause confusion to developers. This change renames it
to be more explicit.

BUG=b:314252855
TEST=None

Change-Id: Ie7a6f6c4a74cd27b17fd270c74cdc927000aed31
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/adhd/+/5075743
Tested-by: chromeos-cop-builder@chromeos-cop.iam.gserviceaccount.com <chromeos-cop-builder@chromeos-cop.iam.gserviceaccount.com>
Commit-Queue: Hsinyu Chao <hychao@chromium.org>
Tested-by: Hsinyu Chao <hychao@chromium.org>
Reviewed-by: Li-Yu Yu <aaronyu@google.com>

cras/client/cras-sys/src/lib.rs

@@ -393,7 +393,7 @@ impl Default for audio_dev_debug_info {
             runtime_nsec: 0,
             longest_wake_sec: 0,
             longest_wake_nsec: 0,
-            software_gain_scaler: 0.0,
+            internal_gain_scaler: 0.0,
             dev_idx: 0,
         }
     }
@@ -423,7 +423,7 @@ pub struct AudioDevDebugInfo {
         serialize_with = "serialize_duration_secs"
     )]
     pub longest_wake: Duration,
-    pub software_gain_scaler: f64,
+    pub internal_gain_scaler: f64,
 }
 
 impl From<audio_dev_debug_info> for AudioDevDebugInfo {
@@ -444,7 +444,7 @@ impl From<audio_dev_debug_info> for AudioDevDebugInfo {
             highest_hw_level: info.highest_hw_level,
             runtime: Duration::new(info.runtime_sec.into(), info.runtime_nsec),
             longest_wake: Duration::new(info.longest_wake_sec.into(), info.longest_wake_nsec),
-            software_gain_scaler: info.software_gain_scaler,
+            internal_gain_scaler: info.internal_gain_scaler,
         }
     }
 }
@@ -470,7 +470,7 @@ impl fmt::Display for AudioDevDebugInfo {
         writeln!(f, "  Highest hardware level: {}", self.highest_hw_level)?;
         writeln!(f, "  Runtime: {:?}", self.runtime)?;
         writeln!(f, "  Longest wake: {:?}", self.longest_wake)?;
-        writeln!(f, "  Software gain scaler: {}", self.software_gain_scaler)?;
+        writeln!(f, "  Internal gain scaler: {}", self.internal_gain_scaler)?;
         Ok(())
     }
 }

cras/include/cras_types.h

@@ -457,7 +457,7 @@ struct __attribute__((__packed__)) audio_dev_debug_info {
   uint32_t runtime_nsec;
   uint32_t longest_wake_sec;
   uint32_t longest_wake_nsec;
-  double software_gain_scaler;
+  double internal_gain_scaler;
   uint32_t dev_idx;
 };
 

cras/src/server/audio_thread.c

@@ -511,8 +511,8 @@ static void append_dev_dump_info(struct audio_dev_debug_info* di,
   di->num_underruns = cras_iodev_get_num_underruns(adev->dev);
   di->num_severe_underruns = cras_iodev_get_num_severe_underruns(adev->dev);
   di->highest_hw_level = adev->dev->highest_hw_level;
-  di->software_gain_scaler = (adev->dev->direction == CRAS_STREAM_INPUT)
-                                 ? adev->dev->software_gain_scaler
+  di->internal_gain_scaler = (adev->dev->direction == CRAS_STREAM_INPUT)
+                                 ? adev->dev->internal_gain_scaler
                                  : 0.0f;
 
   clock_gettime(CLOCK_MONOTONIC_RAW, &now);

cras/src/server/cras_alsa_io.c

@@ -759,7 +759,7 @@ static void set_alsa_capture_gain(struct cras_iodev* iodev) {
         aio->common.mixer, ain ? ain->mixer_input : NULL);
     max_capture_gain = cras_alsa_mixer_get_maximum_capture_gain(
         aio->common.mixer, ain ? ain->mixer_input : NULL);
-    gain = MAX(iodev->active_node->capture_gain, min_capture_gain);
+    gain = MAX(iodev->active_node->internal_capture_gain, min_capture_gain);
     gain = MIN(gain, max_capture_gain);
   }
 
@@ -1033,7 +1033,7 @@ static void set_input_default_node_gain(struct alsa_input_node* input,
                                         struct alsa_io* aio) {
   long gain;
 
-  input->base.capture_gain = DEFAULT_CAPTURE_GAIN;
+  input->base.internal_capture_gain = DEFAULT_CAPTURE_GAIN;
   input->base.ui_gain_scaler = 1.0f;
 
   if (!aio->common.ucm) {
@@ -1042,7 +1042,7 @@ static void set_input_default_node_gain(struct alsa_input_node* input,
 
   if (ucm_get_default_node_gain(aio->common.ucm, input->base.ucm_name, &gain) ==
       0) {
-    input->base.capture_gain = gain;
+    input->base.internal_capture_gain = gain;
   }
 }
 
@@ -1064,11 +1064,11 @@ static void set_input_node_intrinsic_sensitivity(struct alsa_input_node* input,
   }
 
   input->base.intrinsic_sensitivity = sensitivity;
-  input->base.capture_gain = DEFAULT_CAPTURE_VOLUME_DBFS - sensitivity;
+  input->base.internal_capture_gain = DEFAULT_CAPTURE_VOLUME_DBFS - sensitivity;
   syslog(LOG_DEBUG,
          "Use software gain %ld for %s because IntrinsicSensitivity %ld is"
          " specified in UCM",
-         input->base.capture_gain, input->base.name, sensitivity);
+         input->base.internal_capture_gain, input->base.name, sensitivity);
 }
 
 static void check_auto_unplug_output_node(struct alsa_io* aio,

cras/src/server/cras_alsa_usb_io.c

@@ -523,7 +523,7 @@ static void usb_set_alsa_capture_gain(struct cras_iodev* iodev) {
         aio->common.mixer, ain ? ain->mixer_input : NULL);
     max_capture_gain = cras_alsa_mixer_get_maximum_capture_gain(
         aio->common.mixer, ain ? ain->mixer_input : NULL);
-    gain = MAX(iodev->active_node->capture_gain, min_capture_gain);
+    gain = MAX(iodev->active_node->internal_capture_gain, min_capture_gain);
     gain = MIN(gain, max_capture_gain);
   }
 
@@ -728,7 +728,7 @@ static void usb_set_input_default_node_gain(struct alsa_usb_input_node* input,
                                             struct alsa_usb_io* aio) {
   long gain;
 
-  input->base.capture_gain = DEFAULT_CAPTURE_GAIN;
+  input->base.internal_capture_gain = DEFAULT_CAPTURE_GAIN;
   input->base.ui_gain_scaler = 1.0f;
 
   if (!aio->common.ucm) {
@@ -737,7 +737,7 @@ static void usb_set_input_default_node_gain(struct alsa_usb_input_node* input,
 
   if (ucm_get_default_node_gain(aio->common.ucm, input->base.ucm_name, &gain) ==
       0) {
-    input->base.capture_gain = gain;
+    input->base.internal_capture_gain = gain;
   }
 }
 
@@ -763,13 +763,13 @@ static void usb_set_input_node_intrinsic_sensitivity(
     sensitivity = DEFAULT_CAPTURE_VOLUME_DBFS;
   }
   input->base.intrinsic_sensitivity = sensitivity;
-  input->base.capture_gain = DEFAULT_CAPTURE_VOLUME_DBFS - sensitivity;
+  input->base.internal_capture_gain = DEFAULT_CAPTURE_VOLUME_DBFS - sensitivity;
   syslog(LOG_INFO,
          "card type: %s, Use software gain %ld for %s because "
          "IntrinsicSensitivity %ld is"
          " specified in UCM",
          cras_card_type_to_string(aio->common.card_type),
-         input->base.capture_gain, input->base.name, sensitivity);
+         input->base.internal_capture_gain, input->base.name, sensitivity);
 }
 
 static void usb_check_auto_unplug_output_node(struct alsa_usb_io* aio,

cras/src/server/cras_bt_io.c

@@ -93,7 +93,7 @@ static struct cras_ionode* add_profile_dev(struct cras_iodev* bt_iodev,
   n->base.type = CRAS_NODE_TYPE_BLUETOOTH;
   n->base.volume = 100;
   n->base.stable_id = dev->info.stable_id;
-  n->base.capture_gain = 0;
+  n->base.internal_capture_gain = 0;
   gettimeofday(&n->base.plugged_time, NULL);
 
   strlcpy(n->base.name, dev->info.name, sizeof(n->base.name));

cras/src/server/cras_iodev.c

@@ -912,9 +912,10 @@ float cras_iodev_get_software_volume_scaler(struct cras_iodev* iodev) {
   return softvol_get_scaler_default(volume);
 }
 
-float cras_iodev_get_software_gain_scaler(const struct cras_iodev* iodev) {
+float cras_iodev_get_internal_gain_scaler(const struct cras_iodev* iodev) {
   if (cras_iodev_software_volume_needed(iodev)) {
-    return convert_softvol_scaler_from_dB(iodev->active_node->capture_gain);
+    return convert_softvol_scaler_from_dB(
+        iodev->active_node->internal_capture_gain);
   }
   return 1.0f;
 }
@@ -1202,7 +1203,7 @@ int cras_iodev_open(struct cras_iodev* iodev,
      * control. For alsa device, this gain value will be configured
      * based on UCM labels IntrinsicSensitivity.
      */
-    iodev->software_gain_scaler = cras_iodev_get_software_gain_scaler(iodev);
+    iodev->internal_gain_scaler = cras_iodev_get_internal_gain_scaler(iodev);
   }
 
   add_ext_dsp_module_to_pipeline(iodev);

cras/src/server/cras_iodev.h

@@ -111,8 +111,9 @@ struct cras_ionode {
   unsigned int volume;
   // Internal per-node capture gain/attenuation (in 100*dBFS)
   // This is only used for CRAS internal tuning, no way to change by
-  // client.
-  long capture_gain;
+  // client. The value could be used in setting mixer controls in HW
+  // or converted to SW scaler based on device configuration.
+  long internal_capture_gain;
   // The adjustable gain scaler set by client.
   float ui_gain_scaler;
   // If left and right output channels are swapped.
@@ -335,10 +336,10 @@ struct cras_iodev {
   int is_enabled;
   // True if volume control is not supported by hardware.
   int software_volume_needed;
-  // Scaler value to apply to captured data. This can
-  // be different when active node changes. Configured when there's no
-  // hardware gain control.
-  float software_gain_scaler;
+  // Adjust captured data by applying a software gain.
+  // This scaler value may vary depending on the active node.
+  // Configure this value when hardware gain control is unavailable.
+  float internal_gain_scaler;
   // List of audio streams serviced by dev.
   struct dev_stream* streams;
   // Device is in one of close, open, normal, or no_stream state defined
@@ -653,7 +654,7 @@ static inline bool cras_iodev_can_start(const struct cras_iodev* iodev) {
  * Returns:
  *    A scaler translated from system gain and active node gain.
  *    Returns 1.0 if software gain is not needed. */
-float cras_iodev_get_software_gain_scaler(const struct cras_iodev* iodev);
+float cras_iodev_get_internal_gain_scaler(const struct cras_iodev* iodev);
 
 /* Gets the software volume scaler of the iodev. The scaler should only be
  * applied if the device needs software volume. */

cras/src/server/cras_iodev_list.c

@@ -337,7 +337,7 @@ static int fill_node_list(struct iodev_list* list,
       node_info->plugged_time.tv_usec = node->plugged_time.tv_usec;
       node_info->active = dev->is_enabled && (dev->active_node == node);
       node_info->volume = node->volume;
-      node_info->capture_gain = node->capture_gain;
+      node_info->capture_gain = node->internal_capture_gain;
       node_info->ui_gain_scaler = node->ui_gain_scaler;
       node_info->left_right_swapped = node->left_right_swapped;
       node_info->display_rotation = node->display_rotation;

cras/src/server/dev_io.c

@@ -630,7 +630,7 @@ static int capture_to_streams(struct open_dev* adev,
       }
 
       struct input_data_gain gains = input_data_get_software_gain_scaler(
-          idev->input_data, ui_gain_scaler, idev->software_gain_scaler,
+          idev->input_data, ui_gain_scaler, idev->internal_gain_scaler,
           stream->stream);
 
       input_data_get_for_stream(idev->input_data, stream->stream,

cras/src/tests/alsa_io_unittest.cc

@@ -535,7 +535,7 @@ TEST(AlsaIoInit, SoftwareGainIntrinsicSensitivity) {
   ASSERT_EQ(0, alsa_iodev_legacy_complete_init(iodev));
   ASSERT_EQ(intrinsic_sensitivity, iodev->active_node->intrinsic_sensitivity);
   ASSERT_EQ(DEFAULT_CAPTURE_VOLUME_DBFS - intrinsic_sensitivity,
-            iodev->active_node->capture_gain);
+            iodev->active_node->internal_capture_gain);
 
   alsa_iodev_destroy(iodev);
 }
@@ -677,7 +677,7 @@ TEST(AlsaIoInit, OpenCaptureSetCaptureGainWithDefaultNodeGain) {
   cras_iodev_set_format(iodev, &format);
 
   // Check the default node gain is the same as what specified in UCM.
-  EXPECT_EQ(default_node_gain, iodev->active_node->capture_gain);
+  EXPECT_EQ(default_node_gain, iodev->active_node->internal_capture_gain);
   cras_alsa_mixer_get_minimum_capture_gain_ret_value = 0;
   cras_alsa_mixer_get_maximum_capture_gain_ret_value = 2000;
 
@@ -727,7 +727,7 @@ TEST(AlsaIoInit, OpenCaptureSetCaptureGainWithSoftwareGain) {
 
   // Test the case where software gain is not needed.
   iodev->active_node->software_volume_needed = 0;
-  iodev->active_node->capture_gain = 1000;
+  iodev->active_node->internal_capture_gain = 1000;
   iodev->open_dev(iodev);
   iodev->configure_dev(iodev);
   iodev->close_dev(iodev);
@@ -1466,7 +1466,7 @@ TEST(AlsaOutputNode, InputsFromUCM) {
   EXPECT_EQ(1, cras_alsa_jack_enable_ucm_called);
   EXPECT_EQ(1, ucm_set_enabled_called);
   ASSERT_EQ(DEFAULT_CAPTURE_VOLUME_DBFS - intrinsic_sensitivity,
-            iodev->active_node->capture_gain);
+            iodev->active_node->internal_capture_gain);
 
   alsa_iodev_destroy(iodev);
 }

cras/src/tests/cras_alsa_usb_io_unittest.cc

@@ -340,7 +340,7 @@ TEST(AlsaIoInit, DefaultNodeUSBCard) {
   // No extra gain applied.
   ASSERT_EQ(DEFAULT_CAPTURE_VOLUME_DBFS,
             aio->common.base.active_node->intrinsic_sensitivity);
-  ASSERT_EQ(0, aio->common.base.active_node->capture_gain);
+  ASSERT_EQ(0, aio->common.base.active_node->internal_capture_gain);
   iodev->close_dev(iodev);
   cras_alsa_usb_iodev_destroy(iodev);
   free(fake_format);
@@ -361,7 +361,7 @@ TEST(AlsaIoInit, OpenCaptureSetCaptureGainWithDefaultUsbDevice) {
   ASSERT_EQ(0, cras_alsa_usb_iodev_legacy_complete_init(iodev));
 
   iodev->active_node->intrinsic_sensitivity = DEFAULT_CAPTURE_VOLUME_DBFS;
-  iodev->active_node->capture_gain = 0;
+  iodev->active_node->internal_capture_gain = 0;
 
   iodev->open_dev(iodev);
   iodev->configure_dev(iodev);

cras/src/tests/iodev_unittest.cc

@@ -1256,15 +1256,15 @@ TEST(IoDev, SoftwareGain) {
   iodev.active_node = &ionode;
   iodev.active_node->dev = &iodev;
 
-  ionode.capture_gain = 2400;
+  ionode.internal_capture_gain = 2400;
   ionode.software_volume_needed = 1;
 
   // 2400 * 0.01 dB is 15.848931
-  EXPECT_FLOAT_EQ(15.848931, cras_iodev_get_software_gain_scaler(&iodev));
+  EXPECT_FLOAT_EQ(15.848931, cras_iodev_get_internal_gain_scaler(&iodev));
 
   // Software gain scaler should be 1.0 if software gain is not needed.
   ionode.software_volume_needed = 0;
-  EXPECT_FLOAT_EQ(1.0, cras_iodev_get_software_gain_scaler(&iodev));
+  EXPECT_FLOAT_EQ(1.0, cras_iodev_get_internal_gain_scaler(&iodev));
 }
 
 // This get_buffer implementation set returned frames larger than requested

cras/src/tools/cras_test_client/cras_test_client.c

@@ -1149,7 +1149,7 @@ static void print_aligned_audio_debug_info(const struct audio_debug_info* info,
         (unsigned int)info->devs[i].runtime_nsec,
         (unsigned int)info->devs[i].longest_wake_sec,
         (unsigned int)info->devs[i].longest_wake_nsec,
-        info->devs[i].software_gain_scaler);
+        info->devs[i].internal_gain_scaler);
     printf("\n");
   }