From patchwork Fri Aug 23 06:13:08 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Akihiko Odaki X-Patchwork-Id: 1975879 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=daynix-com.20230601.gappssmtp.com header.i=@daynix-com.20230601.gappssmtp.com header.a=rsa-sha256 header.s=20230601 header.b=aFIM2zW9; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-ppc-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Wqqb06R5mz1yNm for ; Fri, 23 Aug 2024 16:16:28 +1000 (AEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1shNYd-0002kv-97; Fri, 23 Aug 2024 02:13:59 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1shNYb-0002br-CO for qemu-ppc@nongnu.org; Fri, 23 Aug 2024 02:13:57 -0400 Received: from mail-pl1-x62e.google.com ([2607:f8b0:4864:20::62e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1shNYN-00037i-Ib for qemu-ppc@nongnu.org; Fri, 23 Aug 2024 02:13:57 -0400 Received: by mail-pl1-x62e.google.com with SMTP id d9443c01a7336-20202df1c2fso17942575ad.1 for ; Thu, 22 Aug 2024 23:13:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=daynix-com.20230601.gappssmtp.com; s=20230601; t=1724393622; x=1724998422; darn=nongnu.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=0K7RxwRuv9YcnxMw2PosqOuYZUXE/imSqne2Rr+Wijc=; b=aFIM2zW9IUGrpVHHauYwa8lcCNcrIbTy9PQcKTSk8yZTicER7rLQaMdaOYGxa6eLpk o/zzb+eVugQBD6/T58wHXJY/CsYScIth7WEs7S9kvQ2mts+qQrgDpCmHWqgr3MSs8rjv tSivx6JMLEzw714LqFOwJ0pV49WOaDHPAQGIZTVHNhjPDHBVa9lrlUSwxkAWlBwBagki jf7fiqOB83bMmc/p1ujejB5chfyOYd+ODw2h7fLr05FRl68vttfYNA8vk2Mk6qYQQtjQ psmE9jBYZGUcyjkkkhPjzZR1LpDTiqB2aFtmxNBvoQRVjYhNaDdBSLzmR8LjZ8qYZBOU ZjqA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1724393622; x=1724998422; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=0K7RxwRuv9YcnxMw2PosqOuYZUXE/imSqne2Rr+Wijc=; b=RBoK+ayiLlGWWsEzgmPVcRMAoNWiGsIyxOvvZwkj0BxObxfF3GthfiaAHjCRn193vP 4/GX6Z9VqAg4JKFeoNy+eqF4CkPkQIGUVvzE3vRH+rYSzH6yNHzSoBrxerw2SRXtqh7p XmEr+Svb6tvMuc5NFBc+lRjC8D4Bwf2Lf/G/GGYw7c6hsfclq2u2qxYUc8YLaRBMIjHr E1aXldWUTzulm2j0YBzhGXbqwryXSgeCQcJT9KGkk+6/gUIIFLcIb17O3EFoheTj31+D pY8RwovKK8BNVDGQ8QrThSy8W9vmZaZMrv82yZyZDXxVLdF/89v0zclX9fXbVHYXsOpL 0uLQ== X-Forwarded-Encrypted: i=1; AJvYcCUZhFyyfk8Hw4ab3tItycEjXm22PaCynOaPPCRqVM7dWKO28HP6/yfVCpGPmNdPpYzk7CeJrQVpKg==@nongnu.org X-Gm-Message-State: AOJu0Yz6/KMA2z0ekyjPrMSyIckjlF74WSxS6MNrTARo/2l2gVjrNpVy mVPH9btdkDcZVQmVpocDMLqQ1EEg0X35qwjYYYdAWvoxjX5B4qSfv7/dQ5FgDMc= X-Google-Smtp-Source: AGHT+IEAngTao5BZsP0x6bDwn8uzYT07K8nnRx/E7okr5ZhVBwjQFP3fKv8hQyXPsvSnEWre4QJ+nA== X-Received: by 2002:a17:902:ecd2:b0:1fa:97ec:3a4 with SMTP id d9443c01a7336-2039c44c05dmr24395855ad.8.1724393622109; Thu, 22 Aug 2024 23:13:42 -0700 (PDT) Received: from localhost ([157.82.207.23]) by smtp.gmail.com with UTF8SMTPSA id d9443c01a7336-20385566479sm21646755ad.58.2024.08.22.23.13.37 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 22 Aug 2024 23:13:41 -0700 (PDT) From: Akihiko Odaki Date: Fri, 23 Aug 2024 15:13:08 +0900 Subject: [PATCH v4 3/7] memory: Refer to docs/devel/memory.rst for "owner" MIME-Version: 1.0 Message-Id: <20240823-san-v4-3-a24c6dfa4ceb@daynix.com> References: <20240823-san-v4-0-a24c6dfa4ceb@daynix.com> In-Reply-To: <20240823-san-v4-0-a24c6dfa4ceb@daynix.com> To: Eduardo Habkost , Marcel Apfelbaum , =?utf-8?q?Philippe_Mathieu-?= =?utf-8?q?Daud=C3=A9?= , Yanan Wang , John Snow , BALATON Zoltan , Jiaxun Yang , Nicholas Piggin , Daniel Henrique Barboza , David Gibson , Harsh Prateek Bora , Alexey Kardashevskiy , "Michael S. Tsirkin" , =?utf-8?q?Alex_Benn=C3=A9e?= , Peter Xu , Fabiano Rosas , Paolo Bonzini , David Hildenbrand , Thomas Huth , Laurent Vivier , Peter Maydell Cc: qemu-devel@nongnu.org, qemu-block@nongnu.org, qemu-ppc@nongnu.org, Akihiko Odaki X-Mailer: b4 0.14-dev-fd6e3 Received-SPF: none client-ip=2607:f8b0:4864:20::62e; envelope-from=akihiko.odaki@daynix.com; helo=mail-pl1-x62e.google.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_NONE=0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_HELO_TEMPERROR=0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-ppc@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-ppc-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-ppc-bounces+incoming=patchwork.ozlabs.org@nongnu.org memory_region_ref() and memory_region_unref() used to have their own descriptions of "owner", but they are somewhat out-of-date and misleading. In particular, they say "whenever memory regions are accessed outside the BQL, they need to be preserved against hot-unplug", but protecting against hot-unplug is not mandatory if it is known that they will never be hot-unplugged. They also say "MemoryRegions actually do not have their own reference count", but they actually do. They just will not be used unless their owners are not themselves. Refer to docs/devel/memory.rst as the single source of truth instead of maintaining duplicate descriptions of "owner". Signed-off-by: Akihiko Odaki --- include/exec/memory.h | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/include/exec/memory.h b/include/exec/memory.h index b9f0ad09bfad..461e42d03491 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -1219,15 +1219,8 @@ void memory_region_init(MemoryRegion *mr, /** * memory_region_ref: Add a reference to a memory region * - * Whenever memory regions are accessed outside the BQL, they need to be - * preserved against hot-unplug. MemoryRegions actually do not have their - * own reference count; they piggyback on a QOM object, their "owner". * This function adds a reference to the owner. - * - * All MemoryRegions must have an owner if they can disappear, even if the - * device they belong to operates exclusively under the BQL. This is because - * the region could be returned at any time by memory_region_find, and this - * is usually under guest control. + * See docs/devel/memory.rst to know about owner. * * @mr: the #MemoryRegion */ @@ -1236,10 +1229,8 @@ void memory_region_ref(MemoryRegion *mr); /** * memory_region_unref: Remove a reference to a memory region * - * Whenever memory regions are accessed outside the BQL, they need to be - * preserved against hot-unplug. MemoryRegions actually do not have their - * own reference count; they piggyback on a QOM object, their "owner". * This function removes a reference to the owner and possibly destroys it. + * See docs/devel/memory.rst to know about owner. * * @mr: the #MemoryRegion */