[PM][PATCH 2/2] omap: opp: documentation update

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



move the documentation from header to c, cleanup missing function
documentation for the functions

Signed-off-by: Nishanth Menon <nm@xxxxxx>

Cc: Eduardo Valentin <eduardo.valentin@xxxxxxxxx>
Cc: Jouni Hogander <jouni.hogander@xxxxxxxxx>
Cc: Kevin Hilman <khilman@xxxxxxxxxxxxxxxxxxx>
Cc: Paul Walmsley <paul@xxxxxxxxx>
Cc: Rajendra Nayak <rnayak@xxxxxx>
Cc: Sanjeev Premi <premi@xxxxxx>
Cc: Tero Kristo <tero.kristo@xxxxxxxxx>
Cc: Tony Lindgren <tony@xxxxxxxxxxx>
Cc: Vishwanath BS <vishwanath.bs@xxxxxx>
---
 Documentation/arm/OMAP/omap_pm        |   66 +++++++++++++
 arch/arm/plat-omap/include/plat/opp.h |  143 +----------------------------
 arch/arm/plat-omap/opp.c              |  164 +++++++++++++++++++++++++++++---
 3 files changed, 216 insertions(+), 157 deletions(-)

diff --git a/Documentation/arm/OMAP/omap_pm b/Documentation/arm/OMAP/omap_pm
index 5389440..9376ad4 100644
--- a/Documentation/arm/OMAP/omap_pm
+++ b/Documentation/arm/OMAP/omap_pm
@@ -127,3 +127,69 @@ implementation needs:
 10. (*pdata->cpu_set_freq)(unsigned long f)
 
 11. (*pdata->cpu_get_freq)(void)
