diff options
author | Jonathan Corbet <corbet@lwn.net> | 2023-05-04 01:47:22 +0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2023-06-12 15:33:40 +0300 |
commit | e790a4ce529041bb21ec0b69a38c1b92f29df2cf (patch) | |
tree | 56f44e5f8f8fe8d94d43a4bd7743e82e4e7889d6 /Documentation/arm/omap | |
parent | f1fcbaa18b28dec10281551dfe6ed3a3ed80e3d6 (diff) | |
download | linux-e790a4ce529041bb21ec0b69a38c1b92f29df2cf.tar.xz |
arm: docs: Move Arm documentation to Documentation/arch/
Architecture-specific documentation is being moved into Documentation/arch/
as a way of cleaning up the top-level documentation directory and making
the docs hierarchy more closely match the source hierarchy. Move
Documentation/arm into arch/ (along with the Chinese equvalent
translations).
Cc: Maxime Coquelin <mcoquelin.stm32@gmail.com>
Cc: Chen-Yu Tsai <wens@csie.org>
Cc: Jernej Skrabec <jernej.skrabec@gmail.com>
Cc: Samuel Holland <samuel@sholland.org>
Cc: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Cc: Alim Akhtar <alim.akhtar@samsung.com>
Cc: Alex Shi <alexs@kernel.org>
Cc: linux-doc@vger.kernel.org
Cc: linux-arm-kernel@lists.infradead.org
Cc: linux-arch@vger.kernel.org
Acked-by: Alexandre TORGUE <alexandre.torgue@foss.st.com>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/arm/omap')
-rw-r--r-- | Documentation/arm/omap/dss.rst | 372 | ||||
-rw-r--r-- | Documentation/arm/omap/index.rst | 12 | ||||
-rw-r--r-- | Documentation/arm/omap/omap.rst | 18 | ||||
-rw-r--r-- | Documentation/arm/omap/omap_pm.rst | 165 |
4 files changed, 0 insertions, 567 deletions
diff --git a/Documentation/arm/omap/dss.rst b/Documentation/arm/omap/dss.rst deleted file mode 100644 index a40c4d9c717a..000000000000 --- a/Documentation/arm/omap/dss.rst +++ /dev/null @@ -1,372 +0,0 @@ -========================= -OMAP2/3 Display Subsystem -========================= - -This is an almost total rewrite of the OMAP FB driver in drivers/video/omap -(let's call it DSS1). The main differences between DSS1 and DSS2 are DSI, -TV-out and multiple display support, but there are lots of small improvements -also. - -The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB, -panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live -currently side by side, you can choose which one to use. - -Features --------- - -Working and tested features include: - -- MIPI DPI (parallel) output -- MIPI DSI output in command mode -- MIPI DBI (RFBI) output -- SDI output -- TV output -- All pieces can be compiled as a module or inside kernel -- Use DISPC to update any of the outputs -- Use CPU to update RFBI or DSI output -- OMAP DISPC planes -- RGB16, RGB24 packed, RGB24 unpacked -- YUV2, UYVY -- Scaling -- Adjusting DSS FCK to find a good pixel clock -- Use DSI DPLL to create DSS FCK - -Tested boards include: -- OMAP3 SDP board -- Beagle board -- N810 - -omapdss driver --------------- - -The DSS driver does not itself have any support for Linux framebuffer, V4L or -such like the current ones, but it has an internal kernel API that upper level -drivers can use. - -The DSS driver models OMAP's overlays, overlay managers and displays in a -flexible way to enable non-common multi-display configuration. In addition to -modelling the hardware overlays, omapdss supports virtual overlays and overlay -managers. These can be used when updating a display with CPU or system DMA. - -omapdss driver support for audio --------------------------------- -There exist several display technologies and standards that support audio as -well. Hence, it is relevant to update the DSS device driver to provide an audio -interface that may be used by an audio driver or any other driver interested in -the functionality. - -The audio_enable function is intended to prepare the relevant -IP for playback (e.g., enabling an audio FIFO, taking in/out of reset -some IP, enabling companion chips, etc). It is intended to be called before -audio_start. The audio_disable function performs the reverse operation and is -intended to be called after audio_stop. - -While a given DSS device driver may support audio, it is possible that for -certain configurations audio is not supported (e.g., an HDMI display using a -VESA video timing). The audio_supported function is intended to query whether -the current configuration of the display supports audio. - -The audio_config function is intended to configure all the relevant audio -parameters of the display. In order to make the function independent of any -specific DSS device driver, a struct omap_dss_audio is defined. Its purpose -is to contain all the required parameters for audio configuration. At the -moment, such structure contains pointers to IEC-60958 channel status word -and CEA-861 audio infoframe structures. This should be enough to support -HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958. - -The audio_enable/disable, audio_config and audio_supported functions could be -implemented as functions that may sleep. Hence, they should not be called -while holding a spinlock or a readlock. - -The audio_start/audio_stop function is intended to effectively start/stop audio -playback after the configuration has taken place. These functions are designed -to be used in an atomic context. Hence, audio_start should return quickly and be -called only after all the needed resources for audio playback (audio FIFOs, -DMA channels, companion chips, etc) have been enabled to begin data transfers. -audio_stop is designed to only stop the audio transfers. The resources used -for playback are released using audio_disable. - -The enum omap_dss_audio_state may be used to help the implementations of -the interface to keep track of the audio state. The initial state is _DISABLED; -then, the state transitions to _CONFIGURED, and then, when it is ready to -play audio, to _ENABLED. The state _PLAYING is used when the audio is being -rendered. - - -Panel and controller drivers ----------------------------- - -The drivers implement panel or controller specific functionality and are not -usually visible to users except through omapfb driver. They register -themselves to the DSS driver. - -omapfb driver -------------- - -The omapfb driver implements arbitrary number of standard linux framebuffers. -These framebuffers can be routed flexibly to any overlays, thus allowing very -dynamic display architecture. - -The driver exports some omapfb specific ioctls, which are compatible with the -ioctls in the old driver. - -The rest of the non standard features are exported via sysfs. Whether the final -implementation will use sysfs, or ioctls, is still open. - -V4L2 drivers ------------- - -V4L2 is being implemented in TI. - -From omapdss point of view the V4L2 drivers should be similar to framebuffer -driver. - -Architecture --------------------- - -Some clarification what the different components do: - - - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the - pixel data for the image. Framebuffer has width and height and color - depth. - - Overlay defines where the pixels are read from and where they go on the - screen. The overlay may be smaller than framebuffer, thus displaying only - part of the framebuffer. The position of the overlay may be changed if - the overlay is smaller than the display. - - Overlay manager combines the overlays in to one image and feeds them to - display. - - Display is the actual physical display device. - -A framebuffer can be connected to multiple overlays to show the same pixel data -on all of the overlays. Note that in this case the overlay input sizes must be -the same, but, in case of video overlays, the output size can be different. Any -framebuffer can be connected to any overlay. - -An overlay can be connected to one overlay manager. Also DISPC overlays can be -connected only to DISPC overlay managers, and virtual overlays can be only -connected to virtual overlays. - -An overlay manager can be connected to one display. There are certain -restrictions which kinds of displays an overlay manager can be connected: - - - DISPC TV overlay manager can be only connected to TV display. - - Virtual overlay managers can only be connected to DBI or DSI displays. - - DISPC LCD overlay manager can be connected to all displays, except TV - display. - -Sysfs ------ -The sysfs interface is mainly used for testing. I don't think sysfs -interface is the best for this in the final version, but I don't quite know -what would be the best interfaces for these things. - -The sysfs interface is divided to two parts: DSS and FB. - -/sys/class/graphics/fb? directory: -mirror 0=off, 1=on -rotate Rotation 0-3 for 0, 90, 180, 270 degrees -rotate_type 0 = DMA rotation, 1 = VRFB rotation -overlays List of overlay numbers to which framebuffer pixels go -phys_addr Physical address of the framebuffer -virt_addr Virtual address of the framebuffer -size Size of the framebuffer - -/sys/devices/platform/omapdss/overlay? directory: -enabled 0=off, 1=on -input_size width,height (ie. the framebuffer size) -manager Destination overlay manager name -name -output_size width,height -position x,y -screen_width width -global_alpha global alpha 0-255 0=transparent 255=opaque - -/sys/devices/platform/omapdss/manager? directory: -display Destination display -name -alpha_blending_enabled 0=off, 1=on -trans_key_enabled 0=off, 1=on -trans_key_type gfx-destination, video-source -trans_key_value transparency color key (RGB24) -default_color default background color (RGB24) - -/sys/devices/platform/omapdss/display? directory: - -=============== ============================================================= -ctrl_name Controller name -mirror 0=off, 1=on -update_mode 0=off, 1=auto, 2=manual -enabled 0=off, 1=on -name -rotate Rotation 0-3 for 0, 90, 180, 270 degrees -timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw) - When writing, two special timings are accepted for tv-out: - "pal" and "ntsc" -panel_name -tear_elim Tearing elimination 0=off, 1=on -output_type Output type (video encoder only): "composite" or "svideo" -=============== ============================================================= - -There are also some debugfs files at <debugfs>/omapdss/ which show information -about clocks and registers. - -Examples --------- - -The following definitions have been made for the examples below:: - - ovl0=/sys/devices/platform/omapdss/overlay0 - ovl1=/sys/devices/platform/omapdss/overlay1 - ovl2=/sys/devices/platform/omapdss/overlay2 - - mgr0=/sys/devices/platform/omapdss/manager0 - mgr1=/sys/devices/platform/omapdss/manager1 - - lcd=/sys/devices/platform/omapdss/display0 - dvi=/sys/devices/platform/omapdss/display1 - tv=/sys/devices/platform/omapdss/display2 - - fb0=/sys/class/graphics/fb0 - fb1=/sys/class/graphics/fb1 - fb2=/sys/class/graphics/fb2 - -Default setup on OMAP3 SDP --------------------------- - -Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI -and TV-out are not in use. The columns from left to right are: -framebuffers, overlays, overlay managers, displays. Framebuffers are -handled by omapfb, and the rest by the DSS:: - - FB0 --- GFX -\ DVI - FB1 --- VID1 --+- LCD ---- LCD - FB2 --- VID2 -/ TV ----- TV - -Example: Switch from LCD to DVI -------------------------------- - -:: - - w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1` - h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1` - - echo "0" > $lcd/enabled - echo "" > $mgr0/display - fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h - # at this point you have to switch the dvi/lcd dip-switch from the omap board - echo "dvi" > $mgr0/display - echo "1" > $dvi/enabled - -After this the configuration looks like::: - - FB0 --- GFX -\ -- DVI - FB1 --- VID1 --+- LCD -/ LCD - FB2 --- VID2 -/ TV ----- TV - -Example: Clone GFX overlay to LCD and TV ----------------------------------------- - -:: - - w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1` - h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1` - - echo "0" > $ovl0/enabled - echo "0" > $ovl1/enabled - - echo "" > $fb1/overlays - echo "0,1" > $fb0/overlays - - echo "$w,$h" > $ovl1/output_size - echo "tv" > $ovl1/manager - - echo "1" > $ovl0/enabled - echo "1" > $ovl1/enabled - - echo "1" > $tv/enabled - -After this the configuration looks like (only relevant parts shown):: - - FB0 +-- GFX ---- LCD ---- LCD - \- VID1 ---- TV ---- TV - -Misc notes ----------- - -OMAP FB allocates the framebuffer memory using the standard dma allocator. You -can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma -allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase -the global memory area for CMA. - -Using DSI DPLL to generate pixel clock it is possible produce the pixel clock -of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI. - -Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB -does not support mirroring. - -VRFB rotation requires much more memory than non-rotated framebuffer, so you -probably need to increase your vram setting before using VRFB rotation. Also, -many applications may not work with VRFB if they do not pay attention to all -framebuffer parameters. - -Kernel boot arguments ---------------------- - -omapfb.mode=<display>:<mode>[,...] - - Default video mode for specified displays. For example, - "dvi:800x400MR-24@60". See drivers/video/modedb.c. - There are also two special modes: "pal" and "ntsc" that - can be used to tv out. - -omapfb.vram=<fbnum>:<size>[@<physaddr>][,...] - - VRAM allocated for a framebuffer. Normally omapfb allocates vram - depending on the display size. With this you can manually allocate - more or define the physical address of each framebuffer. For example, - "1:4M" to allocate 4M for fb1. - -omapfb.debug=<y|n> - - Enable debug printing. You have to have OMAPFB debug support enabled - in kernel config. - -omapfb.test=<y|n> - - Draw test pattern to framebuffer whenever framebuffer settings change. - You need to have OMAPFB debug support enabled in kernel config. - -omapfb.vrfb=<y|n> - - Use VRFB rotation for all framebuffers. - -omapfb.rotate=<angle> - - Default rotation applied to all framebuffers. - 0 - 0 degree rotation - 1 - 90 degree rotation - 2 - 180 degree rotation - 3 - 270 degree rotation - -omapfb.mirror=<y|n> - - Default mirror for all framebuffers. Only works with DMA rotation. - -omapdss.def_disp=<display> - - Name of default display, to which all overlays will be connected. - Common examples are "lcd" or "tv". - -omapdss.debug=<y|n> - - Enable debug printing. You have to have DSS debug support enabled in - kernel config. - -TODO ----- - -DSS locking - -Error checking - -- Lots of checks are missing or implemented just as BUG() - -System DMA update for DSI - -- Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how - to skip the empty byte?) - -OMAP1 support - -- Not sure if needed diff --git a/Documentation/arm/omap/index.rst b/Documentation/arm/omap/index.rst deleted file mode 100644 index 8b365b212e49..000000000000 --- a/Documentation/arm/omap/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -======= -TI OMAP -======= - -.. toctree:: - :maxdepth: 1 - - omap - omap_pm - dss diff --git a/Documentation/arm/omap/omap.rst b/Documentation/arm/omap/omap.rst deleted file mode 100644 index f440c0f4613f..000000000000 --- a/Documentation/arm/omap/omap.rst +++ /dev/null @@ -1,18 +0,0 @@ -============ -OMAP history -============ - -This file contains documentation for running mainline -kernel on omaps. - -====== ====================================================== -KERNEL NEW DEPENDENCIES -====== ====================================================== -v4.3+ Update is needed for custom .config files to make sure - CONFIG_REGULATOR_PBIAS is enabled for MMC1 to work - properly. - -v4.18+ Update is needed for custom .config files to make sure - CONFIG_MMC_SDHCI_OMAP is enabled for all MMC instances - to work in DRA7 and K2G based boards. -====== ====================================================== diff --git a/Documentation/arm/omap/omap_pm.rst b/Documentation/arm/omap/omap_pm.rst deleted file mode 100644 index a335e4c8ce2c..000000000000 --- a/Documentation/arm/omap/omap_pm.rst +++ /dev/null @@ -1,165 +0,0 @@ -===================== -The OMAP PM interface -===================== - -This document describes the temporary OMAP PM interface. Driver -authors use these functions to communicate minimum latency or -throughput constraints to the kernel power management code. -Over time, the intention is to merge features from the OMAP PM -interface into the Linux PM QoS code. - -Drivers need to express PM parameters which: - -- support the range of power management parameters present in the TI SRF; - -- separate the drivers from the underlying PM parameter - implementation, whether it is the TI SRF or Linux PM QoS or Linux - latency framework or something else; - -- specify PM parameters in terms of fundamental units, such as - latency and throughput, rather than units which are specific to OMAP - or to particular OMAP variants; - -- allow drivers which are shared with other architectures (e.g., - DaVinci) to add these constraints in a way which won't affect non-OMAP - systems, - -- can be implemented immediately with minimal disruption of other - architectures. - - -This document proposes the OMAP PM interface, including the following -five power management functions for driver code: - -1. Set the maximum MPU wakeup latency:: - - (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t) - -2. Set the maximum device wakeup latency:: - - (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) - -3. Set the maximum system DMA transfer start latency (CORE pwrdm):: - - (*pdata->set_max_sdma_lat)(struct device *dev, long t) - -4. Set the minimum bus throughput needed by a device:: - - (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r) - -5. Return the number of times the device has lost context:: - - (*pdata->get_dev_context_loss_count)(struct device *dev) - - -Further documentation for all OMAP PM interface functions can be -found in arch/arm/plat-omap/include/mach/omap-pm.h. - - -The OMAP PM layer is intended to be temporary ---------------------------------------------- - -The intention is that eventually the Linux PM QoS layer should support -the range of power management features present in OMAP3. As this -happens, existing drivers using the OMAP PM interface can be modified -to use the Linux PM QoS code; and the OMAP PM interface can disappear. - - -Driver usage of the OMAP PM functions -------------------------------------- - -As the 'pdata' in the above examples indicates, these functions are -exposed to drivers through function pointers in driver .platform_data -structures. The function pointers are initialized by the `board-*.c` -files to point to the corresponding OMAP PM functions: - -- set_max_dev_wakeup_lat will point to - omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do - not support these functions should leave these function pointers set - to NULL. Drivers should use the following idiom:: - - if (pdata->set_max_dev_wakeup_lat) - (*pdata->set_max_dev_wakeup_lat)(dev, t); - -The most common usage of these functions will probably be to specify -the maximum time from when an interrupt occurs, to when the device -becomes accessible. To accomplish this, driver writers should use the -set_max_mpu_wakeup_lat() function to constrain the MPU wakeup -latency, and the set_max_dev_wakeup_lat() function to constrain the -device wakeup latency (from clk_enable() to accessibility). For -example:: - - /* Limit MPU wakeup latency */ - if (pdata->set_max_mpu_wakeup_lat) - (*pdata->set_max_mpu_wakeup_lat)(dev, tc); - - /* Limit device powerdomain wakeup latency */ - if (pdata->set_max_dev_wakeup_lat) - (*pdata->set_max_dev_wakeup_lat)(dev, td); - - /* total wakeup latency in this example: (tc + td) */ - -The PM parameters can be overwritten by calling the function again -with the new value. The settings can be removed by calling the -function with a t argument of -1 (except in the case of -set_max_bus_tput(), which should be called with an r argument of 0). - -The fifth function above, omap_pm_get_dev_context_loss_count(), -is intended as an optimization to allow drivers to determine whether the -device has lost its internal context. If context has been lost, the -driver must restore its internal context before proceeding. - - -Other specialized interface functions -------------------------------------- - -The five functions listed above are intended to be usable by any -device driver. DSPBridge and CPUFreq have a few special requirements. -DSPBridge expresses target DSP performance levels in terms of OPP IDs. -CPUFreq expresses target MPU performance levels in terms of MPU -frequency. The OMAP PM interface contains functions for these -specialized cases to convert that input information (OPPs/MPU -frequency) into the form that the underlying power management -implementation needs: - -6. `(*pdata->dsp_get_opp_table)(void)` - -7. `(*pdata->dsp_set_min_opp)(u8 opp_id)` - -8. `(*pdata->dsp_get_opp)(void)` - -9. `(*pdata->cpu_get_freq_table)(void)` - -10. `(*pdata->cpu_set_freq)(unsigned long f)` - -11. `(*pdata->cpu_get_freq)(void)` - -Customizing OPP for platform -============================ -Defining CONFIG_PM should enable OPP layer for the silicon -and the registration of OPP table should take place automatically. -However, in special cases, the default OPP table may need to be -tweaked, for e.g.: - - * enable default OPPs which are disabled by default, but which - could be enabled on a platform - * Disable an unsupported OPP on the platform - * Define and add a custom opp table entry - in these cases, the board file needs to do additional steps as follows: - -arch/arm/mach-omapx/board-xyz.c:: - - #include "pm.h" - .... - static void __init omap_xyz_init_irq(void) - { - .... - /* Initialize the default table */ - omapx_opp_init(); - /* Do customization to the defaults */ - .... - } - -NOTE: - omapx_opp_init will be omap3_opp_init or as required - based on the omap family. |