HWMOD

Welcome to the HWMOD & Device Driver Adaptations wiki.

Introduction
This webpage describes the HWMOD & Device Driver Adaptations software development effort for OMAP3 and OMAP4 platforms. The purpose is to provide information on the current status and features planned in the road map.

Steps involved in HWMOD

 * Convert your device to platform device driver. This doesn't require any understanding of PM or HWMOD. E.g. GPIO, which was a library, was converted to platform driver first before doing any HWMOD.


 * Use HWMOD and make sure that the functionality achieved in the previous step is achieved (without PM).
 * Do omap_device_build call that looks up the HWMOD database and does platform device registration.
 * Earlier individual devices had to be registered using platform_device_register by passing all the information (like IRQ line, memory map, DMA channel etc.) in the platform_device structure.
 * The information had to manually populated.
 * Now that is taken care of by omap_device_build


 * Use omap_device APIs viz. omap_device_enable, omap_device_idle & omap_device_shutdown for power management in place of clock related controls.


 * Use omap_pm_layer to put the constraints.


 * Test driver's normal functionality with adaptations enabled.


 * Test system level PM features like CORE CSWR.


 * Drivers implementing h/w mod need to implement run-time PM as well.
 * Instead of using omap_device_enable/disable functions directly, drivers will be calling get_sync/put_sync which eventually will call platform_pm_runtime_suspend & platform_pm_runtime_resume of platform bus.
 * These APIs will in turn call omap_device_enable/disable + the runtime_suspend/resume defined by the driver.
 * Refer the following for details on runtime PM:
 * http://www.elinux.org/images/0/08/ELC-2010-Hilman-Runtime-PM.pdf
 * \Documentation\power\runtime_pm.txt
 * arch\arm\mach-omap2\pm_bus.c for platform bus run time API implementation.
 * Points to be noted
 * Compile and test the changes on OMAP4, OMAP3 & OMAP2 platforms
 * SoC specifics of any device is attached to the SoC specific hwmod using the dev_attr pointer. Make use of this.
 * Make use omap_hwmod_for_each_by_class to iterate over all the hwmods in the device class while doing omap_device_build
 * Any clocks other than fck/ick need to make use of clock FW APIs if required. For fck/ick do not use clock FW APIs as omap_device layer APIs takes care of the same. There is a opt_clk fld for other clocks (example: GPIO has debounce clock)
 * Do not break the working code and multi-omap build functionality.
 * All the SoC base address will be gathered in a single header file (omapXXXX.h) that should be used only by the omap_hwmod_xxxx_data.c file.

Plan for Device Driver Adaptation Using HWMOD
The following table gives the schedule for device driver adaptations to HWMOD and tracks the progress.

Device Driver Adaptation to HWMOD - Schedule and Progress

Reset Management Support in HWMOD

 * Problem Statement
 * Most processor IPs do have a HW reset signal controlled by the PRM.
 * There is currently no abstraction layer to control the PRM reset register.
 * Since these reset signals are IP specific, they should be controlled manually by the driver code.


 * Proposed Solution
 * Add two APIs for asserting / deasserting reset lines in hwmods processor that require manual reset control.
 * Add one API to get the current reset state.


 * RFC Patches
 * RFC Patches Branch: hwmod_reset

More Granular HWMOD Structures

 * Problem Statement
 * Today hwmod structs are generated at a module level for DSS and IPU (Ducati).
 * However the drivers require control at submodule level. E.g. The DSS2 driver would require to control sub-modules like dispc, dsi1, dsi2, hdmi etc.
 * Also the syslink and IOMMU drivers need control at individual M3 level


 * Proposed Solution
 * Generate hwmod structs at sub-module level.
 * Need to decide if hierarchical control is needed


 * RFC Patches
 * RFC Patches Branch: hwmod_dss

Multi-level omap_device_idle

 * Problem Statement
 * Today most drivers only use one level of device_idle by populating activate/ deactivate_func as omap_device_idle_hwmods/ omap_device_enable_hwmods
 * omap_device_idle_hwmods disables the device clocks, if they happen to be the last set of clocks in the clockdomian, the clockdomain transitions to inactive and the powerdomain to the target state programmed (Deepest possile by default)
 * How do we support multiple levels of device idling? So that drivers can prevent going to the deepest idle state incase latency is not acceptable.


 * Proposed Solution
 * Use device latency constraint to control the powerdomain (of the device) target state.
 * Start with mapping the different device idle states with the different powerdomain states supported.
 * Keep the activate/deactivate_func same as before.

Placeholder for patches from Vibhore to support device latency contraint
 * RFC Patches

Access to HWMOD Internal Data

 * Problem Statement
 * Information stored in hwmod structs are not directly accessible to drivers. There might be instances when this is needed.
 * E.g. A driver requesting for optional clocks can do away with knowing the clock name string.
 * Syslink, which needs to request for i2c1 clocks can request for i2c hmwod main_clk.


 * Proposed Solution
 * Discuss and identify a list of all the hwmod internal data that might be needed by drivers and define apis for each of them - Rajendra

Miscellaneous Issues

 * Today omap_device_build provides a way to only pass platform_data structure during device registration. How do you pass other info which needs to be part of struct device? E.g. in the case of USB driver, there is a need to populate the dma_mask.
 * Is usecounting needed at omap_device level?
 * More to be added as identified during discussions

Additional HWMOD Enhancements Identified

 * Identified during the Bangalore PM SW workshop 7-11 Jun, 2010
 * rt_va : hwmod Paul
 * ifdef !CONFIG_PM_RUNTIME, leave enabled : hwmod Kevin
 * dev-> init_name : Thara, Kevin
 * Add clk_add_alias to omap_device_build : omap_device/ hwmod Paul
 * Add PRCM reset code for processor IPs & connect to HWMOD_INIT_NO_RESET : hwmod Benoit
 * Fix hwmod locking by adding lockless enable/ idle functions : device/ hwmod Kevin
 * Syslink needs to call device driver functions to reserve devices : syslink/ other devices? Is a HWMOD processor reset API necessary? Benoit
 * Connect omap_device lifecycle to device/ platform_device: hwmod Paul
 * Integration code that needs to set dev->dma_mask need to call get_device/ put_device : Integration code
 * Fine grained hwmod locking Paul
 * Add power domain/ clock domain wakeup latency tracking
 * Fix OMAP4 hwmod generator to generate HWMOD_NO_IDLEST Partha
 * Remove OCP_USER from OMAP4 hwmods without address space: OMAP4 autogen Partha