Internal Only discussion : Re: [PATCHv4 7/9] Thermal: Add Documentationto new APIs

[Srinivas Pandruvada]

On 10/01/2013 11:38 AM, Durgadoss R wrote:
> This patch adds Documentation for the new APIs
> introduced in this patch set. The documentation
> also has a model sysfs structure for reference.
>
> Signed-off-by: Durgadoss R <durgadoss.r@xxxxxxxxx>
> ---
>   Documentation/thermal/sysfs-api2.txt |  248 ++++++++++++++++++++++++++++++++++
>   1 file changed, 248 insertions(+)
>   create mode 100644 Documentation/thermal/sysfs-api2.txt
>
> diff --git a/Documentation/thermal/sysfs-api2.txt b/Documentation/thermal/sysfs-api2.txt
> new file mode 100644
> index 0000000..c456dad
> --- /dev/null
> +++ b/Documentation/thermal/sysfs-api2.txt
> @@ -0,0 +1,248 @@
> +Thermal Framework
> +-----------------
> +
> +Written by Durgadoss R <durgadoss.r@xxxxxxxxx>
> +Copyright (c) 2013 Intel Corporation
> +
> +Created on: 25 September 2013
> +
> +0. Introduction
> +---------------
> +The Linux thermal framework provides a set of interfaces for thermal
> +sensors and thermal cooling devices (fan, processor...) to register
> +with the thermal management solution and to be a part of it.
> +
> +This document focuses on how to enable new thermal sensors and cooling
> +devices to participate in thermal management. This solution is intended
> +to be 'light-weight' and platform/architecture independent. Any thermal
> +sensor/cooling device should be able to use the infrastructure easily.
> +
> +The goal of thermal framework is to expose the thermal sensor/zone and
> +cooling device attributes in a consistent way. This will help the
> +thermal governors to make use of the information to manage platform
> +thermals efficiently.
> +
> +The thermal sensor source file can be generic (can be any sensor driver,
> +in any subsystem). This driver will use the sensor APIs and register with
> +thermal framework to participate in platform Thermal management. This
> +does not (and should not) know about which zone it belongs to, or any
> +other information about platform thermals. A sensor driver is a standalone
> +piece of code, which can optionally register with thermal framework.
> +
> +However, for any platform, there should be a platformX_thermal.c file,
> +which will know about the platform thermal characteristics (e.g how many
> +sensors, zones, cooling devices, etc.. And how they are related to each other
> +i.e the mapping information). Only in this file, the zone level APIs should
> +be used, in which case the file will have all information required to attach
> +various sensors to a particular zone.
> +
> +This way, we can have one platform level thermal file, which can support
> +multiple platforms (may be)using the same set of sensors (but)binded in
> +a different way. This file can get the platform thermal information
> +through Firmware, ACPI tables, device tree etc.
> +
> +Unfortunately, today we don't have many drivers that can be clearly
> +differentiated as 'sensor_file.c' and 'platform_thermal_file.c'.
> +But very soon we will need/have. We see a lot of chip drivers,
> +starting to use thermal framework; we should keep it really
> +light-weight for them to do so but at the same time provide all
> +the necessary features to participate in platform thermal management.
> +
> +An Example: drivers/hwmon/emc1403.c - a generic thermal chip driver
> +In one platform this sensor can belong to 'ZoneA' and in another the
> +same can belong to 'ZoneB'. But, emc1403.c does not really care about
> +where does it belong. It just reports temperature.
> +
> +1. Terminology
> +--------------
> +This section describes the terminology used in the rest of this
> +document as well as the thermal framework code.
> +
> +thermal_sensor: Hardware that can report temperature of a particular
> +		spot in the platform, where it is placed. The temperature
> +		reported by the sensor is the 'real' temperature reported
> +		by the hardware.
> +thermal_zone:	A virtual area on the device, that gets heated up. It may
> +		have one or more thermal sensors attached to it.
> +cooling_device:	Any component that can help in reducing the temperature of
> +		a 'hot spot' either by reducing its performance (passive
> +		cooling) or by other means(Active cooling E.g. Fan)
> +
> +trip_points:	Various temperature levels for each sensor. As of now, we
> +		have four levels namely active, passive, hot and critical.
> +		Hot and critical trip point support only one value whereas
> +		active and passive can have any number of values. These
> +		temperature values can come from platform data, and are
> +		exposed through sysfs in a consistent manner. Stand-alone
> +		thermal sensor drivers are not expected to know these values.
> +		These values are RO.
> +thresholds:	These are programmable temperature limits, on reaching which
> +		the thermal sensor generates an interrupt. The framework is
> +		notified about this interrupt to take appropriate action.
> +		There can be as many number of thresholds as that of the
> +		hardware supports. These values are RW.
> +
> +thermal_map:	This provides the mapping (aka binding) information between
> +		various sensors and cooling devices in a particular zone.
> +		Typically, this also comes from platform data; Stand-alone
> +		sensor drivers or cooling device drivers are not expected
> +		to know these mapping information.
> +
> +2. Thermal framework APIs
> +-------------------------
> +2.1: For Thermal Sensors
> +2.1.1 thermal_sensor_register:
> +	This function creates a new sensor directory under /sys/class/thermal/
> +	as sensor[0-*]. This API is expected to be called by thermal sensor
> +	drivers. These drivers may or may not be in thermal subsystem. This
> +	function returns a thermal_sensor structure on success and appropriate
> +	error on failure.
> +
> +	name: Name of the sensor
> +	count: Number of programmable thresholds associated with this sensor
> +	devdata: Device private data
> +	ops: Thermal sensor callbacks
> +		.get_temp: obtain the current temperature of the sensor
> +		.get_trend: obtain the trend of the sensor
> +		.get_threshold: get a particular threshold temperature
> +		.set_threshold: set a particular threshold temperature
> +		.get_hyst: get hysteresis value associated with a threshold
> +		.set_hyst: set hysteresis value associated with a threshold
> +
> +2.1.2 thermal_sensor_unregister:
> +	This function deletes the sensor directory under /sys/class/thermal/
> +	for the given sensor. Thermal sensor drivers may call this API
> +	during the driver's 'exit' routine.
> +
> +	ts: Thermal sensor that has to be unregistered
> +
> +2.1.3 enable_sensor_thresholds:
> +	This function creates 'threshold[0-*]' attributes under a particular
> +	sensorX directory. These values are RW. This function is called by
> +	the sensr driver only if the sensor supports interrupt mechanism.
> +
> +	ts: Thermal sensor for which thresholds have to be enabled
> +	num_thresholds: Number of thresholds supported by the sensor
> +
> +2.2: For Cooling Devices
> +2.2.1 thermal_cooling_device_register:
> +	This function adds a new thermal cooling device (fan/processor/...)
> +	to /sys/class/thermal/ folder as cooling_device[0-*]. This function
> +	is expected to be called by cooling device drivers that may be
> +	present in other subsystems also.
> +
> +	name: the cooling device name
> +	devdata: device private data
> +	ops: thermal cooling devices callbacks
> +	.get_max_state: get the Maximum throttle state of the cooling device
> +	.get_cur_state: get the Current throttle state of the cooling device
> +	.set_cur_state: set the Current throttle state of the cooling device
> +
> +2.2.2 thermal_cooling_device_unregister:
> +	This function deletes the given cdev entry form /sys/class/thermal;
> +	and also cleans all the symlinks referred from various zones.
> +
> +	cdev: Cooling device to be unregistered
> +
> +2.3: For Thermal Zones
> +2.3.1 create_thermal_zone:
> +	This function adds a new 'zone' under /sys/class/thermal/
> +	directory as zone[0-*]. This zone has at least one thermal
> +	sensor and at most MAX_SENSORS_PER_ZONE number of sensors
> +	attached to it. Similarly, this zone has at least one cdev
> +	and at most MAX_CDEVS_PER_ZONE number of cdevs attached to it.
> +	As of now, MAX_*_PER_ZONE values are hard-coded to 5. We can
> +	make them configurable, through Kconfig option(during 'menuconfig').
> +
> +	name: Name of the thermal zone
> +	devdata: Device private data
> +
> +2.3.2 add_sensor_to_zone
> +	This function adds a 'sensorX' entry under /sys/class/thermal/
> +	zoneY/ directory. This 'sensorX' is a symlink to the actual
> +	sensor entry under /sys/class/thermal/. Correspondingly, the
> +	method remove_sensor_from_zone deletes the symlink.
> +
> +	tz: thermal zone structure
> +	ts: thermal sensor structure
> +
> +2.3.3 add_cdev_to_zone
> +	This function adds a 'cdevX' entry under /sys/class/thermal/
> +	zoneY/ directory. This 'cdevX' is a symlink to the actual
> +	cdev entry under /sys/class/thermal/. Correspondingly, the
> +	method remove_cdev_from_zone deletes the symlink.
> +
> +	tz: thermal zone structure
> +	cdev: thermal cooling device structure
> +
> +2.4 For Thermal Trip
> +2.4.1 add_sensor_trip_info
> +	This function adds trip point information for the given sensor,
> +	(under a given zone) under /sys/class/thermal/zoneX/.
> +	This API creates sysfs attributes namely:
> +	sensorX_trip_activeY, sensorX_trip_passiveY, sensorX_trip_hot,
> +	sensorX_trip_critical. Each of these hold one trip point temperature
> +	(in mC) values, as provided from platform data. As of now, we
> +	support many Active and Passive trip points but only one hot
> +	one critical trip point.
> +
> +	tz: thermal zone structure
> +	ts: thermal sensor to which the trip points are attached
> +	trip: trip point structure. Usually obtained from platform data
> +
> +2.5 For Thermal Map
> +2.5.1 add_map_entry
> +	This function adds a 'map[0-*]' sysfs attribute under
> +	/sys/class/thermal/zoneX/mapY_*. Each map attribute helps
> +	to describe the binding relationship between a sensor and
> +	a cdev in the given zone. The map structure is typically
> +	obtained as platform data. For example, through ACPI tables,
> +	SFI tables, Device tree etc. The trip mask is a hex value;
> +	if 'n' th bit (from LSB) is set, then for trip point 'n' this
> +	cdev is throttled with the given weight[n].
> +
> +	tz: thermal zone to which a 'map' is being added
> +	map: thermal_map structure
> +
> +3. Sysfs attributes structure
> +-----------------------------
> +Thermal sysfs attributes will be represented under /sys/class/thermal.
> +
> +3.1: For Thermal Sensors
> +	/sys/class/thermal/sensor[0-*]:
> +		|---type:		Name of the thermal sensor
> +		|---temp_input:		Current temperature in mC
> +		|---threshold[0-*]:	Threshold temperature in mC
> +		|---threshold[0-*]_hyst:Optional hysteresis value in mC
> +
> +3.2: For Thermal Cooling Devices
> +	/sys/class/thermal/cooling_device[0-*]:
> +		|---type:		Type of the cooling device
> +		|---max_state:		Maximum throttle state of the cdev
> +		|---cur_state:		Current throttle state of the cdev
> +
-I wish if you can have parent child relationship in this table. For 
example cpu package id to a core id relationship (If you set the state 
for parent device all children get affected. Currently we can't tie a 
cpu cooling device to a physical processor. I am sure there will be 
other cases. ).
-Also min_state and step_size is useful. I can configure this thermal 
daemon, and someone in the community using these to control level 
thermals in a macbook with 10+ sensors.
-I call auto down control in thermal daemon. This helps whether we can 
force a device from highest state to min state in one step or you need 
to gradually bring down. This helps when you use a trigger based user 
space control without polling. Once temperature drops below a limit in 
ACPI, you don't get any events. So if you don't poll these devices still 
under controlled state because of there are no events. For such systems 
once you reach a threshold you can drop state to min state.
> +3.3: For Thermal Zones
> +	/sys/class/thermal/zone[0-*]:
> +		|---name:			Name of the thermal
> +		|---sensorX:			Symlink to ../sensorX
> +		|---cdevY:			Symlink to ../cdevY
> +		|---sensorX_trip_activeM:	Active trip point for sensorX
> +		|---sensorX_trip_passiveN:	Passive trip point for sensorX
> +		|---sensorX_trip_hot:		Hot trip point for sensorX
> +		|---sensorX_trip_critical:	Critical trip point for sensorX
> +		|---mapX_sensor_name:		Sensor Name
> +		|---mapX_cdev_name:		Cooling device Name
> +		|---mapX_trip_type:		Trip point type
> +		|---mapX_trip_mask:		Trip point mask
> +		|---mapX_weightY:		Weights (used by governors)
> +
> +3.5: For Thermal Map
> +	Each attribute represents the mapping/binding information between
> +	a sensor and a cdev, together with a trip type.
> +	/sys/class/thermal/zoneX/:
> +		|---mapY_trip_type:		active/passive
> +		|---mapY_sensor_name:		cpu
> +		|---mapY_cdev_name:		proc
> +		|---mapY_trip_mask:		0x03
> +		|---mapY_weight0:		50
> +		|---mapY_weight1:		30
Thanks,
Srinivas
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/