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