include/linux/platform_device.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * platform_device.h - generic, centralized driver model
   4  *
   5  * Copyright (c) 2001-2003 Patrick Mochel <mochel@osdl.org>
   6  *
   7  * See Documentation/driver-api/driver-model/ for more information.
   8  */
   9
  10 #ifndef _PLATFORM_DEVICE_H_
  11 #define _PLATFORM_DEVICE_H_
  12
  13 #include <linux/device.h>
  14
  15 #define PLATFORM_DEVID_NONE     (-1)
  16 #define PLATFORM_DEVID_AUTO     (-2)
  17
  18 struct irq_affinity;
  19 struct mfd_cell;
  20 struct property_entry;
  21 struct platform_device_id;
  22
  23 struct platform_device {
  24         const char      *name;
  25         int             id;
  26         bool            id_auto;
  27         struct device   dev;
  28         u64             platform_dma_mask;
  29         struct device_dma_parameters dma_parms;
  30         u32             num_resources;
  31         struct resource *resource;
  32
  33         const struct platform_device_id *id_entry;
  34         /*
  35          * Driver name to force a match.  Do not set directly, because core
  36          * frees it.  Use driver_set_override() to set or clear it.
  37          */
  38         const char *driver_override;
  39
  40         /* MFD cell pointer */
  41         struct mfd_cell *mfd_cell;
  42
  43         /* arch specific additions */
  44         struct pdev_archdata    archdata;
  45 };
  46
  47 #define platform_get_device_id(pdev)    ((pdev)->id_entry)
  48
  49 #define dev_is_platform(dev) ((dev)->bus == &platform_bus_type)
  50 #define to_platform_device(x) container_of((x), struct platform_device, dev)
  51
  52 extern int platform_device_register(struct platform_device *);
  53 extern void platform_device_unregister(struct platform_device *);
  54
  55 extern struct bus_type platform_bus_type;
  56 extern struct device platform_bus;
  57
  58 extern struct resource *platform_get_resource(struct platform_device *,
  59                                               unsigned int, unsigned int);
  60 extern struct resource *platform_get_mem_or_io(struct platform_device *,
  61                                                unsigned int);
  62
  63 extern struct device *
  64 platform_find_device_by_driver(struct device *start,
  65                                const struct device_driver *drv);
  66
  67 #ifdef CONFIG_HAS_IOMEM
  68 extern void __iomem *
  69 devm_platform_get_and_ioremap_resource(struct platform_device *pdev,
  70                                 unsigned int index, struct resource **res);
  71 extern void __iomem *
  72 devm_platform_ioremap_resource(struct platform_device *pdev,
  73                                unsigned int index);
  74 extern void __iomem *
  75 devm_platform_ioremap_resource_byname(struct platform_device *pdev,
  76                                       const char *name);
  77 #else
  78
  79 static inline void __iomem *
  80 devm_platform_get_and_ioremap_resource(struct platform_device *pdev,
  81                                 unsigned int index, struct resource **res)
  82 {
  83         return ERR_PTR(-EINVAL);
  84 }
  85
  86
  87 static inline void __iomem *
  88 devm_platform_ioremap_resource(struct platform_device *pdev,
  89                                unsigned int index)
  90 {
  91         return ERR_PTR(-EINVAL);
  92 }
  93
  94 static inline void __iomem *
  95 devm_platform_ioremap_resource_byname(struct platform_device *pdev,
  96                                       const char *name)
  97 {
  98         return ERR_PTR(-EINVAL);
  99 }
 100
 101 #endif
 102
 103 extern int platform_get_irq(struct platform_device *, unsigned int);
 104 extern int platform_get_irq_optional(struct platform_device *, unsigned int);
 105 extern int platform_irq_count(struct platform_device *);
 106 extern int devm_platform_get_irqs_affinity(struct platform_device *dev,
 107                                            struct irq_affinity *affd,
 108                                            unsigned int minvec,
 109                                            unsigned int maxvec,
 110                                            int **irqs);
 111 extern struct resource *platform_get_resource_byname(struct platform_device *,
 112                                                      unsigned int,
 113                                                      const char *);
 114 extern int platform_get_irq_byname(struct platform_device *, const char *);
 115 extern int platform_get_irq_byname_optional(struct platform_device *dev,
 116                                             const char *name);
 117 extern int platform_add_devices(struct platform_device **, int);
 118
 119 struct platform_device_info {
 120                 struct device *parent;
 121                 struct fwnode_handle *fwnode;
 122                 bool of_node_reused;
 123
 124                 const char *name;
 125                 int id;
 126
 127                 const struct resource *res;
 128                 unsigned int num_res;
 129
 130                 const void *data;
 131                 size_t size_data;
 132                 u64 dma_mask;
 133
 134                 const struct property_entry *properties;
 135 };
 136 extern struct platform_device *platform_device_register_full(
 137                 const struct platform_device_info *pdevinfo);
 138
 139 /**
 140  * platform_device_register_resndata - add a platform-level device with
 141  * resources and platform-specific data
 142  *
 143  * @parent: parent device for the device we're adding
 144  * @name: base name of the device we're adding
 145  * @id: instance id
 146  * @res: set of resources that needs to be allocated for the device
 147  * @num: number of resources
 148  * @data: platform specific data for this platform device
 149  * @size: size of platform specific data
 150  *
 151  * Returns &struct platform_device pointer on success, or ERR_PTR() on error.
 152  */
 153 static inline struct platform_device *platform_device_register_resndata(
 154                 struct device *parent, const char *name, int id,
 155                 const struct resource *res, unsigned int num,
 156                 const void *data, size_t size) {
 157
 158         struct platform_device_info pdevinfo = {
 159                 .parent = parent,
 160                 .name = name,
 161                 .id = id,
 162                 .res = res,
 163                 .num_res = num,
 164                 .data = data,
 165                 .size_data = size,
 166                 .dma_mask = 0,
 167         };
 168
 169         return platform_device_register_full(&pdevinfo);
 170 }
 171
 172 /**
 173  * platform_device_register_simple - add a platform-level device and its resources
 174  * @name: base name of the device we're adding
 175  * @id: instance id
 176  * @res: set of resources that needs to be allocated for the device
 177  * @num: number of resources
 178  *
 179  * This function creates a simple platform device that requires minimal
 180  * resource and memory management. Canned release function freeing memory
 181  * allocated for the device allows drivers using such devices to be
 182  * unloaded without waiting for the last reference to the device to be
 183  * dropped.
 184  *
 185  * This interface is primarily intended for use with legacy drivers which
 186  * probe hardware directly.  Because such drivers create sysfs device nodes
 187  * themselves, rather than letting system infrastructure handle such device
 188  * enumeration tasks, they don't fully conform to the Linux driver model.
 189  * In particular, when such drivers are built as modules, they can't be
 190  * "hotplugged".
 191  *
 192  * Returns &struct platform_device pointer on success, or ERR_PTR() on error.
 193  */
 194 static inline struct platform_device *platform_device_register_simple(
 195                 const char *name, int id,
 196                 const struct resource *res, unsigned int num)
 197 {
 198         return platform_device_register_resndata(NULL, name, id,
 199                         res, num, NULL, 0);
 200 }
 201
 202 /**
 203  * platform_device_register_data - add a platform-level device with platform-specific data
 204  * @parent: parent device for the device we're adding
 205  * @name: base name of the device we're adding
 206  * @id: instance id
 207  * @data: platform specific data for this platform device
 208  * @size: size of platform specific data
 209  *
 210  * This function creates a simple platform device that requires minimal
 211  * resource and memory management. Canned release function freeing memory
 212  * allocated for the device allows drivers using such devices to be
 213  * unloaded without waiting for the last reference to the device to be
 214  * dropped.
 215  *
 216  * Returns &struct platform_device pointer on success, or ERR_PTR() on error.
 217  */
 218 static inline struct platform_device *platform_device_register_data(
 219                 struct device *parent, const char *name, int id,
 220                 const void *data, size_t size)
 221 {
 222         return platform_device_register_resndata(parent, name, id,
 223                         NULL, 0, data, size);
 224 }
 225
 226 extern struct platform_device *platform_device_alloc(const char *name, int id);
 227 extern int platform_device_add_resources(struct platform_device *pdev,
 228                                          const struct resource *res,
 229                                          unsigned int num);
 230 extern int platform_device_add_data(struct platform_device *pdev,
 231                                     const void *data, size_t size);
 232 extern int platform_device_add(struct platform_device *pdev);
 233 extern void platform_device_del(struct platform_device *pdev);
 234 extern void platform_device_put(struct platform_device *pdev);
 235
 236 struct platform_driver {
 237         int (*probe)(struct platform_device *);
 238
 239         /*
 240          * Traditionally the remove callback returned an int which however is
 241          * ignored by the driver core. This led to wrong expectations by driver
 242          * authors who thought returning an error code was a valid error
 243          * handling strategy. To convert to a callback returning void, new
 244          * drivers should implement .remove_new() until the conversion it done
 245          * that eventually makes .remove() return void.
 246          */
 247         int (*remove)(struct platform_device *);
 248         void (*remove_new)(struct platform_device *);
 249
 250         void (*shutdown)(struct platform_device *);
 251         int (*suspend)(struct platform_device *, pm_message_t state);
 252         int (*resume)(struct platform_device *);
 253         struct device_driver driver;
 254         const struct platform_device_id *id_table;
 255         bool prevent_deferred_probe;
 256         /*
 257          * For most device drivers, no need to care about this flag as long as
 258          * all DMAs are handled through the kernel DMA API. For some special
 259          * ones, for example VFIO drivers, they know how to manage the DMA
 260          * themselves and set this flag so that the IOMMU layer will allow them
 261          * to setup and manage their own I/O address space.
 262          */
 263         bool driver_managed_dma;
 264 };
 265
 266 #define to_platform_driver(drv) (container_of((drv), struct platform_driver, \
 267                                  driver))
 268
 269 /*
 270  * use a macro to avoid include chaining to get THIS_MODULE
 271  */
 272 #define platform_driver_register(drv) \
 273         __platform_driver_register(drv, THIS_MODULE)
 274 extern int __platform_driver_register(struct platform_driver *,
 275                                         struct module *);
 276 extern void platform_driver_unregister(struct platform_driver *);
 277
 278 /* non-hotpluggable platform devices may use this so that probe() and
 279  * its support may live in __init sections, conserving runtime memory.
 280  */
 281 #define platform_driver_probe(drv, probe) \
 282         __platform_driver_probe(drv, probe, THIS_MODULE)
 283 extern int __platform_driver_probe(struct platform_driver *driver,
 284                 int (*probe)(struct platform_device *), struct module *module);
 285
 286 static inline void *platform_get_drvdata(const struct platform_device *pdev)
 287 {
 288         return dev_get_drvdata(&pdev->dev);
 289 }
 290
 291 static inline void platform_set_drvdata(struct platform_device *pdev,
 292                                         void *data)
 293 {
 294         dev_set_drvdata(&pdev->dev, data);
 295 }
 296
 297 /* module_platform_driver() - Helper macro for drivers that don't do
 298  * anything special in module init/exit.  This eliminates a lot of
 299  * boilerplate.  Each module may only use this macro once, and
 300  * calling it replaces module_init() and module_exit()
 301  */
 302 #define module_platform_driver(__platform_driver) \
 303         module_driver(__platform_driver, platform_driver_register, \
 304                         platform_driver_unregister)
 305
 306 /* builtin_platform_driver() - Helper macro for builtin drivers that
 307  * don't do anything special in driver init.  This eliminates some
 308  * boilerplate.  Each driver may only use this macro once, and
 309  * calling it replaces device_initcall().  Note this is meant to be
 310  * a parallel of module_platform_driver() above, but w/o _exit stuff.
 311  */
 312 #define builtin_platform_driver(__platform_driver) \
 313         builtin_driver(__platform_driver, platform_driver_register)
 314
 315 /* module_platform_driver_probe() - Helper macro for drivers that don't do
 316  * anything special in module init/exit.  This eliminates a lot of
 317  * boilerplate.  Each module may only use this macro once, and
 318  * calling it replaces module_init() and module_exit()
 319  */
 320 #define module_platform_driver_probe(__platform_driver, __platform_probe) \
 321 static int __init __platform_driver##_init(void) \
 322 { \
 323         return platform_driver_probe(&(__platform_driver), \
 324                                      __platform_probe);    \
 325 } \
 326 module_init(__platform_driver##_init); \
 327 static void __exit __platform_driver##_exit(void) \
 328 { \
 329         platform_driver_unregister(&(__platform_driver)); \
 330 } \
 331 module_exit(__platform_driver##_exit);
 332
 333 /* builtin_platform_driver_probe() - Helper macro for drivers that don't do
 334  * anything special in device init.  This eliminates some boilerplate.  Each
 335  * driver may only use this macro once, and using it replaces device_initcall.
 336  * This is meant to be a parallel of module_platform_driver_probe above, but
 337  * without the __exit parts.
 338  */
 339 #define builtin_platform_driver_probe(__platform_driver, __platform_probe) \
 340 static int __init __platform_driver##_init(void) \
 341 { \
 342         return platform_driver_probe(&(__platform_driver), \
 343                                      __platform_probe);    \
 344 } \
 345 device_initcall(__platform_driver##_init); \
 346
 347 #define platform_create_bundle(driver, probe, res, n_res, data, size) \
 348         __platform_create_bundle(driver, probe, res, n_res, data, size, THIS_MODULE)
 349 extern struct platform_device *__platform_create_bundle(
 350         struct platform_driver *driver, int (*probe)(struct platform_device *),
 351         struct resource *res, unsigned int n_res,
 352         const void *data, size_t size, struct module *module);
 353
 354 int __platform_register_drivers(struct platform_driver * const *drivers,
 355                                 unsigned int count, struct module *owner);
 356 void platform_unregister_drivers(struct platform_driver * const *drivers,
 357                                  unsigned int count);
 358
 359 #define platform_register_drivers(drivers, count) \
 360         __platform_register_drivers(drivers, count, THIS_MODULE)
 361
 362 #ifdef CONFIG_SUSPEND
 363 extern int platform_pm_suspend(struct device *dev);
 364 extern int platform_pm_resume(struct device *dev);
 365 #else
 366 #define platform_pm_suspend             NULL
 367 #define platform_pm_resume              NULL
 368 #endif
 369
 370 #ifdef CONFIG_HIBERNATE_CALLBACKS
 371 extern int platform_pm_freeze(struct device *dev);
 372 extern int platform_pm_thaw(struct device *dev);
 373 extern int platform_pm_poweroff(struct device *dev);
 374 extern int platform_pm_restore(struct device *dev);
 375 #else
 376 #define platform_pm_freeze              NULL
 377 #define platform_pm_thaw                NULL
 378 #define platform_pm_poweroff            NULL
 379 #define platform_pm_restore             NULL
 380 #endif
 381
 382 #ifdef CONFIG_PM_SLEEP
 383 #define USE_PLATFORM_PM_SLEEP_OPS \
 384         .suspend = platform_pm_suspend, \
 385         .resume = platform_pm_resume, \
 386         .freeze = platform_pm_freeze, \
 387         .thaw = platform_pm_thaw, \
 388         .poweroff = platform_pm_poweroff, \
 389         .restore = platform_pm_restore,
 390 #else
 391 #define USE_PLATFORM_PM_SLEEP_OPS
 392 #endif
 393
 394 #ifndef CONFIG_SUPERH
 395 /*
 396  * REVISIT: This stub is needed for all non-SuperH users of early platform
 397  * drivers. It should go away once we introduce the new platform_device-based
 398  * early driver framework.
 399  */
 400 static inline int is_sh_early_platform_device(struct platform_device *pdev)
 401 {
 402         return 0;
 403 }
 404 #endif /* CONFIG_SUPERH */
 405
 406 /* For now only SuperH uses it */
 407 void early_platform_cleanup(void);
 408
 409 #endif /* _PLATFORM_DEVICE_H_ */