The DebugFS Interface

The ESPROS kernel modules expose a set of developer-only debug controls via debugfs. These interfaces are intended for debugging, bring-up, and development only and are not ABI-stable.

This interface provides low-level access to device registers to simplify bring-up and fault analysis.

Debugfs is a kernel build-time option. The ESPROS kernel modules compile there debugfs support only when debugfs is enabled. See Enabling / Disabling CONFIG_DEBUG_FS.

All files are located under:

/sys/kernel/debug/epcxxx/

Warning

Writing arbitrary registers can damage the device or put it into an undefined state. Use these interfaces only if you understand the register map and consequences.

Overview

File	Access	Description
read_reg	read / write	Configure and read one or more 8-bit registers
write_reg	read / write	Write one or more 8-bit registers and read back the last write report
dump	read	Dump a fixed register range (0x00–0xFF)

read_reg — Read Register(s)

read_reg is a two-step interface:

• Write selects a start address and an optional count.

• Read performs the I2C register access and returns formatted output.

Write (configure)

Accepted formats:

<start_addr>
<start_addr> <count>

Values may be decimal or hex (e.g. 18, 0x12).

Examples:

# Read one register at 0xA0
echo "0xA0" | sudo tee read_reg

# Read three registers starting at 0xA0: 0xA0, 0xA1, 0xA2
echo "0xA0 3" | sudo tee read_reg

Notes:

• If is omitted, it defaults to 1.

• If is 0, it is clamped to 1.

• is clamped to the driver’s internal maximum burst size.

Read (execute + output)

sudo cat read_reg

Example output:

0xA0: 0x12
0xA1: 0x34
0xA2: <err -5>

If a register read fails, the error code is printed inline.

write_reg — Write Register(s)

Writes one or more 8-bit values starting at a given address. After writing, the driver stores a formatted report which you can read back by reading the same file.

Write

Input format:

<start_addr> <val0> <val1> <val2> ...

• Values are whitespace-separated (spaces/tabs/newlines).

• Decimal and hex are accepted (15 or 0x0F).

• Each value must be in the 8-bit range 0..255 (0x00..0xFF).

Examples:

# Write 0x12 to 0xA0, 0x34 to 0xA1, 0x56 to 0xA2
echo "0xA0 0x12 0x34 0x56" | sudo tee write_reg

# Decimal input also works
echo "160 18 52 86" | sudo tee write_reg

Warning

⚠️ No comma-separated lists
This will fail because parsing is whitespace-based:

echo "0xA0 0x12, 0x34" | sudo tee write_reg
# -> Invalid argument

Read (last report)

sudo cat write_reg

Example output:

0xA0: 0x12
0xA1: 0x34
0xA2: 0x56

On error:

0xA0: <err -6>
0xA1: 0x34

Notes:

• The read output shows the most recent write_reg operation.

• If output would exceed the internal buffer, it may show … truncated ….

dump — Register Dump (0x00–0xFF)

dump reads a fixed range of registers and prints each address/value pair.

Read

sudo cat dump

Example output:

0x00: 0x12
0x01: 0x34
0x02: 0x00
0x03: <err -5>
...
0xFF: 0xA7

If a register read fails, the error code is printed inline.

Notes:

• The implementation may yield CPU (cond_resched()) and will stop early if a signal is pending.

Typical Debug Workflow

# 1) Configure a read (start=0xA0, count=3)
echo "0xA0 3" | sudo tee read_reg

# 2) Perform the read
sudo cat read_reg

# 3) Write three registers starting at 0xA0
echo "0xA0 0x12 0x34 0x56" | sudo tee write_reg

# 4) Read back the last write report
sudo cat write_reg

# 5) Dump 0x00..0xFF
sudo cat dump

Notes & Limitations

• If you don’t see /sys/kernel/debug, DebugFS must be mounted

sudo mount -t debugfs none /sys/kernel/debug

• These interfaces are not intended for production use.

• Concurrent access is serialized internally with a mutex.

• read_reg performs the actual device read on file read, not on config write.

Troubleshooting

Permission denied

• Ensure you are running as root.

Invalid argument

• Check input format and value ranges.

  • read_reg: <addr> or <addr> <count>

  • write_reg: <addr> <val0> <val1> … (whitespace-separated, no commas)

  • Values must be 0..255.

Enabling / Disabling CONFIG_DEBUG_FS

debugfs is a kernel build-time option. So, if it’s necessary, kernel can be rebuild to enable/disable this option. ESPROS kernel modules automatically compile the debugfs code only when it is enabled.

#if IS_ENABLED(CONFIG_DEBUG_FS)
	/* debugfs code */
#endif

So userspace behavior depends entirely on the kernel configuration.

Enable (development)

In the kernel build tree:

make menuconfig

Navigate:

Kernel hacking —> [*] Debug Filesystem

Or non-interactive:

scripts/config --enable DEBUG_FS
make olddefconfig

Disable (production)

scripts/config --disable DEBUG_FS
make olddefconfig

Then rebuild/install that kernel.

Raspberry Pi specific note

On Raspberry Pi OS / downstream kernels, config-$(uname -r) in /boot is usually the easiest truth source:

grep -n "^CONFIG_DEBUG_FS=" /boot/config-$(uname -r)