openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
linux/Documentation/ABI/testing/sysfs-driver-w1_therm

117 lines
4.4 KiB
Plaintext
Raw Normal View History

w1_therm: adding alarm sysfs entry Adding device alarms settings by a dedicated sysfs entry alarms (RW): read or write TH and TL in the device RAM. Checking devices in alarm state could be performed using the master search command. As alarms temperature level are store in a 8 bit register on the device and are signed values, a safe cast shall be performed using the min and max temperature that device are able to measure. This is done by int_to_short inline function. A 'write_data' field is added in the device structure, to bind the correct writing function, as some devices may have 2 or 3 bytes RAM. Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203801.411253-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:38:01 +08:00
What: /sys/bus/w1/devices/.../alarms
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(RW) read or write TH and TL (Temperature High an Low) alarms.
Values shall be space separated and in the device range
(typical -55 degC to 125 degC), if not values will be trimmed
to device min/max capabilities. Values are integer as they are
stored in a 8bit register in the device. Lowest value is
automatically put to TL. Once set, alarms could be search at
docs: ABI: fix a typo when pointing to w1-generic.rst There's a typo there: w1_generic.rst -> w1-generic.rst Causing the document reference to point to the wrong place. Fixes: e2c94d6f5720 ("w1_therm: adding alarm sysfs entry") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/66b47dd879e8ae38b6db6d2f38780e00a29fc086.1592895969.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-23 15:09:09 +08:00
master level, refer to Documentation/w1/w1-generic.rst for
w1_therm: adding alarm sysfs entry Adding device alarms settings by a dedicated sysfs entry alarms (RW): read or write TH and TL in the device RAM. Checking devices in alarm state could be performed using the master search command. As alarms temperature level are store in a 8 bit register on the device and are signed values, a safe cast shall be performed using the min and max temperature that device are able to measure. This is done by int_to_short inline function. A 'write_data' field is added in the device structure, to bind the correct writing function, as some devices may have 2 or 3 bytes RAM. Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203801.411253-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:38:01 +08:00
detailed information
Users: any user space application which wants to communicate with
w1_term device
w1_therm: adding eeprom sysfs entry The driver implement 2 hardware functions to access device RAM: * copy_scratchpad * recall_scratchpad They act according to device specifications. As EEPROM operations are not device dependent (all w1_therm can perform EEPROM read/write operation following the same protocol), it is removed from device families structures. Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203725.410844-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:37:25 +08:00
What: /sys/bus/w1/devices/.../eeprom
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(WO) writing that file will either trigger a save of the
device data to its embedded EEPROM, either restore data
embedded in device EEPROM. Be aware that devices support
limited EEPROM writing cycles (typical 50k)
* 'save': save device RAM to EEPROM
* 'restore': restore EEPROM data in device RAM
Users: any user space application which wants to communicate with
w1_term device
w1_therm: adding ext_power sysfs entry Adding ext_power sysfs entry (RO). Return the power status of the device: - 0: device parasite powered - 1: device externally powered - xx: xx is kernel error The power status of each device is check when the device is discover by the bus master, in 'w1_therm_add_slave(struct w1_slave *)'. The status is stored in the device structure w1_therm_family_data so that the driver always knows the power state of each device, which could be used later to determine the required strong pull up to apply on the line. The power status is re evaluate each time the sysfs ext_power read by a user. The hardware function 'read_powermode(struct w1_slave *sl)' act just as per device specifications, sending W1_READ_PSUPPLY command on the bus, and issue a read time slot, reading only one bit. A helper function 'bool bus_mutex_lock(struct mutex *lock)' is introduced. It try to aquire the bus mutex several times (W1_THERM_MAX_TRY), waiting W1_THERM_RETRY_DELAY between two attempt. Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203650.410439-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:36:50 +08:00
What: /sys/bus/w1/devices/.../ext_power
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(RO) return the power status by asking the device
* '0': device parasite powered
* '1': device externally powered
* '-xx': xx is kernel error when reading power status
Users: any user space application which wants to communicate with
w1_term device
w1_therm: adding resolution sysfs entry Adding resolution sysfs entry (RW) to get or set the device resolution Write values are managed as follow: * '9..12': resolution to set in bit * Anything else: do nothing Read values are : * '9..12': device resolution in bit * '-xx': xx is kernel error when reading the resolution Only supported devices will show the sysfs entry. A new family has been created for DS18S20 devices as they do not implement resolution feature. The resolution of each device is check when the device is discover by the bus master, in 'w1_therm_add_slave(struct w1_slave *)'. The status is stored in the device structure w1_therm_family_data so that the driver always knows the resolution of each device, which could be used later to determine the required conversion duration (resolution dependent). The resolution is re evaluate each time a user read or write the sysfs entry. To avoid looping through the w1_therm_families at run time, the pointer 'specific_functions' is set up to the correct 'w1_therm_family_converter' when the slave is added (which mean when it is discovered by the master). This initialization is done by a helper function 'device_family(struct w1_slave *sl)', and a dedicated macro 'SLAVE_SPECIFIC_FUNC(sl)' allow the access to the specific function of the slave device. 'read_scratchpad' and 'write_scratchpad' are the hardware functions to access the device RAM, as per protocol specification. It cancel the former 'precision' functions, which was only set and never read (so not stored in the device struct). Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203708.410649-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:37:08 +08:00
What: /sys/bus/w1/devices/.../resolution
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(RW) get or set the device resolution (on supported devices,
if not, this entry is not present). Note that the resolution
will be changed only in device RAM, so it will be cleared when
power is lost. Trigger a 'save' to EEPROM command to keep
values after power-on. Read or write are :
* '9..12': device resolution in bit
or resolution to set in bit
* '-xx': xx is kernel error when reading the resolution
* Anything else: do nothing
Users: any user space application which wants to communicate with
w1_term device
w1_therm: optimizing temperature read timings Optimizing temperature reading by reducing waiting conversion time according to device resolution settings, as per device specification. This is device dependent as not all the devices supports resolution setting, so it has been added in device family structures. The process to read the temperature on the device has been adapted in a new function 'convert_t()', which replace the former 'read_therm()', is introduce to deal with this timing. Strong pull up is also applied during the required time, according to device power status needs and 'strong_pullup' module parameter. 'temperature_from_RAM()' function is introduced to get the correct temperature computation (device dependent) from device RAM data. An new sysfs entry has been added to ouptut only temperature. The old entry w1_slave has been kept for compatibility, without changing its output format. Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203742.411039-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:37:42 +08:00
What: /sys/bus/w1/devices/.../temperature
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(RO) return the temperature in 1/1000 degC.
w1_therm: adding bulk read support to trigger multiple conversion on bus Adding bulk read support: Sending a 'trigger' command in the dedicated sysfs entry of bus master device send a conversion command for all the slaves on the bus. The sysfs entry is added as soon as at least one device supporting this feature is detected on the bus. The behavior of the sysfs reading temperature on the device is as follow: * If no bulk read pending, trigger a conversion on the device, wait for the conversion to be done, read the temperature in device RAM * If a bulk read has been trigger, access directly the device RAM This behavior is the same on the 2 sysfs entries ('temperature' and 'w1_slave'). Reading the therm_bulk_read sysfs give the status of bulk operations: * '-1': conversion in progress on at least 1 sensor * '1': conversion complete but at least one sensor has not been read yet * '0': no bulk operation. Reading temperature on ecah device will trigger a conversion As not all devices support bulk read feature, it has been added in device family structure. The attribute is set at master level as soon as a supporting device is discover. It is removed when the last supported device leave the bus. The count of supported device is kept with the static counter bulk_read_device_counter. A strong pull up is apply on the line if at least one device required it. The duration of the pull up is the max time required by a device on the line, which depends on the resolution settings of each device. The strong pull up could be adjust with the a module parameter. Updating documentation in Documentation/ABI/testing/sysfs-driver-w1_therm and Documentation/w1/slaves/w1_therm.rst accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203820.411483-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:38:20 +08:00
* If a bulk read has been triggered, it will directly
return the temperature computed when the bulk read
occurred, if available. If not yet available, nothing
is returned (a debug kernel message is sent), you
should retry later on.
* If no bulk read has been triggered, it will trigger
a conversion and send the result. Note that the
conversion duration depend on the resolution (if
device support this feature). It takes 94ms in 9bits
resolution, 750ms for 12bits.
w1_therm: optimizing temperature read timings Optimizing temperature reading by reducing waiting conversion time according to device resolution settings, as per device specification. This is device dependent as not all the devices supports resolution setting, so it has been added in device family structures. The process to read the temperature on the device has been adapted in a new function 'convert_t()', which replace the former 'read_therm()', is introduce to deal with this timing. Strong pull up is also applied during the required time, according to device power status needs and 'strong_pullup' module parameter. 'temperature_from_RAM()' function is introduced to get the correct temperature computation (device dependent) from device RAM data. An new sysfs entry has been added to ouptut only temperature. The old entry w1_slave has been kept for compatibility, without changing its output format. Updating Documentation/ABI/testing/sysfs-driver-w1_therm accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203742.411039-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:37:42 +08:00
Users: any user space application which wants to communicate with
w1_term device
w1_therm: adding sysfs-driver-w1_therm doc Adding a sysfs-driver-w1_therm documentation file in Documentation/ABI/testing. It describe the onlys sysfs entry of w1_therm module, based on Documentation/w1/slaves/w1_therm.rst Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203631.410227-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:36:31 +08:00
What: /sys/bus/w1/devices/.../w1_slave
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(RW) return the temperature in 1/1000 degC.
*read*: return 2 lines with the hexa output data sent on the
bus, return the CRC check and temperature in 1/1000 degC
*write* :
* '0' : save the 2 or 3 bytes to the device EEPROM
(i.e. TH, TL and config register)
* '9..12' : set the device resolution in RAM
(if supported)
* Anything else: do nothing
refer to Documentation/w1/slaves/w1_therm.rst for detailed
information.
Users: any user space application which wants to communicate with
w1_therm: adding bulk read support to trigger multiple conversion on bus Adding bulk read support: Sending a 'trigger' command in the dedicated sysfs entry of bus master device send a conversion command for all the slaves on the bus. The sysfs entry is added as soon as at least one device supporting this feature is detected on the bus. The behavior of the sysfs reading temperature on the device is as follow: * If no bulk read pending, trigger a conversion on the device, wait for the conversion to be done, read the temperature in device RAM * If a bulk read has been trigger, access directly the device RAM This behavior is the same on the 2 sysfs entries ('temperature' and 'w1_slave'). Reading the therm_bulk_read sysfs give the status of bulk operations: * '-1': conversion in progress on at least 1 sensor * '1': conversion complete but at least one sensor has not been read yet * '0': no bulk operation. Reading temperature on ecah device will trigger a conversion As not all devices support bulk read feature, it has been added in device family structure. The attribute is set at master level as soon as a supporting device is discover. It is removed when the last supported device leave the bus. The count of supported device is kept with the static counter bulk_read_device_counter. A strong pull up is apply on the line if at least one device required it. The duration of the pull up is the max time required by a device on the line, which depends on the resolution settings of each device. The strong pull up could be adjust with the a module parameter. Updating documentation in Documentation/ABI/testing/sysfs-driver-w1_therm and Documentation/w1/slaves/w1_therm.rst accordingly. Signed-off-by: Akira Shimahara <akira215corp@gmail.com> Link: https://lore.kernel.org/r/20200511203820.411483-1-akira215corp@gmail.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-05-12 04:38:20 +08:00
w1_term device
What: /sys/bus/w1/devices/w1_bus_masterXX/therm_bulk_read
Date: May 2020
Contact: Akira Shimahara <akira215corp@gmail.com>
Description:
(RW) trigger a bulk read conversion. read the status
*read*:
* '-1': conversion in progress on at least 1 sensor
* '1' : conversion complete but at least one sensor
value has not been read yet
* '0' : no bulk operation. Reading temperature will
trigger a conversion on each device
*write*: 'trigger': trigger a bulk read on all supporting
devices on the bus
Note that if a bulk read is sent but one sensor is not read
immediately, the next access to temperature on this device
will return the temperature measured at the time of issue
of the bulk read command (not the current temperature).
Users: any user space application which wants to communicate with
w1_term device