include/media/media-device.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Media device
0004  *
0005  * Copyright (C) 2010 Nokia Corporation
0006  *
0007  * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
0008  *       Sakari Ailus <sakari.ailus@iki.fi>
0009  */
0010
0011 #ifndef _MEDIA_DEVICE_H
0012 #define _MEDIA_DEVICE_H
0013
0014 #include <linux/list.h>
0015 #include <linux/mutex.h>
0016 #include <linux/pci.h>
0017 #include <linux/platform_device.h>
0018
0019 #include <media/media-devnode.h>
0020 #include <media/media-entity.h>
0021
0022 struct ida;
0023 struct media_device;
0024
0025 /**
0026  * struct media_entity_notify - Media Entity Notify
0027  *
0028  * @list: List head
0029  * @notify_data: Input data to invoke the callback
0030  * @notify: Callback function pointer
0031  *
0032  * Drivers may register a callback to take action when new entities get
0033  * registered with the media device. This handler is intended for creating
0034  * links between existing entities and should not create entities and register
0035  * them.
0036  */
0037 struct media_entity_notify {
0038     struct list_head list;
0039     void *notify_data;
0040     void (*notify)(struct media_entity *entity, void *notify_data);
0041 };
0042
0043 /**
0044  * struct media_device_ops - Media device operations
0045  * @link_notify: Link state change notification callback. This callback is
0046  *       called with the graph_mutex held.
0047  * @req_alloc: Allocate a request. Set this if you need to allocate a struct
0048  *         larger then struct media_request. @req_alloc and @req_free must
0049  *         either both be set or both be NULL.
0050  * @req_free: Free a request. Set this if @req_alloc was set as well, leave
0051  *        to NULL otherwise.
0052  * @req_validate: Validate a request, but do not queue yet. The req_queue_mutex
0053  *            lock is held when this op is called.
0054  * @req_queue: Queue a validated request, cannot fail. If something goes
0055  *         wrong when queueing this request then it should be marked
0056  *         as such internally in the driver and any related buffers
0057  *         must eventually return to vb2 with state VB2_BUF_STATE_ERROR.
0058  *         The req_queue_mutex lock is held when this op is called.
0059  *         It is important that vb2 buffer objects are queued last after
0060  *         all other object types are queued: queueing a buffer kickstarts
0061  *         the request processing, so all other objects related to the
0062  *         request (and thus the buffer) must be available to the driver.
0063  *         And once a buffer is queued, then the driver can complete
0064  *         or delete objects from the request before req_queue exits.
0065  */
0066 struct media_device_ops {
0067     int (*link_notify)(struct media_link *link, u32 flags,
0068                unsigned int notification);
0069     struct media_request *(*req_alloc)(struct media_device *mdev);
0070     void (*req_free)(struct media_request *req);
0071     int (*req_validate)(struct media_request *req);
0072     void (*req_queue)(struct media_request *req);
0073 };
0074
0075 /**
0076  * struct media_device - Media device
0077  * @dev:    Parent device
0078  * @devnode:    Media device node
0079  * @driver_name: Optional device driver name. If not set, calls to
0080  *      %MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``.
0081  *      This is needed for USB drivers for example, as otherwise
0082  *      they'll all appear as if the driver name was "usb".
0083  * @model:  Device model name
0084  * @serial: Device serial number (optional)
0085  * @bus_info:   Unique and stable device location identifier
0086  * @hw_revision: Hardware device revision
0087  * @topology_version: Monotonic counter for storing the version of the graph
0088  *      topology. Should be incremented each time the topology changes.
0089  * @id:     Unique ID used on the last registered graph object
0090  * @entity_internal_idx: Unique internal entity ID used by the graph traversal
0091  *      algorithms
0092  * @entity_internal_idx_max: Allocated internal entity indices
0093  * @entities:   List of registered entities
0094  * @interfaces: List of registered interfaces
0095  * @pads:   List of registered pads
0096  * @links:  List of registered links
0097  * @entity_notify: List of registered entity_notify callbacks
0098  * @graph_mutex: Protects access to struct media_device data
0099  * @pm_count_walk: Graph walk for power state walk. Access serialised using
0100  *         graph_mutex.
0101  *
0102  * @source_priv: Driver Private data for enable/disable source handlers
0103  * @enable_source: Enable Source Handler function pointer
0104  * @disable_source: Disable Source Handler function pointer
0105  *
0106  * @ops:    Operation handler callbacks
0107  * @req_queue_mutex: Serialise the MEDIA_REQUEST_IOC_QUEUE ioctl w.r.t.
0108  *           other operations that stop or start streaming.
0109  * @request_id: Used to generate unique request IDs
0110  *
0111  * This structure represents an abstract high-level media device. It allows easy
0112  * access to entities and provides basic media device-level support. The
0113  * structure can be allocated directly or embedded in a larger structure.
0114  *
0115  * The parent @dev is a physical device. It must be set before registering the
0116  * media device.
0117  *
0118  * @model is a descriptive model name exported through sysfs. It doesn't have to
0119  * be unique.
0120  *
0121  * @enable_source is a handler to find source entity for the
0122  * sink entity  and activate the link between them if source
0123  * entity is free. Drivers should call this handler before
0124  * accessing the source.
0125  *
0126  * @disable_source is a handler to find source entity for the
0127  * sink entity  and deactivate the link between them. Drivers
0128  * should call this handler to release the source.
0129  *
0130  * Use-case: find tuner entity connected to the decoder
0131  * entity and check if it is available, and activate the
0132  * link between them from @enable_source and deactivate
0133  * from @disable_source.
0134  *
0135  * .. note::
0136  *
0137  *    Bridge driver is expected to implement and set the
0138  *    handler when &media_device is registered or when
0139  *    bridge driver finds the media_device during probe.
0140  *    Bridge driver sets source_priv with information
0141  *    necessary to run @enable_source and @disable_source handlers.
0142  *    Callers should hold graph_mutex to access and call @enable_source
0143  *    and @disable_source handlers.
0144  */
0145 struct media_device {
0146     /* dev->driver_data points to this struct. */
0147     struct device *dev;
0148     struct media_devnode *devnode;
0149
0150     char model[32];
0151     char driver_name[32];
0152     char serial[40];
0153     char bus_info[32];
0154     u32 hw_revision;
0155
0156     u64 topology_version;
0157
0158     u32 id;
0159     struct ida entity_internal_idx;
0160     int entity_internal_idx_max;
0161
0162     struct list_head entities;
0163     struct list_head interfaces;
0164     struct list_head pads;
0165     struct list_head links;
0166
0167     /* notify callback list invoked when a new entity is registered */
0168     struct list_head entity_notify;
0169
0170     /* Serializes graph operations. */
0171     struct mutex graph_mutex;
0172     struct media_graph pm_count_walk;
0173
0174     void *source_priv;
0175     int (*enable_source)(struct media_entity *entity,
0176                  struct media_pipeline *pipe);
0177     void (*disable_source)(struct media_entity *entity);
0178
0179     const struct media_device_ops *ops;
0180
0181     struct mutex req_queue_mutex;
0182     atomic_t request_id;
0183 };
0184
0185 /* We don't need to include usb.h here */
0186 struct usb_device;
0187
0188 #ifdef CONFIG_MEDIA_CONTROLLER
0189
0190 /* Supported link_notify @notification values. */
0191 #define MEDIA_DEV_NOTIFY_PRE_LINK_CH    0
0192 #define MEDIA_DEV_NOTIFY_POST_LINK_CH   1
0193
0194 /**
0195  * media_entity_enum_init - Initialise an entity enumeration
0196  *
0197  * @ent_enum: Entity enumeration to be initialised
0198  * @mdev: The related media device
0199  *
0200  * Return: zero on success or a negative error code.
0201  */
0202 static inline __must_check int media_entity_enum_init(
0203     struct media_entity_enum *ent_enum, struct media_device *mdev)
0204 {
0205     return __media_entity_enum_init(ent_enum,
0206                     mdev->entity_internal_idx_max + 1);
0207 }
0208
0209 /**
0210  * media_device_init() - Initializes a media device element
0211  *
0212  * @mdev:   pointer to struct &media_device
0213  *
0214  * This function initializes the media device prior to its registration.
0215  * The media device initialization and registration is split in two functions
0216  * to avoid race conditions and make the media device available to user-space
0217  * before the media graph has been completed.
0218  *
0219  * So drivers need to first initialize the media device, register any entity
0220  * within the media device, create pad to pad links and then finally register
0221  * the media device by calling media_device_register() as a final step.
0222  *
0223  * The caller is responsible for initializing the media device before
0224  * registration. The following fields must be set:
0225  *
0226  * - dev must point to the parent device
0227  * - model must be filled with the device model name
0228  *
0229  * The bus_info field is set by media_device_init() for PCI and platform devices
0230  * if the field begins with '\0'.
0231  */
0232 void media_device_init(struct media_device *mdev);
0233
0234 /**
0235  * media_device_cleanup() - Cleanups a media device element
0236  *
0237  * @mdev:   pointer to struct &media_device
0238  *
0239  * This function that will destroy the graph_mutex that is
0240  * initialized in media_device_init().
0241  */
0242 void media_device_cleanup(struct media_device *mdev);
0243
0244 /**
0245  * __media_device_register() - Registers a media device element
0246  *
0247  * @mdev:   pointer to struct &media_device
0248  * @owner:  should be filled with %THIS_MODULE
0249  *
0250  * Users, should, instead, call the media_device_register() macro.
0251  *
0252  * The caller is responsible for initializing the &media_device structure
0253  * before registration. The following fields of &media_device must be set:
0254  *
0255  *  - &media_device.model must be filled with the device model name as a
0256  *    NUL-terminated UTF-8 string. The device/model revision must not be
0257  *    stored in this field.
0258  *
0259  * The following fields are optional:
0260  *
0261  *  - &media_device.serial is a unique serial number stored as a
0262  *    NUL-terminated ASCII string. The field is big enough to store a GUID
0263  *    in text form. If the hardware doesn't provide a unique serial number
0264  *    this field must be left empty.
0265  *
0266  *  - &media_device.bus_info represents the location of the device in the
0267  *    system as a NUL-terminated ASCII string. For PCI/PCIe devices
0268  *    &media_device.bus_info must be set to "PCI:" (or "PCIe:") followed by
0269  *    the value of pci_name(). For USB devices,the usb_make_path() function
0270  *    must be used. This field is used by applications to distinguish between
0271  *    otherwise identical devices that don't provide a serial number.
0272  *
0273  *  - &media_device.hw_revision is the hardware device revision in a
0274  *    driver-specific format. When possible the revision should be formatted
0275  *    with the KERNEL_VERSION() macro.
0276  *
0277  * .. note::
0278  *
0279  *    #) 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.
0280  *
0281  *    #) Unregistering a media device that hasn't been registered is **NOT** safe.
0282  *
0283  * Return: returns zero on success or a negative error code.
0284  */
0285 int __must_check __media_device_register(struct media_device *mdev,
0286                      struct module *owner);
0287
0288
0289 /**
0290  * media_device_register() - Registers a media device element
0291  *
0292  * @mdev:   pointer to struct &media_device
0293  *
0294  * This macro calls __media_device_register() passing %THIS_MODULE as
0295  * the __media_device_register() second argument (**owner**).
0296  */
0297 #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE)
0298
0299 /**
0300  * media_device_unregister() - Unregisters a media device element
0301  *
0302  * @mdev:   pointer to struct &media_device
0303  *
0304  * It is safe to call this function on an unregistered (but initialised)
0305  * media device.
0306  */
0307 void media_device_unregister(struct media_device *mdev);
0308
0309 /**
0310  * media_device_register_entity() - registers a media entity inside a
0311  *  previously registered media device.
0312  *
0313  * @mdev:   pointer to struct &media_device
0314  * @entity: pointer to struct &media_entity to be registered
0315  *
0316  * Entities are identified by a unique positive integer ID. The media
0317  * controller framework will such ID automatically. IDs are not guaranteed
0318  * to be contiguous, and the ID number can change on newer Kernel versions.
0319  * So, neither the driver nor userspace should hardcode ID numbers to refer
0320  * to the entities, but, instead, use the framework to find the ID, when
0321  * needed.
0322  *
0323  * The media_entity name, type and flags fields should be initialized before
0324  * calling media_device_register_entity(). Entities embedded in higher-level
0325  * standard structures can have some of those fields set by the higher-level
0326  * framework.
0327  *
0328  * If the device has pads, media_entity_pads_init() should be called before
0329  * this function. Otherwise, the &media_entity.pad and &media_entity.num_pads
0330  * should be zeroed before calling this function.
0331  *
0332  * Entities have flags that describe the entity capabilities and state:
0333  *
0334  * %MEDIA_ENT_FL_DEFAULT
0335  *    indicates the default entity for a given type.
0336  *    This can be used to report the default audio and video devices or the
0337  *    default camera sensor.
0338  *
0339  * .. note::
0340  *
0341  *    Drivers should set the entity function before calling this function.
0342  *    Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
0343  *    %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
0344  */
0345 int __must_check media_device_register_entity(struct media_device *mdev,
0346                           struct media_entity *entity);
0347
0348 /**
0349  * media_device_unregister_entity() - unregisters a media entity.
0350  *
0351  * @entity: pointer to struct &media_entity to be unregistered
0352  *
0353  * All links associated with the entity and all PADs are automatically
0354  * unregistered from the media_device when this function is called.
0355  *
0356  * Unregistering an entity will not change the IDs of the other entities and
0357  * the previoully used ID will never be reused for a newly registered entities.
0358  *
0359  * When a media device is unregistered, all its entities are unregistered
0360  * automatically. No manual entities unregistration is then required.
0361  *
0362  * .. note::
0363  *
0364  *    The media_entity instance itself must be freed explicitly by
0365  *    the driver if required.
0366  */
0367 void media_device_unregister_entity(struct media_entity *entity);
0368
0369 /**
0370  * media_device_register_entity_notify() - Registers a media entity_notify
0371  *                     callback
0372  *
0373  * @mdev:      The media device
0374  * @nptr:      The media_entity_notify
0375  *
0376  * .. note::
0377  *
0378  *    When a new entity is registered, all the registered
0379  *    media_entity_notify callbacks are invoked.
0380  */
0381
0382 int __must_check media_device_register_entity_notify(struct media_device *mdev,
0383                     struct media_entity_notify *nptr);
0384
0385 /**
0386  * media_device_unregister_entity_notify() - Unregister a media entity notify
0387  *                       callback
0388  *
0389  * @mdev:      The media device
0390  * @nptr:      The media_entity_notify
0391  *
0392  */
0393 void media_device_unregister_entity_notify(struct media_device *mdev,
0394                     struct media_entity_notify *nptr);
0395
0396 /* Iterate over all entities. */
0397 #define media_device_for_each_entity(entity, mdev)          \
0398     list_for_each_entry(entity, &(mdev)->entities, graph_obj.list)
0399
0400 /* Iterate over all interfaces. */
0401 #define media_device_for_each_intf(intf, mdev)          \
0402     list_for_each_entry(intf, &(mdev)->interfaces, graph_obj.list)
0403
0404 /* Iterate over all pads. */
0405 #define media_device_for_each_pad(pad, mdev)            \
0406     list_for_each_entry(pad, &(mdev)->pads, graph_obj.list)
0407
0408 /* Iterate over all links. */
0409 #define media_device_for_each_link(link, mdev)          \
0410     list_for_each_entry(link, &(mdev)->links, graph_obj.list)
0411
0412 /**
0413  * media_device_pci_init() - create and initialize a
0414  *  struct &media_device from a PCI device.
0415  *
0416  * @mdev:   pointer to struct &media_device
0417  * @pci_dev:    pointer to struct pci_dev
0418  * @name:   media device name. If %NULL, the routine will use the default
0419  *      name for the pci device, given by pci_name() macro.
0420  */
0421 void media_device_pci_init(struct media_device *mdev,
0422                struct pci_dev *pci_dev,
0423                const char *name);
0424 /**
0425  * __media_device_usb_init() - create and initialize a
0426  *  struct &media_device from a PCI device.
0427  *
0428  * @mdev:   pointer to struct &media_device
0429  * @udev:   pointer to struct usb_device
0430  * @board_name: media device name. If %NULL, the routine will use the usb
0431  *      product name, if available.
0432  * @driver_name: name of the driver. if %NULL, the routine will use the name
0433  *      given by ``udev->dev->driver->name``, with is usually the wrong
0434  *      thing to do.
0435  *
0436  * .. note::
0437  *
0438  *    It is better to call media_device_usb_init() instead, as
0439  *    such macro fills driver_name with %KBUILD_MODNAME.
0440  */
0441 void __media_device_usb_init(struct media_device *mdev,
0442                  struct usb_device *udev,
0443                  const char *board_name,
0444                  const char *driver_name);
0445
0446 #else
0447 static inline int media_device_register(struct media_device *mdev)
0448 {
0449     return 0;
0450 }
0451 static inline void media_device_unregister(struct media_device *mdev)
0452 {
0453 }
0454 static inline int media_device_register_entity(struct media_device *mdev,
0455                         struct media_entity *entity)
0456 {
0457     return 0;
0458 }
0459 static inline void media_device_unregister_entity(struct media_entity *entity)
0460 {
0461 }
0462 static inline int media_device_register_entity_notify(
0463                     struct media_device *mdev,
0464                     struct media_entity_notify *nptr)
0465 {
0466     return 0;
0467 }
0468 static inline void media_device_unregister_entity_notify(
0469                     struct media_device *mdev,
0470                     struct media_entity_notify *nptr)
0471 {
0472 }
0473
0474 static inline void media_device_pci_init(struct media_device *mdev,
0475                      struct pci_dev *pci_dev,
0476                      char *name)
0477 {
0478 }
0479
0480 static inline void __media_device_usb_init(struct media_device *mdev,
0481                        struct usb_device *udev,
0482                        char *board_name,
0483                        char *driver_name)
0484 {
0485 }
0486
0487 #endif /* CONFIG_MEDIA_CONTROLLER */
0488
0489 /**
0490  * media_device_usb_init() - create and initialize a
0491  *  struct &media_device from a PCI device.
0492  *
0493  * @mdev:   pointer to struct &media_device
0494  * @udev:   pointer to struct usb_device
0495  * @name:   media device name. If %NULL, the routine will use the usb
0496  *      product name, if available.
0497  *
0498  * This macro calls media_device_usb_init() passing the
0499  * media_device_usb_init() **driver_name** parameter filled with
0500  * %KBUILD_MODNAME.
0501  */
0502 #define media_device_usb_init(mdev, udev, name) \
0503     __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME)
0504
0505 /**
0506  * media_set_bus_info() - Set bus_info field
0507  *
0508  * @bus_info:       Variable where to write the bus info (char array)
0509  * @bus_info_size:  Length of the bus_info
0510  * @dev:        Related struct device
0511  *
0512  * Sets bus information based on &dev. This is currently done for PCI and
0513  * platform devices. dev is required to be non-NULL for this to happen.
0514  *
0515  * This function is not meant to be called from drivers.
0516  */
0517 static inline void
0518 media_set_bus_info(char *bus_info, size_t bus_info_size, struct device *dev)
0519 {
0520     if (!dev)
0521         strscpy(bus_info, "no bus info", bus_info_size);
0522     else if (dev_is_platform(dev))
0523         snprintf(bus_info, bus_info_size, "platform:%s", dev_name(dev));
0524     else if (dev_is_pci(dev))
0525         snprintf(bus_info, bus_info_size, "PCI:%s", dev_name(dev));
0526 }
0527
0528 #endif