From c56a3b18475b0f93b484c25162c1379f5aee367a Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Tue, 13 Apr 2010 12:55:09 +0200 Subject: ALSA: Update the documentation for changes of proc files Signed-off-by: Takashi Iwai --- Documentation/DocBook/writing-an-alsa-driver.tmpl | 27 ++++++++++++++--------- 1 file changed, 17 insertions(+), 10 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 0d0f7b4d4b1a..0ba149de2608 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -5518,34 +5518,41 @@ struct _snd_pcm_runtime { ]]> + + For the raw data, size field must be + set properly. This specifies the maximum size of the proc file access. - The callback is much more complicated than the text-file - version. You need to use a low-level I/O functions such as + The read/write callbacks of raw mode are more direct than the text mode. + You need to use a low-level I/O functions such as copy_from/to_user() to transfer the data. local_max_size) - size = local_max_size - pos; - if (copy_to_user(buf, local_data + pos, size)) + if (copy_to_user(buf, local_data + pos, count)) return -EFAULT; - return size; + return count; } ]]> + + If the size of the info entry has been set up properly, + count and pos are + guaranteed to fit within 0 and the given size. + You don't have to check the range in the callbacks unless any + other condition is required. + -- cgit v1.2.3 From 2d2ef822758e3f5da59c40a392d0c6d89394d4b4 Mon Sep 17 00:00:00 2001 From: Jesse Barnes Date: Mon, 26 Oct 2009 13:06:31 -0700 Subject: drm: add initial DRM developer documentation Add a DRM DocBook providing basic information about DRM interfaces, including TTM, GEM, KMS and vblank infrastructure. Intended to provide information to new and existing developers about how to perform driver initialization, implement mode setting and other DRM features. Signed-off-by: Jesse Barnes Signed-off-by: Dave Airlie --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/drm.tmpl | 839 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 840 insertions(+), 1 deletion(-) create mode 100644 Documentation/DocBook/drm.tmpl (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 325cfd1d6d99..c7e5dc7e8cb3 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ mac80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml media.xml + tracepoint.xml media.xml drm.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl new file mode 100644 index 000000000000..7583dc7cf64d --- /dev/null +++ b/Documentation/DocBook/drm.tmpl @@ -0,0 +1,839 @@ + + + + + + Linux DRM Developer's Guide + + + 2008-2009 + + Intel Corporation (Jesse Barnes <jesse.barnes@intel.com>) + + + + + + The contents of this file may be used under the terms of the GNU + General Public License version 2 (the "GPL") as distributed in + the kernel source COPYING file. + + + + + + + + + + Introduction + + The Linux DRM layer contains code intended to support the needs + of complex graphics devices, usually containing programmable + pipelines well suited to 3D graphics acceleration. Graphics + drivers in the kernel can make use of DRM functions to make + tasks like memory management, interrupt handling and DMA easier, + and provide a uniform interface to applications. + + + A note on versions: this guide covers features found in the DRM + tree, including the TTM memory manager, output configuration and + mode setting, and the new vblank internals, in addition to all + the regular features found in current kernels. + + + [Insert diagram of typical DRM stack here] + + + + + + + DRM Internals + + This chapter documents DRM internals relevant to driver authors + and developers working to add support for the latest features to + existing drivers. + + + First, we'll go over some typical driver initialization + requirements, like setting up command buffers, creating an + initial output configuration, and initializing core services. + Subsequent sections will cover core internals in more detail, + providing implementation notes and examples. + + + The DRM layer provides several services to graphics drivers, + many of them driven by the application interfaces it provides + through libdrm, the library that wraps most of the DRM ioctls. + These include vblank event handling, memory + management, output management, framebuffer management, command + submission & fencing, suspend/resume support, and DMA + services. + + + The core of every DRM driver is struct drm_device. Drivers + will typically statically initialize a drm_device structure, + then pass it to drm_init() at load time. + + + + + + Driver initialization + + Before calling the DRM initialization routines, the driver must + first create and fill out a struct drm_device structure. + + + static struct drm_driver driver = { + /* don't use mtrr's here, the Xserver or user space app should + * deal with them for intel hardware. + */ + .driver_features = + DRIVER_USE_AGP | DRIVER_REQUIRE_AGP | + DRIVER_HAVE_IRQ | DRIVER_IRQ_SHARED | DRIVER_MODESET, + .load = i915_driver_load, + .unload = i915_driver_unload, + .firstopen = i915_driver_firstopen, + .lastclose = i915_driver_lastclose, + .preclose = i915_driver_preclose, + .save = i915_save, + .restore = i915_restore, + .device_is_agp = i915_driver_device_is_agp, + .get_vblank_counter = i915_get_vblank_counter, + .enable_vblank = i915_enable_vblank, + .disable_vblank = i915_disable_vblank, + .irq_preinstall = i915_driver_irq_preinstall, + .irq_postinstall = i915_driver_irq_postinstall, + .irq_uninstall = i915_driver_irq_uninstall, + .irq_handler = i915_driver_irq_handler, + .reclaim_buffers = drm_core_reclaim_buffers, + .get_map_ofs = drm_core_get_map_ofs, + .get_reg_ofs = drm_core_get_reg_ofs, + .fb_probe = intelfb_probe, + .fb_remove = intelfb_remove, + .fb_resize = intelfb_resize, + .master_create = i915_master_create, + .master_destroy = i915_master_destroy, +#if defined(CONFIG_DEBUG_FS) + .debugfs_init = i915_debugfs_init, + .debugfs_cleanup = i915_debugfs_cleanup, +#endif + .gem_init_object = i915_gem_init_object, + .gem_free_object = i915_gem_free_object, + .gem_vm_ops = &i915_gem_vm_ops, + .ioctls = i915_ioctls, + .fops = { + .owner = THIS_MODULE, + .open = drm_open, + .release = drm_release, + .ioctl = drm_ioctl, + .mmap = drm_mmap, + .poll = drm_poll, + .fasync = drm_fasync, +#ifdef CONFIG_COMPAT + .compat_ioctl = i915_compat_ioctl, +#endif + }, + .pci_driver = { + .name = DRIVER_NAME, + .id_table = pciidlist, + .probe = probe, + .remove = __devexit_p(drm_cleanup_pci), + }, + .name = DRIVER_NAME, + .desc = DRIVER_DESC, + .date = DRIVER_DATE, + .major = DRIVER_MAJOR, + .minor = DRIVER_MINOR, + .patchlevel = DRIVER_PATCHLEVEL, + }; + + + In the example above, taken from the i915 DRM driver, the driver + sets several flags indicating what core features it supports. + We'll go over the individual callbacks in later sections. Since + flags indicate which features your driver supports to the DRM + core, you need to set most of them prior to calling drm_init(). Some, + like DRIVER_MODESET can be set later based on user supplied parameters, + but that's the exception rather than the rule. + + + Driver flags + + DRIVER_USE_AGP + + Driver uses AGP interface + + + + DRIVER_REQUIRE_AGP + + Driver needs AGP interface to function. + + + + DRIVER_USE_MTRR + + + Driver uses MTRR interface for mapping memory. Deprecated. + + + + + DRIVER_PCI_DMA + + Driver is capable of PCI DMA. Deprecated. + + + + DRIVER_SG + + Driver can perform scatter/gather DMA. Deprecated. + + + + DRIVER_HAVE_DMA + Driver supports DMA. Deprecated. + + + DRIVER_HAVE_IRQDRIVER_IRQ_SHARED + + + DRIVER_HAVE_IRQ indicates whether the driver has a IRQ + handler, DRIVER_IRQ_SHARED indicates whether the device & + handler support shared IRQs (note that this is required of + PCI drivers). + + + + + DRIVER_DMA_QUEUE + + + If the driver queues DMA requests and completes them + asynchronously, this flag should be set. Deprecated. + + + + + DRIVER_FB_DMA + + + Driver supports DMA to/from the framebuffer. Deprecated. + + + + + DRIVER_MODESET + + + Driver supports mode setting interfaces. + + + + + + In this specific case, the driver requires AGP and supports + IRQs. DMA, as we'll see, is handled by device specific ioctls + in this case. It also supports the kernel mode setting APIs, though + unlike in the actual i915 driver source, this example unconditionally + exports KMS capability. + + + + + + + Driver load + + In the previous section, we saw what a typical drm_driver + structure might look like. One of the more important fields in + the structure is the hook for the load function. + + + static struct drm_driver driver = { + ... + .load = i915_driver_load, + ... + }; + + + The load function has many responsibilities: allocating a driver + private structure, specifying supported performance counters, + configuring the device (e.g. mapping registers & command + buffers), initializing the memory manager, and setting up the + initial output configuration. + + + Note that the tasks performed at driver load time must not + conflict with DRM client requirements. For instance, if user + level mode setting drivers are in use, it would be problematic + to perform output discovery & configuration at load time. + Likewise, if pre-memory management aware user level drivers are + in use, memory management and command buffer setup may need to + be omitted. These requirements are driver specific, and care + needs to be taken to keep both old and new applications and + libraries working. The i915 driver supports the "modeset" + module parameter to control whether advanced features are + enabled at load time or in legacy fashion. If compatibility is + a concern (e.g. with drivers converted over to the new interfaces + from the old ones), care must be taken to prevent incompatible + device initialization and control with the currently active + userspace drivers. + + + + Driver private & performance counters + + The driver private hangs off the main drm_device structure and + can be used for tracking various device specific bits of + information, like register offsets, command buffer status, + register state for suspend/resume, etc. At load time, a + driver can simply allocate one and set drm_device.dev_priv + appropriately; at unload the driver can free it and set + drm_device.dev_priv to NULL. + + + The DRM supports several counters which can be used for rough + performance characterization. Note that the DRM stat counter + system is not often used by applications, and supporting + additional counters is completely optional. + + + These interfaces are 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 to performance monitoring + tools and applications. + + + + + Configuring the device + + Obviously, device configuration will be device specific. + However, there are several common operations: finding a + device's PCI resources, mapping them, and potentially setting + up an IRQ handler. + + + Finding & mapping resources is fairly straightforward. The + DRM wrapper functions, drm_get_resource_start() and + drm_get_resource_len() can be used to find BARs on the given + drm_device struct. Once those values have been retrieved, the + driver load function can call drm_addmap() to create a new + mapping for the BAR in question. Note you'll probably want a + drm_local_map_t in your driver private structure to track any + mappings you create. + + + + + if compatibility with other operating systems isn't a concern + (DRM drivers can run under various BSD variants and OpenSolaris), + native Linux calls can be used for the above, e.g. pci_resource_* + and iomap*/iounmap. See the Linux device driver book for more + info. + + + Once you have a register map, you can use the DRM_READn() and + DRM_WRITEn() macros to access the registers on your device, or + use driver specific versions to offset into your MMIO space + relative to a driver specific base pointer (see I915_READ for + example). + + + If your device supports interrupt generation, you may want to + setup an interrupt handler at driver load time as well. This + is done using the drm_irq_install() function. If your device + supports vertical blank interrupts, it should call + drm_vblank_init() to initialize the core vblank handling code before + enabling interrupts on your device. This ensures the vblank related + structures are allocated and allows the core to handle vblank events. + + + + Once your interrupt handler is registered (it'll use your + drm_driver.irq_handler as the actual interrupt handling + function), you can safely enable interrupts on your device, + assuming any other state your interrupt handler uses is also + initialized. + + + Another task that may be necessary during configuration is + mapping the video BIOS. On many devices, the VBIOS describes + device configuration, LCD panel timings (if any), and contains + flags indicating device state. Mapping the BIOS can be done + using the pci_map_rom() call, a convenience function that + takes care of mapping the actual ROM, whether it has been + shadowed into memory (typically at address 0xc0000) or exists + on the PCI device in the ROM BAR. Note that once you've + mapped the ROM and extracted any necessary information, be + sure to unmap it; on many devices the ROM address decoder is + shared with other BARs, so leaving it mapped can cause + undesired behavior like hangs or memory corruption. + + + + + + Memory manager initialization + + In order to allocate command buffers, cursor memory, scanout + buffers, etc., as well as support the latest features provided + by packages like Mesa and the X.Org X server, your driver + should support a memory manager. + + + If your driver supports memory management (it should!), you'll + need to set that up at load time as well. How you intialize + it depends on which memory manager you're using, TTM or GEM. + + + TTM initialization + + TTM (for Translation Table Manager) manages video memory and + aperture space for graphics devices. TTM supports both UMA devices + and devices with dedicated video RAM (VRAM), i.e. most discrete + graphics devices. If your device has dedicated RAM, supporting + TTM is desireable. TTM also integrates tightly with your + driver specific buffer execution function. See the radeon + driver for examples. + + + The core TTM structure is the ttm_bo_driver struct. It contains + several fields with function pointers for initializing the TTM, + allocating and freeing memory, waiting for command completion + and fence synchronization, and memory migration. See the + radeon_ttm.c file for an example of usage. + + + The ttm_global_reference structure is made up of several fields: + + + struct ttm_global_reference { + enum ttm_global_types global_type; + size_t size; + void *object; + int (*init) (struct ttm_global_reference *); + void (*release) (struct ttm_global_reference *); + }; + + + There should be one global reference structure for your memory + manager as a whole, and there will be others for each object + created by the memory manager at runtime. Your global TTM should + have a type of TTM_GLOBAL_TTM_MEM. The size field for the global + object should be sizeof(struct ttm_mem_global), and the init and + release hooks should point at your driver specific init and + release routines, which will probably eventually call + ttm_mem_global_init and ttm_mem_global_release respectively. + + + Once your global TTM accounting structure is set up and initialized + (done by calling ttm_global_item_ref on the global object you + just created), you'll need to create a buffer object TTM to + provide a pool for buffer object allocation by clients and the + kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, + and its size should be sizeof(struct ttm_bo_global). Again, + driver specific init and release functions can be provided, + likely eventually calling ttm_bo_global_init and + ttm_bo_global_release, respectively. Also like the previous + object, ttm_global_item_ref is used to create an initial reference + count for the TTM, which will call your initalization function. + + + + GEM initialization + + GEM is an alternative to TTM, designed specifically for UMA + devices. It has simpler initialization and execution requirements + than TTM, but has no VRAM management capability. Core GEM + initialization is comprised of a basic drm_mm_init call to create + a GTT DRM MM object, which provides an address space pool for + object allocation. In a KMS configuration, the driver will + need to allocate and initialize a command ring buffer following + basic GEM initialization. Most UMA devices have a so-called + "stolen" memory region, which provides space for the initial + framebuffer and large, contiguous memory regions required by the + device. This space is not typically managed by GEM, and must + be initialized separately into its own DRM MM object. + + + Initialization will be driver specific, and will depend on + the architecture of the device. In the case of Intel + integrated graphics chips like 965GM, GEM initialization can + be done by calling the internal GEM init function, + i915_gem_do_init(). Since the 965GM is a UMA device + (i.e. it doesn't have dedicated VRAM), GEM will manage + making regular RAM available for GPU operations. Memory set + aside by the BIOS (called "stolen" memory by the i915 + driver) will be managed by the DRM memrange allocator; the + rest of the aperture will be managed by GEM. + + /* Basic memrange allocator for stolen space (aka vram) */ + drm_memrange_init(&dev_priv->vram, 0, prealloc_size); + /* Let GEM Manage from end of prealloc space to end of aperture */ + i915_gem_do_init(dev, prealloc_size, agp_size); + + + + + Once the memory manager has been set up, we can allocate the + command buffer. In the i915 case, this is also done with a + GEM function, i915_gem_init_ringbuffer(). + + + + + + Output configuration + + The final initialization task is output configuration. This involves + finding and initializing the CRTCs, encoders and connectors + for your device, creating an initial configuration and + registering a framebuffer console driver. + + + Output discovery and initialization + + Several core functions exist to create CRTCs, encoders and + connectors, namely drm_crtc_init(), drm_connector_init() and + drm_encoder_init(), along with several "helper" functions to + perform common tasks. + + + Connectors should be registered with sysfs once they've been + detected and initialized, using the + drm_sysfs_connector_add() function. Likewise, when they're + removed from the system, they should be destroyed with + drm_sysfs_connector_remove(). + + +base; + drm_connector_init(dev, &intel_output->base, + &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); + + drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, + DRM_MODE_ENCODER_DAC); + + drm_mode_connector_attach_encoder(&intel_output->base, + &intel_output->enc); + + /* Set up the DDC bus. */ + intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); + if (!intel_output->ddc_bus) { + dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " + "failed.\n"); + return; + } + + intel_output->type = INTEL_OUTPUT_ANALOG; + connector->interlace_allowed = 0; + connector->doublescan_allowed = 0; + + drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); + drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); + + drm_sysfs_connector_add(connector); +} +]]> + + + In the example above (again, taken from the i915 driver), a + CRT connector and encoder combination is created. A device + specific i2c bus is also created, for fetching EDID data and + performing monitor detection. Once the process is complete, + the new connector is regsitered with sysfs, to make its + properties available to applications. + + + Helper functions and core functions + + Since many PC-class graphics devices have similar display output + designs, the DRM provides a set of helper functions to make + output management easier. The core helper routines handle + encoder re-routing and disabling of unused functions following + mode set. Using the helpers is optional, but recommended for + devices with PC-style architectures (i.e. a set of display planes + for feeding pixels to encoders which are in turn routed to + connectors). Devices with more complex requirements needing + finer grained management can opt to use the core callbacks + directly. + + + [Insert typical diagram here.] [Insert OMAP style config here.] + + + + For each encoder, CRTC and connector, several functions must + be provided, depending on the object type. Encoder objects + need should provide a DPMS (basically on/off) function, mode fixup + (for converting requested modes into native hardware timings), + and prepare, set and commit functions for use by the core DRM + helper functions. Connector helpers need to provide mode fetch and + validity functions as well as an encoder matching function for + returing an ideal encoder for a given connector. The core + connector functions include a DPMS callback, (deprecated) + save/restore routines, detection, mode probing, property handling, + and cleanup functions. + + + + + + + + + + + + VBlank event handling + + The DRM core exposes two vertical blank related ioctls: + DRM_IOCTL_WAIT_VBLANK and DRM_IOCTL_MODESET_CTL. + + + + DRM_IOCTL_WAIT_VBLANK takes a struct drm_wait_vblank structure + as its argument, and is used to block or request a signal when a + specified vblank event occurs. + + + DRM_IOCTL_MODESET_CTL should be called by application level + drivers before and after mode setting, since on many devices the + vertical blank counter will be 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). + + + To support the functions above, the DRM core provides several + helper functions for tracking vertical blank counters, and + requires drivers to provide several callbacks: + get_vblank_counter(), enable_vblank() and disable_vblank(). The + core uses get_vblank_counter() to keep the counter accurate + across interrupt disable periods. It should return the current + vertical blank event count, which is often tracked in a device + register. The enable and disable vblank callbacks should enable + and disable vertical blank interrupts, respectively. In the + absence of DRM clients waiting on vblank events, the core DRM + code will use the disable_vblank() function to disable + interrupts, which saves power. They'll be re-enabled again when + a client calls the vblank wait ioctl above. + + + Devices that don't provide a count register can simply use an + internal atomic counter incremented on every vertical blank + interrupt, and can make their enable and disable vblank + functions into no-ops. + + + + + Memory management + + The memory manager lies at the heart of many DRM operations, and + is also required to support advanced client features like OpenGL + pbuffers. The DRM currently contains two memory managers, TTM + and GEM. + + + + The Translation Table Manager (TTM) + + TTM was developed by Tungsten Graphics, primarily by Thomas + Hellström, and is intended to be a flexible, high performance + graphics memory manager. + + + Drivers wishing to support TTM must fill out a drm_bo_driver + structure. + + + TTM design background and information belongs here. + + + + + The Graphics Execution Manager (GEM) + + GEM is an Intel project, authored by Eric Anholt and Keith + Packard. It provides simpler interfaces than TTM, and is well + suited for UMA devices. + + + GEM-enabled drivers must provide gem_init_object() and + gem_free_object() callbacks to support the core memory + allocation routines. They should also provide several driver + specific ioctls to support command execution, pinning, buffer + read & write, mapping, and domain ownership transfers. + + + On a fundamental level, GEM involves several operations: memory + allocation and freeing, command execution, and aperture management + at command execution time. Buffer object allocation is relatively + straightforward and largely provided by Linux's shmem layer, which + provides memory to back each object. When mapped into the GTT + or used in a command buffer, the backing pages for an object are + flushed to memory and marked write combined so as to be coherent + with the GPU. Likewise, when the GPU finishes rendering to an object, + if the CPU accesses it, it must be made coherent with the CPU's view + of memory, usually involving GPU cache flushing of various kinds. + This core CPU<->GPU coherency management is provided by the GEM + set domain function, which evaluates an object's current domain and + performs any necessary flushing or synchronization to put the object + into the desired coherency domain (note that the object may be busy, + i.e. an active render target; in that case the set domain function + will block the client and wait for rendering to complete before + performing any necessary flushing operations). + + + Perhaps the most important GEM function is providing a command + execution interface to clients. Client programs construct command + buffers containing references to previously allocated memory objects + and submit them to GEM. At that point, GEM will take care to bind + all the objects into the GTT, execute the buffer, and provide + necessary synchronization between clients accessing the same buffers. + This often involves evicting some objects from the GTT and re-binding + others (a fairly expensive operation), and providing relocation + support which hides fixed GTT offsets from clients. Clients must + take care not to submit command buffers that reference more objects + than can fit in the GTT or GEM will reject them and no rendering + will occur. Similarly, if several objects in the buffer require + fence registers to be allocated for correct rendering (e.g. 2D blits + on pre-965 chips), care must be taken not to require more fence + registers than are available to the client. Such resource management + should be abstracted from the client in libdrm. + + + + + + + + Output management + + At the core of the DRM output management code is a set of + structures representing CRTCs, encoders and connectors. + + + A CRTC is an abstraction representing a part of the chip that + contains a pointer to a scanout buffer. Therefore, the number + of CRTCs available determines how many independent scanout + buffers can be active at any given time. The CRTC structure + contains several fields to support this: a pointer to some video + memory, a display mode, and an (x, y) offset into the video + memory to support panning or configurations where one piece of + video memory spans multiple CRTCs. + + + An encoder takes pixel data from a CRTC and converts it to a + format suitable for any attached connectors. On some devices, + it may be possible to have a CRTC send data to more than one + encoder. In that case, both encoders would receive data from + the same scanout buffer, resulting in a "cloned" display + configuration across the connectors attached to each encoder. + + + A connector is the final destination for pixel data on a device, + and usually connects directly to an external display device like + a monitor or laptop panel. A connector can only be attached to + one encoder at a time. The connector is also the structure + where information about the attached display is kept, so it + contains fields for display data, EDID data, DPMS & + connection status, and information about modes supported on the + attached displays. + + + + + + Framebuffer management + + In order to set a mode on a given CRTC, encoder and connector + configuration, clients need to provide a framebuffer object which + will provide a source of pixels for the CRTC to deliver to the encoder(s) + and ultimately the connector(s) in the configuration. A framebuffer + is fundamentally a driver specific memory object, made into an opaque + handle by the DRM addfb function. Once an fb has been created this + way it can be passed to the KMS mode setting routines for use in + a configuration. + + + + + Command submission & fencing + + This should cover a few device specific command submission + implementations. + + + + + Suspend/resume + + The DRM core provides some suspend/resume code, but drivers + wanting full suspend/resume support should provide save() and + restore() functions. These will be called at suspend, + hibernate, or resume time, and should perform any state save or + restore required by your device across suspend or hibernate + states. + + + + + DMA services + + This should cover how DMA mapping etc. is supported by the core. + These functions are deprecated and should not be used. + + + + + + + + Userland interfaces + + The DRM core exports several interfaces to applications, + generally intended to be used through corresponding libdrm + wrapper functions. In addition, drivers export device specific + interfaces for use by userspace drivers & device aware + applications through ioctls and sysfs files. + + + External interfaces include: memory mapping, context management, + DMA operations, AGP management, vblank control, fence + management, memory management, and output management. + + + Cover generic ioctls and sysfs layout here. Only need high + level info, since man pages will cover the rest. + + + + + + + DRM Driver API + + Include auto-generated API reference here (need to reference it + from paragraphs above too). + + + + -- cgit v1.2.3 From a33f32244d8550da8b4a26e277ce07d5c6d158b5 Mon Sep 17 00:00:00 2001 From: Francis Galiegue Date: Fri, 23 Apr 2010 00:08:02 +0200 Subject: Documentation/: it's -> its where appropriate Fix obvious cases of "it's" being used when "its" was meant. Signed-off-by: Francis Galiegue Acked-by: Randy Dunlap Signed-off-by: Jiri Kosina --- Documentation/DocBook/libata.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index ba9975771503..261b57bc6f08 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -490,7 +490,7 @@ void (*host_stop) (struct ata_host_set *host_set); allocates space for a legacy IDE PRD table and returns. - ->port_stop() is called after ->host_stop(). It's sole function + ->port_stop() is called after ->host_stop(). Its sole function is to release DMA/memory resources, now that they are no longer actively being used. Many drivers also free driver-private data from port at this time. -- cgit v1.2.3 From 40868c85b8dfe233192f29099f45348f5b363ce9 Mon Sep 17 00:00:00 2001 From: Sergei Shtylyov Date: Wed, 5 May 2010 17:27:10 +0400 Subject: libata: Fix several inaccuracies in developer's guide Commit 6bfff31e77cfa1b13490337e5a4dbaa3407e83ac (libata: kill probe_ent and related helpers) killed ata_device_add() but didn't remove references to it from the libata developer's guide. Commits 9363c3825ea9ad76561eb48a395349dd29211ed6 (libata: rename SFF functions) and 5682ed33aae05d10a25c95633ef9d9c062825888 (libata: rename SFF port ops) renamed the taskfile access methods but didn't update the developer's guide. Commit c9f75b04ed5ed65a058d18a8a8dda50632a96de8 (libata: kill ata_noop_dev_select()) didn't update the developer's guide as well. The guide also refers to the long gone ata_pio_data_xfer_noirq(), ata_pio_data_xfer(), and ata_mmio_data_xfer() -- replace those by the modern ata_sff_data_xfer_noirq(), ata_sff_data_xfer(), and ata_sff_data_xfer32(). Also, remove the reference to non-existant ata_port_stop()... Signed-off-by: Sergei Shtylyov Signed-off-by: Jeff Garzik --- Documentation/DocBook/libata.tmpl | 49 +++++++++++++-------------------------- 1 file changed, 16 insertions(+), 33 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index ba9975771503..ff3e5bec1c24 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -107,10 +107,6 @@ void (*dev_config) (struct ata_port *, struct ata_device *); issue of SET FEATURES - XFER MODE, and prior to operation. - Called by ata_device_add() after ata_dev_identify() determines - a device is present. - - This entry may be specified as NULL in ata_port_operations. @@ -154,8 +150,8 @@ unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned in Taskfile read/write -void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); -void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); +void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); +void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); @@ -164,36 +160,35 @@ void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); hardware registers / DMA buffers, to obtain the current set of taskfile register values. Most drivers for taskfile-based hardware (PIO or MMIO) use - ata_tf_load() and ata_tf_read() for these hooks. + ata_sff_tf_load() and ata_sff_tf_read() for these hooks. PIO data read/write -void (*data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); +void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); All bmdma-style drivers must implement this hook. This is the low-level operation that actually copies the data bytes during a PIO data transfer. -Typically the driver -will choose one of ata_pio_data_xfer_noirq(), ata_pio_data_xfer(), or -ata_mmio_data_xfer(). +Typically the driver will choose one of ata_sff_data_xfer_noirq(), +ata_sff_data_xfer(), or ata_sff_data_xfer32(). ATA command execute -void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); +void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); causes an ATA command, previously loaded with ->tf_load(), to be initiated in hardware. - Most drivers for taskfile-based hardware use ata_exec_command() + Most drivers for taskfile-based hardware use ata_sff_exec_command() for this hook. @@ -218,8 +213,8 @@ command. Read specific ATA shadow registers -u8 (*check_status)(struct ata_port *ap); -u8 (*check_altstatus)(struct ata_port *ap); +u8 (*sff_check_status)(struct ata_port *ap); +u8 (*sff_check_altstatus)(struct ata_port *ap); @@ -227,20 +222,14 @@ u8 (*check_altstatus)(struct ata_port *ap); hardware. On some hardware, reading the Status register has the side effect of clearing the interrupt condition. Most drivers for taskfile-based hardware use - ata_check_status() for this hook. - - - Note that because this is called from ata_device_add(), at - least a dummy function that clears device interrupts must be - provided for all drivers, even if the controller doesn't - actually have a taskfile status register. + ata_sff_check_status() for this hook. Select ATA device on bus -void (*dev_select)(struct ata_port *ap, unsigned int device); +void (*sff_dev_select)(struct ata_port *ap, unsigned int device); @@ -251,9 +240,7 @@ void (*dev_select)(struct ata_port *ap, unsigned int device); Most drivers for taskfile-based hardware use - ata_std_dev_select() for this hook. Controllers which do not - support second drives on a port (such as SATA contollers) will - use ata_noop_dev_select(). + ata_sff_dev_select() for this hook. @@ -441,13 +428,13 @@ void (*irq_clear) (struct ata_port *); to struct ata_host_set. - Most legacy IDE drivers use ata_interrupt() for the + Most legacy IDE drivers use ata_sff_interrupt() for the irq_handler hook, which scans all ports in the host_set, determines which queued command was active (if any), and calls - ata_host_intr(ap,qc). + ata_sff_host_intr(ap,qc). - Most legacy IDE drivers use ata_bmdma_irq_clear() for the + Most legacy IDE drivers use ata_sff_irq_clear() for the irq_clear() hook, which simply clears the interrupt and error flags in the DMA status register. @@ -496,10 +483,6 @@ void (*host_stop) (struct ata_host_set *host_set); data from port at this time. - Many drivers use ata_port_stop() as this hook, which frees the - PRD table. - - ->host_stop() is called after all ->port_stop() calls have completed. The hook must finalize hardware shutdown, release DMA and other resources, etc. -- cgit v1.2.3 From a71ba09655d197f22938fffa6f5d210ff5134f98 Mon Sep 17 00:00:00 2001 From: Paul Mundt Date: Thu, 13 May 2010 18:42:25 +0900 Subject: sh: fixup the docbook paths for clock framework shuffling. Now that the definitions have been consolidated in an alternate header, update the template accordingly. Signed-off-by: Paul Mundt --- Documentation/DocBook/sh.tmpl | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl index 0c3dc4c69dd1..d858d92cf6d9 100644 --- a/Documentation/DocBook/sh.tmpl +++ b/Documentation/DocBook/sh.tmpl @@ -19,13 +19,17 @@ - 2008 + 2008-2010 Paul Mundt - 2008 + 2008-2010 Renesas Technology Corp. + + 2010 + Renesas Electronics Corp. + @@ -77,7 +81,7 @@ Clock Framework Extensions -!Iarch/sh/include/asm/clock.h +!Iinclude/linux/sh_clk.h Machine Specific Interfaces -- cgit v1.2.3 From 294440887b32c58d220fb54b73b7a58079b78f20 Mon Sep 17 00:00:00 2001 From: Sergei Shtylyov Date: Thu, 22 Apr 2010 20:03:35 +0400 Subject: libata-sff: kill unused ata_bus_reset() ... since I see no callers of it. Signed-off-by: Sergei Shtylyov Signed-off-by: Jeff Garzik --- Documentation/DocBook/libata.tmpl | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index ff3e5bec1c24..70b811e9f2ca 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -81,16 +81,14 @@ void (*port_disable) (struct ata_port *); - Called from ata_bus_probe() and ata_bus_reset() error paths, - as well as when unregistering from the SCSI module (rmmod, hot - unplug). + Called from ata_bus_probe() error path, as well as when + unregistering from the SCSI module (rmmod, hot unplug). This function should do whatever needs to be done to take the port out of use. In most cases, ata_port_disable() can be used as this hook. Called from ata_bus_probe() on a failed probe. - Called from ata_bus_reset() on a failed bus reset. Called from ata_scsi_release(). -- cgit v1.2.3 From 41dec29bcb05eb8ec396f70ce791c6e3e4ce4712 Mon Sep 17 00:00:00 2001 From: Sergei Shtylyov Date: Fri, 7 May 2010 22:47:50 +0400 Subject: libata: introduce sff_set_devctl() method The set of libata's taskfile access methods is clearly incomplete as it lacks a method to write to the device control register -- which forces drivers like 'pata_bf54x' and 'pata_scc' to implement more "high level" (and more weighty) methods like freeze() and postreset(). So, introduce the optional sff_set_devctl() method which the drivers only have to implement if the standard iowrite8() can't be used (just like the existing sff_check_altstatus() method) and make use of it in the freeze() and postreset() method implementations (I could also have used it in softreset() method but it also reads other taskfile registers without using tf_read() making that quite pointless); this makes freeze() method implementations in the 'pata_bf54x' and 'pata_scc' methods virtually identical to ata_sff_freeze(), so we can get rid of them completely. Signed-off-by: Sergei Shtylyov Signed-off-by: Jeff Garzik --- Documentation/DocBook/libata.tmpl | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index 70b811e9f2ca..828748c4e78d 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -225,6 +225,18 @@ u8 (*sff_check_altstatus)(struct ata_port *ap); + Write specific ATA shadow register + +void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); + + + + Write the device control ATA shadow register to the hardware. + Most drivers don't need to define this. + + + + Select ATA device on bus void (*sff_dev_select)(struct ata_port *ap, unsigned int device); -- cgit v1.2.3 From 9583183acbd40fc6e972ac39ae0a2173976f288e Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 13 Mar 2010 19:03:21 -0300 Subject: V4L/DVB: v4l doc: fix font of field name The field 'reserved' was not tagged as a 'structfield' as it should. This made the text a bit confusing. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/vidioc-reqbufs.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml index 1c0816372074..69800ae23348 100644 --- a/Documentation/DocBook/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml @@ -61,7 +61,7 @@ fields of the v4l2_requestbuffers structure. They set the type field to the respective stream or buffer type, the count field to the desired number of buffers, memory -must be set to the requested I/O method and the reserved array +must be set to the requested I/O method and the reserved array must be zeroed. When the ioctl is called with a pointer to this structure the driver will attempt to allocate the requested number of buffers and it stores the actual number -- cgit v1.2.3 From 7a01f6dbc7abb85a6ec048dd45db92ef1b91fe78 Mon Sep 17 00:00:00 2001 From: Devin Heitmueller Date: Thu, 11 Mar 2010 21:27:59 -0300 Subject: V4L/DVB: videodev2: introduce a common control for chroma gain Introduce a new control for modifying the chroma gain. This allows for user intervention in abnormal signal conditions cases where the decoder's chroma AGC cannot compensate and the value needs to be adjusted manually. This work was sponsored by EyeMagnet Limited. Signed-off-by: Devin Heitmueller Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/controls.xml | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml index f46450610412..e1bdbb6eff84 100644 --- a/Documentation/DocBook/v4l/controls.xml +++ b/Documentation/DocBook/v4l/controls.xml @@ -266,6 +266,12 @@ minimum value disables backlight compensation. boolean Chroma automatic gain control. + + V4L2_CID_CHROMA_GAIN + integer + Adjusts the Chroma gain control (for use when chroma AGC + is disabled). + V4L2_CID_COLOR_KILLER boolean -- cgit v1.2.3 From b3e212dcbddb10b44d472a5f4c23d5aa0b5876ca Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 22 Mar 2010 04:52:21 -0300 Subject: V4L/DVB: v4l: add V4L2_PIX_FMT_Y4 and V4L2_PIX_FMT_Y6 pixelformats Old 4 and 6 bit greyscale pixel formats for the old bw-qcam webcam. This is needed to convert it to V4L2. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/pixfmt.xml | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml index 885968d6a2fc..c4ad0a8e42dc 100644 --- a/Documentation/DocBook/v4l/pixfmt.xml +++ b/Documentation/DocBook/v4l/pixfmt.xml @@ -792,6 +792,18 @@ http://www.thedirks.org/winnov/ 'YYUV' unknown + + V4L2_PIX_FMT_Y4 + 'Y04 ' + Old 4-bit greyscale format. Only the least significant 4 bits of each byte are used, +the other bits are set to 0. + + + V4L2_PIX_FMT_Y6 + 'Y06 ' + Old 6-bit greyscale format. Only the least significant 6 bits of each byte are used, +the other bits are set to 0. + -- cgit v1.2.3 From 48213fe3f981d2cbccd926d6858fa9cf8617beed Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Wed, 20 Jan 2010 12:12:57 -0300 Subject: V4L/DVB: v4l: Add V4L2_CID_IRIS_ABSOLUTE and V4L2_CID_IRIS_RELATIVE controls Those control, as their names imply, control the camera aperture settings. Signed-off-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/compat.xml | 11 +++++++++++ Documentation/DocBook/v4l/controls.xml | 19 +++++++++++++++++++ Documentation/DocBook/v4l/videodev2.h.xml | 3 +++ 3 files changed, 33 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml index b9dbdf9e6d29..854235b5208e 100644 --- a/Documentation/DocBook/v4l/compat.xml +++ b/Documentation/DocBook/v4l/compat.xml @@ -2332,6 +2332,17 @@ more information. +
+ V4L2 in Linux 2.6.34 + + + Added +V4L2_CID_IRIS_ABSOLUTE and +V4L2_CID_IRIS_RELATIVE controls to the + Camera controls class. + + +
diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml index e1bdbb6eff84..7e0c68747134 100644 --- a/Documentation/DocBook/v4l/controls.xml +++ b/Documentation/DocBook/v4l/controls.xml @@ -1830,6 +1830,25 @@ wide-angle direction. The zoom speed unit is driver-specific. + + V4L2_CID_IRIS_ABSOLUTE  + integer + This control sets the +camera's aperture to the specified value. The unit is undefined. +Larger values open the iris wider, smaller values close it. + + + + + V4L2_CID_IRIS_RELATIVE  + integer + This control modifies the +camera's aperture by the specified amount. The unit is undefined. +Positive values open the iris one step further, negative values close +it one step further. This is a write-only control. + + + V4L2_CID_PRIVACY  boolean diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml index 068325940658..c18dfebedeff 100644 --- a/Documentation/DocBook/v4l/videodev2.h.xml +++ b/Documentation/DocBook/v4l/videodev2.h.xml @@ -1271,6 +1271,9 @@ enum v4l2_exposure_auto_type { #define V4L2_CID_PRIVACY (V4L2_CID_CAMERA_CLASS_BASE+16) +#define V4L2_CID_IRIS_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+17) +#define V4L2_CID_IRIS_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+18) + /* FM Modulator class control IDs */ #define V4L2_CID_FM_TX_CLASS_BASE (V4L2_CTRL_CLASS_FM_TX | 0x900) #define V4L2_CID_FM_TX_CLASS (V4L2_CTRL_CLASS_FM_TX | 1) -- cgit v1.2.3 From 860553023bfed0179b3fe5d01838635f54a314a3 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 6 Apr 2010 06:41:28 -0300 Subject: V4L/DVB: V4L2 Spec: fix V4L2_CTRL_TYPE_CTRL_CLASS documentation The spec says that the control ID for these types of controls is the same as that of the control class. But it should read: 'control class + 1'. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/vidioc-queryctrl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml index 4876ff1a1a04..8e0e055ac934 100644 --- a/Documentation/DocBook/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/v4l/vidioc-queryctrl.xml @@ -325,7 +325,7 @@ should be part of the control documentation. n/a This is not a control. When VIDIOC_QUERYCTRL is called with a control ID -equal to a control class code (see ), the +equal to a control class code (see ) + 1, the ioctl returns the name of the control class and this control type. Older drivers which do not support this feature return an &EINVAL;. -- cgit v1.2.3 From e426e8663f028272b99f91e57bbbab6fda603bf1 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 6 Apr 2010 10:32:19 -0300 Subject: V4L/DVB: DocBook/v4l/compat.xml: add missing
The indentation of the sections had gone wrong, causing a mistake with section nesting. Fixed. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/compat.xml | 115 ++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 57 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml index 854235b5208e..b42b935913cd 100644 --- a/Documentation/DocBook/v4l/compat.xml +++ b/Documentation/DocBook/v4l/compat.xml @@ -2343,15 +2343,15 @@ more information. - + -
- Relation of V4L2 to other Linux multimedia APIs +
+ Relation of V4L2 to other Linux multimedia APIs -
- X Video Extension +
+ X Video Extension - The X Video Extension (abbreviated XVideo or just Xv) is + The X Video Extension (abbreviated XVideo or just Xv) is an extension of the X Window system, implemented for example by the XFree86 project. Its scope is similar to V4L2, an API to video capture and output devices for X clients. Xv allows applications to display @@ -2362,7 +2362,7 @@ capture or output still images in XPixmaps extension available across many operating systems and architectures. - Because the driver is embedded into the X server Xv has a + Because the driver is embedded into the X server Xv has a number of advantages over the V4L2 video overlay interface. The driver can easily determine the overlay target, &ie; visible graphics memory or off-screen buffers for a @@ -2371,16 +2371,16 @@ overlay, scaling or color-keying, or the clipping functions of the video capture hardware, always in sync with drawing operations or windows moving or changing their stacking order. - To combine the advantages of Xv and V4L a special Xv + To combine the advantages of Xv and V4L a special Xv driver exists in XFree86 and XOrg, just programming any overlay capable Video4Linux device it finds. To enable it /etc/X11/XF86Config must contain these lines: - + Section "Module" Load "v4l" EndSection - As of XFree86 4.2 this driver still supports only V4L + As of XFree86 4.2 this driver still supports only V4L ioctls, however it should work just fine with all V4L2 devices through the V4L2 backward-compatibility layer. Since V4L2 permits multiple opens it is possible (if supported by the V4L2 driver) to capture @@ -2388,83 +2388,84 @@ video while an X client requested video overlay. Restrictions of simultaneous capturing and overlay are discussed in apply. - Only marginally related to V4L2, XFree86 extended Xv to + Only marginally related to V4L2, XFree86 extended Xv to support hardware YUV to RGB conversion and scaling for faster video playback, and added an interface to MPEG-2 decoding hardware. This API is useful to display images captured with V4L2 devices. -
+
-
- Digital Video +
+ Digital Video - V4L2 does not support digital terrestrial, cable or + V4L2 does not support digital terrestrial, cable or satellite broadcast. A separate project aiming at digital receivers exists. You can find its homepage at http://linuxtv.org. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both. -
+
-
- Audio Interfaces +
+ Audio Interfaces - [to do - OSS/ALSA] + [to do - OSS/ALSA] +
-
-
- Experimental API Elements +
+ Experimental API Elements - The following V4L2 API elements are currently experimental + The following V4L2 API elements are currently experimental and may change in the future. - - - Video Output Overlay (OSD) Interface, + + Video Output Overlay (OSD) Interface, . - + - V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY, + V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY, &v4l2-buf-type;, . - - - V4L2_CAP_VIDEO_OUTPUT_OVERLAY, + + + V4L2_CAP_VIDEO_OUTPUT_OVERLAY, &VIDIOC-QUERYCAP; ioctl, . - - - &VIDIOC-ENUM-FRAMESIZES; and + + + &VIDIOC-ENUM-FRAMESIZES; and &VIDIOC-ENUM-FRAMEINTERVALS; ioctls. - - - &VIDIOC-G-ENC-INDEX; ioctl. - - - &VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; + + + &VIDIOC-G-ENC-INDEX; ioctl. + + + &VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; ioctls. - - - &VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; + + + &VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; ioctls. - - - &VIDIOC-DBG-G-CHIP-IDENT; ioctl. - - -
+ + + &VIDIOC-DBG-G-CHIP-IDENT; ioctl. + + +
-
- Obsolete API Elements +
+ Obsolete API Elements - The following V4L2 API elements were superseded by new + The following V4L2 API elements were superseded by new interfaces and should not be implemented in new drivers. - - - VIDIOC_G_MPEGCOMP and + + + VIDIOC_G_MPEGCOMP and VIDIOC_S_MPEGCOMP ioctls. Use Extended Controls, . - - + + +
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml index 060105af49e5..9737243377a3 100644 --- a/Documentation/DocBook/v4l/v4l2.xml +++ b/Documentation/DocBook/v4l/v4l2.xml @@ -401,6 +401,7 @@ and discussions on the V4L mailing list.
&sub-dev-teletext;
&sub-dev-radio;
&sub-dev-rds;
+
&sub-dev-event;
@@ -426,6 +427,7 @@ and discussions on the V4L mailing list. &sub-cropcap; &sub-dbg-g-chip-ident; &sub-dbg-g-register; + &sub-dqevent; &sub-encoder-cmd; &sub-enumaudio; &sub-enumaudioout; @@ -467,6 +469,7 @@ and discussions on the V4L mailing list. &sub-reqbufs; &sub-s-hw-freq-seek; &sub-streamon; + &sub-subscribe-event; &sub-mmap; &sub-munmap; diff --git a/Documentation/DocBook/v4l/vidioc-dqevent.xml b/Documentation/DocBook/v4l/vidioc-dqevent.xml new file mode 100644 index 000000000000..eb45c1695d8c --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dqevent.xml @@ -0,0 +1,124 @@ + + + ioctl VIDIOC_DQEVENT + &manvol; + + + + VIDIOC_DQEVENT + Dequeue event + + + + + + int ioctl + int fd + int request + struct v4l2_event +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_DQEVENT + + + + argp + + + + + + + + + Description + + Dequeue an event from a video device. No input is required + for this ioctl. All the fields of the &v4l2-event; structure are + filled by the driver. The file handle will also receive exceptions + which the application may get by e.g. using the select system + call. + + + struct <structname>v4l2_event</structname> + + &cs-str; + + + __u32 + type + + Type of the event. + + + union + u + + + + + + __u8 + data[64] + Event data. Defined by the event type. The union + should be used to define easily accessible type for + events. + + + __u32 + pending + + Number of pending events excluding this one. + + + __u32 + sequence + + Event sequence number. The sequence number is + incremented for every subscribed event that takes place. + If sequence numbers are not contiguous it means that + events have been lost. + + + + struct timeval + timestamp + + Event timestamp. + + + __u32 + reserved[9] + + Reserved for future extensions. Drivers must set + the array to zero. + + + +
+ + + + diff --git a/Documentation/DocBook/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml new file mode 100644 index 000000000000..71ab88cb76b3 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml @@ -0,0 +1,104 @@ + + + ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + &manvol; + + + + VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + Subscribe or unsubscribe event + + + + + + int ioctl + int fd + int request + struct v4l2_event_subscription +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + + + + argp + + + + + + + + + Description + + Subscribe or unsubscribe V4L2 event. Subscribed events are + dequeued by using the &VIDIOC-DQEVENT; ioctl. + + + struct <structname>v4l2_event_subscription</structname> + + &cs-str; + + + __u32 + type + Type of the event. + + + __u32 + reserved[7] + Reserved for future extensions. Drivers and applications + must set the array to zero. + + + +
+ + + Event Types + + &cs-def; + + + V4L2_EVENT_ALL + 0 + All events. V4L2_EVENT_ALL is valid only for + VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. + + + + V4L2_EVENT_PRIVATE_START + 0x08000000 + Base event number for driver-private events. + + + +
+ + + + -- cgit v1.2.3 From 37089368c1b1bea3c71217163e6d5d3b01ef1f19 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 27 Mar 2010 14:10:37 -0300 Subject: V4L/DVB: v4l spec: document what odd and even fields are Document that odd == top and even == bottom. I can never remember this, so it is probably worth documenting. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/io.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml index e870330cbf77..bb685ed6fe7b 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -918,8 +918,8 @@ order. When the driver provides or accepts images field by field rather than interleaved, it is also important applications understand -how the fields combine to frames. We distinguish between top and -bottom fields, the spatial order: The first line +how the fields combine to frames. We distinguish between top (aka odd) and +bottom (aka even) fields, the spatial order: The first line of the top field is the first line of an interlaced frame, the first line of the bottom field is the second line of that frame. @@ -972,12 +972,12 @@ between V4L2_FIELD_TOP and V4L2_FIELD_TOP 2 - Images consist of the top field only. + Images consist of the top (aka odd) field only. V4L2_FIELD_BOTTOM 3 - Images consist of the bottom field only. + Images consist of the bottom (aka even) field only. Applications may wish to prevent a device from capturing interlaced images because they will have "comb" or "feathering" artefacts around moving objects. -- cgit v1.2.3 From 0e1de38db83606d802cf2b3e00cf95fc693b8ca2 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 27 Mar 2010 14:10:57 -0300 Subject: V4L/DVB: v4l spec: document new events Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media-entities.tmpl | 2 ++ Documentation/DocBook/v4l/vidioc-dqevent.xml | 9 ++++++- .../DocBook/v4l/vidioc-subscribe-event.xml | 29 ++++++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index 770be3c3ba75..5d4d40f429a5 100644 --- a/Documentation/DocBook/media-entities.tmpl +++ b/Documentation/DocBook/media-entities.tmpl @@ -85,6 +85,7 @@ VIDIOC_TRY_ENCODER_CMD"> VIDIOC_TRY_EXT_CTRLS"> VIDIOC_TRY_FMT"> +VIDIOC_UNSUBSCRIBE_EVENT"> v4l2_std_id"> @@ -145,6 +146,7 @@ v4l2_encoder_cmd"> v4l2_event"> v4l2_event_subscription"> +v4l2_event_vsync"> v4l2_ext_control"> v4l2_ext_controls"> v4l2_fmtdesc"> diff --git a/Documentation/DocBook/v4l/vidioc-dqevent.xml b/Documentation/DocBook/v4l/vidioc-dqevent.xml index eb45c1695d8c..4e0a7cc30812 100644 --- a/Documentation/DocBook/v4l/vidioc-dqevent.xml +++ b/Documentation/DocBook/v4l/vidioc-dqevent.xml @@ -72,6 +72,13 @@ + + + &v4l2-event-vsync; + vsync + Event data for event V4L2_EVENT_VSYNC. + + __u8 @@ -97,7 +104,7 @@ - struct timeval + struct timespec timestamp Event timestamp. diff --git a/Documentation/DocBook/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml index 71ab88cb76b3..8b501791aa68 100644 --- a/Documentation/DocBook/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml @@ -84,6 +84,21 @@ VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. + + V4L2_EVENT_VSYNC + 1 + This event is triggered on the vertical sync. + This event has &v4l2-event-vsync; associated with it. + + + + V4L2_EVENT_EOS + 2 + This event is triggered when the end of a stream is reached. + This is typically used with MPEG decoders to report to the application + when the last of the MPEG stream has been decoded. + + V4L2_EVENT_PRIVATE_START 0x08000000 @@ -93,6 +108,20 @@ + + struct <structname>v4l2_event_vsync</structname> + + &cs-str; + + + __u8 + field + The upcoming field. See &v4l2-field;. + + + +
+