path: root/drivers/misc/nvs/nvs_light.c

/* Copyright (c) 2014-2017, NVIDIA CORPORATION.  All rights reserved.
 *
 * This software is licensed under the terms of the GNU General Public
 * License version 2, as published by the Free Software Foundation, and
 * may be copied, distributed, and modified under those terms.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 */
/* The NVS = NVidia Sensor framework */
/* This common NVS ALS module allows, along with the NVS IIO common module, an
 * ALS driver to offload the code interacting with IIO and ALS reporting, and
 * just have code that interacts with the HW.
 * The commonality between this module and the NVS ALS driver is the nvs_light
 * structure.  It is expected that the NVS ALS driver will:
 * - call nvs_light_enable when the device is enabled to initialize variables.
 * - read the HW and place the value in nvs_light.hw
 * - call nvs_light_read
 * - depending on the nvs_light_read return value:
 *     - -1 = poll HW using nvs_light.poll_delay_ms delay.
 *     - 0 = if interrupt driven, do nothing or resume regular polling
 *     - 1 = set new thresholds using the nvs_light.hw_thresh_lo/hi
 * Reporting the lux is handled within this module.
 * See nvs_light.h for nvs_light structure details.
 */
/* The NVS HAL will use the IIO scale and offset sysfs attributes to modify the
 * data using the following formula: (data * scale) + offset
 * A scale value of 0 disables scale.
 * A scale value of 1 puts the NVS HAL into calibration mode where the scale
 * and offset are read everytime the data is read to allow realtime calibration
 * of the scale and offset values to be used in the device tree parameters.
 * Keep in mind the data is buffered but the NVS HAL will display the data and
 * scale/offset parameters in the log.  See calibration steps below.
 */
/* The configuration threshold values are HW value based.  In other words, to
 * obtain the upper and lower HW thresholds, the configuration threshold is
 * simply added or subtracted from the HW data read, respectively.
 * A little history about this: this code originally expected the configuration
 * threshold values to be in lux.  It then converted the threshold lux value to
 * a HW value by reversing the calibrated value to uncalibrated and then the
 * scaling of the resolution.  The idea was to make configuration easy by just
 * setting how much lux needed to change before reporting.  However, there were
 * two issues with this method:
 * 1) that's a lot of overhead for each sample, and 2) the lux range isn't
 * exactly linear.  Lux values in a dark room will probably want to be reported
 * every +/- 100 or 10 if not less.  This is opposed to a bright room or even
 * outside on a sunny day where lux value changes can be reported every
 * +/- 1000 or even 10000.  Since many ALS's have dynamic resolution, changing
 * the range depending on the lux reading, it makes sense to use HW threshold
 * values that will automatically scale with the HW resolution used.
 */
/* NVS light drivers have two calibration mechanisms.  Method 1 is required if
 * the driver is using dynamic resolution since the resolution cannot be read
 * by the NVS HAL on every data value read due to buffering.  So instead.a
 * mechanism allows floating point to be calculated here in the kernel by
 * shifting up to integer the floating point significant amount.  This allows
 * real-time resolution changes without the NVS HAL having to synchronize to
 * the actual resolution for each datum.  The scale.fval must be a 10 base
 * value, e.g. 0.1, 0.01, ... 0.000001, etc. as the significant amount.
 * The NVS HAL will then convert the value to float by multiplying the integer
 * float-data with scale.
 * Method 1:
 * This method uses interpolation and requires a low and high uncalibrated
 * value along with the corresponding low and high calibrated values.  The
 * uncalibrated values are what is read from the sensor in the steps below.
 * The corresponding calibrated values are what the correct value should be.
 * All values are programmed into the device tree settings.
 * 1. Read scale sysfs attribute.  This value will need to be written back.
 * 2. Disable device.  (Write 0 = buffer/enable sysfs attribute)
 * 3. Write 1 to the scale sysfs attribute (e.g. in_illuminance_scale).
 * 4. Enable device. (Write 1 = buffer/enable sysfs attribute)
 * 5. The NVS HAL will announce in the 'logcat -v time | grep -i "sensors"'
 *    that calibration mode is enabled and
 *    display the data along with the scale and offset parameters applied.
 * 6. Write the scale value read in step 1 back to the scale sysfs attribute.
 * 7. Put the device into a state where the data read is a low value.
 *    (Generate light source < 100 lux.)
 * 8. Note the values displayed in the log.  Separately measure the actual
 *    value with a high accuracy light meter.  Make sure the light meter
 *    is calibrated to the same color temperature as your light source.
 *    The value from the sensor will be the uncalibrated value and the
 *    separately measured value will be the calibrated value for the current
 *    state (low or high values).
 *    Device Tree nodes related to light calibration:
 *    light_uncalibrated_lo <-- Value found in logcat.
 *    light_calibrated_lo <-- Value read from light meter.
 * 9. Put the device into a state where the data read is a high value.
 *    (Generate light source > 3000 lux.)
 * 10. Repeat step 8.
 *    Device Tree nodes related to light calibration:
 *    light_uncalibrated_hi <-- Value found in logcat.
 *    light_calibrated_hi <-- Value read from light meter.
 * 11. Enter the values in the device tree settings for the device.  Both
 *     calibrated and uncalibrated values will be the values before scale and
 *     offset are applied.
 *     The light sensor has the following device tree parameters for this:
 *     light_uncalibrated_lo
 *     light_calibrated_lo
 *     light_uncalibrated_hi
 *     light_calibrated_hi
 *
 * To test calibration values in realtime.
 * An NVS ALS driver may support a simplified version of method 1 that can be
 * used in realtime:
 * 1. At step 8, while the light source is still at this low value,
 *    write the light meter value to the in_illuminance_threshold_low
 *    attribute.  When in calibration mode this value will be written to the
 *    light_calibrated_lo and the current lux written to light_uncalibrated_lo
 *    internal to the driver.
 * 2. If this is after step 9, while the light source is still at this high
 *    value, write the light meter value to the in_illuminance_threshold_high
 *    attribute.
 * 3. To confirm the realtime values and see what the driver used for
 *    uncalibrated values, do the following at the adb prompt in the driver
 *    space:
 *    # echo 5 > nvs
 *    # cat nvs
 *    This will be a partial dump of the sensor's configuration structure that
 *    will show the calibrated and uncalibrated values.  For example:
 *    ...
 *    uncal_lo=52	<-- Program this value into DT: light_uncalibrated_lo
 *    uncal_hi=1627	<-- Program this value into DT: light_uncalibrated_hi
 *    cal_lo=8050	<-- Program this value into DT: light_calibrated_lo
 *    cal_hi=308000	<-- Program this value into DT: light_calibrated_hi
 *    thresh_lo=10
 *    thresh_hi=10
 *    ...
 * Note that the calibrated value must be the value before the scale and offset
 * is applied.  For example, if the calibrated lux reading is 123.4 lux, and
 * the in_illuminance_scale is normally 0.01, then the value entered is 12340
 * which will be 123.4 lux when the scale is applied at the HAL layer.
 *
 * If the thresholds have changed instead of the calibration settings, then
 * the driver doesn't support this feature.
 * In order to display raw values, interpolation, that uses the calibration
 * values, is not executed by the driver when in calibration mode, so to test,
 * disable and reenable the device to exit calibration mode and test the new
 * calibration values.
 *
 *
 * Method 2 can only be used if dynamic resolution is not used by the HW
 * driver.  The data passed up to the HAL is the HW value read so that the HAL
 * can multiply the HW value with the scale (resolution).
 * As a baseline, scale would be the same value as the static resolution.
 * Method 2:
 * 1. Disable device.
 * 2. Write 1 to the scale sysfs attribute.
 * 3. Enable device.
 * 4. The NVS HAL will announce in the log that calibration mode is enabled and
 *    display the data along with the scale and offset parameters applied.
 * 5. Write to scale and offset sysfs attributes as needed to get the data
 *    modified as desired.
 * 6. Disabling the device disables calibration mode.
 * 7. Set the new scale and offset parameters in the device tree:
 *    light_scale_ival = the integer value of the scale.
 *    light_scale_fval = the floating value of the scale.
 *    light_offset_ival = the integer value of the offset.
 *    light_offset_fval = the floating value of the offset.
 *    The values are in the NVS_FLOAT_SIGNIFICANCE_ format (see nvs.h).
 */


#include <linux/module.h>
#include <linux/of.h>
#include <linux/version.h>
#include <linux/nvs_light.h>

#define NVS_LIGHT_VERSION		(106)


