]>
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 | ||
afcbdb55 SK |
267 | /** |
268 | * struct media_entity_notify - Media Entity Notify | |
269 | * | |
270 | * @list: List head | |
271 | * @notify_data: Input data to invoke the callback | |
272 | * @notify: Callback function pointer | |
273 | * | |
274 | * Drivers may register a callback to take action when | |
275 | * new entities get registered with the media device. | |
276 | */ | |
277 | struct media_entity_notify { | |
278 | struct list_head list; | |
279 | void *notify_data; | |
280 | void (*notify)(struct media_entity *entity, void *notify_data); | |
281 | }; | |
282 | ||
176fb0d1 LP |
283 | /** |
284 | * struct media_device - Media device | |
285 | * @dev: Parent device | |
286 | * @devnode: Media device node | |
bb07bd6b MCC |
287 | * @driver_name: Optional device driver name. If not set, calls to |
288 | * %MEDIA_IOC_DEVICE_INFO will return dev->driver->name. | |
289 | * This is needed for USB drivers for example, as otherwise | |
290 | * they'll all appear as if the driver name was "usb". | |
176fb0d1 LP |
291 | * @model: Device model name |
292 | * @serial: Device serial number (optional) | |
293 | * @bus_info: Unique and stable device location identifier | |
294 | * @hw_revision: Hardware device revision | |
295 | * @driver_version: Device driver version | |
2521fdac MCC |
296 | * @topology_version: Monotonic counter for storing the version of the graph |
297 | * topology. Should be incremented each time the topology changes. | |
05b3b77c | 298 | * @id: Unique ID used on the last registered graph object |
03e49338 MCC |
299 | * @entity_internal_idx: Unique internal entity ID used by the graph traversal |
300 | * algorithms | |
301 | * @entity_internal_idx_max: Allocated internal entity indices | |
53e269c1 | 302 | * @entities: List of registered entities |
57cf79b7 | 303 | * @interfaces: List of registered interfaces |
9155d859 MCC |
304 | * @pads: List of registered pads |
305 | * @links: List of registered links | |
afcbdb55 | 306 | * @entity_notify: List of registered entity_notify callbacks |
53e269c1 | 307 | * @lock: Entities list lock |
503c3d82 | 308 | * @graph_mutex: Entities graph operation lock |
0c426c47 SA |
309 | * @pm_count_walk: Graph walk for power state walk. Access serialised using |
310 | * graph_mutex. | |
cd87ce87 SK |
311 | * |
312 | * @source_priv: Driver Private data for enable/disable source handlers | |
313 | * @enable_source: Enable Source Handler function pointer | |
314 | * @disable_source: Disable Source Handler function pointer | |
315 | * | |
813f5c0a | 316 | * @link_notify: Link state change notification callback |
176fb0d1 LP |
317 | * |
318 | * This structure represents an abstract high-level media device. It allows easy | |
319 | * access to entities and provides basic media device-level support. The | |
320 | * structure can be allocated directly or embedded in a larger structure. | |
321 | * | |
322 | * The parent @dev is a physical device. It must be set before registering the | |
323 | * media device. | |
324 | * | |
325 | * @model is a descriptive model name exported through sysfs. It doesn't have to | |
326 | * be unique. | |
cd87ce87 SK |
327 | * |
328 | * @enable_source is a handler to find source entity for the | |
329 | * sink entity and activate the link between them if source | |
330 | * entity is free. Drivers should call this handler before | |
331 | * accessing the source. | |
332 | * | |
333 | * @disable_source is a handler to find source entity for the | |
334 | * sink entity and deactivate the link between them. Drivers | |
335 | * should call this handler to release the source. | |
336 | * | |
337 | * Note: Bridge driver is expected to implement and set the | |
338 | * handler when media_device is registered or when | |
339 | * bridge driver finds the media_device during probe. | |
340 | * Bridge driver sets source_priv with information | |
341 | * necessary to run enable/disable source handlers. | |
342 | * | |
343 | * Use-case: find tuner entity connected to the decoder | |
344 | * entity and check if it is available, and activate the | |
345 | * the link between them from enable_source and deactivate | |
346 | * from disable_source. | |
176fb0d1 LP |
347 | */ |
348 | struct media_device { | |
349 | /* dev->driver_data points to this struct. */ | |
350 | struct device *dev; | |
351 | struct media_devnode devnode; | |
352 | ||
353 | char model[32]; | |
bb07bd6b | 354 | char driver_name[32]; |
176fb0d1 LP |
355 | char serial[40]; |
356 | char bus_info[32]; | |
357 | u32 hw_revision; | |
358 | u32 driver_version; | |
53e269c1 | 359 | |
2521fdac MCC |
360 | u32 topology_version; |
361 | ||
05b3b77c | 362 | u32 id; |
665faa97 SA |
363 | struct ida entity_internal_idx; |
364 | int entity_internal_idx_max; | |
bfab2aac | 365 | |
53e269c1 | 366 | struct list_head entities; |
57cf79b7 | 367 | struct list_head interfaces; |
9155d859 MCC |
368 | struct list_head pads; |
369 | struct list_head links; | |
53e269c1 | 370 | |
afcbdb55 SK |
371 | /* notify callback list invoked when a new entity is registered */ |
372 | struct list_head entity_notify; | |
373 | ||
a08fad1e | 374 | /* Protects the graph objects creation/removal */ |
53e269c1 | 375 | spinlock_t lock; |
503c3d82 LP |
376 | /* Serializes graph operations. */ |
377 | struct mutex graph_mutex; | |
0c426c47 | 378 | struct media_entity_graph pm_count_walk; |
97548ed4 | 379 | |
cd87ce87 SK |
380 | void *source_priv; |
381 | int (*enable_source)(struct media_entity *entity, | |
382 | struct media_pipeline *pipe); | |
383 | void (*disable_source)(struct media_entity *entity); | |
384 | ||
813f5c0a SN |
385 | int (*link_notify)(struct media_link *link, u32 flags, |
386 | unsigned int notification); | |
176fb0d1 LP |
387 | }; |
388 | ||
41b44e35 MCC |
389 | /* We don't need to include pci.h or usb.h here */ |
390 | struct pci_dev; | |
391 | struct usb_device; | |
392 | ||
e576d60b SK |
393 | #ifdef CONFIG_MEDIA_CONTROLLER |
394 | ||
813f5c0a SN |
395 | /* Supported link_notify @notification values. */ |
396 | #define MEDIA_DEV_NOTIFY_PRE_LINK_CH 0 | |
397 | #define MEDIA_DEV_NOTIFY_POST_LINK_CH 1 | |
398 | ||
176fb0d1 LP |
399 | /* media_devnode to media_device */ |
400 | #define to_media_device(node) container_of(node, struct media_device, devnode) | |
401 | ||
c8d54cd5 SA |
402 | /** |
403 | * media_entity_enum_init - Initialise an entity enumeration | |
404 | * | |
03e49338 | 405 | * @ent_enum: Entity enumeration to be initialised |
c8d54cd5 SA |
406 | * @mdev: The related media device |
407 | * | |
408 | * Returns zero on success or a negative error code. | |
409 | */ | |
410 | static inline __must_check int media_entity_enum_init( | |
411 | struct media_entity_enum *ent_enum, struct media_device *mdev) | |
412 | { | |
413 | return __media_entity_enum_init(ent_enum, | |
414 | mdev->entity_internal_idx_max + 1); | |
415 | } | |
416 | ||
9832e155 JMC |
417 | /** |
418 | * media_device_init() - Initializes a media device element | |
419 | * | |
420 | * @mdev: pointer to struct &media_device | |
421 | * | |
422 | * This function initializes the media device prior to its registration. | |
423 | * The media device initialization and registration is split in two functions | |
424 | * to avoid race conditions and make the media device available to user-space | |
425 | * before the media graph has been completed. | |
426 | * | |
427 | * So drivers need to first initialize the media device, register any entity | |
428 | * within the media device, create pad to pad links and then finally register | |
429 | * the media device by calling media_device_register() as a final step. | |
430 | */ | |
431 | void media_device_init(struct media_device *mdev); | |
432 | ||
433 | /** | |
434 | * media_device_cleanup() - Cleanups a media device element | |
435 | * | |
436 | * @mdev: pointer to struct &media_device | |
437 | * | |
438 | * This function that will destroy the graph_mutex that is | |
439 | * initialized in media_device_init(). | |
440 | */ | |
441 | void media_device_cleanup(struct media_device *mdev); | |
442 | ||
db7ee32a MCC |
443 | /** |
444 | * __media_device_register() - Registers a media device element | |
445 | * | |
446 | * @mdev: pointer to struct &media_device | |
447 | * @owner: should be filled with %THIS_MODULE | |
448 | * | |
449 | * Users, should, instead, call the media_device_register() macro. | |
450 | * | |
451 | * The caller is responsible for initializing the media_device structure before | |
452 | * registration. The following fields must be set: | |
453 | * | |
454 | * - dev must point to the parent device (usually a &pci_dev, &usb_interface or | |
455 | * &platform_device instance). | |
456 | * | |
457 | * - model must be filled with the device model name as a NUL-terminated UTF-8 | |
458 | * string. The device/model revision must not be stored in this field. | |
459 | * | |
460 | * The following fields are optional: | |
461 | * | |
462 | * - serial is a unique serial number stored as a NUL-terminated ASCII string. | |
463 | * The field is big enough to store a GUID in text form. If the hardware | |
464 | * doesn't provide a unique serial number this field must be left empty. | |
465 | * | |
466 | * - bus_info represents the location of the device in the system as a | |
467 | * NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to | |
468 | * "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, | |
469 | * the usb_make_path() function must be used. This field is used by | |
470 | * applications to distinguish between otherwise identical devices that don't | |
471 | * provide a serial number. | |
472 | * | |
473 | * - hw_revision is the hardware device revision in a driver-specific format. | |
474 | * When possible the revision should be formatted with the KERNEL_VERSION | |
475 | * macro. | |
476 | * | |
477 | * - driver_version is formatted with the KERNEL_VERSION macro. The version | |
478 | * minor must be incremented when new features are added to the userspace API | |
479 | * without breaking binary compatibility. The version major must be | |
480 | * incremented when binary compatibility is broken. | |
481 | * | |
482 | * Notes: | |
483 | * | |
484 | * Upon successful registration a character device named media[0-9]+ is created. | |
485 | * The device major and minor numbers are dynamic. The model name is exported as | |
486 | * a sysfs attribute. | |
487 | * | |
488 | * Unregistering a media device that hasn't been registered is *NOT* safe. | |
92777994 MCC |
489 | * |
490 | * Return: returns zero on success or a negative error code. | |
db7ee32a | 491 | */ |
85de721c SA |
492 | int __must_check __media_device_register(struct media_device *mdev, |
493 | struct module *owner); | |
494 | #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE) | |
db7ee32a MCC |
495 | |
496 | /** | |
497 | * __media_device_unregister() - Unegisters a media device element | |
498 | * | |
499 | * @mdev: pointer to struct &media_device | |
92777994 MCC |
500 | * |
501 | * | |
502 | * It is safe to call this function on an unregistered (but initialised) | |
503 | * media device. | |
db7ee32a | 504 | */ |
176fb0d1 LP |
505 | void media_device_unregister(struct media_device *mdev); |
506 | ||
db7ee32a MCC |
507 | /** |
508 | * media_device_register_entity() - registers a media entity inside a | |
509 | * previously registered media device. | |
510 | * | |
511 | * @mdev: pointer to struct &media_device | |
512 | * @entity: pointer to struct &media_entity to be registered | |
513 | * | |
514 | * Entities are identified by a unique positive integer ID. The media | |
515 | * controller framework will such ID automatically. IDs are not guaranteed | |
516 | * to be contiguous, and the ID number can change on newer Kernel versions. | |
517 | * So, neither the driver nor userspace should hardcode ID numbers to refer | |
518 | * to the entities, but, instead, use the framework to find the ID, when | |
519 | * needed. | |
520 | * | |
521 | * The media_entity name, type and flags fields should be initialized before | |
522 | * calling media_device_register_entity(). Entities embedded in higher-level | |
523 | * standard structures can have some of those fields set by the higher-level | |
524 | * framework. | |
525 | * | |
526 | * If the device has pads, media_entity_pads_init() should be called before | |
527 | * this function. Otherwise, the &media_entity.@pad and &media_entity.@num_pads | |
528 | * should be zeroed before calling this function. | |
529 | * | |
530 | * Entities have flags that describe the entity capabilities and state: | |
531 | * | |
532 | * %MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. | |
533 | * This can be used to report the default audio and video devices or the | |
534 | * default camera sensor. | |
d1b9da2d MCC |
535 | * |
536 | * NOTE: Drivers should set the entity function before calling this function. | |
537 | * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and | |
538 | * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers. | |
db7ee32a | 539 | */ |
53e269c1 LP |
540 | int __must_check media_device_register_entity(struct media_device *mdev, |
541 | struct media_entity *entity); | |
db7ee32a MCC |
542 | |
543 | /* | |
544 | * media_device_unregister_entity() - unregisters a media entity. | |
545 | * | |
546 | * @entity: pointer to struct &media_entity to be unregistered | |
547 | * | |
548 | * All links associated with the entity and all PADs are automatically | |
549 | * unregistered from the media_device when this function is called. | |
550 | * | |
551 | * Unregistering an entity will not change the IDs of the other entities and | |
552 | * the previoully used ID will never be reused for a newly registered entities. | |
553 | * | |
554 | * When a media device is unregistered, all its entities are unregistered | |
555 | * automatically. No manual entities unregistration is then required. | |
556 | * | |
557 | * Note: the media_entity instance itself must be freed explicitly by | |
558 | * the driver if required. | |
559 | */ | |
53e269c1 | 560 | void media_device_unregister_entity(struct media_entity *entity); |
b6e4ca81 | 561 | |
afcbdb55 SK |
562 | /** |
563 | * media_device_register_entity_notify() - Registers a media entity_notify | |
564 | * callback | |
565 | * | |
566 | * @mdev: The media device | |
567 | * @nptr: The media_entity_notify | |
568 | * | |
569 | * Note: When a new entity is registered, all the registered | |
570 | * media_entity_notify callbacks are invoked. | |
571 | */ | |
572 | ||
573 | int __must_check media_device_register_entity_notify(struct media_device *mdev, | |
574 | struct media_entity_notify *nptr); | |
575 | ||
576 | /** | |
577 | * media_device_unregister_entity_notify() - Unregister a media entity notify | |
578 | * callback | |
579 | * | |
580 | * @mdev: The media device | |
581 | * @nptr: The media_entity_notify | |
582 | * | |
583 | */ | |
584 | void media_device_unregister_entity_notify(struct media_device *mdev, | |
585 | struct media_entity_notify *nptr); | |
586 | ||
b6e4ca81 MCC |
587 | /** |
588 | * media_device_get_devres() - get media device as device resource | |
589 | * creates if one doesn't exist | |
590 | * | |
591 | * @dev: pointer to struct &device. | |
592 | * | |
593 | * Sometimes, the media controller &media_device needs to be shared by more | |
594 | * than one driver. This function adds support for that, by dynamically | |
595 | * allocating the &media_device and allowing it to be obtained from the | |
596 | * struct &device associated with the common device where all sub-device | |
597 | * components belong. So, for example, on an USB device with multiple | |
598 | * interfaces, each interface may be handled by a separate per-interface | |
599 | * drivers. While each interface have its own &device, they all share a | |
600 | * common &device associated with the hole USB device. | |
601 | */ | |
d062f911 | 602 | struct media_device *media_device_get_devres(struct device *dev); |
b6e4ca81 MCC |
603 | |
604 | /** | |
605 | * media_device_find_devres() - find media device as device resource | |
606 | * | |
607 | * @dev: pointer to struct &device. | |
608 | */ | |
d062f911 | 609 | struct media_device *media_device_find_devres(struct device *dev); |
53e269c1 LP |
610 | |
611 | /* Iterate over all entities. */ | |
612 | #define media_device_for_each_entity(entity, mdev) \ | |
05bfa9fa | 613 | list_for_each_entry(entity, &(mdev)->entities, graph_obj.list) |
53e269c1 | 614 | |
cf975a4b MCC |
615 | /* Iterate over all interfaces. */ |
616 | #define media_device_for_each_intf(intf, mdev) \ | |
05bfa9fa | 617 | list_for_each_entry(intf, &(mdev)->interfaces, graph_obj.list) |
cf975a4b | 618 | |
9155d859 MCC |
619 | /* Iterate over all pads. */ |
620 | #define media_device_for_each_pad(pad, mdev) \ | |
621 | list_for_each_entry(pad, &(mdev)->pads, graph_obj.list) | |
622 | ||
623 | /* Iterate over all links. */ | |
624 | #define media_device_for_each_link(link, mdev) \ | |
625 | list_for_each_entry(link, &(mdev)->links, graph_obj.list) | |
41b44e35 MCC |
626 | |
627 | /** | |
628 | * media_device_pci_init() - create and initialize a | |
629 | * struct &media_device from a PCI device. | |
630 | * | |
6cf5dad1 | 631 | * @mdev: pointer to struct &media_device |
41b44e35 MCC |
632 | * @pci_dev: pointer to struct pci_dev |
633 | * @name: media device name. If %NULL, the routine will use the default | |
634 | * name for the pci device, given by pci_name() macro. | |
635 | */ | |
6cf5dad1 MCC |
636 | void media_device_pci_init(struct media_device *mdev, |
637 | struct pci_dev *pci_dev, | |
638 | const char *name); | |
41b44e35 MCC |
639 | /** |
640 | * __media_device_usb_init() - create and initialize a | |
641 | * struct &media_device from a PCI device. | |
642 | * | |
6cf5dad1 | 643 | * @mdev: pointer to struct &media_device |
41b44e35 MCC |
644 | * @udev: pointer to struct usb_device |
645 | * @board_name: media device name. If %NULL, the routine will use the usb | |
646 | * product name, if available. | |
647 | * @driver_name: name of the driver. if %NULL, the routine will use the name | |
648 | * given by udev->dev->driver->name, with is usually the wrong | |
649 | * thing to do. | |
650 | * | |
651 | * NOTE: It is better to call media_device_usb_init() instead, as | |
652 | * such macro fills driver_name with %KBUILD_MODNAME. | |
653 | */ | |
6cf5dad1 MCC |
654 | void __media_device_usb_init(struct media_device *mdev, |
655 | struct usb_device *udev, | |
656 | const char *board_name, | |
657 | const char *driver_name); | |
41b44e35 | 658 | |
e576d60b SK |
659 | #else |
660 | static inline int media_device_register(struct media_device *mdev) | |
661 | { | |
662 | return 0; | |
663 | } | |
664 | static inline void media_device_unregister(struct media_device *mdev) | |
665 | { | |
666 | } | |
667 | static inline int media_device_register_entity(struct media_device *mdev, | |
668 | struct media_entity *entity) | |
669 | { | |
670 | return 0; | |
671 | } | |
672 | static inline void media_device_unregister_entity(struct media_entity *entity) | |
673 | { | |
674 | } | |
afcbdb55 SK |
675 | static inline int media_device_register_entity_notify( |
676 | struct media_device *mdev, | |
677 | struct media_entity_notify *nptr) | |
678 | { | |
679 | return 0; | |
680 | } | |
681 | static inline void media_device_unregister_entity_notify( | |
682 | struct media_device *mdev, | |
683 | struct media_entity_notify *nptr) | |
684 | { | |
685 | } | |
e576d60b SK |
686 | static inline struct media_device *media_device_get_devres(struct device *dev) |
687 | { | |
688 | return NULL; | |
689 | } | |
690 | static inline struct media_device *media_device_find_devres(struct device *dev) | |
691 | { | |
692 | return NULL; | |
693 | } | |
41b44e35 | 694 | |
6cf5dad1 MCC |
695 | static inline void media_device_pci_init(struct media_device *mdev, |
696 | struct pci_dev *pci_dev, | |
697 | char *name) | |
41b44e35 | 698 | { |
41b44e35 MCC |
699 | } |
700 | ||
6cf5dad1 MCC |
701 | static inline void __media_device_usb_init(struct media_device *mdev, |
702 | struct usb_device *udev, | |
703 | char *board_name, | |
704 | char *driver_name) | |
41b44e35 | 705 | { |
41b44e35 MCC |
706 | } |
707 | ||
e576d60b | 708 | #endif /* CONFIG_MEDIA_CONTROLLER */ |
41b44e35 | 709 | |
6cf5dad1 MCC |
710 | #define media_device_usb_init(mdev, udev, name) \ |
711 | __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME) | |
41b44e35 | 712 | |
176fb0d1 | 713 | #endif |