diff options
Diffstat (limited to 'Documentation/DocBook')
26 files changed, 3181 insertions, 290 deletions
diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl index 044b76436e8..d9b9416c989 100644 --- a/Documentation/DocBook/80211.tmpl +++ b/Documentation/DocBook/80211.tmpl @@ -100,6 +100,7 @@ !Finclude/net/cfg80211.h wdev_priv !Finclude/net/cfg80211.h ieee80211_iface_limit !Finclude/net/cfg80211.h ieee80211_iface_combination +!Finclude/net/cfg80211.h cfg80211_check_combinations </chapter> <chapter> <title>Actions and configuration</title> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 8d96ebf524e..bec06659e0e 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,9 +14,10 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml drm.xml media_api.xml w1.xml + tracepoint.xml drm.xml media_api.xml w1.xml \ + writing_musb_glue_layer.xml -include $(srctree)/Documentation/DocBook/media/Makefile +include Documentation/DocBook/media/Makefile ### # The build process is as follows (targets): @@ -36,6 +37,7 @@ PS_METHOD = $(prefer-db2x) # The targets that may be used. PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs +targets += $(DOCBOOKS) BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) xmldocs: $(BOOKS) sgmldocs: xmldocs @@ -58,14 +60,14 @@ mandocs: $(MAN) installmandocs: mandocs mkdir -p /usr/local/man/man9/ - install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ + install $(obj)/man/*.9.gz /usr/local/man/man9/ ### #External programs used KERNELDOC = $(srctree)/scripts/kernel-doc DOCPROC = $(objtree)/scripts/docproc -XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl +XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl XMLTOFLAGS += --skip-validation ### @@ -87,21 +89,9 @@ define rule_docproc ) > $(dir $@).$(notdir $@).cmd endef -%.xml: %.tmpl FORCE +%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE $(call if_changed_rule,docproc) -### -#Read in all saved dependency files -cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd)) - -ifneq ($(cmd_files),) - include $(cmd_files) -endif - -### -# Changes in kernel-doc force a rebuild of all documentation -$(BOOKS): $(KERNELDOC) - # Tell kbuild to always build the programs always := $(hostprogs-y) @@ -139,7 +129,7 @@ quiet_cmd_db2pdf = PDF $@ index = index.html -main_idx = Documentation/DocBook/$(index) +main_idx = $(obj)/$(index) build_main_index = rm -rf $(main_idx); \ echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ @@ -148,7 +138,7 @@ build_main_index = rm -rf $(main_idx); \ quiet_cmd_db2html = HTML $@ cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ - $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ + $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ %.html: %.xml @(which xmlto > /dev/null 2>&1) || \ diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index f5170082bdb..cc63f30de16 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -276,7 +276,7 @@ X!Isound/sound_firmware.c </para> <sect1><title>Frame Buffer Memory</title> -!Edrivers/video/fbmem.c +!Edrivers/video/fbdev/core/fbmem.c </sect1> <!-- <sect1><title>Frame Buffer Console</title> @@ -284,7 +284,7 @@ X!Edrivers/video/console/fbcon.c </sect1> --> <sect1><title>Frame Buffer Colormap</title> -!Edrivers/video/fbcmap.c +!Edrivers/video/fbdev/core/fbcmap.c </sect1> <!-- FIXME: drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment @@ -294,11 +294,11 @@ X!Idrivers/video/fbgen.c </sect1> KAO --> <sect1><title>Frame Buffer Video Mode Database</title> -!Idrivers/video/modedb.c -!Edrivers/video/modedb.c +!Idrivers/video/fbdev/core/modedb.c +!Edrivers/video/fbdev/core/modedb.c </sect1> <sect1><title>Frame Buffer Macintosh Video Mode Database</title> -!Edrivers/video/macmodes.c +!Edrivers/video/fbdev/macmodes.c </sect1> <sect1><title>Frame Buffer Fonts</title> <para> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ed1d6d28902..7df3134ebc0 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -29,12 +29,26 @@ </address> </affiliation> </author> + <author> + <firstname>Daniel</firstname> + <surname>Vetter</surname> + <contrib>Contributions all over the place</contrib> + <affiliation> + <orgname>Intel Corporation</orgname> + <address> + <email>daniel.vetter@ffwll.ch</email> + </address> + </affiliation> + </author> </authorgroup> <copyright> <year>2008-2009</year> - <year>2012</year> + <year>2013-2014</year> <holder>Intel Corporation</holder> + </copyright> + <copyright> + <year>2012</year> <holder>Laurent Pinchart</holder> </copyright> @@ -60,7 +74,15 @@ <toc></toc> - <!-- Introduction --> +<part id="drmCore"> + <title>DRM Core</title> + <partintro> + <para> + This first part of the DRM Developer's Guide documents core DRM code, + helper libraries for writing drivers and generic userspace interfaces + exposed by DRM drivers. + </para> + </partintro> <chapter id="drmIntroduction"> <title>Introduction</title> @@ -120,6 +142,12 @@ to register it with the DRM subsystem. </para> <para> + Newer drivers that no longer require a <structname>drm_bus</structname> + structure can alternatively use the low-level device initialization and + registration functions such as <function>drm_dev_alloc()</function> and + <function>drm_dev_register()</function> directly. + </para> + <para> The <structname>drm_driver</structname> structure contains static information that describes the driver and features it supports, and pointers to methods that the DRM core will call to implement the DRM API. @@ -260,12 +288,42 @@ char *date;</synopsis> </sect3> </sect2> <sect2> + <title>Device Registration</title> + <para> + A number of functions are provided to help with device registration. + The functions deal with PCI, USB and platform devices, respectively. + </para> +!Edrivers/gpu/drm/drm_pci.c +!Edrivers/gpu/drm/drm_usb.c +!Edrivers/gpu/drm/drm_platform.c + <para> + New drivers that no longer rely on the services provided by the + <structname>drm_bus</structname> structure can call the low-level + device registration functions directly. The + <function>drm_dev_alloc()</function> function can be used to allocate + and initialize a new <structname>drm_device</structname> structure. + Drivers will typically want to perform some additional setup on this + structure, such as allocating driver-specific data and storing a + pointer to it in the DRM device's <structfield>dev_private</structfield> + field. Drivers should also set the device's unique name using the + <function>drm_dev_set_unique()</function> function. After it has been + set up a device can be registered with the DRM subsystem by calling + <function>drm_dev_register()</function>. This will cause the device to + be exposed to userspace and will call the driver's + <structfield>.load()</structfield> implementation. When a device is + removed, the DRM device can safely be unregistered and freed by calling + <function>drm_dev_unregister()</function> followed by a call to + <function>drm_dev_unref()</function>. + </para> +!Edrivers/gpu/drm/drm_stub.c + </sect2> + <sect2> <title>Driver Load</title> <para> The <methodname>load</methodname> method is the driver and device initialization entry point. The method is responsible for allocating and - initializing driver private data, specifying supported performance - counters, performing resource allocation and mapping (e.g. acquiring + initializing driver private data, performing resource allocation and + mapping (e.g. acquiring clocks, mapping registers or allocating command buffers), initializing the memory manager (<xref linkend="drm-memory-management"/>), installing the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up @@ -295,7 +353,7 @@ char *date;</synopsis> their <methodname>load</methodname> method called with flags to 0. </para> <sect3> - <title>Driver Private & Performance Counters</title> + <title>Driver Private Data</title> <para> The driver private hangs off the main <structname>drm_device</structname> structure and can be used for @@ -307,14 +365,6 @@ char *date;</synopsis> <structname>drm_device</structname>.<structfield>dev_priv</structfield> set to NULL when the driver is unloaded. </para> - <para> - DRM supports several counters which were used for rough performance - characterization. This stat counter system is deprecated and should not - be used. If performance monitoring is desired, the developer should - investigate and potentially enhance the kernel perf and tracing - infrastructure to export GPU related performance information for - consumption by performance monitoring tools and applications. - </para> </sect3> <sect3 id="drm-irq-registration"> <title>IRQ Registration</title> @@ -328,21 +378,13 @@ char *date;</synopsis> <sect4> <title>Managed IRQ Registration</title> <para> - Both the <function>drm_irq_install</function> and - <function>drm_irq_uninstall</function> functions get the device IRQ by - calling <function>drm_dev_to_irq</function>. This inline function will - call a bus-specific operation to retrieve the IRQ number. For platform - devices, <function>platform_get_irq</function>(..., 0) is used to - retrieve the IRQ number. - </para> - <para> <function>drm_irq_install</function> starts by calling the <methodname>irq_preinstall</methodname> driver operation. The operation is optional and must make sure that the interrupt will not get fired by clearing all pending interrupt flags or disabling the interrupt. </para> <para> - The IRQ will then be requested by a call to + The passed-in IRQ will then be requested by a call to <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver feature flag is set, a shared (IRQF_SHARED) IRQ handler will be requested. @@ -445,7 +487,7 @@ char *date;</synopsis> providing a solution to every graphics memory-related problems, GEM identified common code between drivers and created a support library to share it. GEM has simpler initialization and execution requirements than - TTM, but has no video RAM management capabitilies and is thus limited to + TTM, but has no video RAM management capabilities and is thus limited to UMA devices. </para> <sect2> @@ -697,55 +739,16 @@ char *date;</synopsis> respectively. The conversion is handled by the DRM core without any driver-specific support. </para> - <para> - Similar to global names, GEM file descriptors are also used to share GEM - objects across processes. They offer additional security: as file - descriptors must be explicitly sent over UNIX domain sockets to be shared - between applications, they can't be guessed like the globally unique GEM - names. - </para> - <para> - Drivers that support GEM file descriptors, also known as the DRM PRIME - API, must set the DRIVER_PRIME bit in the struct - <structname>drm_driver</structname> - <structfield>driver_features</structfield> field, and implement the - <methodname>prime_handle_to_fd</methodname> and - <methodname>prime_fd_to_handle</methodname> operations. - </para> - <para> - <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, - struct drm_file *file_priv, uint32_t handle, - uint32_t flags, int *prime_fd); - int (*prime_fd_to_handle)(struct drm_device *dev, - struct drm_file *file_priv, int prime_fd, - uint32_t *handle);</synopsis> - Those two operations convert a handle to a PRIME file descriptor and - vice versa. Drivers must use the kernel dma-buf buffer sharing framework - to manage the PRIME file descriptors. - </para> - <para> - While non-GEM drivers must implement the operations themselves, GEM - drivers must use the <function>drm_gem_prime_handle_to_fd</function> - and <function>drm_gem_prime_fd_to_handle</function> helper functions. - Those helpers rely on the driver - <methodname>gem_prime_export</methodname> and - <methodname>gem_prime_import</methodname> operations to create a dma-buf - instance from a GEM object (dma-buf exporter role) and to create a GEM - object from a dma-buf instance (dma-buf importer role). - </para> - <para> - <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, - struct drm_gem_object *obj, - int flags); - struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, - struct dma_buf *dma_buf);</synopsis> - These two operations are mandatory for GEM drivers that support DRM - PRIME. - </para> - <sect4> - <title>DRM PRIME Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers - </sect4> + <para> + GEM also supports buffer sharing with dma-buf file descriptors through + PRIME. GEM-based drivers must use the provided helpers functions to + implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. + Since sharing file descriptors is inherently more secure than the + easily guessable and global GEM names it is the preferred buffer + sharing mechanism. Sharing buffers through GEM names is only supported + for legacy userspace. Furthermore PRIME also allows cross-device + buffer sharing since it is based on dma-bufs. + </para> </sect3> <sect3 id="drm-gem-objects-mapping"> <title>GEM Objects Mapping</title> @@ -830,62 +833,6 @@ char *date;</synopsis> </para> </sect3> <sect3> - <title>Dumb GEM Objects</title> - <para> - The GEM API doesn't standardize GEM objects creation and leaves it to - driver-specific ioctls. While not an issue for full-fledged graphics - stacks that include device-specific userspace components (in libdrm for - instance), this limit makes DRM-based early boot graphics unnecessarily - complex. - </para> - <para> - Dumb GEM objects partly alleviate the problem by providing a standard - API to create dumb buffers suitable for scanout, which can then be used - to create KMS frame buffers. - </para> - <para> - To support dumb GEM objects drivers must implement the - <methodname>dumb_create</methodname>, - <methodname>dumb_destroy</methodname> and - <methodname>dumb_map_offset</methodname> operations. - </para> - <itemizedlist> - <listitem> - <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, - struct drm_mode_create_dumb *args);</synopsis> - <para> - The <methodname>dumb_create</methodname> operation creates a GEM - object suitable for scanout based on the width, height and depth - from the struct <structname>drm_mode_create_dumb</structname> - argument. It fills the argument's <structfield>handle</structfield>, - <structfield>pitch</structfield> and <structfield>size</structfield> - fields with a handle for the newly created GEM object and its line - pitch and size in bytes. - </para> - </listitem> - <listitem> - <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle);</synopsis> - <para> - The <methodname>dumb_destroy</methodname> operation destroys a dumb - GEM object created by <methodname>dumb_create</methodname>. - </para> - </listitem> - <listitem> - <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle, uint64_t *offset);</synopsis> - <para> - The <methodname>dumb_map_offset</methodname> operation associates an - mmap fake offset with the GEM object given by the handle and returns - it. Drivers must use the - <function>drm_gem_create_mmap_offset</function> function to - associate the fake offset as described in - <xref linkend="drm-gem-objects-mapping"/>. - </para> - </listitem> - </itemizedlist> - </sect3> - <sect3> <title>Memory Coherency</title> <para> When mapped to the device or used in a command buffer, backing pages @@ -924,7 +871,99 @@ char *date;</synopsis> abstracted from the client in libdrm. </para> </sect3> - </sect2> + <sect3> + <title>GEM Function Reference</title> +!Edrivers/gpu/drm/drm_gem.c + </sect3> + </sect2> + <sect2> + <title>VMA Offset Manager</title> +!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager +!Edrivers/gpu/drm/drm_vma_manager.c +!Iinclude/drm/drm_vma_manager.h + </sect2> + <sect2 id="drm-prime-support"> + <title>PRIME Buffer Sharing</title> + <para> + PRIME is the cross device buffer sharing framework in drm, originally + created for the OPTIMUS range of multi-gpu platforms. To userspace + PRIME buffers are dma-buf based file descriptors. + </para> + <sect3> + <title>Overview and Driver Interface</title> + <para> + Similar to GEM global names, PRIME file descriptors are + also used to share buffer objects across processes. They offer + additional security: as file descriptors must be explicitly sent over + UNIX domain sockets to be shared between applications, they can't be + guessed like the globally unique GEM names. + </para> + <para> + Drivers that support the PRIME + API must set the DRIVER_PRIME bit in the struct + <structname>drm_driver</structname> + <structfield>driver_features</structfield> field, and implement the + <methodname>prime_handle_to_fd</methodname> and + <methodname>prime_fd_to_handle</methodname> operations. + </para> + <para> + <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd); +int (*prime_fd_to_handle)(struct drm_device *dev, + struct drm_file *file_priv, int prime_fd, + uint32_t *handle);</synopsis> + Those two operations convert a handle to a PRIME file descriptor and + vice versa. Drivers must use the kernel dma-buf buffer sharing framework + to manage the PRIME file descriptors. Similar to the mode setting + API PRIME is agnostic to the underlying buffer object manager, as + long as handles are 32bit unsigned integers. + </para> + <para> + While non-GEM drivers must implement the operations themselves, GEM + drivers must use the <function>drm_gem_prime_handle_to_fd</function> + and <function>drm_gem_prime_fd_to_handle</function> helper functions. + Those helpers rely on the driver + <methodname>gem_prime_export</methodname> and + <methodname>gem_prime_import</methodname> operations to create a dma-buf + instance from a GEM object (dma-buf exporter role) and to create a GEM + object from a dma-buf instance (dma-buf importer role). + </para> + <para> + <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, + struct drm_gem_object *obj, + int flags); +struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, + struct dma_buf *dma_buf);</synopsis> + These two operations are mandatory for GEM drivers that support + PRIME. + </para> + </sect3> + <sect3> + <title>PRIME Helper Functions</title> +!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + </sect3> + </sect2> + <sect2> + <title>PRIME Function References</title> +!Edrivers/gpu/drm/drm_prime.c + </sect2> + <sect2> + <title>DRM MM Range Allocator</title> + <sect3> + <title>Overview</title> +!Pdrivers/gpu/drm/drm_mm.c Overview + </sect3> + <sect3> + <title>LRU Scan/Eviction Support</title> +!Pdrivers/gpu/drm/drm_mm.c lru scan roaster + </sect3> + </sect2> + <sect2> + <title>DRM MM Range Allocator Function References</title> +!Edrivers/gpu/drm/drm_mm.c +!Iinclude/drm/drm_mm.h + </sect2> </sect1> <!-- Internals: mode setting --> @@ -953,6 +992,11 @@ int max_width, max_height;</synopsis> </listitem> </itemizedlist> <sect2> + <title>Display Modes Function Reference</title> +!Iinclude/drm/drm_modes.h +!Edrivers/gpu/drm/drm_modes.c + </sect2> + <sect2> <title>Frame Buffer Creation</title> <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, struct drm_file *file_priv, @@ -968,9 +1012,11 @@ int max_width, max_height;</synopsis> Frame buffers rely on the underneath memory manager for low-level memory operations. When creating a frame buffer applications pass a memory handle (or a list of memory handles for multi-planar formats) through - the <parameter>drm_mode_fb_cmd2</parameter> argument. This document - assumes that the driver uses GEM, those handles thus reference GEM - objects. + the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using + GEM as their userspace buffer management interface this would be a GEM + handle. Drivers are however free to use their own backing storage object + handles, e.g. vmwgfx directly exposes special TTM handles to userspace + and so expects TTM handles in the create ioctl and not GEM handles. </para> <para> Drivers must first validate the requested frame buffer parameters passed @@ -992,7 +1038,7 @@ int max_width, max_height;</synopsis> </para> <para> - The initailization of the new framebuffer instance is finalized with a + The initialization of the new framebuffer instance is finalized with a call to <function>drm_framebuffer_init</function> which takes a pointer to DRM frame buffer operations (struct <structname>drm_framebuffer_funcs</structname>). Note that this function @@ -1042,7 +1088,7 @@ int max_width, max_height;</synopsis> <para> The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with - <function>drm_framebuffer_reference</function> </para> and drop them + <function>drm_framebuffer_reference</function>and drop them again with <function>drm_framebuffer_unreference</function>. For driver-private framebuffers for which the last reference is never dropped (e.g. for the fbdev framebuffer when the struct @@ -1050,6 +1096,72 @@ int max_width, max_height;</synopsis> helper struct) drivers can manually clean up a framebuffer at module unload time with <function>drm_framebuffer_unregister_private</function>. + </para> + </sect2> + <sect2> + <title>Dumb Buffer Objects</title> + <para> + The KMS API doesn't standardize backing storage object creation and + leaves it to driver-specific ioctls. Furthermore actually creating a + buffer object even for GEM-based drivers is done through a + driver-specific ioctl - GEM only has a common userspace interface for + sharing and destroying objects. While not an issue for full-fledged + graphics stacks that include device-specific userspace components (in + libdrm for instance), this limit makes DRM-based early boot graphics + unnecessarily complex. + </para> + <para> + Dumb objects partly alleviate the problem by providing a standard + API to create dumb buffers suitable for scanout, which can then be used + to create KMS frame buffers. + </para> + <para> + To support dumb objects drivers must implement the + <methodname>dumb_create</methodname>, + <methodname>dumb_destroy</methodname> and + <methodname>dumb_map_offset</methodname> operations. + </para> + <itemizedlist> + <listitem> + <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, + struct drm_mode_create_dumb *args);</synopsis> + <para> + The <methodname>dumb_create</methodname> operation creates a driver + object (GEM or TTM handle) suitable for scanout based on the + width, height and depth from the struct + <structname>drm_mode_create_dumb</structname> argument. It fills the + argument's <structfield>handle</structfield>, + <structfield>pitch</structfield> and <structfield>size</structfield> + fields with a handle for the newly created object and its line + pitch and size in bytes. + </para> + </listitem> + <listitem> + <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle);</synopsis> + <para> + The <methodname>dumb_destroy</methodname> operation destroys a dumb + object created by <methodname>dumb_create</methodname>. + </para> + </listitem> + <listitem> + <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle, uint64_t *offset);</synopsis> + <para> + The <methodname>dumb_map_offset</methodname> operation associates an + mmap fake offset with the object given by the handle and returns + it. Drivers must use the + <function>drm_gem_create_mmap_offset</function> function to + associate the fake offset as described in + <xref linkend="drm-gem-objects-mapping"/>. + </para> + </listitem> + </itemizedlist> + <para> + Note that dumb objects may not be used for gpu acceleration, as has been + attempted on some ARM embedded platforms. Such drivers really must have + a hardware-specific ioctl to allocate suitable buffer objects. + </para> </sect2> <sect2> <title>Output Polling</title> @@ -1110,7 +1222,7 @@ int max_width, max_height;</synopsis> pointer to CRTC functions. </para> </sect3> - <sect3> + <sect3 id="drm-kms-crtcops"> <title>CRTC Operations</title> <sect4> <title>Set Configuration</title> @@ -1130,8 +1242,11 @@ int max_width, max_height;</synopsis> This operation is called with the mode config lock held. </para> <note><para> - FIXME: How should set_config interact with DPMS? If the CRTC is - suspended, should it be resumed? + Note that the drm core has no notion of restoring the mode setting + state after resume, since all resume handling is in the full + responsibility of the driver. The common mode setting helper library + though provides a helper which can be used for this: + <function>drm_helper_resume_force_mode</function>. </para></note> </sect4> <sect4> @@ -1248,15 +1363,47 @@ int max_width, max_height;</synopsis> optionally scale it to a destination size. The result is then blended with or overlayed on top of a CRTC. </para> + <para> + The DRM core recognizes three types of planes: + <itemizedlist> + <listitem> + DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary + planes are the planes operated upon by by CRTC modesetting and flipping + operations described in <xref linkend="drm-kms-crtcops"/>. + </listitem> + <listitem> + DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor + planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and + DRM_IOCTL_MODE_CURSOR2 ioctls. + </listitem> + <listitem> + DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. + Some drivers refer to these types of planes as "sprites" internally. + </listitem> + </itemizedlist> + For compatibility with legacy userspace, only overlay planes are made + available to userspace by default. Userspace clients may set the + DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that + they wish to receive a universal plane list containing all plane types. + </para> <sect3> <title>Plane Initialization</title> <para> - Planes are optional. To create a plane, a KMS drivers allocates and + To create a plane, a KMS drivers allocates and zeroes an instances of struct <structname>drm_plane</structname> (possibly as part of a larger structure) and registers it with a call - to <function>drm_plane_init</function>. The function takes a bitmask + to <function>drm_universal_plane_init</function>. The function takes a bitmask of the CRTCs that can be associated with the plane, a pointer to the - plane functions and a list of format supported formats. + plane functions, a list of format supported formats, and the type of + plane (primary, cursor, or overlay) being initialized. + </para> + <para> + Cursor and overlay planes are optional. All drivers should provide + one primary plane per CRTC (although this requirement may change in + the future); drivers that do not wish to provide special handling for + primary planes may make use of the helper functions described in + <xref linkend="drm-kms-planehelpers"/> to create and register a + primary plane with standard capabilities. </para> </sect3> <sect3> @@ -1680,6 +1827,12 @@ void intel_crt_init(struct drm_device *dev) <title>KMS API Functions</title> !Edrivers/gpu/drm/drm_crtc.c </sect2> + <sect2> + <title>KMS Locking</title> +!Pdrivers/gpu/drm/drm_modeset_lock.c kms locking +!Iinclude/drm/drm_modeset_lock.h +!Edrivers/gpu/drm/drm_modeset_lock.c + </sect2> </sect1> <!-- Internals: kms helper functions --> @@ -1687,7 +1840,7 @@ void intel_crt_init(struct drm_device *dev) <sect1> <title>Mode Setting Helper Functions</title> <para> - The CRTC, encoder and connector functions provided by the drivers + The plane, CRTC, encoder and connector functions provided by the drivers implement the DRM API. They're called by the DRM core and ioctl handlers to handle device state changes and configuration request. As implementing those functions often requires logic not specific to drivers, mid-layer @@ -1695,8 +1848,8 @@ void intel_crt_init(struct drm_device *dev) </para> <para> The DRM core contains one mid-layer implementation. The mid-layer provides - implementations of several CRTC, encoder and connector functions (called - from the top of the mid-layer) that pre-process requests and call + implementations of several plane, CRTC, encoder and connector functions + (called from the top of the mid-layer) that pre-process requests and call lower-level functions provided by the driver (at the bottom of the mid-layer). For instance, the <function>drm_crtc_helper_set_config</function> function can be used to @@ -1784,8 +1937,8 @@ void intel_crt_init(struct drm_device *dev) <para> The function filters out modes larger than <parameter>max_width</parameter> and <parameter>max_height</parameter> - if specified. It then calls the connector - <methodname>mode_valid</methodname> helper operation for each mode in + if specified. It then calls the optional connector + <methodname>mode_valid</methodname> helper operation for each mode in the probed list to check whether the mode is valid for the connector. </para> </listitem> @@ -2134,7 +2287,7 @@ void intel_crt_init(struct drm_device *dev) set the <structfield>display_info</structfield> <structfield>width_mm</structfield> and <structfield>height_mm</structfield> fields if they haven't been set - already (for instance at initilization time when a fixed-size panel is + already (for instance at initialization time when a fixed-size panel is attached to the connector). The mode <structfield>width_mm</structfield> and <structfield>height_mm</structfield> fields are only used internally during EDID parsing and should not be set when creating modes manually. @@ -2146,7 +2299,7 @@ void intel_crt_init(struct drm_device *dev) <para> Verify whether a mode is valid for the connector. Return MODE_OK for supported modes and one of the enum drm_mode_status values (MODE_*) - for unsupported modes. This operation is mandatory. + for unsupported modes. This operation is optional. </para> <para> As the mode rejection reason is currently not used beside for @@ -2168,6 +2321,11 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_crtc_helper.c </sect2> <sect2> + <title>Output Probing Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_probe_helper.c output probing helper overview +!Edrivers/gpu/drm/drm_probe_helper.c + </sect2> + <sect2> <title>fbdev Helper Functions Reference</title> !Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers !Edrivers/gpu/drm/drm_fb_helper.c @@ -2196,10 +2354,19 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_flip_work.c </sect2> <sect2> - <title>VMA Offset Manager</title> -!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager -!Edrivers/gpu/drm/drm_vma_manager.c -!Iinclude/drm/drm_vma_manager.h + <title>HDMI Infoframes Helper Reference</title> + <para> + Strictly speaking this is not a DRM helper library but generally useable + by any driver interfacing with HDMI outputs like v4l or alsa drivers. + But it nicely fits into the overall topic of mode setting helper + libraries and hence is also included here. + </para> +!Iinclude/linux/hdmi.h +!Edrivers/video/hdmi.c + </sect2> + <sect2> + <title id="drm-kms-planehelpers">Plane Helper Reference</title> +!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers </sect2> </sect1> @@ -2223,7 +2390,7 @@ void intel_crt_init(struct drm_device *dev) first create properties and then create and associate individual instances of those properties to objects. A property can be instantiated multiple times and associated with different objects. Values are stored in property - instances, and all other property information are stored in the propery + instances, and all other property information are stored in the property and shared between all instances of the property. </para> <para> @@ -2317,6 +2484,863 @@ void intel_crt_init(struct drm_device *dev) pointer to the target object, a pointer to the previously created property and an initial instance value. </para> + <sect2> + <title>Existing KMS Properties</title> + <para> + The following table gives description of drm properties exposed by various + modules/drivers. + </para> + <table border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr style="font-weight: bold;"> + <td valign="top" >Owner Module/Drivers</td> + <td valign="top" >Group</td> + <td valign="top" >Property Name</td> + <td valign="top" >Type</td> + <td valign="top" >Property Values</td> + <td valign="top" >Object attached</td> + <td valign="top" >Description/Restrictions</td> + </tr> + <tr> + <td rowspan="20" valign="top" >DRM</td> + <td rowspan="2" valign="top" >Generic</td> + <td valign="top" >“EDID”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains id of edid blob ptr object.</td> + </tr> + <tr> + <td valign="top" >“DPMS”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains DPMS operation mode value.</td> + </tr> + <tr> + <td rowspan="1" valign="top" >Plane</td> + <td valign="top" >“type”</td> + <td valign="top" >ENUM | IMMUTABLE</td> + <td valign="top" >{ "Overlay", "Primary", "Cursor" }</td> + <td valign="top" >Plane</td> + <td valign="top" >Plane type</td> + </tr> + <tr> + <td rowspan="2" valign="top" >DVI-I</td> + <td valign="top" >“subconnector”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“select subconnector”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="13" valign="top" >TV</td> + <td valign="top" >“subconnector”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“select subconnector”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“left margin”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“right margin”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“top margin”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“bottom margin”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“brightness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“contrast”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker reduction”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“overscan”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“saturation”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“hue”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="2" valign="top" >Optional</td> + <td valign="top" >“scaling mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“dirty”</td> + <td valign="top" >ENUM | IMMUTABLE</td> + <td valign="top" >{ "Off", "On", "Annotate" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="21" valign="top" >i915</td> + <td rowspan="3" valign="top" >Generic</td> + <td valign="top" >"Broadcast RGB"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“audio”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "force-dvi", "off", "auto", "on" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Standard name as in DRM</td> + <td valign="top" >Standard type as in DRM</td> + <td valign="top" >Standard value as in DRM</td> + <td valign="top" >Standard Object as in DRM</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="17" valign="top" >SDVO-TV</td> + <td valign="top" >“mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"left_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"right_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"top_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"bottom_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“hpos”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“vpos”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“contrast”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“saturation”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“hue”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“sharpness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker_filter”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker_filter_adaptive”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker_filter_2d”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“tv_chroma_filter”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“tv_luma_filter”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“dot_crawl”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >SDVO-TV/LVDS</td> + <td valign="top" >“brightness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="3" valign="top" >CDV gma-500</td> + <td rowspan="3" valign="top" >Generic</td> + <td valign="top" >"Broadcast RGB"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ “Full”, “Limited 16:235” }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"Broadcast RGB"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ “off”, “auto”, “on” }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Standard name as in DRM</td> + <td valign="top" >Standard type as in DRM</td> + <td valign="top" >Standard value as in DRM</td> + <td valign="top" >Standard Object as in DRM</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="20" valign="top" >Poulsbo</td> + <td rowspan="2" valign="top" >Generic</td> + <td valign="top" >“backlight”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=100</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Standard name as in DRM</td> + <td valign="top" >Standard type as in DRM</td> + <td valign="top" >Standard value as in DRM</td> + <td valign="top" >Standard Object as in DRM</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="17" valign="top" >SDVO-TV</td> + <td valign="top" >“mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"left_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"right_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"top_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"bottom_margin"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“hpos”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“vpos”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“contrast”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“saturation”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“hue”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“sharpness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker_filter”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker_filter_adaptive”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“flicker_filter_2d”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“tv_chroma_filter”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“tv_luma_filter”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“dot_crawl”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >SDVO-TV/LVDS</td> + <td valign="top" >“brightness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max= SDVO dependent</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="11" valign="top" >armada</td> + <td rowspan="2" valign="top" >CRTC</td> + <td valign="top" >"CSC_YUV"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td> + <td valign="top" >CRTC</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"CSC_RGB"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "Auto", "Computer system", "Studio" }</td> + <td valign="top" >CRTC</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="9" valign="top" >Overlay</td> + <td valign="top" >"colorkey"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"colorkey_min"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"colorkey_max"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"colorkey_val"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"colorkey_alpha"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"colorkey_mode"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "disabled", "Y component", "U component" + , "V component", "RGB", “R component", "G component", "B component" }</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"brightness"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=256 + 255</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"contrast"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0x7fff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"saturation"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0x7fff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="2" valign="top" >exynos</td> + <td valign="top" >CRTC</td> + <td valign="top" >“mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "normal", "blank" }</td> + <td valign="top" >CRTC</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Overlay</td> + <td valign="top" >“zpos”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=MAX_PLANE-1</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="3" valign="top" >i2c/ch7006_drv</td> + <td valign="top" >Generic</td> + <td valign="top" >“scale”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=2</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="2" valign="top" >TV</td> + <td valign="top" >Standard names as in DRM</td> + <td valign="top" >Standard types as in DRM</td> + <td valign="top" >Standard Values as in DRM</td> + <td valign="top" >Standard object as in DRM</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc" + , "PAL-60", "NTSC-M", "NTSC-J" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="16" valign="top" >nouveau</td> + <td rowspan="6" valign="top" >NV10 Overlay</td> + <td valign="top" >"colorkey"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0x01ffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“contrast”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=8192-1</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“brightness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1024</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“hue”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=359</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“saturation”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=8192-1</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“iturbt_709”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="2" valign="top" >Nv04 Overlay</td> + <td valign="top" >“colorkey”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0x01ffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“brightness”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1024</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="7" valign="top" >Display</td> + <td valign="top" >“dithering mode”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "auto", "off", "on" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“dithering depth”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“underscan”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“underscan hborder”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=128</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“underscan vborder”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=128</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“vibrant hue”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=180</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“color vibrance”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=200</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Generic</td> + <td valign="top" >Standard name as in DRM</td> + <td valign="top" >Standard type as in DRM</td> + <td valign="top" >Standard value as in DRM</td> + <td valign="top" >Standard Object as in DRM</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="2" valign="top" >omap</td> + <td rowspan="2" valign="top" >Generic</td> + <td valign="top" >“rotation”</td> + <td valign="top" >BITMASK</td> + <td valign="top" >{ 0, "rotate-0" }, + { 1, "rotate-90" }, + { 2, "rotate-180" }, + { 3, "rotate-270" }, + { 4, "reflect-x" }, + { 5, "reflect-y" }</td> + <td valign="top" >CRTC, Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >“zorder”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=3</td> + <td valign="top" >CRTC, Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >qxl</td> + <td valign="top" >Generic</td> + <td valign="top" >“hotplug_mode_update"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="10" valign="top" >radeon</td> + <td valign="top" >DVI-I</td> + <td valign="top" >“coherent”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >DAC enable load detect</td> + <td valign="top" >“load detection”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=1</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >TV Standard</td> + <td valign="top" >"tv standard"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j" + , "scart-pal", "pal-cn", "secam" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >legacy TMDS PLL detect</td> + <td valign="top" >"tmds_pll"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "driver", "bios" }</td> + <td valign="top" >-</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="3" valign="top" >Underscan</td> + <td valign="top" >"underscan"</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "off", "on", "auto" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"underscan hborder"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=128</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"underscan vborder"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=128</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Audio</td> + <td valign="top" >“audio”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "off", "on", "auto" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >FMT Dithering</td> + <td valign="top" >“dither”</td> + <td valign="top" >ENUM</td> + <td valign="top" >{ "off", "on" }</td> + <td valign="top" >Connector</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >Generic</td> + <td valign="top" >Standard name as in DRM</td> + <td valign="top" >Standard type as in DRM</td> + <td valign="top" >Standard value as in DRM</td> + <td valign="top" >Standard Object as in DRM</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td rowspan="3" valign="top" >rcar-du</td> + <td rowspan="3" valign="top" >Generic</td> + <td valign="top" >"alpha"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=255</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"colorkey"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0x01ffffff</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + <tr> + <td valign="top" >"zpos"</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=1, Max=7</td> + <td valign="top" >Plane</td> + <td valign="top" >TBD</td> + </tr> + </tbody> + </table> + </sect2> </sect1> <!-- Internals: vertical blanking --> @@ -2394,6 +3418,10 @@ void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis> with a call to <function>drm_vblank_cleanup</function> in the driver <methodname>unload</methodname> operation handler. </para> + <sect2> + <title>Vertical Blanking and Interrupt Handling Functions Reference</title> +!Edrivers/gpu/drm/drm_irq.c + </sect2> </sect1> <!-- Internals: open/close, file operations and ioctls --> @@ -2561,42 +3589,44 @@ int num_ioctls;</synopsis> </para> </sect2> </sect1> - <sect1> - <title>Command submission & fencing</title> + <title>Legacy Support Code</title> <para> - This should cover a few device-specific command submission - implementations. + The section very briefly covers some of the old legacy support code which + is only used by old DRM drivers which have done a so-called shadow-attach + to the underlying device instead of registering as a real driver. This + also includes some of the old generic buffer management and command + submission code. Do not use any of this in new and modern drivers. </para> - </sect1> - <!-- Internals: suspend/resume --> - - <sect1> - <title>Suspend/Resume</title> - <para> - The DRM core provides some suspend/resume code, but drivers wanting full - suspend/resume support should provide save() and restore() functions. - These are called at suspend, hibernate, or resume time, and should perform - any state save or restore required by your device across suspend or - hibernate states. - </para> - <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); -int (*resume) (struct drm_device *);</synopsis> - <para> - Those are legacy suspend and resume methods. New driver should use the - power management interface provided by their bus type (usually through - the struct <structname>device_driver</structname> dev_pm_ops) and set - these methods to NULL. - </para> - </sect1> + <sect2> + <title>Legacy Suspend/Resume</title> + <para> + The DRM core provides some suspend/resume code, but drivers wanting full + suspend/resume support should provide save() and restore() functions. + These are called at suspend, hibernate, or resume time, and should perform + any state save or restore required by your device across suspend or + hibernate states. + </para> + <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); + int (*resume) (struct drm_device *);</synopsis> + <para> + Those are legacy suspend and resume methods which + <emphasis>only</emphasis> work with the legacy shadow-attach driver + registration functions. New driver should use the power management + interface provided by their bus type (usually through + the struct <structname>device_driver</structname> dev_pm_ops) and set + these methods to NULL. + </para> + </sect2> - <sect1> - <title>DMA services</title> - <para> - This should cover how DMA mapping etc. is supported by the core. - These functions are deprecated and should not be used. - </para> + <sect2> + <title>Legacy DMA Services</title> + <para> + This should cover how DMA mapping etc. is supported by the core. + These functions are deprecated and should not be used. + </para> + </sect2> </sect1> </chapter> @@ -2658,8 +3688,8 @@ int (*resume) (struct drm_device *);</synopsis> DRM core provides multiple character-devices for user-space to use. Depending on which device is opened, user-space can perform a different set of operations (mainly ioctls). The primary node is always created - and called <term>card<num></term>. Additionally, a currently - unused control node, called <term>controlD<num></term> is also + and called card<num>. Additionally, a currently + unused control node, called controlD<num> is also created. The primary node provides all legacy operations and historically was the only interface used by userspace. With KMS, the control node was introduced. However, the planned KMS control interface @@ -2674,21 +3704,21 @@ int (*resume) (struct drm_device *);</synopsis> nodes were introduced. Render nodes solely serve render clients, that is, no modesetting or privileged ioctls can be issued on render nodes. Only non-global rendering commands are allowed. If a driver supports - render nodes, it must advertise it via the <term>DRIVER_RENDER</term> + render nodes, it must advertise it via the DRIVER_RENDER DRM driver capability. If not supported, the primary node must be used for render clients together with the legacy drmAuth authentication procedure. </para> <para> If a driver advertises render node support, DRM core will create a - separate render node called <term>renderD<num></term>. There will + separate render node called renderD<num>. There will be one render node per device. No ioctls except PRIME-related ioctls - will be allowed on this node. Especially <term>GEM_OPEN</term> will be + will be allowed on this node. Especially GEM_OPEN will be explicitly prohibited. Render nodes are designed to avoid the buffer-leaks, which occur if clients guess the flink names or mmap offsets on the legacy interface. Additionally to this basic interface, drivers must mark their driver-dependent render-only ioctls as - <term>DRM_RENDER_ALLOW</term> so render clients can use them. Driver + DRM_RENDER_ALLOW so render clients can use them. Driver authors must be careful not to allow any privileged ioctls on render nodes. </para> @@ -2734,30 +3764,182 @@ int (*resume) (struct drm_device *);</synopsis> <term>DRM_IOCTL_MODESET_CTL</term> <listitem> <para> - This should be called by application level drivers before and - after mode setting, since on many devices the vertical blank - counter is reset at that time. Internally, the DRM snapshots - the last vblank count when the ioctl is called with the - _DRM_PRE_MODESET command, so that the counter won't go backwards - (which is dealt with when _DRM_POST_MODESET is used). + This was only used for user-mode-settind drivers around + modesetting changes to allow the kernel to update the vblank + interrupt after mode setting, since on many devices the vertical + blank counter is reset to 0 at some point during modeset. Modern + drivers should not call this any more since with kernel mode + setting it is a no-op. </para> </listitem> </varlistentry> </variablelist> -<!--!Edrivers/char/drm/drm_irq.c--> </para> </sect1> </chapter> +</part> +<part id="drmDrivers"> + <title>DRM Drivers</title> - <!-- API reference --> + <partintro> + <para> + This second part of the DRM Developer's Guide documents driver code, + implementation details and also all the driver-specific userspace + interfaces. Especially since all hardware-acceleration interfaces to + userspace are driver specific for efficiency and other reasons these + interfaces can be rather substantial. Hence every driver has its own + chapter. + </para> + </partintro> - <appendix id="drmDriverApi"> - <title>DRM Driver API</title> + <chapter id="drmI915"> + <title>drm/i915 Intel GFX Driver</title> <para> - Include auto-generated API reference here (need to reference it - from paragraphs above too). + The drm/i915 driver supports all (with the exception of some very early + models) integrated GFX chipsets with both Intel display and rendering + blocks. This excludes a set of SoC platforms with an SGX rendering unit, + those have basic support through the gma500 drm driver. </para> - </appendix> + <sect1> + <title>Display Hardware Handling</title> + <para> + This section covers everything related to the display hardware including + the mode setting infrastructure, plane, sprite and cursor handling and + display, output probing and related topics. + </para> + <sect2> + <title>Mode Setting Infrastructure</title> + <para> + The i915 driver is thus far the only DRM driver which doesn't use the + common DRM helper code to implement mode setting sequences. Thus it + has its own tailor-made infrastructure for executing a display + configuration change. + </para> + </sect2> + <sect2> + <title>Plane Configuration</title> + <para> + This section covers plane configuration and composition with the + primary plane, sprites, cursors and overlays. This includes the + infrastructure to do atomic vsync'ed updates of all this state and + also tightly coupled topics like watermark setup and computation, + framebuffer compression and panel self refresh. + </para> + </sect2> + <sect2> + <title>Output Probing</title> + <para> + This section covers output probing and related infrastructure like the + hotplug interrupt storm detection and mitigation code. Note that the + i915 driver still uses most of the common DRM helper code for output + probing, so those sections fully apply. + </para> + </sect2> + <sect2> + <title>DPIO</title> +!Pdrivers/gpu/drm/i915/i915_reg.h DPIO + <table id="dpiox2"> + <title>Dual channel PHY (VLV/CHV)</title> + <tgroup cols="8"> + <colspec colname="c0" /> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <colspec colname="c6" /> + <colspec colname="c7" /> + <spanspec spanname="ch0" namest="c0" nameend="c3" /> + <spanspec spanname="ch1" namest="c4" nameend="c7" /> + <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" /> + <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" /> + <spanspec spanname="ch1pcs01" namest="c4" nameend="c5" /> + <spanspec spanname="ch1pcs23" namest="c6" nameend="c7" /> + <thead> + <row> + <entry spanname="ch0">CH0</entry> + <entry spanname="ch1">CH1</entry> + </row> + </thead> + <tbody valign="top" align="center"> + <row> + <entry spanname="ch0">CMN/PLL/REF</entry> + <entry spanname="ch1">CMN/PLL/REF</entry> + </row> + <row> + <entry spanname="ch0pcs01">PCS01</entry> + <entry spanname="ch0pcs23">PCS23</entry> + <entry spanname="ch1pcs01">PCS01</entry> + <entry spanname="ch1pcs23">PCS23</entry> + </row> + <row> + <entry>TX0</entry> + <entry>TX1</entry> + <entry>TX2</entry> + <entry>TX3</entry> + <entry>TX0</entry> + <entry>TX1</entry> + <entry>TX2</entry> + <entry>TX3</entry> + </row> + <row> + <entry spanname="ch0">DDI0</entry> + <entry spanname="ch1">DDI1</entry> + </row> + </tbody> + </tgroup> + </table> + <table id="dpiox1"> + <title>Single channel PHY (CHV)</title> + <tgroup cols="4"> + <colspec colname="c0" /> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <spanspec spanname="ch0" namest="c0" nameend="c3" /> + <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" /> + <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" /> + <thead> + <row> + <entry spanname="ch0">CH0</entry> + </row> + </thead> + <tbody valign="top" align="center"> + <row> + <entry spanname="ch0">CMN/PLL/REF</entry> + </row> + <row> + <entry spanname="ch0pcs01">PCS01</entry> + <entry spanname="ch0pcs23">PCS23</entry> + </row> + <row> + <entry>TX0</entry> + <entry>TX1</entry> + <entry>TX2</entry> + <entry>TX3</entry> + </row> + <row> + <entry spanname="ch0">DDI2</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + <sect1> + <title>Memory Management and Command Submission</title> + <para> + This sections covers all things related to the GEM implementation in the + i915 driver. + </para> + <sect2> + <title>Batchbuffer Parsing</title> +!Pdrivers/gpu/drm/i915/i915_cmd_parser.c batch buffer command parser +!Idrivers/gpu/drm/i915/i915_cmd_parser.c + </sect2> + </sect1> + </chapter> +</part> </book> diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl index 4f676838da0..bcdfdb9a927 100644 --- a/Documentation/DocBook/filesystems.tmpl +++ b/Documentation/DocBook/filesystems.tmpl @@ -62,7 +62,7 @@ !Efs/mpage.c !Efs/namei.c !Efs/buffer.c -!Efs/bio.c +!Eblock/bio.c !Efs/seq_file.c !Efs/filesystems.c !Efs/fs-writeback.c diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index 4017f147ba2..2c425d70f7e 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -708,7 +708,7 @@ hardware level details could be very different. <para>Systems need specialized hardware support to implement OTG, notably including a special <emphasis>Mini-AB</emphasis> jack -and associated transciever to support <emphasis>Dual-Role</emphasis> +and associated transceiver to support <emphasis>Dual-Role</emphasis> operation: they can act either as a host, using the standard Linux-USB host side driver stack, diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index 46347f60335..59fb5c07754 100644 --- a/Documentation/DocBook/genericirq.tmpl +++ b/Documentation/DocBook/genericirq.tmpl @@ -182,7 +182,7 @@ <para> Each interrupt is described by an interrupt descriptor structure irq_desc. The interrupt is referenced by an 'unsigned int' numeric - value which selects the corresponding interrupt decription structure + value which selects the corresponding interrupt description structure in the descriptor structures array. The descriptor structure contains status information and pointers to the interrupt flow method and the interrupt chip structure @@ -470,7 +470,7 @@ if (desc->irq_data.chip->irq_eoi) <para> To avoid copies of identical implementations of IRQ chips the core provides a configurable generic interrupt chip - implementation. Developers should check carefuly whether the + implementation. Developers should check carefully whether the generic chip fits their needs before implementing the same functionality slightly differently themselves. </para> diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index d0758b241b2..e84f09467cd 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl @@ -671,7 +671,7 @@ printk(KERN_INFO "my ip: %pI4\n", &ipaddress); <sect1 id="routines-local-irqs"> <title><function>local_irq_save()</function>/<function>local_irq_restore()</function> - <filename class="headerfile">include/asm/system.h</filename> + <filename class="headerfile">include/linux/irqflags.h</filename> </title> <para> @@ -850,16 +850,6 @@ printk(KERN_INFO "my ip: %pI4\n", &ipaddress); <returnvalue>-ERESTARTSYS</returnvalue> if a signal is received. The <function>wait_event()</function> version ignores signals. </para> - <para> - Do not use the <function>sleep_on()</function> function family - - it is very easy to accidentally introduce races; almost certainly - one of the <function>wait_event()</function> family will do, or a - loop around <function>schedule_timeout()</function>. If you choose - to loop around <function>schedule_timeout()</function> remember - you must set the task state (with - <function>set_current_state()</function>) on each iteration to avoid - busy-looping. - </para> </sect1> diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 19f2a5a5a5b..e584ee12a1e 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -1760,7 +1760,7 @@ as it would be on UP. </para> <para> -There is a furthur optimization possible here: remember our original +There is a further optimization possible here: remember our original cache code, where there were no reference counts and the caller simply held the lock whenever using the object? This is still possible: if you hold the lock, no one can delete the object, so you don't need to diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index deb71baed32..d7fcdc5a437 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -677,7 +677,7 @@ and other resources, etc. <listitem> <para> - ATA_QCFLAG_ACTIVE is clared from qc->flags. + ATA_QCFLAG_ACTIVE is cleared from qc->flags. </para> </listitem> @@ -708,7 +708,7 @@ and other resources, etc. <listitem> <para> - qc->waiting is claread & completed (in that order). + qc->waiting is cleared & completed (in that order). </para> </listitem> @@ -1163,7 +1163,7 @@ and other resources, etc. <para> Once sense data is acquired, this type of errors can be - handled similary to other SCSI errors. Note that sense data + handled similarly to other SCSI errors. Note that sense data may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such cases, the error should be considered as an ATA bus error and diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index f9fd615427f..639e7485796 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -195,15 +195,15 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api + $(Q)-cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ $(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES) @$($(quiet)gen_xml) - @(ln -sf $(MEDIA_SRC_DIR)/v4l/*xml $(MEDIA_OBJ_DIR)/) - @(ln -sf $(MEDIA_SRC_DIR)/dvb/*xml $(MEDIA_OBJ_DIR)/) + @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/v4l/*xml $(MEDIA_OBJ_DIR)/) + @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/dvb/*xml $(MEDIA_OBJ_DIR)/) $(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 97a69bf6f3e..a086a5db7a1 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -125,7 +125,7 @@ location of the buffers in device memory can be determined with the <structfield>m.offset</structfield> and <structfield>length</structfield> returned in a &v4l2-buffer; are passed as sixth and second parameter to the <function>mmap()</function> function. When using the multi-planar API, -struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each +&v4l2-buffer; contains an array of &v4l2-plane; structures, each containing its own <structfield>m.offset</structfield> and <structfield>length</structfield>. When using the multi-planar API, every plane of every buffer has to be mapped separately, so the number of @@ -699,7 +699,12 @@ linkend="v4l2-buf-type" /></entry> buffer. It depends on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when <structfield>type</structfield> -refers to an input stream, applications when it refers to an output stream.</entry> +refers to an input stream, applications when it refers to an output stream. +If the application sets this to 0 for an output stream, then +<structfield>bytesused</structfield> will be set to the size of the +buffer (see the <structfield>length</structfield> field of this struct) by +the driver. For multiplanar formats this field is ignored and the +<structfield>planes</structfield> pointer is used instead.</entry> </row> <row> <entry>__u32</entry> @@ -861,7 +866,11 @@ should set this to 0.</entry> <entry></entry> <entry>The number of bytes occupied by data in the plane (its payload). Drivers must set this field when <structfield>type</structfield> - refers to an input stream, applications when it refers to an output stream.</entry> + refers to an input stream, applications when it refers to an output stream. + If the application sets this to 0 for an output stream, then + <structfield>bytesused</structfield> will be set to the size of the + plane (see the <structfield>length</structfield> field of this struct) + by the driver.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml index cf8548556c7..74fb394ec66 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml @@ -79,13 +79,13 @@ <entry>Entity id, set by the application.</entry> </row> <row> - <entry>struct &media-pad-desc;</entry> + <entry>&media-pad-desc;</entry> <entry>*<structfield>pads</structfield></entry> <entry>Pointer to a pads array allocated by the application. Ignored if NULL.</entry> </row> <row> - <entry>struct &media-link-desc;</entry> + <entry>&media-link-desc;</entry> <entry>*<structfield>links</structfield></entry> <entry>Pointer to a links array allocated by the application. Ignored if NULL.</entry> @@ -153,12 +153,12 @@ &cs-str; <tbody valign="top"> <row> - <entry>struct &media-pad-desc;</entry> + <entry>&media-pad-desc;</entry> <entry><structfield>source</structfield></entry> <entry>Pad at the origin of this link.</entry> </row> <row> - <entry>struct &media-pad-desc;</entry> + <entry>&media-pad-desc;</entry> <entry><structfield>sink</structfield></entry> <entry>Pad at the target of this link.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index ea514d6075c..91dcbc84f3f 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -772,7 +772,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see </row> <row id="V4L2-PIX-FMT-H264-MVC"> <entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry> - <entry>'MVC'</entry> + <entry>'M264'</entry> <entry>H264 MVC video elementary stream.</entry> </row> <row id="V4L2-PIX-FMT-H263"> @@ -812,7 +812,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see </row> <row id="V4L2-PIX-FMT-VP8"> <entry><constant>V4L2_PIX_FMT_VP8</constant></entry> - <entry>'VP8'</entry> + <entry>'VP80'</entry> <entry>VP8 video elementary stream.</entry> </row> </tbody> diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml index 7331ce116f4..b2d5a0363cb 100644 --- a/Documentation/DocBook/media/v4l/subdev-formats.xml +++ b/Documentation/DocBook/media/v4l/subdev-formats.xml @@ -1898,6 +1898,134 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> + <row id="V4L2-MBUS-FMT-UYVY10-2X10"> + <entry>V4L2_MBUS_FMT_UYVY10_2X10</entry> + <entry>0x2018</entry> + <entry></entry> + &dash-ent-22; + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-22; + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-22; + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-22; + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY10-2X10"> + <entry>V4L2_MBUS_FMT_VYUY10_2X10</entry> + <entry>0x2019</entry> + <entry></entry> + &dash-ent-22; + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-22; + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-22; + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-22; + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> <row id="V4L2-MBUS-FMT-YUYV10-2X10"> <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry> <entry>0x200b</entry> @@ -2308,6 +2436,110 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> + <row id="V4L2-MBUS-FMT-UYVY10-1X20"> + <entry>V4L2_MBUS_FMT_UYVY10_1X20</entry> + <entry>0x201a</entry> + <entry></entry> + &dash-ent-12; + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-12; + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY10-1X20"> + <entry>V4L2_MBUS_FMT_VYUY10_1X20</entry> + <entry>0x201b</entry> + <entry></entry> + &dash-ent-12; + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-12; + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> <row id="V4L2-MBUS-FMT-YUYV10-1X20"> <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry> <entry>0x200d</entry> @@ -2486,6 +2718,534 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> + <row id="V4L2-MBUS-FMT-UYVY12-2X12"> + <entry>V4L2_MBUS_FMT_UYVY12_2X12</entry> + <entry>0x201c</entry> + <entry></entry> + &dash-ent-20; + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY12-2X12"> + <entry>V4L2_MBUS_FMT_VYUY12_2X12</entry> + <entry>0x201d</entry> + <entry></entry> + &dash-ent-20; + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV12-2X12"> + <entry>V4L2_MBUS_FMT_YUYV12_2X12</entry> + <entry>0x201e</entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU12-2X12"> + <entry>V4L2_MBUS_FMT_YVYU12_2X12</entry> + <entry>0x201f</entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-20; + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-UYVY12-1X24"> + <entry>V4L2_MBUS_FMT_UYVY12_1X24</entry> + <entry>0x2020</entry> + <entry></entry> + &dash-ent-8; + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-8; + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY12-1X24"> + <entry>V4L2_MBUS_FMT_VYUY12_1X24</entry> + <entry>0x2021</entry> + <entry></entry> + &dash-ent-8; + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-8; + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV12-1X24"> + <entry>V4L2_MBUS_FMT_YUYV12_1X24</entry> + <entry>0x2022</entry> + <entry></entry> + &dash-ent-8; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-8; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU12-1X24"> + <entry>V4L2_MBUS_FMT_YVYU12_1X24</entry> + <entry>0x2023</entry> + <entry></entry> + &dash-ent-8; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>v<subscript>11</subscript></entry> + <entry>v<subscript>10</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + &dash-ent-8; + <entry>y<subscript>11</subscript></entry> + <entry>y<subscript>10</subscript></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>u<subscript>11</subscript></entry> + <entry>u<subscript>10</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index 89891adb928..820f86e8744 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml @@ -242,6 +242,22 @@ </tgroup> </table> + <table frame="none" pgwide="1" id="v4l2-event-src-change"> + <title>struct <structname>v4l2_event_src_change</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>changes</structfield></entry> + <entry> + A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />. + </entry> + </row> + </tbody> + </tgroup> + </table> + <table pgwide="1" frame="none" id="changes-flags"> <title>Changes</title> <tgroup cols="3"> @@ -270,6 +286,23 @@ </tbody> </tgroup> </table> + + <table pgwide="1" frame="none" id="src-changes-flags"> + <title>Source Changes</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry> + <entry>0x0001</entry> + <entry>This event gets triggered when a resolution change is + detected at an input. This can come from an input connector or + from a video decoder. + </entry> + </row> + </tbody> + </tgroup> + </table> </refsect1> <refsect1> &return-value; diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml index cd7720d404e..28a8c1e1c70 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml @@ -1,11 +1,12 @@ <refentry id="vidioc-dv-timings-cap"> <refmeta> - <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP</refentrytitle> + <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</refentrytitle> &manvol; </refmeta> <refnamediv> <refname>VIDIOC_DV_TIMINGS_CAP</refname> + <refname>VIDIOC_SUBDEV_DV_TIMINGS_CAP</refname> <refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose> </refnamediv> @@ -33,7 +34,7 @@ <varlistentry> <term><parameter>request</parameter></term> <listitem> - <para>VIDIOC_DV_TIMINGS_CAP</para> + <para>VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</para> </listitem> </varlistentry> <varlistentry> @@ -54,10 +55,19 @@ interface and may change in the future.</para> </note> - <para>To query the capabilities of the DV receiver/transmitter applications can call -this ioctl and the driver will fill in the structure. Note that drivers may return + <para>To query the capabilities of the DV receiver/transmitter applications +can call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node +and the driver will fill in the structure. Note that drivers may return different values after switching the video input or output.</para> + <para>When implemented by the driver DV capabilities of subdevices can be +queried by calling the <constant>VIDIOC_SUBDEV_DV_TIMINGS_CAP</constant> ioctl +directly on a subdevice node. The capabilities are specific to inputs (for DV +receivers) or outputs (for DV transmitters), applications must specify the +desired pad number in the &v4l2-dv-timings-cap; <structfield>pad</structfield> +field. Attempts to query capabilities on a pad that doesn't support them will +return an &EINVAL;.</para> + <table pgwide="1" frame="none" id="v4l2-bt-timings-cap"> <title>struct <structname>v4l2_bt_timings_cap</structname></title> <tgroup cols="3"> @@ -127,7 +137,14 @@ different values after switching the video input or output.</para> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API. This field + is only used when operating on a subdevice node. When operating on a + video node applications must set this field to zero.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[2]</entry> <entry>Reserved for future extensions. Drivers must set the array to zero.</entry> </row> <row> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml index b3e17c1dfaf..b9fdfeacdbc 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml @@ -1,11 +1,12 @@ <refentry id="vidioc-enum-dv-timings"> <refmeta> - <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS</refentrytitle> + <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refentrytitle> &manvol; </refmeta> <refnamediv> <refname>VIDIOC_ENUM_DV_TIMINGS</refname> + <refname>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refname> <refpurpose>Enumerate supported Digital Video timings</refpurpose> </refnamediv> @@ -33,7 +34,7 @@ <varlistentry> <term><parameter>request</parameter></term> <listitem> - <para>VIDIOC_ENUM_DV_TIMINGS</para> + <para>VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</para> </listitem> </varlistentry> <varlistentry> @@ -61,14 +62,21 @@ standards or even custom timings that are not in this list.</para> <para>To query the available timings, applications initialize the <structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings; -and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an +and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a +pointer to this structure. Drivers fill the rest of the structure or return an &EINVAL; when the index is out of bounds. To enumerate all supported DV timings, applications shall begin at index zero, incrementing by one until the driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a different set of DV timings after switching the video input or output.</para> + <para>When implemented by the driver DV timings of subdevices can be queried +by calling the <constant>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</constant> ioctl directly +on a subdevice node. The DV timings are specific to inputs (for DV receivers) or +outputs (for DV transmitters), applications must specify the desired pad number +in the &v4l2-enum-dv-timings; <structfield>pad</structfield> field. Attempts to +enumerate timings on a pad that doesn't support them will return an &EINVAL;.</para> + <table pgwide="1" frame="none" id="v4l2-enum-dv-timings"> <title>struct <structname>v4l2_enum_dv_timings</structname></title> <tgroup cols="3"> @@ -82,8 +90,16 @@ application.</entry> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> - <entry>Reserved for future extensions. Drivers must set the array to zero.</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API. This field + is only used when operating on a subdevice node. When operating on a + video node applications must set this field to zero.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[2]</entry> + <entry>Reserved for future extensions. Drivers and applications must + set the array to zero.</entry> </row> <row> <entry>&v4l2-dv-timings;</entry> @@ -103,7 +119,7 @@ application.</entry> <term><errorcode>EINVAL</errorcode></term> <listitem> <para>The &v4l2-enum-dv-timings; <structfield>index</structfield> -is out of bounds.</para> +is out of bounds or the <structfield>pad</structfield> number is invalid.</para> </listitem> </varlistentry> <varlistentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index 5c70b616d81..17efa870d4d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml @@ -155,6 +155,26 @@ </entry> </row> <row> + <entry><constant>V4L2_EVENT_SOURCE_CHANGE</constant></entry> + <entry>5</entry> + <entry> + <para>This event is triggered when a source parameter change is + detected during runtime by the video device. It can be a + runtime resolution change triggered by a video decoder or the + format change happening on an input connector. + This event requires that the <structfield>id</structfield> + matches the input index (when used with a video device node) + or the pad index (when used with a subdevice node) from which + you want to receive events.</para> + + <para>This event has a &v4l2-event-src-change; associated + with it. The <structfield>changes</structfield> bitfield denotes + what has changed for the subscribed pad. If multiple events + occurred before application could dequeue them, then the changes + will have the ORed value of all the events generated.</para> + </entry> + </row> + <row> <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> <entry>0x08000000</entry> <entry>Base event number for driver-private events.</entry> diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index 4decb46bfa7..03f9a1f8d41 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -68,7 +68,7 @@ several digital tv standards. While it is called as DVB API, in fact it covers several different video standards including DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated - to documment support also for DVB-S2, ISDB-T and ISDB-S.</para> + to document support also for DVB-S2, ISDB-T and ISDB-S.</para> <para>The third part covers the Remote Controller API.</para> <para>The fourth part covers the Media Controller API.</para> <para>For additional information and for the latest development code, diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index cd11926e07c..7da8f0402af 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -91,7 +91,7 @@ <listitem><para> [MTD Interface]</para><para> These functions provide the interface to the MTD kernel API. - They are not replacable and provide functionality + They are not replaceable and provide functionality which is complete hardware independent. </para></listitem> <listitem><para> @@ -100,14 +100,14 @@ </para></listitem> <listitem><para> [GENERIC]</para><para> - Generic functions are not replacable and provide functionality + Generic functions are not replaceable and provide functionality which is complete hardware independent. </para></listitem> <listitem><para> [DEFAULT]</para><para> Default functions provide hardware related functionality which is suitable for most of the implementations. These functions can be replaced by the - board driver if neccecary. Those functions are called via pointers in the + board driver if necessary. Those functions are called via pointers in the NAND chip description structure. The board driver can set the functions which should be replaced by board dependent functions before calling nand_scan(). If the function pointer is NULL on entry to nand_scan() then the pointer @@ -264,7 +264,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) is set up nand_scan() is called. This function tries to detect and identify then chip. If a chip is found all the internal data fields are initialized accordingly. - The structure(s) have to be zeroed out first and then filled with the neccecary + The structure(s) have to be zeroed out first and then filled with the necessary information about the device. </para> <programlisting> @@ -327,7 +327,7 @@ module_init(board_init); <sect1 id="Exit_function"> <title>Exit function</title> <para> - The exit function is only neccecary if the driver is + The exit function is only necessary if the driver is compiled as a module. It releases all resources which are held by the chip driver and unregisters the partitions in the MTD layer. @@ -494,7 +494,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) in this case. See rts_from4.c and diskonchip.c for implementation reference. In those cases we must also use bad block tables on FLASH, because the ECC layout is - interferring with the bad block marker positions. + interfering with the bad block marker positions. See bad block table support for details. </para> </sect2> @@ -542,7 +542,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <para> nand_scan() calls the function nand_default_bbt(). nand_default_bbt() selects appropriate default - bad block table desriptors depending on the chip information + bad block table descriptors depending on the chip information which was retrieved by nand_scan(). </para> <para> @@ -554,7 +554,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <sect2 id="Flash_based_tables"> <title>Flash based tables</title> <para> - It may be desired or neccecary to keep a bad block table in FLASH. + It may be desired or necessary to keep a bad block table in FLASH. For AG-AND chips this is mandatory, as they have no factory marked bad blocks. They have factory marked good blocks. The marker pattern is erased when the block is erased to be reused. So in case of @@ -565,10 +565,10 @@ static void board_select_chip (struct mtd_info *mtd, int chip) of the blocks. </para> <para> - The blocks in which the tables are stored are procteted against + The blocks in which the tables are stored are protected against accidental access by marking them bad in the memory bad block table. The bad block table management functions are allowed - to circumvernt this protection. + to circumvent this protection. </para> <para> The simplest way to activate the FLASH based bad block table support @@ -592,7 +592,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) User defined tables are created by filling out a nand_bbt_descr structure and storing the pointer in the nand_chip structure member bbt_td before calling nand_scan(). - If a mirror table is neccecary a second structure must be + If a mirror table is necessary a second structure must be created and a pointer to this structure must be stored in bbt_md inside the nand_chip structure. If the bbt_md member is set to NULL then only the main table is used @@ -666,7 +666,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <para> For automatic placement some blocks must be reserved for bad block table storage. The number of reserved blocks is defined - in the maxblocks member of the babd block table description structure. + in the maxblocks member of the bad block table description structure. Reserving 4 blocks for mirrored tables should be a reasonable number. This also limits the number of blocks which are scanned for the bad block table ident pattern. @@ -1068,11 +1068,11 @@ in this page</entry> <chapter id="filesystems"> <title>Filesystem support</title> <para> - The NAND driver provides all neccecary functions for a + The NAND driver provides all necessary functions for a filesystem via the MTD interface. </para> <para> - Filesystems must be aware of the NAND pecularities and + Filesystems must be aware of the NAND peculiarities and restrictions. One major restrictions of NAND Flash is, that you cannot write as often as you want to a page. The consecutive writes to a page, before erasing it again, are restricted to 1-3 writes, depending on the @@ -1222,7 +1222,7 @@ in this page</entry> #define NAND_BBT_VERSION 0x00000100 /* Create a bbt if none axists */ #define NAND_BBT_CREATE 0x00000200 -/* Write bbt if neccecary */ +/* Write bbt if necessary */ #define NAND_BBT_WRITE 0x00001000 /* Read and write back block contents when writing bbt */ #define NAND_BBT_SAVECONTENT 0x00002000 diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl index 346e552fa2c..3b08a085d2c 100644 --- a/Documentation/DocBook/regulator.tmpl +++ b/Documentation/DocBook/regulator.tmpl @@ -155,7 +155,7 @@ release regulators. Functions are provided to <link linkend='API-regulator-enable'>enable</link> and <link linkend='API-regulator-disable'>disable</link> the - reguator and to get and set the runtime parameters of the + regulator and to get and set the runtime parameters of the regulator. </para> <para> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 95618159e29..bbe9c1fd5ce 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -766,10 +766,10 @@ framework to set up sysfs files for this region. Simply leave it alone. <para> The dynamic memory regions will be allocated when the UIO device file, <varname>/dev/uioX</varname> is opened. - Simiar to static memory resources, the memory region information for + Similar to static memory resources, the memory region information for dynamic regions is then visible via sysfs at <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. - The dynmaic memory regions will be freed when the UIO device file is + The dynamic memory regions will be freed when the UIO device file is closed. When no processes are holding the device file open, the address returned to userspace is ~0. </para> diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 8d57c1888dc..85fc0e28576 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -153,7 +153,7 @@ <listitem><para>The Linux USB API supports synchronous calls for control and bulk messages. - It also supports asynchnous calls for all kinds of data transfer, + It also supports asynchronous calls for all kinds of data transfer, using request structures called "URBs" (USB Request Blocks). </para></listitem> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index d0056a4e9c5..6f639d9530b 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -5696,7 +5696,7 @@ struct _snd_pcm_runtime { suspending the PCM operations via <function>snd_pcm_suspend_all()</function> or <function>snd_pcm_suspend()</function>. It means that the PCM - streams are already stoppped when the register snapshot is + streams are already stopped when the register snapshot is taken. But, remember that you don't have to restart the PCM stream in the resume callback. It'll be restarted via trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl new file mode 100644 index 00000000000..837eca77f27 --- /dev/null +++ b/Documentation/DocBook/writing_musb_glue_layer.tmpl @@ -0,0 +1,873 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="Writing-MUSB-Glue-Layer"> + <bookinfo> + <title>Writing an MUSB Glue Layer</title> + + <authorgroup> + <author> + <firstname>Apelete</firstname> + <surname>Seketeli</surname> + <affiliation> + <address> + <email>apelete at seketeli.net</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2014</year> + <holder>Apelete Seketeli</holder> + </copyright> + + <legalnotice> + <para> + This documentation is free software; you can redistribute it + and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + </para> + + <para> + This documentation is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public License + along with this documentation; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA + 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the Linux kernel source + tree. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="introduction"> + <title>Introduction</title> + <para> + The Linux MUSB subsystem is part of the larger Linux USB + subsystem. It provides support for embedded USB Device Controllers + (UDC) that do not use Universal Host Controller Interface (UHCI) + or Open Host Controller Interface (OHCI). + </para> + <para> + Instead, these embedded UDC rely on the USB On-the-Go (OTG) + specification which they implement at least partially. The silicon + reference design used in most cases is the Multipoint USB + Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor + Graphics Inventra™ design. + </para> + <para> + As a self-taught exercise I have written an MUSB glue layer for + the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers + in the kernel source tree. This layer can be found at + drivers/usb/musb/jz4740.c. In this documentation I will walk + through the basics of the jz4740.c glue layer, explaining the + different pieces and what needs to be done in order to write your + own device glue layer. + </para> + </chapter> + + <chapter id="linux-musb-basics"> + <title>Linux MUSB Basics</title> + <para> + To get started on the topic, please read USB On-the-Go Basics (see + Resources) which provides an introduction of USB OTG operation at + the hardware level. A couple of wiki pages by Texas Instruments + and Analog Devices also provide an overview of the Linux kernel + MUSB configuration, albeit focused on some specific devices + provided by these companies. Finally, getting acquainted with the + USB specification at USB home page may come in handy, with + practical instance provided through the Writing USB Device Drivers + documentation (again, see Resources). + </para> + <para> + Linux USB stack is a layered architecture in which the MUSB + controller hardware sits at the lowest. The MUSB controller driver + abstract the MUSB controller hardware to the Linux USB stack. + </para> + <programlisting> + ------------------------ + | | <------- drivers/usb/gadget + | Linux USB Core Stack | <------- drivers/usb/host + | | <------- drivers/usb/core + ------------------------ + ⬍ + -------------------------- + | | <------ drivers/usb/musb/musb_gadget.c + | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c + | | <------ drivers/usb/musb/musb_core.c + -------------------------- + ⬍ + --------------------------------- + | MUSB Platform Specific Driver | + | | <-- drivers/usb/musb/jz4740.c + | aka "Glue Layer" | + --------------------------------- + ⬍ + --------------------------------- + | MUSB Controller Hardware | + --------------------------------- + </programlisting> + <para> + As outlined above, the glue layer is actually the platform + specific code sitting in between the controller driver and the + controller hardware. + </para> + <para> + Just like a Linux USB driver needs to register itself with the + Linux USB subsystem, the MUSB glue layer needs first to register + itself with the MUSB controller driver. This will allow the + controller driver to know about which device the glue layer + supports and which functions to call when a supported device is + detected or released; remember we are talking about an embedded + controller chip here, so no insertion or removal at run-time. + </para> + <para> + All of this information is passed to the MUSB controller driver + through a platform_driver structure defined in the glue layer as: + </para> + <programlisting linenumbering="numbered"> +static struct platform_driver jz4740_driver = { + .probe = jz4740_probe, + .remove = jz4740_remove, + .driver = { + .name = "musb-jz4740", + }, +}; + </programlisting> + <para> + The probe and remove function pointers are called when a matching + device is detected and, respectively, released. The name string + describes the device supported by this glue layer. In the current + case it matches a platform_device structure declared in + arch/mips/jz4740/platform.c. Note that we are not using device + tree bindings here. + </para> + <para> + In order to register itself to the controller driver, the glue + layer goes through a few steps, basically allocating the + controller hardware resources and initialising a couple of + circuits. To do so, it needs to keep track of the information used + throughout these steps. This is done by defining a private + jz4740_glue structure: + </para> + <programlisting linenumbering="numbered"> +struct jz4740_glue { + struct device *dev; + struct platform_device *musb; + struct clk *clk; +}; + </programlisting> + <para> + The dev and musb members are both device structure variables. The + first one holds generic information about the device, since it's + the basic device structure, and the latter holds information more + closely related to the subsystem the device is registered to. The + clk variable keeps information related to the device clock + operation. + </para> + <para> + Let's go through the steps of the probe function that leads the + glue layer to register itself to the controller driver. + </para> + <para> + N.B.: For the sake of readability each function will be split in + logical parts, each part being shown as if it was independent from + the others. + </para> + <programlisting linenumbering="numbered"> +static int jz4740_probe(struct platform_device *pdev) +{ + struct platform_device *musb; + struct jz4740_glue *glue; + struct clk *clk; + int ret; + + glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); + if (!glue) + return -ENOMEM; + + musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); + if (!musb) { + dev_err(&pdev->dev, "failed to allocate musb device\n"); + return -ENOMEM; + } + + clk = devm_clk_get(&pdev->dev, "udc"); + if (IS_ERR(clk)) { + dev_err(&pdev->dev, "failed to get clock\n"); + ret = PTR_ERR(clk); + goto err_platform_device_put; + } + + ret = clk_prepare_enable(clk); + if (ret) { + dev_err(&pdev->dev, "failed to enable clock\n"); + goto err_platform_device_put; + } + + musb->dev.parent = &pdev->dev; + + glue->dev = &pdev->dev; + glue->musb = musb; + glue->clk = clk; + + return 0; + +err_platform_device_put: + platform_device_put(musb); + return ret; +} + </programlisting> + <para> + The first few lines of the probe function allocate and assign the + glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows + the allocation process to sleep and wait for memory, thus being + usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line + 12) allows automatic allocation and management of device IDs in + order to avoid device namespace collisions with explicit IDs. With + devm_clk_get() (line 18) the glue layer allocates the clock -- the + <literal>devm_</literal> prefix indicates that clk_get() is + managed: it automatically frees the allocated clock resource data + when the device is released -- and enable it. + </para> + <para> + Then comes the registration steps: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_probe(struct platform_device *pdev) +{ + struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; + + pdata->platform_ops = &jz4740_musb_ops; + + platform_set_drvdata(pdev, glue); + + ret = platform_device_add_resources(musb, pdev->resource, + pdev->num_resources); + if (ret) { + dev_err(&pdev->dev, "failed to add resources\n"); + goto err_clk_disable; + } + + ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); + if (ret) { + dev_err(&pdev->dev, "failed to add platform_data\n"); + goto err_clk_disable; + } + + return 0; + +err_clk_disable: + clk_disable_unprepare(clk); +err_platform_device_put: + platform_device_put(musb); + return ret; +} + </programlisting> + <para> + The first step is to pass the device data privately held by the + glue layer on to the controller driver through + platform_set_drvdata() (line 7). Next is passing on the device + resources information, also privately held at that point, through + platform_device_add_resources() (line 9). + </para> + <para> + Finally comes passing on the platform specific data to the + controller driver (line 16). Platform data will be discussed in + <link linkend="device-platform-data">Chapter 4</link>, but here + we are looking at the platform_ops function pointer (line 5) in + musb_hdrc_platform_data structure (line 3). This function + pointer allows the MUSB controller driver to know which function + to call for device operation: + </para> + <programlisting linenumbering="numbered"> +static const struct musb_platform_ops jz4740_musb_ops = { + .init = jz4740_musb_init, + .exit = jz4740_musb_exit, +}; + </programlisting> + <para> + Here we have the minimal case where only init and exit functions + are called by the controller driver when needed. Fact is the + JZ4740 MUSB controller is a basic controller, lacking some + features found in other controllers, otherwise we may also have + pointers to a few other functions like a power management function + or a function to switch between OTG and non-OTG modes, for + instance. + </para> + <para> + At that point of the registration process, the controller driver + actually calls the init function: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_init(struct musb *musb) +{ + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); + if (!musb->xceiv) { + pr_err("HS UDC: no transceiver configured\n"); + return -ENODEV; + } + + /* Silicon does not implement ConfigData register. + * Set dyn_fifo to avoid reading EP config from hardware. + */ + musb->dyn_fifo = true; + + musb->isr = jz4740_musb_interrupt; + + return 0; +} + </programlisting> + <para> + The goal of jz4740_musb_init() is to get hold of the transceiver + driver data of the MUSB controller hardware and pass it on to the + MUSB controller driver, as usual. The transceiver is the circuitry + inside the controller hardware responsible for sending/receiving + the USB data. Since it is an implementation of the physical layer + of the OSI model, the transceiver is also referred to as PHY. + </para> + <para> + Getting hold of the MUSB PHY driver data is done with + usb_get_phy() which returns a pointer to the structure + containing the driver instance data. The next couple of + instructions (line 12 and 14) are used as a quirk and to setup + IRQ handling respectively. Quirks and IRQ handling will be + discussed later in <link linkend="device-quirks">Chapter + 5</link> and <link linkend="handling-irqs">Chapter 3</link>. + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_exit(struct musb *musb) +{ + usb_put_phy(musb->xceiv); + + return 0; +} + </programlisting> + <para> + Acting as the counterpart of init, the exit function releases the + MUSB PHY driver when the controller hardware itself is about to be + released. + </para> + <para> + Again, note that init and exit are fairly simple in this case due + to the basic set of features of the JZ4740 controller hardware. + When writing an musb glue layer for a more complex controller + hardware, you might need to take care of more processing in those + two functions. + </para> + <para> + Returning from the init function, the MUSB controller driver jumps + back into the probe function: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_probe(struct platform_device *pdev) +{ + ret = platform_device_add(musb); + if (ret) { + dev_err(&pdev->dev, "failed to register musb device\n"); + goto err_clk_disable; + } + + return 0; + +err_clk_disable: + clk_disable_unprepare(clk); +err_platform_device_put: + platform_device_put(musb); + return ret; +} + </programlisting> + <para> + This is the last part of the device registration process where the + glue layer adds the controller hardware device to Linux kernel + device hierarchy: at this stage, all known information about the + device is passed on to the Linux USB core stack. + </para> + <programlisting linenumbering="numbered"> +static int jz4740_remove(struct platform_device *pdev) +{ + struct jz4740_glue *glue = platform_get_drvdata(pdev); + + platform_device_unregister(glue->musb); + clk_disable_unprepare(glue->clk); + + return 0; +} + </programlisting> + <para> + Acting as the counterpart of probe, the remove function unregister + the MUSB controller hardware (line 5) and disable the clock (line + 6), allowing it to be gated. + </para> + </chapter> + + <chapter id="handling-irqs"> + <title>Handling IRQs</title> + <para> + Additionally to the MUSB controller hardware basic setup and + registration, the glue layer is also responsible for handling the + IRQs: + </para> + <programlisting linenumbering="numbered"> +static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) +{ + unsigned long flags; + irqreturn_t retval = IRQ_NONE; + struct musb *musb = __hci; + + spin_lock_irqsave(&musb->lock, flags); + + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); + + /* + * The controller is gadget only, the state of the host mode IRQ bits is + * undefined. Mask them to make sure that the musb driver core will + * never see them set + */ + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | + MUSB_INTR_RESET | MUSB_INTR_SOF; + + if (musb->int_usb || musb->int_tx || musb->int_rx) + retval = musb_interrupt(musb); + + spin_unlock_irqrestore(&musb->lock, flags); + + return retval; +} + </programlisting> + <para> + Here the glue layer mostly has to read the relevant hardware + registers and pass their values on to the controller driver which + will handle the actual event that triggered the IRQ. + </para> + <para> + The interrupt handler critical section is protected by the + spin_lock_irqsave() and counterpart spin_unlock_irqrestore() + functions (line 7 and 24 respectively), which prevent the + interrupt handler code to be run by two different threads at the + same time. + </para> + <para> + Then the relevant interrupt registers are read (line 9 to 11): + </para> + <itemizedlist> + <listitem> + <para> + MUSB_INTRUSB: indicates which USB interrupts are currently + active, + </para> + </listitem> + <listitem> + <para> + MUSB_INTRTX: indicates which of the interrupts for TX + endpoints are currently active, + </para> + </listitem> + <listitem> + <para> + MUSB_INTRRX: indicates which of the interrupts for TX + endpoints are currently active. + </para> + </listitem> + </itemizedlist> + <para> + Note that musb_readb() is used to read 8-bit registers at most, + while musb_readw() allows us to read at most 16-bit registers. + There are other functions that can be used depending on the size + of your device registers. See musb_io.h for more information. + </para> + <para> + Instruction on line 18 is another quirk specific to the JZ4740 + USB device controller, which will be discussed later in <link + linkend="device-quirks">Chapter 5</link>. + </para> + <para> + The glue layer still needs to register the IRQ handler though. + Remember the instruction on line 14 of the init function: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_init(struct musb *musb) +{ + musb->isr = jz4740_musb_interrupt; + + return 0; +} + </programlisting> + <para> + This instruction sets a pointer to the glue layer IRQ handler + function, in order for the controller hardware to call the handler + back when an IRQ comes from the controller hardware. The interrupt + handler is now implemented and registered. + </para> + </chapter> + + <chapter id="device-platform-data"> + <title>Device Platform Data</title> + <para> + In order to write an MUSB glue layer, you need to have some data + describing the hardware capabilities of your controller hardware, + which is called the platform data. + </para> + <para> + Platform data is specific to your hardware, though it may cover a + broad range of devices, and is generally found somewhere in the + arch/ directory, depending on your device architecture. + </para> + <para> + For instance, platform data for the JZ4740 SoC is found in + arch/mips/jz4740/platform.c. In the platform.c file each device of + the JZ4740 SoC is described through a set of structures. + </para> + <para> + Here is the part of arch/mips/jz4740/platform.c that covers the + USB Device Controller (UDC): + </para> + <programlisting linenumbering="numbered"> +/* USB Device Controller */ +struct platform_device jz4740_udc_xceiv_device = { + .name = "usb_phy_gen_xceiv", + .id = 0, +}; + +static struct resource jz4740_udc_resources[] = { + [0] = { + .start = JZ4740_UDC_BASE_ADDR, + .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = JZ4740_IRQ_UDC, + .end = JZ4740_IRQ_UDC, + .flags = IORESOURCE_IRQ, + .name = "mc", + }, +}; + +struct platform_device jz4740_udc_device = { + .name = "musb-jz4740", + .id = -1, + .dev = { + .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, + .coherent_dma_mask = DMA_BIT_MASK(32), + }, + .num_resources = ARRAY_SIZE(jz4740_udc_resources), + .resource = jz4740_udc_resources, +}; + </programlisting> + <para> + The jz4740_udc_xceiv_device platform device structure (line 2) + describes the UDC transceiver with a name and id number. + </para> + <para> + At the time of this writing, note that + "usb_phy_gen_xceiv" is the specific name to be used for + all transceivers that are either built-in with reference USB IP or + autonomous and doesn't require any PHY programming. You will need + to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make + use of the corresponding transceiver driver. The id field could be + set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to + PLATFORM_DEVID_AUTO) or start with 0 for the first device of this + kind if we want a specific id number. + </para> + <para> + The jz4740_udc_resources resource structure (line 7) defines the + UDC registers base addresses. + </para> + <para> + The first array (line 9 to 11) defines the UDC registers base + memory addresses: start points to the first register memory + address, end points to the last register memory address and the + flags member defines the type of resource we are dealing with. So + IORESOURCE_MEM is used to define the registers memory addresses. + The second array (line 14 to 17) defines the UDC IRQ registers + addresses. Since there is only one IRQ register available for the + JZ4740 UDC, start and end point at the same address. The + IORESOURCE_IRQ flag tells that we are dealing with IRQ resources, + and the name "mc" is in fact hard-coded in the MUSB core + in order for the controller driver to retrieve this IRQ resource + by querying it by its name. + </para> + <para> + Finally, the jz4740_udc_device platform device structure (line 21) + describes the UDC itself. + </para> + <para> + The "musb-jz4740" name (line 22) defines the MUSB + driver that is used for this device; remember this is in fact + the name that we used in the jz4740_driver platform driver + structure in <link linkend="linux-musb-basics">Chapter + 2</link>. The id field (line 23) is set to -1 (equivalent to + PLATFORM_DEVID_NONE) since we do not need an id for the device: + the MUSB controller driver was already set to allocate an + automatic id in <link linkend="linux-musb-basics">Chapter + 2</link>. In the dev field we care for DMA related information + here. The dma_mask field (line 25) defines the width of the DMA + mask that is going to be used, and coherent_dma_mask (line 26) + has the same purpose but for the alloc_coherent DMA mappings: in + both cases we are using a 32 bits mask. Then the resource field + (line 29) is simply a pointer to the resource structure defined + before, while the num_resources field (line 28) keeps track of + the number of arrays defined in the resource structure (in this + case there were two resource arrays defined before). + </para> + <para> + With this quick overview of the UDC platform data at the arch/ + level now done, let's get back to the MUSB glue layer specific + platform data in drivers/usb/musb/jz4740.c: + </para> + <programlisting linenumbering="numbered"> +static struct musb_hdrc_config jz4740_musb_config = { + /* Silicon does not implement USB OTG. */ + .multipoint = 0, + /* Max EPs scanned, driver will decide which EP can be used. */ + .num_eps = 4, + /* RAMbits needed to configure EPs from table */ + .ram_bits = 9, + .fifo_cfg = jz4740_musb_fifo_cfg, + .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), +}; + +static struct musb_hdrc_platform_data jz4740_musb_platform_data = { + .mode = MUSB_PERIPHERAL, + .config = &jz4740_musb_config, +}; + </programlisting> + <para> + First the glue layer configures some aspects of the controller + driver operation related to the controller hardware specifics. + This is done through the jz4740_musb_config musb_hdrc_config + structure. + </para> + <para> + Defining the OTG capability of the controller hardware, the + multipoint member (line 3) is set to 0 (equivalent to false) + since the JZ4740 UDC is not OTG compatible. Then num_eps (line + 5) defines the number of USB endpoints of the controller + hardware, including endpoint 0: here we have 3 endpoints + + endpoint 0. Next is ram_bits (line 7) which is the width of the + RAM address bus for the MUSB controller hardware. This + information is needed when the controller driver cannot + automatically configure endpoints by reading the relevant + controller hardware registers. This issue will be discussed when + we get to device quirks in <link linkend="device-quirks">Chapter + 5</link>. Last two fields (line 8 and 9) are also about device + quirks: fifo_cfg points to the USB endpoints configuration table + and fifo_cfg_size keeps track of the size of the number of + entries in that configuration table. More on that later in <link + linkend="device-quirks">Chapter 5</link>. + </para> + <para> + Then this configuration is embedded inside + jz4740_musb_platform_data musb_hdrc_platform_data structure (line + 11): config is a pointer to the configuration structure itself, + and mode tells the controller driver if the controller hardware + may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG + which is a dual mode. + </para> + <para> + Remember that jz4740_musb_platform_data is then used to convey + platform data information as we have seen in the probe function + in <link linkend="linux-musb-basics">Chapter 2</link> + </para> + </chapter> + + <chapter id="device-quirks"> + <title>Device Quirks</title> + <para> + Completing the platform data specific to your device, you may also + need to write some code in the glue layer to work around some + device specific limitations. These quirks may be due to some + hardware bugs, or simply be the result of an incomplete + implementation of the USB On-the-Go specification. + </para> + <para> + The JZ4740 UDC exhibits such quirks, some of which we will discuss + here for the sake of insight even though these might not be found + in the controller hardware you are working on. + </para> + <para> + Let's get back to the init function first: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_init(struct musb *musb) +{ + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); + if (!musb->xceiv) { + pr_err("HS UDC: no transceiver configured\n"); + return -ENODEV; + } + + /* Silicon does not implement ConfigData register. + * Set dyn_fifo to avoid reading EP config from hardware. + */ + musb->dyn_fifo = true; + + musb->isr = jz4740_musb_interrupt; + + return 0; +} + </programlisting> + <para> + Instruction on line 12 helps the MUSB controller driver to work + around the fact that the controller hardware is missing registers + that are used for USB endpoints configuration. + </para> + <para> + Without these registers, the controller driver is unable to read + the endpoints configuration from the hardware, so we use line 12 + instruction to bypass reading the configuration from silicon, and + rely on a hard-coded table that describes the endpoints + configuration instead: + </para> + <programlisting linenumbering="numbered"> +static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { +{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, +{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, +{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, +}; + </programlisting> + <para> + Looking at the configuration table above, we see that each + endpoints is described by three fields: hw_ep_num is the endpoint + number, style is its direction (either FIFO_TX for the controller + driver to send packets in the controller hardware, or FIFO_RX to + receive packets from hardware), and maxpacket defines the maximum + size of each data packet that can be transmitted over that + endpoint. Reading from the table, the controller driver knows that + endpoint 1 can be used to send and receive USB data packets of 512 + bytes at once (this is in fact a bulk in/out endpoint), and + endpoint 2 can be used to send data packets of 64 bytes at once + (this is in fact an interrupt endpoint). + </para> + <para> + Note that there is no information about endpoint 0 here: that one + is implemented by default in every silicon design, with a + predefined configuration according to the USB specification. For + more examples of endpoint configuration tables, see musb_core.c. + </para> + <para> + Let's now get back to the interrupt handler function: + </para> + <programlisting linenumbering="numbered"> +static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) +{ + unsigned long flags; + irqreturn_t retval = IRQ_NONE; + struct musb *musb = __hci; + + spin_lock_irqsave(&musb->lock, flags); + + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); + + /* + * The controller is gadget only, the state of the host mode IRQ bits is + * undefined. Mask them to make sure that the musb driver core will + * never see them set + */ + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | + MUSB_INTR_RESET | MUSB_INTR_SOF; + + if (musb->int_usb || musb->int_tx || musb->int_rx) + retval = musb_interrupt(musb); + + spin_unlock_irqrestore(&musb->lock, flags); + + return retval; +} + </programlisting> + <para> + Instruction on line 18 above is a way for the controller driver to + work around the fact that some interrupt bits used for USB host + mode operation are missing in the MUSB_INTRUSB register, thus left + in an undefined hardware state, since this MUSB controller + hardware is used in peripheral mode only. As a consequence, the + glue layer masks these missing bits out to avoid parasite + interrupts by doing a logical AND operation between the value read + from MUSB_INTRUSB and the bits that are actually implemented in + the register. + </para> + <para> + These are only a couple of the quirks found in the JZ4740 USB + device controller. Some others were directly addressed in the MUSB + core since the fixes were generic enough to provide a better + handling of the issues for others controller hardware eventually. + </para> + </chapter> + + <chapter id="conclusion"> + <title>Conclusion</title> + <para> + Writing a Linux MUSB glue layer should be a more accessible task, + as this documentation tries to show the ins and outs of this + exercise. + </para> + <para> + The JZ4740 USB device controller being fairly simple, I hope its + glue layer serves as a good example for the curious mind. Used + with the current MUSB glue layers, this documentation should + provide enough guidance to get started; should anything gets out + of hand, the linux-usb mailing list archive is another helpful + resource to browse through. + </para> + </chapter> + + <chapter id="acknowledgements"> + <title>Acknowledgements</title> + <para> + Many thanks to Lars-Peter Clausen and Maarten ter Huurne for + answering my questions while I was writing the JZ4740 glue layer + and for helping me out getting the code in good shape. + </para> + <para> + I would also like to thank the Qi-Hardware community at large for + its cheerful guidance and support. + </para> + </chapter> + + <chapter id="resources"> + <title>Resources</title> + <para> + USB Home Page: + <ulink url="http://www.usb.org">http://www.usb.org</ulink> + </para> + <para> + linux-usb Mailing List Archives: + <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink> + </para> + <para> + USB On-the-Go Basics: + <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink> + </para> + <para> + Writing USB Device Drivers: + <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink> + </para> + <para> + Texas Instruments USB Configuration Wiki Page: + <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink> + </para> + <para> + Analog Devices Blackfin MUSB Configuration: + <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink> + </para> + </chapter> + +</book> |