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