Skip to contentSkip to conversation

debugfs: clarify return values when disabled

RFC PATCH New Randy Dunlap 1 participant 1 message Sep 20

Subsystems (2)
Documentation Driver core
lore
Share & tools
lore

Randy Dunlap

author reviewer
#0 lore raw

RFC PATCH 1/1 debugfs: clarify return values when disabled

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 <[email protected]>

---
Cc: Greg Kroah-Hartman <[email protected]>
Cc: "Rafael J. Wysocki" <[email protected]>
Cc: Danilo Krummrich <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: Shuah Khan <[email protected]>
Cc: [email protected]

 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(-)
Documentation/admin-guide/kernel-parameters.txt +2 -1
@@ -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
include/linux/debugfs.h +3 -2
@@ -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,
Documentation/filesystems/debugfs.rst +22 -2
@@ -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::
fs/debugfs/file.c +4 -2
@@ -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,
fs/debugfs/inode.c +16 -6
@@ -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, ...)
 {