Commit | Line | Data |
---|---|---|
1802d0be | 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
176fb0d1 LP |
2 | /* |
3 | * Media device | |
4 | * | |
5 | * Copyright (C) 2010 Nokia Corporation | |
6 | * | |
7 | * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> | |
8 | * Sakari Ailus <sakari.ailus@iki.fi> | |
176fb0d1 LP |
9 | */ |
10 | ||
11 | #ifndef _MEDIA_DEVICE_H | |
12 | #define _MEDIA_DEVICE_H | |
13 | ||
176fb0d1 | 14 | #include <linux/list.h> |
503c3d82 | 15 | #include <linux/mutex.h> |
176fb0d1 LP |
16 | |
17 | #include <media/media-devnode.h> | |
53e269c1 | 18 | #include <media/media-entity.h> |
176fb0d1 | 19 | |
665faa97 | 20 | struct ida; |
313162d0 | 21 | struct device; |
10905d70 | 22 | struct media_device; |
313162d0 | 23 | |
afcbdb55 SK |
24 | /** |
25 | * struct media_entity_notify - Media Entity Notify | |
26 | * | |
27 | * @list: List head | |
28 | * @notify_data: Input data to invoke the callback | |
29 | * @notify: Callback function pointer | |
30 | * | |
fc641261 SK |
31 | * Drivers may register a callback to take action when new entities get |
32 | * registered with the media device. This handler is intended for creating | |
33 | * links between existing entities and should not create entities and register | |
34 | * them. | |
afcbdb55 SK |
35 | */ |
36 | struct media_entity_notify { | |
37 | struct list_head list; | |
38 | void *notify_data; | |
39 | void (*notify)(struct media_entity *entity, void *notify_data); | |
40 | }; | |
41 | ||
68429f50 LP |
42 | /** |
43 | * struct media_device_ops - Media device operations | |
44 | * @link_notify: Link state change notification callback. This callback is | |
45 | * called with the graph_mutex held. | |
10905d70 HV |
46 | * @req_alloc: Allocate a request. Set this if you need to allocate a struct |
47 | * larger then struct media_request. @req_alloc and @req_free must | |
48 | * either both be set or both be NULL. | |
49 | * @req_free: Free a request. Set this if @req_alloc was set as well, leave | |
50 | * to NULL otherwise. | |
51 | * @req_validate: Validate a request, but do not queue yet. The req_queue_mutex | |
52 | * lock is held when this op is called. | |
53 | * @req_queue: Queue a validated request, cannot fail. If something goes | |
54 | * wrong when queueing this request then it should be marked | |
55 | * as such internally in the driver and any related buffers | |
56 | * must eventually return to vb2 with state VB2_BUF_STATE_ERROR. | |
57 | * The req_queue_mutex lock is held when this op is called. | |
58 | * It is important that vb2 buffer objects are queued last after | |
59 | * all other object types are queued: queueing a buffer kickstarts | |
60 | * the request processing, so all other objects related to the | |
61 | * request (and thus the buffer) must be available to the driver. | |
62 | * And once a buffer is queued, then the driver can complete | |
63 | * or delete objects from the request before req_queue exits. | |
68429f50 LP |
64 | */ |
65 | struct media_device_ops { | |
66 | int (*link_notify)(struct media_link *link, u32 flags, | |
67 | unsigned int notification); | |
10905d70 HV |
68 | struct media_request *(*req_alloc)(struct media_device *mdev); |
69 | void (*req_free)(struct media_request *req); | |
70 | int (*req_validate)(struct media_request *req); | |
71 | void (*req_queue)(struct media_request *req); | |
68429f50 LP |
72 | }; |
73 | ||
176fb0d1 LP |
74 | /** |
75 | * struct media_device - Media device | |
76 | * @dev: Parent device | |
77 | * @devnode: Media device node | |
bb07bd6b | 78 | * @driver_name: Optional device driver name. If not set, calls to |
48a7c4ba | 79 | * %MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``. |
bb07bd6b MCC |
80 | * This is needed for USB drivers for example, as otherwise |
81 | * they'll all appear as if the driver name was "usb". | |
176fb0d1 LP |
82 | * @model: Device model name |
83 | * @serial: Device serial number (optional) | |
84 | * @bus_info: Unique and stable device location identifier | |
85 | * @hw_revision: Hardware device revision | |
2521fdac MCC |
86 | * @topology_version: Monotonic counter for storing the version of the graph |
87 | * topology. Should be incremented each time the topology changes. | |
05b3b77c | 88 | * @id: Unique ID used on the last registered graph object |
03e49338 MCC |
89 | * @entity_internal_idx: Unique internal entity ID used by the graph traversal |
90 | * algorithms | |
91 | * @entity_internal_idx_max: Allocated internal entity indices | |
53e269c1 | 92 | * @entities: List of registered entities |
57cf79b7 | 93 | * @interfaces: List of registered interfaces |
9155d859 MCC |
94 | * @pads: List of registered pads |
95 | * @links: List of registered links | |
afcbdb55 | 96 | * @entity_notify: List of registered entity_notify callbacks |
e2c91d4d | 97 | * @graph_mutex: Protects access to struct media_device data |
0c426c47 SA |
98 | * @pm_count_walk: Graph walk for power state walk. Access serialised using |
99 | * graph_mutex. | |
cd87ce87 SK |
100 | * |
101 | * @source_priv: Driver Private data for enable/disable source handlers | |
102 | * @enable_source: Enable Source Handler function pointer | |
103 | * @disable_source: Disable Source Handler function pointer | |
104 | * | |
68429f50 | 105 | * @ops: Operation handler callbacks |
10905d70 HV |
106 | * @req_queue_mutex: Serialise the MEDIA_REQUEST_IOC_QUEUE ioctl w.r.t. |
107 | * other operations that stop or start streaming. | |
108 | * @request_id: Used to generate unique request IDs | |
176fb0d1 LP |
109 | * |
110 | * This structure represents an abstract high-level media device. It allows easy | |
111 | * access to entities and provides basic media device-level support. The | |
112 | * structure can be allocated directly or embedded in a larger structure. | |
113 | * | |
114 | * The parent @dev is a physical device. It must be set before registering the | |
115 | * media device. | |
116 | * | |
117 | * @model is a descriptive model name exported through sysfs. It doesn't have to | |
118 | * be unique. | |
cd87ce87 SK |
119 | * |
120 | * @enable_source is a handler to find source entity for the | |
121 | * sink entity and activate the link between them if source | |
122 | * entity is free. Drivers should call this handler before | |
123 | * accessing the source. | |
124 | * | |
125 | * @disable_source is a handler to find source entity for the | |
126 | * sink entity and deactivate the link between them. Drivers | |
127 | * should call this handler to release the source. | |
128 | * | |
cd87ce87 SK |
129 | * Use-case: find tuner entity connected to the decoder |
130 | * entity and check if it is available, and activate the | |
48a7c4ba MCC |
131 | * the link between them from @enable_source and deactivate |
132 | * from @disable_source. | |
133 | * | |
134 | * .. note:: | |
135 | * | |
136 | * Bridge driver is expected to implement and set the | |
137 | * handler when &media_device is registered or when | |
138 | * bridge driver finds the media_device during probe. | |
139 | * Bridge driver sets source_priv with information | |
140 | * necessary to run @enable_source and @disable_source handlers. | |
90cd366b SK |
141 | * Callers should hold graph_mutex to access and call @enable_source |
142 | * and @disable_source handlers. | |
176fb0d1 LP |
143 | */ |
144 | struct media_device { | |
145 | /* dev->driver_data points to this struct. */ | |
146 | struct device *dev; | |
a087ce70 | 147 | struct media_devnode *devnode; |
176fb0d1 LP |
148 | |
149 | char model[32]; | |
bb07bd6b | 150 | char driver_name[32]; |
176fb0d1 LP |
151 | char serial[40]; |
152 | char bus_info[32]; | |
153 | u32 hw_revision; | |
53e269c1 | 154 | |
952f8eef | 155 | u64 topology_version; |
2521fdac | 156 | |
05b3b77c | 157 | u32 id; |
665faa97 SA |
158 | struct ida entity_internal_idx; |
159 | int entity_internal_idx_max; | |
bfab2aac | 160 | |
53e269c1 | 161 | struct list_head entities; |
57cf79b7 | 162 | struct list_head interfaces; |
9155d859 MCC |
163 | struct list_head pads; |
164 | struct list_head links; | |
53e269c1 | 165 | |
afcbdb55 SK |
166 | /* notify callback list invoked when a new entity is registered */ |
167 | struct list_head entity_notify; | |
168 | ||
503c3d82 LP |
169 | /* Serializes graph operations. */ |
170 | struct mutex graph_mutex; | |
20b85227 | 171 | struct media_graph pm_count_walk; |
97548ed4 | 172 | |
cd87ce87 SK |
173 | void *source_priv; |
174 | int (*enable_source)(struct media_entity *entity, | |
175 | struct media_pipeline *pipe); | |
176 | void (*disable_source)(struct media_entity *entity); | |
177 | ||
68429f50 | 178 | const struct media_device_ops *ops; |
10905d70 HV |
179 | |
180 | struct mutex req_queue_mutex; | |
181 | atomic_t request_id; | |
176fb0d1 LP |
182 | }; |
183 | ||
41b44e35 MCC |
184 | /* We don't need to include pci.h or usb.h here */ |
185 | struct pci_dev; | |
186 | struct usb_device; | |
187 | ||
e576d60b SK |
188 | #ifdef CONFIG_MEDIA_CONTROLLER |
189 | ||
813f5c0a SN |
190 | /* Supported link_notify @notification values. */ |
191 | #define MEDIA_DEV_NOTIFY_PRE_LINK_CH 0 | |
192 | #define MEDIA_DEV_NOTIFY_POST_LINK_CH 1 | |
193 | ||
c8d54cd5 SA |
194 | /** |
195 | * media_entity_enum_init - Initialise an entity enumeration | |
196 | * | |
03e49338 | 197 | * @ent_enum: Entity enumeration to be initialised |
c8d54cd5 SA |
198 | * @mdev: The related media device |
199 | * | |
48a7c4ba | 200 | * Return: zero on success or a negative error code. |
c8d54cd5 SA |
201 | */ |
202 | static inline __must_check int media_entity_enum_init( | |
203 | struct media_entity_enum *ent_enum, struct media_device *mdev) | |
204 | { | |
205 | return __media_entity_enum_init(ent_enum, | |
206 | mdev->entity_internal_idx_max + 1); | |
207 | } | |
208 | ||
9832e155 JMC |
209 | /** |
210 | * media_device_init() - Initializes a media device element | |
211 | * | |
212 | * @mdev: pointer to struct &media_device | |
213 | * | |
214 | * This function initializes the media device prior to its registration. | |
215 | * The media device initialization and registration is split in two functions | |
216 | * to avoid race conditions and make the media device available to user-space | |
217 | * before the media graph has been completed. | |
218 | * | |
219 | * So drivers need to first initialize the media device, register any entity | |
220 | * within the media device, create pad to pad links and then finally register | |
221 | * the media device by calling media_device_register() as a final step. | |
222 | */ | |
223 | void media_device_init(struct media_device *mdev); | |
224 | ||
225 | /** | |
226 | * media_device_cleanup() - Cleanups a media device element | |
227 | * | |
228 | * @mdev: pointer to struct &media_device | |
229 | * | |
230 | * This function that will destroy the graph_mutex that is | |
231 | * initialized in media_device_init(). | |
232 | */ | |
233 | void media_device_cleanup(struct media_device *mdev); | |
234 | ||
db7ee32a MCC |
235 | /** |
236 | * __media_device_register() - Registers a media device element | |
237 | * | |
238 | * @mdev: pointer to struct &media_device | |
239 | * @owner: should be filled with %THIS_MODULE | |
240 | * | |
241 | * Users, should, instead, call the media_device_register() macro. | |
242 | * | |
48a7c4ba MCC |
243 | * The caller is responsible for initializing the &media_device structure |
244 | * before registration. The following fields of &media_device must be set: | |
db7ee32a | 245 | * |
48a7c4ba MCC |
246 | * - &media_entity.dev must point to the parent device (usually a &pci_dev, |
247 | * &usb_interface or &platform_device instance). | |
db7ee32a | 248 | * |
48a7c4ba MCC |
249 | * - &media_entity.model must be filled with the device model name as a |
250 | * NUL-terminated UTF-8 string. The device/model revision must not be | |
251 | * stored in this field. | |
db7ee32a MCC |
252 | * |
253 | * The following fields are optional: | |
254 | * | |
48a7c4ba MCC |
255 | * - &media_entity.serial is a unique serial number stored as a |
256 | * NUL-terminated ASCII string. The field is big enough to store a GUID | |
257 | * in text form. If the hardware doesn't provide a unique serial number | |
258 | * this field must be left empty. | |
db7ee32a | 259 | * |
48a7c4ba MCC |
260 | * - &media_entity.bus_info represents the location of the device in the |
261 | * system as a NUL-terminated ASCII string. For PCI/PCIe devices | |
262 | * &media_entity.bus_info must be set to "PCI:" (or "PCIe:") followed by | |
263 | * the value of pci_name(). For USB devices,the usb_make_path() function | |
264 | * must be used. This field is used by applications to distinguish between | |
265 | * otherwise identical devices that don't provide a serial number. | |
db7ee32a | 266 | * |
48a7c4ba MCC |
267 | * - &media_entity.hw_revision is the hardware device revision in a |
268 | * driver-specific format. When possible the revision should be formatted | |
269 | * with the KERNEL_VERSION() macro. | |
db7ee32a | 270 | * |
74604b73 | 271 | * .. note:: |
db7ee32a | 272 | * |
74604b73 | 273 | * #) Upon successful registration a character device named media[0-9]+ is created. The device major and minor numbers are dynamic. The model name is exported as a sysfs attribute. |
db7ee32a | 274 | * |
74604b73 | 275 | * #) Unregistering a media device that hasn't been registered is **NOT** safe. |
92777994 MCC |
276 | * |
277 | * Return: returns zero on success or a negative error code. | |
db7ee32a | 278 | */ |
85de721c SA |
279 | int __must_check __media_device_register(struct media_device *mdev, |
280 | struct module *owner); | |
48a7c4ba MCC |
281 | |
282 | ||
283 | /** | |
284 | * media_device_register() - Registers a media device element | |
285 | * | |
286 | * @mdev: pointer to struct &media_device | |
287 | * | |
288 | * This macro calls __media_device_register() passing %THIS_MODULE as | |
289 | * the __media_device_register() second argument (**owner**). | |
290 | */ | |
85de721c | 291 | #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE) |
db7ee32a MCC |
292 | |
293 | /** | |
3047f3f9 | 294 | * media_device_unregister() - Unregisters a media device element |
db7ee32a MCC |
295 | * |
296 | * @mdev: pointer to struct &media_device | |
92777994 | 297 | * |
92777994 MCC |
298 | * It is safe to call this function on an unregistered (but initialised) |
299 | * media device. | |
db7ee32a | 300 | */ |
176fb0d1 LP |
301 | void media_device_unregister(struct media_device *mdev); |
302 | ||
db7ee32a MCC |
303 | /** |
304 | * media_device_register_entity() - registers a media entity inside a | |
305 | * previously registered media device. | |
306 | * | |
307 | * @mdev: pointer to struct &media_device | |
308 | * @entity: pointer to struct &media_entity to be registered | |
309 | * | |
310 | * Entities are identified by a unique positive integer ID. The media | |
311 | * controller framework will such ID automatically. IDs are not guaranteed | |
312 | * to be contiguous, and the ID number can change on newer Kernel versions. | |
313 | * So, neither the driver nor userspace should hardcode ID numbers to refer | |
314 | * to the entities, but, instead, use the framework to find the ID, when | |
315 | * needed. | |
316 | * | |
317 | * The media_entity name, type and flags fields should be initialized before | |
318 | * calling media_device_register_entity(). Entities embedded in higher-level | |
319 | * standard structures can have some of those fields set by the higher-level | |
320 | * framework. | |
321 | * | |
322 | * If the device has pads, media_entity_pads_init() should be called before | |
48a7c4ba | 323 | * this function. Otherwise, the &media_entity.pad and &media_entity.num_pads |
db7ee32a MCC |
324 | * should be zeroed before calling this function. |
325 | * | |
326 | * Entities have flags that describe the entity capabilities and state: | |
327 | * | |
48a7c4ba MCC |
328 | * %MEDIA_ENT_FL_DEFAULT |
329 | * indicates the default entity for a given type. | |
330 | * This can be used to report the default audio and video devices or the | |
331 | * default camera sensor. | |
d1b9da2d | 332 | * |
74604b73 MCC |
333 | * .. note:: |
334 | * | |
335 | * Drivers should set the entity function before calling this function. | |
336 | * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and | |
337 | * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers. | |
db7ee32a | 338 | */ |
53e269c1 LP |
339 | int __must_check media_device_register_entity(struct media_device *mdev, |
340 | struct media_entity *entity); | |
db7ee32a | 341 | |
74604b73 | 342 | /** |
db7ee32a MCC |
343 | * media_device_unregister_entity() - unregisters a media entity. |
344 | * | |
345 | * @entity: pointer to struct &media_entity to be unregistered | |
346 | * | |
347 | * All links associated with the entity and all PADs are automatically | |
348 | * unregistered from the media_device when this function is called. | |
349 | * | |
350 | * Unregistering an entity will not change the IDs of the other entities and | |
351 | * the previoully used ID will never be reused for a newly registered entities. | |
352 | * | |
353 | * When a media device is unregistered, all its entities are unregistered | |
354 | * automatically. No manual entities unregistration is then required. | |
355 | * | |
74604b73 MCC |
356 | * .. note:: |
357 | * | |
358 | * The media_entity instance itself must be freed explicitly by | |
359 | * the driver if required. | |
db7ee32a | 360 | */ |
53e269c1 | 361 | void media_device_unregister_entity(struct media_entity *entity); |
b6e4ca81 | 362 | |
afcbdb55 SK |
363 | /** |
364 | * media_device_register_entity_notify() - Registers a media entity_notify | |
365 | * callback | |
366 | * | |
367 | * @mdev: The media device | |
368 | * @nptr: The media_entity_notify | |
369 | * | |
48a7c4ba MCC |
370 | * .. note:: |
371 | * | |
372 | * When a new entity is registered, all the registered | |
373 | * media_entity_notify callbacks are invoked. | |
afcbdb55 SK |
374 | */ |
375 | ||
376 | int __must_check media_device_register_entity_notify(struct media_device *mdev, | |
377 | struct media_entity_notify *nptr); | |
378 | ||
379 | /** | |
380 | * media_device_unregister_entity_notify() - Unregister a media entity notify | |
381 | * callback | |
382 | * | |
383 | * @mdev: The media device | |
384 | * @nptr: The media_entity_notify | |
385 | * | |
386 | */ | |
387 | void media_device_unregister_entity_notify(struct media_device *mdev, | |
388 | struct media_entity_notify *nptr); | |
389 | ||
53e269c1 LP |
390 | /* Iterate over all entities. */ |
391 | #define media_device_for_each_entity(entity, mdev) \ | |
05bfa9fa | 392 | list_for_each_entry(entity, &(mdev)->entities, graph_obj.list) |
53e269c1 | 393 | |
cf975a4b MCC |
394 | /* Iterate over all interfaces. */ |
395 | #define media_device_for_each_intf(intf, mdev) \ | |
05bfa9fa | 396 | list_for_each_entry(intf, &(mdev)->interfaces, graph_obj.list) |
cf975a4b | 397 | |
9155d859 MCC |
398 | /* Iterate over all pads. */ |
399 | #define media_device_for_each_pad(pad, mdev) \ | |
400 | list_for_each_entry(pad, &(mdev)->pads, graph_obj.list) | |
401 | ||
402 | /* Iterate over all links. */ | |
403 | #define media_device_for_each_link(link, mdev) \ | |
404 | list_for_each_entry(link, &(mdev)->links, graph_obj.list) | |
41b44e35 MCC |
405 | |
406 | /** | |
407 | * media_device_pci_init() - create and initialize a | |
408 | * struct &media_device from a PCI device. | |
409 | * | |
6cf5dad1 | 410 | * @mdev: pointer to struct &media_device |
41b44e35 MCC |
411 | * @pci_dev: pointer to struct pci_dev |
412 | * @name: media device name. If %NULL, the routine will use the default | |
413 | * name for the pci device, given by pci_name() macro. | |
414 | */ | |
6cf5dad1 MCC |
415 | void media_device_pci_init(struct media_device *mdev, |
416 | struct pci_dev *pci_dev, | |
417 | const char *name); | |
41b44e35 MCC |
418 | /** |
419 | * __media_device_usb_init() - create and initialize a | |
420 | * struct &media_device from a PCI device. | |
421 | * | |
6cf5dad1 | 422 | * @mdev: pointer to struct &media_device |
41b44e35 MCC |
423 | * @udev: pointer to struct usb_device |
424 | * @board_name: media device name. If %NULL, the routine will use the usb | |
425 | * product name, if available. | |
426 | * @driver_name: name of the driver. if %NULL, the routine will use the name | |
48a7c4ba | 427 | * given by ``udev->dev->driver->name``, with is usually the wrong |
41b44e35 MCC |
428 | * thing to do. |
429 | * | |
48a7c4ba MCC |
430 | * .. note:: |
431 | * | |
432 | * It is better to call media_device_usb_init() instead, as | |
433 | * such macro fills driver_name with %KBUILD_MODNAME. | |
41b44e35 | 434 | */ |
6cf5dad1 MCC |
435 | void __media_device_usb_init(struct media_device *mdev, |
436 | struct usb_device *udev, | |
437 | const char *board_name, | |
438 | const char *driver_name); | |
41b44e35 | 439 | |
e576d60b SK |
440 | #else |
441 | static inline int media_device_register(struct media_device *mdev) | |
442 | { | |
443 | return 0; | |
444 | } | |
445 | static inline void media_device_unregister(struct media_device *mdev) | |
446 | { | |
447 | } | |
448 | static inline int media_device_register_entity(struct media_device *mdev, | |
449 | struct media_entity *entity) | |
450 | { | |
451 | return 0; | |
452 | } | |
453 | static inline void media_device_unregister_entity(struct media_entity *entity) | |
454 | { | |
455 | } | |
afcbdb55 SK |
456 | static inline int media_device_register_entity_notify( |
457 | struct media_device *mdev, | |
458 | struct media_entity_notify *nptr) | |
459 | { | |
460 | return 0; | |
461 | } | |
462 | static inline void media_device_unregister_entity_notify( | |
463 | struct media_device *mdev, | |
464 | struct media_entity_notify *nptr) | |
465 | { | |
466 | } | |
41b44e35 | 467 | |
6cf5dad1 MCC |
468 | static inline void media_device_pci_init(struct media_device *mdev, |
469 | struct pci_dev *pci_dev, | |
470 | char *name) | |
41b44e35 | 471 | { |
41b44e35 MCC |
472 | } |
473 | ||
6cf5dad1 MCC |
474 | static inline void __media_device_usb_init(struct media_device *mdev, |
475 | struct usb_device *udev, | |
476 | char *board_name, | |
477 | char *driver_name) | |
41b44e35 | 478 | { |
41b44e35 MCC |
479 | } |
480 | ||
e576d60b | 481 | #endif /* CONFIG_MEDIA_CONTROLLER */ |
41b44e35 | 482 | |
48a7c4ba MCC |
483 | /** |
484 | * media_device_usb_init() - create and initialize a | |
485 | * struct &media_device from a PCI device. | |
486 | * | |
487 | * @mdev: pointer to struct &media_device | |
488 | * @udev: pointer to struct usb_device | |
489 | * @name: media device name. If %NULL, the routine will use the usb | |
490 | * product name, if available. | |
491 | * | |
492 | * This macro calls media_device_usb_init() passing the | |
493 | * media_device_usb_init() **driver_name** parameter filled with | |
494 | * %KBUILD_MODNAME. | |
495 | */ | |
6cf5dad1 MCC |
496 | #define media_device_usb_init(mdev, udev, name) \ |
497 | __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME) | |
41b44e35 | 498 | |
176fb0d1 | 499 | #endif |