From bfd3b0831268b24a1f3e54fbc1d5978409882a91 Mon Sep 17 00:00:00 2001 From: Amaury Pouly Date: Sat, 20 Aug 2016 21:26:58 +0100 Subject: Document AUDIOHW_SETTING Everytime I use it, I get highly confused because it's complicated and undocumented. The code is spread all over the place and some targets clearly use incorrect values. This is the first step of a series to cleanup audio settings and document it properly. Change-Id: I20cb7af2bfa33986cb8b0bf8573f17a92227f893 --- firmware/export/audiohw.h | 104 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 100 insertions(+), 4 deletions(-) (limited to 'firmware/export/audiohw.h') diff --git a/firmware/export/audiohw.h b/firmware/export/audiohw.h index acf5fda9f1..e6bb8dc3fc 100644 --- a/firmware/export/audiohw.h +++ b/firmware/export/audiohw.h @@ -57,6 +57,102 @@ struct sound_settings_info }; #undef AUDIOHW_SETTING /* will have been #defined in config.h as empty */ +/* Use AUDIOHW_SETTING to create an audio setting. There are two ways to use this + * macro: + * AUDIOHW_SETTING(name, unit, nr_decimals, step, min, max, default) + * AUDIOHW_SETTING(name, unit, nr_decimals, step, min, max, default, expr) + * + * It is important to understand that each setting has two scales: the hardware + * scale and the user scale. In the first form of the macro, they coincide. + * In the second form, the conversion from hardware to user is done by the + * expression [expr] provided in the extra argument (see examples below). The + * hardware scale ranges from [min] to [max], in steps of [step]. The default value + * is [default]. Furthermore, when displaying the value to the user, [nr_decimals] + * gives the number of decimal points to display. Thus if [nr_decimals] is 0 then + * a value of x means x [unit]. If [nr_decimals] is 1 then a value of x means + * x/10 [unit] and so on. Note that both [nr_decimals] and [unit] are irrelevant + * to the hardware, they simply provide a flexible way to show natural value to + * the user. When you want the user scale to be different than the hardware scale, + * you must provide [expr], an expression that can use the variable "val", which + * represents the hardware value, and converts it to the user value. The [expr] + * can involved a function call in very complicated/nonlinear cases, as long as + * the function does not have any side-effect. Finally, the [name] parameter + * must be one of the settings listed in audiohw_setting.h + * + * Examples: + * + * AUDIOHW_SETTING(VOLUME, "dB", 0, 1, -100, 12, -25) + * This describes the volume setting. The values are in dB (no decimal). The + * minimum value is -100 and the maximum is 12, with a step of 1 and a default + * value of -25. This means that the hardware can take any of the following value: + * -100, -99, -98, ..., 11,12 + * Since there is are decimals and no conversion expression, a hardware value of + * x means x dB. So a value of -25 means -25 dB, a value of 5 means 5 dB. + * WARNING VOLUME is actually special: whatever scale you choose, the sound code + * will always set the volume by calling audiohw_set_volume() with a centibel + * value (ie it will not perform any conversion). Thus it is strongly advised + * that you always choose a VOLUME scale with precision 1 (centibels) and no + * hardware conversion. + * + * AUDIOHW_SETTING(MDB_CENTER, "Hz", 0, 10, 20, 300, 60) + * This describes the MDB (dynbamic bass) center. The values are in Hz (no + * decimal). The minimum value is 20 and the maximum is 300, in steps of 10 + * and a default of 60. Thus hardware can take any of the following value: + * 20, 30, 40, ... 290, 300 + * Since there are no decimals and no conversion expression, a hardware of x + * means x Hz. So a value of 60 means 60 Hz. + * + * AUDIOHW_SETTING(BASS, "dB", 1, 15, -60, 90, 0) + * This describes the bass control. Since there is one decimal, the values are + * in tenth of dB. The minimum value is -60 and the maximum is 90, in steps of + * 15 and a default value of 0. Thus hardware can take any of the following value: + * -60, -45, -30, ... 60, 75, 90 + * Since there is one decimal, a hardware value of x means x/10 Hz. So a value + * of 60 means 60/10 = 6 dB. A value of -45 means -45/10 = -4.5 dB. + * + * AUDIOHW_SETTING(DEPTH_3D, "%", 0, 1, 0, 15, 0, (100 * val + 8) / 15) + * This describes 3D enhancement control. The values are in percentage (no + * decimal). This setting makes a difference between hardware and user scale. + * The minimal hardware value is 0 and the maximum is 15, in steps of 1 and + * a default of 0. Thus hardware can take any of the following value: + * 0, 1, 2, ... 14, 15 + * Because of the conversion expression, a hardware value of x means + * (100 * val + 8) / 15) %. A hardware value of 0 means (100 * 0 + 8) / 15) = 0 % + * because the result must be an integer (8 / 15 = 0). A hardware value of 1 + * means (100 * 1 + 8) / 15 = 7 %. A hardware value of 15 means + * (100 * 15 + 8) / 15 = 100 %. In fact, from the user point of view, the range + * of available values is: + * 0%, 7%, 13%, 20%, ..., 93%, 100% + * + * AUDIOHW_SETTING(LEFT_GAIN, "dB", 2, 15,-345, 1200, 0, val * 5) + * This describes the left gain. Since there are two decimals, the values are in + * hundredth of dB. This setting makes a difference between hardware and user scale. + * The minimal hardware value is -345 and the maximum is 1200, in steps of 15 and + * a default of 0. Thus hardware can take any of the following value: + * -345, -330, -315, ..., 1185, 1200 + * Because of the conversion expression, a hardware value of x means + * val * 5 hundredth of dB or, in other words, (val * 5)/100 dB (where we keep two + * decimals). A hardware value of -345 means -345 * 5 = -1725 hundredth of dB + * = -17,25 dB. A value of -330 means -330*5 = -1650 hundredth of dB = -16,50 dB. + * A value of 1200 means 1200 * 5 = 6000 hundredth of dB = 60 dB. In fact, + * from the user point of view, the range of available values is: + * -17.25 dB, -16.60 dB, ..., 59.25 dB, 60dB. + * + * AUDIOHW_SETTING(DEPTH_3D, "dB", 0, 1, 0, 3, 0, depth3d_phys2_val(val)) + * This describes 3D enhancement control. The values are in dB (no + * decimal). This setting makes a difference between hardware and user scale. + * The minimal hardware value is 0 and the maximum is 3, in steps of 1 and + * a default of 0. Thus hardware can take any of the following value: + * 0, 1, 2, 3 + * Because of the conversion expression, a hardware value of x means + * depth3d_phys2_val(x) dB. If for example the conversion functions is: + * int depth3d_phys2_val(int val) + * { + * return val == 0 ? 0 : val * 5 + 30; + * } + * then from the user point of view, the range of available values is: + * 0 dB, 35 dB, 40 dB, 45 dB + */ #define AUDIOHW_SETTING(name, us, nd, st, minv, maxv, defv, expr...) \ static const struct sound_settings_info _audiohw_setting_##name = \ { .unit = us, .numdecimals = nd, .steps = st, \ @@ -323,7 +419,7 @@ void audiohw_close(void); #ifdef AUDIOHW_HAVE_MONO_VOLUME /** * Set new volume value - * @param val to set. + * @param val to set in centibels. * NOTE: AUDIOHW_CAPS need to contain * CLIPPING_CAP */ @@ -331,8 +427,8 @@ void audiohw_set_volume(int val); #else /* Stereo volume */ /** * Set new volume value for each channel - * @param vol_l sets left channel volume - * @param vol_r sets right channel volume + * @param vol_l sets left channel volume in centibels. + * @param vol_r sets right channel volume in centibels. */ void audiohw_set_volume(int vol_l, int vol_r); #endif /* AUDIOHW_HAVE_MONO_VOLUME */ @@ -351,7 +447,7 @@ void audiohw_set_lineout_volume(int vol_l, int vol_r); || defined(AUDIOHW_HAVE_EQ) /** * Set new prescaler value. - * @param val to set. + * @param val to set in centibels. * NOTE: AUDIOHW_CAPS need to contain * PRESCALER_CAP */ -- cgit v1.2.3