From 5d76e09229d6f6a1a8611ae791c0cad7a920229a Mon Sep 17 00:00:00 2001
From: mulhern <amulhern@redhat.com>
Date: Thu, 30 Nov 2023 19:51:32 -0500
Subject: [PATCH] Update introspection docs for r6

blockdev.xml: no changes between r5 and r6
filesystem.xml: SizeLimit property added
pool.xml: CreateFilesystems spec now includes size limit
manager.xml: manager.StopPool takes id and id_type arguments

Signed-off-by: mulhern <amulhern@redhat.com>
---
 docs/dbus/blockdev.xml   |  45 ++++++++
 docs/dbus/filesystem.xml |  38 +++++++
 docs/dbus/manager.xml    | 177 +++++++++++++++++++++++++++++
 docs/dbus/pool.xml       | 232 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 492 insertions(+)

diff --git a/docs/dbus/blockdev.xml b/docs/dbus/blockdev.xml
index bff3ded..571f544 100644
--- a/docs/dbus/blockdev.xml
+++ b/docs/dbus/blockdev.xml
@@ -323,4 +323,49 @@
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
     </property>
   </interface>
+  <interface name="org.storage.stratis3.blockdev.r6">
+    <!-- Device node of the block device. -->
+    <property name="Devnode" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!-- Optional hardware id for this block device. -->
+    <property name="HardwareInfo" type="(bs)" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!-- Time that stratisd initialized the block device. -->
+    <property name="InitializationTime" type="t" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!--
+      Size of the block device's devnode, if different from the size recorded
+      in the Stratis metadata.
+    -->
+    <property name="NewPhysicalSize" type="(bs)" access="read" />
+    <!--
+      Physical path of the block device. This may be different from the device
+      represented by the Devnode property. For example, with encryption, the
+      PhysicalPath property is the device on which the Stratis LUKS metadata
+      is written; the Devnode property is the opened device on which the
+      Stratis metadata is written.
+    -->
+    <property name="PhysicalPath" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!-- Object path of the parent pool. -->
+    <property name="Pool" type="o" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!-- Tier the block device occupies, either Data(0) or Cache(1). -->
+    <property name="Tier" type="q" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="false" />
+    </property>
+    <!-- Size of the block device's Devnode. -->
+    <property name="TotalPhysicalSize" type="s" access="read" />
+    <!-- Optional user-defined string associated with this block device. -->
+    <property name="UserInfo" type="(bs)" access="readwrite" />
+    <!-- Stratis UUID of this block device. -->
+    <property name="Uuid" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+  </interface>
 </node>
diff --git a/docs/dbus/filesystem.xml b/docs/dbus/filesystem.xml
index 44cb63f..b1df661 100644
--- a/docs/dbus/filesystem.xml
+++ b/docs/dbus/filesystem.xml
@@ -242,4 +242,42 @@
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
     </property>
   </interface>
+  <interface name="org.storage.stratis3.filesystem.r6">
+    <!-- Set the filesystem name. -->
+    <method name="SetName">
+      <!-- The new name of the filesystem. -->
+      <arg name="name" type="s" direction="in" />
+      <!--
+        b: True if the name was changed, otherwise false.
+        s: UUID of the filesystem or a default UUID if no change was made.
+      -->
+      <arg name="result" type="(bs)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Time the filesystem was created. -->
+    <property name="Created" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!-- Filesystem device node. -->
+    <property name="Devnode" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="invalidates" />
+    </property>
+    <!-- Name of the filesystem. -->
+    <property name="Name" type="s" access="read" />
+    <!-- Object path of the parent pool. -->
+    <property name="Pool" type="o" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!-- Logical size of the filesystem. -->
+    <property name="Size" type="s" access="read" />
+    <!-- Logical size limit of the filesystem. -->
+    <property name="SizeLimit" type="(bs)" access="readwrite" />
+    <!-- Filesystem usage. -->
+    <property name="Used" type="(bs)" access="read" />
+    <!-- Filesystem UUID. -->
+    <property name="Uuid" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+  </interface>
 </node>
diff --git a/docs/dbus/manager.xml b/docs/dbus/manager.xml
index 1c8b6eb..b92850b 100644
--- a/docs/dbus/manager.xml
+++ b/docs/dbus/manager.xml
@@ -893,6 +893,169 @@
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
     </property>
   </interface>
