From patchwork Mon Jun 19 17:14:33 2023 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: 694091 Delivered-To: patch@linaro.org Received: by 2002:a5d:4d91:0:0:0:0:0 with SMTP id b17csp2476923wru; Mon, 19 Jun 2023 10:15:38 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ6W6Hqr02AbtnrSlaG7Bk/eKskEex+9ZFkmpK4I+bGPgoUYT88+O1DRpYWSm5UrPfHQL3lT X-Received: by 2002:a05:620a:454c:b0:761:dd4:3b1e with SMTP id u12-20020a05620a454c00b007610dd43b1emr11790715qkp.34.1687194938470; Mon, 19 Jun 2023 10:15:38 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687194938; cv=none; d=google.com; s=arc-20160816; b=nwgWE73A/OW9I5679tdLf5t80oq54idIsW/03DyfcScp5zLvsITgfO0AxNkQMrF3Ju BD89bVd5G1KRCCazDr/8yb7NCzUU1LpEoidNXE7CAEHCRgpG4Jr+ooFAUGUlz4wlw+1f TPXWdk8dXN9pGt+3PMd/EToGUfyO8Qltb4PwYEDZbR4nBcTjF41zxykzU0W3+/S4lfVK guPH6vM5IQ3gsy5X1mxdDqF7Ho7UN/ZC8o9pFEmVUCoNGEuEU5R80aGozZArgo1wmlzy cW4GOKBFWu0Nl0l0N9mPbgFSxqUEHRyih0AXUlymdgmEd3nsJD4ai0p4VwhpTNMsxX6H vJIg== 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=JJ0znkPd7OGWQQPw/921rAm+F3I/XIRFyJEm2ABhTJI=; b=zjZVRB9p+TrpAopNci25oaeYfUBiCXCbtLmWv8HkV3AozJZ2Th0eSUdzilHYOL743V yHU9WTU8lQCMtVZr6oJvjO8GJ05fZrzhXmYpAFLqUSoHBZ85QLL1u6gvcmo7mcDeNTOa w++5+x/RpEkO2WT3l+dPOxStIBbK2P2NMqejWK5FijKLo/GmjkwMlvwp/WQWhfbs5leY a6S0PxJbegBbxV/k5t/0s+Kci+zO+NjqEakLqCYJIatGBzuDJJSYsBwMzgMZtys0BnJ6 /WkNXDJ0Afw8KCyPEw4X5hDF8H0k1ZmDzoEzokU5NUI0cFONqcIMlsJixb6IihguXM/a VOCg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="qL/MNiPz"; 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 d2-20020a05620a204200b0075d57c7f7a3si120054qka.334.2023.06.19.10.15.38 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 19 Jun 2023 10:15:38 -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=pass header.i=@linaro.org header.s=google header.b="qL/MNiPz"; 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 1qBISj-0003KQ-Sr; Mon, 19 Jun 2023 13:14:45 -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 1qBISg-0003JY-N3 for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:43 -0400 Received: from mail-wm1-x332.google.com ([2a00:1450:4864:20::332]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qBISe-00024n-Sj for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:42 -0400 Received: by mail-wm1-x332.google.com with SMTP id 5b1f17b1804b1-3f900cd3f69so22395185e9.0 for ; Mon, 19 Jun 2023 10:14:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1687194879; x=1689786879; 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=JJ0znkPd7OGWQQPw/921rAm+F3I/XIRFyJEm2ABhTJI=; b=qL/MNiPzmpekrEJAYtxE56Jm0hU1bTxS+cDv0W4RQud8CV0sNUBe0MmUWF9tE+3M3S EC9Q08/99QFqLX/42ECbCZn50vmZpFqDA9ZE7pJGX2cAX6mznkDFnNUWdPP3UtVCQdKH BP0nBqrloVP9mXaBqySP5M+Smw0gYTASAbqYA72qAzrck76NRvttnrPwzJCaCzDcY15h 6AhODXVHCPFKbgwGA9eGUho2xSekxHjFqdt1TnGpWkBQWO4/jOwkDE79CFryC9YEL8sg cpwm+gHqO7t4WETpTKJDIAo17ldF0O8uwwbsS0pvHM6ucuerkujv7LlzabIgAL24gRIl JLbg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687194879; x=1689786879; 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=JJ0znkPd7OGWQQPw/921rAm+F3I/XIRFyJEm2ABhTJI=; b=UW9SsWlVOxv15HGGTTJHZfl/4C5RtfB+MBPnbt2TpzuVoxe6vqKWBTg590PLI2WWCl kGpQULHJq6IZAq9tZOc5vZqDf2qjgBu0rBKxtxyp+Ri93cRR8i3iFOxxgTaiwcQDYbFM 4EQqBaut7ge579iTbXLdKlUx25LqsjcHyZ+icPWQXt9abTMpssVpR5FAFGQcddncHuLw 6wfPxh9TcL4wbxkZs1Y06PAlQISuiFlvFUJVi2hRSbED5uDjudnBqA4wTUPHJsKK/2Kt G9yHAgBOXKnsapyZiQPiOZebSX5e8meJ+OrD0nrLDqw9idvY/FjCIS0+n7ROE1vksNub tsWg== X-Gm-Message-State: AC+VfDzSYQqU+v7QtOAIwI/629OO2gz04XPVjgxHVquyZ3PQMwHOIkxf 51ZKnqRK44fdD0GOIkBy3cYufQ== X-Received: by 2002:a1c:f70a:0:b0:3f7:34dc:ed0d with SMTP id v10-20020a1cf70a000000b003f734dced0dmr7243948wmh.25.1687194879247; Mon, 19 Jun 2023 10:14:39 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id p25-20020a05600c205900b003f9b1131a90sm252645wmg.23.2023.06.19.10.14.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 19 Jun 2023 10:14:38 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 7B6031FFBC; Mon, 19 Jun 2023 18:14:37 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?utf-8?q?Alex_Benn=C3=A9e?= Subject: [PATCH 1/5] docs/devel: add some front matter to the devel index Date: Mon, 19 Jun 2023 18:14:33 +0100 Message-Id: <20230619171437.357374-2-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230619171437.357374-1-alex.bennee@linaro.org> References: <20230619171437.357374-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::332; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x332.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 Give an overview of the most useful bits of the devel documentation to read depending on what the developer wants to do. Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson Reviewed-by: Peter Maydell --- docs/devel/index-process.rst | 2 ++ docs/devel/index-tcg.rst | 2 ++ docs/devel/index.rst | 24 ++++++++++++++++++++++-- docs/devel/tcg.rst | 2 ++ 4 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst index d50dd74c3e..362f97ee30 100644 --- a/docs/devel/index-process.rst +++ b/docs/devel/index-process.rst @@ -1,3 +1,5 @@ +.. _development_process: + QEMU Community Processes ------------------------ diff --git a/docs/devel/index-tcg.rst b/docs/devel/index-tcg.rst index b44ff8b5a4..a992844e5c 100644 --- a/docs/devel/index-tcg.rst +++ b/docs/devel/index-tcg.rst @@ -1,3 +1,5 @@ +.. _tcg: + TCG Emulation ------------- diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 09cfb322be..8f7e3dd80f 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -2,10 +2,30 @@ Developer Information --------------------- -This section of the manual documents various parts of the internals of QEMU. -You only need to read it if you are interested in reading or +This section of the manual documents various parts of the internals of +QEMU. You only need to read it if you are interested in reading or modifying QEMU's source code. +QEMU is a large and mature project with a number of complex subsystems +that can be overwhelming to understand. The development documentation +is not comprehensive but hopefully presents enough of a starting point +to get you started. If there are areas that are unclear please reach +out either via the IRC channel or mailing list and hopefully we can +improve the documentation for future developers. + +All developers will want to familiarise themselves with +:ref:`development_process` and how the community interacts. Please pay +particular attention to the :ref:`coding-style` and +:ref:`submitting-a-patch` sections to avoid common pitfalls. + +If you wish to implement a new hardware model you will want to read +through the :ref:`qom` documentation to understand how QEMU's object +model works. + +Those wishing to enhance or add new CPU emulation capabilities will +want to read our :ref:`tcg` documentation, especially the overview of +the :ref:`tcg_internals`. + .. toctree:: :maxdepth: 1 diff --git a/docs/devel/tcg.rst b/docs/devel/tcg.rst index b4096a17df..2786f2f679 100644 --- a/docs/devel/tcg.rst +++ b/docs/devel/tcg.rst @@ -1,3 +1,5 @@ +.. _tcg_internals: + ==================== Translator Internals ==================== From patchwork Mon Jun 19 17:14:34 2023 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: 694093 Delivered-To: patch@linaro.org Received: by 2002:a5d:4d91:0:0:0:0:0 with SMTP id b17csp2477057wru; Mon, 19 Jun 2023 10:15:55 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ7pw2bapKylTy2wa+xFGMvz7xKMoZzo3ro6hB2IW2TKs3+nhlpBgewxYsYsTbgYEqHdcAYG X-Received: by 2002:a05:620a:1a26:b0:762:29ff:228f with SMTP id bk38-20020a05620a1a2600b0076229ff228fmr11357656qkb.23.1687194954808; Mon, 19 Jun 2023 10:15:54 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687194954; cv=none; d=google.com; s=arc-20160816; b=wDf8ASdnm3GNmrCKNFMumzmldG/Aj4PbhswszBVe8g01cqXXR8uuA/GxWf9ZK3T4PS CL/BNBz8yWI5Fk/VZeRUJYyC9KfHvlYgQxbZp68W4QcpT3/Dh93i12K6B7zzGFH0uEY4 L/oLy+RnwDVM3Gesh81ynRffOpDNYu21yyAFMkEAoaEFL2KYH8tUqmxaNZowNjsjobzC 5HQpvjCPXA4YZW+1WFcbN45SKK1x6v4xzbSDbxAlZC6CpH5d5N3Yh6ux3R5Nah1jbnGr L0/lHfKCteebnfmbM06GHsPOOL6/cEE7I09UM6J2Mrr4i0NzObd5boKb+uy1UlTHrBQW s3hw== 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=XAzDJYHeZ3egsdpPxn+zZy7ksHc4V1jiKHsxofssT6o=; b=BWlVfQnaO2OLAWDurFCcmy6RHRo3+Vyb1sYFtIhpN30MOoJ+4wZ9HwG5nre8lx8riR gnq6Vq6kVYVja/IvE3E+wnddRQxn0ThGP5qGWM9zrV9I53MZCNJbhlqgdFB1CDv33Qz/ LhK75gGoDEct3C2sfqHcBpZsV+BbOXdK8fLJOmcdL48ojoErcPFS4R5bXAsQ6cKKAyzA qGz/5FsFYiL1hgkgOBR0Xb6W1Uq2ZxWTuNHVBtNwBjH6VWcnf6VpqvH2N1NB1dAJcOGy Ufp4CgdmeSDU2/UFoj65D4CvKtzdrd0yFdgL0EH/GBENfRm51g6BBCe3YotvFPDuQ73z Q6nA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=PX92BXvx; 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 n15-20020ae9c30f000000b0076250115d65si109926qkg.437.2023.06.19.10.15.54 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 19 Jun 2023 10:15:54 -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=pass header.i=@linaro.org header.s=google header.b=PX92BXvx; 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 1qBISl-0003Mk-3F; Mon, 19 Jun 2023 13:14:47 -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 1qBISh-0003Ja-MN for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:43 -0400 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 1qBISf-00024t-Cx for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:43 -0400 Received: by mail-wm1-x32e.google.com with SMTP id 5b1f17b1804b1-3f900cd3f96so24777645e9.2 for ; Mon, 19 Jun 2023 10:14:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1687194879; x=1689786879; 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=XAzDJYHeZ3egsdpPxn+zZy7ksHc4V1jiKHsxofssT6o=; b=PX92BXvxsydR26vi7/30yy9Ru+EgAhrexq/R58MkhqGZQ67Cq5LJjN9khjSL4EVu1V Vumb0c5eJoc41bCXFcuUMQYbikdnQ8/a0asfS1Jb6bZX9ItHOj/WvFO+Ya4xLQHBssIZ FMwa0rQs8HhtV8/rHJBKAbWCgq8gNYyJRVSwdyrGPvYon31ObQerdwXi88lXptEyjJCH mdyPrpECKnwEKOcR8hNfCokWkBj0fUb9OvqpdKn0RH+U5ycnViDegKdyakOh8G+7Nli8 AmQEHFlL1+VBmAdBNj2GIcYD3Rw8BuKrpq58FcVgjSr7ec5V7r5d566CNrs//1ettuNK 2fcQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687194879; x=1689786879; 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=XAzDJYHeZ3egsdpPxn+zZy7ksHc4V1jiKHsxofssT6o=; b=iECefbOD5Cn+axk3aiIX8a2BvoKpxBP570e4Gw6u+DBAJS4+7LYN6rgCRHp3bmC6Ph LEH3ivF1EHYdmhEpASBp0fHaflzKlqEIlO6U2iks9ABA/nY0yqMVIQ0WTRzDhyxGDb75 gxIWVCCn4BQFXG1HhlB5JN39xnYU5AW60ZunCExlrDPEXSgJIdjr6NmacLnzuMjJQP/f taLBruq7orU75M5ga63az/42ibvFcWdQXDFlnRn5wp0USj9K2lqNiISWx/f29yq55Wpk 4ES1uu5gyl7okrQNjGc7n8qaQdBMibLZwaje0jBV8UQmTvZGH6TCGJ0IGaCR6UtIDSKf 0N5w== X-Gm-Message-State: AC+VfDw2044ZkFL7yPdRzdqir1tscheZkQIcP0uZrlojzFLSS7LAXJGi ztlY+Eh3wWm8PAZjru5tB0gaNA== X-Received: by 2002:a7b:cb87:0:b0:3f7:e4d7:4469 with SMTP id m7-20020a7bcb87000000b003f7e4d74469mr7283058wmi.41.1687194879501; Mon, 19 Jun 2023 10:14:39 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id k4-20020a05600c0b4400b003f727764b10sm296549wmr.4.2023.06.19.10.14.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 19 Jun 2023 10:14:38 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 969C31FFBD; Mon, 19 Jun 2023 18:14:37 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?utf-8?q?Alex_Benn=C3=A9e?= Subject: [PATCH 2/5] include/migration: mark vmstate_register() as a legacy function Date: Mon, 19 Jun 2023 18:14:34 +0100 Message-Id: <20230619171437.357374-3-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230619171437.357374-1-alex.bennee@linaro.org> References: <20230619171437.357374-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 Mention that QOM-ified devices already have support for registering the description. Signed-off-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Richard Henderson Acked-by: Peter Xu Reviewed-by: Juan Quintela --- include/migration/vmstate.h | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/include/migration/vmstate.h b/include/migration/vmstate.h index 084f5e784a..35579b2c1f 100644 --- a/include/migration/vmstate.h +++ b/include/migration/vmstate.h @@ -1209,7 +1209,14 @@ int vmstate_register_with_alias_id(VMStateIf *obj, uint32_t instance_id, int required_for_version, Error **errp); -/* Returns: 0 on success, -1 on failure */ +/** + * vmstate_register() - legacy function to register state serialisation description + * + * New code shouldn't be using this function as QOM-ified devices have + * dc->vmsd to store the serialisation description. + * + * Returns: 0 on success, -1 on failure + */ static inline int vmstate_register(VMStateIf *obj, int instance_id, const VMStateDescription *vmsd, void *opaque) From patchwork Mon Jun 19 17:14:35 2023 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: 694095 Delivered-To: patch@linaro.org Received: by 2002:a5d:4d91:0:0:0:0:0 with SMTP id b17csp2477185wru; Mon, 19 Jun 2023 10:16:14 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ4bLqBAVVKilU0HXqa71lydrQpjIuFExQOfPBi/4GZrn3UZYyer0nEnIHdfDwEiweCKeTPL X-Received: by 2002:a05:6214:2686:b0:620:a1be:c74d with SMTP id gm6-20020a056214268600b00620a1bec74dmr12488668qvb.37.1687194974631; Mon, 19 Jun 2023 10:16:14 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687194974; cv=none; d=google.com; s=arc-20160816; b=kv77rV7o/3wOO9rJN9Y1GRJ+L+2LVz8uUXGE/x5xsnMmYOGlkkrFy7Vc/fWlYLNfFA WChpirrFv7CYtva+iWrYPcBFiUkmgmcY0afmz9Lf5gnF7+bkqXgPrqydwoPgOMsfleLa iOF6A1camuvCG2yp9ZLrZiRFS/pvb5P8TjHKOse/hqrCSrt03E+olX5q+OrfwEZWmEl8 WzF7CstHqiVi0/hCGimIp0u711bTZLO91/Ma5vVihHpo/dTxwYygwt8BUqx9Nx3nACVw WHbmrZreBiTX+/xd2K16/8yZO4vD/JhnMkCSap8KaYFK30qSrySgYYuJHoD4d/ejtBWR D6DQ== 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=pkFrDIIweegbRGGdzIcZRYuzCjxf5L+g2rFiEeEv9p8=; b=VIDdQlLboJbDkC+GFZ0FxhPcWOPhBENt5H5yWd5VtzzKeYW/e0NF5AhlW/8v+vRTOL BlZ2rCYQE0DHLPHa4N0GWChmVmXtytNg3gU6rHRzYEZJavEq5BRhIJkdcfjyk4INzzCT A+QSWj+TVV3OgQTrBZIGEu5nlKbVyb73d8qf3kBkQTFlHjvu99m6SOhfH1M4mqWw0PWI /mO87wBJqyFAfoKKwxRDRbDYvZ7v5xYzQO3ajndOxA6caXMaAMJ/cTPBM/Stnh7d/44Y Yxv0w1cp5JYEaVXm+8lAhf/lWFDCr8SJA5zTPtnB/ONVgoAPRCR85ujK38q6TOmQC2nw b7Kw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=mSKcXI5D; 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 im10-20020a056214246a00b00625bb5fc673si117159qvb.405.2023.06.19.10.16.14 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 19 Jun 2023 10:16:14 -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=pass header.i=@linaro.org header.s=google header.b=mSKcXI5D; 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 1qBISr-0003N7-60; Mon, 19 Jun 2023 13:14:54 -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 1qBISi-0003Ju-El for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:44 -0400 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 1qBISg-000252-6r for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:44 -0400 Received: by mail-lf1-x129.google.com with SMTP id 2adb3069b0e04-4f8735ac3e3so1466838e87.2 for ; Mon, 19 Jun 2023 10:14:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1687194880; x=1689786880; 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=pkFrDIIweegbRGGdzIcZRYuzCjxf5L+g2rFiEeEv9p8=; b=mSKcXI5DQE4Su5jqxyGvl/qrP5DBmSzZqy/gEm4lvCpKCmxu9A8Gmy+atJy0oVRBlm T3cd+wpsCTcpavEjhaOImcL+Cz7JnYIs5vtdpuH/14rlRVmnRfwPCNWxiNUyfmGyUrQi VrHI3YxVKU0ebc1RZ2ww0aDBP3k4aFoKxzaH6JxxW56Ctwp6UnAERJcgwyeBct7CNOeX 5VCpc9LIdGs2Jn/TRAkA2gdlwmP7S//NV74FTih7i3VKzHqPMhwhlVKOap9k/SHlHi3A nH6A+xUAEfdEPG4T2f4vbpc8AEiPAXTFPIJo4XCqLEc3o1MzOPDmtgYYr2JfaKCOMIci ANUQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687194880; x=1689786880; 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=pkFrDIIweegbRGGdzIcZRYuzCjxf5L+g2rFiEeEv9p8=; b=O6EXN8DrAdk+e3g/CPsGIY+LwtISrh/G5ZbiHsyVJ8bIoSBDF4+aZ7t/aT3m/5igQ9 se6Q+z/30Az1+Bp2eXzUWARQ0HkhxIQzYnzBfGj9AFVhjRDtJPZ9DaQIb7X/ILv/SbRp pXZxTp7qTzIx+/CAhELqqaiASyosJg+bg5BSE70W99SsDvpNthsBmk5c0Jg64QQQZZuN rDtf1/ARzpYXCzUka0Naoo3dUxQNv1waLQTxJcyo/alfuUmJhgO4APXGuZTHhPpSlgQc pSBIA/Rr2elHz6JvF9NQ4ckt9dr1BPOnsXjnbq5iG+6Mg+pOyZtrD2gaegtIf+GJszP+ ukmg== X-Gm-Message-State: AC+VfDz9SWafH/CJLy6wS/jAB7inpMmQl9H9sNwpceQeMtOwL0JdYgY4 fQqi6r7QEVgsqQF7vIyWlFkD8w== X-Received: by 2002:a19:915d:0:b0:4f6:1805:6095 with SMTP id y29-20020a19915d000000b004f618056095mr5872109lfj.8.1687194880433; Mon, 19 Jun 2023 10:14:40 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id q19-20020a1cf313000000b003f7361ca753sm11154563wmq.24.2023.06.19.10.14.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 19 Jun 2023 10:14:38 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id B06E31FFBE; Mon, 19 Jun 2023 18:14:37 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?utf-8?q?Alex_Benn=C3=A9e?= Subject: [PATCH 3/5] include/hw/qdev-core: fixup kerneldoc annotations (!COMPLETE) Date: Mon, 19 Jun 2023 18:14:35 +0100 Message-Id: <20230619171437.357374-4-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230619171437.357374-1-alex.bennee@linaro.org> References: <20230619171437.357374-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 Fix up the kerneldoc markup and start documenting the various fields in QDEV related structures. Unfortunately this is not enough include the documentation because kerneldoc currently chokes on some of our macros such as: /** * @gpios: list of named GPIOs the device provides. */ QLIST_HEAD(, NamedGPIOList) gpios; where it demands we document QLIST_HEAD and NamedGPIOList despite them not technically being fields in the structure. Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson --- include/hw/qdev-core.h | 123 ++++++++++++++++++++++++++++++++++------- 1 file changed, 102 insertions(+), 21 deletions(-) diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h index f1070d6dc7..74b4971d7e 100644 --- a/include/hw/qdev-core.h +++ b/include/hw/qdev-core.h @@ -38,7 +38,10 @@ typedef void (*BusRealize)(BusState *bus, Error **errp); typedef void (*BusUnrealize)(BusState *bus); /** - * DeviceClass: + * struct DeviceClass: + * + * The base class for all devices. + * * @props: Properties accessing state fields. * @realize: Callback function invoked when the #DeviceState:realized * property is changed to %true. @@ -97,22 +100,34 @@ typedef void (*BusUnrealize)(BusState *bus); * */ struct DeviceClass { - /*< private >*/ + /* private: */ ObjectClass parent_class; - /*< public >*/ + /* public: */ + /** + * @categories: device categories device belongs to + */ DECLARE_BITMAP(categories, DEVICE_CATEGORY_MAX); + /** + * @fw_name: name used to identify device to firmware interfaces + */ const char *fw_name; + /** + * @desc: human readable description of device + */ const char *desc; - /* - * The underscore at the end ensures a compile-time error if someone - * assigns to dc->props instead of using device_class_set_props. + /** + * @props_: properties associated with device, should only be + * assigned by using device_class_set_props(). The underscore + * ensures a compile-time error if someone attempts to assign + * dc->props directly. */ Property *props_; - /* - * Can this device be instantiated with -device / device_add? + /** + * @user_creatable: Can this device be instantiated with -device / device_add? + * * All devices should support instantiation with device_add, and * this flag should not exist. But we're not there, yet. Some * devices fail to instantiate with cryptic error messages. @@ -126,19 +141,28 @@ struct DeviceClass { bool hotpluggable; /* callbacks */ - /* - * Reset method here is deprecated and replaced by methods in the - * resettable class interface to implement a multi-phase reset. + /** + * @reset: deprecated device reset method pointer + * + * Modern code should use the ResettableClass interface to + * implement a multi-phase reset. + * * TODO: remove once every reset callback is unused */ DeviceReset reset; DeviceRealize realize; DeviceUnrealize unrealize; - /* device state */ + /** + * @vmsd: device state serialisation description for + * migration/save/restore + */ const VMStateDescription *vmsd; - /* Private to qdev / bus. */ + /** + * @bus_type: bus type + * private: to qdev / bus. + */ const char *bus_type; }; @@ -168,36 +192,91 @@ typedef struct { } MemReentrancyGuard; /** - * DeviceState: - * @reset: ResettableState for the device; handled by Resettable interface. + * struct DeviceState - common device state, accessed with qdev helpers * * This structure should not be accessed directly. We declare it here * so that it can be embedded in individual device state structures. */ struct DeviceState { - /*< private >*/ + /* private: */ Object parent_obj; - /*< public >*/ + /* public: */ + /** + * @id: global device id + */ char *id; + /** + * @canonical_path: canonical path of realized device in the QOM tree + */ char *canonical_path; + /** + * @realized: has device been realized? + */ bool realized; + /** + * @pending_deleted_event: track pending deletion events during unplug + */ bool pending_deleted_event; + /** + * @pending_deleted_expires_ms: optional timeout for deletion events + */ int64_t pending_deleted_expires_ms; + /** + * @opts: QDict of options for the device + */ QDict *opts; + /** + * @hotplugged: was device added after PHASE_MACHINE_READY? + */ int hotplugged; + /** + * @allow_unplug_during_migration: can device be unplugged during migration + */ bool allow_unplug_during_migration; + /** + * @parent_bus: bus this device belongs to + */ BusState *parent_bus; + /** + * @gpios: list of named GPIOs the device provides. + */ QLIST_HEAD(, NamedGPIOList) gpios; + /** + * @clocks: list of named clocks the device provides. + */ QLIST_HEAD(, NamedClockList) clocks; + /** + * @child_bus: list of child buses + */ QLIST_HEAD(, BusState) child_bus; + /** + * @num_child_bus: number of @child_bus entries + */ int num_child_bus; + /** + * @instance_id_alias: device alias for handling legacy migration setups + */ int instance_id_alias; + /** + * @alias_required_for_version: indicates @instance_id_alias is + * needed for migration + */ int alias_required_for_version; + /** + * @reset: ResettableState for the device; handled by Resettable interface. + */ ResettableState reset; + /** + * @unplug_blockers: list of reasons to block unplugging of device + */ GSList *unplug_blockers; - /* Is the device currently in mmio/pio/dma? Used to prevent re-entrancy */ + /** + * @mem_reentrancy_guard: Is the device currently in mmio/pio/dma? + * + * Used to prevent re-entrancy confusing things. + */ MemReentrancyGuard mem_reentrancy_guard; }; @@ -265,7 +344,7 @@ typedef struct BusChild { #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler" /** - * BusState: + * struct BusState: * @hotplug_handler: link to a hotplug handler associated with bus. * @reset: ResettableState for the bus; handled by Resettable interface. */ @@ -290,7 +369,8 @@ struct BusState { }; /** - * GlobalProperty: + * typedef GlobalProperty - a global property type + * * @used: Set to true if property was used when initializing a device. * @optional: If set to true, GlobalProperty will be skipped without errors * if the property doesn't exist. @@ -871,7 +951,8 @@ void device_listener_register(DeviceListener *listener); void device_listener_unregister(DeviceListener *listener); /** - * @qdev_should_hide_device: + * qdev_should_hide_device() - check if device should be hidden + * * @opts: options QDict * @from_json: true if @opts entries are typed, false for all strings * @errp: pointer to error object From patchwork Mon Jun 19 17:14:36 2023 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: 694092 Delivered-To: patch@linaro.org Received: by 2002:a5d:4d91:0:0:0:0:0 with SMTP id b17csp2476942wru; Mon, 19 Jun 2023 10:15:40 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ7/qursNoo2saQ0yZ4s/Vhn3hurHudC2YAGMW4OiOpJgq78ddOMReXgeBAU3/7WV1R/5UFz X-Received: by 2002:a05:620a:4390:b0:763:9ba4:6f7e with SMTP id a16-20020a05620a439000b007639ba46f7emr3018676qkp.35.1687194940436; Mon, 19 Jun 2023 10:15:40 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687194940; cv=none; d=google.com; s=arc-20160816; b=qHe2JJTYHZtgCLeK5m17mhHi03zEPrHq2NDmO/yBQ4z32Q6rrdgYxcwg36Fcn5Bm0Z s1toIvecqnmIcGYSlWyAhkxK+iglu69ApjdkOTy2hFTTUMTNBfPFhPdcTg1AkJH8XXMG k7ca21bixR5mYGXAkPjtIw3rUxrZma2jiTTMhdQHl/M1xiDuya9Gkp9qh9bgjuhwXKlb C1EuOzGYAXkcBAKnOugEo/vcre45qfjERjdleeBCCEOseL25a4WrFpFiS3WBLjtP+SjP V8jGa2QabmuOOitVQpEQ/tpbR7Myf8dAUxlqTz8xDGJkYQ25ObV6h1aw5k7wHI2eSzdo 8wlw== 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=pNCXKy9KD1nbv+iKj9nGFzUMHc9zCSFXe2xCj+cXcBY=; b=Z6c1ZDQi6SiS9CDFQrvpWP46jaafg42Ab9BzIyEArp/zRcrYoXuuZtua2Sz4jGQiHF FnTdwCO7I10tXsNGkl29b+jBjhS93+2PVzihGAm2x3wX8loAO/aDTCN5wwPZgjvVuRJi ypIjcyxUfLTR0BNUKhaSk7roTTbgsm6+u1/BV1jvdn56Ra0/nIneNyfs95p97Ef3xaCx dQYvYhiwZxm4uT+YU/8ukFsnVIUHg+NqS8rDht79jP2Rpq937BxcAP+xPPmx602qv2FW gHyEyZIKgis3cxr6Ko0BWvZxPtfqKOTZr5iPDE3Ys5LWL0w+396hkVlzedm8L0LqFQyz oN9w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=edNhWpuU; 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 tn20-20020a05620a3c1400b007624af3ece8si143059qkn.29.2023.06.19.10.15.40 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 19 Jun 2023 10:15:40 -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=pass header.i=@linaro.org header.s=google header.b=edNhWpuU; 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 1qBISj-0003KR-U5; Mon, 19 Jun 2023 13:14:46 -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 1qBISi-0003Jt-7F for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:44 -0400 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qBISg-000255-Dh for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:43 -0400 Received: by mail-wr1-x429.google.com with SMTP id ffacd0b85a97d-30adc51b65cso3814506f8f.0 for ; Mon, 19 Jun 2023 10:14:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1687194880; x=1689786880; 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=pNCXKy9KD1nbv+iKj9nGFzUMHc9zCSFXe2xCj+cXcBY=; b=edNhWpuUu+tLTJQkAf+/0XFZ8Z5YXKWEaCfVcxkaLQCDw+T9BHwLbVjfsQHyVpewbK /IkROx3+CJ6cZzhRDDVO5znmmP3dNRreaKhRTDup/4V22KaAtYrhxhMfKmjwdt1aSbQF 5/IDAUU0XWsn3fUd2cZZTPjU5mQDmXy+1bbFvMcQbpVats5n5tqZ4z84QuPOFG+L2Diq ORC7qpDfYv1DQHzH+qa3mv0TMin2dMjKgfUIdSYLoPpXpXYqgqt5tRYANIXESKcUs7i7 f+Z7m9AnMfBdJxJWCD0uENxKaaFOyI0ijuKazrHSmLN0QJ7b+/zmodpk9r5Emajukcqf JjTg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687194880; x=1689786880; 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=pNCXKy9KD1nbv+iKj9nGFzUMHc9zCSFXe2xCj+cXcBY=; b=k5aoj07G2MlH/ohUQsHACSs2ylBs/Lmswe2sLwGye9nJKB38qIo1w2Tu117CF0pkuR cLVt/nDHYCUq2bvMUJBNOC0aM+Pcf6hNAHuoAYBBOwwBkuoFpqbbGk/Ya9/KEx4QiQtD 1wZEXvtaJ9xitjGAl40eN6r5OhWdaVUja7lmEw6GMkriN5vxEScRGxTvfFClATUIZsBa nhAj1oYN8EnpgOJebhBHZkVR95Vqrm29JcHp6pes6Xc/mAsBxO80Abogd70RVTmpIaiN YZZb0iBd8JOk1N8AJrp8VgO6JY28sMTOlGVKiF/8gVGeF2842KaLolXxptVjWKZz8j96 IycA== X-Gm-Message-State: AC+VfDxzrgkaepUNY4CD7DIBbb+Zd3owEz7x3zSZM/zy9LOC6mNyKiEG SwLd8+x2cSHpWtGmG3t/jAcueQ== X-Received: by 2002:a5d:6084:0:b0:312:74a9:8263 with SMTP id w4-20020a5d6084000000b0031274a98263mr1488897wrt.44.1687194879977; Mon, 19 Jun 2023 10:14:39 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id x1-20020a5d4441000000b00311d8c2561bsm37700wrr.60.2023.06.19.10.14.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 19 Jun 2023 10:14:38 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id CEDBA1FFBF; Mon, 19 Jun 2023 18:14:37 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?utf-8?q?Alex_Benn=C3=A9e?= Subject: [PATCH 4/5] docs/devel: split qom-api reference into new file Date: Mon, 19 Jun 2023 18:14:36 +0100 Message-Id: <20230619171437.357374-5-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230619171437.357374-1-alex.bennee@linaro.org> References: <20230619171437.357374-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x429.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 Lets try and keep the overview of the sub-system digestible by splitting the core API stuff into a separate file. As QOM and QDEV work together we should also try and enumerate the qdev_ functions. Currently this is a little broken as kerneldoc doesn't understand our macros. Signed-off-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé --- docs/devel/index-api.rst | 2 ++ docs/devel/qdev-api.rst | 12 ++++++++++++ docs/devel/qom-api.rst | 9 +++++++++ docs/devel/qom.rst | 3 ++- 4 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 docs/devel/qdev-api.rst create mode 100644 docs/devel/qom-api.rst diff --git a/docs/devel/index-api.rst b/docs/devel/index-api.rst index 7108821746..539ad29c21 100644 --- a/docs/devel/index-api.rst +++ b/docs/devel/index-api.rst @@ -11,5 +11,7 @@ generated from in-code annotations to function prototypes. loads-stores memory modules + qom-api + qdev-api ui zoned-storage diff --git a/docs/devel/qdev-api.rst b/docs/devel/qdev-api.rst new file mode 100644 index 0000000000..d47c4d7493 --- /dev/null +++ b/docs/devel/qdev-api.rst @@ -0,0 +1,12 @@ +.. _qdev-api: + +================================ +QEMU Device (qdev) API Reference +================================ + +We don't currently generate the API documentation for QDEV due to QEMU +macros confusing the kerneldoc tool. For now see the headers in +``include/hw/qdev-core.h`` + +.. + kernel-doc:: include/hw/qdev-core.h diff --git a/docs/devel/qom-api.rst b/docs/devel/qom-api.rst new file mode 100644 index 0000000000..ed1f17e797 --- /dev/null +++ b/docs/devel/qom-api.rst @@ -0,0 +1,9 @@ +.. _qom-api: + +===================================== +QEMU Object Model (QOM) API Reference +===================================== + +This is the complete API documentation for :ref:`qom`. + +.. kernel-doc:: include/qom/object.h diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index c9237950d0..98a4f178d5 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -387,4 +387,5 @@ OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: API Reference ------------- -.. kernel-doc:: include/qom/object.h +See the :ref:`QOM API` and :ref:`QDEV API` +documents for the complete API description. From patchwork Mon Jun 19 17:14:37 2023 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: 694096 Delivered-To: patch@linaro.org Received: by 2002:a5d:4d91:0:0:0:0:0 with SMTP id b17csp2477199wru; Mon, 19 Jun 2023 10:16:17 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ7y3Dn9EiIPRP00wwACQvxzDUHGAHSiyeW4khaQDww1qLyEjStqPiItmXaztA+X8u+/pngh X-Received: by 2002:ac8:5f13:0:b0:3fd:ecd2:3107 with SMTP id x19-20020ac85f13000000b003fdecd23107mr5399032qta.10.1687194976786; Mon, 19 Jun 2023 10:16:16 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687194976; cv=none; d=google.com; s=arc-20160816; b=yRo+QOQhDmZh8deT/tuPLBJbnNDisVCQl1WpULXX9BrMed4bwgeLhKOGNlXCrD0Gf1 e6oGmJU1r0OVKg+bOEOhRc0mzVmWRNHRmfWtQdx+yb62CMaLArnld/NQZ18XXtpaU2xx 5VtBQZGaX0hmkv8nVC1y77bPBG/pw1qOgLlRuhuVRjar7fqbUT1Y+ZTaVxJyY8zkBzzT ugxQId3s6L0S8sPSUfOS8QclnIxaFahPZersM/kuXtANeaelOY6l6zeoMtbNFKpMe0H3 hvTpsrUbVBLMJeyYFKLDclrUqTuJDHON75iIybhq4Q1F0ikHoGvRyeNSainW0PwRRIml hd5g== 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=VqZkN80sHKFG/1nL+XOE6YDm/Z/wk4N5tP5bpONv3gA=; b=adW1E+cooQDhb23R2C0wa+sXuNeei8bO5LsGaa7AL15/a3PUaSzhdSe9DISlm0Mnay N5Ck3buBnprli9+9Q3KN8Ba8A0kfqna2wjAlPKlGPjj3yQWhTc+iA1x/SXtBd/42ejT9 V+/NCve5Jhx3ap2xEv8Z3+1tnR2AYYFygWTQjqLJAXyWQLQ0PZx4lZdBohuS6qgJF28Y JKy05SiMAHPTvoO0KJLCeZBfp/oPyxT66IZXCad1YBeATxvvmQmU08O4IPLsVQuOqg0J QrBKSnd63JsmMNAeQ9+c0Lu62ly3NVhpgWX60zZ7h1X4sawfScB+JxHkhppFe7e+ZKdZ jugA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=aGh+xSEC; 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 12-20020ac84e8c000000b003fddff02d44si74019qtp.348.2023.06.19.10.16.16 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 19 Jun 2023 10:16:16 -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=pass header.i=@linaro.org header.s=google header.b=aGh+xSEC; 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 1qBISu-0003Nf-18; Mon, 19 Jun 2023 13:14:56 -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 1qBISj-0003KJ-9B for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:45 -0400 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qBISh-000258-Em for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:44 -0400 Received: by mail-wm1-x32d.google.com with SMTP id 5b1f17b1804b1-3f8f3786f20so44202955e9.2 for ; Mon, 19 Jun 2023 10:14:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1687194881; x=1689786881; 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=VqZkN80sHKFG/1nL+XOE6YDm/Z/wk4N5tP5bpONv3gA=; b=aGh+xSEChh285r3fEZZ72OP+h3yp7+pEaPcJs+I3s4tspPqHwlIgy0PZayBWYCnp86 mvQaDyDuZ53sbkK9RbDLNiOBNyyG7GzI0oDg9KUzgqRvOCjFk8SPug5pHFvlbNtayMC0 JPA6tYByGDINLBO21ZjHMvB+9CnT0hgT/2pnCWjgfCar/FD/dARpZxT+Rl18n40XX1EH VMA/WRaK/VgOMF5WtDHbiQTaytUF7vTkzUx7wH3eBwD+zQrFSL095eMiK2ozYGg0zW3I jkhPugmHPvWKCnauusqp9gKQlZqOUH0YXrmGb4pw/od33gnVoEp9JDnUtrB7tCI5bjSS WPQA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687194881; x=1689786881; 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=VqZkN80sHKFG/1nL+XOE6YDm/Z/wk4N5tP5bpONv3gA=; b=PSF71iyEAEDgepvA58mC+gvMH1BRIXNB62JFDIG1RLkw58b+E7U9YFqaWnDCB2b2To nmU0HhzTQf9pLK29Z01J3ecgLPUFqyBFihrSLjDdKEI+MRJ+fou+ksmcmyiBNQ2rS4Yw gWSg0WYd5cg0d4+5jGTgedSLIpOr/d51HcQjZPXuF2acrgZ+ZyjPZlVnE9wpNWuDFWQD DKGW4uZI7FcQVORp48nNJqkS3ZNWriLifoijl0iO0EE94y2aTqb9pIWAc3zVrp4S5es7 7y+fwy9wrQ0S4pLhgCphX+xHkAAjGaeVqgb28xZPWSkoSJiskB9DJMEQDNQs3KlNTxDQ B0Qw== X-Gm-Message-State: AC+VfDyi/xJM8wjidXm+nwX+piwckLoDjO5HRQOeGNA3g/FVbyyQj9g5 8x3I4a7J35TAACdjy5aoYiyd+A== X-Received: by 2002:a7b:c459:0:b0:3f9:b3a3:52ef with SMTP id l25-20020a7bc459000000b003f9b3a352efmr1508484wmi.36.1687194881474; Mon, 19 Jun 2023 10:14:41 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id l5-20020a1ced05000000b003f70a7b4537sm11315830wmh.36.2023.06.19.10.14.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 19 Jun 2023 10:14:40 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id E6D851FFC0; Mon, 19 Jun 2023 18:14:37 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?utf-8?q?Alex_Benn=C3=A9e?= Subject: [PATCH 5/5] docs/devel: introduce some key concepts for QOM development Date: Mon, 19 Jun 2023 18:14:37 +0100 Message-Id: <20230619171437.357374-6-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230619171437.357374-1-alex.bennee@linaro.org> References: <20230619171437.357374-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32d; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32d.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 Using QOM correctly is increasingly important to maintaining a modern code base. However the current documentation skips some important concepts before launching into a simple example. Lets: - at least mention properties - mention TYPE_OBJECT and TYPE_DEVICE - talk about why we have realize/unrealize - mention the QOM tree Signed-off-by: Alex Bennée --- docs/devel/qom.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 98a4f178d5..53633fbd35 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -13,6 +13,53 @@ features: - System for dynamically registering types - Support for single-inheritance of types - Multiple inheritance of stateless interfaces +- Mapping internal members to publicly exposed properties + +The root object class is TYPE_OBJECT which provides for the basic +object methods. + +The Device Class +================ + +The TYPE_DEVICE class is the parent class for all modern devices +implemented in QEMU and adds some specific methods to handle QEMU +device model. This includes managing the lifetime of devices from +creation through to when they become visible to the guest and +eventually unrealized. + +Device Life-cycle +----------------- + +As class initialisation cannot fail devices have an two additional +methods to handle the creation of dynamic devices. The ``realize`` +function is called with ``Error **`` pointer which should be set if +the device cannot complete its setup. Otherwise on successful +completion of the ``realize`` method the device object is added to the +QOM tree and made visible to the guest. + +The reverse function is ``unrealize`` and should be were clean-up +code lives to tidy up after the system is done with the device. + +All devices can be instantiated by C code, however only some can +created dynamically via the command line or monitor. Likewise only +some can be unplugged after creation and need an explicit +``unrealize`` implementation. This is determined by the +``user_creatable`` and ``hotpluggable`` variables in the root +``DeviceClass`` structure. + +The QOM tree +------------ + +The QOM tree is a composition tree which represents all of the objects +that make up a QEMU "machine". You can view this tree by running +``info qom-tree`` in the :ref:`QEMU monitor`. It will contain both +objects created by the machine itself as well those created due to +user configuration. + +Creating a minimal device +========================= + +A simple minimal device implementation may look something like bellow: .. code-block:: c :caption: Creating a minimal type