[PATCH 1/2] erofs-utils: manpage: document missing options for mkfs.erofs

[PATCH 1/2] erofs-utils: manpage: document missing options for mkfs.erofs

[Yifan Zhao]

Signed-off-by: Yifan Zhao <zhaoyifan28@huawei.com>
---
 man/mkfs.erofs.1 | 267 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 248 insertions(+), 19 deletions(-)

diff --git a/man/mkfs.erofs.1 b/man/mkfs.erofs.1
index 4316214..695ae99 100644
--- a/man/mkfs.erofs.1
+++ b/man/mkfs.erofs.1
@@ -17,17 +17,21 @@ achieve high performance for embedded devices with limited memory since it has
 unnoticable memory overhead and page cache thrashing.
 .PP
 mkfs.erofs is used to create such EROFS filesystem \fIDESTINATION\fR image file
-from \fISOURCE\fR directory or tarball.
+from various \fISOURCE\fR, where \fISOURCE\fR can be:
+.RS
+.IP \(bu 2
+a local directory
+.IP \(bu 2
+a (zipped) tarball
+.IP \(bu 2
+an S3 bucket or a prefix within it
+.IP \(bu 2
+an OCI image reference
+.IP \(bu 2
+other EROFS image(s), see \fIREBUILD MODE\fR below
+.RE
 .SH OPTIONS
 .TP
-.BI "\-z " compression-algorithm \fR[\fP, # \fR][\fP: ... \fR]\fP
-Set a primary algorithm for data compression, which can be set with an
-optional compression level. Alternative algorithms could be specified
-and separated by colons.  See the output of
-.B mkfs.erofs \-\-help
-for a listing of the algorithms that \fBmkfs.erofs\fR is compiled with
-and what their respective level ranges are.
-.TP
 .BI "\-b " block-size
 Set the fundamental block size of the filesystem in bytes.  In other words,
 specify the smallest amount of data that can be accessed at a time.  The
@@ -40,9 +44,6 @@ This may cause the big pcluster feature to be enabled (Linux v5.13+).
 .BI "\-d " #
 Specify the level of debugging messages. The default is 2, which shows basic
 warning messages.
-.TP
-.BI "\-x " #
-Limit how many xattrs will be inlined. The default is 2.
 Disables storing xattrs if < 0.
 .TP
 .BI "\-E " [^]extended-option \fR[\fP, ... \fR]\fP
@@ -52,6 +53,9 @@ feature, usually prefix the extended option name with a caret ('^') character.
 The following extended options are supported:
 .RS 1.2i
 .TP
+.BI 48bit
+Enable 48-bit block addressing to support larger block addresses. (Linux v6.15+)
+.TP
 .BI all-fragments
 Forcely record the whole files into a special inode for better compression and
 it may take an argument as the pcluster size of the packed inode in bytes.
@@ -63,6 +67,10 @@ the filesystem. May further reduce image size when used with
 .BR -E\ fragments .
 (Linux v6.1+)
 .TP
+.BI dot-omitted
+Omit the "." (dot) directory entry in all directories to reduce metadata
+overhead.
+.TP
 .BI force-inode-compact
 Force generation of compact (32-byte) inodes.
 .TP
@@ -102,6 +110,15 @@ for those images, however, there could be other use cases too.
 Disable "inplace decompression" and "compacted indexes",
 for compatibility with Linux pre-v5.4.
 .TP
+.BI nosbcrc
+Disable CRC32 checksum for the filesystem superblock.
+.TP
+.BI plain-xattr-prefixes
+Store long extended attribute name prefixes directly on disk rather than in
+special inodes. By default, long xattr name prefixes are placed in metabox_inode
+(if metabox is enabled) or packed_inode (if fragments is enabled). This option
+forces them to be stored as plain on-disk structures.
+.TP
 .B xattr-name-filter
 Enable a name filter for extended attributes to optimize negative lookups.
 (Linux v6.6+).
@@ -111,11 +128,18 @@ Pack the tail part (pcluster) of compressed files into its metadata to save
 more space and the tail part I/O. (Linux v5.17+)
 .RE
 .TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help string and exit.
+.TP
 .BI "\-L " volume-label
 Set the volume label for the filesystem to
 .IR volume-label .
 The maximum length of the volume label is 15 bytes.
 .TP
+.BI "\-m " #\fR[\fP: algorithm \fR]\fP
+Enable metadata compression with #-byte clusters in a metabox inode (Linux v6.17+);
+optionally specify an algorithm (defaults to data compression algorithm if omitted).
+.TP
 .BI "\-T " #
 Specify a UNIX timestamp for image creation time for reproducible builds.
 If \fI--mkfs-time\fR is not specified, it will behave as \fI--all-time\fR:
@@ -139,6 +163,20 @@ clear the file system UUID
 generate a new randomly-generated UUID
 .RE
 .TP
+\fB\-V\fR, \fB\-\-version\fR
+Print the version number and exit.
+.TP
+.BI "\-x " #
+Limit how many xattrs will be inlined. The default is 2.
+.TP
+.BI "\-z " compression-algorithm \fR[\fP, # \fR][\fP: ... \fR]\fP
+Set a primary algorithm for data compression, which can be set with an
+optional compression level. Alternative algorithms could be specified
+and separated by colons.  See the output of
+.B mkfs.erofs \-\-help
+for a listing of the algorithms that \fBmkfs.erofs\fR is compiled with
+and what their respective level ranges are.
+.TP
 .B \-\-all-root
 Make all files owned by root.
 .TP
@@ -146,12 +184,55 @@ Make all files owned by root.
 (used together with \fB-T\fR) set all files to the fixed timestamp. This is the
 default.
 .TP
+.BI "\-\-async-queue-limit=" #
+Specify the maximum number of entries in the multi-threaded job queue.
+.TP
+.BI "\-\-aufs"
+Replace aufs special files with overlayfs metadata.
+.TP
 .BI "\-\-blobdev " file
 Specify an extra blob device to store chunk-based data.
 .TP
 .BI "\-\-chunksize " #
 Generate chunk-based files with #-byte chunks.
 .TP
+.BI "\-\-clean=" MODE
+Run full clean build with the given \fIMODE\fR, which could be one of \fBdata\fR, \fBrvsp\fR, or \fB0\fR.
+
+If \fB\-\-clean\fR is specified without an explicit value, it is treated as
+\fB\-\-clean=data\fR.
+
+\fBdata\fR: Import complete file data from the source into the destination
+image, creating a fully self-contained EROFS image. This mode is useful when
+you need a standalone image that doesn't depend on external blob devices.
+
+\fBrvsp\fR: Reserve space for file data in the destination image without
+copying the actual content. The file data will need to be filled in later
+through other means. This is useful for creating sparse images or when the
+actual data will be populated separately.
+
+\fB0\fR:Fill all inode data with zeros.
+
+Source-specific support for \fIMODE\fR:
+.RS 1.2i
+.TP
+.I Local directory source
+Only \fBdata\fR is supported. \fBrvsp\fR and \fB0\fR will be ignored.
+.TP
+.I Tar source (\fB\-\-tar\fR)
+\fBdata\fR and \fBrvsp\fR are supported. \fB0\fR will be ignored.
+Note that \fBrvsp\fR takes precedence over \fB--tar=i\fR or \fB--tar=headerball\fR.
+.TP
+.I Rebuild mode
+Only \fBrvsp\fR is supported.
+.TP
+.I S3 source (\fB\-\-s3\fR)
+\fBdata\fR and \fB0\fR are supported.
+.TP
+.I OCI source (\fB\-\-oci\fR)
+Only \fBdata\fR is supported.
+.RE
+.TP
 .BI "\-\-compress-hints " file
 Apply a per-file compression strategy. Each line in
 .I file
@@ -159,9 +240,11 @@ is defined by
 tokens separated by spaces in the following form.  Optionally, instead of
 the given primary algorithm, alternative algorithms can be specified with
 \fIalgorithm-index\fR explicitly:
-.RS 1.2i
+.sp
+.in +4n
 <pcluster-size-in-bytes> [algorithm-index] <match-pattern>
-.RE
+.in
+.sp
 .IR match-pattern s
 are extended regular expressions, matched against absolute paths within
 the output filesystem, with no leading /.
@@ -216,11 +299,12 @@ When this option is used together with
 the final file gids are
 set to \fIGID\fR + \fIGID-OFFSET\fR.
 .TP
-\fB\-V\fR, \fB\-\-version\fR
-Print the version number and exit.
+.BI "\-\-gzinfo\fR[\fP=" file \fR]\fP
+(used together with \fI--tar\fR) Generate AWS SOCI-compatible zinfo to support random gzip access.
+Source file must be a gzip-compressed tarball.
 .TP
-\fB\-h\fR, \fB\-\-help\fR
-Display help string and exit.
+.BI "\-\-hard-dereference"
+Dereference hardlinks and add links as separate inodes.
 .TP
 .B "\-\-ignore-mtime"
 Ignore the file modification time whenever it would cause \fBmkfs.erofs\fR to
@@ -228,6 +312,29 @@ use extended inodes over compact inodes. When not using a fixed timestamp, this
 can reduce total metadata size. Implied by
 .BR "-E force-inode-compact" .
 .TP
+.BI "\-\-incremental=" MODE
+Run an incremental build where DESTINATION is an existing EROFS image,
+and the data specified by SOURCE will be incrementally appended to the image.
+\fIMODE\fR has the same meaning as in \fB\-\-clean\fR above.
+Incremental build is unsupported for \fB\-\-s3\fR and \fB\-\-oci\fR sources.
+
+If \fB\-\-incremental\fR is specified without an explicit value, it is treated
+as \fB\-\-incremental=data\fR.
+
+Source-specific support for \fIMODE\fR:
+.RS 1.2i
+.TP
+.I Local directory source
+Only \fBdata\fR is supported. \fBrvsp\fR and \fB0\fR will be ignored.
+.TP
+.I Tar source (\fB\-\-tar\fR)
+\fBdata\fR and \fBrvsp\fR are supported. \fB0\fR will be ignored.
+Note that \fBrvsp\fR takes precedence over \fB--tar=i\fR or \fB--tar=headerball\fR.
+.TP
+.I Rebuild mode
+Only \fBrvsp\fR is supported.
+.RE
+.TP
 .BI "\-\-max-extent-bytes " #
 Specify maximum decompressed extent size in bytes.
 .TP
@@ -235,14 +342,73 @@ Specify maximum decompressed extent size in bytes.
 (used together with \fB-T\fR) the given timestamp is only applied to the build
 time.
 .TP
+.BI "\-\-mount-point=" path
+Specify the prefix of target filesystem path (default: /).
+.TP
+.BI "\-\-MZ\fR[\fP=<0|[id]>\fR]\fP"
+Put inode metadata ('i') and/or directory data ('d') into the separate metadata zone.
+This improves spatial locality of metadata layout within the image, which is beneficial
+for on-demand metadata access.
+.TP
+.BI "\-\-oci\fR[\fP=<f|i>\fR]\fP"
+Generate a full (f) or index-only (i) image from OCI remote source.
+Additional options can be specified:
+.RS 1.2i
+.TP
+.BI platform= platform
+Specify the platform (default: linux/amd64).
+.TP
+.BI layer= #
+Specify the layer index to extract (0-based; omit to extract all layers).
+.TP
+.BI blob= digest
+Specify the blob digest to extract (omit to extract all layers).
+.TP
+.BI username= username
+Username for authentication (optional).
+.TP
+.BI password= password
+Password for authentication (optional).
+.TP
+.B insecure
+Use HTTP instead of HTTPS (optional).
+.RE
+.TP
+.BI "\-\-offset=" #
+Skip # bytes at the beginning of the image.
+.TP
+.BI "\-\-ovlfs-strip\fR[\fP=<0|1>\fR]\fP"
+Strip overlayfs metadata in the target image (e.g. whiteouts).
+.TP
 .B "\-\-preserve-mtime"
-Use extended inodes instead of compact inodes if the file modification time
+Use extended inodes instead of compact inodes if the file modifi1cation time
 would overflow compact inodes. This is the default. Overrides
 .BR --ignore-mtime .
 .TP
 .B "\-\-quiet"
 Quiet execution (do not write anything to standard output.)
 .TP
+.BI "\-\-root-xattr-isize=" #
+Ensure the inline xattr size of the root directory is # bytes at least.
+.TP
+.BI "\-\-s3=" endpoint
+Generate an image from S3-compatible object store.
+Additional options can be specified:
+.RS 1.2i
+.TP
+.BI passwd_file= file
+S3FS-compatible password file, with the format of "accessKey:secretKey" in the first line.
+.TP
+.BI urlstyle= style
+S3 API calling style (vhost or path) (default: vhost).
+.TP
+.BI sig= version
+S3 API signature version (2 or 4) (default: 2).
+.TP
+.BI region= code
+Region code in which endpoint belongs to (required for sig=4).
+.RE
+.TP
 .BI "\-\-sort=" MODE
 Inode data sorting order for tarballs as input.
 
@@ -290,11 +456,74 @@ be dumped together.
 Generate a VMDK descriptor file to merge sub-filesystems, which can be used
 for tar index or rebuild mode.
 .TP
+.BI "\-\-workers=" #
+Set the number of worker threads to # (default: 12).
+.TP
+.BI "\-\-xattr-inode-digest=" name
+Specify extended attribute name to record inode digests.
+.TP
 .BI "\-\-xattr-prefix=" PREFIX
 Specify a customized extended attribute namespace prefix for space saving,
 e.g. "trusted.overlay.".  You may give multiple
 .B --xattr-prefix
 options (Linux v6.4+).
+.TP
+.BI "\-\-zD\fR[\fP=<0|1>\fR]\fP"
+Specify directory compression: 0=disable [default], 1=enable.
+.TP
+.BI "\-\-zfeature-bits=" #
+Toggle filesystem compression features according to given bits #.
+Each bit in the value corresponds to a specific compression feature:
+.RS 1.2i
+.nf
+.ft CW
+  7 6 5 4 3 2 1 0  (bit position)
+  | | | | | | | |
+  | | | | | | | +-- Bit 0 (1)   : legacy-compress
+  | | | | | | +---- Bit 1 (2)   : ztailpacking
+  | | | | | +------ Bit 2 (4)   : fragments
+  | | | | +-------- Bit 3 (8)   : all-fragments
+  | | | +---------- Bit 4 (16)  : dedupe
+  | | +------------ Bit 5 (32)  : fragdedupe
+  | +-------------- Bit 6 (64)  : 48bit
+  +---------------- Bit 7 (128) : dot-omitted
+.ft
+.fi
+.RE
+.IP
+For example,
+.B --zfeature-bits=6
+(binary: 0000 0110) enables ztailpacking (bit 1) and fragments (bit 2).
+.TP
+.B REBUILD MODE
+.B Rebuild mode
+is an experimental feature that allows
+.B mkfs.erofs
+to generate a new EROFS image from one or more existing EROFS images passed as
+\fISOURCE\fR(s).
+This mode is particularly useful for merging multiple EROFS images or creating
+index-only metadata images that reference data in the source images.
+
+When SOURCE contains one or more EROFS image files,
+.B mkfs.erofs
+automatically enters rebuild mode. The behavior is controlled by the
+.B \-\-clean
+or
+.B \-\-incremental
+options, which determine how file data is handled:
+.RS 1.2i
+.TP
+.I Default mode (blob index)
+The generated image contains only metadata (inodes, dentries, and xattrs).
+File data is referenced through chunk-based indexes pointing to the original
+source images, which act as external blob devices. This creates a compact
+metadata layer suitable for layered filesystem scenarios, similar to container
+image layers.
+.TP
+.I rvsp mode
+\fB\-\-clean=rvsp\fR or \fB\-\-incremental=rvsp\fR: Reserve space for file
+data without copying actual content, useful for creating sparse images.
+.RE
 .SH AUTHOR
 This version of \fBmkfs.erofs\fR is written by Li Guifu <blucerlee@gmail.com>,
 Miao Xie <miaoxie@huawei.com> and Gao Xiang <xiang@kernel.org> with
-- 
2.47.3

[PATCH 2/2] erofs-utils: mkfs: validate source and dataimport mode combinations

[Yifan Zhao]

This patch adds validation for all combinations of source mode and
dataimport mode, and prints corresponding error/warning messages.
It should have no impact on external behavior.

Signed-off-by: Yifan Zhao <zhaoyifan28@huawei.com>
---
 mkfs/main.c | 144 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 131 insertions(+), 13 deletions(-)

diff --git a/mkfs/main.c b/mkfs/main.c
index a948b2e..e369347 100644
--- a/mkfs/main.c
+++ b/mkfs/main.c
@@ -169,7 +169,7 @@ static void usage(int argc, char **argv)
 	}
 	printf(
 		" -C#                    specify the size of compress physical cluster in bytes\n"
-		" -EX[,...]              X=extended options\n"
+		" -EX[,...]              X=extended options, see mkfs.erofs(1) manual for details\n"
 		" -L volume-label        set the volume label (maximum 15 bytes)\n"
 		" -m#[:X]                enable metadata compression (# = physical cluster size in bytes;\n"
 		"                                                     X = another compression algorithm for metadata)\n"
@@ -300,6 +300,10 @@ static struct ocierofs_config ocicfg;
 static bool mkfs_oci_tarindex_mode;
 
 enum {
+	/* XXX: the "DEFAULT" mode is actually source-dependent,
+	 * meaning BLOB_INDEX for rebuild mode and FULLDATA for others.
+	 * Consider refactoring this...
+	 */
 	EROFS_MKFS_DATA_IMPORT_DEFAULT,
 	EROFS_MKFS_DATA_IMPORT_FULLDATA,
 	EROFS_MKFS_DATA_IMPORT_RVSP,
@@ -314,6 +318,118 @@ static enum {
 	EROFS_MKFS_SOURCE_REBUILD,
 } source_mode;
 
+static int erofs_mkfs_validate_source_datamode(void)
+{
+	int status;
+	enum {
+		EROFS_MKFS_CLEAN_MODE = 0,
+		EROFS_MKFS_INCREMENTAL_MODE = 1
+	};
+	const char *SOURCE_NAME[] = {
+		[EROFS_MKFS_SOURCE_LOCALDIR] = "localdir source",
+		[EROFS_MKFS_SOURCE_TAR] = "tarball source",
+		[EROFS_MKFS_SOURCE_S3] = "S3-compatible object store source",
+		[EROFS_MKFS_SOURCE_OCI] = "OCI remote source",
+		[EROFS_MKFS_SOURCE_REBUILD] = "rebuilding from existing EROFS image(s)",
+	};
+	const char *DATAIMPORT_NAME[] = {
+		[EROFS_MKFS_DATA_IMPORT_DEFAULT] = "default", // placeholder
+		[EROFS_MKFS_DATA_IMPORT_FULLDATA] = "data",
+		[EROFS_MKFS_DATA_IMPORT_RVSP] = "rvsp",
+		[EROFS_MKFS_DATA_IMPORT_ZEROFILL] = "0",
+	};
+	enum {
+		INVALID = 0, // INVALID must be 0 for static initialization
+		NOP = 1,
+		SUPPORTED = 2,
+	};
+	static const int support[EROFS_MKFS_SOURCE_REBUILD + 1][EROFS_MKFS_INCREMENTAL_MODE + 1][EROFS_MKFS_DATA_IMPORT_ZEROFILL + 1] = {
+		[EROFS_MKFS_SOURCE_LOCALDIR] = {
+			[EROFS_MKFS_CLEAN_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_RVSP] = NOP,
+				[EROFS_MKFS_DATA_IMPORT_ZEROFILL] = NOP
+			},
+			[EROFS_MKFS_INCREMENTAL_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_RVSP] = NOP,
+				[EROFS_MKFS_DATA_IMPORT_ZEROFILL] = NOP
+			},
+		},
+		[EROFS_MKFS_SOURCE_TAR] = {
+			[EROFS_MKFS_CLEAN_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_RVSP] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_ZEROFILL] = NOP
+			},
+			[EROFS_MKFS_INCREMENTAL_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_RVSP] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_ZEROFILL] = NOP
+			},
+		},
+		[EROFS_MKFS_SOURCE_S3] = {
+			[EROFS_MKFS_CLEAN_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_ZEROFILL] = SUPPORTED,
+			},
+		},
+		[EROFS_MKFS_SOURCE_OCI] = {
+			[EROFS_MKFS_CLEAN_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED
+			},
+		},
+		[EROFS_MKFS_SOURCE_REBUILD] = {
+			[EROFS_MKFS_CLEAN_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_DEFAULT] = SUPPORTED,
+				/* XXX: FULLDATA rebuild mode doesn't work actually, let's keep
+				 * its behavior until v1.9 is released to avoid breaking anyone who
+				 * might rely on it...
+				 */
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_RVSP] = SUPPORTED,
+			},
+			[EROFS_MKFS_INCREMENTAL_MODE] = {
+				[EROFS_MKFS_DATA_IMPORT_DEFAULT] = SUPPORTED,
+				/* XXX: FULLDATA rebuild mode doesn't work actually, let's keep
+				 * its behavior until v1.9 is released to avoid breaking anyone who
+				 * might rely on it...
+				 */
+				[EROFS_MKFS_DATA_IMPORT_FULLDATA] = SUPPORTED,
+				[EROFS_MKFS_DATA_IMPORT_RVSP] = SUPPORTED,
+			},
+		},
+	};
+	int real_dataimport_mode = dataimport_mode;
+	if (real_dataimport_mode == EROFS_MKFS_DATA_IMPORT_DEFAULT)
+		real_dataimport_mode = (source_mode == EROFS_MKFS_SOURCE_REBUILD) ?
+			EROFS_MKFS_DATA_IMPORT_DEFAULT : EROFS_MKFS_DATA_IMPORT_FULLDATA;
+
+	if (source_mode < 0 || source_mode > EROFS_MKFS_SOURCE_REBUILD)
+		return -EINVAL;
+
+	if (real_dataimport_mode < EROFS_MKFS_DATA_IMPORT_DEFAULT ||
+	    real_dataimport_mode > EROFS_MKFS_DATA_IMPORT_ZEROFILL)
+		return -EINVAL;
+
+	status = support[source_mode][incremental_mode ? EROFS_MKFS_INCREMENTAL_MODE : EROFS_MKFS_CLEAN_MODE][real_dataimport_mode];
+	if (status == SUPPORTED) {
+		return 0;
+	} else if (status == NOP) {
+		erofs_warn("datamode '%s' under %s mode is a no-op for %s.",
+			   DATAIMPORT_NAME[real_dataimport_mode],
+			   incremental_mode ? "incremental" : "clean",
+			   SOURCE_NAME[source_mode]);
+		return 0;
+	} else {
+		erofs_err("datamode '%s' under %s mode is not supported for %s.",
+			  DATAIMPORT_NAME[real_dataimport_mode],
+			  incremental_mode ? "incremental" : "clean",
+			  SOURCE_NAME[source_mode]);
+		return -EOPNOTSUPP;
+	}
+}
+
 static unsigned int rebuild_src_count, total_ccfgs;
 static LIST_HEAD(rebuild_src_list);
 static u8 fixeduuid[16];
