]>
Commit | Line | Data |
---|---|---|
176fb0d1 LP |
1 | /* |
2 | * Media device | |
3 | * | |
4 | * Copyright (C) 2010 Nokia Corporation | |
5 | * | |
6 | * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> | |
7 | * Sakari Ailus <sakari.ailus@iki.fi> | |
8 | * | |
9 | * This program is free software; you can redistribute it and/or modify | |
10 | * it under the terms of the GNU General Public License version 2 as | |
11 | * published by the Free Software Foundation. | |
12 | * | |
13 | * This program is distributed in the hope that it will be useful, | |
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | * GNU General Public License for more details. | |
17 | * | |
18 | * You should have received a copy of the GNU General Public License | |
19 | * along with this program; if not, write to the Free Software | |
20 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
21 | */ | |
22 | ||
23 | #ifndef _MEDIA_DEVICE_H | |
24 | #define _MEDIA_DEVICE_H | |
25 | ||
176fb0d1 | 26 | #include <linux/list.h> |
503c3d82 | 27 | #include <linux/mutex.h> |
176fb0d1 LP |
28 | |
29 | #include <media/media-devnode.h> | |
53e269c1 | 30 | #include <media/media-entity.h> |
176fb0d1 | 31 | |
cc2dd94a MCC |
32 | /** |
33 | * DOC: Media Controller | |
34 | * | |
db7ee32a MCC |
35 | * The media controller userspace API is documented in DocBook format in |
36 | * Documentation/DocBook/media/v4l/media-controller.xml. This document focus | |
cc2dd94a MCC |
37 | * on the kernel-side implementation of the media framework. |
38 | * | |
db7ee32a | 39 | * * Abstract media device model: |
cc2dd94a MCC |
40 | * |
41 | * Discovering a device internal topology, and configuring it at runtime, is one | |
42 | * of the goals of the media framework. To achieve this, hardware devices are | |
43 | * modelled as an oriented graph of building blocks called entities connected | |
44 | * through pads. | |
45 | * | |
46 | * An entity is a basic media hardware building block. It can correspond to | |
47 | * a large variety of logical blocks such as physical hardware devices | |
48 | * (CMOS sensor for instance), logical hardware devices (a building block | |
49 | * in a System-on-Chip image processing pipeline), DMA channels or physical | |
50 | * connectors. | |
51 | * | |
52 | * A pad is a connection endpoint through which an entity can interact with | |
53 | * other entities. Data (not restricted to video) produced by an entity | |
54 | * flows from the entity's output to one or more entity inputs. Pads should | |
55 | * not be confused with physical pins at chip boundaries. | |
56 | * | |
57 | * A link is a point-to-point oriented connection between two pads, either | |
58 | * on the same entity or on different entities. Data flows from a source | |
59 | * pad to a sink pad. | |
60 | * | |
61 | * | |
db7ee32a | 62 | * * Media device: |
cc2dd94a | 63 | * |
db7ee32a | 64 | * A media device is represented by a struct &media_device instance, defined in |
cc2dd94a | 65 | * include/media/media-device.h. Allocation of the structure is handled by the |
db7ee32a | 66 | * media device driver, usually by embedding the &media_device instance in a |
cc2dd94a MCC |
67 | * larger driver-specific structure. |
68 | * | |
69 | * Drivers register media device instances by calling | |
db7ee32a MCC |
70 | * __media_device_register() via the macro media_device_register() |
71 | * and unregistered by calling | |
72 | * media_device_unregister(). | |
cc2dd94a | 73 | * |
db7ee32a | 74 | * * Entities, pads and links: |
cc2dd94a MCC |
75 | * |
76 | * - Entities | |
77 | * | |
db7ee32a | 78 | * Entities are represented by a struct &media_entity instance, defined in |
cc2dd94a MCC |
79 | * include/media/media-entity.h. The structure is usually embedded into a |
80 | * higher-level structure, such as a v4l2_subdev or video_device instance, | |
81 | * although drivers can allocate entities directly. | |
82 | * | |
83 | * Drivers initialize entity pads by calling | |
db7ee32a | 84 | * media_entity_pads_init(). |
cc2dd94a MCC |
85 | * |
86 | * Drivers register entities with a media device by calling | |
db7ee32a MCC |
87 | * media_device_register_entity() |
88 | * and unregistred by calling | |
89 | * media_device_unregister_entity(). | |
cc2dd94a | 90 | * |
db7ee32a | 91 | * - Interfaces |
cc2dd94a | 92 | * |
db7ee32a MCC |
93 | * Interfaces are represented by a struct &media_interface instance, defined in |
94 | * include/media/media-entity.h. Currently, only one type of interface is | |
95 | * defined: a device node. Such interfaces are represented by a struct | |
96 | * &media_intf_devnode. | |
cc2dd94a | 97 | * |
db7ee32a MCC |
98 | * Drivers initialize and create device node interfaces by calling |
99 | * media_devnode_create() | |
100 | * and remove them by calling: | |
101 | * media_devnode_remove(). | |
cc2dd94a MCC |
102 | * |
103 | * - Pads | |
104 | * | |
db7ee32a | 105 | * Pads are represented by a struct &media_pad instance, defined in |
cc2dd94a MCC |
106 | * include/media/media-entity.h. Each entity stores its pads in a pads array |
107 | * managed by the entity driver. Drivers usually embed the array in a | |
108 | * driver-specific structure. | |
109 | * | |
db7ee32a MCC |
110 | * Pads are identified by their entity and their 0-based index in the pads |
111 | * array. | |
112 | * Both information are stored in the &media_pad structure, making the | |
113 | * &media_pad pointer the canonical way to store and pass link references. | |
cc2dd94a MCC |
114 | * |
115 | * Pads have flags that describe the pad capabilities and state. | |
116 | * | |
db7ee32a MCC |
117 | * %MEDIA_PAD_FL_SINK indicates that the pad supports sinking data. |
118 | * %MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data. | |
cc2dd94a | 119 | * |
db7ee32a MCC |
120 | * NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must |
121 | * be set for each pad. | |
cc2dd94a MCC |
122 | * |
123 | * - Links | |
124 | * | |
db7ee32a MCC |
125 | * Links are represented by a struct &media_link instance, defined in |
126 | * include/media/media-entity.h. There are two types of links: | |
127 | * | |
128 | * 1. pad to pad links: | |
cc2dd94a | 129 | * |
db7ee32a MCC |
130 | * Associate two entities via their PADs. Each entity has a list that points |
131 | * to all links originating at or targeting any of its pads. | |
132 | * A given link is thus stored twice, once in the source entity and once in | |
133 | * the target entity. | |
cc2dd94a | 134 | * |
db7ee32a MCC |
135 | * Drivers create pad to pad links by calling: |
136 | * media_create_pad_link() and remove with media_entity_remove_links(). | |
cc2dd94a | 137 | * |
db7ee32a | 138 | * 2. interface to entity links: |
cc2dd94a | 139 | * |
db7ee32a | 140 | * Associate one interface to a Link. |
cc2dd94a | 141 | * |
db7ee32a MCC |
142 | * Drivers create interface to entity links by calling: |
143 | * media_create_intf_link() and remove with media_remove_intf_links(). | |
cc2dd94a | 144 | * |
db7ee32a | 145 | * NOTE: |
cc2dd94a | 146 | * |
db7ee32a MCC |
147 | * Links can only be created after having both ends already created. |
148 | * | |
149 | * Links have flags that describe the link capabilities and state. The | |
150 | * valid values are described at media_create_pad_link() and | |
151 | * media_create_intf_link(). | |
152 | * | |
153 | * Graph traversal: | |
cc2dd94a MCC |
154 | * |
155 | * The media framework provides APIs to iterate over entities in a graph. | |
156 | * | |
db7ee32a MCC |
157 | * To iterate over all entities belonging to a media device, drivers can use |
158 | * the media_device_for_each_entity macro, defined in | |
159 | * include/media/media-device.h. | |
cc2dd94a MCC |
160 | * |
161 | * struct media_entity *entity; | |
162 | * | |
163 | * media_device_for_each_entity(entity, mdev) { | |
164 | * // entity will point to each entity in turn | |
165 | * ... | |
166 | * } | |
167 | * | |
168 | * Drivers might also need to iterate over all entities in a graph that can be | |
169 | * reached only through enabled links starting at a given entity. The media | |
170 | * framework provides a depth-first graph traversal API for that purpose. | |
171 | * | |
172 | * Note that graphs with cycles (whether directed or undirected) are *NOT* | |
173 | * supported by the graph traversal API. To prevent infinite loops, the graph | |
174 | * traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH, | |
175 | * currently defined as 16. | |
176 | * | |
177 | * Drivers initiate a graph traversal by calling | |
db7ee32a | 178 | * media_entity_graph_walk_start() |
cc2dd94a MCC |
179 | * |
180 | * The graph structure, provided by the caller, is initialized to start graph | |
181 | * traversal at the given entity. | |
182 | * | |
183 | * Drivers can then retrieve the next entity by calling | |
db7ee32a | 184 | * media_entity_graph_walk_next() |
cc2dd94a MCC |
185 | * |
186 | * When the graph traversal is complete the function will return NULL. | |
187 | * | |
db7ee32a MCC |
188 | * Graph traversal can be interrupted at any moment. No cleanup function call |
189 | * is required and the graph structure can be freed normally. | |
cc2dd94a MCC |
190 | * |
191 | * Helper functions can be used to find a link between two given pads, or a pad | |
192 | * connected to another pad through an enabled link | |
db7ee32a | 193 | * media_entity_find_link() and media_entity_remote_pad() |
cc2dd94a | 194 | * |
db7ee32a | 195 | * Use count and power handling: |
cc2dd94a | 196 | * |
db7ee32a MCC |
197 | * Due to the wide differences between drivers regarding power management |
198 | * needs, the media controller does not implement power management. However, | |
199 | * the &media_entity structure includes a use_count field that media drivers | |
200 | * can use to track the number of users of every entity for power management | |
201 | * needs. | |
cc2dd94a | 202 | * |
db7ee32a MCC |
203 | * The &media_entity.@use_count field is owned by media drivers and must not be |
204 | * touched by entity drivers. Access to the field must be protected by the | |
205 | * &media_device.@graph_mutex lock. | |
cc2dd94a | 206 | * |
db7ee32a | 207 | * Links setup: |
cc2dd94a MCC |
208 | * |
209 | * Link properties can be modified at runtime by calling | |
db7ee32a | 210 | * media_entity_setup_link() |
cc2dd94a | 211 | * |
db7ee32a | 212 | * Pipelines and media streams: |
cc2dd94a MCC |
213 | * |
214 | * When starting streaming, drivers must notify all entities in the pipeline to | |
215 | * prevent link states from being modified during streaming by calling | |
db7ee32a | 216 | * media_entity_pipeline_start(). |
cc2dd94a MCC |
217 | * |
218 | * The function will mark all entities connected to the given entity through | |
219 | * enabled links, either directly or indirectly, as streaming. | |
220 | * | |
db7ee32a MCC |
221 | * The &media_pipeline instance pointed to by the pipe argument will be stored |
222 | * in every entity in the pipeline. Drivers should embed the &media_pipeline | |
223 | * structure in higher-level pipeline structures and can then access the | |
224 | * pipeline through the &media_entity pipe field. | |
cc2dd94a | 225 | * |
db7ee32a MCC |
226 | * Calls to media_entity_pipeline_start() can be nested. The pipeline pointer |
227 | * must be identical for all nested calls to the function. | |
cc2dd94a MCC |
228 | * |
229 | * media_entity_pipeline_start() may return an error. In that case, it will | |
230 | * clean up any of the changes it did by itself. | |
231 | * | |
232 | * When stopping the stream, drivers must notify the entities with | |
db7ee32a | 233 | * media_entity_pipeline_stop(). |
cc2dd94a MCC |
234 | * |
235 | * If multiple calls to media_entity_pipeline_start() have been made the same | |
db7ee32a MCC |
236 | * number of media_entity_pipeline_stop() calls are required to stop streaming. |
237 | * The &media_entity pipe field is reset to NULL on the last nested stop call. | |
cc2dd94a | 238 | * |
db7ee32a MCC |
239 | * Link configuration will fail with -%EBUSY by default if either end of the |
240 | * link is a streaming entity. Links that can be modified while streaming must | |
241 | * be marked with the %MEDIA_LNK_FL_DYNAMIC flag. | |
cc2dd94a MCC |
242 | * |
243 | * If other operations need to be disallowed on streaming entities (such as | |
244 | * changing entities configuration parameters) drivers can explicitly check the | |
245 | * media_entity stream_count field to find out if an entity is streaming. This | |
246 | * operation must be done with the media_device graph_mutex held. | |
247 | * | |
db7ee32a | 248 | * Link validation: |
cc2dd94a MCC |
249 | * |
250 | * Link validation is performed by media_entity_pipeline_start() for any | |
251 | * entity which has sink pads in the pipeline. The | |
db7ee32a MCC |
252 | * &media_entity.@link_validate() callback is used for that purpose. In |
253 | * @link_validate() callback, entity driver should check that the properties of | |
cc2dd94a MCC |
254 | * the source pad of the connected entity and its own sink pad match. It is up |
255 | * to the type of the entity (and in the end, the properties of the hardware) | |
256 | * what matching actually means. | |
257 | * | |
258 | * Subsystems should facilitate link validation by providing subsystem specific | |
259 | * helper functions to provide easy access for commonly needed information, and | |
260 | * in the end provide a way to use driver-specific callbacks. | |
261 | */ | |
262 | ||
665faa97 | 263 | struct ida; |
313162d0 PG |
264 | struct device; |
265 | ||
afcbdb55 SK |
266 | /** |
267 | * struct media_entity_notify - Media Entity Notify | |
268 | * | |
269 | * @list: List head | |
270 | * @notify_data: Input data to invoke the callback | |
271 | * @notify: Callback function pointer | |
272 | * | |
273 | * Drivers may register a callback to take action when | |
274 | * new entities get registered with the media device. | |
275 | */ | |
276 | struct media_entity_notify { | |
277 | struct list_head list; | |
278 | void *notify_data; | |
279 | void (*notify)(struct media_entity *entity, void *notify_data); | |
280 | }; | |
281 | ||
176fb0d1 LP |
282 | /** |
283 | * struct media_device - Media device | |
284 | * @dev: Parent device | |
285 | * @devnode: Media device node | |
bb07bd6b MCC |
286 | * @driver_name: Optional device driver name. If not set, calls to |
287 | * %MEDIA_IOC_DEVICE_INFO will return dev->driver->name. | |
288 | * This is needed for USB drivers for example, as otherwise | |
289 | * they'll all appear as if the driver name was "usb". | |
176fb0d1 LP |
290 | * @model: Device model name |
291 | * @serial: Device serial number (optional) | |
292 | * @bus_info: Unique and stable device location identifier | |
293 | * @hw_revision: Hardware device revision | |
294 | * @driver_version: Device driver version | |
2521fdac MCC |
295 | * @topology_version: Monotonic counter for storing the version of the graph |
296 | * topology. Should be incremented each time the topology changes. | |
05b3b77c | 297 | * @id: Unique ID used on the last registered graph object |
03e49338 MCC |
298 | * @entity_internal_idx: Unique internal entity ID used by the graph traversal |
299 | * algorithms | |
300 | * @entity_internal_idx_max: Allocated internal entity indices | |
53e269c1 | 301 | * @entities: List of registered entities |
57cf79b7 | 302 | * @interfaces: List of registered interfaces |
9155d859 MCC |
303 | * @pads: List of registered pads |
304 | * @links: List of registered links | |
afcbdb55 | 305 | * @entity_notify: List of registered entity_notify callbacks |
e2c91d4d | 306 | * @graph_mutex: Protects access to struct media_device data |
0c426c47 SA |
307 | * @pm_count_walk: Graph walk for power state walk. Access serialised using |
308 | * graph_mutex. | |
cd87ce87 SK |
309 | * |
310 | * @source_priv: Driver Private data for enable/disable source handlers | |
311 | * @enable_source: Enable Source Handler function pointer | |
312 | * @disable_source: Disable Source Handler function pointer | |
313 | * | |
5ed470fe MCC |
314 | * @link_notify: Link state change notification callback. This callback is |
315 | * called with the graph_mutex held. | |
176fb0d1 LP |
316 | * |
317 | * This structure represents an abstract high-level media device. It allows easy | |
318 | * access to entities and provides basic media device-level support. The | |
319 | * structure can be allocated directly or embedded in a larger structure. | |
320 | * | |
321 | * The parent @dev is a physical device. It must be set before registering the | |
322 | * media device. | |
323 | * | |
324 | * @model is a descriptive model name exported through sysfs. It doesn't have to | |
325 | * be unique. | |
cd87ce87 SK |
326 | * |
327 | * @enable_source is a handler to find source entity for the | |
328 | * sink entity and activate the link between them if source | |
329 | * entity is free. Drivers should call this handler before | |
330 | * accessing the source. | |
331 | * | |
332 | * @disable_source is a handler to find source entity for the | |
333 | * sink entity and deactivate the link between them. Drivers | |
334 | * should call this handler to release the source. | |
335 | * | |
336 | * Note: Bridge driver is expected to implement and set the | |
337 | * handler when media_device is registered or when | |
338 | * bridge driver finds the media_device during probe. | |
339 | * Bridge driver sets source_priv with information | |
340 | * necessary to run enable/disable source handlers. | |
341 | * | |
342 | * Use-case: find tuner entity connected to the decoder | |
343 | * entity and check if it is available, and activate the | |
344 | * the link between them from enable_source and deactivate | |
345 | * from disable_source. | |
176fb0d1 LP |
346 | */ |
347 | struct media_device { | |
348 | /* dev->driver_data points to this struct. */ | |
349 | struct device *dev; | |
350 | struct media_devnode devnode; | |
351 | ||
352 | char model[32]; | |
bb07bd6b | 353 | char driver_name[32]; |
176fb0d1 LP |
354 | char serial[40]; |
355 | char bus_info[32]; | |
356 | u32 hw_revision; | |
357 | u32 driver_version; | |
53e269c1 | 358 | |
952f8eef | 359 | u64 topology_version; |
2521fdac | 360 | |
05b3b77c | 361 | u32 id; |
665faa97 SA |
362 | struct ida entity_internal_idx; |
363 | int entity_internal_idx_max; | |
bfab2aac | 364 | |
53e269c1 | 365 | struct list_head entities; |
57cf79b7 | 366 | struct list_head interfaces; |
9155d859 MCC |
367 | struct list_head pads; |
368 | struct list_head links; | |
53e269c1 | 369 | |
afcbdb55 SK |
370 | /* notify callback list invoked when a new entity is registered */ |
371 | struct list_head entity_notify; | |
372 | ||
503c3d82 LP |
373 | /* Serializes graph operations. */ |
374 | struct mutex graph_mutex; | |
0c426c47 | 375 | struct media_entity_graph pm_count_walk; |
97548ed4 | 376 | |
cd87ce87 SK |
377 | void *source_priv; |
378 | int (*enable_source)(struct media_entity *entity, | |
379 | struct media_pipeline *pipe); | |
380 | void (*disable_source)(struct media_entity *entity); | |
381 | ||
813f5c0a SN |
382 | int (*link_notify)(struct media_link *link, u32 flags, |
383 | unsigned int notification); | |
176fb0d1 LP |
384 | }; |
385 | ||
41b44e35 MCC |
386 | /* We don't need to include pci.h or usb.h here */ |
387 | struct pci_dev; | |
388 | struct usb_device; | |
389 | ||
e576d60b SK |
390 | #ifdef CONFIG_MEDIA_CONTROLLER |
391 | ||
813f5c0a SN |
392 | /* Supported link_notify @notification values. */ |
393 | #define MEDIA_DEV_NOTIFY_PRE_LINK_CH 0 | |
394 | #define MEDIA_DEV_NOTIFY_POST_LINK_CH 1 | |
395 | ||
176fb0d1 LP |
396 | /* media_devnode to media_device */ |
397 | #define to_media_device(node) container_of(node, struct media_device, devnode) | |
398 | ||
c8d54cd5 SA |
399 | /** |
400 | * media_entity_enum_init - Initialise an entity enumeration | |
401 | * | |
03e49338 | 402 | * @ent_enum: Entity enumeration to be initialised |
c8d54cd5 SA |
403 | * @mdev: The related media device |
404 | * | |
405 | * Returns zero on success or a negative error code. | |
406 | */ | |
407 | static inline __must_check int media_entity_enum_init( | |
408 | struct media_entity_enum *ent_enum, struct media_device *mdev) | |
409 | { | |
410 | return __media_entity_enum_init(ent_enum, | |
411 | mdev->entity_internal_idx_max + 1); | |
412 | } | |
413 | ||
9832e155 JMC |
414 | /** |
415 | * media_device_init() - Initializes a media device element | |
416 | * | |
417 | * @mdev: pointer to struct &media_device | |
418 | * | |
419 | * This function initializes the media device prior to its registration. | |
420 | * The media device initialization and registration is split in two functions | |
421 | * to avoid race conditions and make the media device available to user-space | |
422 | * before the media graph has been completed. | |
423 | * | |
424 | * So drivers need to first initialize the media device, register any entity | |
425 | * within the media device, create pad to pad links and then finally register | |
426 | * the media device by calling media_device_register() as a final step. | |
427 | */ | |
428 | void media_device_init(struct media_device *mdev); | |
429 | ||
430 | /** | |
431 | * media_device_cleanup() - Cleanups a media device element | |
432 | * | |
433 | * @mdev: pointer to struct &media_device | |
434 | * | |
435 | * This function that will destroy the graph_mutex that is | |
436 | * initialized in media_device_init(). | |
437 | */ | |
438 | void media_device_cleanup(struct media_device *mdev); | |
439 | ||
db7ee32a MCC |
440 | /** |
441 | * __media_device_register() - Registers a media device element | |
442 | * | |
443 | * @mdev: pointer to struct &media_device | |
444 | * @owner: should be filled with %THIS_MODULE | |
445 | * | |
446 | * Users, should, instead, call the media_device_register() macro. | |
447 | * | |
448 | * The caller is responsible for initializing the media_device structure before | |
449 | * registration. The following fields must be set: | |
450 | * | |
451 | * - dev must point to the parent device (usually a &pci_dev, &usb_interface or | |
452 | * &platform_device instance). | |
453 | * | |
454 | * - model must be filled with the device model name as a NUL-terminated UTF-8 | |
455 | * string. The device/model revision must not be stored in this field. | |
456 | * | |
457 | * The following fields are optional: | |
458 | * | |
459 | * - serial is a unique serial number stored as a NUL-terminated ASCII string. | |
460 | * The field is big enough to store a GUID in text form. If the hardware | |
461 | * doesn't provide a unique serial number this field must be left empty. | |
462 | * | |
463 | * - bus_info represents the location of the device in the system as a | |
464 | * NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to | |
465 | * "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, | |
466 | * the usb_make_path() function must be used. This field is used by | |
467 | * applications to distinguish between otherwise identical devices that don't | |
468 | * provide a serial number. | |
469 | * | |
470 | * - hw_revision is the hardware device revision in a driver-specific format. | |
471 | * When possible the revision should be formatted with the KERNEL_VERSION | |
472 | * macro. | |
473 | * | |
474 | * - driver_version is formatted with the KERNEL_VERSION macro. The version | |
475 | * minor must be incremented when new features are added to the userspace API | |
476 | * without breaking binary compatibility. The version major must be | |
477 | * incremented when binary compatibility is broken. | |
478 | * | |
479 | * Notes: | |
480 | * | |
481 | * Upon successful registration a character device named media[0-9]+ is created. | |
482 | * The device major and minor numbers are dynamic. The model name is exported as | |
483 | * a sysfs attribute. | |
484 | * | |
485 | * Unregistering a media device that hasn't been registered is *NOT* safe. | |
92777994 MCC |
486 | * |
487 | * Return: returns zero on success or a negative error code. | |
db7ee32a | 488 | */ |
85de721c SA |
489 | int __must_check __media_device_register(struct media_device *mdev, |
490 | struct module *owner); | |
491 | #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE) | |
db7ee32a MCC |
492 | |
493 | /** | |
3047f3f9 | 494 | * media_device_unregister() - Unregisters a media device element |
db7ee32a MCC |
495 | * |
496 | * @mdev: pointer to struct &media_device | |
92777994 MCC |
497 | * |
498 | * | |
499 | * It is safe to call this function on an unregistered (but initialised) | |
500 | * media device. | |
db7ee32a | 501 | */ |
176fb0d1 LP |
502 | void media_device_unregister(struct media_device *mdev); |
503 | ||
db7ee32a MCC |
504 | /** |
505 | * media_device_register_entity() - registers a media entity inside a | |
506 | * previously registered media device. | |
507 | * | |
508 | * @mdev: pointer to struct &media_device | |
509 | * @entity: pointer to struct &media_entity to be registered | |
510 | * | |
511 | * Entities are identified by a unique positive integer ID. The media | |
512 | * controller framework will such ID automatically. IDs are not guaranteed | |
513 | * to be contiguous, and the ID number can change on newer Kernel versions. | |
514 | * So, neither the driver nor userspace should hardcode ID numbers to refer | |
515 | * to the entities, but, instead, use the framework to find the ID, when | |
516 | * needed. | |
517 | * | |
518 | * The media_entity name, type and flags fields should be initialized before | |
519 | * calling media_device_register_entity(). Entities embedded in higher-level | |
520 | * standard structures can have some of those fields set by the higher-level | |
521 | * framework. | |
522 | * | |
523 | * If the device has pads, media_entity_pads_init() should be called before | |
524 | * this function. Otherwise, the &media_entity.@pad and &media_entity.@num_pads | |
525 | * should be zeroed before calling this function. | |
526 | * | |
527 | * Entities have flags that describe the entity capabilities and state: | |
528 | * | |
529 | * %MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. | |
530 | * This can be used to report the default audio and video devices or the | |
531 | * default camera sensor. | |
d1b9da2d MCC |
532 | * |
533 | * NOTE: Drivers should set the entity function before calling this function. | |
534 | * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and | |
535 | * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers. | |
db7ee32a | 536 | */ |
53e269c1 LP |
537 | int __must_check media_device_register_entity(struct media_device *mdev, |
538 | struct media_entity *entity); | |
db7ee32a MCC |
539 | |
540 | /* | |
541 | * media_device_unregister_entity() - unregisters a media entity. | |
542 | * | |
543 | * @entity: pointer to struct &media_entity to be unregistered | |
544 | * | |
545 | * All links associated with the entity and all PADs are automatically | |
546 | * unregistered from the media_device when this function is called. | |
547 | * | |
548 | * Unregistering an entity will not change the IDs of the other entities and | |
549 | * the previoully used ID will never be reused for a newly registered entities. | |
550 | * | |
551 | * When a media device is unregistered, all its entities are unregistered | |
552 | * automatically. No manual entities unregistration is then required. | |
553 | * | |
554 | * Note: the media_entity instance itself must be freed explicitly by | |
555 | * the driver if required. | |
556 | */ | |
53e269c1 | 557 | void media_device_unregister_entity(struct media_entity *entity); |
b6e4ca81 | 558 | |
afcbdb55 SK |
559 | /** |
560 | * media_device_register_entity_notify() - Registers a media entity_notify | |
561 | * callback | |
562 | * | |
563 | * @mdev: The media device | |
564 | * @nptr: The media_entity_notify | |
565 | * | |
566 | * Note: When a new entity is registered, all the registered | |
567 | * media_entity_notify callbacks are invoked. | |
568 | */ | |
569 | ||
570 | int __must_check media_device_register_entity_notify(struct media_device *mdev, | |
571 | struct media_entity_notify *nptr); | |
572 | ||
573 | /** | |
574 | * media_device_unregister_entity_notify() - Unregister a media entity notify | |
575 | * callback | |
576 | * | |
577 | * @mdev: The media device | |
578 | * @nptr: The media_entity_notify | |
579 | * | |
580 | */ | |
581 | void media_device_unregister_entity_notify(struct media_device *mdev, | |
582 | struct media_entity_notify *nptr); | |
583 | ||
b6e4ca81 MCC |
584 | /** |
585 | * media_device_get_devres() - get media device as device resource | |
586 | * creates if one doesn't exist | |
587 | * | |
588 | * @dev: pointer to struct &device. | |
589 | * | |
590 | * Sometimes, the media controller &media_device needs to be shared by more | |
591 | * than one driver. This function adds support for that, by dynamically | |
592 | * allocating the &media_device and allowing it to be obtained from the | |
593 | * struct &device associated with the common device where all sub-device | |
594 | * components belong. So, for example, on an USB device with multiple | |
595 | * interfaces, each interface may be handled by a separate per-interface | |
596 | * drivers. While each interface have its own &device, they all share a | |
597 | * common &device associated with the hole USB device. | |
598 | */ | |
d062f911 | 599 | struct media_device *media_device_get_devres(struct device *dev); |
b6e4ca81 MCC |
600 | |
601 | /** | |
602 | * media_device_find_devres() - find media device as device resource | |
603 | * | |
604 | * @dev: pointer to struct &device. | |
605 | */ | |
d062f911 | 606 | struct media_device *media_device_find_devres(struct device *dev); |
53e269c1 LP |
607 | |
608 | /* Iterate over all entities. */ | |
609 | #define media_device_for_each_entity(entity, mdev) \ | |
05bfa9fa | 610 | list_for_each_entry(entity, &(mdev)->entities, graph_obj.list) |
53e269c1 | 611 | |
cf975a4b MCC |
612 | /* Iterate over all interfaces. */ |
613 | #define media_device_for_each_intf(intf, mdev) \ | |
05bfa9fa | 614 | list_for_each_entry(intf, &(mdev)->interfaces, graph_obj.list) |
cf975a4b | 615 | |
9155d859 MCC |
616 | /* Iterate over all pads. */ |
617 | #define media_device_for_each_pad(pad, mdev) \ | |
618 | list_for_each_entry(pad, &(mdev)->pads, graph_obj.list) | |
619 | ||
620 | /* Iterate over all links. */ | |
621 | #define media_device_for_each_link(link, mdev) \ | |
622 | list_for_each_entry(link, &(mdev)->links, graph_obj.list) | |
41b44e35 MCC |
623 | |
624 | /** | |
625 | * media_device_pci_init() - create and initialize a | |
626 | * struct &media_device from a PCI device. | |
627 | * | |
6cf5dad1 | 628 | * @mdev: pointer to struct &media_device |
41b44e35 MCC |
629 | * @pci_dev: pointer to struct pci_dev |
630 | * @name: media device name. If %NULL, the routine will use the default | |
631 | * name for the pci device, given by pci_name() macro. | |
632 | */ | |
6cf5dad1 MCC |
633 | void media_device_pci_init(struct media_device *mdev, |
634 | struct pci_dev *pci_dev, | |
635 | const char *name); | |
41b44e35 MCC |
636 | /** |
637 | * __media_device_usb_init() - create and initialize a | |
638 | * struct &media_device from a PCI device. | |
639 | * | |
6cf5dad1 | 640 | * @mdev: pointer to struct &media_device |
41b44e35 MCC |
641 | * @udev: pointer to struct usb_device |
642 | * @board_name: media device name. If %NULL, the routine will use the usb | |
643 | * product name, if available. | |
644 | * @driver_name: name of the driver. if %NULL, the routine will use the name | |
645 | * given by udev->dev->driver->name, with is usually the wrong | |
646 | * thing to do. | |
647 | * | |
648 | * NOTE: It is better to call media_device_usb_init() instead, as | |
649 | * such macro fills driver_name with %KBUILD_MODNAME. | |
650 | */ | |
6cf5dad1 MCC |
651 | void __media_device_usb_init(struct media_device *mdev, |
652 | struct usb_device *udev, | |
653 | const char *board_name, | |
654 | const char *driver_name); | |
41b44e35 | 655 | |
e576d60b SK |
656 | #else |
657 | static inline int media_device_register(struct media_device *mdev) | |
658 | { | |
659 | return 0; | |
660 | } | |
661 | static inline void media_device_unregister(struct media_device *mdev) | |
662 | { | |
663 | } | |
664 | static inline int media_device_register_entity(struct media_device *mdev, | |
665 | struct media_entity *entity) | |
666 | { | |
667 | return 0; | |
668 | } | |
669 | static inline void media_device_unregister_entity(struct media_entity *entity) | |
670 | { | |
671 | } | |
afcbdb55 SK |
672 | static inline int media_device_register_entity_notify( |
673 | struct media_device *mdev, | |
674 | struct media_entity_notify *nptr) | |
675 | { | |
676 | return 0; | |
677 | } | |
678 | static inline void media_device_unregister_entity_notify( | |
679 | struct media_device *mdev, | |
680 | struct media_entity_notify *nptr) | |
681 | { | |
682 | } | |
e576d60b SK |
683 | static inline struct media_device *media_device_get_devres(struct device *dev) |
684 | { | |
685 | return NULL; | |
686 | } | |
687 | static inline struct media_device *media_device_find_devres(struct device *dev) | |
688 | { | |
689 | return NULL; | |
690 | } | |
41b44e35 | 691 | |
6cf5dad1 MCC |
692 | static inline void media_device_pci_init(struct media_device *mdev, |
693 | struct pci_dev *pci_dev, | |
694 | char *name) | |
41b44e35 | 695 | { |
41b44e35 MCC |
696 | } |
697 | ||
6cf5dad1 MCC |
698 | static inline void __media_device_usb_init(struct media_device *mdev, |
699 | struct usb_device *udev, | |
700 | char *board_name, | |
701 | char *driver_name) | |
41b44e35 | 702 | { |
41b44e35 MCC |
703 | } |
704 | ||
e576d60b | 705 | #endif /* CONFIG_MEDIA_CONTROLLER */ |
41b44e35 | 706 | |
6cf5dad1 MCC |
707 | #define media_device_usb_init(mdev, udev, name) \ |
708 | __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME) | |
41b44e35 | 709 | |
176fb0d1 | 710 | #endif |