[RFC PATCH] debugfs: clarify return values when disabled

[Randy Dunlap]

debugfs can be disabled at kconfig time (# CONFIG_DEBUG_FS is not set)
or by using "debugfs=off" on the kernel command line.

The return values for some debugfs functions in these 2 cases can be
different. Describe those differences.

No code changes.

Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
---
Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
Cc: "Rafael J. Wysocki" <rafael@xxxxxxxxxx>
Cc: Danilo Krummrich <dakr@xxxxxxxxxx>
Cc: driver-core@xxxxxxxxxxxxxxx
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
Cc: linux-doc@xxxxxxxxxxxxxxx

 Documentation/admin-guide/kernel-parameters.txt |    3 +
 Documentation/filesystems/debugfs.rst           |   24 ++++++++++++--
 fs/debugfs/file.c                               |    6 ++-
 fs/debugfs/inode.c                              |   22 +++++++++---
 include/linux/debugfs.h                         |    5 +-
 5 files changed, 47 insertions(+), 13 deletions(-)

--- linux-next-20260918.orig/Documentation/admin-guide/kernel-parameters.txt
+++ linux-next-20260918/Documentation/admin-guide/kernel-parameters.txt
@@ -1201,7 +1201,8 @@ Kernel parameters
 			        get a -EPERM as result when trying to register files
 				or directories within debugfs.
 				This is equivalent of the runtime functionality if
-				debugfs was not enabled in the kernel at all.
+				debugfs was not enabled in the kernel at all,
+				except that the latter returns -ENODEV.
 			Default value is set in build-time with a kernel configuration.
 
 	debugpat	[X86] Enable PAT debugging
--- linux-next-20260918.orig/include/linux/debugfs.h
+++ linux-next-20260918/include/linux/debugfs.h
@@ -110,8 +110,9 @@ struct dentry *debugfs_create_file_short
  * you are responsible here.)  If an error occurs, ERR_PTR(-ERROR) will be
  * returned.
  *
- * If debugfs is not enabled in the kernel, the value -%ENODEV will be
- * returned.
+ * If debugfs is not enabled in the kernel build, the value -%ENODEV will be
+ * returned. If debugfs is enabled in the kernel build but is disabled
+ * on the kernel command line, the value -%EPERM will be returned.
  *
  * If fops points to a struct debugfs_short_fops, then simple_open() will be
  * used for the open, and only read/write/llseek are supported and are proxied,
--- linux-next-20260918.orig/Documentation/filesystems/debugfs.rst
+++ linux-next-20260918/Documentation/filesystems/debugfs.rst
@@ -41,7 +41,17 @@ dentry pointer which can be used to crea
 clean it up at the end).  An ERR_PTR(-ERROR) return value indicates that
 something went wrong.  If ERR_PTR(-ENODEV) is returned, that is an
 indication that the kernel has been built without debugfs support and none
-of the functions described below will work.
+of the functions described below will work. If the kernel was built with
+debugfs support but it has been disabled by using "debugfs=off" on the
+kernel command line, ERR_PTR(-EPERM) is returned.
+
+.. note::
+
+  It's expected that most callers should _ignore_ the errors returned
+  by this function. Other debugfs functions handle the fact that the "dentry"
+  passed to them could be an error and they don't crash in that case.
+  Drivers should generally work fine even if debugfs fails to init or is
+  disabled.
 
 The most general way to create a file within a debugfs directory is with::
 
@@ -57,7 +67,17 @@ implement the file's behavior.  At a min
 operations should be provided; others can be included as needed.  Again,
 the return value will be a dentry pointer to the created file,
 ERR_PTR(-ERROR) on error, or ERR_PTR(-ENODEV) if debugfs support is
-missing.
+missing.  If the kernel was built with debugfs support but it has been
+disabled by using "debugfs=off" on the kernel command line, ERR_PTR(-EPERM)
+is returned.
+
+.. note::
+
+  It's expected that most callers should _ignore_ the errors returned
+  by this function. Other debugfs functions handle the fact that the "dentry"
+  passed to them could be an error and they don't crash in that case.
+  Drivers should generally work fine even if debugfs fails to init or is
+  disabled.
 
 Create a file with an initial size, the following function can be used
 instead::
