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