Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 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 | ---------------------------------- |
Emil Velikov | f6499b1 | 2017-02-14 01:34:14 +0000 | [diff] [blame] | 70 | Note: One should not do _any_ changes to the files apart from the steps below. |
| 71 | |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 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 | |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 89 | Most UMS headers: |
Grazvydas Ignotas | 1924b67 | 2016-11-20 20:25:46 +0200 | [diff] [blame] | 90 | - Not using fixed size integers - compat ioctls are broken. |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 91 | Status: ? |
| 92 | Promote to fixed size ints, which match the current (32bit) ones. |
| 93 | |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 94 | nouveau_drm.h |
| 95 | - Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs, |
Eric Anholt | f696698 | 2017-11-08 11:22:55 -0800 | [diff] [blame] | 96 | enums |
Daniel Stone | 8ec043e | 2018-03-30 13:23:45 +0100 | [diff] [blame] | 97 | Status: Deliberate UABI choice; nouveau hides the exact kernel ABI behind libdrm |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 98 | |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 99 | r128_drm.h |
| 100 | - Broken compat ioctls. |
| 101 | |
| 102 | radeon_drm.h |
Eric Anholt | f696698 | 2017-11-08 11:22:55 -0800 | [diff] [blame] | 103 | - Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls |
Emil Velikov | de13ea3 | 2016-11-14 17:59:28 +0000 | [diff] [blame] | 104 | - Both kernel and libdrm: missing padding - |
| 105 | drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ? |
| 106 | Status: ? |
| 107 | |
| 108 | savage_drm.h |
| 109 | - Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken. |
| 110 | Status: ? |
| 111 | |
| 112 | sis_drm.h |
| 113 | - Borken ioctls + libdrm uses int vs kernel long |
| 114 | Status: ? |
| 115 | |
| 116 | via_drm.h |
| 117 | - Borken ioctls - libdrm int vs kernel long |
| 118 | Status: ? |
| 119 | |
| 120 | |
| 121 | omap_drm.h (living in $TOP/omap) |
| 122 | - License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct |
| 123 | Status: ? |
| 124 | |
| 125 | msm_drm.h (located in $TOP/freedreno/msm/) |
| 126 | - License mismatch, missing MSM_PIPE_*, MSM_SUBMIT_*. Renamed |
| 127 | drm_msm_gem_submit::flags, missing drm_msm_gem_submit::fence_fd. |
| 128 | Status: ? |
| 129 | |
| 130 | exynos_drm.h (living in $TOP/exynos) |
| 131 | - License mismatch, now using fixed size ints (but not everywhere). Lots of |
| 132 | new stuff. |
| 133 | Status: ? |