diff options
author | Paul Walmsley <paul@pwsan.com> | 2010-09-21 17:02:23 -0400 |
---|---|---|
committer | Paul Walmsley <paul@pwsan.com> | 2010-09-22 11:19:55 -0400 |
commit | 74ff3a68ed11f1e9eede4fe301f42cc3cdf7396a (patch) | |
tree | bae54b66bcebdad7eb0334695c7765f509728206 /arch/arm/mach-omap2/omap_hwmod.c | |
parent | 4ef7aca895b2d06c07ff9d5f378af84bbf757e43 (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.c | 141 |
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 | */ |
665 | static void _sysc_enable(struct omap_hwmod *oh) | 757 | static 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 | */ |
719 | static void _sysc_idle(struct omap_hwmod *oh) | 811 | static 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 | */ |
752 | static void _sysc_shutdown(struct omap_hwmod *oh) | 844 | static 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 | */ |
1077 | int _omap_hwmod_enable(struct omap_hwmod *oh) | 1172 | int _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 | */ |
1131 | int _omap_hwmod_idle(struct omap_hwmod *oh) | 1228 | int _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 | */ |
1524 | int omap_hwmod_enable(struct omap_hwmod *oh) | 1621 | int 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 | */ |
1546 | int omap_hwmod_idle(struct omap_hwmod *oh) | 1643 | int 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 | */ |