[PATCH 13/19] drm/doc: Add PRIME function references
Daniel Vetter
daniel at ffwll.ch
Thu Jan 23 01:58:43 PST 2014
On Thu, Jan 23, 2014 at 10:45:09AM +0100, David Herrmann wrote:
> Hi
>
> On Thu, Jan 23, 2014 at 10:37 AM, Daniel Vetter <daniel at ffwll.ch> wrote:
> > On Thu, Jan 23, 2014 at 10:28:42AM +0100, David Herrmann wrote:
> >> Hi
> >>
> >> On Thu, Jan 23, 2014 at 9:52 AM, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> >> > For giant hilarity the DocBook reference overview is only generated
> >> > when in a level 2 section, not in a level 3 section. So we need to
> >> > move this up a bit as a side-by-side section to the main PRIME
> >> > documentation.
> >> >
> >> > Whatever.
> >>
> >> I tried digging through scripts/kernel-doc but.. ugh.. it's perl! No
> >> idea how to fix that. But sect2 seems fine as the whole section is
> >> PRIME-related.
> >
> > Well we have two sect2 now: One for the PRIME overview, the other for the
> > reference documenation. I've done the same split for drm_mm btw. If we
> > want to fix this I think this is actually in the DocBook stylesheet, not
> > in the kerneldoc thing. I've checked the intermediate xml and all the
> > function references are there, they even get generated as html files and
> > you can xref them from within the docbook. There's just no section topic
> > for sect3 levels, so you never see a link to that separate page without an
> > explicit reference.
>
> Hm, why not this:
>
> </sect3>
> + <title>PRIME Function References</title>
> +!Edrivers/gpu/drm/drm_prime.c
> + </sect2>
>
> So you just put it at the end of the prime-sect2?
>
> The kernel-doc script at least has "<sect2>" hardcoded, but yeah, no
> idea where to fix that. So I think this is fine.
The only links generated are for the section toc, which is always at the
top of the section. So if we combine it you'll have a pile of function
references + the overview links for the subsections. Loosk rather bad imo.
-Daniel
>
> Thanks
> David
>
> >
> >>
> >> Thanks
> >> David
> >>
> >> >
> >> > To have a complete set of references add the missing kerneldoc for all
> >> > functions exported to modules with the exception of the file private
> >> > init/destry functions - drivers have no business calling those, so
> >> > let's just drop the EXPORT_SYMBOL instead.
> >> >
> >> > Also reflow the function parameters to align correctly and break at 80
> >> > chars - my OCD couldn't stand them while writing the kerneldoc ;-)
> >> >
> >> > Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> >> > ---
> >> > Documentation/DocBook/drm.tmpl | 6 ++-
> >> > drivers/gpu/drm/drm_prime.c | 110 +++++++++++++++++++++++++++++++++--------
> >> > 2 files changed, 94 insertions(+), 22 deletions(-)
> >> >
> >> > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> >> > index 0cc1d85d04de..07abe52b1176 100644
> >> > --- a/Documentation/DocBook/drm.tmpl
> >> > +++ b/Documentation/DocBook/drm.tmpl
> >> > @@ -898,10 +898,14 @@ struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
> >> > </para>
> >> > </sect3>
> >> > <sect3>
> >> > - <title>PRIME Helper Functions Reference</title>
> >> > + <title>PRIME Helper Functions</title>
> >> > !Pdrivers/gpu/drm/drm_prime.c PRIME Helpers
> >> > </sect3>
> >> > </sect2>
> >> > + <sect2>
> >> > + <title>PRIME Function References</title>
> >> > +!Edrivers/gpu/drm/drm_prime.c
> >> > + </sect2>
> >> > </sect1>
> >> >
> >> > <!-- Internals: mode setting -->
> >> > diff --git a/drivers/gpu/drm/drm_prime.c b/drivers/gpu/drm/drm_prime.c
> >> > index 56805c39c906..f1437b6c8dbf 100644
> >> > --- a/drivers/gpu/drm/drm_prime.c
> >> > +++ b/drivers/gpu/drm/drm_prime.c
> >> > @@ -68,7 +68,8 @@ struct drm_prime_attachment {
> >> > enum dma_data_direction dir;
> >> > };
> >> >
> >> > -static int drm_prime_add_buf_handle(struct drm_prime_file_private *prime_fpriv, struct dma_buf *dma_buf, uint32_t handle)
> >> > +static int drm_prime_add_buf_handle(struct drm_prime_file_private *prime_fpriv,
> >> > + struct dma_buf *dma_buf, uint32_t handle)
> >> > {
> >> > struct drm_prime_member *member;
> >> >
> >> > @@ -174,7 +175,7 @@ void drm_prime_remove_buf_handle_locked(struct drm_prime_file_private *prime_fpr
> >> > }
> >> >
> >> > static struct sg_table *drm_gem_map_dma_buf(struct dma_buf_attachment *attach,
> >> > - enum dma_data_direction dir)
> >> > + enum dma_data_direction dir)
> >> > {
> >> > struct drm_prime_attachment *prime_attach = attach->priv;
> >> > struct drm_gem_object *obj = attach->dmabuf->priv;
> >> > @@ -211,11 +212,19 @@ static struct sg_table *drm_gem_map_dma_buf(struct dma_buf_attachment *attach,
> >> > }
> >> >
> >> > static void drm_gem_unmap_dma_buf(struct dma_buf_attachment *attach,
> >> > - struct sg_table *sgt, enum dma_data_direction dir)
> >> > + struct sg_table *sgt,
> >> > + enum dma_data_direction dir)
> >> > {
> >> > /* nothing to be done here */
> >> > }
> >> >
> >> > +/**
> >> > + * drm_gem_dmabuf_release - dma_buf release implementation for GEM
> >> > + * @dma_buf: buffer to be released
> >> > + *
> >> > + * Generic release function for dma_bufs exported as PRIME buffers. GEM drivers
> >> > + * must use this in their dma_buf ops structure as the release callback.
> >> > + */
> >> > void drm_gem_dmabuf_release(struct dma_buf *dma_buf)
> >> > {
> >> > struct drm_gem_object *obj = dma_buf->priv;
> >> > @@ -242,30 +251,30 @@ static void drm_gem_dmabuf_vunmap(struct dma_buf *dma_buf, void *vaddr)
> >> > }
> >> >
> >> > static void *drm_gem_dmabuf_kmap_atomic(struct dma_buf *dma_buf,
> >> > - unsigned long page_num)
> >> > + unsigned long page_num)
> >> > {
> >> > return NULL;
> >> > }
> >> >
> >> > static void drm_gem_dmabuf_kunmap_atomic(struct dma_buf *dma_buf,
> >> > - unsigned long page_num, void *addr)
> >> > + unsigned long page_num, void *addr)
> >> > {
> >> >
> >> > }
> >> > static void *drm_gem_dmabuf_kmap(struct dma_buf *dma_buf,
> >> > - unsigned long page_num)
> >> > + unsigned long page_num)
> >> > {
> >> > return NULL;
> >> > }
> >> >
> >> > static void drm_gem_dmabuf_kunmap(struct dma_buf *dma_buf,
> >> > - unsigned long page_num, void *addr)
> >> > + unsigned long page_num, void *addr)
> >> > {
> >> >
> >> > }
> >> >
> >> > static int drm_gem_dmabuf_mmap(struct dma_buf *dma_buf,
> >> > - struct vm_area_struct *vma)
> >> > + struct vm_area_struct *vma)
> >> > {
> >> > struct drm_gem_object *obj = dma_buf->priv;
> >> > struct drm_device *dev = obj->dev;
> >> > @@ -315,6 +324,15 @@ static const struct dma_buf_ops drm_gem_prime_dmabuf_ops = {
> >> > * driver's scatter/gather table
> >> > */
> >> >
> >> > +/**
> >> > + * drm_gem_prime_export - helper library implemention of the export callback
> >> > + * @dev: drm_device to export from
> >> > + * @obj: GEM object to export
> >> > + * @flags: flags like DRM_CLOEXEC
> >> > + *
> >> > + * This is the implementation of the gem_prime_export functions for GEM drivers
> >> > + * using the PRIME helpers.
> >> > + */
> >> > struct dma_buf *drm_gem_prime_export(struct drm_device *dev,
> >> > struct drm_gem_object *obj, int flags)
> >> > {
> >> > @@ -355,9 +373,23 @@ static struct dma_buf *export_and_register_object(struct drm_device *dev,
> >> > return dmabuf;
> >> > }
> >> >
> >> > +/**
> >> > + * drm_gem_prime_handle_to_fd - PRIME export function for GEM drivers
> >> > + * @dev: dev to export the buffer from
> >> > + * @file_priv: drm file-private structure
> >> > + * @handle: buffer handle to export
> >> > + * @flags: flags like DRM_CLOEXEC
> >> > + * @prime_fd: pointer to storage for the fd id of the create dma-buf
> >> > + *
> >> > + * This is the PRIME export function which must be used mandatorily by GEM
> >> > + * drivers to ensure correct lifetime management of the underlying GEM object.
> >> > + * The actual exporting from GEM object to a dma-buf is done through the
> >> > + * gem_prime_export driver callback.
> >> > + */
> >> > int drm_gem_prime_handle_to_fd(struct drm_device *dev,
> >> > - struct drm_file *file_priv, uint32_t handle, uint32_t flags,
> >> > - int *prime_fd)
> >> > + struct drm_file *file_priv, uint32_t handle,
> >> > + uint32_t flags,
> >> > + int *prime_fd)
> >> > {
> >> > struct drm_gem_object *obj;
> >> > int ret = 0;
> >> > @@ -441,6 +473,14 @@ out_unlock:
> >> > }
> >> > EXPORT_SYMBOL(drm_gem_prime_handle_to_fd);
> >> >
> >> > +/**
> >> > + * drm_gem_prime_import - helper library implemention of the import callback
> >> > + * @dev: drm_device to import into
> >> > + * @dma_buf: dma-buf object to import
> >> > + *
> >> > + * This is the implementation of the gem_prime_import functions for GEM drivers
> >> > + * using the PRIME helpers.
> >> > + */
> >> > struct drm_gem_object *drm_gem_prime_import(struct drm_device *dev,
> >> > struct dma_buf *dma_buf)
> >> > {
> >> > @@ -496,8 +536,21 @@ fail_detach:
> >> > }
> >> > EXPORT_SYMBOL(drm_gem_prime_import);
> >> >
> >> > +/**
> >> > + * drm_gem_prime_fd_to_handle - PRIME import function for GEM drivers
> >> > + * @dev: dev to export the buffer from
> >> > + * @file_priv: drm file-private structure
> >> > + * @prime_fd: fd id of the dma-buf which should be imported
> >> > + * @handle: pointer to storage for the handle of the imported buffer object
> >> > + *
> >> > + * This is the PRIME import function which must be used mandatorily by GEM
> >> > + * drivers to ensure correct lifetime management of the underlying GEM object.
> >> > + * The actual importing of GEM object from the dma-buf is done through the
> >> > + * gem_import_export driver callback.
> >> > + */
> >> > int drm_gem_prime_fd_to_handle(struct drm_device *dev,
> >> > - struct drm_file *file_priv, int prime_fd, uint32_t *handle)
> >> > + struct drm_file *file_priv, int prime_fd,
> >> > + uint32_t *handle)
> >> > {
> >> > struct dma_buf *dma_buf;
> >> > struct drm_gem_object *obj;
> >> > @@ -598,12 +651,14 @@ int drm_prime_fd_to_handle_ioctl(struct drm_device *dev, void *data,
> >> > args->fd, &args->handle);
> >> > }
> >> >
> >> > -/*
> >> > - * drm_prime_pages_to_sg
> >> > +/**
> >> > + * drm_prime_pages_to_sg - converts a page array into an sg list
> >> > + * @pages: pointer to the array of page pointers to convert
> >> > + * @nr_pages: length of the page vector
> >> > *
> >> > - * this helper creates an sg table object from a set of pages
> >> > + * This helper creates an sg table object from a set of pages
> >> > * the driver is responsible for mapping the pages into the
> >> > - * importers address space
> >> > + * importers address space for use with dma_buf itself.
> >> > */
> >> > struct sg_table *drm_prime_pages_to_sg(struct page **pages, int nr_pages)
> >> > {
> >> > @@ -628,9 +683,16 @@ out:
> >> > }
> >> > EXPORT_SYMBOL(drm_prime_pages_to_sg);
> >> >
> >> > -/* export an sg table into an array of pages and addresses
> >> > - this is currently required by the TTM driver in order to do correct fault
> >> > - handling */
> >> > +/**
> >> > + * drm_prime_sg_to_page_addr_arrays - convert an sg table into a page array
> >> > + * @sgt: scatter-gather table to convert
> >> > + * @pages: array of page pointers to store the page array in
> >> > + * @addrs: optional array to store the dma bus address of each page
> >> > + * @max_pages: size of both the passed-in arrays
> >> > + *
> >> > + * Exports an sg table into an array of pages and addresses. This is currently
> >> > + * required by the TTM driver in order to do correct fault handling.
> >> > + */
> >> > int drm_prime_sg_to_page_addr_arrays(struct sg_table *sgt, struct page **pages,
> >> > dma_addr_t *addrs, int max_pages)
> >> > {
> >> > @@ -663,7 +725,15 @@ int drm_prime_sg_to_page_addr_arrays(struct sg_table *sgt, struct page **pages,
> >> > return 0;
> >> > }
> >> > EXPORT_SYMBOL(drm_prime_sg_to_page_addr_arrays);
> >> > -/* helper function to cleanup a GEM/prime object */
> >> > +
> >> > +/**
> >> > + * drm_prime_gem_destroy - helper to clean up a PRIME-imported GEM object
> >> > + * @obj: GEM object which was created from a dma-buf
> >> > + * @sg: the sg-table which was pinned at import time
> >> > + *
> >> > + * This is the cleanup functions which GEM drivers need to call when they use
> >> > + * @drm_gem_prime_import to import dma-bufs.
> >> > + */
> >> > void drm_prime_gem_destroy(struct drm_gem_object *obj, struct sg_table *sg)
> >> > {
> >> > struct dma_buf_attachment *attach;
> >> > @@ -683,11 +753,9 @@ void drm_prime_init_file_private(struct drm_prime_file_private *prime_fpriv)
> >> > INIT_LIST_HEAD(&prime_fpriv->head);
> >> > mutex_init(&prime_fpriv->lock);
> >> > }
> >> > -EXPORT_SYMBOL(drm_prime_init_file_private);
> >> >
> >> > void drm_prime_destroy_file_private(struct drm_prime_file_private *prime_fpriv)
> >> > {
> >> > /* by now drm_gem_release should've made sure the list is empty */
> >> > WARN_ON(!list_empty(&prime_fpriv->head));
> >> > }
> >> > -EXPORT_SYMBOL(drm_prime_destroy_file_private);
> >> > --
> >> > 1.8.5.2
> >> >
> >> > _______________________________________________
> >> > dri-devel mailing list
> >> > dri-devel at lists.freedesktop.org
> >> > http://lists.freedesktop.org/mailman/listinfo/dri-devel
> >
> > --
> > Daniel Vetter
> > Software Engineer, Intel Corporation
> > +41 (0) 79 365 57 48 - http://blog.ffwll.ch
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
More information about the dri-devel
mailing list