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