From patchwork Thu Nov 10 16:44:23 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Emil Velikov X-Patchwork-Id: 9421467 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 870F460512 for ; Thu, 10 Nov 2016 16:44:35 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7D76729767 for ; Thu, 10 Nov 2016 16:44:35 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 723612976C; Thu, 10 Nov 2016 16:44:35 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-3.6 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_MED, RCVD_IN_SORBS_SPAM, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id C6F0729767 for ; Thu, 10 Nov 2016 16:44:34 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 8FC606E200; Thu, 10 Nov 2016 16:44:32 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wm0-x244.google.com (mail-wm0-x244.google.com [IPv6:2a00:1450:400c:c09::244]) by gabe.freedesktop.org (Postfix) with ESMTPS id 3841B6E200 for ; Thu, 10 Nov 2016 16:44:31 +0000 (UTC) Received: by mail-wm0-x244.google.com with SMTP id g23so4269092wme.1 for ; Thu, 10 Nov 2016 08:44:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id; bh=VB144f0tuoL5LoUPvkXdUcAAn3oPD6U+0W69Z44yBC0=; b=EN9Wt+HgDhBymVL6VSAtYHDi1m+7rqSNbMhXLW5252aNpxGtSFQd3RHLSntWj8DNqn 6Sy8jK9yAeMTz93+Dp2UZMnZF3jadcMn4WsshO5cqu5ef9TqKxEeRAXqTaLXkGuE9NJf /KlZDL3bzRiRCvhJsCwuvQ44YpwU1h/ltdKMSStP5Ezy2JAklT/YyLV08Y5LcQHbWKY9 JJUA460+Ii/r22gGkCp6NgB0WtQtJQ8pOkI7dVCIg3eNW8L8D7GlAXmCTmKye15WmUL+ otzze7ncM7HK19+yv/HGPtbpa7d0CGcMsed9X0ENEfQyPU5ahDh+u7K6WJ/s0baa5S7D FvQQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=VB144f0tuoL5LoUPvkXdUcAAn3oPD6U+0W69Z44yBC0=; b=Ru1v66rG/cEB5B8dhYqAaj+6CbVK3m6PDPD12xsjyP39ulu/GcJ2z8AnNQz46F0ovh ypV28yepEeFnfu4FzOP+HVwh3fR7qF3LARLg0+22XPQvUtlKTBcUjsRei3V+uDYPWLMj IAuCtfpSVKv1SB7YnMgrPqDw8OUtuiinMqvrRnjpdJRi/W74iC2e2odg5kEoTCnECFpe NObeydb21d5Zyg+9xu6zDBib1RiAbW+uWUBvZ3g0ZVrOB/O7QIb1jgdrtlZrHo84ASmR JDH3Zr7of2L1xUF2zErEqn5svqHXxY/6bRWMMAmcCBAJRFXSjBYBOSIQOnxrpktHv2MU dSYg== X-Gm-Message-State: ABUngvc8zJuye7j/ftLqUZx4iBQF1zWaa8u8InTbWcaRMgqG3B8fcAZUkwLvnwqH3AbdQw== X-Received: by 10.28.173.4 with SMTP id w4mr6676801wme.70.1478796269713; Thu, 10 Nov 2016 08:44:29 -0800 (PST) Received: from arch-x220.cbg.collabora.co.uk ([2a00:1098:5:0:120b:a9ff:fe8d:c914]) by smtp.gmail.com with ESMTPSA id i2sm2559360wjx.44.2016.11.10.08.44.28 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 10 Nov 2016 08:44:28 -0800 (PST) From: Emil Velikov To: dri-devel@lists.freedesktop.org Subject: [PATCH libdrm] headers: Add README file Date: Thu, 10 Nov 2016 16:44:23 +0000 Message-Id: <20161110164423.588-1-emil.l.velikov@gmail.com> X-Mailer: git-send-email 2.9.3 Cc: Dave Airlie , emil.l.velikov@gmail.com, Daniel Vetter X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP From: Emil Velikov Since we're trying to standardise and make things more consistent in the area, add a basic README which covers some of the more popular topics. Cc: Dave Airlie Cc: Daniel Vetter Signed-off-by: Emil Velikov Reviewed-by: Daniel Vetter --- Dave, did I get it right on the "why only drm files should live here" ? Dave, Daniel, which trees/branches [in drm-misc] we can use as reference point here ? --- include/drm/README | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 include/drm/README diff --git a/include/drm/README b/include/drm/README new file mode 100644 index 0000000..2f80c15 --- /dev/null +++ b/include/drm/README @@ -0,0 +1,72 @@ +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 how to update these files +---------------------------------- +Ideally on each libdrm release these will be kept in sync, with the latest +released kernels. This way users won't need to provide local definitions. + +In order to update the files do the following: + - Switch to a Linux kernel tree/branch which is not rebased. +For example: airlied/drm-next, drm-misc/XXX + - 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"