ssize_t nvs_light_dbg(struct nvs_light *nl, char *buf)
{
	ssize_t t;
	unsigned int n;
	unsigned int i;

	t = snprintf(buf, PAGE_SIZE, "%s v.%u:\n",
		     __func__, NVS_LIGHT_VERSION);
	t += snprintf(buf + t, PAGE_SIZE - t, "timestamp=%lld\n",
		      nl->timestamp);
	t += snprintf(buf + t, PAGE_SIZE - t, "timestamp_report=%lld\n",
		      nl->timestamp_report);
	t += snprintf(buf + t, PAGE_SIZE - t, "lux=%u\n", nl->lux);
	t += snprintf(buf + t, PAGE_SIZE - t, "lux_max=%u\n", nl->lux_max);
	t += snprintf(buf + t, PAGE_SIZE - t, "hw=%u\n", nl->hw);
	t += snprintf(buf + t, PAGE_SIZE - t, "hw_mask=%x\n", nl->hw_mask);
	t += snprintf(buf + t, PAGE_SIZE - t, "hw_thresh_lo=%u\n",
		      nl->hw_thresh_lo);
	t += snprintf(buf + t, PAGE_SIZE - t, "hw_thresh_hi=%u\n",
		      nl->hw_thresh_hi);
	t += snprintf(buf + t, PAGE_SIZE - t, "hw_limit_lo=%x\n",
		      nl->hw_limit_lo);
	t += snprintf(buf + t, PAGE_SIZE - t, "hw_limit_hi=%x\n",
		      nl->hw_limit_hi);
	t += snprintf(buf + t, PAGE_SIZE - t, "thresh_valid_lo=%x\n",
		      nl->thresh_valid_lo);
	t += snprintf(buf + t, PAGE_SIZE - t, "thresh_valid_hi=%x\n",
		      nl->thresh_valid_hi);
	t += snprintf(buf + t, PAGE_SIZE - t, "thresholds_valid=%x\n",
		      nl->thresholds_valid);
	t += snprintf(buf + t, PAGE_SIZE - t, "nld_i_change=%x\n",
		      nl->nld_i_change);
	t += snprintf(buf + t, PAGE_SIZE - t, "calibration_en=%x\n",
		      nl->calibration_en);
	t += snprintf(buf + t, PAGE_SIZE - t, "poll_delay_ms=%u\n",
		      nl->poll_delay_ms);
	t += snprintf(buf + t, PAGE_SIZE - t, "delay_us=%u\n", nl->delay_us);
	t += snprintf(buf + t, PAGE_SIZE - t, "report=%u\n", nl->report);
	t += snprintf(buf + t, PAGE_SIZE - t, "nld_i=%u\n", nl->nld_i);
	t += snprintf(buf + t, PAGE_SIZE - t, "nld_i_lo=%u\n", nl->nld_i_lo);
	t += snprintf(buf + t, PAGE_SIZE - t, "nld_i_hi=%u\n", nl->nld_i_hi);
	t += snprintf(buf + t, PAGE_SIZE - t, "nld_tbl_n=%u\n", nl->nld_tbl_n);
	if (nl->nld_tbl) {
		if (nl->nld_tbl_n) {
			i = 0;
			n = nl->nld_tbl_n;
		} else {
			i = nl->nld_i_lo;
			n = nl->nld_i_hi + 1;
		}
		for (; i < n; i++) {
			if (nl->nld_thr) {
				t += snprintf(buf + t, PAGE_SIZE - t,
					      "nld_thr[%u].lo=%u\n",
					      i, nl->nld_thr[i].lo);
				t += snprintf(buf + t, PAGE_SIZE - t,
					      "nld_thr[%u].hi=%u\n",
					      i, nl->nld_thr[i].hi);
				t += snprintf(buf + t, PAGE_SIZE - t,
					      "nld_thr[%u].i_lo=%u\n",
					      i, nl->nld_thr[i].i_lo);
				t += snprintf(buf + t, PAGE_SIZE - t,
					      "nld_thr[%u].i_hi=%u\n",
					      i, nl->nld_thr[i].i_hi);
			}
			if (nl->cfg->float_significance) {
				t += snprintf(buf + t, PAGE_SIZE - t,
					    "nld_tbl[%d].resolution=%d.%09u\n",
					     i, nl->nld_tbl[i].resolution.ival,
					     nl->nld_tbl[i].resolution.fval);
				t += snprintf(buf + t, PAGE_SIZE - t,
					     "nld_tbl[%d].max_range=%d.%09u\n",
					      i, nl->nld_tbl[i].max_range.ival,
					      nl->nld_tbl[i].max_range.fval);
				t += snprintf(buf + t, PAGE_SIZE - t,
					      "nld_tbl[%d].milliamp=%d.%09u\n",
					      i, nl