From patchwork Tue May 1 10:19:07 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 134751 Delivered-To: patches@linaro.org Received: by 10.46.151.6 with SMTP id r6csp4786667lji; Tue, 1 May 2018 03:19:10 -0700 (PDT) X-Google-Smtp-Source: AB8JxZq0Q/Yo9zjqyJ2qFwePs77oOgihxwr22LM0nU7aNVS5CCJi8mpOE5sLw5SZceQM3idkDmT9 X-Received: by 10.28.195.85 with SMTP id t82mr9450366wmf.129.1525169950486; Tue, 01 May 2018 03:19:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525169950; cv=none; d=google.com; s=arc-20160816; b=jjtpbsCkR89NZNdfCigLqumrlfJSmZ4VSIymuWojVMm81W5jLjo4E/pibG1SvDzlAB LN5jNvLzmnHnJusGhGnseciLlbBnqU0nfMU4EWmyY4mfsGg9ntbIr0LZGyapDRcfZR0g I+AKwl9cKDTERjZ+1gPWR+HJb7i8t7GwBrJw8k/M66WEJEWcYKGw9gET2y6HxCEmQ1AB JDclVfH+AxCWryDHBCX0GKuQAFSqcq5FSGAe4oJPnkEQADMuz0ck43a7ASr+eCFeUd22 SGCIIRJdTRcEWAot0VmKo3i7HOz18mUck2IGCVS3tQn3IyBOKsSTvs+gQ41wFfPRROFx w9SQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=message-id:date:subject:cc:to:from:arc-authentication-results; bh=iCkWOAPv+jFzpai7Pi/fphGNtAWfIyf5HwtrboJA+X8=; b=m1wluH0nMrO1KDypZQXFaD/y1jNTGHv6+3wHY6zyqT6cm98zRKcmqbxde9couChcYk SD9zzrxPABkpb5Hga6Yslz9NZ0Iui3mox+pYLNhcr7uoXeHvD27CYlTtDp4eDk20E61E KyqNukbEXgacpbjVoiVy5JHjBjQCjEqu1sb66ovpzT4qDrenpUCPUYtTxkAxb7D25EBy sKTZvjoFBAgD1b6/mKXDmsEOhsU/fZJTtM/LivuLsBckKBawJ3d95Zu3nFzUtqs65+/1 SCzAX7IeqVlCsHlkJDH1RdFn8tUXqGVfReiD/Ej8J3fol5D2rDTc6dMkbbih1QzAohnP 8lCA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of pm215@archaic.org.uk designates 2001:8b0:1d0::2 as permitted sender) smtp.mailfrom=pm215@archaic.org.uk; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by mx.google.com with ESMTPS id d206si6521709wmc.191.2018.05.01.03.19.10 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 01 May 2018 03:19:10 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of pm215@archaic.org.uk designates 2001:8b0:1d0::2 as permitted sender) client-ip=2001:8b0:1d0::2; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of pm215@archaic.org.uk designates 2001:8b0:1d0::2 as permitted sender) smtp.mailfrom=pm215@archaic.org.uk; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from pm215 by orth.archaic.org.uk with local (Exim 4.89) (envelope-from ) id 1fDSNI-0007Yb-71; Tue, 01 May 2018 11:19:08 +0100 From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Paolo Bonzini , Alex Williamson , Alexey Kardashevskiy , David Gibson Subject: [PATCH v2 1/1] memory.h: Improve IOMMU related documentation Date: Tue, 1 May 2018 11:19:07 +0100 Message-Id: <20180501101907.22638-1-peter.maydell@linaro.org> X-Mailer: git-send-email 2.17.0 Add more detail to the documentation for memory_region_init_iommu() and other IOMMU-related functions and data structures. Signed-off-by: Peter Maydell --- v1 -> v2 changes: * documented replay method * added note about wanting RCU or big qemu lock while calling translate include/exec/memory.h | 96 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 87 insertions(+), 9 deletions(-) -- 2.17.0 diff --git a/include/exec/memory.h b/include/exec/memory.h index 4402ba6c0d..997598c664 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -194,29 +194,95 @@ enum IOMMUMemoryRegionAttr { IOMMU_ATTR_SPAPR_TCE_FD }; +/** + * IOMMUMemoryRegionClass: + * + * All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION + * and provide implementations of at least some of the methods here + * to handle requests to the memory region. The minimum requirement + * is a @translate method. + */ typedef struct IOMMUMemoryRegionClass { /* private */ struct DeviceClass parent_class; /* * Return a TLB entry that contains a given address. Flag should - * be the access permission of this translation operation. We can - * set flag to IOMMU_NONE to mean that we don't need any - * read/write permission checks, like, when for region replay. + * be the access permission of this translation operation. The + * flag may be set to IOMMU_NONE to mean that we don't need any + * read/write permission checks; this is used by the default + * implementation of memory_region_iommu_replay(). (See the documentation + * of the replay method below for more details.) + * + * Once the IOMMU has returned a TLB entry, it must notify + * the IOMMU's users if that TLB entry changes, using + * memory_region_notify_iommu() (or, if necessary, by calling + * memory_region_notify_one() for each registered notifier). + * + * The returned information remains valid while the caller is + * holding the big QEMU lock or is inside an RCU critical section; + * if the caller wishes to cache the mapping beyond that it must + * register an IOMMU notifier so it can invalidate its cached + * information when the IOMMU mapping changes.. + * + * @iommu: the IOMMUMemoryRegion + * @hwaddr: address to be translated within the memory region + * @flag: requested access permissions */ IOMMUTLBEntry (*translate)(IOMMUMemoryRegion *iommu, hwaddr addr, IOMMUAccessFlags flag); - /* Returns minimum supported page size */ + /* Returns minimum supported page size in bytes. + * If this method is not provided then the minimum is assumed to + * be TARGET_PAGE_SIZE. + * + * @iommu: the IOMMUMemoryRegion + */ uint64_t (*get_min_page_size)(IOMMUMemoryRegion *iommu); - /* Called when IOMMU Notifier flag changed */ + /* Called when IOMMU Notifier flag changes (ie when the set of + * events which IOMMU users are requesting notification for changes). + * Optional method -- need not be provided if the IOMMU does not + * need to know exactly which events must be notified. + * + * @iommu: the IOMMUMemoryRegion + * @old_flags: events which previously needed to be notified + * @new_flags: events which now need to be notified + */ void (*notify_flag_changed)(IOMMUMemoryRegion *iommu, IOMMUNotifierFlag old_flags, IOMMUNotifierFlag new_flags); - /* Set this up to provide customized IOMMU replay function */ + /* Called to handle memory_region_iommu_replay(). + * + * The default implementation of memory_region_iommu_replay() is to + * call the IOMMU translate method for every page in the address space + * with flag == IOMMU_NONE and then call the notifier if translate + * returns valid mapping. If this method is implemented then it + * overrides the default behaviour, and must provide the full semantics + * of memory_region_iommu_replay(), by calling @notifier for every + * translation present in the IOMMU. + * + * Optional method -- an IOMMU only needs to provide this method + * if the default is inefficient or produces undesirable side effects. + * + * Note: this is not related to record-and-replay functionality. + */ void (*replay)(IOMMUMemoryRegion *iommu, IOMMUNotifier *notifier); - /* Get IOMMU misc attributes */ - int (*get_attr)(IOMMUMemoryRegion *iommu, enum IOMMUMemoryRegionAttr, + /* Get IOMMU misc attributes. This is an optional method that + * can be used to allow users of the IOMMU to get implementation-specific + * information. The IOMMU implements this method to handle calls + * by IOMMU users to memory_region_iommu_get_attr() by filling in + * the arbitrary data pointer for any IOMMUMemoryRegionAttr values that + * the IOMMU supports. If the method is unimplemented then + * memory_region_iommu_get_attr() will always return -EINVAL. + * + * @iommu: the IOMMUMemoryRegion + * @attr: attribute being queried + * @data: memory to fill in with the attribute data + * + * Returns 0 on success, or a negative errno; in particular + * returns -EINVAL for unrecognized or unimplemented attribute types. + */ + int (*get_attr)(IOMMUMemoryRegion *iommu, enum IOMMUMemoryRegionAttr attr, void *data); } IOMMUMemoryRegionClass; @@ -705,6 +771,14 @@ static inline void memory_region_init_reservation(MemoryRegion *mr, * An IOMMU region translates addresses and forwards accesses to a target * memory region. * + * The IOMMU implementation must define a subclass of TYPE_IOMMU_MEMORY_REGION. + * @_iommu_mr should be a pointer to enough memory for an instance of + * that subclass, @instance_size is the size of that subclass, and + * @mrtypename is its name. This function will initialize @_iommu_mr as an + * instance of the subclass, and its methods will then be called to handle + * accesses to the memory region. See the documentation of + * #IOMMUMemoryRegionClass for further details. + * * @_iommu_mr: the #IOMMUMemoryRegion to be initialized * @instance_size: the IOMMUMemoryRegion subclass instance size * @mrtypename: the type name of the #IOMMUMemoryRegion @@ -953,6 +1027,8 @@ void memory_region_register_iommu_notifier(MemoryRegion *mr, * a notifier with the minimum page granularity returned by * mr->iommu_ops->get_page_size(). * + * Note: this is not related to record-and-replay functionality. + * * @iommu_mr: the memory region to observe * @n: the notifier to which to replay iommu mappings */ @@ -962,6 +1038,8 @@ void memory_region_iommu_replay(IOMMUMemoryRegion *iommu_mr, IOMMUNotifier *n); * memory_region_iommu_replay_all: replay existing IOMMU translations * to all the notifiers registered. * + * Note: this is not related to record-and-replay functionality. + * * @iommu_mr: the memory region to observe */ void memory_region_iommu_replay_all(IOMMUMemoryRegion *iommu_mr); @@ -981,7 +1059,7 @@ void memory_region_unregister_iommu_notifier(MemoryRegion *mr, * memory_region_iommu_get_attr: return an IOMMU attr if get_attr() is * defined on the IOMMU. * - * Returns 0 if succeded, error code otherwise. + * Returns 0 on success, or a negative errno otherwise. * * @iommu_mr: the memory region * @attr: the requested attribute