openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Thierry Reding 2017-04-10 12:27:01 +02:00
parent 2ea659a9ef
commit 466749f13e
3 changed files with 170 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
drivers/gpu/host1x/bus.c
View File

@ -40,6 +40,9 @@ struct host1x_subdev {
/**
* 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,
struct device_node *np)
@ -62,6 +65,7 @@ static int host1x_subdev_add(struct host1x_device *device,
/**
* host1x_subdev_del() - remove subdevice
* @subdev: subdevice to remove
*/
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
* @device: host1x logical device
* @driver: host1x driver
*/
static int host1x_device_parse_dt(struct host1x_device *device,
struct host1x_driver *driver)
@ -166,6 +172,16 @@ static void host1x_subdev_unregister(struct host1x_device *device,
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)
{
struct host1x_client *client;
@ -192,6 +208,15 @@ int host1x_device_init(struct host1x_device *device)
}
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)
{
struct host1x_client *client;
@ -446,6 +471,14 @@ static void host1x_detach_driver(struct host1x *host1x,
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)
{
struct host1x_driver *driver;
@ -464,6 +497,13 @@ int host1x_register(struct host1x *host1x)
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)
{
struct host1x_driver *driver;
@ -513,6 +553,16 @@ static void host1x_device_shutdown(struct device *dev)
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,
struct module *owner)
{
@ -541,6 +591,13 @@ int host1x_driver_register_full(struct host1x_driver *driver,
}
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)
{
driver_unregister(&driver->driver);
@ -551,6 +608,17 @@ void host1x_driver_unregister(struct host1x_driver *driver)
}
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)
{
struct host1x *host1x;
@ -576,6 +644,13 @@ int host1x_client_register(struct host1x_client *client)
}
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)
{
struct host1x_client *c;

81
drivers/gpu/host1x/syncpt.c
View File

@ -99,14 +99,24 @@ static struct host1x_syncpt *host1x_syncpt_alloc(struct host1x *host,
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)
{
return sp->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)
{
@ -175,8 +185,9 @@ u32 host1x_syncpt_load_wait_base(struct host1x_syncpt *sp)
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)
{
@ -195,8 +206,12 @@ static bool syncpt_load_min_is_expired(struct host1x_syncpt *sp, u32 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,
u32 *value)
@ -402,6 +417,16 @@ int host1x_syncpt_init(struct host1x *host)
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,
unsigned long flags)
{
@ -411,6 +436,16 @@ struct host1x_syncpt *host1x_syncpt_request(struct device *dev,
}
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)
{
if (!sp)
@ -438,9 +473,12 @@ void host1x_syncpt_deinit(struct host1x *host)
kfree(sp->name);
}
/*
* Read max. It indicates how many operations there are in queue, either in
* channel or in a software thread.
/**
* host1x_syncpt_read_max() - read maximum syncpoint value
* @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)
{
@ -450,8 +488,12 @@ u32 host1x_syncpt_read_max(struct host1x_syncpt *sp)
}
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)
{
@ -461,6 +503,10 @@ u32 host1x_syncpt_read_min(struct host1x_syncpt *sp)
}
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)
{
return host1x_syncpt_load(sp);
@ -482,6 +528,11 @@ unsigned int host1x_syncpt_nb_mlocks(struct host1x *host)
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)
{
if (id >= host->info->nb_pts)
@ -491,12 +542,20 @@ struct host1x_syncpt *host1x_syncpt_get(struct host1x *host, unsigned int id)
}
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)
{
return sp ? sp->base : NULL;
}
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)
{
return base->id;

25
include/linux/host1x.h
View File

@ -32,11 +32,27 @@ enum host1x_class {
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 {
int (*init)(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 list_head list;
struct device *parent;
@ -251,6 +267,15 @@ void host1x_job_unpin(struct host1x_job *job);
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 device_driver driver;