drivers/sensors/tc74ax: add driver for TC74Ax thermal sensor

Documentation/components/drivers/special/sensors.rst

@@ -35,3 +35,4 @@ general interface.
     sensors/lis2mdl.rst
     sensors/l86xxx.rst
     sensors/gnss_lowerhalf.rst
+    sensors/tc74ax.rst

Documentation/components/drivers/special/sensors/sensors_legacy.rst

@@ -74,6 +74,7 @@ Drivers that are available also with the new sensor framework are marked with ``
 - sht3x
 - sps30
 - t67xx
+- :doc:`tc74ax`
 - veml6070
 - vl53l1x
 - xen1210

Documentation/components/drivers/special/sensors/tc74ax.rst

@@ -0,0 +1,180 @@
+======
+TC74Ax
+======
+
+Driver for TC74Ax thermal sensor by Microchip. There are multiple variants
+of this sensor named TC74A0, TC74A1, TC74A2 etc. up to TC74A7. This driver
+is suitable for all of them.
+
+.. Listed at least some of the chips by full name to make them visible
+.. for search engines
+
+Configuration
+=============
+
+As with other sensors, the driver is enabled
+in :menuselection:`Device Drivers --> Sensor device support`.
+It can be further configured as follows:
+
+I\ :sup:`2`\ C frequency
+------------------------
+
+I\ :sup:`2`\ C frequency used when communicating with the device.
+Must be in range of 10-100kHz.
+
+Power Management
+----------------
+
+The sensor is continuously doing temperature measurements since
+power-on. It also features a standby mode with reduced power consumption.
+The drivers has multiple options for doing power management:
+
+Standby unless opened
+^^^^^^^^^^^^^^^^^^^^^
+
+The driver will switch the sensor to standby mode during initialization.
+It is then kept in standby mode until an application opens corresponding
+device file.
+
+When all applications close the device file, the sensor is put back
+to standby mode.
+
+Manual control with ``ioctl``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sensor's operating mode is controlled manually using
+``SNIOC_SET_OPERATIONAL_MODE`` ``ioctl``. The parameter must
+be one of ``TC74AX_OPERATION_MODE_OPERATING`` or
+``TC74AX_OPERATION_MODE_STANDBY``. Example:
+
+.. code-block:: c
+
+   ioctl(sensor_fd, SNIOC_SET_OPERATIONAL_MODE, TC74AX_OPERATION_MODE_STANDBY);
+
+Note that attempt to read temperature from sensor in standby mode
+is considered an error and the driver will return ``EIO``.
+
+This selection unlocks an additional option to switch the sensor
+to standby mode during boot. If not selected, the sensor will be
+kept in running state.
+
+No power management
+^^^^^^^^^^^^^^^^^^^
+
+The driver provides no means for power management and the sensor
+is always kept in running state.
+
+Multimaster mode
+^^^^^^^^^^^^^^^^
+
+With this mode, it is assumed that the sensor is used by multiple
+I\ :sup:`2`\ C masters. Most notably, this relates to sensor's
+power management. The driver will obey its configuration for power
+management as given by previous configuration options but then it
+will make no assumptions on sensor's current state. Instead, it
+will determine it in runtime every time the temperature is read.
+
+Note that if no power management is configured and the driver
+finds that the sensor is in standby mode (presumably configured
+that way by another master), it will not be able to switch
+it to running state and will return ``EIO`` instead.
+
+See more details an additional information in Kconfig entry
+for this configuration item.
+
+API and usage
+=============
+
+Registration
+------------
+
+Include header file for the driver:
+
+
+.. code-block:: c
+
+   #include <nuttx/sensors/tc74ax.h>
+
+Register the device:
+
+.. code-block:: c
+
+   tc74ax_register("/dev/tc74ax", i2c, address);
+
+Parameter ``i2c`` is a pointer to ``struct i2c_master_s``. Address provided
+in ``address`` variable must be a positive number in range of 72-79. This is
+a base address of 72 with the chip variant (0-7) added to it.
+
+First parameter is a path in ``/dev`` and can be chosen to suit board's needs.
+
+Temperature reading
+-------------------
+
+The driver is not an
+:doc:`UORB </components/drivers/special/sensors/sensors_uorb>` driver,
+the application needs to read and interpret its values directly:
+
+.. code-block:: c
+
+   int8_t buffer;
+
+   fd = open("/dev/tc74ax", O_RDONLY);
+   res = read(fd, &buffer, 1);
+
+Value stored in ``buffer`` is a temperature in degrees Celsius.
+(See the datasheet for temperature range.)
+
+The read is synchronous. Whenever ``read`` function is called,
+the driver submits I\ :sup:`2`\ C request to read current temperature.
+
+In case of errors, the driver mostly returns error code
+from the underlying I\ :sup:`2`\ C driver. Other than that, most
+error conditions cause return of ``EIO``.
+
+Reading duration and timeouts
+-----------------------------
+
+The duration of read always depends on I\ :sup:`2`\ C bus being
+available and on time needed for the transmission. Other than that, there
+are additional factors that may increase the read duration.
+
+Wakeup from standby mode
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The sensor needs some time to do the first measurement after being
+switched from standby to running mode. The read will wait for that
+to happen.
+
+Multimaster contention
+^^^^^^^^^^^^^^^^^^^^^^
+
+In multimaster mode, the driver always reads the power state
+of the sensor before reading the temperature. The read therefore
+takes more time because 4 I\ :sup:`2`\ C messages need
+to be transmitted instead of one.
+
+Additionally - if the read detects that the sensor is in standby
+mode, the read duration increases by the time needed to wake it up
+and to do the first measurement.
+
+Note that if the contention is severe enough - that is, if the other
+master keeps switching the sensor to standby mode - the read may
+never complete successfully. There is a timeout imposed on total
+duration of reading attempts and ``EIO`` is returned if this timeout
+is exceeded.
+
+I/O error recovery
+------------------
+
+Whenever there is an I/O error on the I\ :sup:`2`\ C bus, recovery
+procedure may be needed. If configured for non-multimaster mode,
+this depends on power management mode:
+
+  * with no power management, no recovery is needed. Further reads
+    will simply try again
+  * with ``ioctl``-based power management, the user needs to switch
+    the sensor to standby mode and then back to running mode
+  * with power management based on opening the device file,
+    all users need to close the file handle
+
+If configured for multimaster mode, no error recovery is needed.

