Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

gpu: host1x: Flesh out kerneldoc

Improve kerneldoc for the public parts of the host1x infrastructure in
preparation for adding driver-specific part to the GPU documentation.

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Thierry Reding <treding@nvidia.com>

+170 -11
+75
drivers/gpu/host1x/bus.c
··· 40 40 41 41 /** 42 42 * host1x_subdev_add() - add a new subdevice with an associated device node 43 + * @device: host1x device to add the subdevice to 44 + * @driver: host1x driver 45 + * @np: device node 43 46 */ 44 47 static int host1x_subdev_add(struct host1x_device *device, 45 48 struct device_node *np) ··· 65 62 66 63 /** 67 64 * host1x_subdev_del() - remove subdevice 65 + * @subdev: subdevice to remove 68 66 */ 69 67 static void host1x_subdev_del(struct host1x_subdev *subdev) 70 68 { ··· 76 72 77 73 /** 78 74 * host1x_device_parse_dt() - scan device tree and add matching subdevices 75 + * @device: host1x logical device 76 + * @driver: host1x driver 79 77 */ 80 78 static int host1x_device_parse_dt(struct host1x_device *device, 81 79 struct host1x_driver *driver) ··· 172 166 mutex_unlock(&device->subdevs_lock); 173 167 } 174 168 169 + /** 170 + * host1x_device_init() - initialize a host1x logical device 171 + * @device: host1x logical device 172 + * 173 + * The driver for the host1x logical device can call this during execution of 174 + * its &host1x_driver.probe implementation to initialize each of its clients. 175 + * The client drivers access the subsystem specific driver data using the 176 + * &host1x_client.parent field and driver data associated with it (usually by 177 + * calling dev_get_drvdata()). 178 + */ 175 179 int host1x_device_init(struct host1x_device *device) 176 180 { 177 181 struct host1x_client *client; ··· 208 192 } 209 193 EXPORT_SYMBOL(host1x_device_init); 210 194 195 + /** 196 + * host1x_device_exit() - uninitialize host1x logical device 197 + * @device: host1x logical device 198 + * 199 + * When the driver for a host1x logical device is unloaded, it can call this 200 + * function to tear down each of its clients. Typically this is done after a 201 + * subsystem-specific data structure is removed and the functionality can no 202 + * longer be used. 203 + */ 211 204 int host1x_device_exit(struct host1x_device *device) 212 205 { 213 206 struct host1x_client *client; ··· 471 446 mutex_unlock(&host1x->devices_lock); 472 447 } 473 448 449 + /** 450 + * host1x_register() - register a host1x controller 451 + * @host1x: host1x controller 452 + * 453 + * The host1x controller driver uses this to register a host1x controller with 454 + * the infrastructure. Note that all Tegra SoC generations have only ever come 455 + * with a single host1x instance, so this function is somewhat academic. 456 + */ 474 457 int host1x_register(struct host1x *host1x) 475 458 { 476 459 struct host1x_driver *driver; ··· 497 464 return 0; 498 465 } 499 466 467 + /** 468 + * host1x_unregister() - unregister a host1x controller 469 + * @host1x: host1x controller 470 + * 471 + * The host1x controller driver uses this to remove a host1x controller from 472 + * the infrastructure. 473 + */ 500 474 int host1x_unregister(struct host1x *host1x) 501 475 { 502 476 struct host1x_driver *driver; ··· 553 513 driver->shutdown(device); 554 514 } 555 515 516 + /** 517 + * host1x_driver_register_full() - register a host1x driver 518 + * @driver: host1x driver 519 + * @owner: owner module 520 + * 521 + * Drivers for host1x logical devices call this function to register a driver 522 + * with the infrastructure. Note that since these drive logical devices, the 523 + * registration of the driver actually triggers tho logical device creation. 524 + * A logical device will be created for each host1x instance. 525 + */ 556 526 int host1x_driver_register_full(struct host1x_driver *driver, 557 527 struct module *owner) 558 528 { ··· 591 541 } 592 542 EXPORT_SYMBOL(host1x_driver_register_full); 593 543 544 + /** 545 + * host1x_driver_unregister() - unregister a host1x driver 546 + * @driver: host1x driver 547 + * 548 + * Unbinds the driver from each of the host1x logical devices that it is 549 + * bound to, effectively removing the subsystem devices that they represent. 550 + */ 594 551 void host1x_driver_unregister(struct host1x_driver *driver) 595 552 { 596 553 driver_unregister(&driver->driver); ··· 608 551 } 609 552 EXPORT_SYMBOL(host1x_driver_unregister); 610 553 554 + /** 555 + * host1x_client_register() - register a host1x client 556 + * @client: host1x client 557 + * 558 + * Registers a host1x client with each host1x controller instance. Note that 559 + * each client will only match their parent host1x controller and will only be 560 + * associated with that instance. Once all clients have been registered with 561 + * their parent host1x controller, the infrastructure will set up the logical 562 + * device and call host1x_device_init(), which will in turn call each client's 563 + * &host1x_client_ops.init implementation. 564 + */ 611 565 int host1x_client_register(struct host1x_client *client) 612 566 { 613 567 struct host1x *host1x; ··· 644 576 } 645 577 EXPORT_SYMBOL(host1x_client_register); 646 578 579 + /** 580 + * host1x_client_unregister() - unregister a host1x client 581 + * @client: host1x client 582 + * 583 + * Removes a host1x client from its host1x controller instance. If a logical 584 + * device has already been initialized, it will be torn down. 585 + */ 647 586 int host1x_client_unregister(struct host1x_client *client) 648 587 { 649 588 struct host1x_client *c;
+70 -11
drivers/gpu/host1x/syncpt.c
··· 99 99 return NULL; 100 100 } 101 101 102 + /** 103 + * host1x_syncpt_id() - retrieve syncpoint ID 104 + * @sp: host1x syncpoint 105 + * 106 + * Given a pointer to a struct host1x_syncpt, retrieves its ID. This ID is 107 + * often used as a value to program into registers that control how hardware 108 + * blocks interact with syncpoints. 109 + */ 102 110 u32 host1x_syncpt_id(struct host1x_syncpt *sp) 103 111 { 104 112 return sp->id; 105 113 } 106 114 EXPORT_SYMBOL(host1x_syncpt_id); 107 115 108 - /* 109 - * Updates the value sent to hardware. 116 + /** 117 + * host1x_syncpt_incr_max() - update the value sent to hardware 118 + * @sp: host1x syncpoint 119 + * @incrs: number of increments 110 120 */ 111 121 u32 host1x_syncpt_incr_max(struct host1x_syncpt *sp, u32 incrs) 112 122 { ··· 185 175 return sp->base_val; 186 176 } 187 177 188 - /* 189 - * Increment syncpoint value from cpu, updating cache 178 + /** 179 + * host1x_syncpt_incr() - increment syncpoint value from CPU, updating cache 180 + * @sp: host1x syncpoint 190 181 */ 191 182 int host1x_syncpt_incr(struct host1x_syncpt *sp) 192 183 { ··· 206 195 return host1x_syncpt_is_expired(sp, thresh); 207 196 } 208 197 209 - /* 210 - * Main entrypoint for syncpoint value waits. 198 + /** 199 + * host1x_syncpt_wait() - wait for a syncpoint to reach a given value 200 + * @sp: host1x syncpoint 201 + * @thresh: threshold 202 + * @timeout: maximum time to wait for the syncpoint to reach the given value 203 + * @value: return location for the syncpoint value 211 204 */ 212 205 int host1x_syncpt_wait(struct host1x_syncpt *sp, u32 thresh, long timeout, 213 206 u32 *value) ··· 417 402 return 0; 418 403 } 419 404 405 + /** 406 + * host1x_syncpt_request() - request a syncpoint 407 + * @dev: device requesting the syncpoint 408 + * @flags: flags 409 + * 410 + * host1x client drivers can use this function to allocate a syncpoint for 411 + * subsequent use. A syncpoint returned by this function will be reserved for 412 + * use by the client exclusively. When no longer using a syncpoint, a host1x 413 + * client driver needs to release it using host1x_syncpt_free(). 414 + */ 420 415 struct host1x_syncpt *host1x_syncpt_request(struct device *dev, 421 416 unsigned long flags) 422 417 { ··· 436 411 } 437 412 EXPORT_SYMBOL(host1x_syncpt_request); 438 413 414 + /** 415 + * host1x_syncpt_free() - free a requested syncpoint 416 + * @sp: host1x syncpoint 417 + * 418 + * Release a syncpoint previously allocated using host1x_syncpt_request(). A 419 + * host1x client driver should call this when the syncpoint is no longer in 420 + * use. Note that client drivers must ensure that the syncpoint doesn't remain 421 + * under the control of hardware after calling this function, otherwise two 422 + * clients may end up trying to access the same syncpoint concurrently. 423 + */ 439 424 void host1x_syncpt_free(struct host1x_syncpt *sp) 440 425 { 441 426 if (!sp) ··· 473 438 kfree(sp->name); 474 439 } 475 440 476 - /* 477 - * Read max. It indicates how many operations there are in queue, either in 478 - * channel or in a software thread. 441 + /** 442 + * host1x_syncpt_read_max() - read maximum syncpoint value 443 + * @sp: host1x syncpoint 444 + * 445 + * The maximum syncpoint value indicates how many operations there are in 446 + * queue, either in channel or in a software thread. 479 447 */ 480 448 u32 host1x_syncpt_read_max(struct host1x_syncpt *sp) 481 449 { ··· 488 450 } 489 451 EXPORT_SYMBOL(host1x_syncpt_read_max); 490 452 491 - /* 492 - * Read min, which is a shadow of the current sync point value in hardware. 453 + /** 454 + * host1x_syncpt_read_min() - read minimum syncpoint value 455 + * @sp: host1x syncpoint 456 + * 457 + * The minimum syncpoint value is a shadow of the current sync point value in 458 + * hardware. 493 459 */ 494 460 u32 host1x_syncpt_read_min(struct host1x_syncpt *sp) 495 461 { ··· 503 461 } 504 462 EXPORT_SYMBOL(host1x_syncpt_read_min); 505 463 464 + /** 465 + * host1x_syncpt_read() - read the current syncpoint value 466 + * @sp: host1x syncpoint 467 + */ 506 468 u32 host1x_syncpt_read(struct host1x_syncpt *sp) 507 469 { 508 470 return host1x_syncpt_load(sp); ··· 528 482 return host->info->nb_mlocks; 529 483 } 530 484 485 + /** 486 + * host1x_syncpt_get() - obtain a syncpoint by ID 487 + * @host: host1x controller 488 + * @id: syncpoint ID 489 + */ 531 490 struct host1x_syncpt *host1x_syncpt_get(struct host1x *host, unsigned int id) 532 491 { 533 492 if (id >= host->info->nb_pts) ··· 542 491 } 543 492 EXPORT_SYMBOL(host1x_syncpt_get); 544 493 494 + /** 495 + * host1x_syncpt_get_base() - obtain the wait base associated with a syncpoint 496 + * @sp: host1x syncpoint 497 + */ 545 498 struct host1x_syncpt_base *host1x_syncpt_get_base(struct host1x_syncpt *sp) 546 499 { 547 500 return sp ? sp->base : NULL; 548 501 } 549 502 EXPORT_SYMBOL(host1x_syncpt_get_base); 550 503 504 + /** 505 + * host1x_syncpt_base_id() - retrieve the ID of a syncpoint wait base 506 + * @base: host1x syncpoint wait base 507 + */ 551 508 u32 host1x_syncpt_base_id(struct host1x_syncpt_base *base) 552 509 { 553 510 return base->id;
+25
include/linux/host1x.h
··· 32 32 33 33 struct host1x_client; 34 34 35 + /** 36 + * struct host1x_client_ops - host1x client operations 37 + * @init: host1x client initialization code 38 + * @exit: host1x client tear down code 39 + */ 35 40 struct host1x_client_ops { 36 41 int (*init)(struct host1x_client *client); 37 42 int (*exit)(struct host1x_client *client); 38 43 }; 39 44 45 + /** 46 + * struct host1x_client - host1x client structure 47 + * @list: list node for the host1x client 48 + * @parent: pointer to struct device representing the host1x controller 49 + * @dev: pointer to struct device backing this host1x client 50 + * @ops: host1x client operations 51 + * @class: host1x class represented by this client 52 + * @channel: host1x channel associated with this client 53 + * @syncpts: array of syncpoints requested for this client 54 + * @num_syncpts: number of syncpoints requested for this client 55 + */ 40 56 struct host1x_client { 41 57 struct list_head list; 42 58 struct device *parent; ··· 267 251 268 252 struct host1x_device; 269 253 254 + /** 255 + * struct host1x_driver - host1x logical device driver 256 + * @driver: core driver 257 + * @subdevs: table of OF device IDs matching subdevices for this driver 258 + * @list: list node for the driver 259 + * @probe: called when the host1x logical device is probed 260 + * @remove: called when the host1x logical device is removed 261 + * @shutdown: called when the host1x logical device is shut down 262 + */ 270 263 struct host1x_driver { 271 264 struct device_driver driver; 272 265