From nobody Wed Dec 17 19:00:31 2025 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3315CC61D85 for ; Thu, 23 Nov 2023 22:13:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230521AbjKWWNe (ORCPT ); Thu, 23 Nov 2023 17:13:34 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42244 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230117AbjKWWNZ (ORCPT ); Thu, 23 Nov 2023 17:13:25 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D02CE10D7 for ; Thu, 23 Nov 2023 14:13:29 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1700777609; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=dih2whL2MPf6NwDlCWNCaNjlgkoV00h0l9L+4gltDhE=; b=RsoZcTvtpiZ7Bw2iO5CPMeQw9bJ26x5t/IAReYx+Uua6PbKMd82Y9x2390NlttCdl1m4tD 9AH8UJxznctmPga89B3mHhlgbefmIP/7Cw2RmOo9iG51deIrHiPW66++eQ9TCKhGl8tfut U5HadLXkoQRIXrY+9p0QkbmZbAZ8u+A= Received: from mail-wm1-f69.google.com (mail-wm1-f69.google.com [209.85.128.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-630-I63rtFG7MvWF3fMaZiUCUg-1; Thu, 23 Nov 2023 17:13:27 -0500 X-MC-Unique: I63rtFG7MvWF3fMaZiUCUg-1 Received: by mail-wm1-f69.google.com with SMTP id 5b1f17b1804b1-40845fe2d1cso6948565e9.0 for ; Thu, 23 Nov 2023 14:13:27 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700777606; x=1701382406; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=dih2whL2MPf6NwDlCWNCaNjlgkoV00h0l9L+4gltDhE=; b=sSVVBc4dn7JkTqLcRY9868qZ3W4SkSPgtaKUN2mgrONmR72WdlNNddR/Yu5ws55tBW OmC+Hd34rCzpceZAK6wKrJEzuVp76CMHl3sqnZYBys6vEN2ibtU/sFmBKDMMK7fbTWSA ZQ3aodofTzEFBh4JJhJfG4kJtw4CQjzkj0SKUuSbcn1HRxLm1CaNiHcWd5QNcCIA7SYy 7YpOziyKOuoR3WFrqHne/bHWVDkGSrk7CoU12kQi50bV+nCf9PfkTnTrIMyBeCcNeBTp TzDjyMfpoz6cL8x2Vbhw3+MLr5XgMbYWH2GbsUsGtOBNG8oABreu+L7IHy7Edqlg+TK6 HWiQ== X-Gm-Message-State: AOJu0Yxjg3ID/s/3XHuwqxMqH/dFZtUZUUk+BiIFslic6fBzP+PCLJh3 09E8XY81Zo3JNxJZMZQjRAIzq7y0T84JKHO0sIAJSTrASfOd2jHZTMgygx7d6QuEHxSGWVgogHi pe+4DXN3jKFqY6m1AMAEXy0vI4/fjIo4CRIn3pOTzRoN811TEA8CIpvuR1um2bW9nvJzkr3g/tt l1JV6f84w= X-Received: by 2002:a7b:cc8f:0:b0:40a:6235:e832 with SMTP id p15-20020a7bcc8f000000b0040a6235e832mr646341wma.19.1700777606366; Thu, 23 Nov 2023 14:13:26 -0800 (PST) X-Google-Smtp-Source: AGHT+IEUS52KyNbklxpPEj23AckZsdZntJX98+LIJ9h/c+7dPvbvw5i7N6FBV/jDsPgq5cqyhTFDUQ== X-Received: by 2002:a7b:cc8f:0:b0:40a:6235:e832 with SMTP id p15-20020a7bcc8f000000b0040a6235e832mr646322wma.19.1700777606063; Thu, 23 Nov 2023 14:13:26 -0800 (PST) Received: from localhost (205.pool92-176-231.dynamic.orange.es. [92.176.231.205]) by smtp.gmail.com with ESMTPSA id t5-20020adff045000000b00332e6a0e9f4sm1363883wro.75.2023.11.23.14.13.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 23 Nov 2023 14:13:24 -0800 (PST) From: Javier Martinez Canillas To: linux-kernel@vger.kernel.org Cc: Maxime Ripard , Zack Rusin , Thomas Zimmermann , Pekka Paalanen , Bilal Elmoussaoui , Simon Ser , Erico Nunes , Sima Vetter , Javier Martinez Canillas , Daniel Vetter , David Airlie , Maarten Lankhorst , dri-devel@lists.freedesktop.org Subject: [PATCH v4 4/5] drm/plane: Extend damage tracking kernel-doc Date: Thu, 23 Nov 2023 23:13:03 +0100 Message-ID: <20231123221315.3579454-5-javierm@redhat.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231123221315.3579454-1-javierm@redhat.com> References: <20231123221315.3579454-1-javierm@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" The "Damage Tracking Properties" section in the documentation doesn't have info about the two type of damage handling: frame damage vs buffer damage. Add it to the section and mention that helpers only support frame damage, and how drivers handling buffer damage can indicate that the damage clips should be ignored. Also add references to further documentation about the two damage types. Suggested-by: Simon Ser Signed-off-by: Javier Martinez Canillas Reviewed-by: Simon Ser Reviewed-by: Thomas Zimmermann Reviewed-by: Zack Rusin Acked-by: Sima Vetter --- Changes in v4: - Add another paragraph to "Damage Tracking Properties" section to mention the fields that drivers with per-buffer upload target should check to set drm_plane_state.ignore_damage_clips (Sima Vetter). Changes in v3: - Fix typo in the kernel-doc (Simon Ser). - Add a paragraph explaining what the problem in the kernel is and make it clear that the refeference documents are related to how user-space handles this case (Thomas Zimmermann). drivers/gpu/drm/drm_plane.c | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c index 24e7998d1731..662e0ba2707a 100644 --- a/drivers/gpu/drm/drm_plane.c +++ b/drivers/gpu/drm/drm_plane.c @@ -1442,6 +1442,36 @@ int drm_mode_page_flip_ioctl(struct drm_device *dev, * Drivers implementing damage can use drm_atomic_helper_damage_iter_init(= ) and * drm_atomic_helper_damage_iter_next() helper iterator function to get da= mage * rectangles clipped to &drm_plane_state.src. + * + * Note that there are two types of damage handling: frame damage and buff= er + * damage, the type of damage handling implemented depends on a driver's u= pload + * target. Drivers implementing a per-plane or per-CRTC upload target need= to + * handle frame damage, while drivers implementing a per-buffer upload tar= get + * need to handle buffer damage. + * + * The existing damage helpers only support the frame damage type, there i= s no + * buffer age support or similar damage accumulation algorithm implemented= yet. + * + * Only drivers handling frame damage can use the mentioned damage helpers= to + * iterate over the damaged regions. Drivers that handle buffer damage, mu= st set + * &drm_plane_state.ignore_damage_clips for drm_atomic_helper_damage_iter_= init() + * to know that damage clips should be ignored and return &drm_plane_state= .src + * as the damage rectangle, to force a full plane update. + * + * Drivers with a per-buffer upload target could compare the &drm_plane_st= ate.fb + * of the old and new plane states to determine if the framebuffer attache= d to a + * plane has changed or not since the last plane update. If &drm_plane_sta= te.fb + * has changed, then &drm_plane_state.ignore_damage_clips must be set to t= rue. + * + * That is because drivers with a per-plane upload target, expect the back= ing + * storage buffer to not change for a given plane. If the upload buffer ch= anges + * between page flips, the new upload buffer has to be updated as a whole.= This + * can be improved in the future if support for frame damage is added to t= he DRM + * damage helpers, similarly to how user-space already handle this case as= it is + * explained in the following documents: + * + * https://registry.khronos.org/EGL/extensions/KHR/EGL_KHR_swap_buffer= s_with_damage.txt + * https://emersion.fr/blog/2019/intro-to-damage-tracking/ */ =20 /** --=20 2.41.0