From 03dd4cb26d967f9588437b0fc9cc0e8353322bb7 Mon Sep 17 00:00:00 2001 From: André Fabian Silva Delgado Date: Fri, 25 Mar 2016 03:53:42 -0300 Subject: Linux-libre 4.5-gnu --- Documentation/DocBook/Makefile | 10 +- Documentation/DocBook/device-drivers.tmpl | 85 +- Documentation/DocBook/gpu.tmpl | 1003 +++----------------- Documentation/DocBook/iio.tmpl | 2 +- Documentation/DocBook/media/Makefile | 6 +- Documentation/DocBook/media/dvb/dvbproperty.xml | 2 +- Documentation/DocBook/media/dvb/examples.xml | 2 +- Documentation/DocBook/media/dvb/intro.xml | 2 +- Documentation/DocBook/media/v4l/capture.c.xml | 2 +- Documentation/DocBook/media/v4l/compat.xml | 2 +- Documentation/DocBook/media/v4l/io.xml | 10 +- .../DocBook/media/v4l/media-controller.xml | 44 +- .../DocBook/media/v4l/media-ioc-enum-entities.xml | 104 +- .../DocBook/media/v4l/media-ioc-enum-links.xml | 56 -- .../DocBook/media/v4l/media-ioc-g-topology.xml | 394 ++++++++ Documentation/DocBook/media/v4l/media-types.xml | 236 +++++ Documentation/DocBook/media/v4l/v4l2.xml | 10 + .../DocBook/media/v4l/vidioc-create-bufs.xml | 30 +- .../DocBook/media/v4l/vidioc-dbg-g-chip-info.xml | 2 +- .../DocBook/media/v4l/vidioc-dbg-g-register.xml | 2 +- Documentation/DocBook/media/v4l/vidioc-enumstd.xml | 2 +- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 28 +- Documentation/DocBook/media_api.tmpl | 6 +- Documentation/DocBook/mtdnand.tmpl | 35 +- 24 files changed, 881 insertions(+), 1194 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/media-ioc-g-topology.xml create mode 100644 Documentation/DocBook/media/v4l/media-types.xml (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 91f6d89bb..d70f9b681 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -50,8 +50,7 @@ pdfdocs: $(PDF) HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) htmldocs: $(HTML) - $(call build_main_index) - $(call build_images) + $(call cmd,build_main_index) $(call install_media_images) MAN := $(patsubst %.xml, %.9, $(BOOKS)) @@ -139,7 +138,8 @@ quiet_cmd_db2pdf = PDF $@ index = index.html main_idx = $(obj)/$(index) -build_main_index = rm -rf $(main_idx); \ +quiet_cmd_build_main_index = HTML $(main_idx) + cmd_build_main_index = rm -rf $(main_idx); \ echo '

Linux Kernel HTML Documentation

' >> $(main_idx) && \ echo '

Kernel Version: $(KERNELVERSION)

