drm/include/drm
Juston Li 63d914d479 include/drm: sync up drm.h
a) delta: Adds DRM_IOCTL_MODE_GETFB2
  b) Generated using make headers_install
  c) Taken from drm-next-misc:
        commit 3ff4c24bdb1f494c217c80348f9db4896043ed81
        Author: Lyude Paul <lyude@redhat.com>
        Date:   Fri Jan 17 17:47:48 2020 -0500

        drm/dp_mst: Fix indenting in drm_dp_mst_topology_mgr_set_mst()

Signed-off-by: Juston Li <juston.li@intel.com>
Acked-by: Eric Engestrom <eric@engestrom.ch>
2020-02-12 10:23:44 +11:00
..
README headers/README: fix/add link to drm-next 2018-09-18 19:39:22 +01:00
amdgpu_drm.h include: update amdgpu_drm.h 2019-10-15 14:30:31 -04:00
drm.h include/drm: sync up drm.h 2020-02-12 10:23:44 +11:00
drm_fourcc.h fix various typos 2019-04-17 18:23:25 +01:00
drm_mode.h fix various typos 2019-04-17 18:23:25 +01:00
drm_sarea.h headers: sync drm_sarea.h with airlied/drm-next 2017-06-03 23:39:22 +01:00
i915_drm.h fix various typos 2019-04-17 18:23:25 +01:00
mach64_drm.h Put mach64_drm.h back in to avoid breaking mesa build 2009-11-20 20:17:26 -05:00
mga_drm.h headers: Sync up mga_drm.h from drm-next. 2017-11-10 12:10:15 -08:00
msm_drm.h libdrm: add msm drm uapi header 2018-08-23 08:48:45 -07:00
nouveau_drm.h headers: Sync with drm-next 2018-03-30 16:10:03 +01:00
qxl_drm.h libdrm: headers: Sync with drm-next 2018-10-04 14:51:09 +01:00
r128_drm.h headers: Sync up some header guard changes from drm-next. 2017-11-10 12:10:12 -08:00
radeon_drm.h headers: Sync up kernel changes to use kernel types instead of stdint.h. 2017-11-10 12:10:17 -08:00
savage_drm.h headers: Sync up some comment spelling and whitespace fixes from drm-next. 2017-11-10 12:10:13 -08:00
sis_drm.h headers: Sync up some header guard changes from drm-next. 2017-11-10 12:10:12 -08:00
tegra_drm.h libdrm: headers: Sync with drm-next 2018-10-04 14:51:09 +01:00
vc4_drm.h libdrm: headers: Sync with drm-next 2018-10-04 14:51:09 +01:00
via_drm.h headers: Sync up some header guard changes from drm-next. 2017-11-10 12:10:12 -08:00
virtgpu_drm.h virtgpu: Update kernel header 2019-04-03 20:11:55 -04:00
vmwgfx_drm.h fix various typos 2019-04-17 18:23:25 +01:00

README

What are these headers ?
------------------------
This is the canonical source of drm headers that user space should use for
communicating with the kernel DRM subsystem.

They flow from the kernel, thus any changes must be merged there first.
Do _not_ attempt to "fix" these by deviating from the kernel ones !


Non-linux platforms - changes/patches
-------------------------------------
If your platform has local changes, please send them upstream for inclusion.
Even if your patches don't get accepted in their current form, devs will
give you feedback on how to address things properly.

git send-email --subject-prefix="PATCH libdrm" your patches to dri-devel
mailing list.

Before doing so, please consider the following:
 - Have the [libdrm vs kernel] headers on your platform deviated ?
Consider unifying them first.

 - Have you introduced additional ABI that's not available in Linux ?
Propose it for [Linux kernel] upstream inclusion.
If that doesn't work out (hopefully it never does), move it to another header
and/or keep the change(s) local ?

 - Are your changes DRI1/UMS specific ?
There is virtually no interest/power in keeping those legacy interfaces. They
are around due to the kernel "thou shalt not break existing user space" rule.

Consider porting the driver to DRI2/KMS - all (almost?) sensible hardware is
capable of supporting those.


Which headers go where ?
------------------------
A snipped from the, now removed, Makefile.am used to state:

  XXX airlied says, nothing besides *_drm.h and drm*.h should be necessary.
  however, r300 and via need their reg headers installed in order to build.
  better solutions are welcome.

Obviously the r300 and via headers are no longer around ;-)

Reason behind is that the drm headers can be used as a basic communications
channel with the respective kernel modules. If more advanced functionality is
required one can pull the specific libdrm_$driver which is free to pull
additional files from the kernel.

For example: nouveau has nouveau/nvif/*.h while vc4 has vc4/*.h

If your driver is still in prototyping/staging state, consider moving the
$driver_drm.h into $driver and _not_ installing it. An header providing opaque
definitions and access [via $driver_drmif.h or similar] would be better fit.


When and which headers to update
--------------------------------
Ideally all files will be synced (updated) with the latest released kernel on
each libdrm release. Sadly that's not yet possible since quite a few headers
differ significantly - see Outdated or Broken Headers section below.

That said, it's up-to the individual developers to sync with newer version
(from drm-next) as they see fit.


When and how to update these files
----------------------------------
Note: One should not do _any_ changes to the files apart from the steps below.

In order to update the files do the following:
 - Switch to a Linux kernel tree/branch which is not rebased.
   For example: drm-next (https://cgit.freedesktop.org/drm/drm)
 - Install the headers via `make headers_install' to a separate location.
 - Copy the drm header[s] + git add + git commit.
 - Note: Your commit message must include:
   a) Brief summary on the delta. If there's any change that looks like an
API/ABI break one _must_ explicitly state why it's safe to do so.
   b) "Generated using make headers_install."
   c) "Generated from $tree/branch commit $sha"


Outdated or Broken Headers
--------------------------
This section contains a list of headers and the respective "issues" they might
have relative to their kernel equivalent.

Most UMS headers:
 - Not using fixed size integers - compat ioctls are broken.
Status: ?
Promote to fixed size ints, which match the current (32bit) ones.

nouveau_drm.h
 - Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs,
enums
Status: Deliberate UABI choice; nouveau hides the exact kernel ABI behind libdrm

r128_drm.h
 - Broken compat ioctls.

radeon_drm.h
 - Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls
 - Both kernel and libdrm: missing padding -
drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ?
Status: ?

savage_drm.h
 - Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken.
Status: ?

sis_drm.h
 - Borken ioctls + libdrm uses int vs kernel long
Status: ?

via_drm.h
 - Borken ioctls - libdrm int vs kernel long
Status: ?


omap_drm.h (living in $TOP/omap)
 - License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct
Status: ?

exynos_drm.h (living in $TOP/exynos)
 - License mismatch, now using fixed size ints (but not everywhere). Lots of
new stuff.
Status: ?