From nobody Sun May 5 10:55:56 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1595244284; cv=none; d=zohomail.com; s=zohoarc; b=EORSPP/6VcwyLKoDsDN9W4stea3RklVs76OWN7mApmIJVSlPeScfoNxiZwH31S2eDHwc0mirfh4z2OsTnHubVK1fgzGLGuYvfwqkVjayhuZA9z4V6QqRJK5A9tZIRomzAGwW7d5RUTj5CKLklI4sfu23jWuvLba/bY+sIpVnYsY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595244284; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=xqmEuailkatE49OKxcPmROFooAtat08Dpww+YBsUsi0=; b=dmZRsOa+9ahnVYpBVsMck8LYz5IWdr+55ahEZyXtKZDdBL6++ctV2zgwWm5UK2G2L9YjAuyQZP8cbpeWF12i2Xno/VBYkFYMw4TBGRDQlbZTckThTN9LKu/tnuoEm2Go2t9m2cc6cwfgA6i0A6Q8eofjQMg9vJqugX3nqBZlEz8= ARC-Authentication-Results: i=1; mx.zohomail.com; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 15952442843441011.1865209561763; Mon, 20 Jul 2020 04:24:44 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1jxTtx-0006yP-HP; Mon, 20 Jul 2020 11:24:09 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1jxTtw-0006yK-BX for xen-devel@lists.xenproject.org; Mon, 20 Jul 2020 11:24:08 +0000 Received: from mx2.suse.de (unknown [195.135.220.15]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 861d1629-ca7b-11ea-9f85-12813bfff9fa; Mon, 20 Jul 2020 11:24:07 +0000 (UTC) Received: from relay2.suse.de (unknown [195.135.221.27]) by mx2.suse.de (Postfix) with ESMTP id C1930AB7A; Mon, 20 Jul 2020 11:24:12 +0000 (UTC) X-Inumbo-ID: 861d1629-ca7b-11ea-9f85-12813bfff9fa X-Virus-Scanned: by amavisd-new at test-mx.suse.de From: Juergen Gross To: xen-devel@lists.xenproject.org Subject: [PATCH v3] docs: specify stability of hypfs path documentation Date: Mon, 20 Jul 2020 13:21:37 +0200 Message-Id: <20200720112137.27327-1-jgross@suse.com> X-Mailer: git-send-email 2.26.2 MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Juergen Gross , Stefano Stabellini , Julien Grall , Wei Liu , paul@xen.org, Andrew Cooper , Ian Jackson , George Dunlap , Jan Beulich Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" In docs/misc/hypfs-paths.pandoc the supported paths in the hypervisor file system are specified. Make it more clear that path availability might change, e.g. due to scope widening or narrowing (e.g. being limited to a specific architecture). Signed-off-by: Juergen Gross Release-acked-by: Paul Durrant Acked-by: Jan Beulich --- V2: reworded as requested by Jan Beulich V3: reworded again as suggested by George Dunlap --- docs/misc/hypfs-paths.pandoc | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc index a111c6f25c..68d83d9245 100644 --- a/docs/misc/hypfs-paths.pandoc +++ b/docs/misc/hypfs-paths.pandoc @@ -5,6 +5,9 @@ in the Xen hypervisor file system (hypfs). =20 The hypervisor file system can be accessed via the xenhypfs tool. =20 +The availability of the hypervisor file system depends on the hypervisor +config option CONFIG_HYPFS, which is on per default. + ## Notation =20 The hypervisor file system is similar to the Linux kernel's sysfs. @@ -64,6 +67,23 @@ the list elements separated by spaces, e.g. "dom0 PCID-o= n". The entry would be writable and it would exist on X86 only and only if the hypervisor is configured to support PV guests. =20 +# Stability + +Path *presence* is not stable, but path *meaning* is always stable: if a t= ool +you write finds a path present, it can rely on behavior in future versions= of +the hypervisors, and in different configurations. Specifically: + +1. Conditions under which paths are used may be extended, restricted, or + removed. For example, a path that=E2=80=99s always available only on A= RM systems + may become available on x86; or a path available on both systems may be + restricted to only appearing on ARM systems. Paths may also disappear + entirely. +2. However, the meaning of a path will never change. If a path is present, + it will always have exactly the meaning that it always had. In order to + maintain this, removed paths should be retained with the tag [REMOVED]. + The path may be restored *only* if the restored version of the path is + compatible with the previous functionality. + ## Example =20 A populated Xen hypervisor file system might look like the following examp= le: --=20 2.26.2