@@ -1570,6 +1686,10 @@ static int mkfs_parse_options_cfg(struct erofs_importer_params *params,
 
 	if (has_timestamp && cfg.c_timeinherit == TIMESTAMP_UNSPECIFIED)
 		cfg.c_timeinherit = TIMESTAMP_FIXED;
+
+	err = erofs_mkfs_validate_source_datamode();
+	if (err)
+		return err;
 	return 0;
 }
 
@@ -1631,11 +1751,16 @@ static int erofs_mkfs_rebuild_load_trees(struct erofs_inode *root)
 		datamode = EROFS_REBUILD_DATA_BLOB_INDEX;
 		break;
 	case EROFS_MKFS_DATA_IMPORT_FULLDATA:
+		/* XXX: fulldata rebuild is unsupported, but let's keep this behavior
+		 * in case anyone relies on it until v1.9 is released...
+		 */
 		datamode = EROFS_REBUILD_DATA_FULL;
 		break;
 	case EROFS_MKFS_DATA_IMPORT_RVSP:
 		datamode = EROFS_REBUILD_DATA_RESVSP;
 		break;
+	case EROFS_MKFS_DATA_IMPORT_ZEROFILL:
+		return -EOPNOTSUPP;
 	default:
 		return -EINVAL;
 	}
