thermal: document struct thermal_zone_device and thermal_governor

Document struct thermal_zone_device and struct thermal_governor fields
and their use by the thermal framework code.

Cc: Zhang Rui <rui.zhang@intel.com>
Cc: Eduardo Valentin <edubezval@gmail.com>
Signed-off-by: Javi Merino <javi.merino@arm.com>
Signed-off-by: Zhang Rui <rui.zhang@intel.com>

diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index f7e11c7ea7d9691b045e84a2274cf614307e4e97..0305cde21a74d0bd37cf8ce707d8033632182cd6 100644 (file)
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -158,6 +158,42 @@ struct thermal_attr {
        char name[THERMAL_NAME_LENGTH];
 };
 
+/**
+ * struct thermal_zone_device - structure for a thermal zone
+ * @id:                unique id number for each thermal zone
+ * @type:      the thermal zone device type
+ * @device:    &struct device for this thermal zone
+ * @trip_temp_attrs:   attributes for trip points for sysfs: trip temperature
+ * @trip_type_attrs:   attributes for trip points for sysfs: trip type
+ * @trip_hyst_attrs:   attributes for trip points for sysfs: trip hysteresis
+ * @devdata:   private pointer for device private data
+ * @trips:     number of trip points the thermal zone supports
+ * @passive_delay:     number of milliseconds to wait between polls when
+ *                     performing passive cooling.  Currenty only used by the
+ *                     step-wise governor
+ * @polling_delay:     number of milliseconds to wait between polls when
+ *                     checking whether trip points have been crossed (0 for
+ *                     interrupt driven systems)
+ * @temperature:       current temperature.  This is only for core code,
+ *                     drivers should use thermal_zone_get_temp() to get the
+ *                     current temperature
+ * @last_temperature:  previous temperature read
+ * @emul_temperature:  emulated temperature when using CONFIG_THERMAL_EMULATION
+ * @passive:           1 if you've crossed a passive trip point, 0 otherwise.
+ *                     Currenty only used by the step-wise governor.
+ * @forced_passive:    If > 0, temperature at which to switch on all ACPI
+ *                     processor cooling devices.  Currently only used by the
+ *                     step-wise governor.
+ * @ops:       operations this &thermal_zone_device supports
+ * @tzp:       thermal zone parameters
+ * @governor:  pointer to the governor for this thermal zone
+ * @thermal_instances: list of &struct thermal_instance of this thermal zone
+ * @idr:       &struct idr to generate unique id for this zone's cooling
+ *             devices
+ * @lock:      lock to protect thermal_instances list
+ * @node:      node in thermal_tz_list (in thermal_core.c)
+ * @poll_queue:        delayed work for polling
+ */
 struct thermal_zone_device {
        int id;
        char type[THERMAL_NAME_LENGTH];
@@ -179,12 +215,18 @@ struct thermal_zone_device {
        struct thermal_governor *governor;
        struct list_head thermal_instances;
        struct idr idr;
-       struct mutex lock; /* protect thermal_instances list */
+       struct mutex lock;
        struct list_head node;
        struct delayed_work poll_queue;
 };
 
-/* Structure that holds thermal governor information */
+/**
+ * struct thermal_governor - structure that holds thermal governor information
+ * @name:      name of the governor
+ * @throttle:  callback called for every trip point even if temperature is
+ *             below the trip point temperature
+ * @governor_list:     node in thermal_governor_list (in thermal_core.c)
+ */
 struct thermal_governor {
        char name[THERMAL_NAME_LENGTH];
        int (*throttle)(struct thermal_zone_device *tz, int trip);