drivers/sensors/CMakeLists.txt

@@ -344,6 +344,10 @@ if(CONFIG_SENSORS)
       list(APPEND SRCS tmp112.c)
     endif()
 
+    if(CONFIG_SENSORS_TC74AX)
+      list(APPEND SRCS tc74ax.c)
+    endif()
+
   endif() # CONFIG_I2C
 
   # These drivers depend on SPI support

drivers/sensors/Kconfig

@@ -2151,4 +2151,106 @@ config TMP112_I2C_FREQUENCY
 
 endif #SENSORS_TMP112
 
+config SENSORS_TC74AX
+	bool "Microchip TC74Ax Digital Thermal Sensor"
+	default n
+	select I2C
+	---help---
+		Enable driver support for Microchip TC74Ax Digital Thermal Sensor.
+
+		Say Y if your board uses these sensors
+
+if SENSORS_TC74AX
+
+config SENSORS_TC74AX_I2C_FREQ
+	int "TC74Ax I2C frequency"
+	default 25000
+	range 10000 100000
+	---help---
+		I2C clock frequency used when communicating with this sensor.
+		According to the datasheet, the range from minimal to maximal
+		frequency is 10-100kHz.
+
+choice
+	prompt "TC74Ax Power Management"
+	default SENSORS_TC74AX_CLOSE_STANDBY
+	---help---
+		Select how the driver should manage power state of the sensor
+
+config SENSORS_TC74AX_CLOSE_STANDBY
+	bool "Keep the device in standby mode until opened"
+		---help---
+		Select this option to make the driver automatically keep
+		the sensor in standby mode from startup, until corresponding
+		character device is opened.
+
+		When that happens, the driver wakes the sensor from standby
+		mode to running mode. As soon as the character device is closed
+		again, the driver will put the sensor back to standby mode.
+
+config SENSORS_TC74AX_POWER_IOCTL
+	bool "Provide ioctl() interface for power management"
+		---help---
+		The driver will provide ioctl() call usable to manage power state
+		of the sensor.
+
+config SENSORS_TC74AX_POWER_NONE
+	bool "No power management"
+		---help---
+		The driver will provide no options to manage power state
+		of the sensor. It will be kept in its initial state.
+
+endchoice
+
+if SENSORS_TC74AX_POWER_IOCTL
+
+config SENSORS_TC74AX_RESET_STANDBY
+	bool "Put the device to standby mode during startup"
+	default n
+	---help---
+		The sensor should be in running state when it resets. Nevertheless,
+		the driver attempts to wake it up from standby during initialization.
+		Select this option to put the sensor into standby mode instead.
+
+		This configuration option is only available when the power management
+		is done manually using ioctl() calls. (It is implied if the device
+		is always in standby mode until opened and would make the device
+		unusable when no power management is provided.)
+
+endif # SENSORS_TC74AX_POWER_IOCTL
+
+config SENSORS_TC74AX_MULTIMASTER
+	bool "Enable multimaster mode"
+	default n
+	---help---
+		If this option is NOT selected, the driver assumes this MCU
+		is the only master on every I2C bus (or, at least, on every
+		I2C bus with a TC74Ax device connected to it.)
+
+		This assumption allows the driver to track internal state
+		of the sensor and, for example, only send read I2C messages
+		when it knows that the correct register in the sensor
+		is addressed.
+
+		If the MCU is not the only master on the I2C bus(es) this
+		TC74Ax device is connected to but you know that the other
+		master(s) will not ever use it, you can still keep this unset.
+
+		Otherwise - when other master(s) use this device on at least
+		one I2C bus, you should say Y here. The driver will not track
+		the internal state of the device because it can be changed
+		at any point by the other master(s).
+
+		The driver will determine device state on every read.
+		If the device reports it is in standby mode, the driver
+		will wake it up and attempt a re-read. (Unless power management
+		is set to none, in which case the read returns EIO.)
+
+		Incidentally, this mode reduces program memory size since
+		the code that tracks device state is not built. You can therefore
+		also use it as a tradeoff between code size and I2C bus usage time.
+		(Smaller code but every read needs four I2C messages instead of one.)
+
+endif # SENSORS_TC74AX
+
 endif # SENSORS

drivers/sensors/Make.defs

@@ -320,6 +320,10 @@ ifeq ($(CONFIG_SENSORS_T67XX),y)
   CSRCS += t67xx.c
 endif
 
+ifeq ($(CONFIG_SENSORS_TC74AX),y)
+  CSRCS += tc74ax.c
+endif
+
 ifeq ($(CONFIG_SENSORS_LTR308),y)
   CSRCS += ltr308_uorb.c
 endif