From patchwork Fri Aug 9 18:08:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759079 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 CDE52C531DB for ; Fri, 9 Aug 2024 18:10:10 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2d-0000xx-6Y; Fri, 09 Aug 2024 14:08:43 -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 1scU2c-0000ww-0w for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:42 -0400 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2Z-0007C1-Q0 for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:41 -0400 Received: by mail-wr1-x432.google.com with SMTP id ffacd0b85a97d-3686b554cfcso1208533f8f.1 for ; Fri, 09 Aug 2024 11:08:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226918; x=1723831718; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=jhQP03+tlFIXCNvACIpxrmWqMTiMtqMMEpE7GGG91S4=; b=BAOg1q2xhDlp3QLZNTMmk66nLK1SPBTUQAD5lWrPsnsBA0A8sBpqXQf5X4j3pi+Ujt tBaqGDST2n/0y668bv5uy6mu7ZkEvMLqRqTbQYorZFzyWLGK4xMkwpd9GSf83Uiy6ku7 yD5QtpL1GWYuk+/xMhnpM7IO3z7MLE4G66xBLKKsJkZ5jdcR9jHhIE0XKrZPn0gHFc5g ojbDxUDL8+fsd58TuvklQMLzNwIUcYBOlHb3XCxw/rUsEs6JWv7RgpfUozbr2MFhriob dDkCQcPB2X9DLBzblCRspdyajF39ASS6HxSOXuLg5ohv7y8EMdD83A+bgMkYTUyi6zaJ GXcg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226918; x=1723831718; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=jhQP03+tlFIXCNvACIpxrmWqMTiMtqMMEpE7GGG91S4=; b=UbYCr7f/LoENJJWfnpa9SkIVEff3zm273hSJnrLW0IMKX0C98W9jtp7UBF8I0a+vCv ZeVnpOThWcTJFov4xQpXp6SVwhznEfZrF/4cBHwHKRl9dS69+h9o1cn9Vl5IK9EcnH0d E6D/Y3oJWhkFs6LCtcFzGKtPGntUoQrC3DgEUUEUqM9Sf41tkjv8/rc2XX3bEvnzwrhJ cHTkpH9muzKDWWr5/ySVyLF+RzJXvUCoQmVM7sCWQLXR7SqctT0Zkec/bBvLP3N4/XXX dDwr1RR7HnsEQUvj7u6Dw2z/esukr/CrQFrJWiNsNd0+Ft3mFoawLQIR0MyUD4u2ztmR oa5w== X-Gm-Message-State: AOJu0YwEx7FR5QbEGp/QeNAAP+T1NfXwXs8BHWoGC3cWFLHhwmc3Rhfl S3CjuEjVOFnGO91VhAQT5/6lYqGARmCODBZzCeD9ZX+VjjmXdJaJA0+ntvrG3bhhBOWLrW3Uf+y B X-Google-Smtp-Source: AGHT+IGx4kc0F+g6sGvC5+OVlRvFJ8cteY/oNBFuxVigFm1/udHUhbHZtKHuuzZcVaRP0PvpnErESA== X-Received: by 2002:a5d:6552:0:b0:368:3198:5ac4 with SMTP id ffacd0b85a97d-36d60346adbmr1685448f8f.39.1723226918077; Fri, 09 Aug 2024 11:08:38 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.37 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:37 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 01/11] target/arm: Fix BTI versus CF_PCREL Date: Fri, 9 Aug 2024 19:08:25 +0100 Message-Id: <20240809180835.1243269-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::432; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x432.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Richard Henderson With pcrel, we cannot check the guarded page bit at translation time, as different mappings of the same physical page may or may not have the GP bit set. Instead, add a couple of helpers to check the page at runtime, after all other filters that might obviate the need for the check. The set_btype_for_br call must be moved after the gen_a64_set_pc call to ensure the current pc can still be computed. Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Richard Henderson Message-id: 20240802003028.795476-1-richard.henderson@linaro.org Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- target/arm/tcg/helper-a64.h | 3 ++ target/arm/tcg/translate.h | 2 -- target/arm/tcg/helper-a64.c | 39 +++++++++++++++++++++ target/arm/tcg/translate-a64.c | 64 ++++++++-------------------------- 4 files changed, 56 insertions(+), 52 deletions(-) diff --git a/target/arm/tcg/helper-a64.h b/target/arm/tcg/helper-a64.h index 371388f61b5..481007bf397 100644 --- a/target/arm/tcg/helper-a64.h +++ b/target/arm/tcg/helper-a64.h @@ -133,6 +133,9 @@ DEF_HELPER_4(cpyfp, void, env, i32, i32, i32) DEF_HELPER_4(cpyfm, void, env, i32, i32, i32) DEF_HELPER_4(cpyfe, void, env, i32, i32, i32) +DEF_HELPER_FLAGS_1(guarded_page_check, TCG_CALL_NO_WG, void, env) +DEF_HELPER_FLAGS_2(guarded_page_br, TCG_CALL_NO_RWG, void, env, tl) + DEF_HELPER_FLAGS_5(gvec_fdiv_h, TCG_CALL_NO_RWG, void, ptr, ptr, ptr, ptr, i32) DEF_HELPER_FLAGS_5(gvec_fdiv_s, TCG_CALL_NO_RWG, void, ptr, ptr, ptr, ptr, i32) DEF_HELPER_FLAGS_5(gvec_fdiv_d, TCG_CALL_NO_RWG, void, ptr, ptr, ptr, ptr, i32) diff --git a/target/arm/tcg/translate.h b/target/arm/tcg/translate.h index a8672c857c1..01c217f4a45 100644 --- a/target/arm/tcg/translate.h +++ b/target/arm/tcg/translate.h @@ -163,8 +163,6 @@ typedef struct DisasContext { uint8_t dcz_blocksize; /* A copy of cpu->gm_blocksize. */ uint8_t gm_blocksize; - /* True if this page is guarded. */ - bool guarded_page; /* True if the current insn_start has been updated. */ bool insn_start_updated; /* Bottom two bits of XScale c15_cpar coprocessor access control reg */ diff --git a/target/arm/tcg/helper-a64.c b/target/arm/tcg/helper-a64.c index c60d2a7ec96..21a9abd90a6 100644 --- a/target/arm/tcg/helper-a64.c +++ b/target/arm/tcg/helper-a64.c @@ -1877,3 +1877,42 @@ void HELPER(cpyfe)(CPUARMState *env, uint32_t syndrome, uint32_t wdesc, { do_cpye(env, syndrome, wdesc, rdesc, false, GETPC()); } + +static bool is_guarded_page(CPUARMState *env, target_ulong addr, uintptr_t ra) +{ +#ifdef CONFIG_USER_ONLY + return page_get_flags(addr) & PAGE_BTI; +#else + CPUTLBEntryFull *full; + void *host; + int mmu_idx = cpu_mmu_index(env_cpu(env), true); + int flags = probe_access_full(env, addr, 0, MMU_INST_FETCH, mmu_idx, + false, &host, &full, ra); + + assert(!(flags & TLB_INVALID_MASK)); + return full->extra.arm.guarded; +#endif +} + +void HELPER(guarded_page_check)(CPUARMState *env) +{ + /* + * We have already verified that bti is enabled, and that the + * instruction at PC is not ok for BTYPE. This is always at + * the beginning of a block, so PC is always up-to-date and + * no unwind is required. + */ + if (is_guarded_page(env, env->pc, 0)) { + raise_exception(env, EXCP_UDEF, syn_btitrap(env->btype), + exception_target_el(env)); + } +} + +void HELPER(guarded_page_br)(CPUARMState *env, target_ulong pc) +{ + /* + * We have already checked for branch via x16 and x17. + * What remains for choosing BTYPE is checking for a guarded page. + */ + env->btype = is_guarded_page(env, pc, GETPC()) ? 3 : 1; +} diff --git a/target/arm/tcg/translate-a64.c b/target/arm/tcg/translate-a64.c index 148be2826ec..28a10135032 100644 --- a/target/arm/tcg/translate-a64.c +++ b/target/arm/tcg/translate-a64.c @@ -1507,7 +1507,14 @@ static void set_btype_for_br(DisasContext *s, int rn) { if (dc_isar_feature(aa64_bti, s)) { /* BR to {x16,x17} or !guard -> 1, else 3. */ - set_btype(s, rn == 16 || rn == 17 || !s->guarded_page ? 1 : 3); + if (rn == 16 || rn == 17) { + set_btype(s, 1); + } else { + TCGv_i64 pc = tcg_temp_new_i64(); + gen_pc_plus_diff(s, pc, 0); + gen_helper_guarded_page_br(tcg_env, pc); + s->btype = -1; + } } } @@ -1521,8 +1528,8 @@ static void set_btype_for_blr(DisasContext *s) static bool trans_BR(DisasContext *s, arg_r *a) { - gen_a64_set_pc(s, cpu_reg(s, a->rn)); set_btype_for_br(s, a->rn); + gen_a64_set_pc(s, cpu_reg(s, a->rn)); s->base.is_jmp = DISAS_JUMP; return true; } @@ -1581,8 +1588,8 @@ static bool trans_BRAZ(DisasContext *s, arg_braz *a) } dst = auth_branch_target(s, cpu_reg(s, a->rn), tcg_constant_i64(0), !a->m); - gen_a64_set_pc(s, dst); set_btype_for_br(s, a->rn); + gen_a64_set_pc(s, dst); s->base.is_jmp = DISAS_JUMP; return true; } @@ -11878,37 +11885,6 @@ static bool trans_FAIL(DisasContext *s, arg_OK *a) return true; } -/** - * is_guarded_page: - * @env: The cpu environment - * @s: The DisasContext - * - * Return true if the page is guarded. - */ -static bool is_guarded_page(CPUARMState *env, DisasContext *s) -{ - uint64_t addr = s->base.pc_first; -#ifdef CONFIG_USER_ONLY - return page_get_flags(addr) & PAGE_BTI; -#else - CPUTLBEntryFull *full; - void *host; - int mmu_idx = arm_to_core_mmu_idx(s->mmu_idx); - int flags; - - /* - * We test this immediately after reading an insn, which means - * that the TLB entry must be present and valid, and thus this - * access will never raise an exception. - */ - flags = probe_access_full(env, addr, 0, MMU_INST_FETCH, mmu_idx, - false, &host, &full, 0); - assert(!(flags & TLB_INVALID_MASK)); - - return full->extra.arm.guarded; -#endif -} - /** * btype_destination_ok: * @insn: The instruction at the branch destination @@ -12151,19 +12127,6 @@ static void aarch64_tr_translate_insn(DisasContextBase *dcbase, CPUState *cpu) if (dc_isar_feature(aa64_bti, s)) { if (s->base.num_insns == 1) { - /* - * At the first insn of the TB, compute s->guarded_page. - * We delayed computing this until successfully reading - * the first insn of the TB, above. This (mostly) ensures - * that the softmmu tlb entry has been populated, and the - * page table GP bit is available. - * - * Note that we need to compute this even if btype == 0, - * because this value is used for BR instructions later - * where ENV is not available. - */ - s->guarded_page = is_guarded_page(env, s); - /* First insn can have btype set to non-zero. */ tcg_debug_assert(s->btype >= 0); @@ -12172,12 +12135,13 @@ static void aarch64_tr_translate_insn(DisasContextBase *dcbase, CPUState *cpu) * priority -- below debugging exceptions but above most * everything else. This allows us to handle this now * instead of waiting until the insn is otherwise decoded. + * + * We can check all but the guarded page check here; + * defer the latter to a helper. */ if (s->btype != 0 - && s->guarded_page && !btype_destination_ok(insn, s->bt, s->btype)) { - gen_exception_insn(s, 0, EXCP_UDEF, syn_btitrap(s->btype)); - return; + gen_helper_guarded_page_check(tcg_env); } } else { /* Not the first insn: btype must be 0. */ From patchwork Fri Aug 9 18:08:26 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759074 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 303A6C52D7C for ; Fri, 9 Aug 2024 18:09:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2f-00016W-Gl; Fri, 09 Aug 2024 14:08: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 1scU2d-0000xy-5e for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:43 -0400 Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2a-0007C5-Tt for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:42 -0400 Received: by mail-wr1-x430.google.com with SMTP id ffacd0b85a97d-3684407b2deso1263620f8f.1 for ; Fri, 09 Aug 2024 11:08:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226919; x=1723831719; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=9H8W0O0b1Ww323Eya3NUzzCuyPiKzt+1Rqu3lq0GOBs=; b=Z2YPnO3BEUFXgX0OUNHn4jXBqVYCdz/hk4bdotPv8j76VDRxtP+bLAbjO6QF5x+TeT TZVidLI+h8cBUbDQyJGPnb4aAnZLstG6yRINDZ3pwP3DvCLuWUpqJ94Uamji125tr46p Qv8OA0LBD+oExy/8wDbg9VvLFz14ZOOPTM96YHRZhFAHDyN59AHiCagmwPDlH8vw3tJK B65kRsY7yt8Mz4Q3Umr+B6tvwLoPy4LHJRBVxzIIhbSqoS7kGnuOGQ5RSmy73rTWorI3 WHb5fCVMzWhpytMqyPl88WoLXrEGzDfcxKjibvIOjgnKumGXwGqzOS5zVYAffy5q3MCl pQ6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226919; x=1723831719; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=9H8W0O0b1Ww323Eya3NUzzCuyPiKzt+1Rqu3lq0GOBs=; b=PO5GZRQbfmPx2TRZIb16QxfmBH6UTZz4QsRn8OKte2vxbRcmlLMJxCTVz2ZqRgvYgb bITe9looHr1xmzk1PxYtoYpm/Mbuk+a7SXD6FHO4Uju/aeAWjGHYBvqi+2JVJ38wxB0H 6YrWemgvWyEi0xx+kqgtkdI7GY33KqAoImTQBNW8ohVUZPmaCtpAKXDj6fW8q0kBkiBc PvQBlF3abecQP6MevFjAsDsooyR9p/N9e458LfkqCbb8/Trk7GzWHGZzUfBOVH7tunsr uVLQPUtF50fh5GCiOh+ynLVvgajvZk+9+9WWyYSu0CXyJqylC/zoNRx/6mOGuRvlts7f mjgQ== X-Gm-Message-State: AOJu0YyEcL9vP9pkXkJw33xS7OT22F+GF6XQXVVI5kQi+R89LDHVoXXo bdXi7leACp2cGTZ696JqMPEC3/I+Xq13dowNTfBrQK3UdQkY9UhE1YJiI5bAwu+lzepBy0wErjJ j X-Google-Smtp-Source: AGHT+IGyIqLACViZKl7GbGD+tUL/2MFBIOkiBElfrunkUJCM0KzRQSFKZ2fl2FhPy2YBzcKdVJdLRg== X-Received: by 2002:adf:fb46:0:b0:367:96d6:4c2d with SMTP id ffacd0b85a97d-36d5e4d2ad4mr1756404f8f.25.1723226918692; Fri, 09 Aug 2024 11:08:38 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.38 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:38 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 02/11] include: Fix typo in name of MAKE_IDENTFIER macro Date: Fri, 9 Aug 2024 19:08:26 +0100 Message-Id: <20240809180835.1243269-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::430; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x430.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org In commit bb71846325e23 we added some macro magic to avoid variable-shadowing when using some of our more complicated macros. One of the internal components of this is a macro named MAKE_IDENTFIER. Fix the typo in its name: it should be MAKE_IDENTIFIER. Commit created with sed -i -e 's/MAKE_IDENTFIER/MAKE_IDENTIFIER/g' include/qemu/*.h include/qapi/qmp/qobject.h Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster Reviewed-by: Philippe Mathieu-Daudé Message-id: 20240801102516.3843780-1-peter.maydell@linaro.org --- include/qapi/qmp/qobject.h | 2 +- include/qemu/atomic.h | 2 +- include/qemu/compiler.h | 2 +- include/qemu/osdep.h | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/include/qapi/qmp/qobject.h b/include/qapi/qmp/qobject.h index 89b97d88bca..256d782688c 100644 --- a/include/qapi/qmp/qobject.h +++ b/include/qapi/qmp/qobject.h @@ -54,7 +54,7 @@ struct QObject { typeof(obj) _obj = (obj); \ _obj ? container_of(&_obj->base, QObject, base) : NULL; \ }) -#define QOBJECT(obj) QOBJECT_INTERNAL((obj), MAKE_IDENTFIER(_obj)) +#define QOBJECT(obj) QOBJECT_INTERNAL((obj), MAKE_IDENTIFIER(_obj)) /* Required for qobject_to() */ #define QTYPE_CAST_TO_QNull QTYPE_QNULL diff --git a/include/qemu/atomic.h b/include/qemu/atomic.h index dc4118ddd9e..7a3f2e6576b 100644 --- a/include/qemu/atomic.h +++ b/include/qemu/atomic.h @@ -128,7 +128,7 @@ _val; \ }) #define qatomic_rcu_read(ptr) \ - qatomic_rcu_read_internal((ptr), MAKE_IDENTFIER(_val)) + qatomic_rcu_read_internal((ptr), MAKE_IDENTIFIER(_val)) #define qatomic_rcu_set(ptr, i) do { \ qemu_build_assert(sizeof(*ptr) <= ATOMIC_REG_SIZE); \ diff --git a/include/qemu/compiler.h b/include/qemu/compiler.h index 554c5ce7df7..c06954ccb41 100644 --- a/include/qemu/compiler.h +++ b/include/qemu/compiler.h @@ -38,7 +38,7 @@ #endif /* Expands into an identifier stemN, where N is another number each time */ -#define MAKE_IDENTFIER(stem) glue(stem, __COUNTER__) +#define MAKE_IDENTIFIER(stem) glue(stem, __COUNTER__) #ifndef likely #define likely(x) __builtin_expect(!!(x), 1) diff --git a/include/qemu/osdep.h b/include/qemu/osdep.h index 4cc4c32b144..fe7c3c5f673 100644 --- a/include/qemu/osdep.h +++ b/include/qemu/osdep.h @@ -399,7 +399,7 @@ void QEMU_ERROR("code path is reachable") }) #undef MIN #define MIN(a, b) \ - MIN_INTERNAL((a), (b), MAKE_IDENTFIER(_a), MAKE_IDENTFIER(_b)) + MIN_INTERNAL((a), (b), MAKE_IDENTIFIER(_a), MAKE_IDENTIFIER(_b)) #define MAX_INTERNAL(a, b, _a, _b) \ ({ \ @@ -408,7 +408,7 @@ void QEMU_ERROR("code path is reachable") }) #undef MAX #define MAX(a, b) \ - MAX_INTERNAL((a), (b), MAKE_IDENTFIER(_a), MAKE_IDENTFIER(_b)) + MAX_INTERNAL((a), (b), MAKE_IDENTIFIER(_a), MAKE_IDENTIFIER(_b)) #ifdef __COVERITY__ # define MIN_CONST(a, b) ((a) < (b) ? (a) : (b)) @@ -440,7 +440,7 @@ void QEMU_ERROR("code path is reachable") _a == 0 ? _b : (_b == 0 || _b > _a) ? _a : _b; \ }) #define MIN_NON_ZERO(a, b) \ - MIN_NON_ZERO_INTERNAL((a), (b), MAKE_IDENTFIER(_a), MAKE_IDENTFIER(_b)) + MIN_NON_ZERO_INTERNAL((a), (b), MAKE_IDENTIFIER(_a), MAKE_IDENTIFIER(_b)) /* * Round number down to multiple. Safe when m is not a power of 2 (see From patchwork Fri Aug 9 18:08:27 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759081 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 E8122C52D7F for ; Fri, 9 Aug 2024 18:10:10 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2g-0001AU-HO; Fri, 09 Aug 2024 14:08: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 1scU2e-00013D-JB for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:44 -0400 Received: from mail-wr1-x42a.google.com ([2a00:1450:4864:20::42a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2b-0007CG-G0 for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:44 -0400 Received: by mail-wr1-x42a.google.com with SMTP id ffacd0b85a97d-3687fd09251so1249716f8f.0 for ; Fri, 09 Aug 2024 11:08:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226920; x=1723831720; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=pcTrq9FcAyVIHTx7LxJip+z/+kVAskuuP786YAuXnNs=; b=FuuBvA32aIjAfy551kYFl6UtHGCj+lwrx685YKx62sUm/LWH1a5hF2cCH7cW96Aq9N 0mTHPP1jYksCef/ZPH4km1+TEBWSBeVXPiKFWtYZ1AgTLdPx/ATb59FIaceFBoNWludz IHNQyKHZT4FQ/6ofD0hVNPT/ZbE5RmhqVj7EWYsV+Tz19zcbjBImNBxdrCXxMdLiy9GD lUKKtTJbStp1IyPNxM8FSZUbgM+5j5LpPaZP34gY4y9UBqNFrevPCwWnIDhPRTD/ayux F08J0lDS0yo2tI/nbAuLlA+oWDr8KqywgCNBl7kXTJEmPU7ARGzJ/THgeJLccNri/+gB GBfg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226920; x=1723831720; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=pcTrq9FcAyVIHTx7LxJip+z/+kVAskuuP786YAuXnNs=; b=l5+Nkqss/4CfOTpE5M1nW10lL7Xn+gWTezVomxo0vpCyhdbW92uEMDHSAnc8GWex8n ScRdgeen7p/cSq2HGG1RGGYTjsJki7faa+g7qg2VKgKzxW7y4Ygpc/ruUEAVKLk340LQ nxV8zZFw6VlkOUeqSvFgk9K27j0HLDHuqQuei/dkCz+toLLRjZvrnDItKjHTAA73gRfo XPfrmGmLVwsCpjMH7nMA1wRuPQCCJ3icXGzNsSaz8GBLO1rL1rFORIHis3yFz1LRk7V9 VwIuGv3z7gCBfjQChXKBP9P3OFdTDEI82jKdKvnO2Ahkp20PY5KuAw/ccY6Qv4a1yC7g Ch2g== X-Gm-Message-State: AOJu0YwQc23x2ioacDVkcztYhcio9Z0p0M5LBk6n0hLn164wqZMMprj6 xwK5xyTMaRu+uCoi8luIXtbSUF4HHU0f+xAFie3j4VQMXboCZbiOm4wXMnr5Gt8e2tG43T/xrsY Z X-Google-Smtp-Source: AGHT+IFiAvQXSt/3E9HAVd0jKxOdpcbBA/SkSbNcXmdFPm6vLLNn51dTjzZED898rY5nUOD5MGzOlQ== X-Received: by 2002:adf:f089:0:b0:368:7a18:908c with SMTP id ffacd0b85a97d-36d612eaf2bmr1972586f8f.51.1723226919249; Fri, 09 Aug 2024 11:08:39 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.38 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:38 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 03/11] docs/specs/rocker.txt: Convert to rST Date: Fri, 9 Aug 2024 19:08:27 +0100 Message-Id: <20240809180835.1243269-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42a; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42a.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Convert the rocker.txt specification document to rST format. We make extensive use of the :: marker to introduce a literal block for all the tables and ASCII art, rather than trying to convert the tables to rST table syntax. This produces a valid rST document without needing a huge diff. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Message-id: 20240801170131.3977807-2-peter.maydell@linaro.org --- MAINTAINERS | 2 +- docs/specs/index.rst | 1 + docs/specs/{rocker.txt => rocker.rst} | 181 +++++++++++++------------- 3 files changed, 93 insertions(+), 91 deletions(-) rename docs/specs/{rocker.txt => rocker.rst} (91%) diff --git a/MAINTAINERS b/MAINTAINERS index 10af2126329..36becfaf494 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2465,7 +2465,7 @@ S: Maintained F: hw/net/rocker/ F: qapi/rocker.json F: tests/rocker/ -F: docs/specs/rocker.txt +F: docs/specs/rocker.rst e1000x M: Dmitry Fleytman diff --git a/docs/specs/index.rst b/docs/specs/index.rst index be899b49c28..6495ed5ed9e 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -35,3 +35,4 @@ guest hardware that is specific to QEMU. vmcoreinfo vmgenid rapl-msr + rocker diff --git a/docs/specs/rocker.txt b/docs/specs/rocker.rst similarity index 91% rename from docs/specs/rocker.txt rename to docs/specs/rocker.rst index 1857b317030..3a7fc6a7e0e 100644 --- a/docs/specs/rocker.txt +++ b/docs/specs/rocker.rst @@ -1,23 +1,23 @@ Rocker Network Switch Register Programming Guide -Copyright (c) Scott Feldman -Copyright (c) Neil Horman -Version 0.11, 12/29/2014 +************************************************ -LICENSE -======= +.. + Copyright (c) Scott Feldman + Copyright (c) Neil Horman + Version 0.11, 12/29/2014 -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. -SECTION 1: Introduction -======================= +Introduction +============ Overview -------- @@ -29,25 +29,25 @@ software. Notations and Conventions ------------------------- -o In register descriptions, [n:m] indicates a range from bit n to bit m, -inclusive. -o Use of leading 0x indicates a hexadecimal number. -o Use of leading 0b indicates a binary number. -o The use of RSVD or Reserved indicates that a bit or field is reserved for -future use. -o Field width is in bytes, unless otherwise noted. -o Register are (R) read-only, (R/W) read/write, (W) write-only, or (COR) clear -on read -o TLV values in network-byte-order are designated with (N). +* In register descriptions, [n:m] indicates a range from bit n to bit m, + inclusive. +* Use of leading 0x indicates a hexadecimal number. +* Use of leading 0b indicates a binary number. +* The use of RSVD or Reserved indicates that a bit or field is reserved for + future use. +* Field width is in bytes, unless otherwise noted. +* Register are (R) read-only, (R/W) read/write, (W) write-only, or (COR) clear + on read +* TLV values in network-byte-order are designated with (N). -SECTION 2: PCI Configuration Registers -====================================== +PCI Configuration Registers +=========================== PCI Configuration Space ----------------------- -Each switch instance registers as a PCI device with PCI configuration space: +Each switch instance registers as a PCI device with PCI configuration space:: offset width description value --------------------------------------------- @@ -74,11 +74,10 @@ Each switch instance registers as a PCI device with PCI configuration space: 0x41 1 Retry count 0x42 2 Reserved + * Assigned by sub-system implementation -* Assigned by sub-system implementation - -SECTION 3: Memory-Mapped Register Space -======================================= +Memory-Mapped Register Space +============================ There are two memory-mapped BARs. BAR0 maps device register space and is 0x2000 in size. BAR1 maps MSI-X vector and PBA tables and is also 0x2000 in @@ -89,7 +88,7 @@ byte registers with one 4-byte access, and 8 byte registers with either two 4-byte accesses or a single 8-byte access. In the case of two 4-byte accesses, access must be lower and then upper 4-bytes, in that order. -BAR0 device register space is organized as follows: +BAR0 device register space is organized as follows:: offset description ------------------------------------------------------ @@ -105,7 +104,7 @@ Reads to reserved registers read back as 0. No fancy stuff like write-combining is enabled on any of the registers. -BAR1 MSI-X register space is organized as follows: +BAR1 MSI-X register space is organized as follows:: offset description ------------------------------------------------------ @@ -113,8 +112,8 @@ BAR1 MSI-X register space is organized as follows: 0x1000-0x1fff MSI-X PBA table -SECTION 4: Interrupts, DMA, and Endianness -========================================== +Interrupts, DMA, and Endianness +=============================== PCI Interrupts -------------- @@ -122,7 +121,7 @@ PCI Interrupts The device supports only MSI-X interrupts. BAR1 memory-mapped region contains the MSI-X vector and PBA tables, with support for up to 256 MSI-X vectors. -The vector assignment is: +The vector assignment is:: vector description ----------------------------------------------------- @@ -134,7 +133,7 @@ The vector assignment is: Tx vector is even Rx vector is odd -A MSI-X vector table entry is 16 bytes: +A MSI-X vector table entry is 16 bytes:: field offset width description ------------------------------------------------------------- @@ -170,7 +169,7 @@ ring, and hardware will set this bit when the descriptor is complete. Descriptor ring sizes must be a power of 2 and range from 2 to 64K entries. Descriptor rings' base address must be 8-byte aligned. Descriptors must be packed within ring. Each descriptor in each ring must also be aligned on an 8 -byte boundary. Each descriptor ring will have these registers: +byte boundary. Each descriptor ring will have these registers:: DMA_DESC_xxx_BASE_ADDR, offset 0x1000 + (x * 32), 64-bit, (R/W) DMA_DESC_xxx_SIZE, offset 0x1008 + (x * 32), 32-bit, (R/W) @@ -180,7 +179,7 @@ byte boundary. Each descriptor ring will have these registers: DMA_DESC_xxx_CREDITS, offset 0x1018 + (x * 32), 32-bit, (R/W) DMA_DESC_xxx_RSVD1, offset 0x101c + (x * 32), 32-bit, (R/W) -Where x is descriptor ring index: +Where x is descriptor ring index:: index ring -------------------- @@ -203,14 +202,14 @@ written past TAIL. To do so would wrap the ring. An empty ring is when HEAD == TAIL. A full ring is when HEAD is one position behind TAIL. Both HEAD and TAIL increment and modulo wrap at the ring size. -CTRL register bits: +CTRL register bits:: bit name description ------------------------------------------------------------------------ [0] CTRL_RESET Reset the descriptor ring [1:31] Reserved -All descriptor types share some common fields: +All descriptor types share some common fields:: field width description ------------------------------------------------------------------- @@ -234,7 +233,7 @@ filled in by the switch. Likewise, the switch will ignore unknown fields filled in by software. Descriptor payload buffer is 8-byte aligned and TLVs are 8-byte aligned. The -value within a TLV is also 8-byte aligned. The (packed, 8 byte) TLV header is: +value within a TLV is also 8-byte aligned. The (packed, 8 byte) TLV header is:: field width description ----------------------------- @@ -246,7 +245,7 @@ The alignment requirements for descriptors and TLVs are to avoid unaligned access exceptions in software. Note that the payload for each TLV is also 8 byte aligned. -Figure 1 shows an example descriptor buffer with two TLVs. +Figure 1 shows an example descriptor buffer with two TLVs:: <------- 8 bytes -------> @@ -316,11 +315,11 @@ network packet data. All non-network-packet TLV multi-byte values will be LE. TLV values in network-byte-order are designated with (N). -SECTION 5: Test Registers -========================= +Test Registers +============== Rocker has several test registers to support troubleshooting register access, -interrupt generation, and DMA operations: +interrupt generation, and DMA operations:: TEST_REG, offset 0x0010, 32-bit (R/W) TEST_REG64, offset 0x0018, 64-bit (R/W) @@ -338,7 +337,7 @@ for that vector. To test basic DMA operations, allocate a DMA-able host buffer and put the buffer address into TEST_DMA_ADDR and size into TEST_DMA_SIZE. Then, write to -TEST_DMA_CTRL to manipulate the buffer contents. TEST_DMA_CTRL operations are: +TEST_DMA_CTRL to manipulate the buffer contents. TEST_DMA_CTRL operations are:: operation value description ----------------------------------------------------------- @@ -351,14 +350,14 @@ issue exists. In particular, buffers that start on odd-8-byte boundary and/or span multiple PAGE sizes should be tested. -SECTION 6: Ports -================ +Ports +===== Physical and Logical Ports ------------------------------------ The switch supports up to 62 physical (front-panel) ports. Register -PORT_PHYS_COUNT returns the actual number of physical ports available: +PORT_PHYS_COUNT returns the actual number of physical ports available:: PORT_PHYS_COUNT, offset 0x0304, 32-bit, (R) @@ -369,7 +368,7 @@ Front-panel ports and logical tunnel ports are mapped into a single 32-bit port space. A special CPU port is assigned port 0. The front-panel ports are mapped to ports 1-62. A special loopback port is assigned port 63. Logical tunnel ports are assigned ports 0x0001000-0x0001ffff. -To summarize the port assignments: +To summarize the port assignments:: port mapping ------------------------------------------------------- @@ -391,14 +390,14 @@ set/get the mode for front-panel ports, see port settings, below. Port Settings ------------- -Link status for all front-panel ports is available via PORT_PHYS_LINK_STATUS: +Link status for all front-panel ports is available via PORT_PHYS_LINK_STATUS:: PORT_PHYS_LINK_STATUS, offset 0x0310, 64-bit, (R) Value is port bitmap. Bits 0 and 63 always read 0. Bits 1-62 read 1 for link UP and 0 for link DOWN for respective front-panel ports. -Other properties for front-panel ports are available via DMA CMD descriptors: +Other properties for front-panel ports are available via DMA CMD descriptors:: Get PORT_SETTINGS descriptor: @@ -438,7 +437,7 @@ Port Enable ----------- Front-panel ports are initially disabled, which means port ingress and egress -packets will be dropped. To enable or disable a port, use PORT_PHYS_ENABLE: +packets will be dropped. To enable or disable a port, use PORT_PHYS_ENABLE:: PORT_PHYS_ENABLE: offset 0x0318, 64-bit, (R/W) @@ -447,15 +446,15 @@ packets will be dropped. To enable or disable a port, use PORT_PHYS_ENABLE: Default is 0. -SECTION 7: Switch Control -========================= +Switch Control +============== This section covers switch-wide register settings. Control ------- -This register is used for low level control of the switch. +This register is used for low level control of the switch:: CONTROL: offset 0x0300, 32-bit, (W) @@ -468,18 +467,18 @@ Switch ID --------- The switch has a SWITCH_ID to be used by software to uniquely identify the -switch: +switch:: SWITCH_ID: offset 0x0320, 64-bit, (R) Value is opaque to switch software and no special encoding is implied. -SECTION 8: Events -================= +Events +====== Non-I/O asynchronous events from the device are notified to the host using the -event ring. The TLV structure for events is: +event ring. The TLV structure for events is:: field width description --------------------------------------------------- @@ -491,7 +490,7 @@ event ring. The TLV structure for events is: Link Changed Event ------------------ -When link status changes on a physical port, this event is generated. +When link status changes on a physical port, this event is generated:: field width description --------------------------------------------------- @@ -510,6 +509,8 @@ driver should install to the device the MAC/VLAN on the port into the bridge table. Once installed, the MAC/VLAN is known on the port and this event will no longer be generated. +:: + field width description --------------------------------------------------- INFO @@ -518,8 +519,8 @@ no longer be generated. VLAN 2 VLAN ID -SECTION 9: CPU Packet Processing -================================ +CPU Packet Processing +===================== Ingress packets directed to the host CPU for further processing are delivered in the DMA RX ring. Likewise, host CPU originating packets destined to egress @@ -540,7 +541,7 @@ software that Tx is complete and software resources (e.g. skb) backing packet can be released. Figure 2 shows an example 3-fragment packet queued with one Tx descriptor. A -TLV is used for each packet fragment. +TLV is used for each packet fragment:: pkt frag 1 +–––––––+ +–+ @@ -570,7 +571,7 @@ TLV is used for each packet fragment. fig 2. -The TLVs for Tx descriptor buffer are: +The TLVs for Tx descriptor buffer are:: field width description --------------------------------------------------------------------- @@ -600,7 +601,7 @@ The TLVs for Tx descriptor buffer are: TX_FRAG_ADDR 8 DMA address of packet fragment TX_FRAG_LEN 2 Packet fragment length -Possible status return codes in descriptor on completion are: +Possible status return codes in descriptor on completion are:: DESC_COMP_ERR reason -------------------------------------------------------------------- @@ -623,7 +624,7 @@ worst-case packet size. A single Rx descriptor will contain the entire Rx packet data in one RX_FRAG. Other Rx TLVs describe and hardware offloads performed on the packet, such as checksum validation. -The TLVs for Rx descriptor buffer are: +The TLVs for Rx descriptor buffer are:: field width description --------------------------------------------------- @@ -649,7 +650,7 @@ The TLVs for Rx descriptor buffer are: Offload forward RX_FLAG indicates the device has already forwarded the packet so the host CPU should not also forward the packet. -Possible status return codes in descriptor on completion are: +Possible status return codes in descriptor on completion are:: DESC_COMP_ERR reason -------------------------------------------------------------------- @@ -660,14 +661,14 @@ Possible status return codes in descriptor on completion are: packet data TLV and other TLVs. -SECTION 10: OF-DPA Mode -====================== +OF-DPA Mode +=========== OF-DPA mode allows the switch to offload flow packet processing functions to hardware. An OpenFlow controller would communicate with an OpenFlow agent installed on the switch. The OpenFlow agent would (directly or indirectly) communicate with the Rocker switch driver, which in turn would program switch -hardware with flow functionality, as defined in OF-DPA. The block diagram is: +hardware with flow functionality, as defined in OF-DPA. The block diagram is:: +–––––––––––––––----–––+ | OF | @@ -696,14 +697,14 @@ OF-DPA Flow Table Interface There are commands to add, modify, delete, and get stats of flow table entries. The commands are issued using the DMA CMD descriptor ring. The following -commands are defined: +commands are defined:: CMD_ADD: add an entry to flow table CMD_MOD: modify an entry in flow table CMD_DEL: delete an entry from flow table CMD_GET_STATS: get stats for flow entry -TLVs for add and modify commands are: +TLVs for add and modify commands are:: field width description ---------------------------------------------------- @@ -723,14 +724,14 @@ TLVs for add and modify commands are: Additional TLVs based on flow table ID: -Table ID 0: ingress port +Table ID 0: ingress port:: field width description ---------------------------------------------------- OF_DPA_IN_PPORT 4 ingress physical port number OF_DPA_GOTO_TBL 2 goto table ID; zero to drop -Table ID 10: vlan +Table ID 10: vlan:: field width description ---------------------------------------------------- @@ -740,7 +741,7 @@ Table ID 10: vlan OF_DPA_GOTO_TBL 2 goto table ID; zero to drop OF_DPA_NEW_VLAN_ID 2 (N) new vlan ID -Table ID 20: termination mac +Table ID 20: termination mac:: field width description ---------------------------------------------------- @@ -757,7 +758,7 @@ Table ID 20: termination mac OF_DPA_OUT_PPORT 2 if specified, must be controller, set zero otherwise -Table ID 30: unicast routing +Table ID 30: unicast routing:: field width description ---------------------------------------------------- @@ -772,7 +773,7 @@ Table ID 30: unicast routing OF_DPA_GROUP_ID 4 data for GROUP action must be an L3 Unicast group entry -Table ID 40: multicast routing +Table ID 40: multicast routing:: field width description ---------------------------------------------------- @@ -797,7 +798,7 @@ Table ID 40: multicast routing OF_DPA_GROUP_ID 4 data for GROUP action must be an L3 multicast group entry -Table ID 50: bridging +Table ID 50: bridging:: field width description ---------------------------------------------------- @@ -818,7 +819,7 @@ Table ID 50: bridging restricted to CONTROLLER, set to 0 otherwise -Table ID 60: acl policy +Table ID 60: acl policy:: field width description ---------------------------------------------------- @@ -890,7 +891,7 @@ Table ID 60: acl policy dropped (all other instructions ignored) -TLVs for flow delete and get stats command are: +TLVs for flow delete and get stats command are:: field width description --------------------------------------------------- @@ -898,7 +899,7 @@ TLVs for flow delete and get stats command are: OF_DPA_COOKIE 8 Cookie On completion of get stats command, the descriptor buffer is written back with -the following TLVs: +the following TLVs:: field width description --------------------------------------------------- @@ -906,7 +907,7 @@ the following TLVs: OF_DPA_STAT_RX_PKTS 8 Received packets OF_DPA_STAT_TX_PKTS 8 Transmit packets -Possible status return codes in descriptor on completion are: +Possible status return codes in descriptor on completion are:: DESC_COMP_ERR command reason -------------------------------------------------------------------- @@ -928,14 +929,14 @@ Group Table Interface There are commands to add, modify, delete, and get stats of group table entries. The commands are issued using the DMA CMD descriptor ring. The -following commands are defined: +following commands are defined:: CMD_ADD: add an entry to group table CMD_MOD: modify an entry in group table CMD_DEL: delete an entry from group table CMD_GET_STATS: get stats for group entry -TLVs for add and modify commands are: +TLVs for add and modify commands are:: field width description ----------------------------------------------------------- @@ -969,7 +970,7 @@ TLVs for add and modify commands are: FLOW_SRC_MAC 6 (types 1, 2, 5) FLOW_DST_MAC 6 (types 1, 2) -TLVs for flow delete and get stats command are: +TLVs for flow delete and get stats command are:: field width description ----------------------------------------------------------- @@ -977,7 +978,7 @@ TLVs for flow delete and get stats command are: FLOW_GROUP_ID 2 Flow group ID On completion of get stats command, the descriptor buffer is written back with -the following TLVs: +the following TLVs:: field width description --------------------------------------------------- @@ -986,7 +987,7 @@ the following TLVs: FLOW_STAT_REF_COUNT 4 Flow reference count FLOW_STAT_BUCKET_COUNT 4 Flow bucket count -Possible status return codes in descriptor on completion are: +Possible status return codes in descriptor on completion are:: DESC_COMP_ERR command reason -------------------------------------------------------------------- From patchwork Fri Aug 9 18:08:28 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759075 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 2E508C3DA4A for ; Fri, 9 Aug 2024 18:09:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2n-0001bI-Ia; Fri, 09 Aug 2024 14:08:53 -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 1scU2l-0001VC-Qu for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:51 -0400 Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2j-0007DA-LF for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:51 -0400 Received: by mail-wr1-x430.google.com with SMTP id ffacd0b85a97d-3686b285969so1234316f8f.0 for ; Fri, 09 Aug 2024 11:08:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226928; x=1723831728; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=gFqkGsXiARvhRWrK655SyRQtokwmjKh8RhYlups7b4I=; b=X3XE8ibb1nm6u79yIzCWb43LSFhfKeP9MgCCEBqfyvg1DwyyAmI9WZtuH9G/StUOA5 l1heXPNZMyFBrMWA4OY2Md06s9mxrc621bSDJ57o4FxTiTAoCSiLNeZYD4nGeyxjENZ/ D7tjdV3VEkIhIL1TvqszTPLyb+jCCowIhoSxBfKme2VfRxhGnQ1uyXIprOoIyt+AueH4 sfuYglVdxhRo1H5MrveZQkTc/UwlyV7L3XEg3F06sRfwP2udUYjzMlejiaKuwPpeTbod 70poMrgUpwy7XZYLBUrCJYnZmdbe6UpHoB7iw+ToA1TImiycbzR5NbdXS3PqfVimXWPD ICEg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226928; x=1723831728; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=gFqkGsXiARvhRWrK655SyRQtokwmjKh8RhYlups7b4I=; b=KZ1iYOLuRyzFVep69Y5Ko2LKd9so11a4n/fu4tc/V3xK2NX1yW14DayMG1kej2qxLA Ze4T62Xr6305EOARgxr4yp1ro+Zlu8VCF2leJzc0/Oa63wqu0H6NJF41+X1KloULURAA LAQIV3kWA3jSZ9WkP0mLYnFjJDm0X3lTIpwmx3uE+IO/I3QEBzvCpE7LeZQ8F9kExw3P oYgH+0uWCC1C06VKvMVkd4Rp4V+gmci/U4Mk+qFR4W+0Q/eWje5UyysFYDdGucae9Unz uClIAV1cen083EQNc/Yf6L1h0lnvX704gVQHs4nh1q9qvTk2G9mTB4KAVonRe0xwm44O UMLw== X-Gm-Message-State: AOJu0Yz0S0mu2TlG5oeivqTI2RDzIrI6oROSIn0jm8Sse1BQkr58GFw/ HPhXlZoKl0uiLZCrZbEH6QAJJUdbNAQzd1i38gPZn0KkV29KhSKEWWx5i7E6I6edezHx2g6nH0z 4 X-Google-Smtp-Source: AGHT+IFai4o1/ULVGtUSkwzaUA9x4LINU18MSTjVBIah+eVDHJjOaCPV9uANJ01jAqEJuP66k3SecQ== X-Received: by 2002:adf:fa08:0:b0:367:98e6:2a15 with SMTP id ffacd0b85a97d-36d60353f60mr2121669f8f.53.1723226928001; Fri, 09 Aug 2024 11:08:48 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.39 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:39 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 04/11] docs/interop/nbd.txt: Convert to rST Date: Fri, 9 Aug 2024 19:08:28 +0100 Message-Id: <20240809180835.1243269-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::430; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x430.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Convert nbd.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Reviewed-by: Eric Blake Message-id: 20240801170131.3977807-3-peter.maydell@linaro.org --- MAINTAINERS | 2 +- docs/interop/index.rst | 1 + docs/interop/nbd.rst | 89 ++++++++++++++++++++++++++++++++++++++++++ docs/interop/nbd.txt | 72 ---------------------------------- 4 files changed, 91 insertions(+), 73 deletions(-) create mode 100644 docs/interop/nbd.rst delete mode 100644 docs/interop/nbd.txt diff --git a/MAINTAINERS b/MAINTAINERS index 36becfaf494..04a1fd08503 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3871,7 +3871,7 @@ F: nbd/ F: include/block/nbd* F: qemu-nbd.* F: blockdev-nbd.c -F: docs/interop/nbd.txt +F: docs/interop/nbd.rst F: docs/tools/qemu-nbd.rst F: tests/qemu-iotests/tests/*nbd* T: git https://repo.or.cz/qemu/ericb.git nbd diff --git a/docs/interop/index.rst b/docs/interop/index.rst index ed65395bfb2..b9ceaabc648 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -14,6 +14,7 @@ are useful for making QEMU interoperate with other software. dbus-vmstate dbus-display live-block-operations + nbd pr-helper qmp-spec qemu-ga diff --git a/docs/interop/nbd.rst b/docs/interop/nbd.rst new file mode 100644 index 00000000000..de079d31fd8 --- /dev/null +++ b/docs/interop/nbd.rst @@ -0,0 +1,89 @@ +QEMU NBD protocol support +========================= + +QEMU supports the NBD protocol, and has an internal NBD client (see +``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an +external NBD server tool (see ``qemu-nbd.c``). The common code is placed +in ``nbd/*``. + +The NBD protocol is specified here: +https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md + +The following paragraphs describe some specific properties of NBD +protocol realization in QEMU. + +Metadata namespaces +------------------- + +QEMU supports the ``base:allocation`` metadata context as defined in the +NBD protocol specification, and also defines an additional metadata +namespace ``qemu``. + +``qemu`` namespace +------------------ + +The ``qemu`` namespace currently contains two available metadata context +types. The first is related to exposing the contents of a dirty +bitmap alongside the associated disk contents. That metadata context +is named with the following form:: + + qemu:dirty-bitmap: + +Each dirty-bitmap metadata context defines only one flag for extents +in reply for ``NBD_CMD_BLOCK_STATUS``: + +bit 0: + ``NBD_STATE_DIRTY``, set when the extent is "dirty" + +The second is related to exposing the source of various extents within +the image, with a single metadata context named:: + + qemu:allocation-depth + +In the allocation depth context, the entire 32-bit value represents a +depth of which layer in a thin-provisioned backing chain provided the +data (0 for unallocated, 1 for the active layer, 2 for the first +backing layer, and so forth). + +For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported +in addition to the specific ``qemu:allocation-depth`` and +``qemu:dirty-bitmap:``: + +``qemu:`` + returns list of all available metadata contexts in the namespace +``qemu:dirty-bitmap:`` + returns list of all available dirty-bitmap metadata contexts + +Features by version +------------------- + +The following list documents which qemu version first implemented +various features (both as a server exposing the feature, and as a +client taking advantage of the feature when present), to make it +easier to plan for cross-version interoperability. Note that in +several cases, the initial release containing a feature may require +additional patches from the corresponding stable branch to fix bugs in +the operation of that feature. + +2.6 + ``NBD_OPT_STARTTLS`` with TLS X.509 Certificates +2.8 + ``NBD_CMD_WRITE_ZEROES`` +2.10 + ``NBD_OPT_GO``, ``NBD_INFO_BLOCK`` +2.11 + ``NBD_OPT_STRUCTURED_REPLY`` +2.12 + ``NBD_CMD_BLOCK_STATUS`` for ``base:allocation`` +3.0 + ``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK), + ``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE`` +4.2 + ``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports, + ``NBD_CMD_FLAG_FAST_ZERO`` +5.2 + ``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth`` +7.1 + ``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports +8.2 + ``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD`` diff --git a/docs/interop/nbd.txt b/docs/interop/nbd.txt deleted file mode 100644 index 18efb251de9..00000000000 --- a/docs/interop/nbd.txt +++ /dev/null @@ -1,72 +0,0 @@ -QEMU supports the NBD protocol, and has an internal NBD client (see -block/nbd.c), an internal NBD server (see blockdev-nbd.c), and an -external NBD server tool (see qemu-nbd.c). The common code is placed -in nbd/*. - -The NBD protocol is specified here: -https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md - -The following paragraphs describe some specific properties of NBD -protocol realization in QEMU. - -= Metadata namespaces = - -QEMU supports the "base:allocation" metadata context as defined in the -NBD protocol specification, and also defines an additional metadata -namespace "qemu". - -== "qemu" namespace == - -The "qemu" namespace currently contains two available metadata context -types. The first is related to exposing the contents of a dirty -bitmap alongside the associated disk contents. That metadata context -is named with the following form: - - qemu:dirty-bitmap: - -Each dirty-bitmap metadata context defines only one flag for extents -in reply for NBD_CMD_BLOCK_STATUS: - - bit 0: NBD_STATE_DIRTY, set when the extent is "dirty" - -The second is related to exposing the source of various extents within -the image, with a single metadata context named: - - qemu:allocation-depth - -In the allocation depth context, the entire 32-bit value represents a -depth of which layer in a thin-provisioned backing chain provided the -data (0 for unallocated, 1 for the active layer, 2 for the first -backing layer, and so forth). - -For NBD_OPT_LIST_META_CONTEXT the following queries are supported -in addition to the specific "qemu:allocation-depth" and -"qemu:dirty-bitmap:": - -* "qemu:" - returns list of all available metadata contexts in the - namespace. -* "qemu:dirty-bitmap:" - returns list of all available dirty-bitmap - metadata contexts. - -= Features by version = - -The following list documents which qemu version first implemented -various features (both as a server exposing the feature, and as a -client taking advantage of the feature when present), to make it -easier to plan for cross-version interoperability. Note that in -several cases, the initial release containing a feature may require -additional patches from the corresponding stable branch to fix bugs in -the operation of that feature. - -* 2.6: NBD_OPT_STARTTLS with TLS X.509 Certificates -* 2.8: NBD_CMD_WRITE_ZEROES -* 2.10: NBD_OPT_GO, NBD_INFO_BLOCK -* 2.11: NBD_OPT_STRUCTURED_REPLY -* 2.12: NBD_CMD_BLOCK_STATUS for "base:allocation" -* 3.0: NBD_OPT_STARTTLS with TLS Pre-Shared Keys (PSK), -NBD_CMD_BLOCK_STATUS for "qemu:dirty-bitmap:", NBD_CMD_CACHE -* 4.2: NBD_FLAG_CAN_MULTI_CONN for shareable read-only exports, -NBD_CMD_FLAG_FAST_ZERO -* 5.2: NBD_CMD_BLOCK_STATUS for "qemu:allocation-depth" -* 7.1: NBD_FLAG_CAN_MULTI_CONN for shareable writable exports -* 8.2: NBD_OPT_EXTENDED_HEADERS, NBD_FLAG_BLOCK_STATUS_PAYLOAD From patchwork Fri Aug 9 18:08:29 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759080 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 C1C84C531DD for ; Fri, 9 Aug 2024 18:10:11 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2o-0001dH-4q; Fri, 09 Aug 2024 14:08: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 1scU2m-0001Y3-HW for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:52 -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 1scU2k-0007DC-Aa for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:08:52 -0400 Received: by mail-wr1-x429.google.com with SMTP id ffacd0b85a97d-367940c57ddso1296820f8f.3 for ; Fri, 09 Aug 2024 11:08:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226929; x=1723831729; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=agG5AiF1eAhZlwXMsZvTErllzGZ75Y15g9KkwWX0cZI=; b=K93YX/9noKVt/to1LE+MCGGsgfcInbSprDYIf7qSkEXAZcMvdiaAkm17qslVdsuNja UiVQOuky5P+1LAlL8tLY9zdcBOpSnxnqf4gL+6703QdXOez44A7Dxc7qvy/ouDQhRiLh cSocJLalqTwCLUtwcKql1YiV7vFck2B+Gr4aWWc3oYLIUed5+zn3+oPJb21jLQ62cgnl b1AdTl697X+hEOT+NMqQyIHdy2EbXc0FMLm+BKlg2NZicNWfVNKJbUPT4K5jc8GiEqCd Hx/S3ViX3ZhbCiO/bzTzw5iuHQT7hRG6tFHTCtrNv4D/OsHpg8QDPGkHi8iQqFsgWZBk OyOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226929; x=1723831729; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=agG5AiF1eAhZlwXMsZvTErllzGZ75Y15g9KkwWX0cZI=; b=N+MrpGl49QTNuthD3LU1/5rWNSIWyOZvYYJ44nMb6nxZ+Cc4BFHnr9bvSNn1QT/NSZ /MYhoSHJF8tx9o+8Xyb2kYHjte3zvn7yr/Se+WJk0zV5FKwbfb2bmCQfz+XIDUYptHWt 60nitpLEK4UnqV8RQIlFJWImxcf8Hl0XEOGAloeTBUAoqrOPwYs+bLfx2Rza1i9++1nk m7buwvgSkZsi6wvevK8GC5/j1PeMaz2s+nZ9TR5hkUhvuGHcz1VdF9gyKUUe3tnJOFs8 4XQgSfsMatHdSX40ckQFh5svZC5f86/m34lMkVywuHX8iG7Q/ILkfYuEFTM/1y3xhdLY HLhA== X-Gm-Message-State: AOJu0YzHXJ+JPbwHO9XxZa2SZvCHts44dEk/oxYodtByQ0hFERI/Xjqt R8otbshvHqZfREQYAH0c7JZnzaDdqQfsXMLlTICZRSZ24HaPmYSq9tGcnDN4ggEPXHpTYnaiK1F d X-Google-Smtp-Source: AGHT+IFj8NX652LCVHS/Sr3a4C5UGz4yBLHzOqUx9KNUw7b6DgdZg3rccmcbHhl3bDMEUwWB4j+Viw== X-Received: by 2002:a5d:5488:0:b0:367:9903:a79 with SMTP id ffacd0b85a97d-36d5fd7fb14mr1413557f8f.48.1723226928625; Fri, 09 Aug 2024 11:08:48 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.48 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:48 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 05/11] docs/interop/parallels.txt: Convert to rST Date: Fri, 9 Aug 2024 19:08:29 +0100 Message-Id: <20240809180835.1243269-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=peter.maydell@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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Convert parallels.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Reviewed-by: Eric Blake Message-id: 20240801170131.3977807-4-peter.maydell@linaro.org --- MAINTAINERS | 2 +- docs/interop/index.rst | 1 + docs/interop/{parallels.txt => parallels.rst} | 108 ++++++++++-------- 3 files changed, 60 insertions(+), 51 deletions(-) rename docs/interop/{parallels.txt => parallels.rst} (72%) diff --git a/MAINTAINERS b/MAINTAINERS index 04a1fd08503..ae8bed8c757 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3964,7 +3964,7 @@ L: qemu-block@nongnu.org S: Supported F: block/parallels.c F: block/parallels-ext.c -F: docs/interop/parallels.txt +F: docs/interop/parallels.rst T: git https://src.openvz.org/scm/~den/qemu.git parallels qed diff --git a/docs/interop/index.rst b/docs/interop/index.rst index b9ceaabc648..70bba62d907 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -15,6 +15,7 @@ are useful for making QEMU interoperate with other software. dbus-display live-block-operations nbd + parallels pr-helper qmp-spec qemu-ga diff --git a/docs/interop/parallels.txt b/docs/interop/parallels.rst similarity index 72% rename from docs/interop/parallels.txt rename to docs/interop/parallels.rst index bb3fadf3692..7b328a40c80 100644 --- a/docs/interop/parallels.txt +++ b/docs/interop/parallels.rst @@ -1,41 +1,46 @@ -= License = +Parallels Expandable Image File Format +====================================== -Copyright (c) 2015 Denis Lunev -Copyright (c) 2015 Vladimir Sementsov-Ogievskiy +.. + Copyright (c) 2015 Denis Lunev + Copyright (c) 2015 Vladimir Sementsov-Ogievskiy -This work is licensed under the terms of the GNU GPL, version 2 or later. -See the COPYING file in the top-level directory. + This work is licensed under the terms of the GNU GPL, version 2 or later. + See the COPYING file in the top-level directory. -= Parallels Expandable Image File Format = A Parallels expandable image file consists of three consecutive parts: - * header - * BAT - * data area + +* header +* BAT +* data area All numbers in a Parallels expandable image are stored in little-endian byte order. -== Definitions == +Definitions +----------- - Sector A 512-byte data chunk. +Sector + A 512-byte data chunk. - Cluster A data chunk of the size specified in the image header. - Currently, the default size is 1MiB (2048 sectors). In previous - versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were - used. +Cluster + A data chunk of the size specified in the image header. + Currently, the default size is 1MiB (2048 sectors). In previous + versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were used. - BAT Block Allocation Table, an entity that contains information for - guest-to-host I/O data address translation. +BAT + Block Allocation Table, an entity that contains information for + guest-to-host I/O data address translation. - -== Header == +Header +------ The header is placed at the start of an image and contains the following -fields: +fields:: -Bytes: + Bytes: 0 - 15: magic Must contain "WithoutFreeSpace" or "WithouFreSpacExt". @@ -103,44 +108,46 @@ Bytes: ext_off must meet the same requirements as cluster offsets defined by BAT entries (see below). - -== BAT == +BAT +--- BAT is placed immediately after the image header. In the file, BAT is a contiguous array of 32-bit unsigned little-endian integers with -(bat_entries * 4) bytes size. +``(bat_entries * 4)`` bytes size. Each BAT entry contains an offset from the start of the file to the -corresponding cluster. The offset set in clusters for "WithouFreSpacExt" images -and in sectors for "WithoutFreeSpace" images. +corresponding cluster. The offset set in clusters for ``WithouFreSpacExt`` +images and in sectors for ``WithoutFreeSpace`` images. If a BAT entry is zero, the corresponding cluster is not allocated and should be considered as filled with zeroes. Cluster offsets specified by BAT entries must meet the following requirements: - - the value must not be lower than data offset (provided by header.data_off - or calculated as specified above), - - the value must be lower than the desired file size, - - the value must be unique among all BAT entries, - - the result of (cluster offset - data offset) must be aligned to cluster - size. +- the value must not be lower than data offset (provided by ``header.data_off`` + or calculated as specified above) +- the value must be lower than the desired file size +- the value must be unique among all BAT entries +- the result of ``(cluster offset - data offset)`` must be aligned to + cluster size -== Data Area == +Data Area +--------- -The data area is an area from the data offset (provided by header.data_off or -calculated as specified above) to the end of the file. It represents a +The data area is an area from the data offset (provided by ``header.data_off`` +or calculated as specified above) to the end of the file. It represents a contiguous array of clusters. Most of them are allocated by the BAT, some may -be allocated by the ext_off field in the header while other may be allocated by -extensions. All clusters allocated by ext_off and extensions should meet the -same requirements as clusters specified by BAT entries. +be allocated by the ``ext_off`` field in the header while other may be +allocated by extensions. All clusters allocated by ``ext_off`` and extensions +should meet the same requirements as clusters specified by BAT entries. -== Format Extension == +Format Extension +---------------- The Format Extension is an area 1 cluster in size that provides additional format features. This cluster is addressed by the ext_off field in the header. -The format of the Format Extension area is the following: +The format of the Format Extension area is the following:: 0 - 7: magic Must be 0xAB234CEF23DCEA87 @@ -149,10 +156,10 @@ The format of the Format Extension area is the following: The MD5 checksum of the entire Header Extension cluster except the first 24 bytes. - The above are followed by feature sections or "extensions". The last - extension must be "End of features" (see below). +The above are followed by feature sections or "extensions". The last +extension must be "End of features" (see below). -Each feature section has the following format: +Each feature section has the following format:: 0 - 7: magic The identifier of the feature: @@ -183,16 +190,17 @@ Each feature section has the following format: variable: data (data_size bytes) - The above is followed by padding to the next 8 bytes boundary, then the - next extension starts. +The above is followed by padding to the next 8 bytes boundary, then the +next extension starts. - The last extension must be "End of features" with all the fields set to 0. +The last extension must be "End of features" with all the fields set to 0. -=== Dirty bitmaps feature === +Dirty bitmaps feature +--------------------- This feature provides a way of storing dirty bitmaps in the image. The fields -of its data area are: +of its data area are:: 0 - 7: size The bitmap size, should be equal to disk size in sectors. @@ -215,7 +223,7 @@ clusters inside the Parallels image file. The offsets of these clusters are saved in the L1 offset table specified by the feature extension. Each L1 table entry is a 64 bit integer as described below: -Given an offset in bytes into the bitmap data, corresponding L1 entry is +Given an offset in bytes into the bitmap data, corresponding L1 entry is:: l1_table[offset / cluster_size] @@ -227,6 +235,6 @@ are assumed to be 1. If an L1 table entry is not 0 or 1, it contains the corresponding cluster offset (in 512b sectors). Given an offset in bytes into the bitmap data the -offset in bytes into the image file can be obtained as follows: +offset in bytes into the image file can be obtained as follows:: offset = l1_table[offset / cluster_size] * 512 + (offset % cluster_size) From patchwork Fri Aug 9 18:08:30 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759076 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 04450C52D7F for ; Fri, 9 Aug 2024 18:09:50 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2w-0001yr-SI; Fri, 09 Aug 2024 14:09:02 -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 1scU2u-0001xk-OZ for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:00 -0400 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2s-0007Dl-5N for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:00 -0400 Received: by mail-wr1-x432.google.com with SMTP id ffacd0b85a97d-36868fcb919so1413301f8f.2 for ; Fri, 09 Aug 2024 11:08:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226937; x=1723831737; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=eVnCY3qbuf5yLSqsOtwFDfk5cUSu4Pud+DjVgvKddbU=; b=FmvDQkMtUFDbWqraL1xnvsbM5wxsXBJrCYeiMBFIc+asJ6vJahAL7nim3/4eHnhPnz n//cl1XXrIN5pUtnKhgs26e3+Q8lO9QLWqK4KLNliOia0qXowsb9wTVyL1i92+T+rOCR dlvlZcZPiH5ce6yVqIelh2Q030uxHLl/I3l2L9vrMhj6dkjRYiWgqgum/sPndEZp350B IjkRlXGKSbPNzEPmhGyqtQe5fgLcF4JsNUNtPyHsU5AIB6FHa3mlQVTtNF6cp+Qy1Tlu SfpNwLpuPGK9fCEYci1KtzOOsdzoa6/yYNuk5gd9c3EaYY1KCl4iSrPukmR4gGXFOhAH 0l5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226937; x=1723831737; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=eVnCY3qbuf5yLSqsOtwFDfk5cUSu4Pud+DjVgvKddbU=; b=D2y6U2YGd4BPsCfjGp93YJX6eEyLOQGyySrs2z3lQQAdJaqSCc7oPNm5Jixb14HwyS K5pBCbqA6xSOY0Mq0QWdFTUnTXABFSDFuRCRLpOQmNXLwwqNsiG4n/f+e03lv1wc+d3j zi3qCuWp5c7GRk9g178Anp0/6TS8PmOKUahKHUx6yCmh1ZbWxFV3gso89M+b9mBGDVSm Le2IXmXTciwSEdq1vMhFA9zJiIAfKCPUZ7vSmj4k9sS8gkdGJp3Twd0mRQrcsmveBfWu JYLuz6/gOstsBOz3ouJRdr/503mo8OmfK/b96nY7JSXNqlM6A6yfRjWfE7XMGxaNfvO/ n1vQ== X-Gm-Message-State: AOJu0Yz1tVSFFNSazhkuFMz4xjaWNfA9KtadKN3s0XsNqEeGLUbR1RqA RoxylsVG1Gc69jEBTdOyEalXRMftme5+hR3ZcEmb1xAkuUq/QFwK7owdsoI96vWlirdui0ImAEr L X-Google-Smtp-Source: AGHT+IHY9uBYR75FJdTa6r3S2Wa2eM5Pw7kV713Ce5j5Lf5iZvQcAipmX8W8chTs7twW7pQ9v7m5Yw== X-Received: by 2002:adf:ed52:0:b0:367:8e53:7fd7 with SMTP id ffacd0b85a97d-36d5fe78063mr1642524f8f.28.1723226936414; Fri, 09 Aug 2024 11:08:56 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.48 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:48 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 06/11] docs/interop/prl-xml.txt: Convert to rST Date: Fri, 9 Aug 2024 19:08:30 +0100 Message-Id: <20240809180835.1243269-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::432; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x432.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Convert prl-xml.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Reviewed-by: Eric Blake Message-id: 20240801170131.3977807-5-peter.maydell@linaro.org --- MAINTAINERS | 1 + docs/interop/index.rst | 1 + docs/interop/prl-xml.rst | 187 +++++++++++++++++++++++++++++++++++++++ docs/interop/prl-xml.txt | 158 --------------------------------- 4 files changed, 189 insertions(+), 158 deletions(-) create mode 100644 docs/interop/prl-xml.rst delete mode 100644 docs/interop/prl-xml.txt diff --git a/MAINTAINERS b/MAINTAINERS index ae8bed8c757..3584d6a6c6d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3965,6 +3965,7 @@ S: Supported F: block/parallels.c F: block/parallels-ext.c F: docs/interop/parallels.rst +F: docs/interop/prl-xml.rst T: git https://src.openvz.org/scm/~den/qemu.git parallels qed diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 70bba62d907..999e44eae19 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -16,6 +16,7 @@ are useful for making QEMU interoperate with other software. live-block-operations nbd parallels + prl-xml pr-helper qmp-spec qemu-ga diff --git a/docs/interop/prl-xml.rst b/docs/interop/prl-xml.rst new file mode 100644 index 00000000000..aacf11f4c44 --- /dev/null +++ b/docs/interop/prl-xml.rst @@ -0,0 +1,187 @@ +Parallels Disk Format +===================== + +.. + Copyright (c) 2015-2017, Virtuozzo, Inc. + Authors: + 2015 Denis Lunev + 2015 Vladimir Sementsov-Ogievskiy + 2016-2017 Klim Kireev + 2016-2017 Edgar Kaziakhmedov + + This work is licensed under the terms of the GNU GPL, version 2 or later. + See the COPYING file in the top-level directory. + +This specification contains minimal information about Parallels Disk Format, +which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server +and Parallels Desktop are able to add some unspecified nodes to xml and use +them, but they are for internal work and don't affect functionality. Also it +uses auxiliary xml ``Snapshot.xml``, which allows to store optional snapshot +information, but it doesn't influence open/read/write functionality. QEMU and +other software should not use fields not covered in this document and +``Snapshot.xml`` file and must leave them as is. + +Parallels disk consists of two parts: the set of snapshots and the disk +descriptor file, which stores information about all files and snapshots. + +Definitions +----------- + +Snapshot + a record of the contents captured at a particular time, capable + of storing current state. A snapshot has UUID and parent UUID. + +Snapshot image + an overlay representing the difference between this + snapshot and some earlier snapshot. + +Overlay + an image storing the different sectors between two captured states. + +Root image + snapshot image with no parent, the root of snapshot tree. + +Storage + the backing storage for a subset of the virtual disk. When + there is more than one storage in a Parallels disk then that + is referred to as a split image. In this case every storage + covers specific address space area of the disk and has its + particular root image. Split images are not considered here + and are not supported. Each storage consists of disk + parameters and a list of images. The list of images always + contains a root image and may also contain overlays. The + root image can be an expandable Parallels image file or + plain. Overlays must be expandable. + +Description file + ``DiskDescriptor.xml`` stores information about disk parameters, + snapshots, storages. + +Top Snapshot + The overlay between actual state and some previous snapshot. + It is not a snapshot in the classical sense because it + serves as the active image that the guest writes to. + +Sector + a 512-byte data chunk. + +Description file +---------------- + +All information is placed in a single XML element +``Parallels_disk_image``. +The element has only one attribute ``Version``, that must be ``1.0``. + +Schema of ``DiskDescriptor.xml``:: + + + + ... + + + ... + + + ... + + + +``Disk_Parameters`` element +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``Disk_Parameters`` element describes the physical layout of the +virtual disk and some general settings. + +The ``Disk_Parameters`` element MUST contain the following child elements: + +* ``Disk_size`` - number of sectors in the disk, + desired size of the disk. +* ``Cylinders`` - number of the disk cylinders. +* ``Heads`` - number of the disk heads. +* ``Sectors`` - number of the disk sectors per cylinder + (sector size is 512 bytes) + Limitation: Product of the ``Heads``, ``Sectors`` and ``Cylinders`` + values MUST be equal to the value of the Disk_size parameter. +* ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may + use padding set to 1, however this case is not covered + by this spec, QEMU and other software should not open + such disks and should not create them. + +``StorageData`` element +^^^^^^^^^^^^^^^^^^^^^^^ + +This element of the file describes the root image and all snapshot images. + +The ``StorageData`` element consists of the ``Storage`` child element, +as shown below:: + + + + ... + + + +A ``Storage`` element has following child elements: + +* ``Start`` - start sector of the storage, in case of non split storage + equals to 0. +* ``End`` - number of sector following the last sector, in case of non + split storage equals to ``Disk_size``. +* ``Blocksize`` - storage cluster size, number of sectors per one cluster. + Cluster size for each "Compressed" (see below) image in + parallels disk must be equal to this field. Note: cluster + size for Parallels Expandable Image is in ``tracks`` field of + its header (see :doc:`parallels`). +* Several ``Image`` child elements. + +Each ``Image`` element has following child elements: + +* ``GUID`` - image identifier, UUID in curly brackets. + For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.`` + The GUID is used by the Snapshots element to reference images + (see below) +* ``Type`` - image type of the element. It can be: + + * ``Plain`` for raw files. + * ``Compressed`` for expanding disks. + +* ``File`` - path to image file. Path can be relative to + ``DiskDescriptor.xml`` or absolute. + +``Snapshots`` element +^^^^^^^^^^^^^^^^^^^^^ + +The ``Snapshots`` element describes the snapshot relations with the snapshot tree. + +The element contains the set of ``Shot`` child elements, as shown below:: + + + ... /* Optional child element */ + + ... + + + ... + + ... + + +Each ``Shot`` element contains the following child elements: + +* ``GUID`` - an image GUID. +* ``ParentGUID`` - GUID of the image of the parent snapshot. + +The software may traverse snapshots from child to parent using ```` +field as reference. ``ParentGUID`` of root snapshot is +``{00000000-0000-0000-0000-000000000000}``. There should be only one root +snapshot. Top snapshot could be described via two ways: via ``TopGUID`` child +element of the ``Snapshots`` element or via predefined GUID +``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined, +predefined GUID is interpreted as usual GUID. All snapshot images +(except Top Snapshot) should be +opened read-only. There is another predefined GUID, +``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by +original and some third-party software for backup, QEMU and other +software may operate with images with ``GUID = BackupID`` as usual, +however, it is not recommended to use this +GUID for new disks. Top snapshot cannot have this GUID. diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt deleted file mode 100644 index cf9b3fba265..00000000000 --- a/docs/interop/prl-xml.txt +++ /dev/null @@ -1,158 +0,0 @@ -= License = - -Copyright (c) 2015-2017, Virtuozzo, Inc. -Authors: - 2015 Denis Lunev - 2015 Vladimir Sementsov-Ogievskiy - 2016-2017 Klim Kireev - 2016-2017 Edgar Kaziakhmedov - -This work is licensed under the terms of the GNU GPL, version 2 or later. -See the COPYING file in the top-level directory. - -This specification contains minimal information about Parallels Disk Format, -which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server -and Parallels Desktop are able to add some unspecified nodes to xml and use -them, but they are for internal work and don't affect functionality. Also it -uses auxiliary xml "Snapshot.xml", which allows to store optional snapshot -information, but it doesn't influence open/read/write functionality. QEMU and -other software should not use fields not covered in this document and -Snapshot.xml file and must leave them as is. - -= Parallels Disk Format = - -Parallels disk consists of two parts: the set of snapshots and the disk -descriptor file, which stores information about all files and snapshots. - -== Definitions == - Snapshot a record of the contents captured at a particular time, - capable of storing current state. A snapshot has UUID and - parent UUID. - - Snapshot image an overlay representing the difference between this - snapshot and some earlier snapshot. - - Overlay an image storing the different sectors between two captured - states. - - Root image snapshot image with no parent, the root of snapshot tree. - - Storage the backing storage for a subset of the virtual disk. When - there is more than one storage in a Parallels disk then that - is referred to as a split image. In this case every storage - covers specific address space area of the disk and has its - particular root image. Split images are not considered here - and are not supported. Each storage consists of disk - parameters and a list of images. The list of images always - contains a root image and may also contain overlays. The - root image can be an expandable Parallels image file or - plain. Overlays must be expandable. - - Description DiskDescriptor.xml stores information about disk parameters, - file snapshots, storages. - - Top The overlay between actual state and some previous snapshot. - Snapshot It is not a snapshot in the classical sense because it - serves as the active image that the guest writes to. - - Sector a 512-byte data chunk. - -== Description file == -All information is placed in a single XML element Parallels_disk_image. -The element has only one attribute "Version", that must be 1.0. -Schema of DiskDescriptor.xml: - - - - ... - - - ... - - - ... - - - -== Disk_Parameters element == -The Disk_Parameters element describes the physical layout of the virtual disk -and some general settings. - -The Disk_Parameters element MUST contain the following child elements: - * Disk_size - number of sectors in the disk, - desired size of the disk. - * Cylinders - number of the disk cylinders. - * Heads - number of the disk heads. - * Sectors - number of the disk sectors per cylinder - (sector size is 512 bytes) - Limitation: Product of the Heads, Sectors and Cylinders - values MUST be equal to the value of the Disk_size parameter. - * Padding - must be 0. Parallels Cloud Server and Parallels Desktop may - use padding set to 1, however this case is not covered - by this spec, QEMU and other software should not open - such disks and should not create them. - -== StorageData element == -This element of the file describes the root image and all snapshot images. - -The StorageData element consists of the Storage child element, as shown below: - - - ... - - - -A Storage element has following child elements: - * Start - start sector of the storage, in case of non split storage - equals to 0. - * End - number of sector following the last sector, in case of non - split storage equals to Disk_size. - * Blocksize - storage cluster size, number of sectors per one cluster. - Cluster size for each "Compressed" (see below) image in - parallels disk must be equal to this field. Note: cluster - size for Parallels Expandable Image is in 'tracks' field of - its header (see docs/interop/parallels.txt). - * Several Image child elements. - -Each Image element has following child elements: - * GUID - image identifier, UUID in curly brackets. - For instance, {12345678-9abc-def1-2345-6789abcdef12}. - The GUID is used by the Snapshots element to reference images - (see below) - * Type - image type of the element. It can be: - "Plain" for raw files. - "Compressed" for expanding disks. - * File - path to image file. Path can be relative to DiskDescriptor.xml or - absolute. - -== Snapshots element == -The Snapshots element describes the snapshot relations with the snapshot tree. - -The element contains the set of Shot child elements, as shown below: - - ... /* Optional child element */ - - ... - - - ... - - ... - - -Each Shot element contains the following child elements: - * GUID - an image GUID. - * ParentGUID - GUID of the image of the parent snapshot. - -The software may traverse snapshots from child to parent using -field as reference. ParentGUID of root snapshot is -{00000000-0000-0000-0000-000000000000}. There should be only one root -snapshot. Top snapshot could be described via two ways: via TopGUID child -element of the Snapshots element or via predefined GUID -{5fbaabe3-6958-40ff-92a7-860e329aab41}. If TopGUID is defined, predefined GUID is -interpreted as usual GUID. All snapshot images (except Top Snapshot) should be -opened read-only. There is another predefined GUID, -BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}, which is used by original and -some third-party software for backup, QEMU and other software may operate with -images with GUID = BackupID as usual, however, it is not recommended to use this -GUID for new disks. Top snapshot cannot have this GUID. From patchwork Fri Aug 9 18:08:31 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759078 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 86496C3DA4A for ; Fri, 9 Aug 2024 18:10:09 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2y-000266-SS; Fri, 09 Aug 2024 14:09:04 -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 1scU2x-00020F-AQ for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:03 -0400 Received: from mail-wm1-x333.google.com ([2a00:1450:4864:20::333]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2v-0007E0-6O for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:03 -0400 Received: by mail-wm1-x333.google.com with SMTP id 5b1f17b1804b1-42817bee9e8so17076715e9.3 for ; Fri, 09 Aug 2024 11:09:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226939; x=1723831739; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=B0ZX+BKezJrv3F6YmQherbds9uPIif5DbFUZSAqPArs=; b=KjEF6SV6VTOLFKAxj+2VVrqE7wIBfCap8uSDi2xEvGLH4rxzcmczbWkEVwskRGUMwN wl86FJCEKkbNYyVePpGIyoohV3ob6U1MdBPdCshLcCsW8NKlEY0nkKzeKvGF12kwBIUY Oem0uX2nUXDz2Hw7OcFrryeIftHe465Xxh6Tais0vB8yJx1tOpfudiSI23A2SSnzPYz5 60VjtST4gy7W+jvBwYRQJNfTXJWnb03Hop2WsEeP0gUFRWItEr85LN+HdqzxKb1qlQ1J NA+3IuF8UDnwBdOT0G56V/upOnKcQnGCR9MLb7rZq2o72F+D+mi3Bi/Ja7rP85AqOp9C 37ow== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226939; x=1723831739; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=B0ZX+BKezJrv3F6YmQherbds9uPIif5DbFUZSAqPArs=; b=rBpFVgZP4Jfbdh/Ewox41KCAnOkfgBUdp5Av1uWf0zUckXM9FF1+jtkYVS2/EIQ1eq RNPre7wdk4fyPU43aPRSaS6hmP5a3KtsO9QFpGR5E2gaVwIO1ecSwTKsu+YvJriUQxKM tW9AKRXp/pNP0TAdcOlN75J6FF23gTvl7C5O8t5QdM4W1v2fqDotNdCfkOI4IV18d/qH 9pbJhVjmsga2IJNHp54o0H06OYpHWMLbitNY1ue+6m/ZCOefzUo857085XWYrUAQzyOT A/x2QioWFgZgHDl/w+/Ow52KPASRqJylVSE2DhlIMK0t6sral/QWmQb83ssVJHWO3i1x hehg== X-Gm-Message-State: AOJu0Yx4ypARc0p8ND1U9lU2tT+63TOr67/n39pD2a5W0KqZrguyi0sd 9JYIgHqITCxf1JlTgXFuXMVPg2Mycij+YLG/Bn+Qbb7m8pNnTV5XBIR+Nec5TXqjcrXq8tumrOD 3 X-Google-Smtp-Source: AGHT+IHzMTOf/KpTaNbuSLC8n2ArlEblMGSsACLvCZT744EqR9HdtMfGryEzFAuqOSuZ29pwEYoRcA== X-Received: by 2002:a05:600c:4f92:b0:428:36e:be59 with SMTP id 5b1f17b1804b1-429c3a23bc6mr16552335e9.11.1723226939438; Fri, 09 Aug 2024 11:08:59 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.56 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:56 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 07/11] docs/interop/prl-xml.rst: Fix minor grammar nits Date: Fri, 9 Aug 2024 19:08:31 +0100 Message-Id: <20240809180835.1243269-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::333; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x333.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Fix some minor grammar nits in the prl-xml documentation. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Reviewed-by: Eric Blake Message-id: 20240801170131.3977807-6-peter.maydell@linaro.org --- docs/interop/prl-xml.rst | 73 +++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 34 deletions(-) diff --git a/docs/interop/prl-xml.rst b/docs/interop/prl-xml.rst index aacf11f4c44..5bb63bb93a4 100644 --- a/docs/interop/prl-xml.rst +++ b/docs/interop/prl-xml.rst @@ -13,15 +13,15 @@ Parallels Disk Format See the COPYING file in the top-level directory. This specification contains minimal information about Parallels Disk Format, -which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server -and Parallels Desktop are able to add some unspecified nodes to xml and use +which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server +and Parallels Desktop are able to add some unspecified nodes to the xml and use them, but they are for internal work and don't affect functionality. Also it -uses auxiliary xml ``Snapshot.xml``, which allows to store optional snapshot -information, but it doesn't influence open/read/write functionality. QEMU and -other software should not use fields not covered in this document and -``Snapshot.xml`` file and must leave them as is. +uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot +information, but this doesn't influence open/read/write functionality. QEMU and +other software should not use fields not covered in this document or the +``Snapshot.xml`` file, and must leave them as is. -Parallels disk consists of two parts: the set of snapshots and the disk +A Parallels disk consists of two parts: the set of snapshots and the disk descriptor file, which stores information about all files and snapshots. Definitions @@ -29,7 +29,7 @@ Definitions Snapshot a record of the contents captured at a particular time, capable - of storing current state. A snapshot has UUID and parent UUID. + of storing current state. A snapshot has a UUID and a parent UUID. Snapshot image an overlay representing the difference between this @@ -39,13 +39,13 @@ Overlay an image storing the different sectors between two captured states. Root image - snapshot image with no parent, the root of snapshot tree. + a snapshot image with no parent, the root of the snapshot tree. Storage the backing storage for a subset of the virtual disk. When there is more than one storage in a Parallels disk then that is referred to as a split image. In this case every storage - covers specific address space area of the disk and has its + covers a specific address space area of the disk and has its particular root image. Split images are not considered here and are not supported. Each storage consists of disk parameters and a list of images. The list of images always @@ -55,7 +55,7 @@ Storage Description file ``DiskDescriptor.xml`` stores information about disk parameters, - snapshots, storages. + snapshots, and storages. Top Snapshot The overlay between actual state and some previous snapshot. @@ -70,9 +70,9 @@ Description file All information is placed in a single XML element ``Parallels_disk_image``. -The element has only one attribute ``Version``, that must be ``1.0``. +The element has only one attribute, ``Version``, which must be ``1.0``. -Schema of ``DiskDescriptor.xml``:: +The schema of ``DiskDescriptor.xml``:: @@ -100,11 +100,11 @@ The ``Disk_Parameters`` element MUST contain the following child elements: * ``Heads`` - number of the disk heads. * ``Sectors`` - number of the disk sectors per cylinder (sector size is 512 bytes) - Limitation: Product of the ``Heads``, ``Sectors`` and ``Cylinders`` + Limitation: The product of the ``Heads``, ``Sectors`` and ``Cylinders`` values MUST be equal to the value of the Disk_size parameter. * ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may - use padding set to 1, however this case is not covered - by this spec, QEMU and other software should not open + use padding set to 1; however this case is not covered + by this specification. QEMU and other software should not open such disks and should not create them. ``StorageData`` element @@ -121,20 +121,20 @@ as shown below:: -A ``Storage`` element has following child elements: +A ``Storage`` element has the following child elements: * ``Start`` - start sector of the storage, in case of non split storage equals to 0. * ``End`` - number of sector following the last sector, in case of non split storage equals to ``Disk_size``. * ``Blocksize`` - storage cluster size, number of sectors per one cluster. - Cluster size for each "Compressed" (see below) image in - parallels disk must be equal to this field. Note: cluster - size for Parallels Expandable Image is in ``tracks`` field of + The cluster size for each "Compressed" (see below) image in + a parallels disk must be equal to this field. Note: the cluster + size for a Parallels Expandable Image is in the ``tracks`` field of its header (see :doc:`parallels`). * Several ``Image`` child elements. -Each ``Image`` element has following child elements: +Each ``Image`` element has the following child elements: * ``GUID`` - image identifier, UUID in curly brackets. For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.`` @@ -145,7 +145,7 @@ Each ``Image`` element has following child elements: * ``Plain`` for raw files. * ``Compressed`` for expanding disks. -* ``File`` - path to image file. Path can be relative to +* ``File`` - path to image file. The path can be relative to ``DiskDescriptor.xml`` or absolute. ``Snapshots`` element @@ -171,17 +171,22 @@ Each ``Shot`` element contains the following child elements: * ``GUID`` - an image GUID. * ``ParentGUID`` - GUID of the image of the parent snapshot. -The software may traverse snapshots from child to parent using ```` -field as reference. ``ParentGUID`` of root snapshot is -``{00000000-0000-0000-0000-000000000000}``. There should be only one root -snapshot. Top snapshot could be described via two ways: via ``TopGUID`` child -element of the ``Snapshots`` element or via predefined GUID +The software may traverse snapshots from child to parent using the +```` field as reference. The ``ParentGUID`` of the root +snapshot is ``{00000000-0000-0000-0000-000000000000}``. +There should be only one root snapshot. + +The Top snapshot could be +described via two ways: via the ``TopGUID`` child +element of the ``Snapshots`` element, or via the predefined GUID ``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined, -predefined GUID is interpreted as usual GUID. All snapshot images -(except Top Snapshot) should be -opened read-only. There is another predefined GUID, +the predefined GUID is interpreted as a normal GUID. All snapshot images +(except the Top Snapshot) should be +opened read-only. + +There is another predefined GUID, ``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by -original and some third-party software for backup, QEMU and other -software may operate with images with ``GUID = BackupID`` as usual, -however, it is not recommended to use this -GUID for new disks. Top snapshot cannot have this GUID. +original and some third-party software for backup. QEMU and other +software may operate with images with ``GUID = BackupID`` as usual. +However, it is not recommended to use this +GUID for new disks. The Top snapshot cannot have this GUID. From patchwork Fri Aug 9 18:08:32 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759077 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 98187C52D7C for ; Fri, 9 Aug 2024 18:10:09 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU2z-00028x-GU; Fri, 09 Aug 2024 14:09:05 -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 1scU2x-000216-Hc for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:03 -0400 Received: from mail-lj1-x234.google.com ([2a00:1450:4864:20::234]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2v-0007E6-VQ for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:03 -0400 Received: by mail-lj1-x234.google.com with SMTP id 38308e7fff4ca-2eeb1ba0481so30874251fa.2 for ; Fri, 09 Aug 2024 11:09:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226940; x=1723831740; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=bV8ikeaAUAZQosDzE0s/Lkzb0lfb7R8ZRGC15xmyP3s=; b=NE6YcxpG8tdtCKlblXo/m1YgdzVv30kKs9PNzojYf2OT3ubH/42Bzk/NUEqjlo8dFF SuLeC4jIyJIQ1Ng2gWth6mPZbrfvcrT3bXO4gBwnNo1P5AWIkCCVN0ygoIpbWtl+Sn+T vTREyz+a33IX3beHIGKFjj5BIevIMYliGsJ86PZjcfz2Sf8++rJtd0GjXjiFhjk9WvHq 8KGCBlG/++pStfjmEQLH0Ug2cJugDPNnEHe+FV/dTihzpImogDJzne+9QI+N5KKrBDsT zhosazDznbC8eXCctdYgMtd0GiK959Z2UFSwDld19Axa7DcpNOcl/nhYOGCUGCGRWI3x w9/A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226940; x=1723831740; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bV8ikeaAUAZQosDzE0s/Lkzb0lfb7R8ZRGC15xmyP3s=; b=qXjYsN/qxkW7X0hQuvuPinr7GzVfIll9pidbQzjtz99aZb1Aubxlggpa6Iq8WvHPfz 6y23+pXYKp+MQLTYmlSG1CHbuWUHPklBrKsPqxrLCsaSQkf0Ek6100YWcPz1/oQZPfln Xs7H4r9tB8BwFFlpBkMEYlMiCanpbncr7QJIdHAYnVlM4XzEiaUr8ZzTqyjwq3ZsvjCn 5sAEWevjRphDUuNJUgpgfjXJPnPnhkAV2UAOGDy22ZRp028h/rgngo+mvTwAGrS5GvV7 uL2OrdNmaxPCToEymdPBJ2bCkOE5lnfIBevRkX5p9397VjOP8E4yoFn5JJ+DbXtjtUIm WZeg== X-Gm-Message-State: AOJu0YxzJAICRQXWcnisnWMtr5OtVxVCZ0iWAzJIKpe+GqY1wbPrziSi sf0GPHcVIsfhyqdSSapwEW41dxhmaIWloTrNeY01u3dSACBwZ8J+cPRpgsdue4OEOLJs9AeNVmS / X-Google-Smtp-Source: AGHT+IFRLiBj6Zml026NmTbtvJ1BIH4KJliOlLIDGxzxIlmluvlXCSfzpt4eUiEBPM6RzhMVZKKqAQ== X-Received: by 2002:a2e:f12:0:b0:2ef:2f53:c300 with SMTP id 38308e7fff4ca-2f1a6c778efmr15952001fa.28.1723226940028; Fri, 09 Aug 2024 11:09:00 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.08.59 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:08:59 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 08/11] docs: Typo fix in live disk backup Date: Fri, 9 Aug 2024 19:08:32 +0100 Message-Id: <20240809180835.1243269-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::234; envelope-from=peter.maydell@linaro.org; helo=mail-lj1-x234.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Eric Blake Add in the missing space in the section header. Fixes: 1084159b31 ("qapi: deprecate drive-backup", v6.2.0) Signed-off-by: Eric Blake Signed-off-by: Peter Maydell --- docs/interop/live-block-operations.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst index 691429c7afe..6b549ede7c9 100644 --- a/docs/interop/live-block-operations.rst +++ b/docs/interop/live-block-operations.rst @@ -931,8 +931,8 @@ Shutdown the guest, by issuing the ``quit`` QMP command:: } -Live disk backup --- ``blockdev-backup`` and the deprecated``drive-backup`` ---------------------------------------------------------------------------- +Live disk backup --- ``blockdev-backup`` and the deprecated ``drive-backup`` +---------------------------------------------------------------------------- The ``blockdev-backup`` (and the deprecated ``drive-backup``) allows you to create a point-in-time snapshot. From patchwork Fri Aug 9 18:08:33 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759085 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 6750EC52D7C for ; Fri, 9 Aug 2024 18:10:53 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU30-0002Cb-Ee; Fri, 09 Aug 2024 14:09:06 -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 1scU2y-00025s-NV for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:04 -0400 Received: from mail-lj1-x229.google.com ([2a00:1450:4864:20::229]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU2w-0007EF-OI for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:04 -0400 Received: by mail-lj1-x229.google.com with SMTP id 38308e7fff4ca-2f0271b0ae9so23785321fa.1 for ; Fri, 09 Aug 2024 11:09:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226941; x=1723831741; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=OTKwxuPziiy0+9qyVmM4AyVNPdnxPukHZnKDv7thDS0=; b=jegS4DYaDY0hCVV+NeObu9yuZEO/d6owZgQEwiAD7xMd0pbmj0bgSeYk0rQnV4VwB+ de0oMGsEGw2nF2pdvEgAyfFpqPSKos4BLvf6i1FG0I87kAZDEfPwJjzwbccy3SkURde+ n733lB3OY2HLVWD3zNHsFES+6TcrdVDMkPxKuCN8gY4H/Jc2vYgeE8iNFozApG8RkUuh aZ6ivFq5GKc7wbn19vw/efmm3rwkYb1uqPmMprBTw5gPZzPzPNrOFqD6workj3DbDyWl vo+V2+Zb30/P4T31jTVXygNJX0iqA+4WD5SjkVo0N6zMcYR3SQsfVrR5JW3rli2TOEyo GH0g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226941; x=1723831741; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=OTKwxuPziiy0+9qyVmM4AyVNPdnxPukHZnKDv7thDS0=; b=bJCJtRQqSEUDBxx1UQ5d5KAVykx/RLWNucZlTmq39tuoigTf5qlnGsqhvILJKq4n5/ g0VrsAT2kKWvtOPCDuYW+hQNIX9jSQ4IBq0oojGkjqzt4ZIGfGkb6GJxjkks66v4L4WO LLNqMR499yEkdBF6Kzw/k862FFMlUPGO1xobsam+rnRTADrFU//grdqXU+KzIh8q6csC v+Tkk3dTvHD890Ru4u70PtRotAJ1k2rIEyQw1n1HM9GAiNj2lqgyqhAKwrNftn1V0WZB NGtw3BbvadjNupbWWJhS91w63X8s6R6Z/SSAH6xjI3kEXQn19si0yrHPQyWWS0zugALl 6e4g== X-Gm-Message-State: AOJu0Yx6Vtq6GSda2ZF43YUD94eFxEaKqGDB+Ynwrg+ysAhV0mHfotAg X7WuU4gNk7VE/IacCtN1GRIx31W3spML35PizINl/oOYkNNz/Jm6YIb7fxBwAMirbf6X4Rpe9/f e X-Google-Smtp-Source: AGHT+IGmz4CoUcJ5S5EgVqzAUXDlT0bafavuNsRmNwNytbLIxpdtTvSR+YvA7E+rdJFiLDGVr1YdyQ== X-Received: by 2002:a05:651c:b29:b0:2ee:5ed4:792f with SMTP id 38308e7fff4ca-2f1a6d0034amr18342261fa.2.1723226940590; Fri, 09 Aug 2024 11:09:00 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.09.00 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:09:00 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 09/11] target/arm: add support for PMUv3 64-bit PMCCNTR in AArch32 mode Date: Fri, 9 Aug 2024 19:08:33 +0100 Message-Id: <20240809180835.1243269-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::229; envelope-from=peter.maydell@linaro.org; helo=mail-lj1-x229.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Alex Richardson In the PMUv3, a new AArch32 64-bit (MCRR/MRRC) accessor for the PMCCNTR was added. In QEMU we forgot to implement this, so only provide the 32-bit accessor. Since we have a 64-bit PMCCNTR sysreg for AArch64, adding the 64-bit AArch32 version is easy. We add the PMCCNTR to the v8_cp_reginfo because PMUv3 was added in the ARMv8 architecture. This is consistent with how we handle the existing PMCCNTR support, where we always implement it for all v7 CPUs. This is arguably something we should clean up so it is gated on ARM_FEATURE_PMU and/or an ID register check for the relevant PMU version, but we should do that as its own tidyup rather than being inconsistent between this PMCCNTR accessor and the others. See https://developer.arm.com/documentation/ddi0601/2024-06/AArch32-Registers/PMCCNTR--Performance-Monitors-Cycle-Count-Register?lang=en Signed-off-by: Alex Richardson Message-id: 20240801220328.941866-1-alexrichardson@google.com Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- target/arm/helper.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/target/arm/helper.c b/target/arm/helper.c index 8fb4b474e83..94900667c33 100644 --- a/target/arm/helper.c +++ b/target/arm/helper.c @@ -5952,6 +5952,12 @@ static const ARMCPRegInfo v8_cp_reginfo[] = { .access = PL1_RW, .accessfn = access_trap_aa32s_el1, .writefn = sdcr_write, .fieldoffset = offsetoflow32(CPUARMState, cp15.mdcr_el3) }, + { .name = "PMCCNTR", .state = ARM_CP_STATE_AA32, + .type = ARM_CP_ALIAS | ARM_CP_IO | ARM_CP_64BIT, + .cp = 15, .crm = 9, .opc1 = 0, + .access = PL0_RW, .resetvalue = 0, .fgt = FGT_PMCCNTR_EL0, + .readfn = pmccntr_read, .writefn = pmccntr_write, + .accessfn = pmreg_access_ccntr }, }; /* These are present only when EL1 supports AArch32 */ From patchwork Fri Aug 9 18:08:34 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759083 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 72747C3DA4A for ; Fri, 9 Aug 2024 18:10:39 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU3B-0002eQ-2z; Fri, 09 Aug 2024 14:09:17 -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 1scU38-0002cI-1l for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:14 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU35-0007Ew-JF for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:13 -0400 Received: by mail-wr1-x436.google.com with SMTP id ffacd0b85a97d-369c609d0c7so1775434f8f.3 for ; Fri, 09 Aug 2024 11:09:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226950; x=1723831750; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=jquWz0USW85lcynOd+V15nNwRrJbu/joQPKxFZlMmk0=; b=WQIwxzahEbk5TtQe53/t2dj3VLdxR0tAvSKmHpGENWXu6Zi9vzuJUK19TWaPoHofm+ +rMzQXccEV8GbxabRLcXLT25R1Tk+BDbtDnU4ivxpMIE3SsRlxasWaDRQy1T7cVsmVdv 2TzRIawn5y5/vejNvaiT5d7FZ0Pesw0FyFs8LzcD+pyRflXWITXmKQJaXI8I4AAxdi/W 4FnKXy9K/nAGMx9NKhuintoOTaMxA4SEuns51eHJe+Akr7CR4vzBnvRr6G2311N13Zxu RXbKi7Z3I2n/JjEmbdxMJHy2oZEz5Omyq+5tAGjkbZ0nLaGCmwtsPyRKVvpgm2HGQXfj CE7w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226950; x=1723831750; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=jquWz0USW85lcynOd+V15nNwRrJbu/joQPKxFZlMmk0=; b=kzvhkgAR1IErBFTopVqPTV9t9QtfwCULxok4FvxayofYPHJr6rMVFgkOvlSd26cEeq Wf0+QXecC4QueAY49ZGP3QKNmkEockEs6HN1j1oYDBy6BC5wAR2jP1taEffCdDXTa+eh EJtUbAEy3lrB3y4wGhP2jkA9zHBrZgDv0TjS3Z1gh+atF9FLHDc5brJ5SMrsMh/bwUOS o1ilQCFYebGhIgs4rWW7ciNHbattY5knUGKwmOA5xyegRtb1o8UrZ3VcGj0Kdz2ve0Gi +6fHCwz/v+m/cZhls3LgUS3lVlHtDC9bhIt+qWgD8VaeosSHKehd/8neCd/c//7CNx1A stXQ== X-Gm-Message-State: AOJu0YxgGtibGNK3ZXi1V585RjaQJpoGifxEXES0AepsBYHoDGe02GtA G+hQLPERZEBs+UKQuYuUrMOnDWYUzL/cYzBCsU6UzM/ZJU1JMVTOxaq4mIozDgHuSkihqumyl/d i X-Google-Smtp-Source: AGHT+IGks1AxJW21O1k59IG+rqXlynqIv6KrJ6vyWJ8pe9XmbJAb+S6snsja4Mv6z4jYtXp6f0M3GQ== X-Received: by 2002:adf:ee50:0:b0:368:6596:edba with SMTP id ffacd0b85a97d-36d5fd7e9b0mr1986551f8f.39.1723226949954; Fri, 09 Aug 2024 11:09:09 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.09.00 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:09:00 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 10/11] hw/core/ptimer: fix timer zero period condition for freq > 1GHz Date: Fri, 9 Aug 2024 19:08:34 +0100 Message-Id: <20240809180835.1243269-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::436; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x436.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Jianzhou Yue The real period is zero when both period and period_frac are zero. Check the method ptimer_set_freq, if freq is larger than 1000 MHz, the period is zero, but the period_frac is not, in this case, the ptimer will work but the current code incorrectly recognizes that the ptimer is disabled. Resolves: https://gitlab.com/qemu-project/qemu/-/issues/2306 Signed-off-by: JianZhou Yue Message-id: 3DA024AEA8B57545AF1B3CAA37077D0FB75E82C8@SHASXM03.verisilicon.com Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- hw/core/ptimer.c | 4 ++-- tests/unit/ptimer-test.c | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/hw/core/ptimer.c b/hw/core/ptimer.c index b1517592c6b..1d8964d8044 100644 --- a/hw/core/ptimer.c +++ b/hw/core/ptimer.c @@ -83,7 +83,7 @@ static void ptimer_reload(ptimer_state *s, int delta_adjust) delta = s->delta = s->limit; } - if (s->period == 0) { + if (s->period == 0 && s->period_frac == 0) { if (!qtest_enabled()) { fprintf(stderr, "Timer with period zero, disabling\n"); } @@ -309,7 +309,7 @@ void ptimer_run(ptimer_state *s, int oneshot) assert(s->in_transaction); - if (was_disabled && s->period == 0) { + if (was_disabled && s->period == 0 && s->period_frac == 0) { if (!qtest_enabled()) { fprintf(stderr, "Timer with period zero, disabling\n"); } diff --git a/tests/unit/ptimer-test.c b/tests/unit/ptimer-test.c index 04b5f4e3d03..08240594bbd 100644 --- a/tests/unit/ptimer-test.c +++ b/tests/unit/ptimer-test.c @@ -763,6 +763,33 @@ static void check_oneshot_with_load_0(gconstpointer arg) ptimer_free(ptimer); } +static void check_freq_more_than_1000M(gconstpointer arg) +{ + const uint8_t *policy = arg; + ptimer_state *ptimer = ptimer_init(ptimer_trigger, NULL, *policy); + bool no_round_down = (*policy & PTIMER_POLICY_NO_COUNTER_ROUND_DOWN); + + triggered = false; + + ptimer_transaction_begin(ptimer); + ptimer_set_freq(ptimer, 2000000000); + ptimer_set_limit(ptimer, 8, 1); + ptimer_run(ptimer, 1); + ptimer_transaction_commit(ptimer); + + qemu_clock_step(3); + + g_assert_cmpuint(ptimer_get_count(ptimer), ==, no_round_down ? 3 : 2); + g_assert_false(triggered); + + qemu_clock_step(1); + + g_assert_cmpuint(ptimer_get_count(ptimer), ==, 0); + g_assert_true(triggered); + + ptimer_free(ptimer); +} + static void add_ptimer_tests(uint8_t policy) { char policy_name[256] = ""; @@ -857,6 +884,12 @@ static void add_ptimer_tests(uint8_t policy) policy_name), g_memdup2(&policy, 1), check_oneshot_with_load_0, g_free); g_free(tmp); + + g_test_add_data_func_full( + tmp = g_strdup_printf("/ptimer/freq_more_than_1000M policy=%s", + policy_name), + g_memdup2(&policy, 1), check_freq_more_than_1000M, g_free); + g_free(tmp); } static void add_all_ptimer_policies_comb_tests(void) From patchwork Fri Aug 9 18:08:35 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 13759082 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 E8E9AC3DA4A for ; Fri, 9 Aug 2024 18:10:17 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scU3G-0002rz-9k; Fri, 09 Aug 2024 14:09:22 -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 1scU38-0002cJ-28 for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:14 -0400 Received: from mail-wr1-x42d.google.com ([2a00:1450:4864:20::42d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scU36-0007Ez-5L for qemu-devel@nongnu.org; Fri, 09 Aug 2024 14:09:13 -0400 Received: by mail-wr1-x42d.google.com with SMTP id ffacd0b85a97d-36868fcb919so1413442f8f.2 for ; Fri, 09 Aug 2024 11:09:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1723226950; x=1723831750; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=y9/XnuauRRdGNB5+R3kAgyNx59VWh+he+xrVnHsAoO8=; b=Zf5WlLYe0k7jXqj6Xfq2eJinHrjFah5/m/KCXTDCO0EaQ3cDkb6+5+bP833kYdha6M I4svKiIWNByLIavroP3mxCKOa4EdVSnbpLBmexStsRnZ5tZCEmJmfb8B5z9L1whZ/qLf ruDMROuWpX3l8NG0oYdiVyW1RB3znKvY65U2yD5V64GMRFhMlZK/bMxUiquFANr+d6UU hfTpyimC4NIJVhTxvBjR8idVLz6o9A4zYP77rXBFb/NeZblBCNuafn3QOWKKyNyqFNZX darFQM9fN3B4h+9HoWBmQSqs77fmsdXk2X85CRHXcMYz3k+qWBpapXEmqBvXp0Yxow+b honw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723226950; x=1723831750; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=y9/XnuauRRdGNB5+R3kAgyNx59VWh+he+xrVnHsAoO8=; b=XD4Q+dCmilA/9tPYydOVyecSYxxiPjeLOqbVZybExUVGIlVBku5xPQDaHHASezh52+ QJ4m5OjBo+GK6FhSihPklZmn70smLBqnhJ0nLtt8t1NycqSmahDQSZy2IsTkHSNcpLn1 m6Baa8bF6riqD4kxLJSwB9gok2QNv71PtyG9zvlalp9htkgM5j2tmRDrs2kuCw6e+vLL v4h7N36zvSZrzTOhemVU7W9IjaZ5/QrWugluowuaVatATXIHWXsXE16NHylhMmVvJT/6 kpJ//zKWpd3ZB7sReGe44NfB69C37RvcN6cji8Xgep7eTKaiNa8hQl1ZT6L0EDSrQ8ww A8cg== X-Gm-Message-State: AOJu0YwsadN3X2HgCF1lID2ELlp9HfJRG/nERdBo/MK0fTBP102tz+I7 uUmpQxbnY1h7GAza6vNMKL80GDBgdODBMzF1WvhPpdR+9bwuKkZD5AQ2zBIfoZmMB9l1mxhjXZ4 t X-Google-Smtp-Source: AGHT+IG3jbN2V7bl3rHn+FSI3etZjSeiN4lhid4rGMMIAjpiZZebansF/c+8VJxN4ZhFuDoj0wI8UQ== X-Received: by 2002:adf:fe8b:0:b0:363:e0e2:eeff with SMTP id ffacd0b85a97d-36d5fa9d8b5mr2193544f8f.20.1723226950594; Fri, 09 Aug 2024 11:09:10 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-36e4c937b6esm132262f8f.32.2024.08.09.11.09.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Aug 2024 11:09:10 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 11/11] arm/virt: place power button pin number on a define Date: Fri, 9 Aug 2024 19:08:35 +0100 Message-Id: <20240809180835.1243269-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809180835.1243269-1-peter.maydell@linaro.org> References: <20240809180835.1243269-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42d; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42d.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Mauro Carvalho Chehab Having magic numbers inside the code is not a good idea, as it is error-prone. So, instead, create a macro with the number definition. Link: https://lore.kernel.org/qemu-devel/CAFEAcA-PYnZ-32MRX+PgvzhnoAV80zBKMYg61j2f=oHaGfwSsg@mail.gmail.com/ Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Jonathan Cameron Reviewed-by: Igor Mammedov Message-id: ef0e7f5fca6cd94eda415ecee670c3028c671b74.1723121692.git.mchehab+huawei@kernel.org Suggested-by: Peter Maydell Reviewed-by: Jonathan Cameron Reviewed-by: Igor Mammedov Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- include/hw/arm/virt.h | 3 +++ hw/arm/virt-acpi-build.c | 6 +++--- hw/arm/virt.c | 7 ++++--- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/include/hw/arm/virt.h b/include/hw/arm/virt.h index ab961bb6a9b..a4d937ed45a 100644 --- a/include/hw/arm/virt.h +++ b/include/hw/arm/virt.h @@ -47,6 +47,9 @@ /* See Linux kernel arch/arm64/include/asm/pvclock-abi.h */ #define PVTIME_SIZE_PER_CPU 64 +/* GPIO pins */ +#define GPIO_PIN_POWER_BUTTON 3 + enum { VIRT_FLASH, VIRT_MEM, diff --git a/hw/arm/virt-acpi-build.c b/hw/arm/virt-acpi-build.c index e10cad86dd7..f76fb117adf 100644 --- a/hw/arm/virt-acpi-build.c +++ b/hw/arm/virt-acpi-build.c @@ -154,10 +154,10 @@ static void acpi_dsdt_add_gpio(Aml *scope, const MemMapEntry *gpio_memmap, aml_append(dev, aml_name_decl("_CRS", crs)); Aml *aei = aml_resource_template(); - /* Pin 3 for power button */ - const uint32_t pin_list[1] = {3}; + + const uint32_t pin = GPIO_PIN_POWER_BUTTON; aml_append(aei, aml_gpio_int(AML_CONSUMER, AML_EDGE, AML_ACTIVE_HIGH, - AML_EXCLUSIVE, AML_PULL_UP, 0, pin_list, 1, + AML_EXCLUSIVE, AML_PULL_UP, 0, &pin, 1, "GPO0", NULL, 0)); aml_append(dev, aml_name_decl("_AEI", aei)); diff --git a/hw/arm/virt.c b/hw/arm/virt.c index 719e83e6a1e..687fe0bb8bc 100644 --- a/hw/arm/virt.c +++ b/hw/arm/virt.c @@ -1004,7 +1004,7 @@ static void virt_powerdown_req(Notifier *n, void *opaque) if (s->acpi_dev) { acpi_send_event(s->acpi_dev, ACPI_POWER_DOWN_STATUS); } else { - /* use gpio Pin 3 for power button event */ + /* use gpio Pin for power button event */ qemu_set_irq(qdev_get_gpio_in(gpio_key_dev, 0), 1); } } @@ -1013,7 +1013,8 @@ static void create_gpio_keys(char *fdt, DeviceState *pl061_dev, uint32_t phandle) { gpio_key_dev = sysbus_create_simple("gpio-key", -1, - qdev_get_gpio_in(pl061_dev, 3)); + qdev_get_gpio_in(pl061_dev, + GPIO_PIN_POWER_BUTTON)); qemu_fdt_add_subnode(fdt, "/gpio-keys"); qemu_fdt_setprop_string(fdt, "/gpio-keys", "compatible", "gpio-keys"); @@ -1024,7 +1025,7 @@ static void create_gpio_keys(char *fdt, DeviceState *pl061_dev, qemu_fdt_setprop_cell(fdt, "/gpio-keys/poweroff", "linux,code", KEY_POWER); qemu_fdt_setprop_cells(fdt, "/gpio-keys/poweroff", - "gpios", phandle, 3, 0); + "gpios", phandle, GPIO_PIN_POWER_BUTTON, 0); } #define SECURE_GPIO_POWEROFF 0