[PATCH] drm/i915: Document that mmap forwarding is discouraged

[PATCH] drm/i915: Document that mmap forwarding is discouraged

[Daniel Vetter]

Too many new drm driver writers seem to look at i915 for inspiration.
But we have two ways to do mmap, so discourage readers from the old,
ugly version. In a new driver we'd just expose two mmap offsets per
object, one for the gtt map and the other for the cpu map.

Cc: "Cheng, Yao" <yao.cheng@intel.com>
Cc: David Herrmann <dh.herrmann@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 drivers/gpu/drm/i915/i915_gem.c | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
index e9c783d55612..09d859b89aac 100644
--- a/drivers/gpu/drm/i915/i915_gem.c
+++ b/drivers/gpu/drm/i915/i915_gem.c
@@ -1466,6 +1466,15 @@ unlock:
  *
  * While the mapping holds a reference on the contents of the object, it doesn't
  * imply a ref on the object itself.
+ *
+ * IMPORTANT:
+ *
+ * DRM driver writers who look a this function as an example for how to do GEM
+ * mmap support, please don't implement mmap support like here. The modern way
+ * to implement DRM mmap support is with an mmap offset ioctl (like
+ * i915_gem_mmap_gtt) and then using the mmap syscall on the DRM fd directly.
+ * That way debug tooling like valgrind will understand what's going on, hiding
+ * the mmap call in a driver private ioctl will break that.
  */
 int
 i915_gem_mmap_ioctl(struct drm_device *dev, void *data,
-- 
1.9.3

Re: [PATCH] drm/i915: Document that mmap forwarding is discouraged

[Jani Nikula]

On Thu, 16 Oct 2014, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> Too many new drm driver writers seem to look at i915 for inspiration.
> But we have two ways to do mmap, so discourage readers from the old,
> ugly version. In a new driver we'd just expose two mmap offsets per
> object, one for the gtt map and the other for the cpu map.
>
> Cc: "Cheng, Yao" <yao.cheng@intel.com>
> Cc: David Herrmann <dh.herrmann@gmail.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
>  drivers/gpu/drm/i915/i915_gem.c | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
> index e9c783d55612..09d859b89aac 100644
> --- a/drivers/gpu/drm/i915/i915_gem.c
> +++ b/drivers/gpu/drm/i915/i915_gem.c
> @@ -1466,6 +1466,15 @@ unlock:
>   *
>   * While the mapping holds a reference on the contents of the object, it doesn't
>   * imply a ref on the object itself.
> + *
> + * IMPORTANT:
> + *
> + * DRM driver writers who look a this function as an example for how to do GEM
> + * mmap support, please don't implement mmap support like here. The modern way
> + * to implement DRM mmap support is with an mmap offset ioctl (like
> + * i915_gem_mmap_gtt) and then using the mmap syscall on the DRM fd directly.
> + * That way debug tooling like valgrind will understand what's going on, hiding
> + * the mmap call in a driver private ioctl will break that.

Maybe a sentence here about why we're doing things differently, instead
of merely "do as I say, don't do as I do"? It smells like hysterical
raisins, but no harm in spelling it out, right?

BR,
Jani.

>   */
>  int
>  i915_gem_mmap_ioctl(struct drm_device *dev, void *data,
> -- 
> 1.9.3
>
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH] drm/i915: Document that mmap forwarding is discouraged

[Daniel Vetter]

On Thu, Oct 16, 2014 at 01:48:20PM +0300, Jani Nikula wrote:
> On Thu, 16 Oct 2014, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > Too many new drm driver writers seem to look at i915 for inspiration.
> > But we have two ways to do mmap, so discourage readers from the old,
> > ugly version. In a new driver we'd just expose two mmap offsets per
> > object, one for the gtt map and the other for the cpu map.
> >
> > Cc: "Cheng, Yao" <yao.cheng@intel.com>
> > Cc: David Herrmann <dh.herrmann@gmail.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > ---
> >  drivers/gpu/drm/i915/i915_gem.c | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> >
> > diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
> > index e9c783d55612..09d859b89aac 100644
> > --- a/drivers/gpu/drm/i915/i915_gem.c
> > +++ b/drivers/gpu/drm/i915/i915_gem.c
> > @@ -1466,6 +1466,15 @@ unlock:
> >   *
> >   * While the mapping holds a reference on the contents of the object, it doesn't
> >   * imply a ref on the object itself.
> > + *
> > + * IMPORTANT:
> > + *
> > + * DRM driver writers who look a this function as an example for how to do GEM
> > + * mmap support, please don't implement mmap support like here. The modern way
> > + * to implement DRM mmap support is with an mmap offset ioctl (like
> > + * i915_gem_mmap_gtt) and then using the mmap syscall on the DRM fd directly.
> > + * That way debug tooling like valgrind will understand what's going on, hiding
> > + * the mmap call in a driver private ioctl will break that.
> 
> Maybe a sentence here about why we're doing things differently, instead
> of merely "do as I say, don't do as I do"? It smells like hysterical
> raisins, but no harm in spelling it out, right?

Ok, I'll add a "The i915 only does mmap this way because we didn't know
better".
-Daniel

> 
> BR,
> Jani.
> 
> >   */
> >  int
> >  i915_gem_mmap_ioctl(struct drm_device *dev, void *data,
> > -- 
> > 1.9.3
> >
> > _______________________________________________
> > Intel-gfx mailing list
> > Intel-gfx@lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/intel-gfx
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

Re: [PATCH] drm/i915: Document that mmap forwarding is discouraged

[David Herrmann]

Hi

On Thu, Oct 16, 2014 at 12:28 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> Too many new drm driver writers seem to look at i915 for inspiration.
> But we have two ways to do mmap, so discourage readers from the old,
> ugly version. In a new driver we'd just expose two mmap offsets per
> object, one for the gtt map and the other for the cpu map.

Yes, please! (also fine with Jani's concerns)

Reviewed-by: David Herrmann <dh.herrmann@gmail.com>

Thanks
David

> Cc: "Cheng, Yao" <yao.cheng@intel.com>
> Cc: David Herrmann <dh.herrmann@gmail.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
>  drivers/gpu/drm/i915/i915_gem.c | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
> index e9c783d55612..09d859b89aac 100644
> --- a/drivers/gpu/drm/i915/i915_gem.c
> +++ b/drivers/gpu/drm/i915/i915_gem.c
> @@ -1466,6 +1466,15 @@ unlock:
>   *
>   * While the mapping holds a reference on the contents of the object, it doesn't
>   * imply a ref on the object itself.
> + *
> + * IMPORTANT:
> + *
> + * DRM driver writers who look a this function as an example for how to do GEM
> + * mmap support, please don't implement mmap support like here. The modern way
> + * to implement DRM mmap support is with an mmap offset ioctl (like
> + * i915_gem_mmap_gtt) and then using the mmap syscall on the DRM fd directly.
> + * That way debug tooling like valgrind will understand what's going on, hiding
> + * the mmap call in a driver private ioctl will break that.
>   */
>  int
>  i915_gem_mmap_ioctl(struct drm_device *dev, void *data,
> --
> 1.9.3
>

Re: [PATCH] drm/i915: Document that mmap forwarding is discouraged

[Cheng, Yao]

Nice :) thanks for this!

> -----Original Message-----
> From: David Herrmann [mailto:dh.herrmann@gmail.com]
> Sent: Thursday, October 16, 2014 8:03 PM
> To: Daniel Vetter
> Cc: Intel Graphics Development; Cheng, Yao
> Subject: Re: [PATCH] drm/i915: Document that mmap forwarding is
> discouraged
> 
> Hi
> 
> On Thu, Oct 16, 2014 at 12:28 PM, Daniel Vetter <daniel.vetter@ffwll.ch>
> wrote:
> > Too many new drm driver writers seem to look at i915 for inspiration.
> > But we have two ways to do mmap, so discourage readers from the old,
> > ugly version. In a new driver we'd just expose two mmap offsets per
> > object, one for the gtt map and the other for the cpu map.
> 
> Yes, please! (also fine with Jani's concerns)
> 
> Reviewed-by: David Herrmann <dh.herrmann@gmail.com>
> 
> Thanks
> David
> 
> > Cc: "Cheng, Yao" <yao.cheng@intel.com>
> > Cc: David Herrmann <dh.herrmann@gmail.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > ---
> >  drivers/gpu/drm/i915/i915_gem.c | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> >
> > diff --git a/drivers/gpu/drm/i915/i915_gem.c
> > b/drivers/gpu/drm/i915/i915_gem.c index e9c783d55612..09d859b89aac
> > 100644
> > --- a/drivers/gpu/drm/i915/i915_gem.c
> > +++ b/drivers/gpu/drm/i915/i915_gem.c
> > @@ -1466,6 +1466,15 @@ unlock:
> >   *
> >   * While the mapping holds a reference on the contents of the object, it
> doesn't
> >   * imply a ref on the object itself.
> > + *
> > + * IMPORTANT:
> > + *
> > + * DRM driver writers who look a this function as an example for how
> > + to do GEM
> > + * mmap support, please don't implement mmap support like here. The
> > + modern way
> > + * to implement DRM mmap support is with an mmap offset ioctl (like
> > + * i915_gem_mmap_gtt) and then using the mmap syscall on the DRM fd
> directly.
> > + * That way debug tooling like valgrind will understand what's going
> > + on, hiding
> > + * the mmap call in a driver private ioctl will break that.
> >   */
> >  int
> >  i915_gem_mmap_ioctl(struct drm_device *dev, void *data,
> > --
> > 1.9.3
> >