From nobody Sun Nov 24 14:58:35 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1723227011; cv=none; d=zohomail.com; s=zohoarc; b=bBszSE5w0DQAORKxDQkveZS2qM+FEo38LWAYAR7f68pUyq5d3QfyN6CGkSnIwHk47fwzUa7ThnujptQYRk6EBP6EsuRl65WFQjHF6/nKyfOrIPtpIseNvMW6JjLVGCQV4ONRP4qvTzb/rKDP2m6k3KxDNpifKxkRHnxBfOpGmps= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1723227011; h=Content-Transfer-Encoding:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=agG5AiF1eAhZlwXMsZvTErllzGZ75Y15g9KkwWX0cZI=; b=XbaXALCkAL0/t+qhIPdc4JkNGsyIra/WT99pKp5MQHcga0wQumdUSn3mdEW87zxI5+AjmfZJr7UNd+wzZheD9EO/w8xZSmdhafzBjKSEAVZt6Em7zeGhv0hFAJKCDBWVI63mFnYYgE4rITgYDLT9/jqZnyXUUcfOpIS+fKl5JFc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 172322701170573.72195028777776; Fri, 9 Aug 2024 11:10:11 -0700 (PDT) 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) 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) 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) 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 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1723227013350116600 Content-Type: text/plain; charset="utf-8" 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 =3D> parallels.rst} | 108 ++++++++++-------- 3 files changed, 60 insertions(+), 51 deletions(-) rename docs/interop/{parallels.txt =3D> 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 =20 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 softwa= re. 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 @@ -=3D License =3D +Parallels Expandable Image File Format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -Copyright (c) 2015 Denis Lunev -Copyright (c) 2015 Vladimir Sementsov-Ogievskiy +.. + Copyright (c) 2015 Denis Lunev + Copyright (c) 2015 Vladimir Sementsov-Ogievskiy =20 -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 late= r. + See the COPYING file in the top-level directory. =20 -=3D Parallels Expandable Image File Format =3D =20 A Parallels expandable image file consists of three consecutive parts: - * header - * BAT - * data area + +* header +* BAT +* data area =20 All numbers in a Parallels expandable image are stored in little-endian by= te order. =20 =20 -=3D=3D Definitions =3D=3D +Definitions +----------- =20 - Sector A 512-byte data chunk. +Sector + A 512-byte data chunk. =20 - Cluster A data chunk of the size specified in the image header. - Currently, the default size is 1MiB (2048 sectors). In previ= ous - 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. =20 - 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. =20 - -=3D=3D Header =3D=3D +Header +------ =20 The header is placed at the start of an image and contains the following -fields: +fields:: =20 -Bytes: + Bytes: 0 - 15: magic Must contain "WithoutFreeSpace" or "WithouFreSpacExt". =20 @@ -103,44 +108,46 @@ Bytes: ext_off must meet the same requirements as cluster offsets defined by BAT entries (see below). =20 - -=3D=3D BAT =3D=3D +BAT +--- =20 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. =20 Each BAT entry contains an offset from the start of the file to the -corresponding cluster. The offset set in clusters for "WithouFreSpacExt" i= mages -and in sectors for "WithoutFreeSpace" images. +corresponding cluster. The offset set in clusters for ``WithouFreSpacExt`` +images and in sectors for ``WithoutFreeSpace`` images. =20 If a BAT entry is zero, the corresponding cluster is not allocated and sho= uld be considered as filled with zeroes. =20 Cluster offsets specified by BAT entries must meet the following requireme= nts: - - the value must not be lower than data offset (provided by header.dat= a_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 clus= ter - size. =20 +- 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 =20 -=3D=3D Data Area =3D=3D +Data Area +--------- =20 -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_o= ff`` +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 allocat= ed by -extensions. All clusters allocated by ext_off and extensions should meet t= he -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 extensi= ons +should meet the same requirements as clusters specified by BAT entries. =20 =20 -=3D=3D Format Extension =3D=3D +Format Extension +---------------- =20 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 hea= der. -The format of the Format Extension area is the following: +The format of the Format Extension area is the following:: =20 0 - 7: magic Must be 0xAB234CEF23DCEA87 @@ -149,10 +156,10 @@ The format of the Format Extension area is the follow= ing: The MD5 checksum of the entire Header Extension cluster exce= pt the first 24 bytes. =20 - 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). =20 -Each feature section has the following format: +Each feature section has the following format:: =20 0 - 7: magic The identifier of the feature: @@ -183,16 +190,17 @@ Each feature section has the following format: =20 variable: data (data_size bytes) =20 - 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. =20 - The last extension must be "End of features" with all the fields set t= o 0. +The last extension must be "End of features" with all the fields set to 0. =20 =20 -=3D=3D=3D Dirty bitmaps feature =3D=3D=3D +Dirty bitmaps feature +--------------------- =20 This feature provides a way of storing dirty bitmaps in the image. The fie= lds -of its data area are: +of its data area are:: =20 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 o= f these clusters are saved in the L1 offset table specified by the feature extension. Each L1 t= able entry is a 64 bit integer as described below: =20 -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:: =20 l1_table[offset / cluster_size] =20 @@ -227,6 +235,6 @@ are assumed to be 1. =20 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:: =20 offset =3D l1_table[offset / cluster_size] * 512 + (offset % cluster_s= ize) --=20 2.34.1