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>hifive-unleashed-5.1
Thierry Reding
parent
2ea659a9ef
commit
466749f13e
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -99,14 +99,24 @@ unlock:
|
|||
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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue