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).