From patchwork Thu Mar 7 18:11:01 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 778512 Delivered-To: patch@linaro.org Received: by 2002:a05:6000:47:b0:33e:474f:8c56 with SMTP id k7csp944466wrx; Thu, 7 Mar 2024 10:12:33 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCUaL2uAkkgA45R5h7lRnnGrEWwwqpoUqy3jhYrT4gmGIhnh/IW6Vx5VDRvMceeLaOZtLWeCccsTrx55Ga1tyQUw X-Google-Smtp-Source: AGHT+IHvRO6O67IMw3F4KLdanjpzt042d/rWtV42OqrSlH2xwDnkZESDZE0DrRyYn38qx3I1udno X-Received: by 2002:a81:a183:0:b0:608:c73e:cbaa with SMTP id y125-20020a81a183000000b00608c73ecbaamr18228483ywg.6.1709835152793; Thu, 07 Mar 2024 10:12:32 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709835152; cv=none; d=google.com; s=arc-20160816; b=Xf1EMdN4fb6ZmsS4pf1027XmEijSoALe3do/9NjunaBuKPPgos/0/NzCZCUKtSiVC0 HV+GXnvxEUlZylIBG70JSWKW6UtZHSC0GtWK56GSOqeMnpedZ2jXphqNB8p48av9H/Oo jBe46aE2IyQiQQnxxvZ5tswb1LB+SLewORrgiOmFUyBaCRFzefjC2DtE25IUjUvFqNmL oSYV1e1rfkQKjiU8pjpz4s+DlGqRWwdo9uMfyc8buOyMLPKRFT1Tp0koiMqQiANS4Rhf aRolrdo0QyXS3PLMcJ8BmsHnm0agFACuQ82W7nqx7Fd6C41AM0ZQKcRvf2HwJvQOUK5X N4sA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=FP1Q7CJ3ufIn91uB7tqy2T7aeez+sSRO3vzBm+o+KRQ=; fh=58GrqNPmWxcKasqIC/eaOBnUs8d0lJZe3QlwbsxpY5w=; b=C+50DNlOeyja79LvnmBgGpfVd8T7iGdtdAaUzOK3qqSFlEt5U127/vTQfc1D9Mnz3R izmvzJCmDRAz8gvIlrxWNzE7NViQEULToC7F5T4IMN5WHInJs+/pUiyRwP2gkeuYZXeI ksN1iKr4YQbCKHx9uNbcvrViKT+1Xgv1eTZ/x2FHx0GMaahI4hd9lVCGK7dIy6jzk0le VHVIlxF7MdJPfl20oqmhUO8IeSSaAuk+FJRIGYFOmL1mz5btQ0TIHQNilrwiqOCmVhz0 1mMi5o7bjWyvS5mp53USavBDgCvXJ4KXt0eT4373ISmCG79P5ZELLWBzs/fQbyGjr9Lq vpkw==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=PF3E3R6+; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id y7-20020a05612211a700b004c94c12bc7asi2684570vkn.100.2024.03.07.10.12.32 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2024 10:12:32 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=PF3E3R6+; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1riID3-0002SH-FI; Thu, 07 Mar 2024 13:11:13 -0500 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 1riID1-0002RU-R6 for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:11 -0500 Received: from mail-wr1-x434.google.com ([2a00:1450:4864:20::434]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1riICy-0004RI-PT for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:10 -0500 Received: by mail-wr1-x434.google.com with SMTP id ffacd0b85a97d-33e2774bdc7so926148f8f.0 for ; Thu, 07 Mar 2024 10:11:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709835066; x=1710439866; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=FP1Q7CJ3ufIn91uB7tqy2T7aeez+sSRO3vzBm+o+KRQ=; b=PF3E3R6+j6VLY6Jl+W7pE1u4PqpvsI1BONH18gTe9NfNs1/DvDKobIA2E2i5kydQUI +NJAQcg8iNtvnAzaeoEijg5EFQiqebmEf/w1gr1ESOIrn4bb8K2rjn36eNqFFDUnBHYS owE9WMUwe7C6Evz6IE6oaCajU96qwD2IFpJmoS1VkcB/Cu0TlPhCSw2dQynpwkVZNnpg 8otjnl/o693NAE+fJK4lq1Z/Mh9igEvHRvQ14iIpsSSW/L2Fxzli3Wf9f14vxXgARN+w rqJ8cCnnIJQEK8fj1CIOUMZKM0X09xZi4rUPn30+4FKqocue6Wu0oAoB3V/mIeD4Lud9 j7jQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709835066; x=1710439866; 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=FP1Q7CJ3ufIn91uB7tqy2T7aeez+sSRO3vzBm+o+KRQ=; b=ciTps+SD5xo876v5CDJoXG4LJX1WwDpHYRanBfKGbIe6NkoFNGe3WAszzrmMlGvHz9 XIEKlwB5pJ6g5EUc7vkp6rZI6S8JxgSPu8p3Gznd1a9GRq38N4H5xd/0lTyD4Ik1WTJ6 v1kR2W42moVCIpMgO4UiNQGF1cgfC2HLIukiBgGhB77qVjZoc+R39lTSJTw0q5yXfsAg 3lyu4WNqUwKFyiMzXtgphun+9MuCA+chtI8SMSp8OQSG49c77li5BSHbR6HImVuqh47w v18+IMG0J9UyEj5PYLA3W0uMnNEufmTfVnVavpp514IhrgPqGxobTJpEKMR0j5MaE1rF MHmw== X-Gm-Message-State: AOJu0YwKe1svzlksAb2H6A1LGlgLlRhS00zr6N+WOrd/rPCUTIujdVpy uSS7AgiQ+HQZ6jAA9dDNjGq9xzQHEVMOrr3ZGW1A/dDly9K8vkLi5781m3v8bOg= X-Received: by 2002:adf:f584:0:b0:33e:726d:e963 with SMTP id f4-20020adff584000000b0033e726de963mr656930wro.17.1709835066451; Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id v9-20020adfedc9000000b0033e712b1d9bsm713243wro.77.2024.03.07.10.11.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 8CBEB5F8E1; Thu, 7 Mar 2024 18:11:05 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Elena Ufimtseva , John G Johnson , Jagannathan Raman , Mahmoud Mandour , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Paolo Bonzini , Alexandre Iooss , Peter Xu , Manos Pitsidianakis , Markus Armbruster , Eduardo Habkost , Juan Quintela , Thomas Huth , Richard Henderson , peter.maydell@linaro.org, David Hildenbrand Subject: [PATCH 1/5] scripts/kernel-doc: teach kdoc about QLIST_ macros Date: Thu, 7 Mar 2024 18:11:01 +0000 Message-Id: <20240307181105.4081793-2-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240307181105.4081793-1-alex.bennee@linaro.org> References: <20240307181105.4081793-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::434; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x434.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@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-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org The kernel-doc script does some pre-processing on structure definitions before parsing for names. Teach it about QLIST and replace with simplified structures representing the base type. Signed-off-by: Alex Bennée --- scripts/kernel-doc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 240923d509a..26c47562e79 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1226,7 +1226,14 @@ sub dump_struct($$) { # replace DECLARE_KFIFO_PTR $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; - my $declaration = $members; + # QEMU Specific Macros + + # replace QLIST_ENTRY with base type and variable name + $members =~ s/QLIST_ENTRY\(([^)]+)\)\s+([^;]+)/$1 \*$2/gos; + # replace QLIST_HEAD, optionally capturing an anonymous struct marker, and capture type and variable name + $members =~ s/QLIST_HEAD\(\s*,\s*([^)]+)\)\s+([^;]+)/struct { $1 *lh_first; } $2/gos; + + my $declaration = $members; # Split nested struct/union elements as newer ones while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) { From patchwork Thu Mar 7 18:11:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 778510 Delivered-To: patch@linaro.org Received: by 2002:a05:6000:47:b0:33e:474f:8c56 with SMTP id k7csp944313wrx; Thu, 7 Mar 2024 10:12:17 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCX39F26qWpTg0K0QmCxTdTtTUSqAxuSFZXY2qc4koCYIeLpGWebfTQjFQ+2nZxXZ1WdbtdneKOAG+8JrbmOy6Ws X-Google-Smtp-Source: AGHT+IHDLpZNZQ9q83xA9YwKasDP0yVcocT5YOZp/xYX5ACKciUnixNWx9T0XuKNwgbJqVSJtg2t X-Received: by 2002:ad4:5250:0:b0:690:48fd:3a1f with SMTP id s16-20020ad45250000000b0069048fd3a1fmr9449315qvq.33.1709835136775; Thu, 07 Mar 2024 10:12:16 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709835136; cv=none; d=google.com; s=arc-20160816; b=NezjfvR3a78takOSHk+drcRguADVVFgSuW6YyZt8d1ujhn/OXZctMbM6dg30D7121w GrgnJ+npyRC6So3lJraQKWmbCLlk9zOrB729BrA4AUZnUERDkjw6gSd1H4iTBWfXrPnH PsdnvAwvGatHYirEKMSiLtLqGUkZnpSwdZ3/XvAAgxP9MhrH1DWEF40AB5quSW6Ss0tY vzUB7K1cW5HDuQMH5SE1JF3w7VlHLZB6l/eLm0fNIfwPWWbgeG4dalDf3dpZCRwVZnuD JD3MnO084Vy1bByNC/K0o06uRRTCgHkXSM59GGcwEHUZXM5NU2LycLGSJicLJlkpCwtk /A1Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=3M3p0P+gb/3iG0ankC+FJRfdeFsceOte83WPS3Mcews=; fh=58GrqNPmWxcKasqIC/eaOBnUs8d0lJZe3QlwbsxpY5w=; b=oJz+tgF6spSXkhlWb9iqt9/XUWG816U44KHX162TLRhqGY9kbCTXMiWAjNJiqJkgiC Kxl0tDJyfcSp1SVFva+wLzSM+zE0Kx6foBf8FLvrHe8yVEMDYyK3hhInPZI3sKD8bL3h b3c6/yav84lW5gJvbHvnbleA2Uef9SalmCqe6cRmCywzWkL1ye19KbhTn3tTnNhI+1eK TOwKKQYFAXZE2xZ3y/qBiGSbRRVLh3BYobWZVN24Fg1AZLTuTvufMfi8UnmOuhxgBKpm XTyODS8vW1WWMg234/90gEHPXSgaVDoTXi+TDr7Ts7vqH1EueeAtxnxd475xLexNJYND i/lg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=iDLU831J; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id jo25-20020a056214501900b0068fb8db15fdsi4017350qvb.54.2024.03.07.10.12.16 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2024 10:12:16 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=iDLU831J; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1riID5-0002T0-F0; Thu, 07 Mar 2024 13:11:15 -0500 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 1riID3-0002SG-Dl for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:13 -0500 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1riID0-0004SH-NQ for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:13 -0500 Received: by mail-wm1-x32e.google.com with SMTP id 5b1f17b1804b1-413131d40f4so161265e9.3 for ; Thu, 07 Mar 2024 10:11:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709835069; x=1710439869; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=3M3p0P+gb/3iG0ankC+FJRfdeFsceOte83WPS3Mcews=; b=iDLU831J3qFB5O41/mAa+XHq51RT6BCHv+AgumlH3F4bWe17aR5icyTSip0aZ+AE/r 6VwGdXwOBRoScBgPzJ4t6LsVC49tg1vTteILEtVFRUcgMr0cY3p3z+2Iit78O2MYLGnA a0qrO96nEQFK1ShJWOLgYUFSnC2lYU0ZBZHDjA1eWPf+CVDA8Hf7OveN75l8K4QGchT7 l4/Igkzih/B64l85uuqIMMI2GlUlpED7e4NucRcEdgVMbGDjNJrZXDv5QmQzfvK0WE87 PsJs+TZ2sz1lwNKJgKXra9590Yd9Trw9sqxkbZDnN/YD2Wv5jvy3vNkWD6sY/HLuF8/Z v6ZA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709835069; x=1710439869; 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=3M3p0P+gb/3iG0ankC+FJRfdeFsceOte83WPS3Mcews=; b=Dxqp5l/GZ7S7gLrakra3DdJfERgghB2Y4TX0YRei3CzwbXTryHwBr/S5d+2AHUKJzk AlG/g7A1GT5vhxmZWIMPUNqtKomoF1bHR/A41qmEZOzF7rOxibO+uHdry41NpFIwMFz4 y6rM6Z9QO+IRuYsFIy3iy+ZTAo9yMblEtXiszsbVUkJoqkhMJJJgiV2fLtN5x5VACya3 OnZ840TypGqcuk39XNufK/cC5R8tW2rTAVY5huea0GY2Y0kB86/hfMfvZwqUKWFugZCz vygBKeJW4XEZtJ4/Eh7APhHfX3JZhadCVl5s8SxraHweRMIHBM2kJK22XQassT7DgCg4 BWYA== X-Gm-Message-State: AOJu0YyDFM5RwdsKFiYaW/59f1jG4GG2gvQgiaKgLpaSF6Lh461A6e2n 5QiUuwzdV/i9W6S2wgvon+WWKHxY7D1npFoZmTIuPyAniMCFgALsis3imYWf3L0= X-Received: by 2002:a05:600c:4e8e:b0:412:e70a:ab8a with SMTP id f14-20020a05600c4e8e00b00412e70aab8amr8121212wmq.25.1709835069247; Thu, 07 Mar 2024 10:11:09 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id je13-20020a05600c1f8d00b00412fb4f5756sm3503948wmb.27.2024.03.07.10.11.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id A13075F94F; Thu, 7 Mar 2024 18:11:05 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Elena Ufimtseva , John G Johnson , Jagannathan Raman , Mahmoud Mandour , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Paolo Bonzini , Alexandre Iooss , Peter Xu , Manos Pitsidianakis , Markus Armbruster , Eduardo Habkost , Juan Quintela , Thomas Huth , Richard Henderson , peter.maydell@linaro.org, David Hildenbrand Subject: [PATCH 2/5] docs: include ramblock.h in the memory API docs Date: Thu, 7 Mar 2024 18:11:02 +0000 Message-Id: <20240307181105.4081793-3-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240307181105.4081793-1-alex.bennee@linaro.org> References: <20240307181105.4081793-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32e; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@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-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org The RAMBlock concept is fairly central to RAM-like MemoryRegions so lets update the structure documentation and include in the docs. Signed-off-by: Alex Bennée --- docs/devel/memory.rst | 1 + include/exec/ramblock.h | 76 +++++++++++++++++++++++++++-------------- 2 files changed, 52 insertions(+), 25 deletions(-) diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst index 69c5e3f914a..ed24708fce3 100644 --- a/docs/devel/memory.rst +++ b/docs/devel/memory.rst @@ -369,4 +369,5 @@ callbacks are called: API Reference ------------- +.. kernel-doc:: include/exec/ramblock.h .. kernel-doc:: include/exec/memory.h diff --git a/include/exec/ramblock.h b/include/exec/ramblock.h index 848915ea5bf..eb2416b6f66 100644 --- a/include/exec/ramblock.h +++ b/include/exec/ramblock.h @@ -24,68 +24,94 @@ #include "qemu/rcu.h" #include "exec/ramlist.h" +/** + * struct RAMBlock - represents a chunk of RAM + * + * RAMBlocks can be backed by allocated RAM or a file-descriptor. See + * @flags for the details. For the purposes of migration various book + * keeping and dirty state tracking elements are also tracked in this + * structure. + */ struct RAMBlock { + /** @rcu: used for lazy free under RCU */ struct rcu_head rcu; + /** @mr: parent MemoryRegion the block belongs to */ struct MemoryRegion *mr; + /** @host: pointer to host address of RAM */ uint8_t *host; - uint8_t *colo_cache; /* For colo, VM's ram cache */ + /** @colo_cache: For colo, VM's ram cache */ + uint8_t *colo_cache; + /** @offset: offset into host backing store??? or guest address space? */ ram_addr_t offset; + /** @used_length: amount of store used */ ram_addr_t used_length; + /** @max_length: for blocks that can be resized the max possible */ ram_addr_t max_length; + /** @resized: callback notifier when block resized */ void (*resized)(const char*, uint64_t length, void *host); + /** @flags: see RAM_* flags in memory.h */ uint32_t flags; - /* Protected by the BQL. */ + /** @idstr: Protected by the BQL. */ char idstr[256]; - /* RCU-enabled, writes protected by the ramlist lock */ + /** + * @next: next RAMBlock, RCU-enabled, writes protected by the + * ramlist lock + */ QLIST_ENTRY(RAMBlock) next; + /** @ramblock_notifiers: list of RAMBlockNotifier notifiers */ QLIST_HEAD(, RAMBlockNotifier) ramblock_notifiers; + /** @fd: fd of backing store if used */ int fd; + /** @fd_offset: offset into the fd based backing store */ uint64_t fd_offset; + /** @page_size: ideal page size of backing store*/ size_t page_size; - /* dirty bitmap used during migration */ + /** @bmap: dirty bitmap used during migration */ unsigned long *bmap; /* * Below fields are only used by mapped-ram migration */ - /* bitmap of pages present in the migration file */ + + /** @file_bmap: bitmap of pages present in the migration file */ unsigned long *file_bmap; - /* - * offset in the file pages belonging to this ramblock are saved, - * used only during migration to a file. - */ + /** @bitmap_offset: offset in the migration file of the bitmaps */ off_t bitmap_offset; + /** @pages_offset: offset in the migration file of the pages */ uint64_t pages_offset; - /* bitmap of already received pages in postcopy */ + /** @receivedmap: bitmap of already received pages in postcopy */ unsigned long *receivedmap; - /* - * bitmap to track already cleared dirty bitmap. When the bit is - * set, it means the corresponding memory chunk needs a log-clear. - * Set this up to non-NULL to enable the capability to postpone - * and split clearing of dirty bitmap on the remote node (e.g., - * KVM). The bitmap will be set only when doing global sync. + /** + * @clear_bmap: bitmap to track already cleared dirty bitmap. When + * the bit is set, it means the corresponding memory chunk needs a + * log-clear. Set this up to non-NULL to enable the capability to + * postpone and split clearing of dirty bitmap on the remote node + * (e.g., KVM). The bitmap will be set only when doing global + * sync. * * It is only used during src side of ram migration, and it is * protected by the global ram_state.bitmap_mutex. * * NOTE: this bitmap is different comparing to the other bitmaps * in that one bit can represent multiple guest pages (which is - * decided by the `clear_bmap_shift' variable below). On + * decided by the @clear_bmap_shift variable below). On * destination side, this should always be NULL, and the variable - * `clear_bmap_shift' is meaningless. + * @clear_bmap_shift is meaningless. */ unsigned long *clear_bmap; + /** @clear_bmap_shift: number pages each @clear_bmap bit represents */ uint8_t clear_bmap_shift; - /* - * RAM block length that corresponds to the used_length on the migration - * source (after RAM block sizes were synchronized). Especially, after - * starting to run the guest, used_length and postcopy_length can differ. - * Used to register/unregister uffd handlers and as the size of the received - * bitmap. Receiving any page beyond this length will bail out, as it - * could not have been valid on the source. + /** + * @postcopy_length: RAM block length that corresponds to the + * @used_length on the migration source (after RAM block sizes + * were synchronized). Especially, after starting to run the + * guest, @used_length and @postcopy_length can differ. Used to + * register/unregister uffd handlers and as the size of the + * received bitmap. Receiving any page beyond this length will + * bail out, as it could not have been valid on the source. */ ram_addr_t postcopy_length; }; From patchwork Thu Mar 7 18:11:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 778511 Delivered-To: patch@linaro.org Received: by 2002:a05:6000:47:b0:33e:474f:8c56 with SMTP id k7csp944458wrx; Thu, 7 Mar 2024 10:12:32 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCXm2MaiO0Ojjp+drIdt54K35YuqQEr2Q3rrgOwxI5JG7VdsjCdZzEjvsdJtHCj/ObHyP65w69oqZ709An96fzwn X-Google-Smtp-Source: AGHT+IG3id7v3vouo6Ml2jQPBPaPk0DOjx6sG/T2GzxNWaOOSQdqbVc9FcJIPJSFZ8MxpNzj5FpG X-Received: by 2002:a05:6102:3a55:b0:472:7a4f:1dac with SMTP id c21-20020a0561023a5500b004727a4f1dacmr8495160vsu.16.1709835152134; Thu, 07 Mar 2024 10:12:32 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709835152; cv=none; d=google.com; s=arc-20160816; b=WNBk28kwA1DfVPU/M69IIB7zxXvwmD9yrOjBL3Pftyr3VdqC5Zv7kvfbISn+533qHh DtVQpo6G4vUa9ur4tAbVZvj/LQbeu4LH8kynEXnTlt4ZI+A+VO5J92AzuvXGAGK+ssfQ kKKBXsgrbsRNlOPlyAjQFtaV0OlGusucUAi+kUnDgfnrALMVYu5KWltnnTJ/IajY9B5F iCzyvwniZN6lvk/PctJTPZjBgBOgvszeo/joLo+5aG2Blnyf0J/kOybSkAHWLAu1XQPW RtLgzKgjCXV/H2KE9qNGMJ7DCPECqOKHyftYDgI5fBU7RYB2c5++Wrzswa4n1PXn9N+k hR0A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=JeVw/zqoXIefq1k86hMLBghVqeIdQrvH247p0frdwQw=; fh=58GrqNPmWxcKasqIC/eaOBnUs8d0lJZe3QlwbsxpY5w=; b=UTvsjmSi89XjcVeKe8RJNXC//QFUlHXBnxxPuUsQdZ37vAh6iZfG7TFy94Ebp2HpFo oqD5GeATmriE51dAqiGBOSgHmuU/EuBHGODL51UfoERB7UZNXB0GRDIjnSy8/zwbxcpe RYCdQtq16zjCFrK262wPYRmzE2dCKmeW8V9bJ2wIiKxQIHkQCTgoi4MLe0XY5G5uP2Rl SmOdiEzEStugGQ088P04411T4jnto7EBaj45U6lnoB5+/7tjyK3FiYR7WuaPvQMKlrMi l/QiR1VeUeYU2mnzW5gwqGGFsvIFv9rGBCxctYZkMrQj1dHP4O7pK5k5J7B8zSM182Bo OzYw==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=xUZ3rC9K; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id 91-20020a9f23e4000000b007d6bd7a8f17si244959uao.26.2024.03.07.10.12.31 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2024 10:12:32 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=xUZ3rC9K; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1riID3-0002SJ-Ke; Thu, 07 Mar 2024 13:11:13 -0500 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 1riID1-0002RV-Uk for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:11 -0500 Received: from mail-lf1-x12e.google.com ([2a00:1450:4864:20::12e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1riICy-0004Rt-Q4 for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:11 -0500 Received: by mail-lf1-x12e.google.com with SMTP id 2adb3069b0e04-51344bebe2fso21418e87.2 for ; Thu, 07 Mar 2024 10:11:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709835067; x=1710439867; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=JeVw/zqoXIefq1k86hMLBghVqeIdQrvH247p0frdwQw=; b=xUZ3rC9KI/jRlXyuhj3uRmFfSnmJ9XjvWZN7xp38mXH7M3dKWzgQvdpWgpqBnB1gWZ nOMhzHDd+XmJbwYiszlmzP1b3kIfx3vhknqGSSpRagjEtbIBC8Cl1wJD6lN2RUs/7J6T JFdSB2RUE2pGHQUZAbSOQExLqXVQPdWaj4PiRzVHmSUF/ppYts8kLSMZzBiqG1/xyysH u352s9OWD0PpLDCl4AJLUAijHrh9q/g9JPBM9XupR9KN6Jn4pQJha7muJPPyFAuxQJld 1msBTCi8Xp2tVXRwGU0Xor+Q4/IACEo3Ldvc+FHEm5YurSNw5Vd5RFQ1IzRrxA2ldwPT oJmQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709835067; x=1710439867; 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=JeVw/zqoXIefq1k86hMLBghVqeIdQrvH247p0frdwQw=; b=qZv9w18R4r2Z3F1xClxS6ZdX4rK6wIHn3R7bsvJJJ3KQGVPOMm47/cDUE5GZCp4lg0 I/4Z0EgVLQV4XzTzm60z21ziKJlASqqyht4d6owgKyUF/aQAq03UnJu+rrCAuG3f1tIj YZrbHPFVEZeKKreWjzO30/U9jES/qc93HESsuSHlikwoSoWPkmBB+RoRvm3TgHTNObKK Tspmi4diluUg6SQvqzBi2qIf13jP1fOQRyRdbs+CmwKssyq8cp/SlffHXCkJRvNr1Zvm ShO0UI2QSzjDZysawHomKVcC/h27ZRV9q1/+CvYbDKTowFKc75NmYXXgwVpos5XUBse4 JbFA== X-Gm-Message-State: AOJu0Yza6a4CxyeapYdixxfhVr21HghS6AUKUlGQW1cn2lgtA7FppFLz f1etWPbZJVKsRc+F/2lfp3vKClY6NVNpVhTsCPqPsOCUpUYVRY6LibgGGxVx87M= X-Received: by 2002:a19:9104:0:b0:513:1aa4:a374 with SMTP id t4-20020a199104000000b005131aa4a374mr1913064lfd.2.1709835066857; Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id l37-20020a05600c1d2500b0041315f221c7sm713272wms.16.2024.03.07.10.11.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id B35F45F950; Thu, 7 Mar 2024 18:11:05 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Elena Ufimtseva , John G Johnson , Jagannathan Raman , Mahmoud Mandour , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Paolo Bonzini , Alexandre Iooss , Peter Xu , Manos Pitsidianakis , Markus Armbruster , Eduardo Habkost , Juan Quintela , Thomas Huth , Richard Henderson , peter.maydell@linaro.org, David Hildenbrand Subject: [PATCH 3/5] include/exec: remove warning_printed from MemoryRegion Date: Thu, 7 Mar 2024 18:11:03 +0000 Message-Id: <20240307181105.4081793-4-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240307181105.4081793-1-alex.bennee@linaro.org> References: <20240307181105.4081793-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::12e; envelope-from=alex.bennee@linaro.org; helo=mail-lf1-x12e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@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-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Since d197063fcf9 (memory: move unassigned_mem_ops to memory.c) this field is unused. Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Peter Xu --- include/exec/memory.h | 1 - 1 file changed, 1 deletion(-) diff --git a/include/exec/memory.h b/include/exec/memory.h index 8626a355b31..17b741bc4f5 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -814,7 +814,6 @@ struct MemoryRegion { bool terminates; bool ram_device; bool enabled; - bool warning_printed; /* For reservations */ uint8_t vga_logging_count; MemoryRegion *alias; hwaddr alias_offset; From patchwork Thu Mar 7 18:11:04 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 778509 Delivered-To: patch@linaro.org Received: by 2002:a05:6000:47:b0:33e:474f:8c56 with SMTP id k7csp944120wrx; Thu, 7 Mar 2024 10:11:49 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCU1Ln2ckY3MC1t+S2JrYDQPVThLlaxxB8DHSjnkqiRJSaAvO16uEWY/qK2UIcaA6zKCBiisSqwOt9VxvyfQp83c X-Google-Smtp-Source: AGHT+IFqqGFx347SAgWeZaMmtwrh42FRCrC/eE3Ue8oygi6D7CY8rSgKchLFYPB/+XcGDX/LLp/u X-Received: by 2002:a0c:bf46:0:b0:690:5dcc:31e7 with SMTP id b6-20020a0cbf46000000b006905dcc31e7mr9093838qvj.25.1709835109137; Thu, 07 Mar 2024 10:11:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709835109; cv=none; d=google.com; s=arc-20160816; b=Wf53JWoSQFJBzzJ3CKstJPMxp/pmwMx7rGbN+Jh5qJWXHThJEFNTvr2UU86pr8QbRG NbS4v/v57zzm763PXXwPwNAp+V/5F6ioXqMil7O3v5UTtOM1vV0TIO1DJ6smoh1lAfev ljlARoXYm6qby7FkfS/NT3I0AdJnCB+M2kvQ8Ln05+Gv/SV6hABvboW3NtpIf2KlVWU+ WdBaHIKSJmiiO1xQyuYp9c5ZyecnCaHgMTW0kxPSQDlCM5HjLDl28SJcB9AInu0AJ/jb WrahxK3k/xI7rf7Aq8sfrlHzE8gX12j5mhknaLeBNpi47XHy/1ZZpVDZU7+jJ1JkIDkT 3zpw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=mZ/K3PBuLzDgapFrWwRRkSM6VPt2uSmyXpXI8zQY5GY=; fh=58GrqNPmWxcKasqIC/eaOBnUs8d0lJZe3QlwbsxpY5w=; b=EPjGva9lvrZ4r4P9+GpQ0e6KlC22TelxzQTi05Hi/g/PtvJlQluNwvSVzRzZ55BcdD oaBVFaLhX48iV+L089UGXkT7KCphe7PSgjmmnzMyVkb8dl/Wz4hKuMDxA0wI04I+pguw 2viMKC36KyIhblPJZ6lXUjIYd8XZmK6m7GylS3Yn+zgDLnB3W9ceUbltoSb6HEYXEene 8BUJB9F/3EXwa0xXu63EaqH/TK6PuEfEp7t0+ctVdKyiHpXYdUrbDjo1Y2810AdgyPz9 ZPskEAOlK3M9AorK8tOPnZJKmDhSaiQQj4wxC2gWhjuvpz6dtVMwTe/tRQG4HTHlGDSE ThmA==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=Df+asfrA; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id ow2-20020a0562143f8200b006903ca3f5b3si17209990qvb.129.2024.03.07.10.11.48 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2024 10:11:49 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=Df+asfrA; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1riID7-0002U4-9p; Thu, 07 Mar 2024 13:11:17 -0500 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 1riID2-0002Rp-IL for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:12 -0500 Received: from mail-lf1-x129.google.com ([2a00:1450:4864:20::129]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1riICy-0004Rs-Q6 for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:12 -0500 Received: by mail-lf1-x129.google.com with SMTP id 2adb3069b0e04-51336ab1fb7so34595e87.1 for ; Thu, 07 Mar 2024 10:11:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709835067; x=1710439867; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=mZ/K3PBuLzDgapFrWwRRkSM6VPt2uSmyXpXI8zQY5GY=; b=Df+asfrAa+JCIwaLmhJZx67qTcFJ/1ZLqlUfcKKmTJ3x9BcWMHFd7nR0i0Yangw+4v cio2PAW4lnJFWoUguZ2pY2uGpf0Ac8BjyFYDFj0oINBUNrFsi676jIg3rrq4iIdpKx1Q FPd7B8OE9W749wfX9MC5oRx2/HSEeKeh52rwdAx2IwFWLo6ld8lpeO2tEqHLNS7dwkPh G7bwgI0qcEFSyzdjo13211cHFHY9SrWOUydW00YoHGd4wJMzXjOOyoeXyLGcLf+y+nS4 7BmzGA2cKPh6nHeLVjK+lLPs1RedCSQTU3eBNN73lCa1NBNOCrbqE2Wtz9OVJDHqQ0ga cehg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709835067; x=1710439867; 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=mZ/K3PBuLzDgapFrWwRRkSM6VPt2uSmyXpXI8zQY5GY=; b=AURzWtTPMBhl4A9jb37ir1r4tQs97nnlwnM4/zrKT7yuleA8XM01Y24b7MTZvyN3wF vKbiNtsGZtVCwTegaf2t1iDuq9U1NkhTT0KIM4ycuTHGjiQR6mQXsau4P+vuyC4RSpFf YR9xdthxPwfVz8ml/OG1FVkBxhWrverZEbIZrt9cnQw2WbwSmcIMqo0SCuyvwlbVjHKH MWQf6NkbsngYtfCFOqglE8oa6/bXUrNaJiVTmizqTUWHsCSGfS7AvvuxJmOi2URiH/FQ AQYZZS9cMcKOCGgBiiSisURBGtt8aySHGnP5L/u572o+Cahwbl2xRvsGPRnI1M0XpT4H X3vw== X-Gm-Message-State: AOJu0YzzbmUUbBMHvP4acwz5sEMPxv/qAVDg2vkEHtxlQEuCmtxs37QH 1g74RV2YoFdfUy1tm/wWX7qlPhtGm+9W604xfX3xtC2jCLwtYm3FaXEGDZ2O+CA= X-Received: by 2002:a19:ca4c:0:b0:512:b696:e312 with SMTP id h12-20020a19ca4c000000b00512b696e312mr1839900lfj.46.1709835066664; Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id fs23-20020a05600c3f9700b00412f195426dsm3343613wmb.15.2024.03.07.10.11.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 07 Mar 2024 10:11:06 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id C8A745F954; Thu, 7 Mar 2024 18:11:05 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Elena Ufimtseva , John G Johnson , Jagannathan Raman , Mahmoud Mandour , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Paolo Bonzini , Alexandre Iooss , Peter Xu , Manos Pitsidianakis , Markus Armbruster , Eduardo Habkost , Juan Quintela , Thomas Huth , Richard Henderson , peter.maydell@linaro.org, David Hildenbrand Subject: [PATCH 4/5] include/exec: annotate all the MemoryRegion fields Date: Thu, 7 Mar 2024 18:11:04 +0000 Message-Id: <20240307181105.4081793-5-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240307181105.4081793-1-alex.bennee@linaro.org> References: <20240307181105.4081793-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::129; envelope-from=alex.bennee@linaro.org; helo=mail-lf1-x129.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@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-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Signed-off-by: Alex Bennée --- include/exec/memory.h | 47 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/include/exec/memory.h b/include/exec/memory.h index 17b741bc4f5..312ed564dbe 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -778,9 +778,48 @@ bool memory_get_xlat_addr(IOMMUTLBEntry *iotlb, void **vaddr, typedef struct CoalescedMemoryRange CoalescedMemoryRange; typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd; -/** MemoryRegion: - * - * A struct representing a memory region. +/** + * struct MemoryRegion - represents a memory region + * @parent_obj: parent QOM object for the region + * @romd_mode: if true ROM devices accessed directly rather than with @ops + * @ram: true if a RAM-type device with a @ram_block + * @subpage: true if region covers a subpage + * @readonly: true for RAM-type devices that are readonly + * @nonvolatile: true for nonvolatile RAM-type devices (e.g. NVDIMM) + * @rom_device: true for a ROM device, see also @romd_mode + * @flush_coalesced_mmio: true to flush any queued coalesced MMIO + * operations before access + * @unmergeable: this section should not get merged with adjacent + * sections + * @dirty_log_mask: dirty events region cares about (see DIRTY_ flags) + * @is_iommu: true if part of an IOMMU device + * @ram_block: backing @RamBlock if @ram is true + * @owner: base QOM object that owns this region + * @dev: base Device that owns this region + * @ops: access operations for MMIO or @romd_mode devices + * @opaque: @dev specific data, passed with @ops + * @container: parent `MemoryRegion` + * @mapped_via_alias: number of times mapped via @alias, container + * might be NULL + * @size: size of @MemoryRegion + * @addr: physical hwaddr of @MemoryRegion + * @destructor: cleanup function when @MemoryRegion finalized + * @align: alignment requirements for any physical backing store + * @terminates: true if this @MemoryRegion is a leaf node + * @ram_device: true if @ram device should use @ops to access + * @enabled: true once initialised, false once finalized + * @vga_logging_count: count of memory logging clients + * @alias: link to aliased @MemoryRegion + * @alias_offset: offset into aliased region + * @priority: priority when resolving overlapping regions + * @subregions: list of subregions in this region + * @subregions_link: next subregion in the chain + * @coalesced: list of coalesced memory ranges + * @name: name of memory region + * @ioeventfd_nb: count of @ioeventfds for region + * @ioeventfds: ioevent notifiers for region + * @rdm: if exists see #RamDiscardManager + * @disable_reentrancy_guard: if true don't error if device accesses itself */ struct MemoryRegion { Object parent_obj; @@ -806,7 +845,7 @@ struct MemoryRegion { const MemoryRegionOps *ops; void *opaque; MemoryRegion *container; - int mapped_via_alias; /* Mapped via an alias, container might be NULL */ + int mapped_via_alias; Int128 size; hwaddr addr; void (*destructor)(MemoryRegion *mr); From patchwork Thu Mar 7 18:11:05 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 778508 Delivered-To: patch@linaro.org Received: by 2002:a05:6000:47:b0:33e:474f:8c56 with SMTP id k7csp944119wrx; Thu, 7 Mar 2024 10:11:49 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCXs7CM+HWIGGOiPrKakgowiZussJpFr6HAvKQNg/0/FqBr8vyvLwacuzMvMWOeWg8jW8RFsQVyZz3Sp7V3bXKU7 X-Google-Smtp-Source: AGHT+IEPF9ryc3Bj8A1f4oZDGv6GTjFoGoYuUaUiFLt40oE4kB0d1c0Q7KYLxq8SADiAkxDfrKoA X-Received: by 2002:a05:6358:7e8a:b0:17b:f9c0:14ab with SMTP id o10-20020a0563587e8a00b0017bf9c014abmr10046331rwn.28.1709835109163; Thu, 07 Mar 2024 10:11:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709835109; cv=none; d=google.com; s=arc-20160816; b=cdzkwwcX02Kk6BwnUFBa3vuI8cPe9iZ9M97UBhwhB5uwsjP2iB0pFo8K0BTwptAxNr /4cpcnruBXCqg0BcHb5mmm6ZlbT2LRuUDdPfX7JwZV9EQbU4W3L0Uw+8m1eqxjRPsoMN Oza8MHe1uilC2tLnE3uMbBBNTLZ3BsEH1T4aXTZesJcXEddIvAPbfFALERILSOyGkrk8 aBQb11yDGemwpX1bBr52HI1lnmjjEw7TMgPgYzxVA7bydXB0ICBxg/kWzulgFS3DUbMP 52AGNnalmHzkc2UCsJKF8jiN45LEZuqYcI+wqgPn9+8v/jO4EDmTqyto8OIL1nrmOzXu BWzQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=oL9yBj/gQtPHfe3iZvA3nzS0UYJu6qOXKEO5ee6KSH8=; fh=58GrqNPmWxcKasqIC/eaOBnUs8d0lJZe3QlwbsxpY5w=; b=olrXaphmfhOOa5uIhHrYV6ydj0eQNkfkbopTxnWsWhQgX7o8iW7kOuQuWIV7sTPEy8 vmpZLfVnkJyZhg/YeIoSb+AOOAexD/f40v7kZivkh6DXzCkur8q5WbLaQjkNdQ1omgKS NnWBmqAFy9Dr8fYW/zLlyA84e3QHrUEwGXWJubvM6FAbWK3n8G6q59JBGYD9vrD7+qC2 tZGRBAwyeK6ak26wwaUx+V/AKBWJoDmUMIfss+mfiNp4GIYDNB4KcUPTL3+Cv7DlM24d nrzmslCPvxqb4S6tcwgNmN+wFq9xeNRcMvvz7mKVjMxbYW6B596SWl8+8ksG/Ewe+dtu kX0w==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=u4YfgHel; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id h4-20020ac85844000000b0042ed1303b2dsi12906448qth.264.2024.03.07.10.11.48 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2024 10:11:49 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=u4YfgHel; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1riID5-0002TO-KH; Thu, 07 Mar 2024 13:11:15 -0500 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 1riID4-0002SV-54 for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:14 -0500 Received: from mail-wm1-x335.google.com ([2a00:1450:4864:20::335]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1riID2-0004SJ-4q for qemu-devel@nongnu.org; Thu, 07 Mar 2024 13:11:13 -0500 Received: by mail-wm1-x335.google.com with SMTP id 5b1f17b1804b1-412f62edf25so8876145e9.3 for ; Thu, 07 Mar 2024 10:11:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709835070; x=1710439870; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=oL9yBj/gQtPHfe3iZvA3nzS0UYJu6qOXKEO5ee6KSH8=; b=u4YfgHelJoWz1Yvc63MUBFgP9eYbwqdo6DB6Up8oI7912MHFzugytCigz0bnGBJIB1 CxtOZN0U09Mc5hsiM/Wy9TGwO6c3jalcpqg2N9PZqp0KJWkoT7mSPoFh25DtJYqi2x1K EAdwICXgGwQlfc2rKBneJP5kuPYFSSMwzCaMadJb2q0DilF+mIWCVw46kXiJyiA6ufMl Vl9iPdFeRWZEIKetyYGlguPpSRwxpp3tHW9vd/sDfvPXDl7HvRj5wh6ddzVahB8yTd4J t/ubPVsFpkHD58F9Rc2CrLTEcKsGM+QI5pPN3X+vLFDca8oDq0gOcV8YeMFnj+1tRXS9 7l6A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709835070; x=1710439870; 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=oL9yBj/gQtPHfe3iZvA3nzS0UYJu6qOXKEO5ee6KSH8=; b=O7rUp1oUEpJO2cCtPfk+jIt1vVigbHoJM7sydONscI+C/c8WxXnVH6oibebNF6nYRN RIMrKtq6XWXLnmDxhbsjLbfNnSv0sDUDohvonWlXvrDaUm5oO/3uin/2sSfYn/b7qogQ 1vrXCd4j7rnkWiBqG2PbRT8+Db0yOiqJCCSHIHRkXujiqqcIq8Jz+9cEvCk3iEebjPMX b8fv9ohaUiVN+mj75xgwXs7gNCf47qm0ghhkWlYO09V3fxqyW3xHg3/0otWxh0DLXa0u 3SpbrNTZ3FAcfL7x/VGp8igvIpRHYn5faxwKXK2tkus0MobNMgeLNJ4m0EnvT8pf6HdS HDvw== X-Gm-Message-State: AOJu0YxdzHpUzc94wtiCb8ynMA4qa0r910Jajag6HlLLxfpOxASPwRYe pi1ri2BQ4NRgMva5cWy8cywk49yvGMTGYoxfe/t1LahsforJUPaZrNLwIWteDXI= X-Received: by 2002:a05:600c:1c84:b0:412:e555:818c with SMTP id k4-20020a05600c1c8400b00412e555818cmr8774998wms.26.1709835069608; Thu, 07 Mar 2024 10:11:09 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id l14-20020a7bc44e000000b00412f6c695d1sm3293442wmi.43.2024.03.07.10.11.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 07 Mar 2024 10:11:09 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id DBA785F956; Thu, 7 Mar 2024 18:11:05 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Elena Ufimtseva , John G Johnson , Jagannathan Raman , Mahmoud Mandour , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Paolo Bonzini , Alexandre Iooss , Peter Xu , Manos Pitsidianakis , Markus Armbruster , Eduardo Habkost , Juan Quintela , Thomas Huth , Richard Henderson , peter.maydell@linaro.org, David Hildenbrand Subject: [PATCH 5/5] docs/devel: mark out defined functions and structures Date: Thu, 7 Mar 2024 18:11:05 +0000 Message-Id: <20240307181105.4081793-6-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240307181105.4081793-1-alex.bennee@linaro.org> References: <20240307181105.4081793-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::335; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x335.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@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-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org This allows sphinx to hyperlink the references to their kdoc definitions for easy navigation. Signed-off-by: Alex Bennée Reviewed-by: Peter Maydell --- docs/devel/memory.rst | 48 +++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst index ed24708fce3..193f31198b0 100644 --- a/docs/devel/memory.rst +++ b/docs/devel/memory.rst @@ -16,11 +16,11 @@ The memory model provides support for - setting up coalesced memory for kvm - setting up ioeventfd regions for kvm -Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks +Memory is modelled as an acyclic graph of `MemoryRegion` objects. Sinks (leaves) are RAM and MMIO regions, while other nodes represent buses, memory controllers, and memory regions that have been rerouted. -In addition to MemoryRegion objects, the memory API provides AddressSpace +In addition to `MemoryRegion` objects, the memory API provides `AddressSpace` objects for every root and possibly for intermediate MemoryRegions too. These represent memory as seen from the CPU or a device's viewpoint. @@ -28,17 +28,17 @@ Types of regions ---------------- There are multiple types of memory regions (all represented by a single C type -MemoryRegion): +`MemoryRegion`): - RAM: a RAM region is simply a range of host memory that can be made available to the guest. - You typically initialize these with memory_region_init_ram(). Some special - purposes require the variants memory_region_init_resizeable_ram(), - memory_region_init_ram_from_file(), or memory_region_init_ram_ptr(). + You typically initialize these with `memory_region_init_ram()`. Some special + purposes require the variants `memory_region_init_resizeable_ram()`, + `memory_region_init_ram_from_file()`, or `memory_region_init_ram_ptr()`. - MMIO: a range of guest memory that is implemented by host callbacks; each read or write causes a callback to be called on the host. - You initialize these with memory_region_init_io(), passing it a + You initialize these with `memory_region_init_io()`, passing it a MemoryRegionOps structure describing the callbacks. - ROM: a ROM memory region works like RAM for reads (directly accessing @@ -53,7 +53,7 @@ MemoryRegion): - IOMMU region: an IOMMU region translates addresses of accesses made to it and forwards them to some other target memory region. As the name suggests, these are only needed for modelling an IOMMU, not for simple devices. - You initialize these with memory_region_init_iommu(). + You initialize these with `memory_region_init_iommu()`. - container: a container simply includes other memory regions, each at a different offset. Containers are useful for grouping several regions @@ -65,7 +65,7 @@ MemoryRegion): can overlay a subregion of RAM with MMIO or ROM, or a PCI controller that does not prevent card from claiming overlapping BARs. - You initialize a pure container with memory_region_init(). + You initialize a pure container with `memory_region_init()`. - alias: a subsection of another region. Aliases allow a region to be split apart into discontiguous regions. Examples of uses are memory @@ -83,7 +83,7 @@ MemoryRegion): It claims I/O space that is not supposed to be handled by QEMU itself. The typical use is to track parts of the address space which will be handled by the host kernel when KVM is enabled. You initialize these - by passing a NULL callback parameter to memory_region_init_io(). + by passing a NULL callback parameter to `memory_region_init_io()`. It is valid to add subregions to a region which is not a pure container (that is, to an MMIO, RAM or ROM region). This means that the region @@ -104,28 +104,28 @@ copied to the destination on migration. These APIs which allocate the host memory for you will also register the memory so it is migrated: -- memory_region_init_ram() -- memory_region_init_rom() -- memory_region_init_rom_device() +- `memory_region_init_ram()` +- `memory_region_init_rom()` +- `memory_region_init_rom_device()` For most devices and boards this is the correct thing. If you have a special case where you need to manage the migration of the backing memory yourself, you can call the functions: -- memory_region_init_ram_nomigrate() -- memory_region_init_rom_nomigrate() -- memory_region_init_rom_device_nomigrate() +- `memory_region_init_ram_nomigrate()` +- `memory_region_init_rom_nomigrate()` +- `memory_region_init_rom_device_nomigrate()` which only initialize the MemoryRegion and leave handling migration to the caller. The functions: -- memory_region_init_resizeable_ram() -- memory_region_init_ram_from_file() -- memory_region_init_ram_from_fd() -- memory_region_init_ram_ptr() -- memory_region_init_ram_device_ptr() +- `memory_region_init_resizeable_ram()` +- `memory_region_init_ram_from_file()` +- `memory_region_init_ram_from_fd()` +- `memory_region_init_ram_ptr()` +- `memory_region_init_ram_device_ptr()` are for special cases only, and so they do not automatically register the backing memory for migration; the caller must @@ -150,8 +150,8 @@ device. For example, the owner object will not die between an address_space_map operation and the corresponding address_space_unmap. After creation, a region can be added to an address space or a -container with memory_region_add_subregion(), and removed using -memory_region_del_subregion(). +container with `memory_region_add_subregion()`, and removed using +`memory_region_del_subregion()`. Various region attributes (read-only, dirty logging, coalesced mmio, ioeventfd) can be changed during the region lifecycle. They take effect @@ -213,7 +213,7 @@ allows the region to overlap any other region in the same container, and specifies a priority that allows the core to decide which of two regions at the same address are visible (highest wins). Priority values are signed, and the default value is zero. This means that -you can use memory_region_add_subregion_overlap() both to specify a region +you can use `memory_region_add_subregion_overlap()` both to specify a region that must sit 'above' any others (with a positive priority) and also a background region that sits 'below' others (with a negative priority).