include/drm/README

   1 What are these headers ?
   2 ------------------------
   3 This is the canonical source of drm headers that user space should use for
   4 communicating with the kernel DRM subsystem.
   5
   6 They flow from the kernel, thus any changes must be merged there first.
   7 Do _not_ attempt to "fix" these by deviating from the kernel ones !
   8
   9
  10 Non-linux platforms - changes/patches
  11 -------------------------------------
  12 If your platform has local changes, please send them upstream for inclusion.
  13 Even if your patches don't get accepted in their current form, devs will
  14 give you feedback on how to address things properly.
  15
  16 git send-email --subject-prefix="PATCH libdrm" your patches to dri-devel
  17 mailing list.
  18
  19 Before doing so, please consider the following:
  20  - Have the [libdrm vs kernel] headers on your platform deviated ?
  21 Consider unifying them first.
  22
  23  - Have you introduced additional ABI that's not available in Linux ?
  24 Propose it for [Linux kernel] upstream inclusion.
  25 If that doesn't work out (hopefully it never does), move it to another header
  26 and/or keep the change(s) local ?
  27
  28  - Are your changes DRI1/UMS specific ?
  29 There is virtually no interest/power in keeping those legacy interfaces. They
  30 are around due to the kernel "thou shalt not break existing user space" rule.
  31
  32 Consider porting the driver to DRI2/KMS - all (almost?) sensible hardware is
  33 capable of supporting those.
  34
  35
  36 Which headers go where ?
  37 ------------------------
  38 A snipped from the, now removed, Makefile.am used to state:
  39
  40   XXX airlied says, nothing besides *_drm.h and drm*.h should be necessary.
  41   however, r300 and via need their reg headers installed in order to build.
  42   better solutions are welcome.
  43
  44 Obviously the r300 and via headers are no longer around ;-)
  45
  46 Reason behind is that the drm headers can be used as a basic communications
  47 channel with the respective kernel modules. If more advanced functionality is
  48 required one can pull the specific libdrm_$driver which is free to pull
  49 additional files from the kernel.
  50
  51 For example: nouveau has nouveau/nvif/*.h while vc4 has vc4/*.h
  52
  53 If your driver is still in prototyping/staging state, consider moving the
  54 $driver_drm.h into $driver and _not_ installing it. An header providing opaque
  55 definitions and access [via $driver_drmif.h or similar] would be better fit.
  56
  57
  58 When and which headers to update
  59 --------------------------------
  60 Ideally all files will be synced (updated) with the latest released kernel on
  61 each libdrm release. Sadly that's not yet possible since quite a few headers
  62 differ significantly - see Outdated or Broken Headers section below.
  63
  64 That said, it's up-to the individual developers to sync with newer version
  65 (from drm-next) as they see fit.
  66
  67
  68 When and how to update these files
  69 ----------------------------------
  70 Note: One should not do _any_ changes to the files apart from the steps below.
  71
  72 In order to update the files do the following:
  73  - Switch to a Linux kernel tree/branch which is not rebased.
  74 For example: airlied/drm-next
  75  - Install the headers via `make headers_install' to a separate location.
  76  - Copy the drm header[s] + git add + git commit.
  77  - Note: Your commit message must include:
  78    a) Brief summary on the delta. If there's any change that looks like an
  79 API/ABI break one _must_ explicitly state why it's safe to do so.
  80    b) "Generated using make headers_install."
  81    c) "Generated from $tree/branch commit $sha"
  82
  83
  84 Outdated or Broken Headers
  85 --------------------------
  86 This section contains a list of headers and the respective "issues" they might
  87 have relative to their kernel equivalent.
  88
  89 Nearly all headers:
  90  - Missing extern C notation.
  91 Status: Trivial.
  92
  93 Most UMS headers:
  94  - Not using fixed size integers - compat ioctls are broken.
  95 Status: ?
  96 Promote to fixed size ints, which match the current (32bit) ones.
  97
  98
  99 amdgpu_drm.h
 100  - Using the stdint.h uint*_t over the respective __u* ones
 101 Status: Trivial.
 102
 103 drm_mode.h
 104  - Missing DPI encode/connector pair.
 105 Status: Trivial.
 106
 107 i915_drm.h
 108  - Missing PARAMS - HAS_POOLED_EU, MIN_EU_IN_POOL CONTEXT_PARAM_NO_ERROR_CAPTURE
 109 Status: Trivial.
 110
 111 mga_drm.h
 112  - Typo fix, use struct over typedef.
 113 Status: Trivial.
 114
 115 nouveau_drm.h
 116  - Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs,
 117 enums, using stdint.h over the __u* types.
 118 Status: ?
 119
 120 qxl_drm.h
 121  - Using the stdint.h uint*_t over the respective __u* ones
 122 Status: Trivial.
 123
 124 r128_drm.h
 125  - Broken compat ioctls.
 126
 127 radeon_drm.h
 128  - Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls,
 129 using stdint types.
 130  - Both kernel and libdrm: missing padding -
 131 drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ?
 132 Status: ?
 133
 134 savage_drm.h
 135  - Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken.
 136 Status: ?
 137
 138 sis_drm.h
 139  - Borken ioctls + libdrm uses int vs kernel long
 140 Status: ?
 141
 142 via_drm.h
 143  - Borken ioctls - libdrm int vs kernel long
 144 Status: ?
 145
 146
 147 omap_drm.h (living in $TOP/omap)
 148  - License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct
 149 Status: ?
 150
 151 msm_drm.h (located in $TOP/freedreno/msm/)
 152  - License mismatch, missing MSM_PIPE_*, MSM_SUBMIT_*. Renamed
 153 drm_msm_gem_submit::flags, missing drm_msm_gem_submit::fence_fd.
 154 Status: ?
 155
 156 exynos_drm.h (living in $TOP/exynos)
 157  - License mismatch, now using fixed size ints (but not everywhere). Lots of
 158 new stuff.
 159 Status: ?