1.. SPDX-License-Identifier: GPL-2.0-only
2
3Kernel driver bt1-pvt
4=====================
5
6Supported chips:
7
8  * Baikal-T1 PVT sensor (in SoC)
9
10    Prefix: 'bt1-pvt'
11
12    Addresses scanned: -
13
14    Datasheet: Provided by BAIKAL ELECTRONICS upon request and under NDA
15
16Authors:
17    Maxim Kaurkin <maxim.kaurkin@baikalelectronics.ru>
18    Serge Semin <Sergey.Semin@baikalelectronics.ru>
19
20Description
21-----------
22
23This driver implements support for the hardware monitoring capabilities of the
24embedded into Baikal-T1 process, voltage and temperature sensors. PVT IP-core
25consists of one temperature and four voltage sensors, which can be used to
26monitor the chip internal environment like heating, supply voltage and
27transistors performance. The driver can optionally provide the hwmon alarms
28for each sensor the PVT controller supports. The alarms functionality is made
29compile-time configurable due to the hardware interface implementation
30peculiarity, which is connected with an ability to convert data from only one
31sensor at a time. Additional limitation is that the controller performs the
32thresholds checking synchronously with the data conversion procedure. Due to
33these in order to have the hwmon alarms automatically detected the driver code
34must switch from one sensor to another, read converted data and manually check
35the threshold status bits. Depending on the measurements timeout settings
36(update_interval sysfs node value) this design may cause additional burden on
37the system performance. So in case if alarms are unnecessary in your system
38design it's recommended to have them disabled to prevent the PVT IRQs being
39periodically raised to get the data cache/alarms status up to date. By default
40in alarm-less configuration the data conversion is performed by the driver
41on demand when read operation is requested via corresponding _input-file.
42
43Temperature Monitoring
44----------------------
45
46Temperature is measured with 10-bit resolution and reported in millidegree
47Celsius. The driver performs all the scaling by itself therefore reports true
48temperatures that don't need any user-space adjustments. While the data
49translation formulae isn't linear, which gives us non-linear discreteness,
50it's close to one, but giving a bit better accuracy for higher temperatures.
51The temperature input is mapped as follows (the last column indicates the input
52ranges)::
53
54	temp1: CPU embedded diode	-48.38C - +147.438C
55
56In case if the alarms kernel config is enabled in the driver the temperature input
57has associated min and max limits which trigger an alarm when crossed.
58
59Voltage Monitoring
60------------------
61
62The voltage inputs are also sampled with 10-bit resolution and reported in
63millivolts. But in this case the data translation formulae is linear, which
64provides a constant measurements discreteness. The data scaling is also
65performed by the driver, so returning true millivolts. The voltage inputs are
66mapped as follows (the last column indicates the input ranges)::
67
68	in0: VDD		(processor core)		0.62V - 1.168V
69	in1: Low-Vt		(low voltage threshold)		0.62V - 1.168V
70	in2: High-Vt		(high voltage threshold)	0.62V - 1.168V
71	in3: Standard-Vt	(standard voltage threshold)	0.62V - 1.168V
72
73In case if the alarms config is enabled in the driver the voltage inputs
74have associated min and max limits which trigger an alarm when crossed.
75
76Sysfs Attributes
77----------------
78
79Following is a list of all sysfs attributes that the driver provides, their
80permissions and a short description:
81
82=============================== ======= =======================================
83Name				Perm	Description
84=============================== ======= =======================================
85update_interval			RW	Measurements update interval per
86					sensor.
87temp1_type			RO	Sensor type (always 1 as CPU embedded
88					diode).
89temp1_label			RO	CPU Core Temperature sensor.
90temp1_input			RO	Measured temperature in millidegree
91					Celsius.
92temp1_min			RW	Low limit for temp input.
93temp1_max			RW	High limit for temp input.
94temp1_min_alarm			RO	Temperature input alarm. Returns 1 if
95					temperature input went below min limit,
96					0 otherwise.
97temp1_max_alarm			RO	Temperature input alarm. Returns 1 if
98					temperature input went above max limit,
99					0 otherwise.
100temp1_offset			RW	Temperature offset in millidegree
101					Celsius which is added to the
102					temperature reading by the chip. It can
103					be used to manually adjust the
104					temperature measurements within 7.130
105					degrees Celsius.
106in[0-3]_label			RO	CPU Voltage sensor (either core or
107					low/high/standard thresholds).
108in[0-3]_input			RO	Measured voltage in millivolts.
109in[0-3]_min			RW	Low limit for voltage input.
110in[0-3]_max			RW	High limit for voltage input.
111in[0-3]_min_alarm		RO	Voltage input alarm. Returns 1 if
112					voltage input went below min limit,
113					0 otherwise.
114in[0-3]_max_alarm		RO	Voltage input alarm. Returns 1 if
115					voltage input went above max limit,
116					0 otherwise.
117=============================== ======= =======================================
118