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 #include <linux/device-id/platform.h> 15 16 #define PLATFORM_DEVID_NONE (-1) 17 #define PLATFORM_DEVID_AUTO (-2) 18 19 struct irq_affinity; 20 struct mfd_cell; 21 struct property_entry; 22 struct device_node; 23 struct fwnode_handle; 24 25 struct platform_device { 26 const char *name; 27 int id; 28 bool id_auto; 29 struct device dev; 30 u64 platform_dma_mask; 31 struct device_dma_parameters dma_parms; 32 u32 num_resources; 33 struct resource *resource; 34 35 const struct platform_device_id *id_entry; 36 37 /* MFD cell pointer */ 38 struct mfd_cell *mfd_cell; 39 40 /* arch specific additions */ 41 struct pdev_archdata archdata; 42 }; 43 44 #define platform_get_device_id(pdev) ((pdev)->id_entry) 45 46 #define dev_is_platform(dev) ((dev)->bus == &platform_bus_type) 47 #define to_platform_device(x) container_of((x), struct platform_device, dev) 48 49 extern int platform_device_register(struct platform_device *); 50 extern void platform_device_unregister(struct platform_device *); 51 52 extern const struct bus_type platform_bus_type; 53 extern struct device platform_bus; 54 55 extern struct resource *platform_get_resource(struct platform_device *, 56 unsigned int, unsigned int); 57 extern struct resource *platform_get_mem_or_io(struct platform_device *, 58 unsigned int); 59 60 extern struct device * 61 platform_find_device_by_driver(struct device *start, 62 const struct device_driver *drv); 63 64 #ifdef CONFIG_HAS_IOMEM 65 extern void __iomem * 66 devm_platform_get_and_ioremap_resource(struct platform_device *pdev, 67 unsigned int index, struct resource **res); 68 extern void __iomem * 69 devm_platform_ioremap_resource(struct platform_device *pdev, 70 unsigned int index); 71 extern void __iomem * 72 devm_platform_ioremap_resource_byname(struct platform_device *pdev, 73 const char *name); 74 #else 75 76 static inline void __iomem * 77 devm_platform_get_and_ioremap_resource(struct platform_device *pdev, 78 unsigned int index, struct resource **res) 79 { 80 return IOMEM_ERR_PTR(-EINVAL); 81 } 82 83 84 static inline void __iomem * 85 devm_platform_ioremap_resource(struct platform_device *pdev, 86 unsigned int index) 87 { 88 return IOMEM_ERR_PTR(-EINVAL); 89 } 90 91 static inline void __iomem * 92 devm_platform_ioremap_resource_byname(struct platform_device *pdev, 93 const char *name) 94 { 95 return IOMEM_ERR_PTR(-EINVAL); 96 } 97 98 #endif 99 100 extern int platform_get_irq(struct platform_device *, unsigned int); 101 extern int platform_get_irq_optional(struct platform_device *, unsigned int); 102 extern int platform_get_irq_affinity(struct platform_device *, unsigned int, 103 const struct cpumask **); 104 extern int platform_irq_count(struct platform_device *); 105 extern int devm_platform_get_irqs_affinity(struct platform_device *dev, 106 struct irq_affinity *affd, 107 unsigned int minvec, 108 unsigned int maxvec, 109 int **irqs); 110 extern struct resource *platform_get_resource_byname(struct platform_device *, 111 unsigned int, 112 const char *); 113 extern int platform_get_irq_byname(struct platform_device *, const char *); 114 extern int platform_get_irq_byname_optional(struct platform_device *dev, 115 const char *name); 116 extern int platform_add_devices(struct platform_device **, int); 117 118 /** 119 * struct platform_device_info - set of parameters for creating a platform device 120 * @parent: parent device for the new platform device. 121 * @fwnode: firmware node associated with the device. 122 * @of_node_reused: indicates that device tree node associated with the device 123 * is shared with another device, typically its ancestor. Setting this to 124 * %true prevents the device from being matched via the OF match table, 125 * and stops the device core from automatically binding pinctrl 126 * configuration to avoid disrupting the other device. 127 * @name: name of the device. 128 * @id: instance ID of the device. Use %PLATFORM_DEVID_NONE if there is only 129 * one instance of the device, or %PLATFORM_DEVID_AUTO to let the 130 * kernel automatically assign a unique instance ID. 131 * @res: set of resources to attach to the device. 132 * @num_res: number of entries in @res. 133 * @data: device-specific data for this platform device. 134 * @size_data: size of device-specific data. 135 * @dma_mask: DMA mask for the device. 136 * @swnode: a secondary software node to be attached to the device. The node 137 * will be automatically registered and its lifetime tied to the platform 138 * device if it is not registered yet. 139 * @properties: a set of software properties for the device. If provided, 140 * a managed software node will be automatically created and 141 * assigned to the device. The properties array must be terminated 142 * with a sentinel entry. Specifying both @properties and @swnode is not 143 * allowed. 144 * 145 * This structure is used to hold information needed to create and register 146 * a platform device using platform_device_register_full(). 147 * 148 * platform_device_register_full() makes deep copies of @name, @res, @data and 149 * @properties, so the caller does not need to keep them after registration. 150 * If the registration is performed during initialization, these can be marked 151 * as __initconst. 152 */ 153 struct platform_device_info { 154 struct device *parent; 155 struct fwnode_handle *fwnode; 156 bool of_node_reused; 157 158 const char *name; 159 int id; 160 161 const struct resource *res; 162 unsigned int num_res; 163 164 const void *data; 165 size_t size_data; 166 u64 dma_mask; 167 168 const struct software_node *swnode; 169 const struct property_entry *properties; 170 }; 171 extern struct platform_device *platform_device_register_full( 172 const struct platform_device_info *pdevinfo); 173 174 /** 175 * platform_device_register_resndata - add a platform-level device with 176 * resources and platform-specific data 177 * 178 * @parent: parent device for the device we're adding 179 * @name: base name of the device we're adding 180 * @id: instance id 181 * @res: set of resources that needs to be allocated for the device 182 * @num: number of resources 183 * @data: platform specific data for this platform device 184 * @size: size of platform specific data 185 * 186 * Returns &struct platform_device pointer on success, or ERR_PTR() on error. 187 */ 188 static inline struct platform_device *platform_device_register_resndata( 189 struct device *parent, const char *name, int id, 190 const struct resource *res, unsigned int num, 191 const void *data, size_t size) { 192 193 struct platform_device_info pdevinfo = { 194 .parent = parent, 195 .name = name, 196 .id = id, 197 .res = res, 198 .num_res = num, 199 .data = data, 200 .size_data = size, 201 .dma_mask = 0, 202 }; 203 204 return platform_device_register_full(&pdevinfo); 205 } 206 207 /** 208 * platform_device_register_simple - add a platform-level device and its resources 209 * @name: base name of the device we're adding 210 * @id: instance id 211 * @res: set of resources that needs to be allocated for the device 212 * @num: number of resources 213 * 214 * This function creates a simple platform device that requires minimal 215 * resource and memory management. Canned release function freeing memory 216 * allocated for the device allows drivers using such devices to be 217 * unloaded without waiting for the last reference to the device to be 218 * dropped. 219 * 220 * This interface is primarily intended for use with legacy drivers which 221 * probe hardware directly. Because such drivers create sysfs device nodes 222 * themselves, rather than letting system infrastructure handle such device 223 * enumeration tasks, they don't fully conform to the Linux driver model. 224 * In particular, when such drivers are built as modules, they can't be 225 * "hotplugged". 226 * 227 * Returns &struct platform_device pointer on success, or ERR_PTR() on error. 228 */ 229 static inline struct platform_device *platform_device_register_simple( 230 const char *name, int id, 231 const struct resource *res, unsigned int num) 232 { 233 return platform_device_register_resndata(NULL, name, id, 234 res, num, NULL, 0); 235 } 236 237 /** 238 * platform_device_register_data - add a platform-level device with platform-specific data 239 * @parent: parent device for the device we're adding 240 * @name: base name of the device we're adding 241 * @id: instance id 242 * @data: platform specific data for this platform device 243 * @size: size of platform specific data 244 * 245 * This function creates a simple platform device that requires minimal 246 * resource and memory management. Canned release function freeing memory 247 * allocated for the device allows drivers using such devices to be 248 * unloaded without waiting for the last reference to the device to be 249 * dropped. 250 * 251 * Returns &struct platform_device pointer on success, or ERR_PTR() on error. 252 */ 253 static inline struct platform_device *platform_device_register_data( 254 struct device *parent, const char *name, int id, 255 const void *data, size_t size) 256 { 257 return platform_device_register_resndata(parent, name, id, 258 NULL, 0, data, size); 259 } 260 261 extern struct platform_device *platform_device_alloc(const char *name, int id); 262 extern int platform_device_add_resources(struct platform_device *pdev, 263 const struct resource *res, 264 unsigned int num); 265 extern int platform_device_add_data(struct platform_device *pdev, 266 const void *data, size_t size); 267 void platform_device_set_of_node(struct platform_device *pdev, 268 struct device_node *np); 269 void platform_device_set_fwnode(struct platform_device *pdev, 270 struct fwnode_handle *fwnode); 271 void platform_device_set_of_node_from_dev(struct platform_device *pdev, 272 const struct device *dev2); 273 extern int platform_device_add(struct platform_device *pdev); 274 extern void platform_device_del(struct platform_device *pdev); 275 extern void platform_device_put(struct platform_device *pdev); 276 DEFINE_FREE(platform_device_put, struct platform_device *, if (_T) platform_device_put(_T)) 277 278 struct platform_driver { 279 int (*probe)(struct platform_device *); 280 void (*remove)(struct platform_device *); 281 void (*shutdown)(struct platform_device *); 282 int (*suspend)(struct platform_device *, pm_message_t state); 283 int (*resume)(struct platform_device *); 284 struct device_driver driver; 285 const struct platform_device_id *id_table; 286 bool prevent_deferred_probe; 287 /* 288 * For most device drivers, no need to care about this flag as long as 289 * all DMAs are handled through the kernel DMA API. For some special 290 * ones, for example VFIO drivers, they know how to manage the DMA 291 * themselves and set this flag so that the IOMMU layer will allow them 292 * to setup and manage their own I/O address space. 293 */ 294 bool driver_managed_dma; 295 }; 296 297 #define to_platform_driver(drv) (container_of((drv), struct platform_driver, \ 298 driver)) 299 300 /* 301 * use a macro to avoid include chaining to get THIS_MODULE 302 */ 303 #define platform_driver_register(drv) \ 304 __platform_driver_register(drv, THIS_MODULE, KBUILD_MODNAME) 305 extern int __platform_driver_register(struct platform_driver *, 306 struct module *, const char *mod_name); 307 extern void platform_driver_unregister(struct platform_driver *); 308 309 /* non-hotpluggable platform devices may use this so that probe() and 310 * its support may live in __init sections, conserving runtime memory. 311 */ 312 #define platform_driver_probe(drv, probe) \ 313 __platform_driver_probe(drv, probe, THIS_MODULE, KBUILD_MODNAME) 314 extern int __platform_driver_probe(struct platform_driver *driver, 315 int (*probe)(struct platform_device *), struct module *module, 316 const char *mod_name); 317 318 static inline void *platform_get_drvdata(const struct platform_device *pdev) 319 { 320 return dev_get_drvdata(&pdev->dev); 321 } 322 323 static inline void platform_set_drvdata(struct platform_device *pdev, 324 void *data) 325 { 326 dev_set_drvdata(&pdev->dev, data); 327 } 328 329 /* module_platform_driver() - Helper macro for drivers that don't do 330 * anything special in module init/exit. This eliminates a lot of 331 * boilerplate. Each module may only use this macro once, and 332 * calling it replaces module_init() and module_exit() 333 */ 334 #define module_platform_driver(__platform_driver) \ 335 module_driver(__platform_driver, platform_driver_register, \ 336 platform_driver_unregister) 337 338 /* builtin_platform_driver() - Helper macro for builtin drivers that 339 * don't do anything special in driver init. This eliminates some 340 * boilerplate. Each driver may only use this macro once, and 341 * calling it replaces device_initcall(). Note this is meant to be 342 * a parallel of module_platform_driver() above, but w/o _exit stuff. 343 */ 344 #define builtin_platform_driver(__platform_driver) \ 345 builtin_driver(__platform_driver, platform_driver_register) 346 347 /* 348 * subsys_platform_driver() - Helper macro for drivers that don't do anything 349 * special in module init/exit but need to register earlier, at 350 * subsys_initcall level, when built in. This eliminates a lot of 351 * boilerplate. Each driver may only use this macro once, and calling it 352 * replaces module_init() and module_exit(). This is meant to be a parallel 353 * of module_platform_driver() above, but with the init call promoted to 354 * subsys_initcall() so built-in providers are available earlier during boot. 355 */ 356 #define subsys_platform_driver(__platform_driver) \ 357 subsys_driver(__platform_driver, platform_driver_register, \ 358 platform_driver_unregister) 359 360 /* module_platform_driver_probe() - Helper macro for drivers that don't do 361 * anything special in module init/exit. This eliminates a lot of 362 * boilerplate. Each module may only use this macro once, and 363 * calling it replaces module_init() and module_exit() 364 */ 365 #define module_platform_driver_probe(__platform_driver, __platform_probe) \ 366 static int __init __platform_driver##_init(void) \ 367 { \ 368 return platform_driver_probe(&(__platform_driver), \ 369 __platform_probe); \ 370 } \ 371 module_init(__platform_driver##_init); \ 372 static void __exit __platform_driver##_exit(void) \ 373 { \ 374 platform_driver_unregister(&(__platform_driver)); \ 375 } \ 376 module_exit(__platform_driver##_exit); 377 378 /* builtin_platform_driver_probe() - Helper macro for drivers that don't do 379 * anything special in device init. This eliminates some boilerplate. Each 380 * driver may only use this macro once, and using it replaces device_initcall. 381 * This is meant to be a parallel of module_platform_driver_probe above, but 382 * without the __exit parts. 383 */ 384 #define builtin_platform_driver_probe(__platform_driver, __platform_probe) \ 385 static int __init __platform_driver##_init(void) \ 386 { \ 387 return platform_driver_probe(&(__platform_driver), \ 388 __platform_probe); \ 389 } \ 390 device_initcall(__platform_driver##_init); \ 391 392 /* 393 * subsys_platform_driver_probe() - Helper macro for drivers that don't do 394 * anything special in device init and have no exit, but need to register 395 * earlier, at subsys_initcall level. This eliminates some boilerplate. Each 396 * driver may only use this macro once, and using it replaces subsys_initcall. 397 * This is meant to be a parallel of builtin_platform_driver_probe above, but 398 * with the init call promoted to subsys_initcall so the provider is available 399 * earlier during boot. 400 */ 401 #define subsys_platform_driver_probe(__platform_driver, __platform_probe) \ 402 static int __init __platform_driver##_init(void) \ 403 { \ 404 return platform_driver_probe(&(__platform_driver), \ 405 __platform_probe); \ 406 } \ 407 subsys_initcall(__platform_driver##_init) \ 408 409 #define platform_create_bundle(driver, probe, res, n_res, data, size) \ 410 __platform_create_bundle(driver, probe, res, n_res, data, size, THIS_MODULE, KBUILD_MODNAME) 411 extern struct platform_device *__platform_create_bundle( 412 struct platform_driver *driver, int (*probe)(struct platform_device *), 413 struct resource *res, unsigned int n_res, 414 const void *data, size_t size, struct module *module, const char *mod_name); 415 416 int __platform_register_drivers(struct platform_driver * const *drivers, 417 unsigned int count, struct module *owner, const char *mod_name); 418 void platform_unregister_drivers(struct platform_driver * const *drivers, 419 unsigned int count); 420 421 #define platform_register_drivers(drivers, count) \ 422 __platform_register_drivers(drivers, count, THIS_MODULE, KBUILD_MODNAME) 423 424 #ifdef CONFIG_SUSPEND 425 extern int platform_pm_suspend(struct device *dev); 426 extern int platform_pm_resume(struct device *dev); 427 #else 428 #define platform_pm_suspend NULL 429 #define platform_pm_resume NULL 430 #endif 431 432 #ifdef CONFIG_HIBERNATE_CALLBACKS 433 extern int platform_pm_freeze(struct device *dev); 434 extern int platform_pm_thaw(struct device *dev); 435 extern int platform_pm_poweroff(struct device *dev); 436 extern int platform_pm_restore(struct device *dev); 437 #else 438 #define platform_pm_freeze NULL 439 #define platform_pm_thaw NULL 440 #define platform_pm_poweroff NULL 441 #define platform_pm_restore NULL 442 #endif 443 444 #ifdef CONFIG_PM_SLEEP 445 #define USE_PLATFORM_PM_SLEEP_OPS \ 446 .suspend = platform_pm_suspend, \ 447 .resume = platform_pm_resume, \ 448 .freeze = platform_pm_freeze, \ 449 .thaw = platform_pm_thaw, \ 450 .poweroff = platform_pm_poweroff, \ 451 .restore = platform_pm_restore, 452 #else 453 #define USE_PLATFORM_PM_SLEEP_OPS 454 #endif 455 456 #ifndef CONFIG_SUPERH 457 /* 458 * REVISIT: This stub is needed for all non-SuperH users of early platform 459 * drivers. It should go away once we introduce the new platform_device-based 460 * early driver framework. 461 */ 462 static inline int is_sh_early_platform_device(struct platform_device *pdev) 463 { 464 return 0; 465 } 466 #endif /* CONFIG_SUPERH */ 467 468 /* For now only SuperH uses it */ 469 void early_platform_cleanup(void); 470 471 #endif /* _PLATFORM_DEVICE_H_ */ 472