Commit | Line | Data |
---|---|---|
9ac7849e TH |
1 | Devres - Managed Device Resource |
2 | ================================ | |
3 | ||
4 | Tejun Heo <teheo@suse.de> | |
5 | ||
6 | First draft 10 January 2007 | |
7 | ||
8 | ||
9 | 1. Intro : Huh? Devres? | |
10 | 2. Devres : Devres in a nutshell | |
11 | 3. Devres Group : Group devres'es and release them together | |
12 | 4. Details : Life time rules, calling context, ... | |
13 | 5. Overhead : How much do we have to pay for this? | |
14 | 6. List of managed interfaces : Currently implemented managed interfaces | |
15 | ||
16 | ||
17 | 1. Intro | |
18 | -------- | |
19 | ||
20 | devres came up while trying to convert libata to use iomap. Each | |
21 | iomapped address should be kept and unmapped on driver detach. For | |
22 | example, a plain SFF ATA controller (that is, good old PCI IDE) in | |
23 | native mode makes use of 5 PCI BARs and all of them should be | |
24 | maintained. | |
25 | ||
26 | As with many other device drivers, libata low level drivers have | |
27 | sufficient bugs in ->remove and ->probe failure path. Well, yes, | |
28 | that's probably because libata low level driver developers are lazy | |
29 | bunch, but aren't all low level driver developers? After spending a | |
30 | day fiddling with braindamaged hardware with no document or | |
31 | braindamaged document, if it's finally working, well, it's working. | |
32 | ||
33 | For one reason or another, low level drivers don't receive as much | |
34 | attention or testing as core code, and bugs on driver detach or | |
01dd2fbf | 35 | initialization failure don't happen often enough to be noticeable. |
9ac7849e TH |
36 | Init failure path is worse because it's much less travelled while |
37 | needs to handle multiple entry points. | |
38 | ||
39 | So, many low level drivers end up leaking resources on driver detach | |
40 | and having half broken failure path implementation in ->probe() which | |
41 | would leak resources or even cause oops when failure occurs. iomap | |
42 | adds more to this mix. So do msi and msix. | |
43 | ||
44 | ||
45 | 2. Devres | |
46 | --------- | |
47 | ||
48 | devres is basically linked list of arbitrarily sized memory areas | |
49 | associated with a struct device. Each devres entry is associated with | |
50 | a release function. A devres can be released in several ways. No | |
51 | matter what, all devres entries are released on driver detach. On | |
52 | release, the associated release function is invoked and then the | |
53 | devres entry is freed. | |
54 | ||
55 | Managed interface is created for resources commonly used by device | |
56 | drivers using devres. For example, coherent DMA memory is acquired | |
57 | using dma_alloc_coherent(). The managed version is called | |
58 | dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except | |
59 | for the DMA memory allocated using it is managed and will be | |
60 | automatically released on driver detach. Implementation looks like | |
61 | the following. | |
62 | ||
63 | struct dma_devres { | |
64 | size_t size; | |
65 | void *vaddr; | |
66 | dma_addr_t dma_handle; | |
67 | }; | |
68 | ||
69 | static void dmam_coherent_release(struct device *dev, void *res) | |
70 | { | |
71 | struct dma_devres *this = res; | |
72 | ||
73 | dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); | |
74 | } | |
75 | ||
76 | dmam_alloc_coherent(dev, size, dma_handle, gfp) | |
77 | { | |
78 | struct dma_devres *dr; | |
79 | void *vaddr; | |
80 | ||
81 | dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); | |
82 | ... | |
83 | ||
84 | /* alloc DMA memory as usual */ | |
85 | vaddr = dma_alloc_coherent(...); | |
86 | ... | |
87 | ||
88 | /* record size, vaddr, dma_handle in dr */ | |
89 | dr->vaddr = vaddr; | |
90 | ... | |
91 | ||
92 | devres_add(dev, dr); | |
93 | ||
94 | return vaddr; | |
95 | } | |
96 | ||
97 | If a driver uses dmam_alloc_coherent(), the area is guaranteed to be | |
98 | freed whether initialization fails half-way or the device gets | |
99 | detached. If most resources are acquired using managed interface, a | |
100 | driver can have much simpler init and exit code. Init path basically | |
101 | looks like the following. | |
102 | ||
103 | my_init_one() | |
104 | { | |
105 | struct mydev *d; | |
106 | ||
107 | d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); | |
108 | if (!d) | |
109 | return -ENOMEM; | |
110 | ||
111 | d->ring = dmam_alloc_coherent(...); | |
112 | if (!d->ring) | |
113 | return -ENOMEM; | |
114 | ||
115 | if (check something) | |
116 | return -EINVAL; | |
117 | ... | |
118 | ||
119 | return register_to_upper_layer(d); | |
120 | } | |
121 | ||
122 | And exit path, | |
123 | ||
124 | my_remove_one() | |
125 | { | |
126 | unregister_from_upper_layer(d); | |
127 | shutdown_my_hardware(); | |
128 | } | |
129 | ||
130 | As shown above, low level drivers can be simplified a lot by using | |
131 | devres. Complexity is shifted from less maintained low level drivers | |
132 | to better maintained higher layer. Also, as init failure path is | |
133 | shared with exit path, both can get more testing. | |
134 | ||
41c31f6a NMG |
135 | Note though that when converting current calls or assignments to |
136 | managed devm_* versions it is up to you to check if internal operations | |
137 | like allocating memory, have failed. Managed resources pertains to the | |
138 | freeing of these resources *only* - all other checks needed are still | |
139 | on you. In some cases this may mean introducing checks that were not | |
140 | necessary before moving to the managed devm_* calls. | |
141 | ||
9ac7849e TH |
142 | |
143 | 3. Devres group | |
144 | --------------- | |
145 | ||
146 | Devres entries can be grouped using devres group. When a group is | |
147 | released, all contained normal devres entries and properly nested | |
148 | groups are released. One usage is to rollback series of acquired | |
149 | resources on failure. For example, | |
150 | ||
151 | if (!devres_open_group(dev, NULL, GFP_KERNEL)) | |
152 | return -ENOMEM; | |
153 | ||
154 | acquire A; | |
155 | if (failed) | |
156 | goto err; | |
157 | ||
158 | acquire B; | |
159 | if (failed) | |
160 | goto err; | |
161 | ... | |
162 | ||
163 | devres_remove_group(dev, NULL); | |
164 | return 0; | |
165 | ||
166 | err: | |
167 | devres_release_group(dev, NULL); | |
168 | return err_code; | |
169 | ||
01dd2fbf | 170 | As resource acquisition failure usually means probe failure, constructs |
9ac7849e TH |
171 | like above are usually useful in midlayer driver (e.g. libata core |
172 | layer) where interface function shouldn't have side effect on failure. | |
173 | For LLDs, just returning error code suffices in most cases. | |
174 | ||
175 | Each group is identified by void *id. It can either be explicitly | |
176 | specified by @id argument to devres_open_group() or automatically | |
177 | created by passing NULL as @id as in the above example. In both | |
178 | cases, devres_open_group() returns the group's id. The returned id | |
179 | can be passed to other devres functions to select the target group. | |
180 | If NULL is given to those functions, the latest open group is | |
181 | selected. | |
182 | ||
183 | For example, you can do something like the following. | |
184 | ||
185 | int my_midlayer_create_something() | |
186 | { | |
187 | if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) | |
188 | return -ENOMEM; | |
189 | ||
190 | ... | |
191 | ||
3265b545 | 192 | devres_close_group(dev, my_midlayer_create_something); |
9ac7849e TH |
193 | return 0; |
194 | } | |
195 | ||
196 | void my_midlayer_destroy_something() | |
197 | { | |
19f59460 | 198 | devres_release_group(dev, my_midlayer_create_something); |
9ac7849e TH |
199 | } |
200 | ||
201 | ||
202 | 4. Details | |
203 | ---------- | |
204 | ||
205 | Lifetime of a devres entry begins on devres allocation and finishes | |
206 | when it is released or destroyed (removed and freed) - no reference | |
207 | counting. | |
208 | ||
209 | devres core guarantees atomicity to all basic devres operations and | |
210 | has support for single-instance devres types (atomic | |
211 | lookup-and-add-if-not-found). Other than that, synchronizing | |
212 | concurrent accesses to allocated devres data is caller's | |
213 | responsibility. This is usually non-issue because bus ops and | |
214 | resource allocations already do the job. | |
215 | ||
216 | For an example of single-instance devres type, read pcim_iomap_table() | |
2c19c49a | 217 | in lib/devres.c. |
9ac7849e TH |
218 | |
219 | All devres interface functions can be called without context if the | |
220 | right gfp mask is given. | |
221 | ||
222 | ||
223 | 5. Overhead | |
224 | ----------- | |
225 | ||
226 | Each devres bookkeeping info is allocated together with requested data | |
227 | area. With debug option turned off, bookkeeping info occupies 16 | |
228 | bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded | |
229 | up to ull alignment). If singly linked list is used, it can be | |
230 | reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). | |
231 | ||
232 | Each devres group occupies 8 pointers. It can be reduced to 6 if | |
233 | singly linked list is used. | |
234 | ||
235 | Memory space overhead on ahci controller with two ports is between 300 | |
236 | and 400 bytes on 32bit machine after naive conversion (we can | |
237 | certainly invest a bit more effort into libata core layer). | |
238 | ||
239 | ||
240 | 6. List of managed interfaces | |
241 | ----------------------------- | |
242 | ||
d8e1e012 GU |
243 | CLOCK |
244 | devm_clk_get() | |
60b8f0dd | 245 | devm_clk_get_optional() |
d8e1e012 | 246 | devm_clk_put() |
4143804c | 247 | devm_clk_hw_register() |
aa795c41 | 248 | devm_of_clk_add_hw_provider() |
3eee6c7d | 249 | devm_clk_hw_register_clkdev() |
d8e1e012 GU |
250 | |
251 | DMA | |
f39b948d | 252 | dmaenginem_async_device_register() |
d8e1e012 | 253 | dmam_alloc_coherent() |
63d36c95 | 254 | dmam_alloc_attrs() |
d8e1e012 | 255 | dmam_free_coherent() |
d8e1e012 GU |
256 | dmam_pool_create() |
257 | dmam_pool_destroy() | |
258 | ||
9b1f1b6b NT |
259 | DRM |
260 | devm_drm_dev_init() | |
261 | ||
d8e1e012 GU |
262 | GPIO |
263 | devm_gpiod_get() | |
264 | devm_gpiod_get_index() | |
265 | devm_gpiod_get_index_optional() | |
266 | devm_gpiod_get_optional() | |
267 | devm_gpiod_put() | |
891ddbc7 | 268 | devm_gpiod_unhinge() |
38115ead | 269 | devm_gpiochip_add_data() |
77ae582c LD |
270 | devm_gpio_request() |
271 | devm_gpio_request_one() | |
272 | devm_gpio_free() | |
543f43ce | 273 | |
b8f5fe3b HK |
274 | I2C |
275 | devm_i2c_new_dummy_device() | |
276 | ||
224b995a OK |
277 | IIO |
278 | devm_iio_device_alloc() | |
279 | devm_iio_device_free() | |
8caa07c0 SK |
280 | devm_iio_device_register() |
281 | devm_iio_device_unregister() | |
780103fe KW |
282 | devm_iio_kfifo_allocate() |
283 | devm_iio_kfifo_free() | |
70e48348 GB |
284 | devm_iio_triggered_buffer_setup() |
285 | devm_iio_triggered_buffer_cleanup() | |
d8e1e012 GU |
286 | devm_iio_trigger_alloc() |
287 | devm_iio_trigger_free() | |
9083325f GB |
288 | devm_iio_trigger_register() |
289 | devm_iio_trigger_unregister() | |
e21a294d LD |
290 | devm_iio_channel_get() |
291 | devm_iio_channel_release() | |
292 | devm_iio_channel_get_all() | |
293 | devm_iio_channel_release_all() | |
224b995a | 294 | |
2ea2dc87 AK |
295 | INPUT |
296 | devm_input_allocate_device() | |
297 | ||
9ac7849e | 298 | IO region |
9ac7849e | 299 | devm_release_mem_region() |
d8e1e012 | 300 | devm_release_region() |
8d38821c | 301 | devm_release_resource() |
d8e1e012 GU |
302 | devm_request_mem_region() |
303 | devm_request_region() | |
8d38821c | 304 | devm_request_resource() |
9ac7849e TH |
305 | |
306 | IOMAP | |
307 | devm_ioport_map() | |
308 | devm_ioport_unmap() | |
309 | devm_ioremap() | |
310 | devm_ioremap_nocache() | |
34644524 | 311 | devm_ioremap_wc() |
75096579 | 312 | devm_ioremap_resource() : checks resource, requests memory region, ioremaps |
d8e1e012 | 313 | devm_iounmap() |
9ac7849e | 314 | pcim_iomap() |
9ac7849e | 315 | pcim_iomap_regions() : do request_region() and iomap() on multiple BARs |
d8e1e012 GU |
316 | pcim_iomap_table() : array of mapped addresses indexed by BAR |
317 | pcim_iounmap() | |
070b9079 | 318 | |
d8e1e012 GU |
319 | IRQ |
320 | devm_free_irq() | |
ea05166a | 321 | devm_request_any_context_irq() |
d8e1e012 | 322 | devm_request_irq() |
ea05166a | 323 | devm_request_threaded_irq() |
2b5e7730 BG |
324 | devm_irq_alloc_descs() |
325 | devm_irq_alloc_desc() | |
326 | devm_irq_alloc_desc_at() | |
327 | devm_irq_alloc_desc_from() | |
328 | devm_irq_alloc_descs_from() | |
1c3e3630 | 329 | devm_irq_alloc_generic_chip() |
30fd8fc5 | 330 | devm_irq_setup_generic_chip() |
44e72c7e | 331 | devm_irq_sim_init() |
a8a97db9 | 332 | |
ca1bb4ee BA |
333 | LED |
334 | devm_led_classdev_register() | |
335 | devm_led_classdev_unregister() | |
336 | ||
d8e1e012 GU |
337 | MDIO |
338 | devm_mdiobus_alloc() | |
339 | devm_mdiobus_alloc_size() | |
340 | devm_mdiobus_free() | |
341 | ||
342 | MEM | |
343 | devm_free_pages() | |
344 | devm_get_free_pages() | |
bef59c50 | 345 | devm_kasprintf() |
d8e1e012 GU |
346 | devm_kcalloc() |
347 | devm_kfree() | |
348 | devm_kmalloc() | |
349 | devm_kmalloc_array() | |
350 | devm_kmemdup() | |
54270354 | 351 | devm_kstrdup() |
bef59c50 | 352 | devm_kvasprintf() |
d8e1e012 GU |
353 | devm_kzalloc() |
354 | ||
3698283b | 355 | MFD |
b594b101 | 356 | devm_mfd_add_devices() |
3698283b | 357 | |
a3b02a9c PR |
358 | MUX |
359 | devm_mux_chip_alloc() | |
360 | devm_mux_chip_register() | |
361 | devm_mux_control_get() | |
3698283b | 362 | |
ff86aae3 MB |
363 | PER-CPU MEM |
364 | devm_alloc_percpu() | |
365 | devm_free_percpu() | |
366 | ||
d8e1e012 | 367 | PCI |
5c3f18cc | 368 | devm_pci_alloc_host_bridge() : managed PCI host bridge allocation |
490cb6dd LP |
369 | devm_pci_remap_cfgspace() : ioremap PCI configuration space |
370 | devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource | |
371 | pcim_enable_device() : after success, all PCI ops become managed | |
372 | pcim_pin_device() : keep PCI device enabled after release | |
d8e1e012 GU |
373 | |
374 | PHY | |
375 | devm_usb_get_phy() | |
376 | devm_usb_put_phy() | |
3d1482fe | 377 | |
6d4ca1fb SW |
378 | PINCTRL |
379 | devm_pinctrl_get() | |
380 | devm_pinctrl_put() | |
1f8dd72f LD |
381 | devm_pinctrl_register() |
382 | devm_pinctrl_unregister() | |
6354316d | 383 | |
c1a9634f BA |
384 | POWER |
385 | devm_reboot_mode_register() | |
386 | devm_reboot_mode_unregister() | |
387 | ||
6354316d AC |
388 | PWM |
389 | devm_pwm_get() | |
390 | devm_pwm_put() | |
2202d4e8 | 391 | |
d8e1e012 GU |
392 | REGULATOR |
393 | devm_regulator_bulk_get() | |
394 | devm_regulator_get() | |
395 | devm_regulator_put() | |
396 | devm_regulator_register() | |
0244d84f | 397 | |
8d5b5d5c MY |
398 | RESET |
399 | devm_reset_control_get() | |
400 | devm_reset_controller_register() | |
401 | ||
2cb67d20 AS |
402 | SERDEV |
403 | devm_serdev_device_open() | |
404 | ||
0244d84f AS |
405 | SLAVE DMA ENGINE |
406 | devm_acpi_dma_controller_register() | |
666d5b4c MB |
407 | |
408 | SPI | |
409 | devm_spi_register_master() | |
83fbae5a NA |
410 | |
411 | WATCHDOG | |
412 | devm_watchdog_register_device() |