aboutsummaryrefslogtreecommitdiffstats
path: root/arch/arm/mach-omap2/omap_hwmod.c
diff options
context:
space:
mode:
authorPaul Walmsley <paul@pwsan.com>2010-09-21 17:02:23 -0400
committerPaul Walmsley <paul@pwsan.com>2010-09-22 11:19:55 -0400
commit74ff3a68ed11f1e9eede4fe301f42cc3cdf7396a (patch)
treebae54b66bcebdad7eb0334695c7765f509728206 /arch/arm/mach-omap2/omap_hwmod.c
parent4ef7aca895b2d06c07ff9d5f378af84bbf757e43 (diff)
OMAP: hwmod: improve documentation, clean up function names
This patch: - adds more documentation to the hwmod code - fixes some documentation typos elsewhere in the file - changes the _sysc_*() function names to appear in (verb, noun) order, to match the rest of the function names. This patch should not result in any functional change. Signed-off-by: Paul Walmsley <paul@pwsan.com> Cc: Kevin Hilman <khilman@deeprootsystems.com> Cc: BenoƮt Cousson <b-cousson@ti.com>
Diffstat (limited to 'arch/arm/mach-omap2/omap_hwmod.c')
-rw-r--r--arch/arm/mach-omap2/omap_hwmod.c141
1 files changed, 119 insertions, 22 deletions
diff --git a/arch/arm/mach-omap2/omap_hwmod.c b/arch/arm/mach-omap2/omap_hwmod.c
index d694067e6e9..c3a5889d8ad 100644
--- a/arch/arm/mach-omap2/omap_hwmod.c
+++ b/arch/arm/mach-omap2/omap_hwmod.c
@@ -13,10 +13,102 @@
13 * it under the terms of the GNU General Public License version 2 as 13 * it under the terms of the GNU General Public License version 2 as
14 * published by the Free Software Foundation. 14 * published by the Free Software Foundation.
15 * 15 *
16 * This code manages "OMAP modules" (on-chip devices) and their 16 * Introduction
17 * integration with Linux device driver and bus code. 17 * ------------
18 * 18 * One way to view an OMAP SoC is as a collection of largely unrelated
19 * References: 19 * IP blocks connected by interconnects. The IP blocks include
20 * devices such as ARM processors, audio serial interfaces, UARTs,
21 * etc. Some of these devices, like the DSP, are created by TI;
22 * others, like the SGX, largely originate from external vendors. In
23 * TI's documentation, on-chip devices are referred to as "OMAP
24 * modules." Some of these IP blocks are identical across several
25 * OMAP versions. Others are revised frequently.
26 *
27 * These OMAP modules are tied together by various interconnects.
28 * Most of the address and data flow between modules is via OCP-based
29 * interconnects such as the L3 and L4 buses; but there are other
30 * interconnects that distribute the hardware clock tree, handle idle
31 * and reset signaling, supply power, and connect the modules to
32 * various pads or balls on the OMAP package.
33 *
34 * OMAP hwmod provides a consistent way to describe the on-chip
35 * hardware blocks and their integration into the rest of the chip.
36 * This description can be automatically generated from the TI
37 * hardware database. OMAP hwmod provides a standard, consistent API
38 * to reset, enable, idle, and disable these hardware blocks. And
39 * hwmod provides a way for other core code, such as the Linux device
40 * code or the OMAP power management and address space mapping code,
41 * to query the hardware database.
42 *
43 * Using hwmod
44 * -----------
45 * Drivers won't call hwmod functions directly. That is done by the
46 * omap_device code, and in rare occasions, by custom integration code
47 * in arch/arm/ *omap*. The omap_device code includes functions to
48 * build a struct platform_device using omap_hwmod data, and that is
49 * currently how hwmod data is communicated to drivers and to the
50 * Linux driver model. Most drivers will call omap_hwmod functions only
51 * indirectly, via pm_runtime*() functions.
52 *
53 * From a layering perspective, here is where the OMAP hwmod code
54 * fits into the kernel software stack:
55 *
56 * +-------------------------------+
57 * | Device driver code |
58 * | (e.g., drivers/) |
59 * +-------------------------------+
60 * | Linux driver model |
61 * | (platform_device / |
62 * | platform_driver data/code) |
63 * +-------------------------------+
64 * | OMAP core-driver integration |
65 * |(arch/arm/mach-omap2/devices.c)|
66 * +-------------------------------+
67 * | omap_device code |
68 * | (../plat-omap/omap_device.c) |
69 * +-------------------------------+
70 * ----> | omap_hwmod code/data | <-----
71 * | (../mach-omap2/omap_hwmod*) |
72 * +-------------------------------+
73 * | OMAP clock/PRCM/register fns |
74 * | (__raw_{read,write}l, clk*) |
75 * +-------------------------------+
76 *
77 * Device drivers should not contain any OMAP-specific code or data in
78 * them. They should only contain code to operate the IP block that
79 * the driver is responsible for. This is because these IP blocks can
80 * also appear in other SoCs, either from TI (such as DaVinci) or from
81 * other manufacturers; and drivers should be reusable across other
82 * platforms.
83 *
84 * The OMAP hwmod code also will attempt to reset and idle all on-chip
85 * devices upon boot. The goal here is for the kernel to be
86 * completely self-reliant and independent from bootloaders. This is
87 * to ensure a repeatable configuration, both to ensure consistent
88 * runtime behavior, and to make it easier for others to reproduce
89 * bugs.
90 *
91 * OMAP module activity states
92 * ---------------------------
93 * The hwmod code considers modules to be in one of several activity
94 * states. IP blocks start out in an UNKNOWN state, then once they
95 * are registered via the hwmod code, proceed to the REGISTERED state.
96 * Once their clock names are resolved to clock pointers, the module
97 * enters the CLKS_INITED state; and finally, once the module has been
98 * reset and the integration registers programmed, the INITIALIZED state
99 * is entered. The hwmod code will then place the module into either
100 * the IDLE state to save power, or in the case of a critical system
101 * module, the ENABLED state.
102 *
103 * OMAP core integration code can then call omap_hwmod*() functions
104 * directly to move the module between the IDLE, ENABLED, and DISABLED
105 * states, as needed. This is done during both the PM idle loop, and
106 * in the OMAP core integration code's implementation of the PM runtime
107 * functions.
108 *
109 * References
110 * ----------
111 * This is a partial list.
20 * - OMAP2420 Multimedia Processor Silicon Revision 2.1.1, 2.2 (SWPU064) 112 * - OMAP2420 Multimedia Processor Silicon Revision 2.1.1, 2.2 (SWPU064)
21 * - OMAP2430 Multimedia Device POP Silicon Revision 2.1 (SWPU090) 113 * - OMAP2430 Multimedia Device POP Silicon Revision 2.1 (SWPU090)
22 * - OMAP34xx Multimedia Device Silicon Revision 3.1 (SWPU108) 114 * - OMAP34xx Multimedia Device Silicon Revision 3.1 (SWPU108)
@@ -654,7 +746,7 @@ static void __iomem *_find_mpu_rt_base(struct omap_hwmod *oh, u8 index)
654} 746}
655 747
656/** 748/**
657 * _sysc_enable - try to bring a module out of idle via OCP_SYSCONFIG 749 * _enable_sysc - try to bring a module out of idle via OCP_SYSCONFIG
658 * @oh: struct omap_hwmod * 750 * @oh: struct omap_hwmod *
659 * 751 *
660 * If module is marked as SWSUP_SIDLE, force the module out of slave 752 * If module is marked as SWSUP_SIDLE, force the module out of slave
@@ -662,7 +754,7 @@ static void __iomem *_find_mpu_rt_base(struct omap_hwmod *oh, u8 index)
662 * as SWSUP_MSUSPEND, force the module out of master standby; 754 * as SWSUP_MSUSPEND, force the module out of master standby;
663 * otherwise, configure it for smart-standby. No return value. 755 * otherwise, configure it for smart-standby. No return value.
664 */ 756 */
665static void _sysc_enable(struct omap_hwmod *oh) 757static void _enable_sysc(struct omap_hwmod *oh)
666{ 758{
667 u8 idlemode, sf; 759 u8 idlemode, sf;
668 u32 v; 760 u32 v;
@@ -708,7 +800,7 @@ static void _sysc_enable(struct omap_hwmod *oh)
708} 800}
709 801
710/** 802/**
711 * _sysc_idle - try to put a module into idle via OCP_SYSCONFIG 803 * _idle_sysc - try to put a module into idle via OCP_SYSCONFIG
712 * @oh: struct omap_hwmod * 804 * @oh: struct omap_hwmod *
713 * 805 *
714 * If module is marked as SWSUP_SIDLE, force the module into slave 806 * If module is marked as SWSUP_SIDLE, force the module into slave
@@ -716,7 +808,7 @@ static void _sysc_enable(struct omap_hwmod *oh)
716 * as SWSUP_MSUSPEND, force the module into master standby; otherwise, 808 * as SWSUP_MSUSPEND, force the module into master standby; otherwise,
717 * configure it for smart-standby. No return value. 809 * configure it for smart-standby. No return value.
718 */ 810 */
719static void _sysc_idle(struct omap_hwmod *oh) 811static void _idle_sysc(struct omap_hwmod *oh)
720{ 812{
721 u8 idlemode, sf; 813 u8 idlemode, sf;
722 u32 v; 814 u32 v;
@@ -743,13 +835,13 @@ static void _sysc_idle(struct omap_hwmod *oh)
743} 835}
744 836
745/** 837/**
746 * _sysc_shutdown - force a module into idle via OCP_SYSCONFIG 838 * _shutdown_sysc - force a module into idle via OCP_SYSCONFIG
747 * @oh: struct omap_hwmod * 839 * @oh: struct omap_hwmod *
748 * 840 *
749 * Force the module into slave idle and master suspend. No return 841 * Force the module into slave idle and master suspend. No return
750 * value. 842 * value.
751 */ 843 */
752static void _sysc_shutdown(struct omap_hwmod *oh) 844static void _shutdown_sysc(struct omap_hwmod *oh)
753{ 845{
754 u32 v; 846 u32 v;
755 u8 sf; 847 u8 sf;
@@ -1071,8 +1163,11 @@ dis_opt_clks:
1071 * @oh: struct omap_hwmod * 1163 * @oh: struct omap_hwmod *
1072 * 1164 *
1073 * Enables an omap_hwmod @oh such that the MPU can access the hwmod's 1165 * Enables an omap_hwmod @oh such that the MPU can access the hwmod's
1074 * register target. Returns -EINVAL if the hwmod is in the wrong 1166 * register target. (This function has a full name --
1075 * state or passes along the return value of _wait_target_ready(). 1167 * _omap_hwmod_enable() rather than simply _enable() -- because it is
1168 * currently required by the pm34xx.c idle loop.) Returns -EINVAL if
1169 * the hwmod is in the wrong state or passes along the return value of
1170 * _wait_target_ready().
1076 */ 1171 */
1077int _omap_hwmod_enable(struct omap_hwmod *oh) 1172int _omap_hwmod_enable(struct omap_hwmod *oh)
1078{ 1173{
@@ -1110,7 +1205,7 @@ int _omap_hwmod_enable(struct omap_hwmod *oh)
1110 if (oh->class->sysc) { 1205 if (oh->class->sysc) {
1111 if (!(oh->_int_flags & _HWMOD_SYSCONFIG_LOADED)) 1206 if (!(oh->_int_flags & _HWMOD_SYSCONFIG_LOADED))
1112 _update_sysc_cache(oh); 1207 _update_sysc_cache(oh);
1113 _sysc_enable(oh); 1208 _enable_sysc(oh);
1114 } 1209 }
1115 } else { 1210 } else {
1116 pr_debug("omap_hwmod: %s: _wait_target_ready: %d\n", 1211 pr_debug("omap_hwmod: %s: _wait_target_ready: %d\n",
@@ -1121,12 +1216,14 @@ int _omap_hwmod_enable(struct omap_hwmod *oh)
1121} 1216}
1122 1217
1123/** 1218/**
1124 * _idle - idle an omap_hwmod 1219 * _omap_hwmod_idle - idle an omap_hwmod
1125 * @oh: struct omap_hwmod * 1220 * @oh: struct omap_hwmod *
1126 * 1221 *
1127 * Idles an omap_hwmod @oh. This should be called once the hwmod has 1222 * Idles an omap_hwmod @oh. This should be called once the hwmod has
1128 * no further work. Returns -EINVAL if the hwmod is in the wrong 1223 * no further work. (This function has a full name --
1129 * state or returns 0. 1224 * _omap_hwmod_idle() rather than simply _idle() -- because it is
1225 * currently required by the pm34xx.c idle loop.) Returns -EINVAL if
1226 * the hwmod is in the wrong state or returns 0.
1130 */ 1227 */
1131int _omap_hwmod_idle(struct omap_hwmod *oh) 1228int _omap_hwmod_idle(struct omap_hwmod *oh)
1132{ 1229{
@@ -1139,7 +1236,7 @@ int _omap_hwmod_idle(struct omap_hwmod *oh)
1139 pr_debug("omap_hwmod: %s: idling\n", oh->name); 1236 pr_debug("omap_hwmod: %s: idling\n", oh->name);
1140 1237
1141 if (oh->class->sysc) 1238 if (oh->class->sysc)
1142 _sysc_idle(oh); 1239 _idle_sysc(oh);
1143 _del_initiator_dep(oh, mpu_oh); 1240 _del_initiator_dep(oh, mpu_oh);
1144 _disable_clocks(oh); 1241 _disable_clocks(oh);
1145 1242
@@ -1169,7 +1266,7 @@ static int _shutdown(struct omap_hwmod *oh)
1169 pr_debug("omap_hwmod: %s: disabling\n", oh->name); 1266 pr_debug("omap_hwmod: %s: disabling\n", oh->name);
1170 1267
1171 if (oh->class->sysc) 1268 if (oh->class->sysc)
1172 _sysc_shutdown(oh); 1269 _shutdown_sysc(oh);
1173 1270
1174 /* 1271 /*
1175 * If an IP contains only one HW reset line, then assert it 1272 * If an IP contains only one HW reset line, then assert it
@@ -1262,7 +1359,7 @@ static int _setup(struct omap_hwmod *oh, void *data)
1262 */ 1359 */
1263 if (oh->class->sysc) { 1360 if (oh->class->sysc) {
1264 _update_sysc_cache(oh); 1361 _update_sysc_cache(oh);
1265 _sysc_enable(oh); 1362 _enable_sysc(oh);
1266 } 1363 }
1267 } 1364 }
1268 1365
@@ -1518,7 +1615,7 @@ int omap_hwmod_unregister(struct omap_hwmod *oh)
1518 * omap_hwmod_enable - enable an omap_hwmod 1615 * omap_hwmod_enable - enable an omap_hwmod
1519 * @oh: struct omap_hwmod * 1616 * @oh: struct omap_hwmod *
1520 * 1617 *
1521 * Enable an omap_hwomd @oh. Intended to be called by omap_device_enable(). 1618 * Enable an omap_hwmod @oh. Intended to be called by omap_device_enable().
1522 * Returns -EINVAL on error or passes along the return value from _enable(). 1619 * Returns -EINVAL on error or passes along the return value from _enable().
1523 */ 1620 */
1524int omap_hwmod_enable(struct omap_hwmod *oh) 1621int omap_hwmod_enable(struct omap_hwmod *oh)
@@ -1540,7 +1637,7 @@ int omap_hwmod_enable(struct omap_hwmod *oh)
1540 * omap_hwmod_idle - idle an omap_hwmod 1637 * omap_hwmod_idle - idle an omap_hwmod
1541 * @oh: struct omap_hwmod * 1638 * @oh: struct omap_hwmod *
1542 * 1639 *
1543 * Idle an omap_hwomd @oh. Intended to be called by omap_device_idle(). 1640 * Idle an omap_hwmod @oh. Intended to be called by omap_device_idle().
1544 * Returns -EINVAL on error or passes along the return value from _idle(). 1641 * Returns -EINVAL on error or passes along the return value from _idle().
1545 */ 1642 */
1546int omap_hwmod_idle(struct omap_hwmod *oh) 1643int omap_hwmod_idle(struct omap_hwmod *oh)
@@ -1559,7 +1656,7 @@ int omap_hwmod_idle(struct omap_hwmod *oh)
1559 * omap_hwmod_shutdown - shutdown an omap_hwmod 1656 * omap_hwmod_shutdown - shutdown an omap_hwmod
1560 * @oh: struct omap_hwmod * 1657 * @oh: struct omap_hwmod *
1561 * 1658 *
1562 * Shutdown an omap_hwomd @oh. Intended to be called by 1659 * Shutdown an omap_hwmod @oh. Intended to be called by
1563 * omap_device_shutdown(). Returns -EINVAL on error or passes along 1660 * omap_device_shutdown(). Returns -EINVAL on error or passes along
1564 * the return value from _shutdown(). 1661 * the return value from _shutdown().
1565 */ 1662 */