--- linux-next-20260918.orig/fs/debugfs/file.c
+++ linux-next-20260918/fs/debugfs/file.c
@@ -1205,8 +1205,10 @@ static const struct file_operations fops
  * you are responsible here.)  If an error occurs, ERR_PTR(-ERROR) will be
  * returned.
  *
- * If debugfs is not enabled in the kernel, the value ERR_PTR(-ENODEV) will
- * be returned.
+ * If debugfs is not enabled in the kernel build, the value ERR_PTR(-ENODEV)
+ * will be returned. If debugfs is enabled in the kernel build but is disabled
+ * by using "debugfs=off" on the kernel command line, the value ERR_PTR(-EPERM)
+ * will be returned.
  */
 struct dentry *debugfs_create_blob(const char *name, umode_t mode,
 				   struct dentry *parent,
--- linux-next-20260918.orig/fs/debugfs/inode.c
+++ linux-next-20260918/fs/debugfs/inode.c
@@ -339,8 +339,10 @@ MODULE_ALIAS_FS("debugfs");
  * doesn't exist or an error occurs, %NULL will be returned.  The returned
  * dentry must be passed to dput() when it is no longer needed.
  *
- * If debugfs is not enabled in the kernel, the value -%ENODEV will be
- * returned.
+ * If debugfs is not enabled in the kernel build, the value ERR_PTR(-ENODEV)
+ * will be returned. If debugfs is enabled in the kernel build but is disabled
+ * by using "debugfs=off" on the kernel command line, the value ERR_PTR(-EPERM)
+ * will be returned.
  */
 struct dentry *debugfs_lookup(const char *name, struct dentry *parent)
 {
@@ -562,8 +564,10 @@ EXPORT_SYMBOL_GPL(debugfs_create_file_si
  * you are responsible here.)  If an error occurs, ERR_PTR(-ERROR) will be
  * returned.
  *
- * If debugfs is not enabled in the kernel, the value -%ENODEV will be
- * returned.
+ * If debugfs is not enabled in the kernel build, the value ERR_PTR(-ENODEV)
+ * will be returned. If debugfs is enabled in the kernel build but is disabled
+ * by using "debugfs=off" on the kernel command line, the value ERR_PTR(-EPERM)
+ * will be returned.
  *
  * NOTE: it's expected that most callers should _ignore_ the errors returned
  * by this function. Other debugfs functions handle the fact that the "dentry"
@@ -660,8 +664,10 @@ EXPORT_SYMBOL(debugfs_create_automount);
  * unloaded, you are responsible here.)  If an error occurs, ERR_PTR(-ERROR)
  * will be returned.
  *
- * If debugfs is not enabled in the kernel, the value -%ENODEV will be
- * returned.
+ * If debugfs is not enabled in the kernel build, the value ERR_PTR(-ENODEV)
+ * will be returned. If debugfs is enabled in the kernel build but is disabled
+ * by using "debugfs=off" on the kernel command line, the value ERR_PTR(-EPERM)
+ * will be returned.
  */
 struct dentry *debugfs_create_symlink(const char *name, struct dentry *parent,
 				      const char *target)
@@ -820,6 +826,10 @@ EXPORT_SYMBOL_GPL(debugfs_lookup_and_rem
  *
  * If debugfs is not enabled in the kernel, the value -%ENODEV will be
  * returned.
+ * If debugfs is not enabled in the kernel build, the value %-ENODEV
+ * will be returned. If debugfs is enabled in the kernel build but is disabled
+ * by using "debugfs=off" on the kernel command line, the value %-EPERM
+ * will be returned.
  */
 int __printf(2, 3) debugfs_change_name(struct dentry *dentry, const char *fmt, ...)
 {