CPU cooling APIs How To
===================================

Written by Amit Daniel Kachhap <amit.kachhap@linaro.org>

Updated: 9 March 2012

Copyright (c)  2011 Samsung Electronics Co., Ltd(http://www.samsung.com)

0. Introduction

The generic cpu cooling(freq clipping, cpuhotplug) provides
registration/unregistration APIs to the caller. The binding of the cooling
devices to the trip point is left for the user. The registration APIs returns
the cooling device pointer.

1. cpu cooling APIs

1.1 cpufreq registration/unregistration APIs
1.1.1 struct thermal_cooling_device *cpufreq_cooling_register(
	struct freq_clip_table *tab_ptr, unsigned int tab_size,
	const struct cpumask *mask_val, enum thermal_trip_type type)

    This interface function registers the cpufreq cooling device with the name
    "thermal-cpufreq-%x". This api can support multiple instances of cpufreq
    cooling devices.

    tab_ptr: The table containing the maximum value of frequency to be clipped
    for each cooling state.
	.freq_clip_max: Value of frequency to be clipped for each allowed
	 cpus.
    tab_size: the total number of cpufreq cooling states.
    mask_val: all the allowed cpu's where frequency clipping can happen.
    type: This can have values like (THERMAL_TRIP_PASSIVE, THERMAL_TRIP_ACTIVE,
	   and THERMAL_TRIP_STATE_INSTANCE)

1.1.2 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)

    This interface function unregisters the "thermal-cpufreq-%x" cooling device.

    cdev: Cooling device pointer which has to be unregistered.

1.2 cpuhotplug registration APIs
1.2.1 struct thermal_cooling_device *cpuhotplug_cooling_register(
	const struct cpumask *mask_val)

    This interface function registers the cpuhotplug cooling device with the name
    "cpu-hotplug-%x". This api can support multiple instances of cpuhotplug
    cooling devices.

    mask_val: all the allowed cpu's which can be hotplugged out.

1.1.2 void cpuhotplug_cooling_unregister(struct thermal_cooling_device *cdev)

    This interface function unregisters the "thermal-cpuhotplug-%x" cooling
    device.

    cdev: Cooling device pointer which has to be unregistered.

2. CPU cooling action notifier interface

2.1 int cputherm_register_notifier(struct notifier_block *nb,
	unsigned int list)

    This interface registers a driver with cpu cooling layer. The driver will
    be notified when any cpu cooling action is called.

    nb: notifier function to register
    list: CPUFREQ_COOLING_TYPE or CPUHOTPLUG_COOLING_TYPE

2.2 int cputherm_unregister_notifier(struct notifier_block *nb,
	unsigned int list)

    This interface registers a driver with cpu cooling layer. The driver will
    be notified when any cpu cooling action is called.

    nb: notifier function to register
    list: CPUFREQ_COOLING_TYPE or CPUHOTPLUG_COOLING_TYPE