+  <interface name="org.storage.stratis3.Manager.r6">
+    <!-- Create a single pool with the specified name and blockdevs. -->
+    <method name="CreatePool">
+      <!-- Name of the pool. -->
+      <arg name="name" type="s" direction="in" />
+      <!-- Device nodes of devices to form the pool -->
+      <arg name="devices" type="as" direction="in" />
+      <!-- Optional key description of the key to use to encrypt the pool -->
+      <arg name="key_desc" type="(bs)" direction="in" />
+      <!--
+         Optional Clevis information to use to encrypt the pool.
+         s: Clevis "pin" specification, "tang" or "tpm".
+         s: pin-specfic Clevis configuration
+      -->
+      <arg name="clevis_info" type="(b(ss))" direction="in" />
+      <!--
+         b: True if a pool was created, otherwise false.
+         (oao): Result of the creation action, default values if no pool
+            was created.
+            o: Object path of the created pool.
+            ao: Object paths of all the block devices in the pool.
+      -->
+      <arg name="result" type="(b(oao))" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Destroy the specified pool. -->
+    <method name="DestroyPool">
+      <!-- Object path of the pool to destroy. -->
+      <arg name="pool" type="o" direction="in" />
+      <!--
+        b: True if the pool was destroyed, otherwise false.
+        s: UUID of the pool destroyed or a default value if no action was
+           taken.
+      -->
+      <arg name="result" type="(bs)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!--
+      Return JSON representing the internal state of the daemon. The method
+      signature is stable, but the JSON output format is not guaranteed to be
+      stable.
+    -->
+    <method name="EngineStateReport">
+      <!-- JSON output representing the engine state. -->
+      <arg name="result" type="s" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Return a list of the Stratis keys in the kernel keyring. -->
+    <method name="ListKeys">
+      <!-- Array of key descriptions. -->
+      <arg name="result" type="as" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!--
+      Refresh the state of every running pool instance.
+      This method is for troubleshooting and debugging only.
+    -->
+    <method name="RefreshState">
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Set a Stratis key in the kernel keyring. -->
+    <method name="SetKey">
+      <!-- Key description to assign to the set key. -->
+      <arg name="key_desc" type="s" direction="in" />
+      <!-- File descriptor through which to read the key data. -->
+      <arg name="key_fd" type="h" direction="in" />
+      <!--
+        b: True if the key state was changed, otherwise false.
+        b: True if the key was newly set in the keyring. False if a key with the
+           given key description already existed.
+      -->
+      <arg name="result" type="(bb)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Start a pool. -->
+    <method name="StartPool">
+      <!-- identifier of pool to be started -->
+      <arg name="id" type="s" direction="in" />
+      <!-- id type: "uuid" or "name" -->
+      <arg name="id_type" type="s" direction="in" />
+      <!-- Unlock method to use if pool is encrypted
+        b: True if an unlock method argument is being specified.
+        s: Method to use to unlock the pool, may be "keyring" or "clevis".
+      -->
+      <arg name="unlock_method" type="(bs)" direction="in" />
+      <!--
+        b: True if the pool was started, otherwise false.
+        o: Object path of the started pool.
+        ao: Array of object paths of block devices belonging to the pool.
+        ao: Array of object paths of filesystems belonging to the pool.
+      -->
+      <arg name="result" type="(b(oaoao))" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Stop a running pool. -->
+    <method name="StopPool">
+      <!-- identifier of pool to be stopped -->
+      <arg name="id" type="s" direction="in" />
+      <!-- id type: "uuid" or "name" -->
+      <arg name="id_type" type="s" direction="in" />
+      <!-- Object path of pool to be stopped. -->
+      <arg name="pool" type="o" direction="in" />
+      <!--
+        b: True if the pool was stopped.
+        s: UUID of the stopped pool.
+      -->
+      <arg name="result" type="(bs)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Unset a key in the kernel keyring. -->
+    <method name="UnsetKey">
+      <!-- Key description of the key to unset. -->
+      <arg name="key_desc" type="s" direction="in" />
+      <!-- b: True if the key was in the keyring, otherwise false. -->
+      <arg name="result" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!--
+      a{sa{sv}}: Mapping of Stratis pool UUIDs to information about the
+	devices associated with the UUID. These sets of devices may comprise
+        a Stratis pool that can be started with the StartPool message.
+        s: Stratis pool UUIDs
+	    a{sv}: key/value mapping
+          s: keys: possible values are "devs", "key_description", "clevis_info"
+          v: Values for the keys:
+	    "devs": always present, an array of mappings of device information
+	      Contains two keys: "uuid" and "devnode"
+	    "clevis_info": optional, not present if pool is unencrypted.
+	      (bv): information about Clevis configuration for all devices
+	        if b is true:
+	          devices have consistent Clevis information
+	          v = (bs): Clevis configuration information for all devices
+	            b: if false, devices are not encrypted with Clevis
+	            s: Clevis configuration
+	        else:
+	          devices have inconsistent Clevis configurations
+	          v = s: error message explaining inconsistency
+	    "key_description": optional, not present if pool is unencrypted.
+	      (bv): information about kernel key encryption for all devices
+	        if b is true:
+	          devices have consistent key information
+	          v = (bs): key information for all devices
+	            b: if false, devices are not encrypted with a key
+	            s: key description
+	        else:
+	          devices have inconsistent key information
+	          v = s: error message explaining inconsistency
+    -->
+    <property name="StoppedPools" type="a{sa{sv}}" access="read" />
+    <!-- stratisd version -->
+    <property name="Version" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+  </interface>
   <!--
     The Report interface is an unstable interface for querying internal stratisd
     data structure state. It provides reports as JSON, and while the reports can
