Re: [PATCH] docs/drm: Add a new bullet to the uAPI requirements (v2)
On Wed, 4 Aug 2021 at 19:57, Jason Ekstrand wrote: > While tracking down various bits of i915 uAPI, it's been difficult to > find the userspace much of the time because no one bothers to mention it > in commit messages. Require the kernel patch to be a one-stop shop for > finding the various bits which were used to justify the new uAPI. Acked-by: Daniel Stone
[PATCH] docs/drm: Add a new bullet to the uAPI requirements (v2)
While tracking down various bits of i915 uAPI, it's been difficult to find the userspace much of the time because no one bothers to mention it in commit messages. Require the kernel patch to be a one-stop shop for finding the various bits which were used to justify the new uAPI. v2 (Daniel Vetter): - Minor wording tweaks Signed-off-by: Jason Ekstrand Acked-by: Daniel Vetter Cc: Dave Airlie --- Documentation/gpu/drm-uapi.rst | 5 + 1 file changed, 5 insertions(+) diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 199afb503ab1..7b398c6fadc6 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -109,6 +109,11 @@ leads to a few additional requirements: userspace patches land. uAPI always flows from the kernel, doing things the other way round risks divergence of the uAPI definitions and header files. +- The kernel patch which adds the new uAPI **must** reference the patch series + or merge requests in the userspaces projects which demonstrate the use of the + new uAPI and against which the review was done so that future developers can + find all of the pieces which tie together. + These are fairly steep requirements, but have grown out from years of shared pain and experience with uAPI added hastily, and almost always regretted about just as fast. GFX devices change really fast, requiring a paradigm shift and -- 2.31.1
Re: [PATCH] docs/drm: Add a new bullet to the uAPI requirements
On Wed, Aug 4, 2021 at 8:50 PM Jason Ekstrand wrote: > > On Wed, Aug 4, 2021 at 1:48 PM Jason Ekstrand wrote: > > > > While tracking down various bits of i915 uAPI, it's been difficult to > > find the userspace much of the time because no one bothers to mention it > > in commit messages. Require the kernel patch to be a one-stop shop for > > finding the various bits which were used to justify the new uAPI. > > > > Signed-off-by: Jason Ekstrand > > Cc: Daniel Vetter > > Cc: Dave Airlie > > --- > > Documentation/gpu/drm-uapi.rst | 5 + > > 1 file changed, 5 insertions(+) > > > > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst > > index 199afb503ab1..82f780bc3fce 100644 > > --- a/Documentation/gpu/drm-uapi.rst > > +++ b/Documentation/gpu/drm-uapi.rst > > @@ -109,6 +109,11 @@ leads to a few additional requirements: > >userspace patches land. uAPI always flows from the kernel, doing things > > the > >other way round risks divergence of the uAPI definitions and header > > files. > > > > +- The kernel patch which adds the new uAPI **must** reference the patch > > series > > + or merge requests in the userspaces project which use the new uAPI and > > Locally, I've done s/project which use/projects which demonstrate/ While we paint this shed ... projects which demonstrate the use of the new uAPI? Either way this seems like a fine addition to our docs and process, since grepping through all the things just to figure out what something does because documentation was deemed optional too gets boring. Acked-by: Daniel Vetter -Daniel > > --Jason > > > + against which the review was done so that future developers can find all > > of > > + the pieces which tie together. > > + > > These are fairly steep requirements, but have grown out from years of > > shared > > pain and experience with uAPI added hastily, and almost always regretted > > about > > just as fast. GFX devices change really fast, requiring a paradigm shift > > and > > -- > > 2.31.1 > > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
Re: [PATCH] docs/drm: Add a new bullet to the uAPI requirements
On Wed, Aug 4, 2021 at 1:48 PM Jason Ekstrand wrote: > > While tracking down various bits of i915 uAPI, it's been difficult to > find the userspace much of the time because no one bothers to mention it > in commit messages. Require the kernel patch to be a one-stop shop for > finding the various bits which were used to justify the new uAPI. > > Signed-off-by: Jason Ekstrand > Cc: Daniel Vetter > Cc: Dave Airlie > --- > Documentation/gpu/drm-uapi.rst | 5 + > 1 file changed, 5 insertions(+) > > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst > index 199afb503ab1..82f780bc3fce 100644 > --- a/Documentation/gpu/drm-uapi.rst > +++ b/Documentation/gpu/drm-uapi.rst > @@ -109,6 +109,11 @@ leads to a few additional requirements: >userspace patches land. uAPI always flows from the kernel, doing things the >other way round risks divergence of the uAPI definitions and header files. > > +- The kernel patch which adds the new uAPI **must** reference the patch > series > + or merge requests in the userspaces project which use the new uAPI and Locally, I've done s/project which use/projects which demonstrate/ --Jason > + against which the review was done so that future developers can find all of > + the pieces which tie together. > + > These are fairly steep requirements, but have grown out from years of shared > pain and experience with uAPI added hastily, and almost always regretted > about > just as fast. GFX devices change really fast, requiring a paradigm shift and > -- > 2.31.1 >
[PATCH] docs/drm: Add a new bullet to the uAPI requirements
While tracking down various bits of i915 uAPI, it's been difficult to find the userspace much of the time because no one bothers to mention it in commit messages. Require the kernel patch to be a one-stop shop for finding the various bits which were used to justify the new uAPI. Signed-off-by: Jason Ekstrand Cc: Daniel Vetter Cc: Dave Airlie --- Documentation/gpu/drm-uapi.rst | 5 + 1 file changed, 5 insertions(+) diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 199afb503ab1..82f780bc3fce 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -109,6 +109,11 @@ leads to a few additional requirements: userspace patches land. uAPI always flows from the kernel, doing things the other way round risks divergence of the uAPI definitions and header files. +- The kernel patch which adds the new uAPI **must** reference the patch series + or merge requests in the userspaces project which use the new uAPI and + against which the review was done so that future developers can find all of + the pieces which tie together. + These are fairly steep requirements, but have grown out from years of shared pain and experience with uAPI added hastily, and almost always regretted about just as fast. GFX devices change really fast, requiring a paradigm shift and -- 2.31.1
