Commit 466749f1 authored by Thierry Reding's avatar Thierry Reding

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: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: default avatarThierry Reding <treding@nvidia.com>
parent 2ea659a9
...@@ -40,6 +40,9 @@ struct host1x_subdev { ...@@ -40,6 +40,9 @@ struct host1x_subdev {
/** /**
* host1x_subdev_add() - add a new subdevice with an associated device node * host1x_subdev_add() - add a new subdevice with an associated device node
* @device: host1x device to add the subdevice to
* @driver: host1x driver
* @np: device node
*/ */
static int host1x_subdev_add(struct host1x_device *device, static int host1x_subdev_add(struct host1x_device *device,
struct device_node *np) struct device_node *np)
...@@ -62,6 +65,7 @@ static int host1x_subdev_add(struct host1x_device *device, ...@@ -62,6 +65,7 @@ static int host1x_subdev_add(struct host1x_device *device,
/** /**
* host1x_subdev_del() - remove subdevice * host1x_subdev_del() - remove subdevice
* @subdev: subdevice to remove
*/ */
static void host1x_subdev_del(struct host1x_subdev *subdev) static void host1x_subdev_del(struct host1x_subdev *subdev)
{ {
...@@ -72,6 +76,8 @@ static void host1x_subdev_del(struct host1x_subdev *subdev) ...@@ -72,6 +76,8 @@ static void host1x_subdev_del(struct host1x_subdev *subdev)
/** /**
* host1x_device_parse_dt() - scan device tree and add matching subdevices * host1x_device_parse_dt() - scan device tree and add matching subdevices
* @device: host1x logical device
* @driver: host1x driver
*/ */
static int host1x_device_parse_dt(struct host1x_device *device, static int host1x_device_parse_dt(struct host1x_device *device,
struct host1x_driver *driver) struct host1x_driver *driver)
...@@ -166,6 +172,16 @@ static void host1x_subdev_unregister(struct host1x_device *device, ...@@ -166,6 +172,16 @@ static void host1x_subdev_unregister(struct host1x_device *device,
mutex_unlock(&device->subdevs_lock); mutex_unlock(&device->subdevs_lock);
} }
/**
* host1x_device_init() - initialize a host1x logical device
* @device: host1x logical device
*
* The driver for the host1x logical device can call this during execution of
* its &host1x_driver.probe implementation to initialize each of its clients.
* The client drivers access the subsystem specific driver data using the
* &host1x_client.parent field and driver data associated with it (usually by
* calling dev_get_drvdata()).
*/
int host1x_device_init(struct host1x_device *device) int host1x_device_init(struct host1x_device *device)
{ {
struct host1x_client *client; struct host1x_client *client;
...@@ -192,6 +208,15 @@ int host1x_device_init(struct host1x_device *device) ...@@ -192,6 +208,15 @@ int host1x_device_init(struct host1x_device *device)
} }
EXPORT_SYMBOL(host1x_device_init); EXPORT_SYMBOL(host1x_device_init);
/**
* host1x_device_exit() - uninitialize host1x logical device
* @device: host1x logical device
*
* When the driver for a host1x logical device is unloaded, it can call this
* function to tear down each of its clients. Typically this is done after a
* subsystem-specific data structure is removed and the functionality can no
* longer be used.
*/
int host1x_device_exit(struct host1x_device *device) int host1x_device_exit(struct host1x_device *device)
{ {
struct host1x_client *client; struct host1x_client *client;
...@@ -446,6 +471,14 @@ static void host1x_detach_driver(struct host1x *host1x, ...@@ -446,6 +471,14 @@ static void host1x_detach_driver(struct host1x *host1x,
mutex_unlock(&host1x->devices_lock); mutex_unlock(&host1x->devices_lock);
} }
/**
* host1x_register() - register a host1x controller
* @host1x: host1x controller
*
* The host1x controller driver uses this to register a host1x controller with
* the infrastructure. Note that all Tegra SoC generations have only ever come
* with a single host1x instance, so this function is somewhat academic.
*/
int host1x_register(struct host1x *host1x) int host1x_register(struct host1x *host1x)
{ {
struct host1x_driver *driver; struct host1x_driver *driver;
...@@ -464,6 +497,13 @@ int host1x_register(struct host1x *host1x) ...@@ -464,6 +497,13 @@ int host1x_register(struct host1x *host1x)
return 0; return 0;
} }
/**
* host1x_unregister() - unregister a host1x controller
* @host1x: host1x controller
*
* The host1x controller driver uses this to remove a host1x controller from
* the infrastructure.
*/
int host1x_unregister(struct host1x *host1x) int host1x_unregister(struct host1x *host1x)
{ {
struct host1x_driver *driver; struct host1x_driver *driver;
...@@ -513,6 +553,16 @@ static void host1x_device_shutdown(struct device *dev) ...@@ -513,6 +553,16 @@ static void host1x_device_shutdown(struct device *dev)
driver->shutdown(device); driver->shutdown(device);
} }
/**
* host1x_driver_register_full() - register a host1x driver
* @driver: host1x driver
* @owner: owner module
*
* Drivers for host1x logical devices call this function to register a driver
* with the infrastructure. Note that since these drive logical devices, the
* registration of the driver actually triggers tho logical device creation.
* A logical device will be created for each host1x instance.
*/
int host1x_driver_register_full(struct host1x_driver *driver, int host1x_driver_register_full(struct host1x_driver *driver,
struct module *owner) struct module *owner)
{ {
...@@ -541,6 +591,13 @@ int host1x_driver_register_full(struct host1x_driver *driver, ...@@ -541,6 +591,13 @@ int host1x_driver_register_full(struct host1x_driver *driver,
} }
EXPORT_SYMBOL(host1x_driver_register_full); EXPORT_SYMBOL(host1x_driver_register_full);
/**
* host1x_driver_unregister() - unregister a host1x driver
* @driver: host1x driver
*
* Unbinds the driver from each of the host1x logical devices that it is
* bound to, effectively removing the subsystem devices that they represent.
*/
void host1x_driver_unregister(struct host1x_driver *driver) void host1x_driver_unregister(struct host1x_driver *driver)
{ {
driver_unregister(&driver->driver); driver_unregister(&driver->driver);
...@@ -551,6 +608,17 @@ void host1x_driver_unregister(struct host1x_driver *driver) ...@@ -551,6 +608,17 @@ void host1x_driver_unregister(struct host1x_driver *driver)
} }
EXPORT_SYMBOL(host1x_driver_unregister); EXPORT_SYMBOL(host1x_driver_unregister);
/**
* host1x_client_register() - register a host1x client
* @client: host1x client
*
* Registers a host1x client with each host1x controller instance. Note that
* each client will only match their parent host1x controller and will only be
* associated with that instance. Once all clients have been registered with
* their parent host1x controller, the infrastructure will set up the logical
* device and call host1x_device_init(), which will in turn call each client's
* &host1x_client_ops.init implementation.
*/
int host1x_client_register(struct host1x_client *client) int host1x_client_register(struct host1x_client *client)
{ {
struct host1x *host1x; struct host1x *host1x;
...@@ -576,6 +644,13 @@ int host1x_client_register(struct host1x_client *client) ...@@ -576,6 +644,13 @@ int host1x_client_register(struct host1x_client *client)
} }
EXPORT_SYMBOL(host1x_client_register); EXPORT_SYMBOL(host1x_client_register);
/**
* host1x_client_unregister() - unregister a host1x client
* @client: host1x client
*
* Removes a host1x client from its host1x controller instance. If a logical
* device has already been initialized, it will be torn down.
*/
int host1x_client_unregister(struct host1x_client *client) int host1x_client_unregister(struct host1x_client *client)
{ {
struct host1x_client *c; struct host1x_client *c;
......
...@@ -99,14 +99,24 @@ static struct host1x_syncpt *host1x_syncpt_alloc(struct host1x *host, ...@@ -99,14 +99,24 @@ static struct host1x_syncpt *host1x_syncpt_alloc(struct host1x *host,
return NULL; return NULL;
} }
/**
* host1x_syncpt_id() - retrieve syncpoint ID
* @sp: host1x syncpoint
*
* Given a pointer to a struct host1x_syncpt, retrieves its ID. This ID is
* often used as a value to program into registers that control how hardware
* blocks interact with syncpoints.
*/
u32 host1x_syncpt_id(struct host1x_syncpt *sp) u32 host1x_syncpt_id(struct host1x_syncpt *sp)
{ {
return sp->id; return sp->id;
} }
EXPORT_SYMBOL(host1x_syncpt_id); EXPORT_SYMBOL(host1x_syncpt_id);
/* /**
* Updates the value sent to hardware. * host1x_syncpt_incr_max() - update the value sent to hardware
* @sp: host1x syncpoint
* @incrs: number of increments
*/ */
u32 host1x_syncpt_incr_max(struct host1x_syncpt *sp, u32 incrs) u32 host1x_syncpt_incr_max(struct host1x_syncpt *sp, u32 incrs)
{ {
...@@ -175,8 +185,9 @@ u32 host1x_syncpt_load_wait_base(struct host1x_syncpt *sp) ...@@ -175,8 +185,9 @@ u32 host1x_syncpt_load_wait_base(struct host1x_syncpt *sp)
return sp->base_val; return sp->base_val;
} }
/* /**
* Increment syncpoint value from cpu, updating cache * host1x_syncpt_incr() - increment syncpoint value from CPU, updating cache
* @sp: host1x syncpoint
*/ */
int host1x_syncpt_incr(struct host1x_syncpt *sp) int host1x_syncpt_incr(struct host1x_syncpt *sp)
{ {
...@@ -195,8 +206,12 @@ static bool syncpt_load_min_is_expired(struct host1x_syncpt *sp, u32 thresh) ...@@ -195,8 +206,12 @@ static bool syncpt_load_min_is_expired(struct host1x_syncpt *sp, u32 thresh)
return host1x_syncpt_is_expired(sp, thresh); return host1x_syncpt_is_expired(sp, thresh);
} }
/* /**
* Main entrypoint for syncpoint value waits. * host1x_syncpt_wait() - wait for a syncpoint to reach a given value
* @sp: host1x syncpoint
* @thresh: threshold
* @timeout: maximum time to wait for the syncpoint to reach the given value
* @value: return location for the syncpoint value
*/ */
int host1x_syncpt_wait(struct host1x_syncpt *sp, u32 thresh, long timeout, int host1x_syncpt_wait(struct host1x_syncpt *sp, u32 thresh, long timeout,
u32 *value) u32 *value)
...@@ -402,6 +417,16 @@ int host1x_syncpt_init(struct host1x *host) ...@@ -402,6 +417,16 @@ int host1x_syncpt_init(struct host1x *host)
return 0; return 0;
} }
/**
* host1x_syncpt_request() - request a syncpoint
* @dev: device requesting the syncpoint
* @flags: flags
*
* host1x client drivers can use this function to allocate a syncpoint for
* subsequent use. A syncpoint returned by this function will be reserved for
* use by the client exclusively. When no longer using a syncpoint, a host1x
* client driver needs to release it using host1x_syncpt_free().
*/
struct host1x_syncpt *host1x_syncpt_request(struct device *dev, struct host1x_syncpt *host1x_syncpt_request(struct device *dev,
unsigned long flags) unsigned long flags)
{ {
...@@ -411,6 +436,16 @@ struct host1x_syncpt *host1x_syncpt_request(struct device *dev, ...@@ -411,6 +436,16 @@ struct host1x_syncpt *host1x_syncpt_request(struct device *dev,
} }
EXPORT_SYMBOL(host1x_syncpt_request); EXPORT_SYMBOL(host1x_syncpt_request);
/**
* host1x_syncpt_free() - free a requested syncpoint
* @sp: host1x syncpoint
*
* Release a syncpoint previously allocated using host1x_syncpt_request(). A
* host1x client driver should call this when the syncpoint is no longer in
* use. Note that client drivers must ensure that the syncpoint doesn't remain
* under the control of hardware after calling this function, otherwise two
* clients may end up trying to access the same syncpoint concurrently.
*/
void host1x_syncpt_free(struct host1x_syncpt *sp) void host1x_syncpt_free(struct host1x_syncpt *sp)
{ {
if (!sp) if (!sp)
...@@ -438,9 +473,12 @@ void host1x_syncpt_deinit(struct host1x *host) ...@@ -438,9 +473,12 @@ void host1x_syncpt_deinit(struct host1x *host)
kfree(sp->name); kfree(sp->name);
} }
/* /**
* Read max. It indicates how many operations there are in queue, either in * host1x_syncpt_read_max() - read maximum syncpoint value
* channel or in a software thread. * @sp: host1x syncpoint
*
* The maximum syncpoint value indicates how many operations there are in
* queue, either in channel or in a software thread.
*/ */
u32 host1x_syncpt_read_max(struct host1x_syncpt *sp) u32 host1x_syncpt_read_max(struct host1x_syncpt *sp)
{ {
...@@ -450,8 +488,12 @@ u32 host1x_syncpt_read_max(struct host1x_syncpt *sp) ...@@ -450,8 +488,12 @@ u32 host1x_syncpt_read_max(struct host1x_syncpt *sp)
} }
EXPORT_SYMBOL(host1x_syncpt_read_max); EXPORT_SYMBOL(host1x_syncpt_read_max);
/* /**
* Read min, which is a shadow of the current sync point value in hardware. * host1x_syncpt_read_min() - read minimum syncpoint value
* @sp: host1x syncpoint
*
* The minimum syncpoint value is a shadow of the current sync point value in
* hardware.
*/ */
u32 host1x_syncpt_read_min(struct host1x_syncpt *sp) u32 host1x_syncpt_read_min(struct host1x_syncpt *sp)
{ {
...@@ -461,6 +503,10 @@ u32 host1x_syncpt_read_min(struct host1x_syncpt *sp) ...@@ -461,6 +503,10 @@ u32 host1x_syncpt_read_min(struct host1x_syncpt *sp)
} }
EXPORT_SYMBOL(host1x_syncpt_read_min); EXPORT_SYMBOL(host1x_syncpt_read_min);
/**
* host1x_syncpt_read() - read the current syncpoint value
* @sp: host1x syncpoint
*/
u32 host1x_syncpt_read(struct host1x_syncpt *sp) u32 host1x_syncpt_read(struct host1x_syncpt *sp)
{ {
return host1x_syncpt_load(sp); return host1x_syncpt_load(sp);
...@@ -482,6 +528,11 @@ unsigned int host1x_syncpt_nb_mlocks(struct host1x *host) ...@@ -482,6 +528,11 @@ unsigned int host1x_syncpt_nb_mlocks(struct host1x *host)
return host->info->nb_mlocks; return host->info->nb_mlocks;
} }
/**
* host1x_syncpt_get() - obtain a syncpoint by ID
* @host: host1x controller
* @id: syncpoint ID
*/
struct host1x_syncpt *host1x_syncpt_get(struct host1x *host, unsigned int id) struct host1x_syncpt *host1x_syncpt_get(struct host1x *host, unsigned int id)
{ {
if (id >= host->info->nb_pts) if (id >= host->info->nb_pts)
...@@ -491,12 +542,20 @@ struct host1x_syncpt *host1x_syncpt_get(struct host1x *host, unsigned int id) ...@@ -491,12 +542,20 @@ struct host1x_syncpt *host1x_syncpt_get(struct host1x *host, unsigned int id)
} }
EXPORT_SYMBOL(host1x_syncpt_get); EXPORT_SYMBOL(host1x_syncpt_get);
/**
* host1x_syncpt_get_base() - obtain the wait base associated with a syncpoint
* @sp: host1x syncpoint
*/
struct host1x_syncpt_base *host1x_syncpt_get_base(struct host1x_syncpt *sp) struct host1x_syncpt_base *host1x_syncpt_get_base(struct host1x_syncpt *sp)
{ {
return sp ? sp->base : NULL; return sp ? sp->base : NULL;
} }
EXPORT_SYMBOL(host1x_syncpt_get_base); EXPORT_SYMBOL(host1x_syncpt_get_base);
/**
* host1x_syncpt_base_id() - retrieve the ID of a syncpoint wait base
* @base: host1x syncpoint wait base
*/
u32 host1x_syncpt_base_id(struct host1x_syncpt_base *base) u32 host1x_syncpt_base_id(struct host1x_syncpt_base *base)
{ {
return base->id; return base->id;
......
...@@ -32,11 +32,27 @@ enum host1x_class { ...@@ -32,11 +32,27 @@ enum host1x_class {
struct host1x_client; struct host1x_client;
/**
* struct host1x_client_ops - host1x client operations
* @init: host1x client initialization code
* @exit: host1x client tear down code
*/
struct host1x_client_ops { struct host1x_client_ops {
int (*init)(struct host1x_client *client); int (*init)(struct host1x_client *client);
int (*exit)(struct host1x_client *client); int (*exit)(struct host1x_client *client);
}; };
/**
* struct host1x_client - host1x client structure
* @list: list node for the host1x client
* @parent: pointer to struct device representing the host1x controller
* @dev: pointer to struct device backing this host1x client
* @ops: host1x client operations
* @class: host1x class represented by this client
* @channel: host1x channel associated with this client
* @syncpts: array of syncpoints requested for this client
* @num_syncpts: number of syncpoints requested for this client
*/
struct host1x_client { struct host1x_client {
struct list_head list; struct list_head list;
struct device *parent; struct device *parent;
...@@ -251,6 +267,15 @@ void host1x_job_unpin(struct host1x_job *job); ...@@ -251,6 +267,15 @@ void host1x_job_unpin(struct host1x_job *job);
struct host1x_device; struct host1x_device;
/**
* struct host1x_driver - host1x logical device driver
* @driver: core driver
* @subdevs: table of OF device IDs matching subdevices for this driver
* @list: list node for the driver
* @probe: called when the host1x logical device is probed
* @remove: called when the host1x logical device is removed
* @shutdown: called when the host1x logical device is shut down
*/
struct host1x_driver { struct host1x_driver {
struct device_driver driver; struct device_driver driver;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment