]>
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 | ||
135 | ||
136 | 3. Devres group | |
137 | --------------- | |
138 | ||
139 | Devres entries can be grouped using devres group. When a group is | |
140 | released, all contained normal devres entries and properly nested | |
141 | groups are released. One usage is to rollback series of acquired | |
142 | resources on failure. For example, | |
143 | ||
144 | if (!devres_open_group(dev, NULL, GFP_KERNEL)) | |
145 | return -ENOMEM; | |
146 | ||
147 | acquire A; | |
148 | if (failed) | |
149 | goto err; | |
150 | ||
151 | acquire B; | |
152 | if (failed) | |
153 | goto err; | |
154 | ... | |
155 | ||
156 | devres_remove_group(dev, NULL); | |
157 | return 0; | |
158 | ||
159 | err: | |
160 | devres_release_group(dev, NULL); | |
161 | return err_code; | |
162 | ||
01dd2fbf | 163 | As resource acquisition failure usually means probe failure, constructs |
9ac7849e TH |
164 | like above are usually useful in midlayer driver (e.g. libata core |
165 | layer) where interface function shouldn't have side effect on failure. | |
166 | For LLDs, just returning error code suffices in most cases. | |
167 | ||
168 | Each group is identified by void *id. It can either be explicitly | |
169 | specified by @id argument to devres_open_group() or automatically | |
170 | created by passing NULL as @id as in the above example. In both | |
171 | cases, devres_open_group() returns the group's id. The returned id | |
172 | can be passed to other devres functions to select the target group. | |
173 | If NULL is given to those functions, the latest open group is | |
174 | selected. | |
175 | ||
176 | For example, you can do something like the following. | |
177 | ||
178 | int my_midlayer_create_something() | |
179 | { | |
180 | if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) | |
181 | return -ENOMEM; | |
182 | ||
183 | ... | |
184 | ||
3265b545 | 185 | devres_close_group(dev, my_midlayer_create_something); |
9ac7849e TH |
186 | return 0; |
187 | } | |
188 | ||
189 | void my_midlayer_destroy_something() | |
190 | { | |
19f59460 | 191 | devres_release_group(dev, my_midlayer_create_something); |
9ac7849e TH |
192 | } |
193 | ||
194 | ||
195 | 4. Details | |
196 | ---------- | |
197 | ||
198 | Lifetime of a devres entry begins on devres allocation and finishes | |
199 | when it is released or destroyed (removed and freed) - no reference | |
200 | counting. | |
201 | ||
202 | devres core guarantees atomicity to all basic devres operations and | |
203 | has support for single-instance devres types (atomic | |
204 | lookup-and-add-if-not-found). Other than that, synchronizing | |
205 | concurrent accesses to allocated devres data is caller's | |
206 | responsibility. This is usually non-issue because bus ops and | |
207 | resource allocations already do the job. | |
208 | ||
209 | For an example of single-instance devres type, read pcim_iomap_table() | |
2c19c49a | 210 | in lib/devres.c. |
9ac7849e TH |
211 | |
212 | All devres interface functions can be called without context if the | |
213 | right gfp mask is given. | |
214 | ||
215 | ||
216 | 5. Overhead | |
217 | ----------- | |
218 | ||
219 | Each devres bookkeeping info is allocated together with requested data | |
220 | area. With debug option turned off, bookkeeping info occupies 16 | |
221 | bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded | |
222 | up to ull alignment). If singly linked list is used, it can be | |
223 | reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). | |
224 | ||
225 | Each devres group occupies 8 pointers. It can be reduced to 6 if | |
226 | singly linked list is used. | |
227 | ||
228 | Memory space overhead on ahci controller with two ports is between 300 | |
229 | and 400 bytes on 32bit machine after naive conversion (we can | |
230 | certainly invest a bit more effort into libata core layer). | |
231 | ||
232 | ||
233 | 6. List of managed interfaces | |
234 | ----------------------------- | |
235 | ||
d8e1e012 GU |
236 | CLOCK |
237 | devm_clk_get() | |
238 | devm_clk_put() | |
4143804c | 239 | devm_clk_hw_register() |
d8e1e012 GU |
240 | |
241 | DMA | |
242 | dmam_alloc_coherent() | |
243 | dmam_alloc_noncoherent() | |
244 | dmam_declare_coherent_memory() | |
245 | dmam_free_coherent() | |
246 | dmam_free_noncoherent() | |
247 | dmam_pool_create() | |
248 | dmam_pool_destroy() | |
249 | ||
250 | GPIO | |
251 | devm_gpiod_get() | |
252 | devm_gpiod_get_index() | |
253 | devm_gpiod_get_index_optional() | |
254 | devm_gpiod_get_optional() | |
255 | devm_gpiod_put() | |
38115ead LD |
256 | devm_gpiochip_add_data() |
257 | devm_gpiochip_remove() | |
77ae582c LD |
258 | devm_gpio_request() |
259 | devm_gpio_request_one() | |
260 | devm_gpio_free() | |
543f43ce | 261 | |
224b995a OK |
262 | IIO |
263 | devm_iio_device_alloc() | |
264 | devm_iio_device_free() | |
8caa07c0 SK |
265 | devm_iio_device_register() |
266 | devm_iio_device_unregister() | |
780103fe KW |
267 | devm_iio_kfifo_allocate() |
268 | devm_iio_kfifo_free() | |
d8e1e012 GU |
269 | devm_iio_trigger_alloc() |
270 | devm_iio_trigger_free() | |
e21a294d LD |
271 | devm_iio_channel_get() |
272 | devm_iio_channel_release() | |
273 | devm_iio_channel_get_all() | |
274 | devm_iio_channel_release_all() | |
224b995a | 275 | |
2ea2dc87 AK |
276 | INPUT |
277 | devm_input_allocate_device() | |
278 | ||
9ac7849e | 279 | IO region |
9ac7849e | 280 | devm_release_mem_region() |
d8e1e012 | 281 | devm_release_region() |
8d38821c | 282 | devm_release_resource() |
d8e1e012 GU |
283 | devm_request_mem_region() |
284 | devm_request_region() | |
8d38821c | 285 | devm_request_resource() |
9ac7849e TH |
286 | |
287 | IOMAP | |
288 | devm_ioport_map() | |
289 | devm_ioport_unmap() | |
290 | devm_ioremap() | |
291 | devm_ioremap_nocache() | |
34644524 | 292 | devm_ioremap_wc() |
75096579 | 293 | devm_ioremap_resource() : checks resource, requests memory region, ioremaps |
d8e1e012 | 294 | devm_iounmap() |
9ac7849e | 295 | pcim_iomap() |
9ac7849e | 296 | pcim_iomap_regions() : do request_region() and iomap() on multiple BARs |
d8e1e012 GU |
297 | pcim_iomap_table() : array of mapped addresses indexed by BAR |
298 | pcim_iounmap() | |
070b9079 | 299 | |
d8e1e012 GU |
300 | IRQ |
301 | devm_free_irq() | |
ea05166a | 302 | devm_request_any_context_irq() |
d8e1e012 | 303 | devm_request_irq() |
ea05166a | 304 | devm_request_threaded_irq() |
a8a97db9 | 305 | |
ca1bb4ee BA |
306 | LED |
307 | devm_led_classdev_register() | |
308 | devm_led_classdev_unregister() | |
309 | ||
d8e1e012 GU |
310 | MDIO |
311 | devm_mdiobus_alloc() | |
312 | devm_mdiobus_alloc_size() | |
313 | devm_mdiobus_free() | |
314 | ||
315 | MEM | |
316 | devm_free_pages() | |
317 | devm_get_free_pages() | |
bef59c50 | 318 | devm_kasprintf() |
d8e1e012 GU |
319 | devm_kcalloc() |
320 | devm_kfree() | |
321 | devm_kmalloc() | |
322 | devm_kmalloc_array() | |
323 | devm_kmemdup() | |
54270354 | 324 | devm_kstrdup() |
bef59c50 | 325 | devm_kvasprintf() |
d8e1e012 GU |
326 | devm_kzalloc() |
327 | ||
3698283b LD |
328 | MFD |
329 | devm_mfd_add_devices() | |
330 | ||
d8e1e012 GU |
331 | PCI |
332 | pcim_enable_device() : after success, all PCI ops become managed | |
333 | pcim_pin_device() : keep PCI device enabled after release | |
334 | ||
335 | PHY | |
336 | devm_usb_get_phy() | |
337 | devm_usb_put_phy() | |
3d1482fe | 338 | |
6d4ca1fb SW |
339 | PINCTRL |
340 | devm_pinctrl_get() | |
341 | devm_pinctrl_put() | |
1f8dd72f LD |
342 | devm_pinctrl_register() |
343 | devm_pinctrl_unregister() | |
6354316d AC |
344 | |
345 | PWM | |
346 | devm_pwm_get() | |
347 | devm_pwm_put() | |
2202d4e8 | 348 | |
d8e1e012 GU |
349 | REGULATOR |
350 | devm_regulator_bulk_get() | |
351 | devm_regulator_get() | |
352 | devm_regulator_put() | |
353 | devm_regulator_register() | |
0244d84f | 354 | |
8d5b5d5c MY |
355 | RESET |
356 | devm_reset_control_get() | |
357 | devm_reset_controller_register() | |
358 | ||
0244d84f AS |
359 | SLAVE DMA ENGINE |
360 | devm_acpi_dma_controller_register() | |
666d5b4c MB |
361 | |
362 | SPI | |
363 | devm_spi_register_master() | |
83fbae5a NA |
364 | |
365 | WATCHDOG | |
366 | devm_watchdog_register_device() |