Development notes

Collection of various notes about development practices, how-to's or checklists.

Misc notes

Adding a new ioctl, extending an existing one

• add code to strace so the ioctl calls are parsed into a human readable form. Most of the ioctls are already implemented and can be used a reference.

Tracepoints

The tracepoint message format should be compact and consistent, so please stick to the following format:

• key=value no spaces around =
• separated by spaces, not commas
• named values: print value and string, like "%llu(%s)", no space between, string in parens
• avoid abbreviating key values too much, (eg. use 'size' not 'sz')
• hexadecimal values are always preceded by 0x (use "0x%llx)
• use struct btrfs_inode for inode types, not plain struct inode
• inode number type is u64, use btrfs_ino if needed
• key can be printed as [%llu,%u,%llu]
• enum types need to be exported as TRACE_DEFINE_ENUM

Example:

event: btrfs__chunk

string:

  "root=%llu(%s) offset=%llu size=%llu num_stripes=%d sub_stripes=%d type=%s"

Error messages

• use btrfs_* helpers (btrfs_err, btrfs_info, ...), they print a filesystem identification like

BTRFS info (device sdb): ...

• first letter in the string is lowercase
• message contents
  • be descriptive
  • keep the text length reasonable
  • no typos
  • print values that refer to what happend (inode number, subvolume id, path, offset, ...)
  • print error value from the last call
• message level
  • btrfs_err -- such messages have high visibility so use them for serious problems
  • btrfs_info -- use for informative messages that might help debugging problems in the future and are worth keeping in the logs

Error handling and transaction abort

Please keep all transaction abort exactly at the place where they happen and do not merge them to one. This pattern should be used everwhere and is important when debugging because we can pinpoint the line in the code from the syslog message and do not have to guess which way it got to the merged call.

BCP

• do not use spin_is_locked but lockdep_assert_held

Kernel config options

Testing

Compile-time config options for kernel that can help debugging, testing. They usually take a hit on performance or resources (memory) so they should be selected wisely. The options in bold should be safe to use by default for debugging builds.

Please refer to the option documentation for further details.

• devices for testing
  • CONFIG_BLK_DEV_LOOP - enable loop device
  • for fstests: DM_FLAKEY, CONFIG_FAIL_MAKE_REQUEST
  • CONFIG_SCSI_DEBUG - fake scsi block device
• memory
  • CONFIG_SLUB_DEBUG - boot with slub_debug
  • CONFIG_DEBUG_PAGEALLOC + CONFIG_DEBUG_PAGEALLOC_ENABLE_DEFAULT (on newer kernels)
  • CONFIG_PAGE_POISONING
  • CONFIG_HAVE_DEBUG_KMEMLEAK
  • CONFIG_FAILSLAB
• btrfs
  • CONFIG_BTRFS_DEBUG, CONFIG_BTRFS_ASSERT, CONFIG_BTRFS_FS_RUN_SANITY_TESTS
  • CONFIG_BTRFS_FS_CHECK_INTEGRITY
• locking
  • CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_MUTEXES
  • CONFIG_DEBUG_LOCK_ALLOC
  • CONFIG_PROVE_LOCKING, CONFIG_LOCKDEP
  • CONFIG_LOCK_STAT
  • CONFIG_PROVE_RCU
• sanity checks
  • CONFIG_DEBUG_STACK_USAGE, CONFIG_HAVE_DEBUG_STACKOVERFLOW, CONFIG_DEBUG_STACKOVERFLOW
  • CONFIG_STACKTRACE
  • kasan
• verbose reporting
  • CONFIG_DEBUG_BUGVERBOSE
• tracing
  • CONFIG_TRACING etc

(x)fstests

xfstests has very few "hard" requirements and will succeed without running many of the tests. In order to ensure full test coverage, your test environment should provide the following.

Kernel config options for complete test coverage

• CONFIG_FAULT_INJECTION=y
• CONFIG_FAULT_INJECTION_DEBUG_FS=y
• CONFIG_FAIL_MAKE_REQUEST=y
• CONFIG_DM_FLAKEY=m or y
• CONFIG_DM_THIN_PROVISIONING=m or y
• CONFIG_DM_SNAPSHOT=m or y
• CONFIG_DM_DELAY=m or y
• CONFIG_DM_ERROR=m or y
• CONFIG_DM_LOG_WRITES=m or y
• CONFIG_BLK_DEV_LOOP=m or y
• CONFIG_EXT4_FS=m or y
• CONFIG_SCSI_DEBUG=m

Kernel config options for better bug reports

See the list in the section above for more options.

User space utilities and development library dependencies

• fio
• dmsetup
• xfsprogs >= 4.3.1
  • xfs_io -c reflink is required.
• btrfsprogs
• dbench
• openssl
• libacl
• libattr
• libaio
• libuuid

---

Note: This list may be incomplete.

Storage environment

• At least 4 identically sized partitions/disks/virtual disks, specified using $SCRATCH_DEV_POOL
  • some tests may require 6 such partitions

Other requirements

• An fsgqa user and group must exist.
• An 123456-fsgqa user and group must exist.