f2fs: add lookup_mode mount option
Subsystems (2)
PATCH v2 1/2 f2fs: add lookup_mode mount option
For casefolded directories, f2fs may fall back to a linear search if a hash-based lookup fails. This can cause severe performance regressions.
While this behavior can be controlled by userspace tools (e.g. mkfs, fsck) by setting an on-disk flag, a kernel-level solution is needed to guarantee the lookup behavior regardless of the on-disk state.
This commit introduces the 'lookup_mode' mount option to provide this kernel-side control.
The option accepts three values:
- perf: (Default) Enforces a hash-only lookup. The linear fallback is always disabled.
- compat: Enables the linear search fallback for compatibility with directory entries from older kernels.
- auto: Determines the mode based on the on-disk flag, preserving the userspace-based behavior.
---
v2:
- rework mount option parsing to use the new mount API.
- add lookup_mode field to struct f2fs_mount_info.
- add show_options support for the new option.
Documentation/filesystems/f2fs.rst | 19 +++++++++++++++++++ fs/f2fs/dir.c | 17 ++++++++++++++++- fs/f2fs/f2fs.h | 7 +++++++ fs/f2fs/super.c | 25 +++++++++++++++++++++++++ 4 files changed, 67 insertions(+), 1 deletion(-)
Documentation/filesystems/f2fs.rst +19 -0
@@ -370,6 +370,25 @@ errors=%s Specify f2fs behavior on critical errors. This supports modes: ====================== =============== =============== ======== nat_bits Enable nat_bits feature to enhance full/empty nat blocks access, by default it's disabled. +lookup_mode=%s Control the directory lookup behavior for casefolded + directories. This option has no effect on directories + that do not have the casefold feature enabled. + + ================== ======================================== + Value Description + ================== ======================================== + perf (Default) Enforces a hash-only lookup. + The linear search fallback is always + disabled, ignoring the on-disk flag. + compat Enables the linear search fallback for + compatibility with directory entries + created by older kernel that used a + different case-folding algorithm. + This mode ignores the on-disk flag. + auto F2FS determines the mode based on the + on-disk `SB_ENC_NO_COMPAT_FALLBACK_FL` + flag. + ================== ======================================== ======================== ============================================================ Debugfs Entries
fs/f2fs/dir.c +16 -1
@@ -16,6 +16,21 @@#include "xattr.h" #include <trace/events/f2fs.h> +static inline bool f2fs_should_fallback_to_linear (struct inode *dir) +{ +struct f2fs_sb_info *sbi =F2FS_I_SB (dir); + +switch (F2FS_OPTION (sbi).lookup_mode) { +case LOOKUP_PERF : +return false; +case LOOKUP_COMPAT : +return true; +case LOOKUP_AUTO : +return !sb_no_casefold_compat_fallback (sbi->sb); + } +return false; +} +#if IS_ENABLED (CONFIG_UNICODE )extern struct kmem_cache *f2fs_cf_name_slab;#endif
@@ -366,7 +381,7 @@ struct f2fs_dir_entry *__f2fs_find_entry(struct inode *dir, out:#if IS_ENABLED (CONFIG_UNICODE ) -if (!sb_no_casefold_compat_fallback (dir->i_sb) && +if (f2fs_should_fallback_to_linear (dir) &&IS_CASEFOLDED (dir) && !de && use_hash) { use_hash = false; goto start_find_entry;
fs/f2fs/f2fs.h +7 -0
@@ -212,6 +212,7 @@ struct f2fs_mount_info {int compress_mode;/* compression mode */ unsigned char extensions[COMPRESS_EXT_NUM ][F2FS_EXTENSION_LEN ];/* extensions */ unsigned char noextensions[COMPRESS_EXT_NUM ][F2FS_EXTENSION_LEN ];/* extensions */ +unsigned int lookup_mode; };#define F2FS_FEATURE_ENCRYPT 0x00000001
@@ -1448,6 +1449,12 @@ enum { TOTAL_CALL = FOREGROUND, }; +enum f2fs_lookup_mode { +LOOKUP_PERF , +LOOKUP_COMPAT , +LOOKUP_AUTO , +}; +static inline int f2fs_test_bit (unsigned int nr,char *addr);static inline void f2fs_set_bit (unsigned int nr,char *addr);static inline void f2fs_clear_bit (unsigned int nr,char *addr);
fs/f2fs/super.c +25 -0
@@ -181,6 +181,7 @@ enum { Opt_nat_bits, Opt_jqfmt, Opt_checkpoint, + Opt_lookup_mode, Opt_err, };
@@ -244,6 +245,13 @@ static const struct constant_table f2fs_param_errors[] = { {} }; +static const struct constant_table f2fs_param_lookup_mode[] = { + {"perf" ,LOOKUP_PERF }, + {"compat" ,LOOKUP_COMPAT }, + {"auto" ,LOOKUP_AUTO }, + {} +}; +static const struct fs_parameter_spec f2fs_param_specs[] = {fsparam_enum ("background_gc" , Opt_gc_background, f2fs_param_background_gc),fsparam_flag ("disable_roll_forward" , Opt_disable_roll_forward),
@@ -300,6 +308,7 @@ static const struct fs_parameter_spec f2fs_param_specs[] = {fsparam_enum ("memory" , Opt_memory_mode, f2fs_param_memory_mode),fsparam_flag ("age_extent_cache" , Opt_age_extent_cache),fsparam_enum ("errors" , Opt_errors, f2fs_param_errors), + fsparam_enum("lookup_mode", Opt_lookup_mode, f2fs_param_lookup_mode), {} };
@@ -336,6 +345,7 @@ static match_table_t f2fs_checkpoint_tokens = {#define F2FS_SPEC_discard_unit (1 << 21)#define F2FS_SPEC_memory_mode (1 << 22)#define F2FS_SPEC_errors (1 << 23) +#define F2FS_SPEC_lookup_mode (1 << 24)struct f2fs_fs_context {struct f2fs_mount_info info;
@@ -1143,6 +1153,10 @@ static int f2fs_parse_param(struct fs_context *fc, struct fs_parameter *param)case Opt_nat_bits:ctx_set_opt (ctx,F2FS_MOUNT_NAT_BITS );break ; +case Opt_lookup_mode: +F2FS_CTX_INFO (ctx).lookup_mode = result.uint_32; + ctx->spec_mask |= F2FS_SPEC_lookup_mode; +break ; }return 0 ; }
@@ -1652,6 +1666,8 @@ static void f2fs_apply_options(struct fs_context *fc, struct super_block *sb)F2FS_OPTION (sbi).memory_mode =F2FS_CTX_INFO (ctx).memory_mode;if (ctx->spec_mask & F2FS_SPEC_errors)F2FS_OPTION (sbi).errors =F2FS_CTX_INFO (ctx).errors; +if (ctx->spec_mask & F2FS_SPEC_lookup_mode) +F2FS_OPTION (sbi).lookup_mode =F2FS_CTX_INFO (ctx).lookup_mode;f2fs_apply_compression (fc, sb);f2fs_apply_test_dummy_encryption (fc, sb);
@@ -2416,6 +2432,13 @@ static int f2fs_show_options(struct seq_file *seq, struct dentry *root)if (test_opt (sbi,NAT_BITS ))seq_puts (seq,",nat_bits" ); +if (F2FS_OPTION (sbi).lookup_mode !=LOOKUP_PERF ) { +if (F2FS_OPTION (sbi).lookup_mode ==LOOKUP_COMPAT ) +seq_show_option (seq,"lookup_mode" ,"compat" ); +else if (F2FS_OPTION (sbi).lookup_mode ==LOOKUP_AUTO ) +seq_show_option (seq,"lookup_mode" ,"auto" ); + } +return 0 ; }
@@ -2480,6 +2503,8 @@ static void default_options(struct f2fs_sb_info *sbi, bool remount)#endif f2fs_build_fault_attr (sbi,0 ,0 ,FAULT_ALL ); + +F2FS_OPTION (sbi).lookup_mode =LOOKUP_PERF ; }#ifdef CONFIG_QUOTA
Signature · 1 line
2.50.1.565.gc32cd1483b-goog
PATCH v2 2/2 f2fs: add sysfs entry for effective lookup mode
This commit introduces a new read-only sysfs entry at /sys/fs/f2fs/<device>/effective_lookup_mode.
This entry displays the actual directory lookup mode F2FS is currently using. This is needed for debugging and verification, as the behavior is determined by both on-disk flags and mount options.
---
v2:
- show "auto:perf" or "auto:compat" when lookup_mode is 'auto'.
Documentation/ABI/testing/sysfs-fs-f2fs | 15 +++++++++++++++ fs/f2fs/sysfs.c | 18 ++++++++++++++++++ 2 files changed, 33 insertions(+)
Documentation/ABI/testing/sysfs-fs-f2fs +15 -0
@@ -883,3 +883,18 @@ Date: June 2025 Contact: "Daeho Jeong" <[email protected]> Description: Control GC algorithm for boost GC. 0: cost benefit, 1: greedy Default: 1 + +What: /sys/fs/f2fs/<disk>/effective_lookup_mode +Date: August 2025 +Contact: "Daniel Lee" <[email protected]> +Description: + This is a read-only entry to show the effective directory lookup mode + F2FS is currently using for casefolded directories. + This considers both the "lookup_mode" mount option and the on-disk + encoding flag, SB_ENC_NO_COMPAT_FALLBACK_FL. + + Possible values are: + - "perf": Hash-only lookup. + - "compat": Hash-based lookup with a linear search fallback enabled + - "auto:perf": lookup_mode is auto and fallback is disabled on-disk + - "auto:compat": lookup_mode is auto and fallback is enabled on-disk
fs/f2fs/sysfs.c +18 -0
@@ -281,6 +281,22 @@ static ssize_t encoding_flags_show(struct f2fs_attr *a, le16_to_cpu(F2FS_RAW_SUPER(sbi)->s_encoding_flags)); } +static ssize_t effective_lookup_mode_show (struct f2fs_attr *a, +struct f2fs_sb_info *sbi,char *buf) +{ +switch (F2FS_OPTION (sbi).lookup_mode) { +case LOOKUP_PERF : +return sysfs_emit (buf,"perf\n" ); +case LOOKUP_COMPAT : +return sysfs_emit (buf,"compat\n" ); +case LOOKUP_AUTO : +if (sb_no_casefold_compat_fallback (sbi->sb)) +return sysfs_emit (buf,"auto:perf\n" ); +return sysfs_emit (buf,"auto:compat\n" ); + } +return 0 ; +} +static ssize_t mounted_time_sec_show (struct f2fs_attr *a,struct f2fs_sb_info *sbi,char *buf) {
@@ -1211,6 +1227,7 @@ F2FS_GENERAL_RO_ATTR(current_reserved_blocks);F2FS_GENERAL_RO_ATTR (unusable);F2FS_GENERAL_RO_ATTR (encoding);F2FS_GENERAL_RO_ATTR (encoding_flags); +F2FS_GENERAL_RO_ATTR (effective_lookup_mode);F2FS_GENERAL_RO_ATTR (mounted_time_sec);F2FS_GENERAL_RO_ATTR (main_blkaddr);F2FS_GENERAL_RO_ATTR (pending_discard);
@@ -1329,6 +1346,7 @@ static struct attribute *f2fs_attrs[] = {ATTR_LIST (current_reserved_blocks),ATTR_LIST (encoding),ATTR_LIST (encoding_flags), +ATTR_LIST (effective_lookup_mode),ATTR_LIST (mounted_time_sec), #ifdef CONFIG_F2FS_STAT_FS ATTR_LIST(cp_foreground_calls),
Signature · 1 line
2.50.1.565.gc32cd1483b-goog
Chao Yu
maintainerQuoted 184 lines · Daniel Lee
For casefolded directories, f2fs may fall back to a linear search if a hash-based lookup fails. This can cause severe performance regressions.
While this behavior can be controlled by userspace tools (e.g. mkfs, fsck) by setting an on-disk flag, a kernel-level solution is needed to guarantee the lookup behavior regardless of the on-disk state.
This commit introduces the '
lookup_mode' mount option to provide this kernel-side control.The option accepts three values:
- perf: (Default) Enforces a hash-only lookup. The linear fallback is always disabled.
- compat: Enables the linear search fallback for compatibility with directory entries from older kernels.
- auto: Determines the mode based on the on-disk flag, preserving the userspace-based behavior.Signed-off-by Daniel Lee <[email protected]>---
v2:
- rework mount option parsing to use the new mount API.
- addlookup_modefield to structf2fs_mount_info.
- addshow_optionssupport for the new option.Documentation/filesystems/f2fs.rst | 19 +++++++++++++++++++ fs/f2fs/dir.c | 17 ++++++++++++++++- fs/f2fs/f2fs.h | 7 +++++++ fs/f2fs/super.c | 25 +++++++++++++++++++++++++ 4 files changed, 67 insertions(+), 1 deletion(-)Documentation/filesystems/f2fs.rst +19
-0@@ -370,6 +370,25 @@ errors=%s Specify f2fs behavior on critical errors. This supports modes: ====================== =============== =============== ======== nat_bits Enable nat_bits feature to enhance full/empty nat blocks access, by default it's disabled. +lookup_mode=%s Control the directory lookup behavior for casefolded + directories. This option has no effect on directories + that do not have the casefold feature enabled. + + ================== ======================================== + Value Description + ================== ======================================== + perf (Default) Enforces a hash-only lookup. + The linear search fallback is always + disabled, ignoring the on-disk flag. + compat Enables the linear search fallback for + compatibility with directory entries + created by older kernel that used a + different case-folding algorithm. + This mode ignores the on-disk flag. + auto F2FS determines the mode based on the + on-disk `SB_ENC_NO_COMPAT_FALLBACK_FL` + flag. + ================== ======================================== ======================== ============================================================ Debugfs Entriesfs/f2fs/dir.c +16
-1@@ -16,6 +16,21 @@#include "xattr.h" #include <trace/events/f2fs.h> +static inline bool f2fs_should_fallback_to_linear (struct inode *dir) +{ +struct f2fs_sb_info *sbi =F2FS_I_SB (dir); + +switch (F2FS_OPTION (sbi).lookup_mode) { +case LOOKUP_PERF : +return false; +case LOOKUP_COMPAT : +return true; +case LOOKUP_AUTO : +return !sb_no_casefold_compat_fallback (sbi->sb); + } +return false; +} +#if IS_ENABLED (CONFIG_UNICODE )extern struct kmem_cache *f2fs_cf_name_slab;#endif @@ -366,7 +381,7 @@ struct f2fs_dir_entry *__f2fs_find_entry(struct inode *dir, out:#if IS_ENABLED (CONFIG_UNICODE ) -if (!sb_no_casefold_compat_fallback (dir->i_sb) && +if (f2fs_should_fallback_to_linear (dir) &&IS_CASEFOLDED (dir) && !de && use_hash) { use_hash = false; goto start_find_entry;fs/f2fs/f2fs.h +7
-0@@ -212,6 +212,7 @@ struct f2fs_mount_info {int compress_mode;/* compression mode */ unsigned char extensions[COMPRESS_EXT_NUM ][F2FS_EXTENSION_LEN ];/* extensions */ unsigned char noextensions[COMPRESS_EXT_NUM ][F2FS_EXTENSION_LEN ];/* extensions */ +unsigned int lookup_mode; };#define F2FS_FEATURE_ENCRYPT 0x00000001@@ -1448,6 +1449,12 @@ enum { TOTAL_CALL = FOREGROUND, }; +enum f2fs_lookup_mode { +LOOKUP_PERF , +LOOKUP_COMPAT , +LOOKUP_AUTO , +}; +static inline int f2fs_test_bit (unsigned int nr,char *addr);static inline void f2fs_set_bit (unsigned int nr,char *addr);static inline void f2fs_clear_bit (unsigned int nr,char *addr);fs/f2fs/super.c +16
-0@@ -181,6 +181,7 @@ enum { Opt_nat_bits, Opt_jqfmt, Opt_checkpoint, + Opt_lookup_mode, Opt_err, };@@ -244,6 +245,13 @@ static const struct constant_table f2fs_param_errors[] = { {} }; +static const struct constant_table f2fs_param_lookup_mode[] = { + {"perf" ,LOOKUP_PERF }, + {"compat" ,LOOKUP_COMPAT }, + {"auto" ,LOOKUP_AUTO }, + {} +}; +static const struct fs_parameter_spec f2fs_param_specs[] = {fsparam_enum ("background_gc" , Opt_gc_background, f2fs_param_background_gc),fsparam_flag ("disable_roll_forward" , Opt_disable_roll_forward),@@ -300,6 +308,7 @@ static const struct fs_parameter_spec f2fs_param_specs[] = {fsparam_enum ("memory" , Opt_memory_mode, f2fs_param_memory_mode),fsparam_flag ("age_extent_cache" , Opt_age_extent_cache),fsparam_enum ("errors" , Opt_errors, f2fs_param_errors), + fsparam_enum("lookup_mode", Opt_lookup_mode, f2fs_param_lookup_mode), {} };@@ -336,6 +345,7 @@ static match_table_t f2fs_checkpoint_tokens = {#define F2FS_SPEC_discard_unit (1 << 21)#define F2FS_SPEC_memory_mode (1 << 22)#define F2FS_SPEC_errors (1 << 23) +#define F2FS_SPEC_lookup_mode (1 << 24)struct f2fs_fs_context {struct f2fs_mount_info info;@@ -1143,6 +1153,10 @@ static int f2fs_parse_param(struct fs_context *fc, struct fs_parameter *param)case Opt_nat_bits:ctx_set_opt (ctx,F2FS_MOUNT_NAT_BITS );break ; +case Opt_lookup_mode: +F2FS_CTX_INFO (ctx).lookup_mode = result.uint_32; + ctx->spec_mask |= F2FS_SPEC_lookup_mode; +break ; }return 0 ; }@@ -1652,6 +1666,8 @@ static void f2fs_apply_options(struct fs_context *fc, struct super_block *sb)F2FS_OPTION (sbi).memory_mode =F2FS_CTX_INFO (ctx).memory_mode;if (ctx->spec_mask & F2FS_SPEC_errors)F2FS_OPTION (sbi).errors =F2FS_CTX_INFO (ctx).errors; +if (ctx->spec_mask & F2FS_SPEC_lookup_mode) +F2FS_OPTION (sbi).lookup_mode =F2FS_CTX_INFO (ctx).lookup_mode;f2fs_apply_compression (fc, sb);f2fs_apply_test_dummy_encryption (fc, sb);
fs/f2fs/super.c static int f2fs_show_options(struct seq_file *seq, struct dentry *root) · line 2439
Quoted 8 lines
fs/f2fs/super.c +5
-0@@ -2416,6 +2432,13 @@ static int f2fs_show_options(struct seq_file *seq, struct dentry *root)if (test_opt (sbi,NAT_BITS ))seq_puts (seq,",nat_bits" ); +if (F2FS_OPTION (sbi).lookup_mode !=LOOKUP_PERF ) { +if (F2FS_OPTION (sbi).lookup_mode ==LOOKUP_COMPAT ) +seq_show_option (seq,"lookup_mode" ,"compat" ); +else if (F2FS_OPTION (sbi).lookup_mode ==LOOKUP_AUTO ) +seq_show_option (seq,"lookup_mode" ,"auto" );
Can we show "lookup_mode=perf" in mount option as well?
Thanks,
Quoted 14 lines
fs/f2fs/super.c +4
-0+ } +return 0 ; }@@ -2480,6 +2503,8 @@ static void default_options(struct f2fs_sb_info *sbi, bool remount)#endif f2fs_build_fault_attr (sbi,0 ,0 ,FAULT_ALL ); + +F2FS_OPTION (sbi).lookup_mode =LOOKUP_PERF ; }#ifdef CONFIG_QUOTA