0001 ================================
0002 Devres - Managed Device Resource
0003 ================================
0004
0005 Tejun Heo <teheo@suse.de>
0006
0007 First draft 10 January 2007
0008
0009 .. contents
0010
0011 1. Intro : Huh? Devres?
0012 2. Devres : Devres in a nutshell
0013 3. Devres Group : Group devres'es and release them together
0014 4. Details : Life time rules, calling context, ...
0015 5. Overhead : How much do we have to pay for this?
0016 6. List of managed interfaces: Currently implemented managed interfaces
0017
0018
0019 1. Intro
0020 --------
0021
0022 devres came up while trying to convert libata to use iomap. Each
0023 iomapped address should be kept and unmapped on driver detach. For
0024 example, a plain SFF ATA controller (that is, good old PCI IDE) in
0025 native mode makes use of 5 PCI BARs and all of them should be
0026 maintained.
0027
0028 As with many other device drivers, libata low level drivers have
0029 sufficient bugs in ->remove and ->probe failure path. Well, yes,
0030 that's probably because libata low level driver developers are lazy
0031 bunch, but aren't all low level driver developers? After spending a
0032 day fiddling with braindamaged hardware with no document or
0033 braindamaged document, if it's finally working, well, it's working.
0034
0035 For one reason or another, low level drivers don't receive as much
0036 attention or testing as core code, and bugs on driver detach or
0037 initialization failure don't happen often enough to be noticeable.
0038 Init failure path is worse because it's much less travelled while
0039 needs to handle multiple entry points.
0040
0041 So, many low level drivers end up leaking resources on driver detach
0042 and having half broken failure path implementation in ->probe() which
0043 would leak resources or even cause oops when failure occurs. iomap
0044 adds more to this mix. So do msi and msix.
0045
0046
0047 2. Devres
0048 ---------
0049
0050 devres is basically linked list of arbitrarily sized memory areas
0051 associated with a struct device. Each devres entry is associated with
0052 a release function. A devres can be released in several ways. No
0053 matter what, all devres entries are released on driver detach. On
0054 release, the associated release function is invoked and then the
0055 devres entry is freed.
0056
0057 Managed interface is created for resources commonly used by device
0058 drivers using devres. For example, coherent DMA memory is acquired
0059 using dma_alloc_coherent(). The managed version is called
0060 dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except
0061 for the DMA memory allocated using it is managed and will be
0062 automatically released on driver detach. Implementation looks like
0063 the following::
0064
0065 struct dma_devres {
0066 size_t size;
0067 void *vaddr;
0068 dma_addr_t dma_handle;
0069 };
0070
0071 static void dmam_coherent_release(struct device *dev, void *res)
0072 {
0073 struct dma_devres *this = res;
0074
0075 dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle);
0076 }
0077
0078 dmam_alloc_coherent(dev, size, dma_handle, gfp)
0079 {
0080 struct dma_devres *dr;
0081 void *vaddr;
0082
0083 dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp);
0084 ...
0085
0086 /* alloc DMA memory as usual */
0087 vaddr = dma_alloc_coherent(...);
0088 ...
0089
0090 /* record size, vaddr, dma_handle in dr */
0091 dr->vaddr = vaddr;
0092 ...
0093
0094 devres_add(dev, dr);
0095
0096 return vaddr;
0097 }
0098
0099 If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
0100 freed whether initialization fails half-way or the device gets
0101 detached. If most resources are acquired using managed interface, a
0102 driver can have much simpler init and exit code. Init path basically
0103 looks like the following::
0104
0105 my_init_one()
0106 {
0107 struct mydev *d;
0108
0109 d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL);
0110 if (!d)
0111 return -ENOMEM;
0112
0113 d->ring = dmam_alloc_coherent(...);
0114 if (!d->ring)
0115 return -ENOMEM;
0116
0117 if (check something)
0118 return -EINVAL;
0119 ...
0120
0121 return register_to_upper_layer(d);
0122 }
0123
0124 And exit path::
0125
0126 my_remove_one()
0127 {
0128 unregister_from_upper_layer(d);
0129 shutdown_my_hardware();
0130 }
0131
0132 As shown above, low level drivers can be simplified a lot by using
0133 devres. Complexity is shifted from less maintained low level drivers
0134 to better maintained higher layer. Also, as init failure path is
0135 shared with exit path, both can get more testing.
0136
0137 Note though that when converting current calls or assignments to
0138 managed devm_* versions it is up to you to check if internal operations
0139 like allocating memory, have failed. Managed resources pertains to the
0140 freeing of these resources *only* - all other checks needed are still
0141 on you. In some cases this may mean introducing checks that were not
0142 necessary before moving to the managed devm_* calls.
0143
0144
0145 3. Devres group
0146 ---------------
0147
0148 Devres entries can be grouped using devres group. When a group is
0149 released, all contained normal devres entries and properly nested
0150 groups are released. One usage is to rollback series of acquired
0151 resources on failure. For example::
0152
0153 if (!devres_open_group(dev, NULL, GFP_KERNEL))
0154 return -ENOMEM;
0155
0156 acquire A;
0157 if (failed)
0158 goto err;
0159
0160 acquire B;
0161 if (failed)
0162 goto err;
0163 ...
0164
0165 devres_remove_group(dev, NULL);
0166 return 0;
0167
0168 err:
0169 devres_release_group(dev, NULL);
0170 return err_code;
0171
0172 As resource acquisition failure usually means probe failure, constructs
0173 like above are usually useful in midlayer driver (e.g. libata core
0174 layer) where interface function shouldn't have side effect on failure.
0175 For LLDs, just returning error code suffices in most cases.
0176
0177 Each group is identified by `void *id`. It can either be explicitly
0178 specified by @id argument to devres_open_group() or automatically
0179 created by passing NULL as @id as in the above example. In both
0180 cases, devres_open_group() returns the group's id. The returned id
0181 can be passed to other devres functions to select the target group.
0182 If NULL is given to those functions, the latest open group is
0183 selected.
0184
0185 For example, you can do something like the following::
0186
0187 int my_midlayer_create_something()
0188 {
0189 if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL))
0190 return -ENOMEM;
0191
0192 ...
0193
0194 devres_close_group(dev, my_midlayer_create_something);
0195 return 0;
0196 }
0197
0198 void my_midlayer_destroy_something()
0199 {
0200 devres_release_group(dev, my_midlayer_create_something);
0201 }
0202
0203
0204 4. Details
0205 ----------
0206
0207 Lifetime of a devres entry begins on devres allocation and finishes
0208 when it is released or destroyed (removed and freed) - no reference
0209 counting.
0210
0211 devres core guarantees atomicity to all basic devres operations and
0212 has support for single-instance devres types (atomic
0213 lookup-and-add-if-not-found). Other than that, synchronizing
0214 concurrent accesses to allocated devres data is caller's
0215 responsibility. This is usually non-issue because bus ops and
0216 resource allocations already do the job.
0217
0218 For an example of single-instance devres type, read pcim_iomap_table()
0219 in lib/devres.c.
0220
0221 All devres interface functions can be called without context if the
0222 right gfp mask is given.
0223
0224
0225 5. Overhead
0226 -----------
0227
0228 Each devres bookkeeping info is allocated together with requested data
0229 area. With debug option turned off, bookkeeping info occupies 16
0230 bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded
0231 up to ull alignment). If singly linked list is used, it can be
0232 reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit).
0233
0234 Each devres group occupies 8 pointers. It can be reduced to 6 if
0235 singly linked list is used.
0236
0237 Memory space overhead on ahci controller with two ports is between 300
0238 and 400 bytes on 32bit machine after naive conversion (we can
0239 certainly invest a bit more effort into libata core layer).
0240
0241
0242 6. List of managed interfaces
0243 -----------------------------
0244
0245 CLOCK
0246 devm_clk_get()
0247 devm_clk_get_optional()
0248 devm_clk_put()
0249 devm_clk_bulk_get()
0250 devm_clk_bulk_get_all()
0251 devm_clk_bulk_get_optional()
0252 devm_get_clk_from_child()
0253 devm_clk_hw_register()
0254 devm_of_clk_add_hw_provider()
0255 devm_clk_hw_register_clkdev()
0256
0257 DMA
0258 dmaenginem_async_device_register()
0259 dmam_alloc_coherent()
0260 dmam_alloc_attrs()
0261 dmam_free_coherent()
0262 dmam_pool_create()
0263 dmam_pool_destroy()
0264
0265 DRM
0266 devm_drm_dev_alloc()
0267
0268 GPIO
0269 devm_gpiod_get()
0270 devm_gpiod_get_array()
0271 devm_gpiod_get_array_optional()
0272 devm_gpiod_get_index()
0273 devm_gpiod_get_index_optional()
0274 devm_gpiod_get_optional()
0275 devm_gpiod_put()
0276 devm_gpiod_unhinge()
0277 devm_gpiochip_add_data()
0278 devm_gpio_request()
0279 devm_gpio_request_one()
0280
0281 I2C
0282 devm_i2c_new_dummy_device()
0283
0284 IIO
0285 devm_iio_device_alloc()
0286 devm_iio_device_register()
0287 devm_iio_dmaengine_buffer_setup()
0288 devm_iio_kfifo_buffer_setup()
0289 devm_iio_map_array_register()
0290 devm_iio_triggered_buffer_setup()
0291 devm_iio_trigger_alloc()
0292 devm_iio_trigger_register()
0293 devm_iio_channel_get()
0294 devm_iio_channel_get_all()
0295
0296 INPUT
0297 devm_input_allocate_device()
0298
0299 IO region
0300 devm_release_mem_region()
0301 devm_release_region()
0302 devm_release_resource()
0303 devm_request_mem_region()
0304 devm_request_region()
0305 devm_request_resource()
0306
0307 IOMAP
0308 devm_ioport_map()
0309 devm_ioport_unmap()
0310 devm_ioremap()
0311 devm_ioremap_uc()
0312 devm_ioremap_wc()
0313 devm_ioremap_np()
0314 devm_ioremap_resource() : checks resource, requests memory region, ioremaps
0315 devm_ioremap_resource_wc()
0316 devm_platform_ioremap_resource() : calls devm_ioremap_resource() for platform device
0317 devm_platform_ioremap_resource_byname()
0318 devm_platform_get_and_ioremap_resource()
0319 devm_iounmap()
0320 pcim_iomap()
0321 pcim_iomap_regions() : do request_region() and iomap() on multiple BARs
0322 pcim_iomap_table() : array of mapped addresses indexed by BAR
0323 pcim_iounmap()
0324
0325 IRQ
0326 devm_free_irq()
0327 devm_request_any_context_irq()
0328 devm_request_irq()
0329 devm_request_threaded_irq()
0330 devm_irq_alloc_descs()
0331 devm_irq_alloc_desc()
0332 devm_irq_alloc_desc_at()
0333 devm_irq_alloc_desc_from()
0334 devm_irq_alloc_descs_from()
0335 devm_irq_alloc_generic_chip()
0336 devm_irq_setup_generic_chip()
0337 devm_irq_sim_init()
0338
0339 LED
0340 devm_led_classdev_register()
0341 devm_led_classdev_unregister()
0342
0343 MDIO
0344 devm_mdiobus_alloc()
0345 devm_mdiobus_alloc_size()
0346 devm_mdiobus_register()
0347 devm_of_mdiobus_register()
0348
0349 MEM
0350 devm_free_pages()
0351 devm_get_free_pages()
0352 devm_kasprintf()
0353 devm_kcalloc()
0354 devm_kfree()
0355 devm_kmalloc()
0356 devm_kmalloc_array()
0357 devm_kmemdup()
0358 devm_krealloc()
0359 devm_kstrdup()
0360 devm_kvasprintf()
0361 devm_kzalloc()
0362
0363 MFD
0364 devm_mfd_add_devices()
0365
0366 MUX
0367 devm_mux_chip_alloc()
0368 devm_mux_chip_register()
0369 devm_mux_control_get()
0370 devm_mux_state_get()
0371
0372 NET
0373 devm_alloc_etherdev()
0374 devm_alloc_etherdev_mqs()
0375 devm_register_netdev()
0376
0377 PER-CPU MEM
0378 devm_alloc_percpu()
0379 devm_free_percpu()
0380
0381 PCI
0382 devm_pci_alloc_host_bridge() : managed PCI host bridge allocation
0383 devm_pci_remap_cfgspace() : ioremap PCI configuration space
0384 devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource
0385 pcim_enable_device() : after success, all PCI ops become managed
0386 pcim_pin_device() : keep PCI device enabled after release
0387
0388 PHY
0389 devm_usb_get_phy()
0390 devm_usb_put_phy()
0391
0392 PINCTRL
0393 devm_pinctrl_get()
0394 devm_pinctrl_put()
0395 devm_pinctrl_register()
0396 devm_pinctrl_unregister()
0397
0398 POWER
0399 devm_reboot_mode_register()
0400 devm_reboot_mode_unregister()
0401
0402 PWM
0403 devm_pwm_get()
0404 devm_of_pwm_get()
0405 devm_fwnode_pwm_get()
0406
0407 REGULATOR
0408 devm_regulator_bulk_get()
0409 devm_regulator_get()
0410 devm_regulator_put()
0411 devm_regulator_register()
0412
0413 RESET
0414 devm_reset_control_get()
0415 devm_reset_controller_register()
0416
0417 RTC
0418 devm_rtc_device_register()
0419 devm_rtc_allocate_device()
0420 devm_rtc_register_device()
0421 devm_rtc_nvmem_register()
0422
0423 SERDEV
0424 devm_serdev_device_open()
0425
0426 SLAVE DMA ENGINE
0427 devm_acpi_dma_controller_register()
0428
0429 SPI
0430 devm_spi_register_master()
0431
0432 WATCHDOG
0433 devm_watchdog_register_device()
