From patchwork Mon Mar 14 10:49:41 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Kashyap Chamarthy X-Patchwork-Id: 12780023 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 382FFC433EF for ; Mon, 14 Mar 2022 10:52:01 +0000 (UTC) Received: from localhost ([::1]:44716 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nTiIy-00067K-BF for qemu-devel@archiver.kernel.org; Mon, 14 Mar 2022 06:52:00 -0400 Received: from eggs.gnu.org ([209.51.188.92]:36102) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nTiH5-0004bZ-4U for qemu-devel@nongnu.org; Mon, 14 Mar 2022 06:50:03 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:37209) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nTiH2-0004OD-Px for qemu-devel@nongnu.org; Mon, 14 Mar 2022 06:50:02 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1647255000; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+OvWci0yWarAwRj37UrhUyvV4jWc9ZT+6Swnw675Ygs=; b=B6j3wLZWoMerFLMzY41TubJWeP7wLRrZzU6ZurbcLGl9evznFIT4ajCvocy0BDvL5Wd7/V 56oSTkSn/MJLsZ3TOfLfS3i84HPcSTqKO3W8dOakHyco9vwlyxs+QJ/jKOUOB0z96Gpyyr GISlWtFyvIjBKbzrNeEdPo3cJxS17w4= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-658-L2jFWk7uNNOPPG3JZfeA4g-1; Mon, 14 Mar 2022 06:49:56 -0400 X-MC-Unique: L2jFWk7uNNOPPG3JZfeA4g-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EC42C811E7A; Mon, 14 Mar 2022 10:49:55 +0000 (UTC) Received: from localhost.localdomain (unknown [10.39.195.139]) by smtp.corp.redhat.com (Postfix) with ESMTP id B3BFE4050C65; Mon, 14 Mar 2022 10:49:54 +0000 (UTC) From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 1/3] docs: rSTify "security-process" page; move it to QEMU Git Date: Mon, 14 Mar 2022 11:49:41 +0100 Message-Id: <20220314104943.513593-2-kchamart@redhat.com> In-Reply-To: <20220314104943.513593-1-kchamart@redhat.com> References: <20220314104943.513593-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.082, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: , Cc: pbonzini@redhat.com, thuth@redhat.com, Kashyap Chamarthy , eblake@redhat.com, peter.maydell@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" This is based on Paolo's suggestion[1] that the 'security-process'[2] page being a candidate for docs/devel. Converted from Markdown to rST using: $> pandoc -f markdown -t rst security-process.md \ -o security-process.rst It's a 1-1 conversion (I double-checked to the best I could). I've also checked that the hyperlinks work correctly post-conversion. [1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html [2] https://www.qemu.org/contribute/security-process Suggested-by: Paolo Bonzini Signed-off-by: Kashyap Chamarthy Reviewed-by: Peter Maydell --- docs/devel/index.rst | 1 + docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 docs/devel/security-process.rst diff --git a/docs/devel/index.rst b/docs/devel/index.rst index afd937535e..424eff9294 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -48,3 +48,4 @@ modifying QEMU's source code. trivial-patches submitting-a-patch submitting-a-pull-request + security-process diff --git a/docs/devel/security-process.rst b/docs/devel/security-process.rst new file mode 100644 index 0000000000..cc1000fe43 --- /dev/null +++ b/docs/devel/security-process.rst @@ -0,0 +1,190 @@ +.. _security-process: + +Security Process +================ + +Please report any suspected security issue in QEMU to the security +mailing list at: + +- ` `__ + +To report an issue via `GPG `__ encrypted email, +please send it to the Red Hat Product Security team at: + +- ` `__ + +**Note:** after the triage, encrypted issue details shall be sent to the +upstream ‘qemu-security’ mailing list for archival purposes. + +How to report an issue +---------------------- + +- Please include as many details as possible in the issue report. Ex: + + - QEMU version, upstream commit/tag + - Host & Guest architecture x86/Arm/PPC, 32/64 bit etc. + - Affected code area/snippets + - Stack traces, crash details + - Malicious inputs/reproducer steps etc. + - Any configurations/settings required to trigger the issue. + +- Please share the QEMU command line used to invoke a guest VM. + +- Please specify whom to acknowledge for reporting this issue. + +How we respond +~~~~~~~~~~~~~~ + +- Process of handling security issues comprises following steps: + + 0) **Acknowledge:** + + - A non-automated response email is sent to the reporter(s) to + acknowledge the reception of the report. (*60 day’s counter starts + here*) + + 1) **Triage:** + + - Examine the issue details and confirm whether the issue is genuine + - Validate if it can be misused for malicious purposes + - Determine its worst case impact and severity + [Low/Moderate/Important/Critical] + + 2) **Response:** + + - Negotiate embargo timeline (if required, depending on severity) + - Request a `CVE `__ and open an + upstream `bug `__ + - Create an upstream fix patch annotated with + + - CVE-ID + - Link to an upstream bugzilla + - Reported-by, Tested-by etc. tags + + - Once the patch is merged, close the upstream bug with a link to + the commit + + - Fixed in: + +- Above security lists are operated by select analysts, maintainers + and/or representatives from downstream communities. + +- List members follow a **responsible disclosure** policy. Any + non-public information you share about security issues, is kept + confidential within members of the QEMU security team and a minimal + supporting staff in their affiliated companies. Such information will + not be disclosed to third party organisations/individuals without + prior permission from the reporter(s). + +- We aim to process security issues within maximum of **60 days**. That + is not to say that issues will remain private for 60 days, nope. + After the triaging step above + + - If severity of the issue is sufficiently low, an upstream public + bug will be created immediately. + - If severity of the issue requires co-ordinated disclosure at a + future date, then the embargo process below is followed, and + upstream bug will be opened at the end of the embargo period. + + This will allow upstream contributors to create, test and track fix + patch(es). + +Publication embargo +~~~~~~~~~~~~~~~~~~~ + +- If a security issue is reported that is not already public and its + severity requires coordinated disclosure, then an embargo date will + be set and communicated to the reporter(s). + +- Embargo periods will be negotiated by mutual agreement between + reporter(s), members of the security list and other relevant parties + to the problem. The preferred embargo period is upto `2 + weeks `__. + However, longer embargoes may be negotiated if the severity of the + issue requires it. + +- Members of the security list agree not to publicly disclose any + details of an embargoed security issue until its embargo date + expires. + +CVE allocation +~~~~~~~~~~~~~~ + +Each security issue is assigned a `CVE `__ +number. The CVE number is allocated by one of the vendor security +engineers on the security list. + +When to contact the QEMU Security List +-------------------------------------- + +You should contact the Security List if: \* You think there may be a +security vulnerability in QEMU. \* You are unsure about how a known +vulnerability affects QEMU. \* You can contact us in English. We are +unable to respond in other languages. + +When *not* to contact the QEMU Security List +-------------------------------------------- + +- You need assistance in a language other than English. +- You require technical assistance (for example, “how do I configure + QEMU?”). +- You need help upgrading QEMU due to security alerts. +- Your issue is not security related. + +How impact and severity of a bug is decided +------------------------------------------- + +**Security criterion:** -> +https://www.qemu.org/docs/master/system/security.html + +All security issues in QEMU are not equal. Based on the parts of the +QEMU sources wherein the bug is found, its impact and severity could +vary. + +In particular, QEMU is used in many different scenarios; some of them +assume that the guest is trusted, some of them don’t. General +considerations to triage QEMU issues and decide whether a configuration +is security sensitive include: + +- Is there any feasible way for a malicious party to exploit this flaw + and cause real damage? (e.g. from a guest or via downloadable images) +- Does the flaw require access to the management interface? Would the + management interface be accessible in the scenario where the flaw + could cause real damage? +- Is QEMU used in conjunction with a hypervisor (as opposed to TCG + binary translation)? +- Is QEMU used to offer virtualised production services, as opposed to + usage as a development platform? + +Whenever some or all of these questions have negative answers, what +appears to be a major security flaw might be considered of low severity +because it could only be exercised in use cases where QEMU and +everything interacting with it is trusted. + +For example, consider upstream commit `9201bb9 “sdhci.c: Limit the +maximum block +size” `__, an of +out of bounds (OOB) memory access (ie. buffer overflow) issue that was +found and fixed in the SD Host Controller emulation (hw/sd/sdhci.c). + +On the surface, this bug appears to be a genuine security flaw, with +potentially severe implications. But digging further down, there are +only two ways to use SD Host Controller emulation, one is via +‘sdhci-pci’ interface and the other is via ‘generic-sdhci’ interface. + +Of these two, the ‘sdhci-pci’ interface had actually been disabled by +default in the upstream QEMU releases (commit `1910913 “sdhci: Make +device”sdhci-pci" unavailable with +-device" `__ at +the time the flaw was reported; therefore, guests could not possibly use +‘sdhci-pci’ for any purpose. + +The ‘generic-sdhci’ interface, instead, had only one user in ‘Xilinx +Zynq Baseboard emulation’ (hw/arm/xilinx_zynq.c). Xilinx Zynq is a +programmable systems on chip (SoC) device. While QEMU does emulate this +device, in practice it is used to facilitate cross-platform +developmental efforts, i.e. QEMU is used to write programs for the SoC +device. In such developer environments, it is generally assumed that the +guest is trusted. + +And thus, this buffer overflow turned out to be a security non-issue. From patchwork Mon Mar 14 10:49:42 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kashyap Chamarthy X-Patchwork-Id: 12780028 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 2D97BC433F5 for ; Mon, 14 Mar 2022 10:54:27 +0000 (UTC) Received: from localhost ([::1]:49364 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nTiLK-0000u8-1V for qemu-devel@archiver.kernel.org; Mon, 14 Mar 2022 06:54:26 -0400 Received: from eggs.gnu.org ([209.51.188.92]:36116) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nTiH6-0004cd-Fc for qemu-devel@nongnu.org; Mon, 14 Mar 2022 06:50:04 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]:33254) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nTiH3-0004OP-J3 for qemu-devel@nongnu.org; Mon, 14 Mar 2022 06:50:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1647255000; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=BArEaYl58nIRfFrk4u1GodafaKu1a057MDoK7aemt/g=; b=X0H6y558R3ZoIZb3Gl6Op5TUkVxNi/Y/Qn5h3KhoewQd4OOgjimXWnarKV8AxdqzCBqhIO 3Jr+djLXoyJMeRWfDfJ5A66oiaSvKG0r28LfEyAL+cyBsmC/Kc+secTY89W15w+ti4KqGk vyLOEtmSiG2MBc/wA/shERnZZsHaEYs= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-249-IPZze3ByPI-ybuba2JeLsw-1; Mon, 14 Mar 2022 06:49:58 -0400 X-MC-Unique: IPZze3ByPI-ybuba2JeLsw-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id B9D621875067; Mon, 14 Mar 2022 10:49:57 +0000 (UTC) Received: from localhost.localdomain (unknown [10.39.195.139]) by smtp.corp.redhat.com (Postfix) with ESMTP id 343B54050C65; Mon, 14 Mar 2022 10:49:56 +0000 (UTC) From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git Date: Mon, 14 Mar 2022 11:49:42 +0100 Message-Id: <20220314104943.513593-3-kchamart@redhat.com> In-Reply-To: <20220314104943.513593-1-kchamart@redhat.com> References: <20220314104943.513593-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.129.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.082, 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: , Cc: pbonzini@redhat.com, thuth@redhat.com, Kashyap Chamarthy , eblake@redhat.com, peter.maydell@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" This document is referred to from the GettingStartedDevelopers wiki which will be rSTified in a follow-up commit. Converted from Mediawiki to rST using: $> pandoc -f Mediawiki -t rst MailingLists.wiki -o mailing-lists.rst It's a 1-1 conversion (I double-checked to the best I could). I've also checked that the hyperlinks work correctly post-conversion. Signed-off-by: Kashyap Chamarthy Reviewed-by: Thomas Huth --- docs/devel/index.rst | 1 + docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/devel/mailing-lists.rst diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 424eff9294..fb9d9f3a80 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -12,6 +12,7 @@ modifying QEMU's source code. code-of-conduct conflict-resolution + mailing-lists build-system style kconfig diff --git a/docs/devel/mailing-lists.rst b/docs/devel/mailing-lists.rst new file mode 100644 index 0000000000..53dcbfb007 --- /dev/null +++ b/docs/devel/mailing-lists.rst @@ -0,0 +1,53 @@ +.. _mailing-lists: + +Mailing lists +============= + +- `QEMU developers mailing + list `__ +- `QEMU stable mailing + list `__ +- `QEMU trivial patch mailing + list `__ +- `QEMU users mailing + list `__ + +.. _subsystem_specific_lists: + +Subsystem Specific Lists +------------------------ + +These exist to make it a little easier to follow subsystem specific +patches. You should however continue to CC qemu-devel so your series +gets wide visibility. + +- `QEMU ARM mailing + list `__ +- `QEMU block devices mailing + list `__ +- `QEMU PowerPC mailing + list `__ +- `QEMU RISC-V mailing + list `__ +- `QEMU s390x mailing + list `__ + +If a subsystem maintainer thinks that a new mailing list for their +subsystem would make life easier, we're happy to create one -- mail +qemu-devel to suggest it (ideally cc'ing the people listed as Savannah +project admins in our `AdminContacts `__ page, as they +are the ones with the ability to make the change). + +If you are a Savannah project admin, you may want the `technical notes +on how to create and configure a new +list `__. + +.. _access_via_lore.kernel.org: + +Access via lore.kernel.org +-------------------------- + +The qemu-devel mailing list is also archived via +`public-inbox `__ on +https://lore.kernel.org/qemu-devel/ and accessible via NNTP at +nntp.lore.kernel.org (newsgroup org.nongnu.qemu-devel). From patchwork Mon Mar 14 10:49:43 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kashyap Chamarthy X-Patchwork-Id: 12780029 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 94DBAC433EF for ; Mon, 14 Mar 2022 10:56:25 +0000 (UTC) Received: from localhost ([::1]:51878 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nTiNE-0002fx-H8 for qemu-devel@archiver.kernel.org; Mon, 14 Mar 2022 06:56:24 -0400 Received: from eggs.gnu.org ([209.51.188.92]:36164) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nTiHB-0004g3-4L for qemu-devel@nongnu.org; Mon, 14 Mar 2022 06:50:09 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]:26950) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nTiH7-0004b2-Kp for qemu-devel@nongnu.org; Mon, 14 Mar 2022 06:50:07 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1647255005; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=V5D5XY94fVZu1yqHQ2EE5JqRtI18NvgF23X8rdwRAHA=; b=JFmeGSeVb+3uI/whXLAykVl/16g5x91JaQgvYyoDsJRn36YxF4Dij9CP7Feo2g/NzSZs4r hy1eYjsrsRlP0DQS5Kcj8wCfzcravPhFBB0zV6BeyDEtm0yRjHdFpKMtC72gGqJo2s6hqd PhNLTclz05aPdjCOCNopZMsvXw91+wU= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-199-ZJx72FyoPVy24kLAfpUADg-1; Mon, 14 Mar 2022 06:49:59 -0400 X-MC-Unique: ZJx72FyoPVy24kLAfpUADg-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id E949F1875068; Mon, 14 Mar 2022 10:49:58 +0000 (UTC) Received: from localhost.localdomain (unknown [10.39.195.139]) by smtp.corp.redhat.com (Postfix) with ESMTP id F17164050C66; Mon, 14 Mar 2022 10:49:57 +0000 (UTC) From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 3/3] docs: rSTify GettingStartedDevelopers wiki; move it to QEMU Git Date: Mon, 14 Mar 2022 11:49:43 +0100 Message-Id: <20220314104943.513593-4-kchamart@redhat.com> In-Reply-To: <20220314104943.513593-1-kchamart@redhat.com> References: <20220314104943.513593-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.129.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.082, 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: , Cc: pbonzini@redhat.com, thuth@redhat.com, Kashyap Chamarthy , eblake@redhat.com, peter.maydell@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" Converted the wiki[1] from Markdown to rST using: $> pandoc -f Mediawiki -t rst getting-started-developers.wiki -o getting-started-developers.rst It's a 1-1 conversion (I double-checked to the best I could). I've also checked that the hyperlinks work correctly post-conversion. [1] https://wiki.qemu.org/Documentation/GettingStartedDevelopers Signed-off-by: Kashyap Chamarthy --- docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++ docs/devel/index.rst | 1 + 2 files changed, 201 insertions(+) create mode 100644 docs/devel/getting-started-developers.rst diff --git a/docs/devel/getting-started-developers.rst b/docs/devel/getting-started-developers.rst new file mode 100644 index 0000000000..1299e1dfee --- /dev/null +++ b/docs/devel/getting-started-developers.rst @@ -0,0 +1,200 @@ +.. _getting-started-developers: + +Getting Started for Developers +============================== + +You want to contribute code, documentation or patches to QEMU? + +Then... + +- ... you should probably first join the :ref:`mailing-lists`. + + - Mailing lists are moderated. Non-subscribers may post, so list + policy is reply-to-all to ensure original poster is included. + - Be prepared for upwards of one thousand messages per week if you + subscribe. + - First-time posts (whether subscribed or not) are subject to a + moderation delay until a human can whitelist your email address. + +- Also check out the `patch + submission `__ + page for some hints on mail contributions. + +Wiki +---- + +- To create an account in the QEMU wiki, you must ask on the mailing + list for someone else to do it on your behalf (self-creation is + prohibited to cut down on spam accounts). +- Start with reading the QEMU wiki. +- Contribute to the QEMU wiki by adding new topics or improving and + expanding existing topics. It should help you and others in the + future. + +Documentation +------------- + +- Continue with reading the `existing documentation `__ + and `Contributions Guide `__. + + Be prepared that all written documentation might be invalid - either + because it is too old or because it was never correct. And it is + never complete... + +- If you find bugs in the documentation then fix them and send patches + to the mailing list. See + `Contribute/ReportABug `__. +- If you find problems in the wiki, then fix them if you can, or add + notes to either the applicable page or the Discussion page. +- Depending on how much computer architecture / hardware background you + have, it may help to read some general books. Suggestions include: + + - "Computers as Components, Second Edition: Principles of Embedded + Computing System Design", Wayne Wolf, ISBN-13: 978-0123743978 + +Code +---- + +- Get the code. If you want to be a developer, you almost certainly + want to be building from git (see the + `Download `__ page for + the right tree). +- Compile the code. Here are some instructions how to do this: + + - `QEMU on Linux hosts `__ + - `QEMU on OS X (macOS) hosts `__ + - `QEMU on Windows hosts `__ + +- Run the QEMU system and user mode emulation for different targets + (x86, mips, powerpc, ...). Images can be obtained from the + `Testing `__ page. +- QEMU has a lot of different parts (hardware device emulation, target + emulation, code generation for different hosts, configuration, ...). + + - Choose an interesting part and concentrate on it for some time and + read the code. Its going to take some effort, so try to find + something that you are really interested in - something that will + be a least a little bit fun for you. + - It will be easier if you choose a part of the code that has an + active / responsive maintainer (since this gives you someone to + discuss things with). + +- If you find bugs in the code, then fix them and send a patch to the + mailing list (see `patch submission + process `__) + + - Patches need to go the mailing list, and possibly also to a + specific maintainer (read the MAINTAINERS text file in the top of + the source code tree). + - Read the HACKING and CODING_STYLE text files (in the top of the + source code tree) before writing the patch + - Run your patch through the . See + http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html + for how to hook it into git. + - For very small, simple changes, you can do it as a single patch. + If your change is more complex, you need to break it into smaller, + separate patches (which together form a set of patches, or a + patchset). Each step in the patch process can rely on previous + patches, but not later patches - otherwise "git bisect" will + break. This will require more effort on your part, but it saves a + lot of work for everyone else. + - If you have a lot of patches in a patchset (say five or more), + then it may help to have a public git tree. You can get hosting + from many places (repo.or.cz and github seem popular). + +.. _getting_to_know_the_code: + +Getting to know the code +------------------------ + +- QEMU does not have a high level design description document - only + the source code tells the full story. +- There are some useful (although usually dated) descriptions for + infrastructure code in various parts of the wiki, and sometimes in + mailing list descriptions: + + - Tracing framework is described at + `Features/Tracing `__ and in docs/tracing.txt in + the source tree. + - Some of the internal functionality (and a bit of the human + monitoring / control interface) is implemented in + `QAPI `__ and `QMP `__. See also + https://www.linux-kvm.org/images/1/17/2010-forum-qmp-status-talk.pp.pdf + - If you're into devices (new virtual hardware) it will help to know + about QDEV: + http://www.linux-kvm.org/images/f/fe/2010-forum-armbru-qdev.pdf + and docs/qdev-device-use.txt in the source tree + +- Things do change -- we improve our APIs and develop better ways of + doing things all the time. Reading the mailing list is important to + keep on top of these changes. You may also find the + `DeveloperNews `__ wiki page a useful summary. We try + to track API and design changes currently in progress on the + `ToDo/CodeTransitions `__ page; this may help + you avoid accidentally copying existing code which is out-of-date or + no longer following best practices. + + - We also maintain a list of + `Contribute/BiteSizedTasks `__ that can + help + +getting familiar with the code, and complete those transitions to make +things easier for the next person! + +- QEMU converts instructions in the guest system into instructions on + the host system via Tiny Code Generator (TCG). See tcg/README in the + source tree as a starting point if you want to understand this. +- Some of QEMU makes extensive use of pre-processor operations + (especially token pasting with ## operation) which can make it harder + to determine where a particular function comes from. Mulyadi Santosa + pointed out that you can use the gcc "--save-temps" option to see the + results of the pre-processor stage - see + http://the-hydra.blogspot.com/2011/04/getting-confused-when-exploring-qemu.html + for more detail. + +Bugs +---- + +- Read the Bug Tracker. +- Check for topics in it for which you feel capable of handling and try + to fix the issue. Send patches. + +.. _testing_your_changes: + +Testing your changes +-------------------- + +- You must compile test for all targets (i.e. don't restrict the + target-list at configure time). Make sure its a clean build if you + are not sure. +- Think about what you've changed (review the patches) and do testing + consistent with those changes. For example: + + - If you've developed a new driver (say an AHCI virtual device - + used for SATA disks), make sure that it works. Make sure anything + related still works (e.g. for AHCI, check the IDE driver, and no + disk configurations). If your new device supports migration, make + sure migration and snapshots work. + - If you're working on Xen Hardware Virtual Machine (HVM - full + virtualization), then make sure that Xen para-virtualization + works. + +- Its OK if your new implementation doesn't do everything (or has some + deficiencies / bugs). You do need to declare that in the patch + submission though. +- Main page for testing resources: `Testing `__ + +.. _getting_help: + +Getting Help +------------ + +- IRC might be useful + + - The #qemu channel is on irc://irc.oftc.net (note: no longer on + Freenode). + - You may also get a response on the #kvm channel on + irc://irc.freenode.net + +Please don't post large text dumps on IRC. Use a pastebin service to +post logs so the channel doesn't get flooded. diff --git a/docs/devel/index.rst b/docs/devel/index.rst index fb9d9f3a80..afead67200 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -13,6 +13,7 @@ modifying QEMU's source code. code-of-conduct conflict-resolution mailing-lists + getting-started-developers build-system style kconfig