@@ -1786,6 +1911,8 @@ int main(int argc, char **argv)
 	if (source_mode == EROFS_MKFS_SOURCE_TAR) {
 		if (dataimport_mode == EROFS_MKFS_DATA_IMPORT_RVSP)
 			erofstar.rvsp_mode = true;
+		if (erofstar.index_mode && erofstar.rvsp_mode)
+			erofs_warn("rvsp mode takes precedence and tar index mode is ignored");
 		erofstar.dev = rebuild_src_count + 1;
 
 		if (erofstar.mapfile) {
@@ -1950,12 +2077,8 @@ int main(int argc, char **argv)
 			s3cfg.secret_key[S3_SECRET_KEY_LEN] = '\0';
 		}
 
-		if (incremental_mode ||
-		    dataimport_mode == EROFS_MKFS_DATA_IMPORT_RVSP)
-			err = -EOPNOTSUPP;
-		else
-			err = s3erofs_build_trees(&importer, &s3cfg,
-						  cfg.c_src_path,
+		err = s3erofs_build_trees(&importer, &s3cfg,
+					  cfg.c_src_path,
 				dataimport_mode == EROFS_MKFS_DATA_IMPORT_ZEROFILL);
 #endif
 #ifdef OCIEROFS_ENABLED
@@ -1966,12 +2089,7 @@ int main(int argc, char **argv)
 			if (!ocicfg.zinfo_path)
 				ocicfg.zinfo_path = mkfs_aws_zinfo_file;
 
-			if (incremental_mode ||
-			    dataimport_mode == EROFS_MKFS_DATA_IMPORT_RVSP ||
-			    dataimport_mode == EROFS_MKFS_DATA_IMPORT_ZEROFILL)
-				err = -EOPNOTSUPP;
-			else
-				err = ocierofs_build_trees(&importer, &ocicfg);
+			err = ocierofs_build_trees(&importer, &ocicfg);
 			if (err)
 				goto exit;
 #endif
-- 
2.47.3

Re: [PATCH 2/2] erofs-utils: mkfs: validate source and dataimport mode combinations

[Gao Xiang]

Hi Yifan,

On Fri, Feb 13, 2026 at 03:32:41PM +0800, Yifan Zhao wrote:
> This patch adds validation for all combinations of source mode and
> dataimport mode, and prints corresponding error/warning messages.
> It should have no impact on external behavior.
> 
> Signed-off-by: Yifan Zhao <zhaoyifan28@huawei.com>
> ---
>  mkfs/main.c | 144 +++++++++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 131 insertions(+), 13 deletions(-)
> 
> diff --git a/mkfs/main.c b/mkfs/main.c
> index a948b2e..e369347 100644
> --- a/mkfs/main.c
> +++ b/mkfs/main.c
> @@ -169,7 +169,7 @@ static void usage(int argc, char **argv)
>  	}
>  	printf(
>  		" -C#                    specify the size of compress physical cluster in bytes\n"
> -		" -EX[,...]              X=extended options\n"
> +		" -EX[,...]              X=extended options, see mkfs.erofs(1) manual for details\n"
>  		" -L volume-label        set the volume label (maximum 15 bytes)\n"
>  		" -m#[:X]                enable metadata compression (# = physical cluster size in bytes;\n"
>  		"                                                     X = another compression algorithm for metadata)\n"
> @@ -300,6 +300,10 @@ static struct ocierofs_config ocicfg;
>  static bool mkfs_oci_tarindex_mode;
>  
>  enum {
> +	/* XXX: the "DEFAULT" mode is actually source-dependent,
> +	 * meaning BLOB_INDEX for rebuild mode and FULLDATA for others.
> +	 * Consider refactoring this...
> +	 */
>  	EROFS_MKFS_DATA_IMPORT_DEFAULT,
>  	EROFS_MKFS_DATA_IMPORT_FULLDATA,
>  	EROFS_MKFS_DATA_IMPORT_RVSP,
> @@ -314,6 +318,118 @@ static enum {
>  	EROFS_MKFS_SOURCE_REBUILD,
>  } source_mode;
>  
> +static int erofs_mkfs_validate_source_datamode(void)
> +{

Honestly, I don't like a unique place to deal with all arbitrary
combinations, but we could add test cases to test all valid
combinations.

Also I don't think I will treat this for the upcoming
erofs-utils since it may cause potential regression, let's address
this after erofs-utils 1.9 is out.

Thanks,
Gao Xiang

Re: [PATCH 1/2] erofs-utils: manpage: document missing options for mkfs.erofs

[Gao Xiang]

Hi Yifan,

On Fri, Feb 13, 2026 at 03:32:40PM +0800, Yifan Zhao wrote:
> Signed-off-by: Yifan Zhao <zhaoyifan28@huawei.com>
> ---

I rearrange this a bit and apply it to -experimental.

Thanks,
Gao Xiang