From nobody Sat May 18 16:18:00 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1687194938; cv=none; d=zohomail.com; s=zohoarc; b=Ws4nZSPqXFZNrfEM07FvK48s7TWTuhZCFNB3lpYGip3HGawT4byFLOct6DiNTVnw9Md3+Z9yhutNoL6c71SeMsFpkE183XgSnz8+1R1/qqa+NQnD6BxrxumNgN5oR5aVAukJdQM2ClcL8cOUGv1w9lnTuc3eKs1oZGLHPBGK2jE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1687194938; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=JJ0znkPd7OGWQQPw/921rAm+F3I/XIRFyJEm2ABhTJI=; b=Co5zF21hQWAJAS5xdk8/hAfmRdBZWYCzlwbj0dazuAIKWqR1m323SITgf9XeDkcRjZNWGqCE1MeUTbgKqDHewQEcu+5zirwE+uvktWAhrWyfxcF3r/cIrJt7gnhF13bxCjor2p6gBmiaEAktdK4GqMhUReScrs9rRL7l2QNl95s= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1687194938956873.1483488550542; Mon, 19 Jun 2023 10:15:38 -0700 (PDT) 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) 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) 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-Google-Smtp-Source: ACHHUZ79hOK048U9FmiD8UxmjFic+gzr38SXhRDhK+IvAFjDHfFBRTcwt+S/0EYLrKvoz6BgSHFKtw== 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) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?UTF-8?q?Alex=20Benn=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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1687194940934100004 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=C3=A9e Reviewed-by: Peter Maydell Reviewed-by: Richard Henderson --- 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 ------------------------ =20 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 ------------- =20 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 --------------------- =20 -This section of the manual documents various parts of the internals of QEM= U. -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. =20 +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 =20 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: + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Translator Internals =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --=20 2.39.2 From nobody Sat May 18 16:18:00 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1687194955; cv=none; d=zohomail.com; s=zohoarc; b=AaWPHYI6jra3c0AXkdVpNvDvmruByRqAk4kR/v9zXvYL2ZteQom55o9IIGb6HdFZpnygNowlRC3qcVcm5n9q48drYRLqjqW25H651aR+kmmfOR7C5YcZ/k4GFP576zDfr2N6JRz8IDwPJ4nMBJGP2GvfkRKY6BcLoNHFSOUtay8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1687194955; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=XAzDJYHeZ3egsdpPxn+zZy7ksHc4V1jiKHsxofssT6o=; b=YHUfz+6GPCjmQAY5hgRGO9TvhpkoW3o8riIIY7PXG/Vo9EBwW50somzhHjOFfM+wfApO2OcPBU4lIgurgD2h+U0Rhpvl6Nes3m++KrQsReZvKt1FaWcBuOOuIJKGZTOMwzbaR9Oc0rYDaGPxdzgGq6U+4s40c+mWhggt1DLxjNg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1687194955270762.9985873636402; Mon, 19 Jun 2023 10:15:55 -0700 (PDT) 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) 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) 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-Google-Smtp-Source: ACHHUZ7rWzF24s0Q/G2XEonCuMywCdu2q+yf1VhtarF9fi8+n2iJEPlffN7edsN29kbjN77ib9vezQ== 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) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?UTF-8?q?Alex=20Benn=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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1687194956950100001 Mention that QOM-ified devices already have support for registering the description. Signed-off-by: Alex Benn=C3=A9e Acked-by: Peter Xu Reviewed-by: Juan Quintela Reviewed-by: Philippe Mathieu-Daud=C3=A9 Reviewed-by: Richard Henderson --- 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, u= int32_t instance_id, int required_for_version, Error **errp); =20 -/* Returns: 0 on success, -1 on failure */ +/** + * vmstate_register() - legacy function to register state serialisation de= scription + * + * 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) --=20 2.39.2 From nobody Sat May 18 16:18:00 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1687194977; cv=none; d=zohomail.com; s=zohoarc; b=B8/GWKOQyYa3w1UiWxcSlTyFYlZhGZdw+hB04ZDo233v3zwpTtdqBuc615LLe/sazEd7qDKdEbBh69ZJVFFGoFZsPr4CJ2UHhUI3m9jPXdxCEs3docQUFlfePRrfFQ5RucSUsB8vhI43NCRbHKbkTYM/a2NAVtLneXxen5NX+zk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1687194977; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=pkFrDIIweegbRGGdzIcZRYuzCjxf5L+g2rFiEeEv9p8=; b=UsK3QIWNfwlfIFkqLRmUX+NNiNC2K3QGZtObTgo08aIJ3ReKPlrCA3d6/BwYG7jSpgeiqGs/0euHGVk7xD/nhzA1lbKjmrSkxDEZ37D4+UYEXJowfbF3kXrJF7UruW10z+IsuhYb5SNQbEr9IhjYYWZ38tfLiMzLlqiuwleUV3g= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1687194976989287.0022490629159; Mon, 19 Jun 2023 10:16:16 -0700 (PDT) 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) 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) 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-Google-Smtp-Source: ACHHUZ7LA14Q5MOFCl75+yq8/Q25+YyTaT3zW5z+Tl9CIaXSTvbUjNMHfadhxm58faiDKBqEJ8wT2Q== 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) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?UTF-8?q?Alex=20Benn=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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1687194977871100007 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=C3=A9e 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); =20 /** - * 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: */ =20 + /** + * @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; =20 - /* - * 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_; =20 - /* - * Can this device be instantiated with -device / device_add? + /** + * @user_creatable: Can this device be instantiated with -device / dev= ice_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; =20 /* 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; =20 - /* device state */ + /** + * @vmsd: device state serialisation description for + * migration/save/restore + */ const VMStateDescription *vmsd; =20 - /* Private to qdev / bus. */ + /** + * @bus_type: bus type + * private: to qdev / bus. + */ const char *bus_type; }; =20 @@ -168,36 +192,91 @@ typedef struct { } MemReentrancyGuard; =20 /** - * 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: */ =20 + /** + * @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 migr= ation + */ 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 setu= ps + */ 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 inter= face. + */ ResettableState reset; + /** + * @unplug_blockers: list of reasons to block unplugging of device + */ GSList *unplug_blockers; =20 - /* Is the device currently in mmio/pio/dma? Used to prevent re-entranc= y */ + /** + * @mem_reentrancy_guard: Is the device currently in mmio/pio/dma? + * + * Used to prevent re-entrancy confusing things. + */ MemReentrancyGuard mem_reentrancy_guard; }; =20 @@ -265,7 +344,7 @@ typedef struct BusChild { #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler" =20 /** - * 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 { }; =20 /** - * 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); =20 /** - * @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 --=20 2.39.2 From nobody Sat May 18 16:18:00 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1687194940; cv=none; d=zohomail.com; s=zohoarc; b=WZ2ZwNX6XlU4SkNft8MZZucVB0LBfRbYEj/+8Zq/4MawWiGXbLu1YfA9YtrSaLmkzxn5s0KyGXWzXQzoLTql7nIOpLzfX6r2SUe6HsbFEN65WnGWYGjwE8G9827rI1bSW2YFz7NinVdNouV8SipkOwbbhzUbYK2vm5u4hE3wK9U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1687194940; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=pNCXKy9KD1nbv+iKj9nGFzUMHc9zCSFXe2xCj+cXcBY=; b=A429ixIJ/s0m6NaZOFbkHqbl3BcbIKAzHHPXJOp+3HHYsA+vJEamSHisjQ9NNhenlt5pud3ynYwdjSyycKALCUmhlIOi1cJNJTg2ZFDtCEooMiiLW8Tl4aNbei3o4P5+TGf4bVsxl/VY9B6LolaAbuGkWpzbV76OJOXf3PxRpCQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1687194940594117.49668328021983; Mon, 19 Jun 2023 10:15:40 -0700 (PDT) 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) 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) 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-Google-Smtp-Source: ACHHUZ5lZjRdqyIDUUfDkWl5AJxY0jw80UcjPv/p3EEkQgqPiUOkQrHpZIjIYMpat94HpOmVzdMwjw== 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) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?UTF-8?q?Alex=20Benn=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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1687194940907100003 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=C3=A9e Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- 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: + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D +QEMU Device (qdev) API Reference +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D + +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: + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU Object Model (QOM) API Reference +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 ------------- =20 -.. kernel-doc:: include/qom/object.h +See the :ref:`QOM API` and :ref:`QDEV API` +documents for the complete API description. --=20 2.39.2 From nobody Sat May 18 16:18:00 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1687194976; cv=none; d=zohomail.com; s=zohoarc; b=XBmsUdCg5gnrklwi2vNj4HeXpXDwXZBCGMaGYk2Tl0j6YltIMMK8JvNnVSo8ziioGfsKwT3xoQcto4LNbV/U8ccbRnr306hbrH2gpCIkh4alqRaLSv3bBmyuJujtqN2PzKVi8qMt+W0Myv+hA46UmZsoZy399ZeD+08ajOH3oh8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1687194976; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=VqZkN80sHKFG/1nL+XOE6YDm/Z/wk4N5tP5bpONv3gA=; b=UfR+zSqr8tPRyM99kWaM2bXCysxsgPcltiu3ida52uMduJcbjaTayejmH6pJ0yomLv5vkAZQvVExM08cuYk8FBgyRHvXyByboTUe3rJUHkizSmvMGTG1da8pqcA25m1SX0d3Es277TAtWLDCEy9RvjuSpxU5JzLPHOovHbOsHq0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1687194976651232.1521017963936; Mon, 19 Jun 2023 10:16:16 -0700 (PDT) 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) 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) 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-Google-Smtp-Source: ACHHUZ4RVGdbNB2/6AvDGaAdEcs0J+loHI11h4eZlZGSjQ2ZP3s1RQke1+uwDBnC1E5Yr3pjV8b4zw== 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) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Eduardo Habkost , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Paolo Bonzini , Markus Armbruster , Peter Xu , Mark Cave-Ayland , Peter Maydell , Juan Quintela , Richard Henderson , Leonardo Bras , =?UTF-8?q?Alex=20Benn=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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1687194977201100005 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=C3=A9e --- 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +A simple minimal device implementation may look something like bellow: =20 .. code-block:: c :caption: Creating a minimal type --=20 2.39.2