@@ -984,6 +1147,20 @@
       <arg name="return_string" type="s" direction="out" />
     </method>
   </interface>
+  <interface name="org.storage.stratis3.Report.r6">
+    <!--
+      This method allows fetching a report by name. If a report by the supplied
+      name does not exist, an error is returned.
+    -->
+    <method name="GetReport">
+      <!-- Name of the report. -->
+      <arg name="name" type="s" direction="in" />
+      <!-- s: Report. -->
+      <arg name="result" type="s" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+  </interface>
   <node name="0" />
   <node name="1" />
   <node name="2" />
diff --git a/docs/dbus/pool.xml b/docs/dbus/pool.xml
index 641b01b..4f64b92 100644
--- a/docs/dbus/pool.xml
+++ b/docs/dbus/pool.xml
@@ -1364,4 +1364,236 @@
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
     </property>
   </interface>
+  <interface name="org.storage.stratis3.pool.r6">
+    <!-- Add devices to an already initialized cache. -->
+    <method name="AddCacheDevs">
+      <!-- List of devices to add to the cache. -->
+      <arg name="devices" type="as" direction="in" />
+      <!--
+        b: True if devices were added, otherwise false.
+        ao: Object paths of the newly added devices, may be empty.
+      -->
+      <arg name="results" type="(bao)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Add devices to the pool. -->
+    <method name="AddDataDevs">
+      <!-- List of devices to add. -->
+      <arg name="devices" type="as" direction="in" />
+      <!--
+        b: True if devices were added, otherwise false.
+        ao: Object paths of the newly added devices, may be empty.
+      -->
+      <arg name="results" type="(bao)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Bind an already encrypted pool using Clevis. -->
+    <method name="BindClevis">
+      <!-- Clevis pin. -->
+      <arg name="pin" type="s" direction="in" />
+      <!-- Pin-specific Clevis configuration information. -->
+      <arg name="json" type="s" direction="in" />
+      <!-- True if any new bindings were added, otherwise false. -->
+      <arg name="results" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Bind an already encrypted pool using a key in the kernel keyring. -->
+    <method name="BindKeyring">
+      <!-- Description of the key in the kernel keyring. -->
+      <arg name="key_desc" type="s" direction="in" />
+      <!-- True if any new bindings were added, otherwise false. -->
+      <arg name="results" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Create filesystems for the pool. -->
+    <method name="CreateFilesystems">
+      <!--
+	 List of specifications for the filesystems.
+         a(s(bs)): List of names and optional size specification.
+           s: Name
+           bs: Optional size specification
+           bs: Optional size limit specification
+      -->
+      <arg name="specs" type="a(s(bs)(bs))" direction="in" />
+      <!--
+        b: True if any filesystem was added, otherwise false.
+        os: Object paths of newly added filesystems.
+      -->
+      <arg name="results" type="(ba(os))" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Destroy the specified filesystems. -->
+    <method name="DestroyFilesystems">
+      <!-- List of filesystem object paths to destroy. -->
+      <arg name="filesystems" type="ao" direction="in" />
+      <!--
+        b: True if any filesystems were destroyed, otherwise false.
+        as: UUIDs of destroyed filesystems.
+      -->
+      <arg name="results" type="(bas)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Extend the available size of a pool. -->
+    <method name="GrowPhysicalDevice">
+      <!-- UUID of data device belonging to pool to extend. -->
+      <arg name="dev" type="s" direction="in" />
+      <arg name="results" type="(bas)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Initialize a cache. -->
+    <method name="InitCache">
+      <!-- List of devices to initialize the cache with. -->
+      <arg name="devices" type="as" direction="in" />
+      <!--
+        b: True if the cache was initialized, otherwise false.
+        ao: Object paths of devices in the cache.
+      -->
+      <arg name="results" type="(bao)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!--
+      Regenerate Clevis bindings for devices in the pool using the existing
+      Clevis configuration.
+    -->
+    <method name="RebindClevis">
+      <!--
+        True if all bindings were successfully regenerated. Because of the
+        nature of Clevis rebinding generation, this method will always return
+        true on success.
+      -->
+      <arg name="results" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!--
+      Replace the existing key description with the specified one for devices
+      in the pool.
+    -->
+    <method name="RebindKeyring">
+      <!-- Key description. -->
+      <arg name="key_desc" type="s" direction="in" />
+      <!-- True if the specified key description is different. -->
+      <arg name="results" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Set the pool name. -->
+    <method name="SetName">
+      <!-- Name. -->
+      <arg name="name" type="s" direction="in" />
+      <!--
+        b: True if the name was changed, otherwise false.
+        s: UUID of the pool or a default UUID if no change was made.
+      -->
+      <arg name="result" type="(bs)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Make a snapshot of a Stratis filesystem. -->
+    <method name="SnapshotFilesystem">
+      <!-- Object path of the origin filesystem. -->
+      <arg name="origin" type="o" direction="in" />
+      <!-- Name of the snapshot to be created. -->
+      <arg name="snapshot_name" type="s" direction="in" />
+      <!--
+        b: True if a new filesystem was created, otherwise false.
+        o: Object path of the snapshot.
+      -->
+      <arg name="result" type="(bo)" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Remove Clevis encryption from the devices in the pool. -->
+    <method name="UnbindClevis">
+      <!-- True if some Clevis bindings were removed, otherwise false. -->
+      <arg name="results" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Unbind a keyring passphrase from the devices in the pool. -->
+    <method name="UnbindKeyring">
+      <!-- True if some bindings were removed, otherwise false. -->
+      <arg name="results" type="b" direction="out" />
+      <arg name="return_code" type="q" direction="out" />
+      <arg name="return_string" type="s" direction="out" />
+    </method>
+    <!-- Total space allocated from the pool. -->
+    <property name="AllocatedSize" type="s" access="read" />
+    <!--
+      Indicates the current capabilities of the pool. Generally the pool has
+      full capability, but under certain circumstances stratisd may restrict
+      the actions that the pool can perform.
+    -->
+    <property name="AvailableActions" type="s" access="read" />
+    <!--
+      b: True if the Clevis configuration information is consistent for all the
+         block devices in the pool, otherwise false.
+      b(ss): Clevis encryption configuration.
+         b: True if the pool is encrypted using Clevis.
+         ss: Clevis configuration.
+	   s: Clevis pin.
+	   s: Pin-specfic Clevis configuration information.
+    -->
+    <property name="ClevisInfo" type="(b(b(ss)))" access="read" />
+    <!-- True if the pool is encrypted, otherwise false. -->
+    <property name="Encrypted" type="b" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+    <!--
+      The maximum number of filesystems that the pool supports. May be
+      increased, but not decreased.
+    -->
+    <property name="FsLimit" type="t" access="readwrite" />
+    <!-- True if the pool has a cache, otherwise false. -->
+    <property name="HasCache" type="b" access="read" />
+    <!--
+      b: True if the key description information is the same for all the block
+         devices in the pool, otherwise false.
+      bs: Encryption information.
+         b: True if there is a key description for the devices in the pool,
+	    otherwise false.
+	 s: Key description.
+    -->
+    <property name="KeyDescription" type="(b(bs))" access="read" />
+    <!-- Name of the pool. -->
+    <property name="Name" type="s" access="read" />
+    <!--
+      If true, then all the space on the pool's devices has been allocated
+      to some part of its storage stack. No further allocation, as would be
+      necessary to do if increasing the number of filesystems that the pool
+      supports, is possible.
+    -->
+    <property name="NoAllocSpace" type="b" access="read" />
+    <!--
+      True if the pool allows overprovisioning, otherwise false. Setting this
+      property to false will fail if the sum of the logical sizes of the
+      filesystems that the pool contains is more than the physical space
+      available for them.
+    -->
+    <property name="Overprovisioning" type="b" access="readwrite" />
+    <!--
+      Total size of the pool. The sum of the sizes of all the block
+      devices in the pool's data tier.
+    -->
+    <property name="TotalPhysicalSize" type="s" access="read" />
+    <!--
+      Total space used in the pool. This includes space allocated by Stratis
+      for pool management and consequently unavailable for any other purpose,
+      as well as all space required by data written to every Stratis
+      filesystem on the pool.
+    -->
+    <property name="TotalPhysicalUsed" type="(bs)" access="read" />
+    <!-- Stratis UUID of the pool. -->
+    <property name="Uuid" type="s" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
+    </property>
+  </interface>
 </node>