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 const 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         void (*remove)(struct platform_device *);
 239         void (*shutdown)(struct platform_device *);
 240         int (*suspend)(struct platform_device *, pm_message_t state);
 241         int (*resume)(struct platform_device *);
 242         struct device_driver driver;
 243         const struct platform_device_id *id_table;
 244         bool prevent_deferred_probe;
 245         /*
 246          * For most device drivers, no need to care about this flag as long as
 247          * all DMAs are handled through the kernel DMA API. For some special
 248          * ones, for example VFIO drivers, they know how to manage the DMA
 249          * themselves and set this flag so that the IOMMU layer will allow them
 250          * to setup and manage their own I/O address space.
 251          */
 252         bool driver_managed_dma;
 253 };
 254
 255 #define to_platform_driver(drv) (container_of((drv), struct platform_driver, \
 256                                  driver))
 257
 258 /*
 259  * use a macro to avoid include chaining to get THIS_MODULE
 260  */
 261 #define platform_driver_register(drv) \
 262         __platform_driver_register(drv, THIS_MODULE)
 263 extern int __platform_driver_register(struct platform_driver *,
 264                                         struct module *);
 265 extern void platform_driver_unregister(struct platform_driver *);
 266
 267 /* non-hotpluggable platform devices may use this so that probe() and
 268  * its support may live in __init sections, conserving runtime memory.
 269  */
 270 #define platform_driver_probe(drv, probe) \
 271         __platform_driver_probe(drv, probe, THIS_MODULE)
 272 extern int __platform_driver_probe(struct platform_driver *driver,
 273                 int (*probe)(struct platform_device *), struct module *module);
 274
 275 static inline void *platform_get_drvdata(const struct platform_device *pdev)
 276 {
 277         return dev_get_drvdata(&pdev->dev);
 278 }
 279
 280 static inline void platform_set_drvdata(struct platform_device *pdev,
 281                                         void *data)
 282 {
 283         dev_set_drvdata(&pdev->dev, data);
 284 }
 285
 286 /* module_platform_driver() - Helper macro for drivers that don't do
 287  * anything special in module init/exit.  This eliminates a lot of
 288  * boilerplate.  Each module may only use this macro once, and
 289  * calling it replaces module_init() and module_exit()
 290  */
 291 #define module_platform_driver(__platform_driver) \
 292         module_driver(__platform_driver, platform_driver_register, \
 293                         platform_driver_unregister)
 294
 295 /* builtin_platform_driver() - Helper macro for builtin drivers that
 296  * don't do anything special in driver init.  This eliminates some
 297  * boilerplate.  Each driver may only use this macro once, and
 298  * calling it replaces device_initcall().  Note this is meant to be
 299  * a parallel of module_platform_driver() above, but w/o _exit stuff.
 300  */
 301 #define builtin_platform_driver(__platform_driver) \
 302         builtin_driver(__platform_driver, platform_driver_register)
 303
 304 /* module_platform_driver_probe() - Helper macro for drivers that don't do
 305  * anything special in module init/exit.  This eliminates a lot of
 306  * boilerplate.  Each module may only use this macro once, and
 307  * calling it replaces module_init() and module_exit()
 308  */
 309 #define module_platform_driver_probe(__platform_driver, __platform_probe) \
 310 static int __init __platform_driver##_init(void) \
 311 { \
 312         return platform_driver_probe(&(__platform_driver), \
 313                                      __platform_probe);    \
 314 } \
 315 module_init(__platform_driver##_init); \
 316 static void __exit __platform_driver##_exit(void) \
 317 { \
 318         platform_driver_unregister(&(__platform_driver)); \
 319 } \
 320 module_exit(__platform_driver##_exit);
 321
 322 /* builtin_platform_driver_probe() - Helper macro for drivers that don't do
 323  * anything special in device init.  This eliminates some boilerplate.  Each
 324  * driver may only use this macro once, and using it replaces device_initcall.
 325  * This is meant to be a parallel of module_platform_driver_probe above, but
 326  * without the __exit parts.
 327  */
 328 #define builtin_platform_driver_probe(__platform_driver, __platform_probe) \
 329 static int __init __platform_driver##_init(void) \
 330 { \
 331         return platform_driver_probe(&(__platform_driver), \
 332                                      __platform_probe);    \
 333 } \
 334 device_initcall(__platform_driver##_init); \
 335
 336 #define platform_create_bundle(driver, probe, res, n_res, data, size) \
 337         __platform_create_bundle(driver, probe, res, n_res, data, size, THIS_MODULE)
 338 extern struct platform_device *__platform_create_bundle(
 339         struct platform_driver *driver, int (*probe)(struct platform_device *),
 340         struct resource *res, unsigned int n_res,
 341         const void *data, size_t size, struct module *module);
 342
 343 int __platform_register_drivers(struct platform_driver * const *drivers,
 344                                 unsigned int count, struct module *owner);
 345 void platform_unregister_drivers(struct platform_driver * const *drivers,
 346                                  unsigned int count);
 347
 348 #define platform_register_drivers(drivers, count) \
 349         __platform_register_drivers(drivers, count, THIS_MODULE)
 350
 351 #ifdef CONFIG_SUSPEND
 352 extern int platform_pm_suspend(struct device *dev);
 353 extern int platform_pm_resume(struct device *dev);
 354 #else
 355 #define platform_pm_suspend             NULL
 356 #define platform_pm_resume              NULL
 357 #endif
 358
 359 #ifdef CONFIG_HIBERNATE_CALLBACKS
 360 extern int platform_pm_freeze(struct device *dev);
 361 extern int platform_pm_thaw(struct device *dev);
 362 extern int platform_pm_poweroff(struct device *dev);
 363 extern int platform_pm_restore(struct device *dev);
 364 #else
 365 #define platform_pm_freeze              NULL
 366 #define platform_pm_thaw                NULL
 367 #define platform_pm_poweroff            NULL
 368 #define platform_pm_restore             NULL
 369 #endif
 370
 371 #ifdef CONFIG_PM_SLEEP
 372 #define USE_PLATFORM_PM_SLEEP_OPS \
 373         .suspend = platform_pm_suspend, \
 374         .resume = platform_pm_resume, \
 375         .freeze = platform_pm_freeze, \
 376         .thaw = platform_pm_thaw, \
 377         .poweroff = platform_pm_poweroff, \
 378         .restore = platform_pm_restore,
 379 #else
 380 #define USE_PLATFORM_PM_SLEEP_OPS
 381 #endif
 382
 383 #ifndef CONFIG_SUPERH
 384 /*
 385  * REVISIT: This stub is needed for all non-SuperH users of early platform
 386  * drivers. It should go away once we introduce the new platform_device-based
 387  * early driver framework.
 388  */
 389 static inline int is_sh_early_platform_device(struct platform_device *pdev)
 390 {
 391         return 0;
 392 }
 393 #endif /* CONFIG_SUPERH */
 394
 395 /* For now only SuperH uses it */
 396 void early_platform_cleanup(void);
 397
 398 #endif /* _PLATFORM_DEVICE_H_ */