+
+OMAP OPP Layer
+==============
+OMAP SOCs have a standard set of tuples consisting of frequency and
+voltage pairs that the device will support per voltage domain. This
+is called Operating Points or OPP. The actual definitions of OMAP
+Operating Points varies over silicon within the same family of
+devices. For a specific domain, you can have a set of
+{frequency, voltage} pairs. As the kernel boots and more information
+is available, a set of these are activated based on the precise
+nature of device the kernel boots up on. It is interesting to
+remember that each IP which belongs to a voltage domain may define
+their own set of OPPs on top of this.
+
+OPP layer of its own depends on silicon specific implementation and
+board specific data to finalize on the final set of OPPs available
+in a system
+
+Initial list initialization:
+---------------------------
+Silicon specific initialization: First the OPP layer needs to be told
+that to initialize the tables for OMAP3, this is done board
+perspective by the call to:
+1. omap3_pm_init_opp_table - this in turn calls opp_init_list for all
+OPP types. This is the generic silicon operating points, however, the
+system may have additional features or customizations required. This
+flexibility is provided by the following apis:
+
+Query functions:
+----------------
+Search for OPPs for various cases:
+2. opp_find_freq_exact - exact search function
+3. opp_find_freq_floor - round_up search function
+4. opp_find_freq_ceil - round_down search function
+
+OPP modifier functions:
+----------------------
+The allows opp layer users to add customized OPPs or change the table
+for any need they may have
+5. opp_add - add a new OPP
+6. opp_enable - enable a disabled OPP
+7. opp_disable - disable an enabled OPP
+
+OPP Data retrieval functions:
+----------------------------
+The following sets of functions are useful for drivers to retrieved
+data stored in opp layer for various functions.
+8. opp_get_voltage - retrieve voltage for an opp
+9. opp_get_freq - get the frequency for an opp
+10. opp_get_opp_count - get number of opps enabled for a domain
+
+Cpufreq table generation:
+------------------------
+11. opp_init_cpufreq_table - this translates the OPP layer's internal
+OPP arrangement into a table understood and operated upon by the
+cpufreq layer.
+
+Deprecated functions:
+--------------------
+To maintain compatibility with out of tree drivers, opp_id is needed.
+OPP IDs are not constant acrross silicon, nor are they constant for a
+given silicon family. The rest of the layers should stop using these
+functions at the earliest. For the out of tree drivers currently,
+This is exposed by the following deprecated functions:
+12. opp_find_by_opp_id - get an OPP for an OPP ID
+13. opp_get_opp_id - get the OPP ID for an OPP
diff --git a/arch/arm/plat-omap/include/plat/opp.h b/arch/arm/plat-omap/include/plat/opp.h
index 7d16a46..9f569e3 100644
--- a/arch/arm/plat-omap/include/plat/opp.h
+++ b/arch/arm/plat-omap/include/plat/opp.h
@@ -28,7 +28,6 @@ enum opp_t {
 #error "You need to populate the OPP types for OMAP chip type."
 #endif
 
-
 /**
  * struct omap_opp_def - OMAP OPP Definition
  * @enabled:	True/false - is this OPP enabled/disabled by default
@@ -53,8 +52,8 @@ struct omap_opp_def {
 };
 
 /*
- * Initialization wrapper used to define an OPP
- * to point at the end of a terminator of a list of OPPs,
+ * Initialization wrapper used to define an OPP.
+ * To point at the end of a terminator of a list of OPPs,
  * use OMAP_OPP_DEF(0, 0, 0)
  */
 #define OMAP_OPP_DEF(_enabled, _freq, _uv)	\
@@ -68,165 +67,27 @@ struct omap_opp;
 
 #ifdef CONFIG_CPU_FREQ
 
-/**
- * opp_get_voltage() - Gets the voltage corresponding to an opp
- * @opp:	opp for which voltage has to be returned for
- *
- * Return voltage in micro volt corresponding to the opp, else
- * return 0
- */
 unsigned long opp_get_voltage(const struct omap_opp *opp);
 
-/**
- * opp_get_freq() - Gets the frequency corresponding to an opp
- * @opp:	opp for which frequency has to be returned for
- *
- * Return frequency in hertz corresponding to the opp, else
- * return 0
- */
 unsigned long opp_get_freq(const struct omap_opp *opp);
 
-/**
- * opp_get_opp_count() - Get number of opps enabled in the opp list
- * @num:	returns the number of opps
- * @opp_type:	OPP type we want to count
- *
- * This functions returns the number of opps if there are any OPPs enabled,
- * else returns corresponding error value.
- */
 int opp_get_opp_count(enum opp_t opp_type);
 
-/**
- * opp_find_freq_exact() - search for an exact frequency
- * @opp_type:	OPP type we want to search in.
- * @freq:	frequency to search for
- * @enabled:	enabled/disabled OPP to search for
- *
- * searches for the match in the opp list and returns handle to the matching
- * opp if found, else returns ERR_PTR in case of error and should be handled
- * using IS_ERR.
- *
- * Note enabled is a modifier for the search. if enabled=true, then the match is
- * for exact matching frequency and is enabled. if true, the match is for exact
- * frequency which is disabled.
- */
 struct omap_opp *opp_find_freq_exact(enum opp_t opp_type,
 				     unsigned long freq, bool enabled);
 
-/* XXX This documentation needs fixing */
-
-/**
- * opp_find_freq_floor() - Search for an rounded freq
- * @opp_type:	OPP type we want to search in
- * @freq:	Start frequency
- *
- * Search for the lower *enabled* OPP from a starting freq
- * from a start opp list.
- *
- * Returns *opp and *freq is populated with the next match, else
- * returns NULL opp if found, else returns ERR_PTR in case of error.
- *
- * Example usages:
- *	* find match/next lowest available frequency
- *	freq = 350000;
- *	opp = opp_find_freq_floor(oppl, &freq)))
- *	if (IS_ERR(opp))
- *		pr_err ("unable to find a lower frequency\n");
- *	else
- *		pr_info("match freq = %ld\n", freq);
- *
- *	* print all supported frequencies in descending order *
- *	opp = oppl;
- *	freq = ULONG_MAX;
- *	while (!IS_ERR(opp = opp_find_freq_floor(opp, &freq)) {
- *		pr_info("freq = %ld\n", freq);
- *		freq--; * for next lower match *
- *	}
- *
- * NOTE: if we set freq as ULONG_MAX and search low, we get the
- * highest enabled frequency
- */
 struct omap_opp *opp_find_freq_floor(enum opp_t opp_type, unsigned long *freq);
 
-/* XXX This documentation needs fixing */
-
-/**
- * opp_find_freq_ceil() - Search for an rounded freq
- * @opp_type:	OPP type where we want to search in
- * @freq:	Start frequency
- *
- * Search for the higher *enabled* OPP from a starting freq
- * from a start opp list.
- *
- * Returns *opp and *freq is populated with the next match, else
- * returns NULL opp if found, else returns ERR_PTR in case of error.
- *
- * Example usages:
- *	* find match/next highest available frequency
- *	freq = 350000;
- *	opp = opp_find_freq_ceil(oppl, &freq))
- *	if (IS_ERR(opp))
- *		pr_err ("unable to find a higher frequency\n");
- *	else
- *		pr_info("match freq = %ld\n", freq);
- *
- *	* print all supported frequencies in ascending order *
- *	opp = oppl;
- *	freq = 0;
- *	while (!IS_ERR(opp = opp_find_freq_ceil(opp, &freq)) {
- *		pr_info("freq = %ld\n", freq);
- *		freq++; * for next higher match *
- *	}
- */
 struct omap_opp *opp_find_freq_ceil(enum opp_t opp_type, unsigned long *freq);
 
 
-/**
- * opp_init_list() - Initialize an opp list from the opp definitions
- * @opp_type:	OPP type to initialize this list for.
- * @opp_defs:	Initial opp definitions to create the list.
- *
- * This function creates a list of opp definitions and returns status.
- * This list can be used to further validation/search/modifications. New
- * opp entries can be added to this list by using opp_add().
- *
- * In the case of error, suitable error code is returned.
- */
 int  __init opp_init_list(enum opp_t opp_type,
 			 const struct omap_opp_def *opp_defs);
 
-/**
- * opp_add()  - Add an OPP table from a table definitions
- * @opp_type:	OPP type under which we want to add our new OPP.
- * @opp_def:	omap_opp_def to describe the OPP which we want to add to list.
- *
- * This function adds an opp definition to the opp list and returns status.
- *
- */
 int opp_add(enum opp_t opp_type, const struct omap_opp_def *opp_def);
 
-/**
- * opp_enable() - Enable a specific OPP
- * @opp:	Pointer to opp
- *
- * Enables a provided opp. If the operation is valid, this returns 0, else the
- * corresponding error value.
- *
- * OPP used here is from the the opp_is_valid/opp_has_freq or other search
- * functions
- */
 int opp_enable(struct omap_opp *opp);
 
-/**
- * opp_disable() - Disable a specific OPP
- * @opp:	Pointer to opp
- *
- * Disables a provided opp. If the operation is valid, this returns 0, else the
- * corresponding error value.
- *
- * OPP used here is from the the opp_is_valid/opp_has_freq or other search
- * functions
- */
 int opp_disable(struct omap_opp *opp);
 
 struct omap_opp * __deprecated opp_find_by_opp_id(enum opp_t opp_type,
diff --git a/arch/arm/plat-omap/opp.c b/arch/arm/plat-omap/opp.c
index 0b61325..01eb0c6 100644
--- a/arch/arm/plat-omap/opp.c
+++ b/arch/arm/plat-omap/opp.c
@@ -24,13 +24,10 @@
  * struct omap_opp - OMAP OPP description structure
  * @enabled:	true/false - marking this OPP as enabled/disabled
  * @rate:	Frequency in hertz
- * @opp_id:	(DEPRECATED) opp identifier
- * @u_volt:     minimum microvolts DC required for this OPP to function
+ * @u_volt:	Nominal voltage in microvolts corresponding to this OPP
+ * @opp_id:	opp identifier (deprecated)
  *
  * This structure stores the OPP information for a given domain.
- * Due to legacy reasons, this structure is currently exposed and
- * will soon be removed elsewhere and will only be used as a handle
- * from the OPP internal referencing mechanism
  */
 struct omap_opp {
 	bool enabled;
@@ -39,18 +36,19 @@ struct omap_opp {
 	u8 opp_id;
 };
 
-/*
- * This maintains pointers to the start of each OPP array.
- */
-
+/* This maintains pointers to the start of each OPP array. */
 static struct omap_opp *_opp_list[OPP_TYPES_MAX];
-/*
- * DEPRECATED: Meant to detect end of opp array
- * This is meant to help co-exist with current SRF etc
- * TODO: REMOVE!
- */
+
+/* Detect end of opp array */
 #define OPP_TERM(opp) (!(opp)->rate && !(opp)->u_volt && !(opp)->enabled)
 
+/**
+ * opp_get_voltage() - Gets the voltage corresponding to an opp
+ * @opp:	opp for which voltage has to be returned for
+ *
+ * Return voltage in micro volt corresponding to the opp, else
+ * return 0
+ */
 unsigned long opp_get_voltage(const struct omap_opp *opp)
 {
 	if (unlikely(!opp || IS_ERR(opp)) || !opp->enabled) {
@@ -60,6 +58,13 @@ unsigned long opp_get_voltage(const struct omap_opp *opp)
 	return opp->u_volt;
 }
 
+/**
+ * opp_get_freq() - Gets the frequency corresponding to an opp
+ * @opp:	opp for which frequency has to be returned for
+ *
+ * Return frequency in hertz corresponding to the opp, else
+ * return 0
+ */
 unsigned long opp_get_freq(const struct omap_opp *opp)
 {
 	if (unlikely(!opp || IS_ERR(opp)) || !opp->enabled) {
@@ -71,7 +76,8 @@ unsigned long opp_get_freq(const struct omap_opp *opp)
 
 /**
  * opp_find_by_opp_id - look up OPP by OPP ID (deprecated)
- * @opp_type: OPP type where we want the look up to happen.
+ * @opp_type:	OPP type where we want the look up to happen.
+ * @opp_id:	OPP ID to search for
  *
  * Returns the struct omap_opp pointer corresponding to the given OPP
  * ID @opp_id, or returns NULL on error.
@@ -99,6 +105,12 @@ struct omap_opp * __deprecated opp_find_by_opp_id(enum opp_t opp_type,
 	return ERR_PTR(-ENOENT);
 }
 
+/**
+ * opp_get_opp_id() - Provide OPP ID corresponding to an OPP (deprecated)
+ * @opp:	opp for which frequency has to be returned for
+ *
+ * Returns an OPP ID for the OPP required, if error, returns 0
+ */
 u8 __deprecated opp_get_opp_id(struct omap_opp *opp)
 {
 	if (unlikely(!opp || IS_ERR(opp)) || !opp->enabled) {
@@ -108,6 +120,13 @@ u8 __deprecated opp_get_opp_id(struct omap_opp *opp)
 	return opp->opp_id;
 }
 
+/**
+ * opp_get_opp_count() - Get number of opps enabled in the opp list
+ * @opp_type:	OPP type we want to count
+ *
+ * This functions returns the number of opps if there are any OPPs enabled,
+ * else returns corresponding error value.
+ */
 int opp_get_opp_count(enum opp_t opp_type)
 {
 	u8 n = 0;
@@ -130,6 +149,20 @@ int opp_get_opp_count(enum opp_t opp_type)
 	return n;
 }
 
+/**
+ * opp_find_freq_exact() - search for an exact frequency
+ * @opp_type:	OPP type we want to search in.
+ * @freq:	frequency to search for
+ * @enabled:	enabled/disabled OPP to search for
+ *
+ * Searches for exact match in the opp list and returns handle to the matching
+ * opp if found, else returns ERR_PTR in case of error and should be handled
+ * using IS_ERR.
+ *
+ * Note enabled is a modifier for the search. if enabled=true, then the match is
+ * for exact matching frequency and is enabled. if false, the match is for exact
+ * frequency which is disabled.
+ */
 struct omap_opp *opp_find_freq_exact(enum opp_t opp_type,
 				     unsigned long freq, bool enabled)
 {
@@ -154,6 +187,33 @@ struct omap_opp *opp_find_freq_exact(enum opp_t opp_type,
 	return OPP_TERM(oppl) ? ERR_PTR(-ENOENT) : oppl;
 }
 
+/**
+ * opp_find_freq_ceil() - Search for an rounded ceil freq
+ * @opp_type:	OPP type where we want to search in
+ * @freq:	Start frequency
+ *
+ * Search for the matching ceil *enabled* OPP from a starting freq
+ * for a domain.
+ *
+ * Returns *opp and *freq is populated with the match, else
+ * returns NULL opp if no match, else returns ERR_PTR in case of error.
+ *
+ * Example usages:
+ *	* find match/next highest available frequency *
+ *	freq = 350000;
+ *	opp = opp_find_freq_ceil(OPP_MPU, &freq))
+ *	if (IS_ERR(opp))
+ *		pr_err("unable to find a higher frequency\n");
+ *	else
+ *		pr_info("match freq = %ld\n", freq);
+ *
+ *	* print all supported frequencies in ascending order *
+ *	freq = 0; * Search for the lowest enabled frequency *
+ *	while (!IS_ERR(opp = opp_find_freq_ceil(OPP_MPU, &freq)) {
+ *		pr_info("freq = %ld\n", freq);
+ *		freq++; * for next higher match *
+ *	}
+ */
 struct omap_opp *opp_find_freq_ceil(enum opp_t opp_type, unsigned long *freq)
 {
 	struct omap_opp *oppl;
@@ -183,6 +243,33 @@ struct omap_opp *opp_find_freq_ceil(enum opp_t opp_type, unsigned long *freq)
 	return oppl;
 }
 
+/**
+ * opp_find_freq_floor() - Search for an rounded floor freq
+ * @opp_type:	OPP type we want to search in
+ * @freq:	Start frequency
+ *
+ * Search for the matching floor *enabled* OPP from a starting freq
+ * for a domain.
+ *
+ * Returns *opp and *freq is populated with the next match, else
+ * returns NULL opp if no match, else returns ERR_PTR in case of error.
+ *
+ * Example usages:
+ *	* find match/next lowest available frequency
+ *	freq = 350000;
+ *	opp = opp_find_freq_floor(OPP_MPU, &freq)))
+ *	if (IS_ERR(opp))
+ *		pr_err ("unable to find a lower frequency\n");
+ *	else
+ *		pr_info("match freq = %ld\n", freq);
+ *
+ *	* print all supported frequencies in descending order *
+ *	freq = ULONG_MAX; * search highest enabled frequency *
+ *	while (!IS_ERR(opp = opp_find_freq_floor(OPP_MPU, &freq)) {
+ *		pr_info("freq = %ld\n", freq);
+ *		freq--; * for next lower match *
+ *	}
+ */
 struct omap_opp *opp_find_freq_floor(enum opp_t opp_type, unsigned long *freq)
 {
 	struct omap_opp *prev_opp, *oppl;
@@ -224,6 +311,13 @@ static void omap_opp_populate(struct omap_opp *opp,
 	opp->u_volt = opp_def->u_volt;
 }
 
+/**
+ * opp_add()  - Add an OPP table from a table definitions
+ * @opp_type:	OPP type under which we want to add our new OPP.
+ * @opp_def:	omap_opp_def to describe the OPP which we want to add to list.
+ *
+ * This function adds an opp definition to the opp list and returns status.
+ */
 int opp_add(enum opp_t opp_type, const struct omap_opp_def *opp_def)
 {
 	struct omap_opp *opp, *oppt, *oppr, *oppl;
@@ -292,6 +386,17 @@ int opp_add(enum opp_t opp_type, const struct omap_opp_def *opp_def)
 	return 0;
 }
 
+/**
+ * opp_init_list() - Initialize an opp list from the opp definitions
+ * @opp_type:	OPP type to initialize this list for.
+ * @opp_defs:	Initial opp definitions to create the list.
+ *
+ * This function creates a list of opp definitions and returns status.
+ * This list can be used to further validation/search/modifications. New
+ * opp entries can be added to this list by using opp_add().
+ *
+ * In the case of error, suitable error code is returned.
+ */
 int __init opp_init_list(enum opp_t opp_type,
 				 const struct omap_opp_def *opp_defs)
 {
@@ -335,6 +440,16 @@ int __init opp_init_list(enum opp_t opp_type,
 	return 0;
 }
 
+/**
+ * opp_enable() - Enable a specific OPP
+ * @opp:	Pointer to opp
+ *
+ * Enables a provided opp. If the operation is valid, this returns 0, else the
+ * corresponding error value.
+ *
+ * OPP used here is from the the opp_is_valid/opp_has_freq or other search
+ * functions
+ */
 int opp_enable(struct omap_opp *opp)
 {
 	if (unlikely(!opp || IS_ERR(opp))) {
@@ -345,6 +460,16 @@ int opp_enable(struct omap_opp *opp)
 	return 0;
 }
 
+/**
+ * opp_disable() - Disable a specific OPP
+ * @opp:	Pointer to opp
+ *
+ * Disables a provided opp. If the operation is valid, this returns 0, else the
+ * corresponding error value.
+ *
+ * OPP used here is from the the opp_is_valid/opp_has_freq or other search
+ * functions
+ */
 int opp_disable(struct omap_opp *opp)
 {
 	if (unlikely(!opp || IS_ERR(opp))) {
@@ -355,7 +480,14 @@ int opp_disable(struct omap_opp *opp)
 	return 0;
 }
 
-/* XXX document */
+/**
+ * opp_init_cpufreq_table() - create a cpufreq table for a domain
+ * @opp_type:	OPP type to initialize this list for
+ * @table:	Cpufreq table returned back to caller
+ *
+ * Generate a cpufreq table for a provided domain - this assumes that the
+ * opp list is already initialized and ready for usage
+ */
 void opp_init_cpufreq_table(enum opp_t opp_type,
 			    struct cpufreq_frequency_table **table)
 {
-- 
1.6.3.3

--
To unsubscribe from this list: send the line "unsubscribe linux-omap" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Index of Archives]     [Linux Arm (vger)]     [ARM Kernel]     [ARM MSM]     [Linux Tegra]     [Linux WPAN Networking]     [Linux Wireless Networking]     [Maemo Users]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite Trails]     [Linux Kernel]     [Linux SCSI]

  Powered by Linux