From patchwork Tue May 21 12:25:16 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164725 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1545342ili; Tue, 21 May 2019 05:34:29 -0700 (PDT) X-Google-Smtp-Source: APXvYqyF8zmVnsx2Z59T9Puz2OqYF780dMoWTuBM9oxI8HIqwWTCQIm1vfaUnIVZyEBlxCEG/sOo X-Received: by 2002:a17:906:843:: with SMTP id f3mr52779394ejd.70.1558442069130; Tue, 21 May 2019 05:34:29 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558442069; cv=none; d=google.com; s=arc-20160816; b=G+gGVSzTiU3W3YDO63tYpeLD61I5DLb+23EQ9Fq2y80UGAZ+7b0CgV8q4lhkWmz2Kp PZi+MX4Lv3BRg7Nl6+8Do/m/zCupZSlt9ynZ7RS10Asq8TM/2tGBqJOvzGm/W0TiZlUN 43Og6ENx0cYeRwwo7jqNrZ+fpzJHbcOK+hJ7+fxNsSPs68z9U4A4MkXXsvoeVO3ZYGNz rbT+i4pXmkHBJxUVAgY/VofQqAw1CELd03dUm8eORX+l1auV3cfdoOjrxMuP84BeOo4j Fg6QjjvQOl5Bwr9OAcHxGN1ZADGZroLHztrUrxM4ylxHRUPtllo0BrPiUTOR6KIuOmux qbtA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=R2n/a/9G76Yi92R/Ho6SyZIUaGzncWttQDNv3ZwW0cE=; b=uugK/qnTt3R1Z69aHepU/Zfk5VvliAzcbhGqZhdn5ULpo9u6TtVqN09yo7n1/DaoWv BQHsgnZmKsPUR+BcEXSwDM2K+/RmNvQvCPdQPqgrrZ9zIxpSZOJKgBsqbGKB79G6NBgm /yS3PgXJVYX9CcuL8Pp4h7xZbznmy1oRlKfnkZOxU4h+v7O1t0bKTIpnIcTwa+k4VGKr 2j+PXbfIL0e30efEi6rcDR2JzMz5xtUvoqSVqAAARsVP3S83Rb2eKnyzOx4jAfqy/neE StrsPmtGaKVfVsbCcFyBLl2rL2mN2C4DY75wBnexjqKyujrTDlvPxrWxlNXxNScU2ny2 yqnw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="daR/x1bh"; 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=fail (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 96si4140830edq.250.2019.05.21.05.34.28 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:34:29 -0700 (PDT) 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=fail header.i=@linaro.org header.s=google header.b="daR/x1bh"; 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=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52778 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3yO-0000G5-3i for patch@linaro.org; Tue, 21 May 2019 08:34:28 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45332) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SH-RM for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005HP-JL for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:38683) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3px-00058d-8b for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:45 -0400 Received: by mail-wr1-x435.google.com with SMTP id d18so18397815wrs.5 for ; Tue, 21 May 2019 05:25:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=R2n/a/9G76Yi92R/Ho6SyZIUaGzncWttQDNv3ZwW0cE=; b=daR/x1bhZwTFeUyso7yuHYeAUMb94czQdx2FJ7KWqJyV/COHfFzYYjHPcYgo8/xAh8 q6Vswi6pltIJLEga1/MYgPl0Tj8VdYBK12GzKyoxa4yDIH6Gf/EDPbql/QrEdQb0rdS1 yOSBheA22pIAhykYovCVWujL7Q1jodNedDxt2tHKaTVV+YL7DSSSCxADTGNF3gIqN1gI X82qC/6tTjOQJHiPOMx/dR0nrvZjh2VVim7BqFL+Ug0G+jM2f+joxRNXtfY68fmDAI9q Uev0clPsHD0edfp+bbPflz4jxj/TkZuzax1jJbjgkzV0uXxFWwGO4l9K15sX7aLbmI4m CROA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=R2n/a/9G76Yi92R/Ho6SyZIUaGzncWttQDNv3ZwW0cE=; b=LaJni3of+sO9s4Ra9tmIJU04J9LVRDkOGekKilS3JJbWfwhl0GGM8ph+sCKttripfx K74JSDtzE9W3LcxRIGA2fm2wS2xrHZyMi6a1JuRMZrpFrl6KdsgD81GUfA8r+aCPiVp2 vbzLItg8WT5e6psTQAC7mQYnuWd3DiVI/to4ROu35vQBtmsw/4wP0PHaWprI0BE/LhwL HDmLXVtZJ8YRpsd/FKXJQkQTIFy4rJgLWIm4T5G5/2sK+V3UzbhcIB/LYENpuWJBezzC IayP/dKm3tkfvxW6W8KhWWcAj553y/4OGbXzeBgQlYF21tKgC7bujO9Hy9FOa4MG6MRd dwmQ== X-Gm-Message-State: APjAAAXnqAIHnx10gVDdBH7WVra77DjoCC9kFLtVK6Ha7RSQEwa2OOw2 zNhEa3P4wzCJ+npavue3v60lLb9+s6g= X-Received: by 2002:adf:9bd2:: with SMTP id e18mr577759wrc.210.1558441532719; Tue, 21 May 2019 05:25:32 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:32 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:16 +0100 Message-Id: <20190521122519.12573-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::435 Subject: [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" If you try to use kerneldoc to extract the doc comments from memory.h and run sphinx on it, it generates some warnings: * various functions are missing a parameter in the docs * some 'unexpected indentation' warnings where a list isn't marked up with the leading/trailing blank lines and bullet markers that rST expects These aren't the only issues, but they are the only ones that are actually warned about (as opposed to generating misformatted output). Signed-off-by: Peter Maydell --- include/exec/memory.h | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) -- 2.20.1 diff --git a/include/exec/memory.h b/include/exec/memory.h index 9144a47f571..8447a16ded1 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -907,6 +907,7 @@ void memory_region_init_rom(MemoryRegion *mr, * @mr: the #MemoryRegion to be initialized. * @owner: the object that tracks the region's reference count * @ops: callbacks for write access handling (must not be NULL). + * @opaque: passed to the read and write callbacks of the @ops structure. * @name: Region name, becomes part of RAMBlock name used in migration stream * must be unique within any device * @size: size of the region. @@ -995,7 +996,7 @@ static inline IOMMUMemoryRegion *memory_region_get_iommu(MemoryRegion *mr) * Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu, * otherwise NULL. This is fast path avoiding QOM checking, use with caution. * - * @mr: the memory region being queried + * @iommu_mr: the memory region being queried */ static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck( IOMMUMemoryRegion *iommu_mr) @@ -1558,6 +1559,7 @@ void memory_region_add_subregion_overlap(MemoryRegion *mr, /** * memory_region_get_ram_addr: Get the ram address associated with a memory * region + * @mr: the memory region to get the ram address for */ ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr); @@ -1650,6 +1652,7 @@ bool memory_region_is_mapped(MemoryRegion *mr); * * Returns a #MemoryRegionSection that describes a contiguous overlap. * It will have the following characteristics: + * * .@size = 0 iff no overlap was found * .@mr is non-%NULL iff an overlap was found * @@ -1657,11 +1660,12 @@ bool memory_region_is_mapped(MemoryRegion *mr); * relative to the returned region (in the .@mr field), not to the * @mr argument. * - * Similarly, the .@offset_within_address_space is relative to the + * Similarly, the @.offset_within_address_space is relative to the * address space that contains both regions, the passed and the * returned one. However, in the special case where the @mr argument * has no container (and thus is the root of the address space), the * following will hold: + * * .@offset_within_address_space >= @addr * .@offset_within_address_space + .@size <= @addr + @size * @@ -2107,6 +2111,7 @@ static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write) * @addr: address within that address space * @attrs: memory transaction attributes * @buf: buffer with the data transferred + * @len: length of the buffer */ static inline __attribute__((__always_inline__)) MemTxResult address_space_read(AddressSpace *as, hwaddr addr,