From patchwork Thu Dec 22 08:36:25 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Chris Wilson X-Patchwork-Id: 9484415 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 3A11D601D2 for ; Thu, 22 Dec 2016 08:38:05 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3604E277D9 for ; Thu, 22 Dec 2016 08:38:05 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 2AEEB27F8C; Thu, 22 Dec 2016 08:38:05 +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=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,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 9B2AE277D9 for ; Thu, 22 Dec 2016 08:38:03 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 45D046F178; Thu, 22 Dec 2016 08:38:01 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wj0-x242.google.com (mail-wj0-x242.google.com [IPv6:2a00:1450:400c:c01::242]) by gabe.freedesktop.org (Postfix) with ESMTPS id 918E96F16E; Thu, 22 Dec 2016 08:37:10 +0000 (UTC) Received: by mail-wj0-x242.google.com with SMTP id j10so35201006wjb.3; Thu, 22 Dec 2016 00:37:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references; bh=EcraH/CQzbLebW8CbEAZ1alGVXYa++9DvPwQeD2aot0=; b=G+WsHi+dKHouyrdnHJDSPK7NONc/86tElEiuuzvS5bUd9kTnRVh69Wtvgnf0g2ogPW 1qBlUdTkaQNqAZWD6bD9diJEnXu++EEXoph9mIQhoCULfRYSQInThjdEO42fAYhxmnOf dRJBCWZqCcYs27MLTMTQXcmc0cpJXxwG/BDSDzCY8nkgtd9m47Qhirg70T6dP180SgEK K5NTO08NaThQLnj8AjDiApSPwk7DOOtTaXewtg/LV8IWFCxktv5dPuqYHqGkgn4Aas6j Hrg/qOOOYJ/zXsdvV08qg9q+tO2bv9fEuipqsvfyiTxtWh9kHmbR3n8aKoTDv5XB7yr5 qilw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references; bh=EcraH/CQzbLebW8CbEAZ1alGVXYa++9DvPwQeD2aot0=; b=NbrvLkrXzhULskUuO3xa6pj2N7F+PZwuqK9QExacm5NegbAH7XoTHbiYv7wCH6X6Lb +82ZrSHC57a19qLw39wQH8B3UOLrWuqbTlzQ1WHPRSIlyHfz0ZvbH4gZDGQbm4RgaIai LTHEssNHkG4Ybxtir9C34u5ams1BypPxftJjOM/Uhune8bnOsP74UPpBOJKTE1NJEC5g Yw1zMl9JrkBbCzcDk4kBR4b+ToBFacxUcZuIRzi/tMzdHY/a9NfjuiL/QbqEdhADSIgw YQ3u2X4IkOB559kR5WJf9lRTMJMCHCrvMEcZWJhsO1jx85qGFmd0P5Id0n2aCgr4GxXr YG+w== X-Gm-Message-State: AIkVDXJXuG0nGOuQadfAy62PZF9+YCOKBe1lIvGknpQKwz5DmJylIVCBUTc4femX5wRItQ== X-Received: by 10.194.89.40 with SMTP id bl8mr7776187wjb.214.1482395828356; Thu, 22 Dec 2016 00:37:08 -0800 (PST) Received: from haswell.alporthouse.com ([78.156.65.138]) by smtp.gmail.com with ESMTPSA id di9sm34442318wjc.37.2016.12.22.00.37.07 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 22 Dec 2016 00:37:07 -0800 (PST) From: Chris Wilson To: dri-devel@lists.freedesktop.org Subject: [PATCH v4 22/38] drm: Fix kerneldoc for drm_mm_scan_remove_block() Date: Thu, 22 Dec 2016 08:36:25 +0000 Message-Id: <20161222083641.2691-23-chris@chris-wilson.co.uk> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20161222083641.2691-1-chris@chris-wilson.co.uk> References: <20161222083641.2691-1-chris@chris-wilson.co.uk> Cc: intel-gfx@lists.freedesktop.org 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 The nodes must be removed in the *reverse* order. This is correct in the overview, but backwards in the function description. Whilst here add Intel's copyright statement and tweak some formatting. Signed-off-by: Chris Wilson Reviewed-by: Joonas Lahtinen --- drivers/gpu/drm/drm_mm.c | 34 ++++++++++++++++++---------------- include/drm/drm_mm.h | 19 +++++++++++++------ 2 files changed, 31 insertions(+), 22 deletions(-) diff --git a/drivers/gpu/drm/drm_mm.c b/drivers/gpu/drm/drm_mm.c index fd2667052c73..767cfd05c628 100644 --- a/drivers/gpu/drm/drm_mm.c +++ b/drivers/gpu/drm/drm_mm.c @@ -1,6 +1,7 @@ /************************************************************************** * * Copyright 2006 Tungsten Graphics, Inc., Bismarck, ND., USA. + * Copyright 2016 Intel Corporation * All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a @@ -31,9 +32,9 @@ * class implementation for more advanced memory managers. * * Note that the algorithm used is quite simple and there might be substantial - * performance gains if a smarter free list is implemented. Currently it is just an - * unordered stack of free regions. This could easily be improved if an RB-tree - * is used instead. At least if we expect heavy fragmentation. + * performance gains if a smarter free list is implemented. Currently it is + * just an unordered stack of free regions. This could easily be improved if + * an RB-tree is used instead. At least if we expect heavy fragmentation. * * Aligned allocations can also see improvement. * @@ -67,7 +68,7 @@ * where an object needs to be created which exactly matches the firmware's * scanout target. As long as the range is still free it can be inserted anytime * after the allocator is initialized, which helps with avoiding looped - * depencies in the driver load sequence. + * dependencies in the driver load sequence. * * drm_mm maintains a stack of most recently freed holes, which of all * simplistic datastructures seems to be a fairly decent approach to clustering @@ -78,14 +79,14 @@ * * drm_mm supports a few features: Alignment and range restrictions can be * supplied. Further more every &drm_mm_node has a color value (which is just an - * opaqua unsigned long) which in conjunction with a driver callback can be used + * opaque unsigned long) which in conjunction with a driver callback can be used * to implement sophisticated placement restrictions. The i915 DRM driver uses * this to implement guard pages between incompatible caching domains in the * graphics TT. * - * Two behaviors are supported for searching and allocating: bottom-up and top-down. - * The default is bottom-up. Top-down allocation can be used if the memory area - * has different restrictions, or just to reduce fragmentation. + * Two behaviors are supported for searching and allocating: bottom-up and + * top-down. The default is bottom-up. Top-down allocation can be used if the + * memory area has different restrictions, or just to reduce fragmentation. * * Finally iteration helpers to walk all nodes and all holes are provided as are * some basic allocator dumpers for debugging. @@ -510,7 +511,7 @@ EXPORT_SYMBOL(drm_mm_insert_node_in_range_generic); * * This just removes a node from its drm_mm allocator. The node does not need to * be cleared again before it can be re-inserted into this or any other drm_mm - * allocator. It is a bug to call this function on a un-allocated node. + * allocator. It is a bug to call this function on a unallocated node. */ void drm_mm_remove_node(struct drm_mm_node *node) { @@ -689,16 +690,16 @@ EXPORT_SYMBOL(drm_mm_replace_node); * efficient when we simply start to select all objects from the tail of an LRU * until there's a suitable hole: Especially for big objects or nodes that * otherwise have special allocation constraints there's a good chance we evict - * lots of (smaller) objects unecessarily. + * lots of (smaller) objects unnecessarily. * * The DRM range allocator supports this use-case through the scanning * interfaces. First a scan operation needs to be initialized with - * drm_mm_init_scan() or drm_mm_init_scan_with_range(). The the driver adds + * drm_mm_init_scan() or drm_mm_init_scan_with_range(). The driver adds * objects to the roaster (probably by walking an LRU list, but this can be * freely implemented) until a suitable hole is found or there's no further - * evitable object. + * evictable object. * - * The the driver must walk through all objects again in exactly the reverse + * The driver must walk through all objects again in exactly the reverse * order to restore the allocator state. Note that while the allocator is used * in the scan mode no other operation is allowed. * @@ -838,9 +839,10 @@ EXPORT_SYMBOL(drm_mm_scan_add_block); * drm_mm_scan_remove_block - remove a node from the scan list * @node: drm_mm_node to remove * - * Nodes _must_ be removed in the exact same order from the scan list as they - * have been added, otherwise the internal state of the memory manager will be - * corrupted. + * Nodes _must_ be removed in exactly the reverse order from the scan list as + * they have been added (e.g. using list_add as they are added and then + * list_for_each over that eviction list to remove), otherwise the internal + * state of the memory manager will be corrupted. * * When the scan list is empty, the selected memory nodes can be freed. An * immediately following drm_mm_search_free with !DRM_MM_SEARCH_BEST will then diff --git a/include/drm/drm_mm.h b/include/drm/drm_mm.h index 0ce8c3678c11..7eeb98b5bf70 100644 --- a/include/drm/drm_mm.h +++ b/include/drm/drm_mm.h @@ -1,6 +1,7 @@ /************************************************************************** * * Copyright 2006-2008 Tungsten Graphics, Inc., Cedar Park, TX. USA. + * Copyright 2016 Intel Corporation * All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a @@ -117,7 +118,10 @@ struct drm_mm { * drm_mm_node_allocated - checks whether a node is allocated * @node: drm_mm_node to check * - * Drivers should use this helpers for proper encapusulation of drm_mm + * Drivers are required to clear a node prior to using it with the + * drm_mm range manager. + * + * Drivers should use this helper for proper encapsulation of drm_mm * internals. * * Returns: @@ -132,7 +136,10 @@ static inline bool drm_mm_node_allocated(const struct drm_mm_node *node) * drm_mm_initialized - checks whether an allocator is initialized * @mm: drm_mm to check * - * Drivers should use this helpers for proper encapusulation of drm_mm + * Drivers should clear the struct drm_mm prior to initialisation if they + * want to use this function. + * + * Drivers should use this helper for proper encapsulation of drm_mm * internals. * * Returns: @@ -152,8 +159,8 @@ static inline u64 __drm_mm_hole_node_start(const struct drm_mm_node *hole_node) * drm_mm_hole_node_start - computes the start of the hole following @node * @hole_node: drm_mm_node which implicitly tracks the following hole * - * This is useful for driver-sepific debug dumpers. Otherwise drivers should not - * inspect holes themselves. Drivers must check first whether a hole indeed + * This is useful for driver-specific debug dumpers. Otherwise drivers should + * not inspect holes themselves. Drivers must check first whether a hole indeed * follows by looking at node->hole_follows. * * Returns: @@ -174,8 +181,8 @@ static inline u64 __drm_mm_hole_node_end(const struct drm_mm_node *hole_node) * drm_mm_hole_node_end - computes the end of the hole following @node * @hole_node: drm_mm_node which implicitly tracks the following hole * - * This is useful for driver-sepific debug dumpers. Otherwise drivers should not - * inspect holes themselves. Drivers must check first whether a hole indeed + * This is useful for driver-specific debug dumpers. Otherwise drivers should + * not inspect holes themselves. Drivers must check first whether a hole indeed * follows by looking at node->hole_follows. * * Returns: