aboutsummaryrefslogtreecommitdiffstats
path: root/kernel
diff options
context:
space:
mode:
authorRandy Dunlap <rdunlap@xenotime.net>2006-10-03 04:13:51 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2006-10-03 11:03:41 -0400
commite1ca66d1b990b23e7753c729332c0ada61f4f38d (patch)
treee909397b22346bcad8e776bc69878b5355569d47 /kernel
parenteed34d0fc5e4b89269053ed855ef714edbcf4518 (diff)
[PATCH] kernel-doc for kernel/resource.c
Add kernel-doc function headers in kernel/resource.c and use them in DocBook. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'kernel')
-rw-r--r--kernel/resource.c83
1 files changed, 72 insertions, 11 deletions
diff --git a/kernel/resource.c b/kernel/resource.c
index 9db38a1a7520..6de60c12143e 100644
--- a/kernel/resource.c
+++ b/kernel/resource.c
@@ -193,6 +193,13 @@ static int __release_resource(struct resource *old)
193 return -EINVAL; 193 return -EINVAL;
194} 194}
195 195
196/**
197 * request_resource - request and reserve an I/O or memory resource
198 * @root: root resource descriptor
199 * @new: resource descriptor desired by caller
200 *
201 * Returns 0 for success, negative error code on error.
202 */
196int request_resource(struct resource *root, struct resource *new) 203int request_resource(struct resource *root, struct resource *new)
197{ 204{
198 struct resource *conflict; 205 struct resource *conflict;
@@ -205,6 +212,15 @@ int request_resource(struct resource *root, struct resource *new)
205 212
206EXPORT_SYMBOL(request_resource); 213EXPORT_SYMBOL(request_resource);
207 214
215/**
216 * ____request_resource - reserve a resource, with resource conflict returned
217 * @root: root resource descriptor
218 * @new: resource descriptor desired by caller
219 *
220 * Returns:
221 * On success, NULL is returned.
222 * On error, a pointer to the conflicting resource is returned.
223 */
208struct resource *____request_resource(struct resource *root, struct resource *new) 224struct resource *____request_resource(struct resource *root, struct resource *new)
209{ 225{
210 struct resource *conflict; 226 struct resource *conflict;
@@ -217,6 +233,10 @@ struct resource *____request_resource(struct resource *root, struct resource *ne
217 233
218EXPORT_SYMBOL(____request_resource); 234EXPORT_SYMBOL(____request_resource);
219 235
236/**
237 * release_resource - release a previously reserved resource
238 * @old: resource pointer
239 */
220int release_resource(struct resource *old) 240int release_resource(struct resource *old)
221{ 241{
222 int retval; 242 int retval;
@@ -315,8 +335,16 @@ static int find_resource(struct resource *root, struct resource *new,
315 return -EBUSY; 335 return -EBUSY;
316} 336}
317 337
318/* 338/**
319 * Allocate empty slot in the resource tree given range and alignment. 339 * allocate_resource - allocate empty slot in the resource tree given range & alignment
340 * @root: root resource descriptor
341 * @new: resource descriptor desired by caller
342 * @size: requested resource region size
343 * @min: minimum size to allocate
344 * @max: maximum size to allocate
345 * @align: alignment requested, in bytes
346 * @alignf: alignment function, optional, called if not NULL
347 * @alignf_data: arbitrary data to pass to the @alignf function
320 */ 348 */
321int allocate_resource(struct resource *root, struct resource *new, 349int allocate_resource(struct resource *root, struct resource *new,
322 resource_size_t size, resource_size_t min, 350 resource_size_t size, resource_size_t min,
@@ -407,10 +435,15 @@ int insert_resource(struct resource *parent, struct resource *new)
407 return result; 435 return result;
408} 436}
409 437
410/* 438/**
439 * adjust_resource - modify a resource's start and size
440 * @res: resource to modify
441 * @start: new start value
442 * @size: new size
443 *
411 * Given an existing resource, change its start and size to match the 444 * Given an existing resource, change its start and size to match the
412 * arguments. Returns -EBUSY if it can't fit. Existing children of 445 * arguments. Returns 0 on success, -EBUSY if it can't fit.
413 * the resource are assumed to be immutable. 446 * Existing children of the resource are assumed to be immutable.
414 */ 447 */
415int adjust_resource(struct resource *res, resource_size_t start, resource_size_t size) 448int adjust_resource(struct resource *res, resource_size_t start, resource_size_t size)
416{ 449{
@@ -456,11 +489,19 @@ EXPORT_SYMBOL(adjust_resource);
456 * Note how this, unlike the above, knows about 489 * Note how this, unlike the above, knows about
457 * the IO flag meanings (busy etc). 490 * the IO flag meanings (busy etc).
458 * 491 *
459 * Request-region creates a new busy region. 492 * request_region creates a new busy region.
460 * 493 *
461 * Check-region returns non-zero if the area is already busy 494 * check_region returns non-zero if the area is already busy.
462 * 495 *
463 * Release-region releases a matching busy region. 496 * release_region releases a matching busy region.
497 */
498
499/**
500 * __request_region - create a new busy resource region
501 * @parent: parent resource descriptor
502 * @start: resource start address
503 * @n: resource region size
504 * @name: reserving caller's ID string
464 */ 505 */
465struct resource * __request_region(struct resource *parent, 506struct resource * __request_region(struct resource *parent,
466 resource_size_t start, resource_size_t n, 507 resource_size_t start, resource_size_t n,
@@ -497,9 +538,23 @@ struct resource * __request_region(struct resource *parent,
497 } 538 }
498 return res; 539 return res;
499} 540}
500
501EXPORT_SYMBOL(__request_region); 541EXPORT_SYMBOL(__request_region);
502 542
543/**
544 * __check_region - check if a resource region is busy or free
545 * @parent: parent resource descriptor
546 * @start: resource start address
547 * @n: resource region size
548 *
549 * Returns 0 if the region is free at the moment it is checked,
550 * returns %-EBUSY if the region is busy.
551 *
552 * NOTE:
553 * This function is deprecated because its use is racy.
554 * Even if it returns 0, a subsequent call to request_region()
555 * may fail because another driver etc. just allocated the region.
556 * Do NOT use it. It will be removed from the kernel.
557 */
503int __check_region(struct resource *parent, resource_size_t start, 558int __check_region(struct resource *parent, resource_size_t start,
504 resource_size_t n) 559 resource_size_t n)
505{ 560{
@@ -513,9 +568,16 @@ int __check_region(struct resource *parent, resource_size_t start,
513 kfree(res); 568 kfree(res);
514 return 0; 569 return 0;
515} 570}
516
517EXPORT_SYMBOL(__check_region); 571EXPORT_SYMBOL(__check_region);
518 572
573/**
574 * __release_region - release a previously reserved resource region
575 * @parent: parent resource descriptor
576 * @start: resource start address
577 * @n: resource region size
578 *
579 * The described resource region must match a currently busy region.
580 */
519void __release_region(struct resource *parent, resource_size_t start, 581void __release_region(struct resource *parent, resource_size_t start,
520 resource_size_t n) 582 resource_size_t n)
521{ 583{
@@ -553,7 +615,6 @@ void __release_region(struct resource *parent, resource_size_t start,
553 "<%016llx-%016llx>\n", (unsigned long long)start, 615 "<%016llx-%016llx>\n", (unsigned long long)start,
554 (unsigned long long)end); 616 (unsigned long long)end);
555} 617}
556
557EXPORT_SYMBOL(__release_region); 618EXPORT_SYMBOL(__release_region);
558 619
559/* 620/*