From patchwork Mon Jun 19 17:14:32 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: 1796764 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=NtSdXyaI; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4QlGcv2r5mz20XQ for ; Tue, 20 Jun 2023 03:15:59 +1000 (AEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qBISq-0003N6-U4; 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 1qBISg-0003JW-EO for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:42 -0400 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qBISe-00024l-IG for qemu-devel@nongnu.org; Mon, 19 Jun 2023 13:14:41 -0400 Received: by mail-wm1-x331.google.com with SMTP id 5b1f17b1804b1-3f9b1a117caso9765425e9.0 for ; Mon, 19 Jun 2023 10:14:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1687194878; x=1689786878; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=18OB37PiymPp8QdWzggDlsju2ZBXu6+fyUF/Fezk7Jc=; b=NtSdXyaIR61+iOQh6m9J8YpTv6jaGXeUlBCJKdIulZqw+bK5ajm39zTGWZb3fREygr D+jzerwC5dZSDjGiBVDvmEaB/l0xk84U0o0UkP0rcND95dCcdRQXdDwKEm5pMPiUXQ4p +a29Wtsfpa1fZFQRoytg+hfYahwwY2a6C6VPZ7yRRsZxDKzePKTYJtP/su952rAVyQWa AIcUqvn+jhVsNBQVoLvQHLXkViBD6drptUnVpGe7kwaL/6mreqMz6QCe/0AM8He8whFj 6wlGXaNQipmzPnfjxV85oUhx82PbBDBmBwlkScUWAem7G0SkEPdsl7RaYM3FIMuOl0UT wPAw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687194878; x=1689786878; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=18OB37PiymPp8QdWzggDlsju2ZBXu6+fyUF/Fezk7Jc=; b=igH4S+EmJvo2RKbNpFfoml/3iNMqA6UdJf1hEjRUodqdNBZOLQGt/il9P4pGFLi9+L xoiVn3/xL+z0DuffzwnfCnwK7E6L9G1KygJRbxuaDZRBLccTQDyILD0IDi/WZ2Bh9O+D kQMGKHoRJB4SUSFG8VGrzVPxQ+0BjgI9oVTD6FvG73vFnvrBZMVxmHPG3lR0mksFB10O 0EARot3Bv9I6KSqMgKtPl+22en1ZvfuGGaSgYhO83Bk6/UdaBh/YNM3whGErWAf25MDs oQyW6M1vuuGi3IfwyU6+jOjvFcsvNta1FVSONaAwOBtsDibo+PSGloS2rAxSUexdcbWs msXg== X-Gm-Message-State: AC+VfDym81/QiRJkBYf4vpUM7K7BjeW3CD9SE9ZFKRtFNCn7Mx0hvP4w 88KZQBEouPmC1ZuYr8W+zI7TMg== X-Google-Smtp-Source: ACHHUZ719CRSG1X7rUK0JbHvN/8Jfa6USEiejS8A3JCnZxEjHylS9FK4T9NEyNEbOK1ZlcBB29gPPQ== X-Received: by 2002:a7b:cb89:0:b0:3f9:5db4:e8dd with SMTP id m9-20020a7bcb89000000b003f95db4e8ddmr2734008wmi.34.1687194878323; Mon, 19 Jun 2023 10:14:38 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id p25-20020a05600c205900b003f9b1131a90sm252641wmg.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:37 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 5909F1FFBB; 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 0/5] docs/devel: improve API documentation for QOM Date: Mon, 19 Jun 2023 18:14:32 +0100 Message-Id: <20230619171437.357374-1-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::331; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x331.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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Hi, At the recent QEMU maintainers summit we lamented the fact it was hard to push forward with our modernising plans as legacy approaches still get introduced into the code. A lot of knowledge about the "modern" way of doing things is locked up in senior developers heads. Lets make a push to improve the developer documentation and ensure best practice is easy to find. Some sort of parable about distribution of fishes and knowledge seems appropriate here. Alex Bennée (5): docs/devel: add some front matter to the devel index include/migration: mark vmstate_register() as a legacy function include/hw/qdev-core: fixup kerneldoc annotations (!COMPLETE) docs/devel: split qom-api reference into new file docs/devel: introduce some key concepts for QOM development docs/devel/index-api.rst | 2 + docs/devel/index-process.rst | 2 + docs/devel/index-tcg.rst | 2 + docs/devel/index.rst | 24 ++++++- docs/devel/qdev-api.rst | 12 ++++ docs/devel/qom-api.rst | 9 +++ docs/devel/qom.rst | 50 +++++++++++++- docs/devel/tcg.rst | 2 + include/hw/qdev-core.h | 123 +++++++++++++++++++++++++++++------ include/migration/vmstate.h | 9 ++- 10 files changed, 210 insertions(+), 25 deletions(-) create mode 100644 docs/devel/qdev-api.rst create mode 100644 docs/devel/qom-api.rst