' >> $(main_idx) && \ cat $(HTML) >> $(main_idx) @@ -227,6 +227,10 @@ dochelp: @echo ' mandocs - man pages' @echo ' installmandocs - install man pages generated by mandocs' @echo ' cleandocs - clean all generated DocBook files' + @echo + @echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' + @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' + ### # Temporary files left by various tools diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 42a2d8593..cdd8b24db 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -238,83 +238,32 @@ X!Isound/sound_firmware.c !Iinclude/media/videobuf2-memops.h Digital TV (DVB) devices -!Idrivers/media/dvb-core/dvb_ca_en50221.h -!Idrivers/media/dvb-core/dvb_frontend.h + Digital TV Common functions !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h !Idrivers/media/dvb-core/dvbdev.h - Digital TV Demux API - The kernel demux API defines a driver-internal interface for - registering low-level, hardware specific driver to a hardware - independent demux layer. It is only of interest for Digital TV - device driver writers. The header file for this API is named - demux.h and located in - drivers/media/dvb-core. - - The demux API should be implemented for each demux in the - system. It is used to select the TS source of a demux and to manage - the demux resources. When the demux client allocates a resource via - the demux API, it receives a pointer to the API of that - resource. - Each demux receives its TS input from a DVB front-end or from - memory, as set via this demux API. In a system with more than one - front-end, the API can be used to select one of the DVB front-ends - as a TS source for a demux, unless this is fixed in the HW platform. - The demux API only controls front-ends regarding to their connections - with demuxes; the APIs used to set the other front-end parameters, - such as tuning, are not defined in this document. - The functions that implement the abstract interface demux should - be defined static or module private and registered to the Demux - core for external access. It is not necessary to implement every - function in the struct dmx_demux. For example, - a demux interface might support Section filtering, but not PES - filtering. The API client is expected to check the value of any - function pointer before calling the function: the value of NULL means - that the “function is not available”. - Whenever the functions of the demux API modify shared data, - the possibilities of lost update and race condition problems should - be addressed, e.g. by protecting parts of code with mutexes. - Note that functions called from a bottom half context must not - sleep. Even a simple memory allocation without using GFP_ATOMIC can - result in a kernel thread being put to sleep if swapping is needed. - For example, the Linux kernel calls the functions of a network device - interface from a bottom half context. Thus, if a demux API function - is called from network device code, the function must not sleep. - - - -
- Demux Callback API - This kernel-space API comprises the callback functions that - deliver filtered data to the demux client. Unlike the other DVB - kABIs, these functions are provided by the client and called from - the demux code. - The function pointers of this abstract interface are not - packed into a structure as in the other demux APIs, because the - callback functions are registered and used independent of each - other. As an example, it is possible for the API client to provide - several callback functions for receiving TS packets and no - callbacks for PES packets or sections. - The functions that implement the callback API need not be - re-entrant: when a demux driver calls one of these functions, - the driver is not allowed to call the function again before - the original call returns. If a callback is triggered by a - hardware interrupt, it is recommended to use the Linux - “bottom half” mechanism or start a tasklet instead of - making the callback function call directly from a hardware - interrupt. - This mechanism is implemented by - dmx_ts_cb() and - dmx_section_cb(). -
- + + Digital TV Frontend kABI +!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend +!Idrivers/media/dvb-core/dvb_frontend.h + + Digital TV Demux kABI +!Pdrivers/media/dvb-core/demux.h Digital TV Demux + Demux Callback API +!Pdrivers/media/dvb-core/demux.h Demux Callback + !Idrivers/media/dvb-core/demux.h - + + Digital TV Conditional Access kABI +!Idrivers/media/dvb-core/dvb_ca_en50221.h + + Remote Controller devices !Iinclude/media/rc-core.h !Iinclude/media/lirc_dev.h Media Controller devices +!Pinclude/media/media-device.h Media Controller !Iinclude/media/media-device.h !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 201dcd3c2..a8669330b 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -124,6 +124,43 @@ [Insert diagram of typical DRM stack here] + + Style Guidelines + + For consistency this documentation uses American English. Abbreviations + are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so + on. To aid in reading, documentations make full use of the markup + characters kerneldoc provides: @parameter for function parameters, @member + for structure members, &structure to reference structures and + function() for functions. These all get automatically hyperlinked if + kerneldoc for the referenced objects exists. When referencing entries in + function vtables please use ->vfunc(). Note that kerneldoc does + not support referencing struct members directly, so please add a reference + to the vtable struct somewhere in the same paragraph or at least section. + + + Except in special situations (to separate locked from unlocked variants) + locking requirements for functions aren't documented in the kerneldoc. + Instead locking should be check at runtime using e.g. + WARN_ON(!mutex_is_locked(...));. Since it's much easier to + ignore documentation than runtime noise this provides more value. And on + top of that runtime checks do need to be updated when the locking rules + change, increasing the chances that they're correct. Within the + documentation the locking rules should be explained in the relevant + structures: Either in the comment for the lock explaining what it + protects, or data fields need a note about which lock protects them, or + both. + + + Functions which have a non-void return value should have a + section called "Returns" explaining the expected return values in + different cases and their meanings. Currently there's no consensus whether + that section name should be all upper-case or not, and whether it should + end in a colon or not. Go with the file-local style. Other common section + names are "Notes" with information for dangerous or tricky corner cases, + and "FIXME" where the interface could be cleaned up. + + @@ -615,18 +652,6 @@ char *date; drm_gem_object_init. Storage for private GEM objects must be managed by drivers. - - Drivers that do not need to extend GEM objects with private information - can call the drm_gem_object_alloc function to - allocate and initialize a struct drm_gem_object - instance. The GEM core will call the optional driver - gem_init_object operation after initializing - the GEM object with drm_gem_object_init. - int (*gem_init_object) (struct drm_gem_object *obj); - - - No alloc-and-init function exists for private GEM objects. - GEM Objects Lifetime @@ -635,10 +660,10 @@ char *date; acquired and release by calling drm_gem_object_reference and drm_gem_object_unreference respectively. The caller must hold the drm_device - struct_mutex lock. As a convenience, GEM - provides the drm_gem_object_reference_unlocked and - drm_gem_object_unreference_unlocked functions that - can be called without holding the lock. + struct_mutex lock when calling + drm_gem_object_reference. As a convenience, GEM + provides drm_gem_object_unreference_unlocked + functions that can be called without holding the lock. When the last reference to a GEM object is released the GEM core calls @@ -649,15 +674,9 @@ char *date; void (*gem_free_object) (struct drm_gem_object *obj); - Drivers are responsible for freeing all GEM object resources, including - the resources created by the GEM core. If an mmap offset has been - created for the object (in which case - drm_gem_object::map_list::map - is not NULL) it must be freed by a call to - drm_gem_free_mmap_offset. The shmfs backing store - must be released by calling drm_gem_object_release - (that function can safely be called if no shmfs backing store has been - created). + Drivers are responsible for freeing all GEM object resources. This includes + the resources created by the GEM core, which need to be released with + drm_gem_object_release. @@ -740,17 +759,10 @@ char *date; DRM identifies the GEM object to be mapped by a fake offset passed through the mmap offset argument. Prior to being mapped, a GEM object must thus be associated with a fake offset. To do so, drivers must call - drm_gem_create_mmap_offset on the object. The - function allocates a fake offset range from a pool and stores the - offset divided by PAGE_SIZE in - obj->map_list.hash.key. Care must be taken not to - call drm_gem_create_mmap_offset if a fake offset - has already been allocated for the object. This can be tested by - obj->map_list.map being non-NULL. + drm_gem_create_mmap_offset on the object. Once allocated, the fake offset value - (obj->map_list.hash.key << PAGE_SHIFT) must be passed to the application in a driver-specific way and can then be used as the mmap offset argument. @@ -836,10 +848,11 @@ char *date; abstracted from the client in libdrm. - - GEM Function Reference + + + GEM Function Reference !Edrivers/gpu/drm/drm_gem.c - +!Iinclude/drm/drm_gem.h VMA Offset Manager @@ -970,12 +983,10 @@ int max_width, max_height; Atomic Mode Setting Function Reference !Edrivers/gpu/drm/drm_atomic.c +!Idrivers/gpu/drm/drm_atomic.c - Frame Buffer Creation - struct drm_framebuffer *(*fb_create)(struct drm_device *dev, - struct drm_file *file_priv, - struct drm_mode_fb_cmd2 *mode_cmd); + Frame Buffer Abstraction Frame buffers are abstract memory objects that provide a source of pixels to scanout to a CRTC. Applications explicitly request the @@ -993,73 +1004,6 @@ int max_width, max_height; handles, e.g. vmwgfx directly exposes special TTM handles to userspace and so expects TTM handles in the create ioctl and not GEM handles. - - Drivers must first validate the requested frame buffer parameters passed - through the mode_cmd argument. In particular this is where invalid - sizes, pixel formats or pitches can be caught. - - - If the parameters are deemed valid, drivers then create, initialize and - return an instance of struct drm_framebuffer. - If desired the instance can be embedded in a larger driver-specific - structure. Drivers must fill its width, - height, pitches, - offsets, depth, - bits_per_pixel and - pixel_format fields from the values passed - through the drm_mode_fb_cmd2 argument. They - should call the drm_helper_mode_fill_fb_struct - helper function to do so. - - - - The initialization of the new framebuffer instance is finalized with a - call to drm_framebuffer_init which takes a pointer - to DRM frame buffer operations (struct - drm_framebuffer_funcs). Note that this function - publishes the framebuffer and so from this point on it can be accessed - concurrently from other threads. Hence it must be the last step in the - driver's framebuffer initialization sequence. Frame buffer operations - are - - - int (*create_handle)(struct drm_framebuffer *fb, - struct drm_file *file_priv, unsigned int *handle); - - Create a handle to the frame buffer underlying memory object. If - the frame buffer uses a multi-plane format, the handle will - reference the memory object associated with the first plane. - - - Drivers call drm_gem_handle_create to create - the handle. - - - - void (*destroy)(struct drm_framebuffer *framebuffer); - - Destroy the frame buffer object and frees all associated - resources. Drivers must call - drm_framebuffer_cleanup to free resources - allocated by the DRM core for the frame buffer object, and must - make sure to unreference all memory objects associated with the - frame buffer. Handles created by the - create_handle operation are released by - the DRM core. - - - - int (*dirty)(struct drm_framebuffer *framebuffer, - struct drm_file *file_priv, unsigned flags, unsigned color, - struct drm_clip_rect *clips, unsigned num_clips); - - This optional operation notifies the driver that a region of the - frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB - ioctl call. - - - - The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with @@ -1197,137 +1141,6 @@ int max_width, max_height; pointer to CRTC functions. - - CRTC Operations - - Set Configuration - int (*set_config)(struct drm_mode_set *set); - - Apply a new CRTC configuration to the device. The configuration - specifies a CRTC, a frame buffer to scan out from, a (x,y) position in - the frame buffer, a display mode and an array of connectors to drive - with the CRTC if possible. - - - If the frame buffer specified in the configuration is NULL, the driver - must detach all encoders connected to the CRTC and all connectors - attached to those encoders and disable them. - - - This operation is called with the mode config lock held. - - - 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: - drm_helper_resume_force_mode. - - - - Page Flipping - int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, - struct drm_pending_vblank_event *event); - - Schedule a page flip to the given frame buffer for the CRTC. This - operation is called with the mode config mutex held. - - - Page flipping is a synchronization mechanism that replaces the frame - buffer being scanned out by the CRTC with a new frame buffer during - vertical blanking, avoiding tearing. When an application requests a page - flip the DRM core verifies that the new frame buffer is large enough to - be scanned out by the CRTC in the currently configured mode and then - calls the CRTC page_flip operation with a - pointer to the new frame buffer. - - - The page_flip operation schedules a page flip. - Once any pending rendering targeting the new frame buffer has - completed, the CRTC will be reprogrammed to display that frame buffer - after the next vertical refresh. The operation must return immediately - without waiting for rendering or page flip to complete and must block - any new rendering to the frame buffer until the page flip completes. - - - If a page flip can be successfully scheduled the driver must set the - drm_crtc->fb field to the new framebuffer pointed to - by fb. This is important so that the reference counting - on framebuffers stays balanced. - - - If a page flip is already pending, the - page_flip operation must return - -EBUSY. - - - To synchronize page flip to vertical blanking the driver will likely - need to enable vertical blanking interrupts. It should call - drm_vblank_get for that purpose, and call - drm_vblank_put after the page flip completes. - - - If the application has requested to be notified when page flip completes - the page_flip operation will be called with a - non-NULL event argument pointing to a - drm_pending_vblank_event instance. Upon page - flip completion the driver must call drm_send_vblank_event - to fill in the event and send to wake up any waiting processes. - This can be performed with - event_lock, flags); - ... - drm_send_vblank_event(dev, pipe, event); - spin_unlock_irqrestore(&dev->event_lock, flags); - ]]> - - - FIXME: Could drivers that don't need to wait for rendering to complete - just add the event to dev->vblank_event_list and - let the DRM core handle everything, as for "normal" vertical blanking - events? - - - While waiting for the page flip to complete, the - event->base.link list head can be used freely by - the driver to store the pending event in a driver-specific list. - - - If the file handle is closed before the event is signaled, drivers must - take care to destroy the event in their - preclose operation (and, if needed, call - drm_vblank_put). - - - - Miscellaneous - - - void (*set_property)(struct drm_crtc *crtc, - struct drm_property *property, uint64_t value); - - Set the value of the given CRTC property to - value. See - for more information about properties. - - - - void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, - uint32_t start, uint32_t size); - - Apply a gamma table to the device. The operation is optional. - - - - void (*destroy)(struct drm_crtc *crtc); - - Destroy the CRTC when not needed anymore. See - . - - - - - Planes (struct <structname>drm_plane</structname>) @@ -1344,7 +1157,7 @@ int max_width, max_height; DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary planes are the planes operated upon by CRTC modesetting and flipping - operations described in . + operations described in the page_flip hook in drm_crtc_funcs. DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor @@ -1381,52 +1194,6 @@ int max_width, max_height; primary plane with standard capabilities. - - Plane Operations - - - int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, - struct drm_framebuffer *fb, int crtc_x, int crtc_y, - unsigned int crtc_w, unsigned int crtc_h, - uint32_t src_x, uint32_t src_y, - uint32_t src_w, uint32_t src_h); - - Enable and configure the plane to use the given CRTC and frame buffer. - - - The source rectangle in frame buffer memory coordinates is given by - the src_x, src_y, - src_w and src_h - parameters (as 16.16 fixed point values). Devices that don't support - subpixel plane coordinates can ignore the fractional part. - - - The destination rectangle in CRTC coordinates is given by the - crtc_x, crtc_y, - crtc_w and crtc_h - parameters (as integer values). Devices scale the source rectangle to - the destination rectangle. If scaling is not supported, and the source - rectangle size doesn't match the destination rectangle size, the - driver must return a -EINVAL error. - - - - int (*disable_plane)(struct drm_plane *plane); - - Disable the plane. The DRM core calls this method in response to a - DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. - Disabled planes must not be processed by the CRTC. - - - - void (*destroy)(struct drm_plane *plane); - - Destroy the plane when not needed anymore. See - . - - - - Encoders (struct <structname>drm_encoder</structname>) @@ -1483,27 +1250,6 @@ int max_width, max_height; encoders they want to use to a CRTC. - - Encoder Operations - - - void (*destroy)(struct drm_encoder *encoder); - - Called to destroy the encoder when not needed anymore. See - . - - - - void (*set_property)(struct drm_plane *plane, - struct drm_property *property, uint64_t value); - - Set the value of the given plane property to - value. See - for more information about properties. - - - - Connectors (struct <structname>drm_connector</structname>) @@ -1707,27 +1453,6 @@ int max_width, max_height; connector_status_unknown. - - Miscellaneous - - - void (*set_property)(struct drm_connector *connector, - struct drm_property *property, uint64_t value); - - Set the value of the given connector property to - value. See - for more information about properties. - - - - void (*destroy)(struct drm_connector *connector); - - Destroy the connector when not needed anymore. See - . - - - - @@ -1853,462 +1578,6 @@ void intel_crt_init(struct drm_device *dev) To use it, a driver must provide bottom functions for all of the three KMS entities. - - Helper Functions - - - int drm_crtc_helper_set_config(struct drm_mode_set *set); - - The drm_crtc_helper_set_config helper function - is a CRTC set_config implementation. It - first tries to locate the best encoder for each connector by calling - the connector best_encoder helper - operation. - - - After locating the appropriate encoders, the helper function will - call the mode_fixup encoder and CRTC helper - operations to adjust the requested mode, or reject it completely in - which case an error will be returned to the application. If the new - configuration after mode adjustment is identical to the current - configuration the helper function will return without performing any - other operation. - - - If the adjusted mode is identical to the current mode but changes to - the frame buffer need to be applied, the - drm_crtc_helper_set_config function will call - the CRTC mode_set_base helper operation. If - the adjusted mode differs from the current mode, or if the - mode_set_base helper operation is not - provided, the helper function performs a full mode set sequence by - calling the prepare, - mode_set and - commit CRTC and encoder helper operations, - in that order. - - - - void drm_helper_connector_dpms(struct drm_connector *connector, int mode); - - The drm_helper_connector_dpms helper function - is a connector dpms implementation that - tracks power state of connectors. To use the function, drivers must - provide dpms helper operations for CRTCs - and encoders to apply the DPMS state to the device. - - - The mid-layer doesn't track the power state of CRTCs and encoders. - The dpms helper operations can thus be - called with a mode identical to the currently active mode. - - - - int drm_helper_probe_single_connector_modes(struct drm_connector *connector, - uint32_t maxX, uint32_t maxY); - - The drm_helper_probe_single_connector_modes helper - function is a connector fill_modes - implementation that updates the connection status for the connector - and then retrieves a list of modes by calling the connector - get_modes helper operation. - - - If the helper operation returns no mode, and if the connector status - is connector_status_connected, standard VESA DMT modes up to - 1024x768 are automatically added to the modes list by a call to - drm_add_modes_noedid. - - - The function then filters out modes larger than - max_width and max_height - if specified. It finally calls the optional connector - mode_valid helper operation for each mode in - the probed list to check whether the mode is valid for the connector. - - - - - - CRTC Helper Operations - - - bool (*mode_fixup)(struct drm_crtc *crtc, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); - - Let CRTCs adjust the requested mode or reject it completely. This - operation returns true if the mode is accepted (possibly after being - adjusted) or false if it is rejected. - - - The mode_fixup operation should reject the - mode if it can't reasonably use it. The definition of "reasonable" - is currently fuzzy in this context. One possible behaviour would be - to set the adjusted mode to the panel timings when a fixed-mode - panel is used with hardware capable of scaling. Another behaviour - would be to accept any input mode and adjust it to the closest mode - supported by the hardware (FIXME: This needs to be clarified). - - - - int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, - struct drm_framebuffer *old_fb) - - Move the CRTC on the current frame buffer (stored in - crtc->fb) to position (x,y). Any of the frame - buffer, x position or y position may have been modified. - - - This helper operation is optional. If not provided, the - drm_crtc_helper_set_config function will fall - back to the mode_set helper operation. - - - FIXME: Why are x and y passed as arguments, as they can be accessed - through crtc->x and - crtc->y? - - - - void (*prepare)(struct drm_crtc *crtc); - - Prepare the CRTC for mode setting. This operation is called after - validating the requested mode. Drivers use it to perform - device-specific operations required before setting the new mode. - - - - int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode, int x, int y, - struct drm_framebuffer *old_fb); - - Set a new mode, position and frame buffer. Depending on the device - requirements, the mode can be stored internally by the driver and - applied in the commit operation, or - programmed to the hardware immediately. - - - The mode_set operation returns 0 on success - or a negative error code if an error occurs. - - - - void (*commit)(struct drm_crtc *crtc); - - Commit a mode. This operation is called after setting the new mode. - Upon return the device must use the new mode and be fully - operational. - - - - - - Encoder Helper Operations - - - bool (*mode_fixup)(struct drm_encoder *encoder, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); - - Let encoders adjust the requested mode or reject it completely. This - operation returns true if the mode is accepted (possibly after being - adjusted) or false if it is rejected. See the - mode_fixup CRTC helper - operation for an explanation of the allowed adjustments. - - - - void (*prepare)(struct drm_encoder *encoder); - - Prepare the encoder for mode setting. This operation is called after - validating the requested mode. Drivers use it to perform - device-specific operations required before setting the new mode. - - - - void (*mode_set)(struct drm_encoder *encoder, - struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); - - Set a new mode. Depending on the device requirements, the mode can - be stored internally by the driver and applied in the - commit operation, or programmed to the - hardware immediately. - - - - void (*commit)(struct drm_encoder *encoder); - - Commit a mode. This operation is called after setting the new mode. - Upon return the device must use the new mode and be fully - operational. - - - - - - Connector Helper Operations - - - struct drm_encoder *(*best_encoder)(struct drm_connector *connector); - - Return a pointer to the best encoder for the connecter. Device that - map connectors to encoders 1:1 simply return the pointer to the - associated encoder. This operation is mandatory. - - - - int (*get_modes)(struct drm_connector *connector); - - Fill the connector's probed_modes list - by parsing EDID data with drm_add_edid_modes, - adding standard VESA DMT modes with drm_add_modes_noedid, - or calling drm_mode_probed_add directly for every - supported mode and return the number of modes it has detected. This - operation is mandatory. - - - Note that the caller function will automatically add standard VESA - DMT modes up to 1024x768 if the get_modes - helper operation returns no mode and if the connector status is - connector_status_connected. There is no need to call - drm_add_edid_modes manually in that case. - - - When adding modes manually the driver creates each mode with a call to - drm_mode_create and must fill the following fields. - - - __u32 type; - - Mode type bitmask, a combination of - - - DRM_MODE_TYPE_BUILTIN - not used? - - - DRM_MODE_TYPE_CLOCK_C - not used? - - - DRM_MODE_TYPE_CRTC_C - not used? - - - - DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector - - - not used? - - - - DRM_MODE_TYPE_DEFAULT - not used? - - - DRM_MODE_TYPE_USERDEF - not used? - - - DRM_MODE_TYPE_DRIVER - - - The mode has been created by the driver (as opposed to - to user-created modes). - - - - - Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they - create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred - mode. - - - - __u32 clock; - Pixel clock frequency in kHz unit - - - __u16 hdisplay, hsync_start, hsync_end, htotal; - __u16 vdisplay, vsync_start, vsync_end, vtotal; - Horizontal and vertical timing information - <----------------><-------------><--------------> - - //////////////////////| - ////////////////////// | - ////////////////////// |.................. ................ - _______________ - - <----- [hv]display -----> - <------------- [hv]sync_start ------------> - <--------------------- [hv]sync_end ---------------------> - <-------------------------------- [hv]total -----------------------------> -]]> - - - __u16 hskew; - __u16 vscan; - Unknown - - - __u32 flags; - - Mode flags, a combination of - - - DRM_MODE_FLAG_PHSYNC - - Horizontal sync is active high - - - - DRM_MODE_FLAG_NHSYNC - - Horizontal sync is active low - - - - DRM_MODE_FLAG_PVSYNC - - Vertical sync is active high - - - - DRM_MODE_FLAG_NVSYNC - - Vertical sync is active low - - - - DRM_MODE_FLAG_INTERLACE - - Mode is interlaced - - - - DRM_MODE_FLAG_DBLSCAN - - Mode uses doublescan - - - - DRM_MODE_FLAG_CSYNC - - Mode uses composite sync - - - - DRM_MODE_FLAG_PCSYNC - - Composite sync is active high - - - - DRM_MODE_FLAG_NCSYNC - - Composite sync is active low - - - - DRM_MODE_FLAG_HSKEW - - hskew provided (not used?) - - - - DRM_MODE_FLAG_BCAST - - not used? - - - - DRM_MODE_FLAG_PIXMUX - - not used? - - - - DRM_MODE_FLAG_DBLCLK - - not used? - - - - DRM_MODE_FLAG_CLKDIV2 - - ? - - - - - - Note that modes marked with the INTERLACE or DBLSCAN flags will be - filtered out by - drm_helper_probe_single_connector_modes if - the connector's interlace_allowed or - doublescan_allowed field is set to 0. - - - - char name[DRM_DISPLAY_MODE_LEN]; - - Mode name. The driver must call - drm_mode_set_name to fill the mode name from - hdisplay, - vdisplay and interlace flag after - filling the corresponding fields. - - - - - - The vrefresh value is computed by - drm_helper_probe_single_connector_modes. - - - When parsing EDID data, drm_add_edid_modes fills the - connector display_info - width_mm and - height_mm fields. When creating modes - manually the get_modes helper operation must - set the display_info - width_mm and - height_mm fields if they haven't been set - already (for instance at initialization time when a fixed-size panel is - attached to the connector). The mode width_mm - and height_mm fields are only used internally - during EDID parsing and should not be set when creating modes manually. - - - - int (*mode_valid)(struct drm_connector *connector, - struct drm_display_mode *mode); - - 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 optional. - - - As the mode rejection reason is currently not used beside for - immediately removing the unsupported mode, an implementation can - return MODE_BAD regardless of the exact reason why the mode is not - valid. - - - Note that the mode_valid helper operation is - only called for modes detected by the device, and - not for modes set by the user through the CRTC - set_config operation. - - - - Atomic Modeset Helper Functions Reference @@ -2327,8 +1596,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_atomic_helper.c - Modeset Helper Functions Reference -!Iinclude/drm/drm_crtc_helper.h + Modeset Helper Reference for Common Vtables +!Iinclude/drm/drm_modeset_helper_vtables.h +!Pinclude/drm/drm_modeset_helper_vtables.h overview + + + Legacy CRTC/Modeset Helper Functions Reference !Edrivers/gpu/drm/drm_crtc_helper.c !Pdrivers/gpu/drm/drm_crtc_helper.c overview @@ -4039,92 +3312,6 @@ int num_ioctls; DPIO !Pdrivers/gpu/drm/i915/i915_reg.h DPIO - - Dual channel PHY (VLV/CHV/BXT) - - - - - - - - - - - - - - - - - - CH0 - CH1 - - - - - CMN/PLL/REF - CMN/PLL/REF - - - PCS01 - PCS23 - PCS01 - PCS23 - - - TX0 - TX1 - TX2 - TX3 - TX0 - TX1 - TX2 - TX3 - - - DDI0 - DDI1 - - - -
- - Single channel PHY (CHV/BXT) - - - - - - - - - - - CH0 - - - - - CMN/PLL/REF - - - PCS01 - PCS23 - - - TX0 - TX1 - TX2 - TX3 - - - DDI2 - - - -
@@ -4201,17 +3388,21 @@ int num_ioctls; - GuC-based Command Submission + GuC - GuC + GuC-specific firmware loader !Pdrivers/gpu/drm/i915/intel_guc_loader.c GuC-specific firmware loader !Idrivers/gpu/drm/i915/intel_guc_loader.c - GuC Client -!Pdrivers/gpu/drm/i915/i915_guc_submission.c GuC-based command submissison + GuC-based command submission +!Pdrivers/gpu/drm/i915/i915_guc_submission.c GuC-based command submission !Idrivers/gpu/drm/i915/i915_guc_submission.c + + GuC Firmware Layout +!Pdrivers/gpu/drm/i915/intel_guc_fwif.h GuC Firmware Layout + @@ -4246,41 +3437,63 @@ int num_ioctls; Modes of Use - - Manual switching and manual power control + + Manual switching and manual power control !Pdrivers/gpu/vga/vga_switcheroo.c Manual switching and manual power control - - - Driver power control + + + Driver power control !Pdrivers/gpu/vga/vga_switcheroo.c Driver power control - + - - Public functions + + API + + Public functions !Edrivers/gpu/vga/vga_switcheroo.c - - - - Public structures + + + Public structures !Finclude/linux/vga_switcheroo.h vga_switcheroo_handler !Finclude/linux/vga_switcheroo.h vga_switcheroo_client_ops - - - - Public constants + + + Public constants !Finclude/linux/vga_switcheroo.h vga_switcheroo_client_id !Finclude/linux/vga_switcheroo.h vga_switcheroo_state - - - - Private structures + + + Private structures !Fdrivers/gpu/vga/vga_switcheroo.c vgasr_priv !Fdrivers/gpu/vga/vga_switcheroo.c vga_switcheroo_client + + + + + Handlers + + apple-gmux Handler +!Pdrivers/platform/x86/apple-gmux.c Overview +!Pdrivers/platform/x86/apple-gmux.c Interrupt + + Graphics mux +!Pdrivers/platform/x86/apple-gmux.c Graphics mux + + + Power control +!Pdrivers/platform/x86/apple-gmux.c Power control + + + Backlight control +!Pdrivers/platform/x86/apple-gmux.c Backlight control + + !Cdrivers/gpu/vga/vga_switcheroo.c !Cinclude/linux/vga_switcheroo.h +!Cdrivers/platform/x86/apple-gmux.c diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl index 98be32267..f525bf56d 100644 --- a/Documentation/DocBook/iio.tmpl +++ b/Documentation/DocBook/iio.tmpl @@ -458,7 +458,7 @@ .scan_type = { .sign = 's', .realbits = 12, - .storgebits = 16, + .storagebits = 16, .shift = 4, .endianness = IIO_LE, }, diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 08527e7ea..2840ff483 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -199,8 +199,10 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)-mkdir $(MEDIA_OBJ_DIR)/media_api; \ - cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api + $(Q)if [ "x$(findstring media_api.xml,$(DOCBOOKS))" != "x" ]; then \ + mkdir -p $(MEDIA_OBJ_DIR)/media_api; \ + cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api; \ + fi $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 08227d4e9..e579ae508 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -76,7 +76,7 @@ int main(void) NOTE: While it is possible to directly call the Kernel code like the above example, it is strongly recommended to use - libdvbv5, + libdvbv5, as it provides abstraction to work with the supported digital TV standards and provides methods for usual operations like program scanning and to read/write channel descriptor files. diff --git a/Documentation/DocBook/media/dvb/examples.xml b/Documentation/DocBook/media/dvb/examples.xml index c9f68c718..837fb3b64 100644 --- a/Documentation/DocBook/media/dvb/examples.xml +++ b/Documentation/DocBook/media/dvb/examples.xml @@ -3,7 +3,7 @@ NOTE: This section is out of date, and the code below won't even compile. Please refer to the - libdvbv5 + libdvbv5 for updated/recommended examples. diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml index 51db15648..b5b701f5d 100644 --- a/Documentation/DocBook/media/dvb/intro.xml +++ b/Documentation/DocBook/media/dvb/intro.xml @@ -32,7 +32,7 @@ and filtering several section and PES data streams at the same time. new standard Linux DVB API. As a commitment to the development of terminals based on open standards, Nokia and Convergence made it available to all Linux developers and published it on - in September 2000. + in September 2000. Convergence is the maintainer of the Linux DVB API. Together with the LinuxTV community (i.e. you, the reader of this document), the Linux DVB API will be constantly reviewed and improved. With the Linux driver for diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml index 1c5c49a2d..22126a991 100644 --- a/Documentation/DocBook/media/v4l/capture.c.xml +++ b/Documentation/DocBook/media/v4l/capture.c.xml @@ -5,7 +5,7 @@ * This program can be used and distributed without restrictions. * * This program is provided with the V4L2 API - * see http://linuxtv.org/docs.php for more information + * see https://linuxtv.org/docs.php for more information */ #include <stdio.h> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 5701a08ed..5399e8904 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2666,7 +2666,7 @@ is useful to display images captured with V4L2 devices. 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 +url="https://linuxtv.org">https://linuxtv.org. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both. diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index da654031e..144158b3a 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -699,7 +699,7 @@ linkend="v4l2-buf-type" /> 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 type -refers to an input stream, applications when it refers to an output stream. +refers to a capture stream, applications when it refers to an output stream. If the application sets this to 0 for an output stream, then bytesused will be set to the size of the buffer (see the length field of this struct) by @@ -720,14 +720,14 @@ linkend="buffer-flags" />. Indicates the field order of the image in the buffer, see . This field is not used when the buffer contains VBI data. Drivers must set it when -type refers to an input stream, +type refers to a capture stream, applications when it refers to an output stream. struct timeval timestamp - For input streams this is time when the first data + For capture streams this is time when the first data byte was captured, as returned by the clock_gettime() function for the relevant clock id; see V4L2_BUF_FLAG_TIMESTAMP_* in @@ -866,7 +866,7 @@ must set this to 0. The number of bytes occupied by data in the plane (its payload). Drivers must set this field when type - refers to an input stream, applications when it refers to an output stream. + refers to a capture stream, applications when it refers to an output stream. If the application sets this to 0 for an output stream, then bytesused will be set to the size of the plane (see the length field of this struct) @@ -919,7 +919,7 @@ must set this to 0. Offset in bytes to video data in the plane. Drivers must set this field when type - refers to an input stream, applications when it refers to an output stream. + refers to a capture stream, applications when it refers to an output stream. Note that data_offset is included in bytesused. So the size of the image in the plane is bytesused-data_offset at diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml index 873ac3a62..5f2fc07a9 100644 --- a/Documentation/DocBook/media/v4l/media-controller.xml +++ b/Documentation/DocBook/media/v4l/media-controller.xml @@ -58,21 +58,36 @@ Media device model Discovering a device internal topology, and configuring it at runtime, is one of the goals of the media controller API. To achieve this, hardware - devices are modelled as an oriented graph of building blocks called entities - connected through pads. - An entity is a basic media hardware or software building block. It can - correspond to a large variety of logical blocks such as physical hardware - devices (CMOS sensor for instance), logical hardware devices (a building - block in a System-on-Chip image processing pipeline), DMA channels or - physical connectors. - A pad is a connection endpoint through which an entity can interact - with other entities. Data (not restricted to video) produced by an entity - flows from the entity's output to one or more entity inputs. Pads should not - be confused with physical pins at chip boundaries. - A link is a point-to-point oriented connection between two pads, - either on the same entity or on different entities. Data flows from a source - pad to a sink pad. + devices and Linux Kernel interfaces are modelled as graph objects on + an oriented graph. The object types that constitute the graph are: + + An entity + is a basic media hardware or software building block. It can correspond to + a large variety of logical blocks such as physical hardware devices + (CMOS sensor for instance), logical hardware devices (a building block in + a System-on-Chip image processing pipeline), DMA channels or physical + connectors. + An interface + is a graph representation of a Linux Kernel userspace API interface, + like a device node or a sysfs file that controls one or more entities + in the graph. + A pad + is a data connection endpoint through which an entity can interact with + other entities. Data (not restricted to video) produced by an entity + flows from the entity's output to one or more entity inputs. Pads should + not be confused with physical pins at chip boundaries. + A data link + is a point-to-point oriented connection between two pads, either on the + same entity or on different entities. Data flows from a source pad to a + sink pad. + An interface link + is a point-to-point bidirectional control connection between a Linux + Kernel interface and an entity.m + + + + &sub-media-types; @@ -83,6 +98,7 @@ &sub-media-func-ioctl; &sub-media-ioc-device-info; + &sub-media-ioc-g-topology; &sub-media-ioc-enum-entities; &sub-media-ioc-enum-links; &sub-media-ioc-setup-link; diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml index 5872f8bbf..0c4f96bfc 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml @@ -59,15 +59,6 @@ Entity IDs can be non-contiguous. Applications must not try to enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error. - Two or more entities that share a common non-zero - group_id value are considered as logically - grouped. Groups are used to report - - ALSA, VBI and video nodes that carry the same media - stream - lens and flash controllers associated with a sensor - - struct <structname>media_entity_desc</structname> @@ -106,7 +97,7 @@ revision - Entity revision in a driver/hardware specific format. + Entity revision. Always zero (obsolete) __u32 @@ -120,7 +111,7 @@ group_id - Entity group ID + Entity group ID. Always zero (obsolete) __u16 @@ -171,97 +162,6 @@
- - - Media entity types - - - - - - MEDIA_ENT_T_DEVNODE - Unknown device node - - - MEDIA_ENT_T_DEVNODE_V4L - V4L video, radio or vbi device node - - - MEDIA_ENT_T_DEVNODE_FB - Frame buffer device node - - - MEDIA_ENT_T_DEVNODE_ALSA - ALSA card - - - MEDIA_ENT_T_DEVNODE_DVB_FE - DVB frontend devnode - - - MEDIA_ENT_T_DEVNODE_DVB_DEMUX - DVB demux devnode - - - MEDIA_ENT_T_DEVNODE_DVB_DVR - DVB DVR devnode - - - MEDIA_ENT_T_DEVNODE_DVB_CA - DVB CAM devnode - - - MEDIA_ENT_T_DEVNODE_DVB_NET - DVB network devnode - - - MEDIA_ENT_T_V4L2_SUBDEV - Unknown V4L sub-device - - - MEDIA_ENT_T_V4L2_SUBDEV_SENSOR - Video sensor - - - MEDIA_ENT_T_V4L2_SUBDEV_FLASH - Flash controller - - - MEDIA_ENT_T_V4L2_SUBDEV_LENS - Lens controller - - - MEDIA_ENT_T_V4L2_SUBDEV_DECODER - Video decoder, the basic function of the video decoder is to - accept analogue video from a wide variety of sources such as - broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL or HD format and still occasionally SECAM, separate - it into its component parts, luminance and chrominance, and output - it in some digital video standard, with appropriate embedded timing - signals. - - - MEDIA_ENT_T_V4L2_SUBDEV_TUNER - TV and/or radio tuner - - - -
- - - Media entity flags - - - - - - MEDIA_ENT_FL_DEFAULT - Default entity for its type. Used to discover the default - audio, VBI and video devices, the default camera sensor, ... - - - -
diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml index 74fb394ec..2bbeea9f3 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml @@ -118,35 +118,6 @@ - - Media pad flags - - - - - - MEDIA_PAD_FL_SINK - Input pad, relative to the entity. Input pads sink data and - are targets of links. - - - MEDIA_PAD_FL_SOURCE - Output pad, relative to the entity. Output pads source data - and are origins of links. - - - MEDIA_PAD_FL_MUST_CONNECT - If this flag is set and the pad is linked to any other - pad, then at least one of those links must be enabled for the - entity to be able to stream. There could be temporary reasons - (e.g. device configuration dependent) for the pad to need - enabled links even when this flag isn't set; the absence of the - flag doesn't imply there is none. - - - -
- struct <structname>media_link_desc</structname> @@ -171,33 +142,6 @@ - - Media link flags - - - - - - MEDIA_LNK_FL_ENABLED - The link is enabled and can be used to transfer media data. - When two or more links target a sink pad, only one of them can be - enabled at a time. - - - MEDIA_LNK_FL_IMMUTABLE - The link enabled state can't be modified at runtime. An - immutable link is always enabled. - - - MEDIA_LNK_FL_DYNAMIC - The link enabled state can be modified during streaming. This - flag is set by drivers and is read-only for applications. - - - - - One and only one of MEDIA_PAD_FL_SINK and - MEDIA_PAD_FL_SOURCE must be set for every pad. diff --git a/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml new file mode 100644 index 000000000..63152ab9e --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml @@ -0,0 +1,394 @@ + + + ioctl MEDIA_IOC_G_TOPOLOGY + &manvol; + + + + MEDIA_IOC_G_TOPOLOGY + Enumerate the graph topology and graph element properties + + + + + + int ioctl + int fd + int request + struct media_v2_topology *argp + + + + + + Arguments + + + + fd + + File descriptor returned by + open(). + + + + request + + MEDIA_IOC_G_TOPOLOGY + + + + argp + + + + + + + + + Description + + NOTE: This new ioctl is programmed to be added on Kernel 4.6. Its definition/arguments may change until its final version. + + The typical usage of this ioctl is to call it twice. + On the first call, the structure defined at &media-v2-topology; should + be zeroed. At return, if no errors happen, this ioctl will return the + topology_version and the total number of entities, + interfaces, pads and links. + Before the second call, the userspace should allocate arrays to + store the graph elements that are desired, putting the pointers to them + at the ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping + the other values untouched. + If the topology_version remains the same, the + ioctl should fill the desired arrays with the media graph elements. + + + struct <structname>media_v2_topology</structname> + + + + + + + + + __u64 + topology_version + + + Version of the media graph topology. When the graph is + created, this field starts with zero. Every time a graph + element is added or removed, this field is + incremented. + + + __u64 + num_entities + + + Number of entities in the graph + + + __u64 + ptr_entities + + + A pointer to a memory area where the entities array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + entities. It will just update + num_entities + + + __u64 + num_interfaces + + + Number of interfaces in the graph + + + __u64 + ptr_interfaces + + + A pointer to a memory area where the interfaces array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + interfaces. It will just update + num_interfaces + + + __u64 + num_pads + + + Total number of pads in the graph + + + __u64 + ptr_pads + + + A pointer to a memory area where the pads array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + pads. It will just update + num_pads + + + __u64 + num_links + + + Total number of data and interface links in the graph + + + __u64 + ptr_links + + + A pointer to a memory area where the links array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + links. It will just update + num_links + + + +
+ + + struct <structname>media_v2_entity</structname> + + + + + + + + + __u32 + id + + + Unique ID for the entity. + + + char + name[64] + + + Entity name as an UTF-8 NULL-terminated string. + + + __u32 + function + + + Entity main function, see for details. + + + __u32 + reserved[12] + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + +
+ + + struct <structname>media_v2_interface</structname> + + + + + + + + + __u32 + id + + + Unique ID for the interface. + + + __u32 + intf_type + + + Interface type, see for details. + + + __u32 + flags + + + Interface flags. Currently unused. + + + __u32 + reserved[9] + + + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + struct media_v2_intf_devnode + devnode + + + Used only for device node interfaces. See for details.. + + + +
+ + + struct <structname>media_v2_interface</structname> + + + + + + + + + __u32 + major + + + Device node major number. + + + __u32 + minor + + + Device node minor number. + + + +
+ + + struct <structname>media_v2_pad</structname> + + + + + + + + + __u32 + id + + + Unique ID for the pad. + + + __u32 + entity_id + + + Unique ID for the entity where this pad belongs. + + + __u32 + flags + + + Pad flags, see for more details. + + + __u32 + reserved[9] + + + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + +
+ + + struct <structname>media_v2_pad</structname> + + + + + + + + + __u32 + id + + + Unique ID for the pad. + + + __u32 + source_id + + + + On pad to pad links: unique ID for the source pad. + On interface to entity links: unique ID for the interface. + + + + __u32 + sink_id + + + + On pad to pad links: unique ID for the sink pad. + On interface to entity links: unique ID for the entity. + + + + __u32 + flags + + + Link flags, see for more details. + + + __u32 + reserved[5] + + + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + + + + + + + &return-value; + + + + ENOSPC + + This is returned when either one or more of the num_entities, + num_interfaces, num_links or num_pads are non-zero and are smaller + than the actual number of elements inside the graph. This may happen + if the topology_version changed when compared + to the last time this ioctl was called. Userspace should usually + free the area for the pointers, zero the struct elements and call + this ioctl again. + + + + + diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml new file mode 100644 index 000000000..0ee0f3386 --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-types.xml @@ -0,0 +1,236 @@ +
+Types and flags used to represent the media graph elements + + + Media entity types + + + + + + MEDIA_ENT_F_UNKNOWN and MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN + Unknown entity. That generally indicates that + a driver didn't initialize properly the entity, with is a Kernel bug + + + MEDIA_ENT_F_IO_V4L + Data streaming input and/or output entity. + + + MEDIA_ENT_F_IO_VBI + V4L VBI streaming input or output entity + + + MEDIA_ENT_F_IO_SWRADIO + V4L Software Digital Radio (SDR) streaming input or output entity + + + MEDIA_ENT_F_IO_DTV + DVB Digital TV streaming input or output entity + + + MEDIA_ENT_F_DTV_DEMOD + Digital TV demodulator entity. + + + MEDIA_ENT_F_TS_DEMUX + MPEG Transport stream demux entity. Could be implemented on hardware or in Kernelspace by the Linux DVB subsystem. + + + MEDIA_ENT_F_DTV_CA + Digital TV Conditional Access module (CAM) entity + + + MEDIA_ENT_F_DTV_NET_DECAP + Digital TV network ULE/MLE desencapsulation entity. Could be implemented on hardware or in Kernelspace + + + MEDIA_ENT_F_CONN_RF + Connector for a Radio Frequency (RF) signal. + + + MEDIA_ENT_F_CONN_SVIDEO + Connector for a S-Video signal. + + + MEDIA_ENT_F_CONN_COMPOSITE + Connector for a RGB composite signal. + + + MEDIA_ENT_F_CAM_SENSOR + Camera video sensor entity. + + + MEDIA_ENT_F_FLASH + Flash controller entity. + + + MEDIA_ENT_F_LENS + Lens controller entity. + + + MEDIA_ENT_F_ATV_DECODER + Analog video decoder, the basic function of the video decoder + is to accept analogue video from a wide variety of sources such as + broadcast, DVD players, cameras and video cassette recorders, in + either NTSC, PAL, SECAM or HD format, separating the stream + into its component parts, luminance and chrominance, and output + it in some digital video standard, with appropriate timing + signals. + + + MEDIA_ENT_F_TUNER + Digital TV, analog TV, radio and/or software radio tuner. + + + +
+ + + Media entity flags + + + + + + MEDIA_ENT_FL_DEFAULT + Default entity for its type. Used to discover the default + audio, VBI and video devices, the default camera sensor, ... + + + MEDIA_ENT_FL_CONNECTOR + The entity represents a data conector + + + +
+ + + Media interface types + + + + + + + MEDIA_INTF_T_DVB_FE + Device node interface for the Digital TV frontend + typically, /dev/dvb/adapter?/frontend? + + + MEDIA_INTF_T_DVB_DEMUX + Device node interface for the Digital TV demux + typically, /dev/dvb/adapter?/demux? + + + MEDIA_INTF_T_DVB_DVR + Device node interface for the Digital TV DVR + typically, /dev/dvb/adapter?/dvr? + + + MEDIA_INTF_T_DVB_CA + Device node interface for the Digital TV Conditional Access + typically, /dev/dvb/adapter?/ca? + + + MEDIA_INTF_T_DVB_FE + Device node interface for the Digital TV network control + typically, /dev/dvb/adapter?/net? + + + MEDIA_INTF_T_V4L_VIDEO + Device node interface for video (V4L) + typically, /dev/video? + + + MEDIA_INTF_T_V4L_VBI + Device node interface for VBI (V4L) + typically, /dev/vbi? + + + MEDIA_INTF_T_V4L_RADIO + Device node interface for radio (V4L) + typically, /dev/vbi? + + + MEDIA_INTF_T_V4L_SUBDEV + Device node interface for a V4L subdevice + typically, /dev/v4l-subdev? + + + MEDIA_INTF_T_V4L_SWRADIO + Device node interface for Software Defined Radio (V4L) + typically, /dev/swradio? + + + +
+ + + Media pad flags + + + + + + MEDIA_PAD_FL_SINK + Input pad, relative to the entity. Input pads sink data and + are targets of links. + + + MEDIA_PAD_FL_SOURCE + Output pad, relative to the entity. Output pads source data + and are origins of links. + + + MEDIA_PAD_FL_MUST_CONNECT + If this flag is set and the pad is linked to any other + pad, then at least one of those links must be enabled for the + entity to be able to stream. There could be temporary reasons + (e.g. device configuration dependent) for the pad to need + enabled links even when this flag isn't set; the absence of the + flag doesn't imply there is none. + + + +
+ + One and only one of MEDIA_PAD_FL_SINK and + MEDIA_PAD_FL_SOURCE must be set for every pad. + + + Media link flags + + + + + + MEDIA_LNK_FL_ENABLED + The link is enabled and can be used to transfer media data. + When two or more links target a sink pad, only one of them can be + enabled at a time. + + + MEDIA_LNK_FL_IMMUTABLE + The link enabled state can't be modified at runtime. An + immutable link is always enabled. + + + MEDIA_LNK_FL_DYNAMIC + The link enabled state can be modified during streaming. This + flag is set by drivers and is read-only for applications. + + + MEDIA_LNK_FL_LINK_TYPE + This is a bitmask that defines the type of the link. + Currently, two types of links are supported: + MEDIA_LNK_FL_DATA_LINK + if the link is between two pads + MEDIA_LNK_FL_INTERFACE_LINK + if the link is between an interface and an entity + + + + + +
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 7e6164335..42e626d6c 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -151,6 +151,16 @@ Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, structs, ioctls) must be noted in more detail in the history chapter (compat.xml), along with the possible impact on existing drivers and applications. --> + + 4.5 + 2015-10-29 + rr + Extend vidioc-g-ext-ctrls;. Replace ctrl_class with a new +union with ctrl_class and which. Which is used to select the current value of +the control or the default value. + + + 4.4 2015-05-26 diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 8ffe74f84..d81fa0d40 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -58,7 +58,7 @@ This ioctl is used to create buffers for memory mapped or user pointer or DMA buffer I/O. It can be used as an alternative or in -addition to the VIDIOC_REQBUFS ioctl, when a tighter +addition to the &VIDIOC-REQBUFS; ioctl, when a tighter control over buffers is required. This ioctl can be called multiple times to create buffers of different sizes. @@ -71,30 +71,28 @@ zeroed. The format field specifies the image format that the buffers must be able to handle. The application has to fill in this -&v4l2-format;. Usually this will be done using the -VIDIOC_TRY_FMT or VIDIOC_G_FMT ioctl() -to ensure that the requested format is supported by the driver. Unsupported -formats will result in an error. +&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls +to ensure that the requested format is supported by the driver. +Based on the format's type field the requested buffer +size (for single-planar) or plane sizes (for multi-planar formats) will be +used for the allocated buffers. The driver may return an error if the size(s) +are not supported by the hardware (usually because they are too small). The buffers created by this ioctl will have as minimum size the size -defined by the format.pix.sizeimage field. If the +defined by the format.pix.sizeimage field (or the +corresponding fields for other format types). Usually if the format.pix.sizeimage field is less than the minimum -required for the given format, then sizeimage will be -increased by the driver to that minimum to allocate the buffers. If it is -larger, then the value will be used as-is. The same applies to the -sizeimage field of the -v4l2_plane_pix_format structure in the case of -multiplanar formats. +required for the given format, then an error will be returned since drivers will +typically not allow this. If it is larger, then the value will be used as-is. +In other words, the driver may reject the requested size, but if it is accepted +the driver will use it unchanged. When the ioctl is called with a pointer to this structure the driver will attempt to allocate up to the requested number of buffers and store the actual number allocated and the starting index in the count and the index fields respectively. On return count can be smaller than -the number requested. The driver may also increase buffer sizes if required, -however, it will not update sizeimage field values. -The user has to use VIDIOC_QUERYBUF to retrieve that -information. +the number requested. struct <structname>v4l2_create_buffers</structname> diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml index 4c4603c13..f14a3bb1a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml @@ -99,7 +99,7 @@ if the driver supports writing registers to the device.We recommended the v4l2-dbg utility over calling this ioctl directly. It is available from the LinuxTV v4l-dvb repository; see http://linuxtv.org/repo/ for +url="https://linuxtv.org/repo/">https://linuxtv.org/repo/ for access instructions. -http://www.linuxtv.org/lists.php"> +https://linuxtv.org/lists.php"> -http://linuxtv.org/repo/"> +https://linuxtv.org/repo/"> --------"> ----------"> ------------"> @@ -91,7 +91,7 @@ components, like mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API.For additional information and for the latest development code, - see: http://linuxtv.org. + see: https://linuxtv.org.For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: Linux Media Mailing List (LMML).. diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 7da8f0402..b442921bc 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -162,12 +162,15 @@ Basic defines - At least you have to provide a mtd structure and - a storage for the ioremap'ed chip address. - You can allocate the mtd structure using kmalloc - or you can allocate it statically. - In case of static allocation you have to allocate - a nand_chip structure too. + At least you have to provide a nand_chip structure + and a storage for the ioremap'ed chip address. + You can allocate the nand_chip structure using + kmalloc or you can allocate it statically. + The NAND chip structure embeds an mtd structure + which will be registered to the MTD subsystem. + You can extract a pointer to the mtd structure + from a nand_chip pointer using the nand_to_mtd() + helper. Kmalloc based example @@ -180,7 +183,6 @@ static void __iomem *baseaddr; Static example -static struct mtd_info board_mtd; static struct nand_chip board_chip; static void __iomem *baseaddr; @@ -235,7 +237,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) static void board_hwcontrol(struct mtd_info *mtd, int cmd) { - struct nand_chip *this = (struct nand_chip *) mtd->priv; + struct nand_chip *this = mtd_to_nand(mtd); switch(cmd){ case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break; case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; @@ -274,13 +276,15 @@ static int __init board_init (void) int err = 0; /* Allocate memory for MTD device structure and private data */ - board_mtd = kzalloc(sizeof(struct mtd_info) + sizeof(struct nand_chip), GFP_KERNEL); - if (!board_mtd) { + this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL); + if (!this) { printk ("Unable to allocate NAND MTD device structure.\n"); err = -ENOMEM; goto out; } + board_mtd = nand_to_mtd(this); + /* map physical address */ baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024); if (!baseaddr) { @@ -289,11 +293,6 @@ static int __init board_init (void) goto out_mtd; } - /* Get pointer to private data */ - this = (struct nand_chip *) (); - /* Link the private data with the MTD structure */ - board_mtd->priv = this; - /* Set address of NAND IO lines */ this->IO_ADDR_R = baseaddr; this->IO_ADDR_W = baseaddr; @@ -317,7 +316,7 @@ static int __init board_init (void) out_ior: iounmap(baseaddr); out_mtd: - kfree (board_mtd); + kfree (this); out: return err; } @@ -343,7 +342,7 @@ static void __exit board_cleanup (void) iounmap(baseaddr); /* Free the MTD device structure */ - kfree (board_mtd); + kfree (mtd_to_nand(board_mtd)); } module_exit(board_cleanup); #endif @@ -399,7 +398,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) static void board_select_chip (struct mtd_info *mtd, int chip) { - struct nand_chip *this = (struct nand_chip *) mtd->priv; + struct nand_chip *this = mtd_to_nand(mtd); /* Deselect all chips */ this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; -- cgit v1.2.3-54-g00ecf