The sysfs Filesystem

Patrick Mochel

[email protected]

Abstract

sysfs is a feature of the Linux 2.6 kernel that al-

lows kernel code to export information to user

processes via an in-memory ﬁlesystem. The or-

ganization of the ﬁlesystem directory hierarchy

is strict, and based the internal organization of

kernel data structures. The ﬁles that are created

in the ﬁlesystem are (mostly) ASCII ﬁles with

(usually) one value per ﬁle. These features en-

sure that the information exported is accurate

and easily accessible, making sysfs one of the

most intuitive and useful features of the 2.6 ker-

nel.

Introduction

sysfs is a mechanism for representing kernel

objects, their attributes, and their relationships

with each other. It provides two components:

a kernel programming interface for exporting

these items via sysfs, and a user interface to

view and manipulate these items that maps

back to the kernel objects which they represent.

The table below shows the mapping between

internel (kernel) constructs and their external

(userspace) sysfs mappings.

Internal External

Kernel Objects Directories

Object Attributes Regular Files

Object Relationships Symbolic Links

sysfs is a core piece of kernel infrastructure,

which means that it provides a relatively sim-

ple interface to perform a simple task. Rarely

is the code overly complicated, or the descrip-

tions obtuse. However, like many core pieces

of infrastructure, it can get a bit too abstract

and far removed to keep track of. To help al-

leviate that, this paper takes a gradual approach

to sysfs before getting to the nitty-gritty details.

First, a short but touching history describes its

origins. Then crucial information about mount-

ing and accessing sysfs is included. Next,

the directory organization and layout of sub-

systems in sysfs is described. This provides

enough information for a user to understand the

organization and content of the information that

is exported through sysfs, though for reasons of

time and space constraints, not every object and

its attributes are described.

The primary goal of this paper is to pro-

vide a technical overview of the internal sysfs

interface—the data structures and the func-

tions that are used to export kernel con-

structs to userspace. It describes the functions

among the three concepts mentioned above—

Kernel Objects, Object Attributes, and Object

Relationships—and dedicates a section to each

one. It also provides a section for each of the

two additional regular ﬁle interfaces created to

simplify some common operations—Attribute

Groups and Binary Attributes.

sysfs is a conduit of information between the

kernel and user space. There are many op-

• 313 •

314 • The sysfs Filesystem

portunities for user space applications to lever-

age this information. Some existing uses are

the ability to I/O Scheduler parameters and the

udev program. The ﬁnal section describes a

sampling of the current applications that use

sysfs and attempts to provide enough inspira-

tion to spawn more development in this area.

Because it is a simple and mostly abstract in-

terface, much time can be spent describing its

interactions with each subsystem that uses it.

This is especially true for the kobject and driver

models, which are both new features of the 2.6

kernel and heavily intertwined with sysfs. It

would be impossible to do those topics justice

in such a medium and are left as subjects for

other documents. Readers still curious in these

and related topics are encouraged to read [4].

1 The History of sysfs

sysfs is an in-memory ﬁlesystem that was origi-

nally based on ramfs. ramfs was written around

the time the 2.4.0 kernel was being stabilized.

It was an exercise in elegance, as it showed

just how easy it was to write a simple ﬁlesys-

tem using the then-new VFS layer. Because

of its simplicity and use of the VFS, it pro-

vided a good base from which to derive other

in-memory based ﬁlesystems.

sysfs was originally called ddfs (Device Driver

Filesystem) and was written to debug the new

driver model as it was being written. That de-

bug code had originally used procfs to export a

device tree, but under strict urging from Linus

Torvalds, it was converted to use a new ﬁlesys-

tem based on ramfs.

By the time the new driver model was merged

into the kernel around 2.5.1, it had changed

names to driverfs to be a little more descriptive.

During the next year of 2.5 development, the

mount -t sysfs sysfs /sys

Table 1: A sysfs mount command

sysfs /sys sysfs noauto 0 0

Table 2: A sysfs entry in /etc/fstab

infrastructural capabilities of the driver model

and driverfs began to prove useful to other sub-

systems. kobjects were developed to provide

a central object management mechanism and

driverfs was converted to sysfs to represent its

subsystem agnosticism.

2 Mounting sysfs

sysfs can be mounted from userspace just like

any other memory-based ﬁlesystem. The com-

mand for doing so is listed in Table 1.

sysfs can also be mounted automatically on

boot using the ﬁle /etc/fstab. Most distri-

butions that support the 2.6 kernel have entries

for sysfs in /etc/fstab. An example entry

is shown in Table 2.

Note that the directory that sysfs is mounted on:

/sys. That is the de facto standard location

for the sysfs mount point. This was adopted

without objection by every major distribution.

3 Navigating sysfs

Since sysfs is simply a collection of directo-

ries, ﬁles, and symbolic links, it can be navi-

gated and manipulated using simple shell util-

ities. The author recommends the tree(1)

utility. It was an invaluable aide during the de-

velopment of the core kernel object infrastruc-

ture.

2005 Linux Symposium • 315

/sys/

|-- block

|-- bus

|-- class

|-- devices

|-- firmware

|-- module

‘-- power

Table 3: Top level sysfs directories

At the top level of the sysfs mount point are a

number of directories. These directories rep-

resent the major subsystems that are registered

with sysfs. At the time of publication, this

consisted of the directories listed in Table 3.

These directories are created at system startup

when the subsystems register themselves with

the kobject core. After they are initialized, they

begin to discover objects, which are registered

within their respective directories.

The method by which objects register with

sysfs and how directores are created is ex-

plained later in the paper. In the meantime,

the curious are encouraged to meander on their

own through the sysfs hierarchy, and the mean-

ing of each subsystem and their contents fol-

lows now.

3.1 block

The block directory contains subdirectories

for each block device that has been discovered

in the system. In each block device’s directory

are attributes that describe many things, includ-

ing the size of the device and the dev_t number

that it maps to. There is a symbolic link that

points to the physical device that the block de-

vice maps to (in the physical device tree, which

is explained later). And, there is a directory that

exposes an interface to the I/O scheduler. This

interface provides some statistics about about

the device request queue and some tunable fea-

tures that a user or administrator can use to

bus/

|-- ide

|-- pci

|-- scsi

‘-- usb

Table 4: The bus directory

optimize performance, including the ability to

dyanmically change the I/O scheduler to use.

Each partition of each block device is repre-

sented as a subdirectory of the block device.

Included in these directories are read-only at-

tributes about the partitions.

3.2 bus

The bus directory contains subdirectories for

each physical bus type that has support regis-

tered in the kernel (either statically compiled or

loaded via a module). Partial output is listed in

Table 4.

Each bus type that is represented has two sub-

directories: devices and drivers. The

devicesdirectory contains a ﬂat listing of ev-

ery device discovered on that type of bus in the

entire system. The devices listed are actually

symbolic links that point to the device’s direc-

tory in the global device tree. An example list-

ing is shown in Table 5.

The drivers directory contains directories

for each device driver that has been registered

with the bus type. Within each of the drivers’

directories are attributes that allow viewing and

manipulation of driver parameters, and sym-

bolic links that point to the physical devices (in

the global device tree) that the driver is bound

to.

316 • The sysfs Filesystem

bus/pci/devices/

|-- 0000:00:00.0 -> ../../../devices/pci0000:00/0000:00:00.0

|-- 0000:00:01.0 -> ../../../devices/pci0000:00/0000:00:01.0

|-- 0000:01:00.0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0

|-- 0000:02:00.0 -> ../../../devices/pci0000:00/0000:00:1e.0/0000:02:00.0

|-- 0000:02:00.1 -> ../../../devices/pci0000:00/0000:00:1e.0/0000:02:00.1

|-- 0000:02:01.0 -> ../../../devices/pci0000:00/0000:00:1e.0/0000:02:01.0

‘-- 0000:02:02.0 -> ../../../devices/pci0000:00/0000:00:1e.0/0000:02:02.0

Table 5: PCI devices represented in bus/pci/devices/

class/

|-- graphics

|-- input

|-- net

|-- printer

|-- scsi_device

|-- sound

‘-- tty

Table 6: The class directory

3.3 class

The class directory contains representations

of every device class that is registered with the

kernel. A device class describes a functional

type of device. Examples of classes are shown

in Table 6.

Each device class contains subdirectories for

each class object that has been allocated and

registered with that device class. For most of

class device objects, their directories contain

symbolic links to the device and driver directo-

ries (in the global device hierarchy and the bus

hierarchy respectively) that are associated with

that class object.

Note that there is not necessarily a 1:1 mapping

between class objects and physical devices; a

physical device may contain multiple class ob-

jects that perform a different logical function.

For example, a physical mouse device might

map to a kernel mouse object, as well as a

generic “input event” device and possibly a “in-

put debug” device.

Each class and class object may contain at-

tributes exposing parameters that describe or

control the class object. The contents and for-

mat, though, are completely class dependent

and depend on the support present in one’s ker-

nel.

3.4 devices

The devices directory contains the global

device hierarchy. This contains every physi-

cal device that has been discovered by the bus

types registered with the kernel. It represents

them in an ancestrally correct way—each de-

vice is shown as a subordinate device of the de-

vice that it is physically (electrically) subordi-

nate to.

There are two types of devices that are excep-

tions to this representation: platform devices

and system devices. Platform devices are pe-

ripheral devices that are inherent to a particular

platform. They usually have some I/O ports,

or MMIO, that exists at a known, ﬁxed loca-

tion. Examples of platform devices are legacy

x86 devices like a serial controller or a ﬂoppy

controller, or the embedded devices of a SoC

solution.

System devices are non-peripheral devices that

are integral components of the system. In many

ways, they are nothing like any other device.

They may have some hardware register access

for conﬁguration, but do not have the capabil-

ity to transfer data. They usually do not have

2005 Linux Symposium • 317

drivers which can be bound to them. But, at

least for those represented through sysfs, have

some architecture-speciﬁc code that conﬁgures

them and treats them enough as objects to ex-

port them. Examples of system devices are

CPUs, APICs, and timers.

3.5 ﬁrmware

The firmware directory contains inter-

faces for viewing and manipulating ﬁrmware-

speciﬁc objects and attributes. In this case,

‘ﬁrmware’ refers to the platform-speciﬁc code

that is executed on system power-on, like the

x86 BIOS, OpenFirmware on PPC platforms,

and EFI on ia64 platforms.

Each directory contains a set of objects and at-

tributes that is speciﬁc to the ﬁrmware “driver

in the kernel.” For example, in the case

of ACPI, every object found in the ACPI

DSDT table is listed in firmware/acpi/

namespace/ directory.

3.6 module

The module directory contains subdirectories

for each module that is loaded into the kernel.

The name of each directory is the name of the

module—both the name of the module object

ﬁle and the internal name of the module. Ev-

ery module is represented here, regardless of

the subsystem it registers an object with. Note

that the kernel has a single global namespace

for all modules.

Within each module directory is a subdirectory

called sections. This subdirectory contains

attributes about the module sections. This in-

formation is used for debugging and generally

not very interesting.

Each module directory also contains at least

one attribute: refcnt. This attributes displays

the current reference count, or number of users,

of the module. This is the same value in the

fourth column of lsmod(8) output.

3.7 power

The power directory represents the under-

used power subsystem. It currently contains

only two attributes: disk which controls the

method by which the system will suspend to

disk; and state, which allows a process to en-

ter a low power state. Reading this ﬁle displays

which states the system supports.

4 General Kernel Information

4.1 Code Organization

The code for sysfs resides in fs/sysfs/

and its shared function prototypes are in

include/linux/sysfs.h. It is relatively

small (~2000 lines), but it is divided up among

9 ﬁles, including the shared header ﬁle. The

organization of these ﬁles is listed below. The

contents of each of these ﬁles is described in

the next section.

• include/linux/sysfs.h - Shared

header ﬁle containing function prototypes

and data structure deﬁnitions.

• fs/sysfs/sysfs.h - Internal header

ﬁle for sysfs. Contains function deﬁnitions

shared locally among the sysfs source.

• fs/sysfs/mount.c - This contains

the data structures, methods, and initial-

ization functions necessary for interacting

with the VFS layer.

318 • The sysfs Filesystem

• fs/sysfs/inode.c - This ﬁle con-

tains internal functions shared among the

sysfs source for allocating and freeing the

core ﬁlesystem objects.

• fs/sysfs/dir.c - This ﬁle contains

the externally visible sysfs interface re-

sponsible for creating and removing direc-

tories in the sysfs hierarchy.

• fs/sysfs/file.c - This ﬁle contains

the externally visible sysfs interface re-

sponsible for creating and removing reg-

ular, ASCII ﬁles in the sysfs hiearchy.

• fs/sysfs/group.c - This ﬁle con-

tains a set of externally-visible helpers that

aide in the creation and deletion of multi-

ple regular ﬁles at a time.

• fs/sysfs/symlink.c- This ﬁle con-

tains the externally- visible interface re-

sponsible for creating and removing sym-

link in the sysfs hierarchy.

• fs/sysfs/bin.c - This ﬁle contains

the externally visible sysfs interface re-

sponsible for creating and removing bi-

nary (non-ASCII) ﬁles.

4.2 Initialization

sysfs is initialized in fs/sysfs/mount.c,

via the sysfs_init function. This function

is called directly by the VFS initialization code.

It must be called early, since many subsystems

depend on sysfs being initialized to register ob-

jects with. This function is responsible for do-

ing three things.

• Creating a kmem_cache. This cache

is used for the allocation of sysfs_

dirent objects. These are discussed in

a later section.

• Registering with the VFS. register_

filesystem() is called with the

sysfs_fs_type object. This sets up

the appropriate super block methods and

adds a ﬁlesystem with the name sysfs.

• Mounts itself internally. This is done to

ensure that it is always available for other

kernel code to use, even early in the boot

process, instead of depending on user in-

teraction to explicitly mount it.

Once these actions complete, sysfs is fully

functional and ready to use by all internal code.

4.3 Conﬁguration

sysfs is compiled into the kernel by default.

It is dependent on the conﬁguration option

CONFIG_SYSFS. CONFIG_SYSFS is only

visible if the CONFIG_EMBEDDED option is

set, which provides many options for conﬁg-

uring the kernel for size-constrained envrion-

ments. In general, it is considered a good idea

to leave sysfs conﬁgured in a custom-compiled

kernel. Many tools currently do, and probably

will in the future, depend on sysfs being present

in the system.

4.4 Licensing

The sysfs code is licensed under the GPLv2.

While most of it is now original, it did originate

as a clone of ramfs, which is licensed under the

same terms. All of the externally-visible inter-

faces are original works, and are of course also

licensed under the GPLv2.

The external interfaces are exported to mod-

ules, however only to GPL-compatible mod-

ules, using the macro EXPORT_SYMBOL_

GPL. This is done for reasons of maintainabil-

ity and derivability. sysfs is a core component

2005 Linux Symposium • 319

of the kernel. Many subsystems rely on it, and

while it is a stable piece of infrastructure, it oc-

casionally must change. In order to develop

the best possible modiﬁcations, it’s imperative

that all callers of sysfs interfaces be audited and

updated in lock-step with any sysfs interface

changes. By requiring that all users be licensed

in a GPL manner, and hopefully merged into

the kernel, the level of difﬁculty of an interface

change can be greatly reduced.

Also, since sysfs was developed initially as an

extension of the driver model and has gone

through many iterations of evolution, it has a

very explicit interaction with its users. To de-

velop code that used sysfs but was not copied

or derived from an existing in-kernel GPL-

based user would be difﬁcult, if not impossible.

By requiring GPL-compatibility in the users of

sysfs, this can be made explicit and help pre-

vent falsiﬁcation of derivability.

5 Kernel Interface Overview

The sysfs functions visible to kernel code are

divided into three categories, based on the type

of object they are exporting to userspace (and

the type of object in the ﬁlesystem they create).

• Kernel Objects (Directories).

• Object Attributes (Regular Files).

• Object Relationships (Symbolic Links).

There are also two other sub-categories of ex-

porting attributes that were developed to acco-

modate users that needed to export other ﬁles

besides single, ASCII ﬁles. Both of these cate-

gories result in regular ﬁles being created in the

ﬁlesystem.

• Attribute Groups

• Binary Files

The ﬁrst parameter to all sysfs functions is the

kobject (hereby referenced as k), which is be-

ing manipulated. The sysfs core assumes that

this kobject will remain valid throughout the

function; i.e., they will not be freed. The caller

is always responsible for ensuring that any nec-

essary locks that would modify the object are

held across all calls into sysfs.

For almost every function (the exception be-

ing sysfs_create_dir), the sysfs core as-

sumes that k->dentry is a pointer to a valid

dentry that was previously allocated and initial-

ized.

All sysfs function calls must be made from pro-

cess context. They should also not be called

with any spinlocks held, as many of them take

semaphores directly and all call VFS functions

which may also take semaphores and cause the

process to sleep.

6 Kernel Objects

Kernel objects are exported as directories via

sysfs. The functions for manipulating these di-

rectories are listed in Table 7.

sysfs_create_dir is the only sysfs func-

tion that does not rely on a directory having

already been created in sysfs for the kobject

(since it performs the crucial action of creating

that directory). It does rely on the following

parameters being valid:

• k->parent

• k->name

320 • The sysfs Filesystem

int sysfs_create_dir(struct kobject ∗ k);

void sysfs_remove_dir(struct kobject ∗ k);

int sysfs_rename_dir(struct kobject ∗, const char ∗new_name);

Table 7: Functions for manipulating sysfs directories.

6.1 Creating Directories

These parameters control where the directory

will be located and what it will be called. The

location of the new directory is implied by the

value of k->parent; it is created as a subdi-

rectory of that. In all cases, the subsystem (not

a low-level driver) will ﬁll in that ﬁeld with in-

formation it knows about the object when the

object is registered with the subsystem. This

provides a simple mechanism for creating a

complete user-visible object tree that accurately

represents the internal object tree within the

kernel.

It is possible to call sysfs_create_dir

without k->parent set; it will simply cre-

ate a directory at the very top level of the sysfs

ﬁlesystem. This should be avoided unless one

is writing or porting a new top-level subsystem

using the kobject/sysfs model.

When sysfs_create_dir() is called, a

dentry (the object necessary for most VFS

transactions) is allocated for the directory, and

is placed in k->dentry. An inode is cre-

ated, which makes a user-visible entity, and

that is stored in the new dentry. sysfs ﬁlls in

the file_operationsfor the new directory

with a set of internal methods that exhibit stan-

dard behavior when called via the VFS system

call interface. The return value is 0 on success

and a negative errno code if an error occurs.

6.2 Removing Directories

sysfs_remove_dir will remove an ob-

ject’s directory. It will also remove any regu-

lar ﬁles that reside in the directory. This was

an original feature of the ﬁlesystem to make it

easier to use (so all code that created attributes

for an object would not be required to be called

when an object was removed). However, this

feature has been a source of several race con-

ditions throughout the years and should not be

relied on in the hopes that it will one day be

removed. All code that adds attributes to an ob-

ject’s directory should explicitly remove those

attributes when the object is removed.

6.3 Renaming Directories

sysfs_rename_dir is used to give a direc-

tory a new name. When this function is called,

sysfs will allocate a new dentry for the kobject

and call the kobject routine to change the ob-

ject’s name. If the rename succeeds, this func-

tion will return 0. Otherwise, it will return a

negative errno value specifying the error that

occurred.

It is not possible at this time to move a sysfs

directory from one parent to another.

7 Object Attributes

Attributes of objects can be exposed via sysfs as

regular ﬁles using the struct attribute

2005 Linux Symposium • 321

int sysfs_create_file(struct kobject ∗, const struct attribute ∗);

void sysfs_remove_file(struct kobject ∗, const struct attribute ∗);

int sysfs_update_file(struct kobject ∗, const struct attribute ∗);

Table 8: Functions for manipulating sysfs ﬁles

struct device_attribute {

struct attribute attr;

ssize_t (∗show)(struct device ∗dev, char ∗buf);

ssize_t (∗store)(struct device ∗dev, const char ∗buf, size_t count);

};

int device_create_file(struct device ∗device,

struct device_attribute ∗entry);

void device_remove_file(struct device ∗dev,

struct device_attribute ∗attr);

Table 10: A wrapper for struct attribute from the Driver Model

struct attribute {

char ∗name;

struct module ∗owner;

mode_t mode;

};

Table 9: The struct attribute data type

data type described in Table 9 and the functions

listed in Table 8.

7.1 Creating Attributes

sysfs_create_file() uses the name

ﬁeld to determine the ﬁle name of the attribute

and the mode ﬁeld to set the UNIX ﬁle mode

in the ﬁle’s inode. The directory in which the

ﬁle is created is determined by the location of

the kobject that is passed in the ﬁrst parameter.

7.2 Reference Counting and Modules

The owner ﬁeld may be set by the the caller to

point to the module in which the attribute code

exists. This should not point to the module that

owns the kobject. This is because attributes can

be created and removed at any time. They do

not need to be created when a kobject is regis-

tered; one may load a module with several at-

tributes for objects of a particular type that are

registered after the objects have been registered

with their subsystem.

For example, network devices have a set of

statistics that are exported as attributes via

sysfs. This set of statistics attributes could re-

side in an external module that does not need

to be loaded in order for the network devices

to function properly. When it is loaded, the

attributes contained within are created for ev-

ery registered network device. This module

could be unloaded at any time, removing the

322 • The sysfs Filesystem

attributes from sysfs for each network device.

In this case, the module ﬁeld should point to

the module that contains the network statistic

attributes.

The owner ﬁeld is used for reference count-

ing when the attribute ﬁle is accessed. The ﬁle

operations for attributes that the VFS calls are

set by sysfs with internal functions. This allows

sysfs to trap each access call and perform nec-

essary actions, and it allows the actual methods

that read and write attribute data to be greatly

simpliﬁed.

When an attribute ﬁle is opened, sysfs incre-

ments the reference count of both the kobject

represented by the directory where the attribute

resides, and the module which contains the at-

tribute code. The former operation guarantees

that the kobject will not be freed while the at-

tribute is being accessed. The latter guarantees

that the code which is being executed will not

be unloaded from the kernel and freed while the

attribute is being accessed.

7.3 Wrappable Objects

One will notice that struct attribute

does not actually contain the methods to read

or write the attribute. sysfs does not specify the

format or parameters of these functions. This

was an explicit design decision to help ensure

type safety in these functions, and to aid in sim-

plifying the downstream methods.

Subsystems that use sysfs attributes create

a new data type that encapsulates struct

attribute, like in Table 10. By deﬁning a

wrapping data type and functions, downstream

code is protected from the low-level details of

sysfs and kobject semantics.

When an attribute is read or written, sysfs ac-

cesses a special data structure, through the kob-

ject, called a kset. This contains the base opera-

tions for reading and writing attributes for kob-

jects of a particular type. These functions trans-

late the kobject and attribute into higher level

objects, which are then passed to the show and

store methods described in Table 10. Again,

this helps ensure type safety, because it guar-

antees that the downstream function receives a

higher-level object that it use directly, without

having to translate it.

Many programmers are inclined to cast be-

tween object types, which can lead to hard-to-

ﬁnd bugs if the position of the ﬁelds in a struc-

ture changes. By using helper functions within

the kernel that perform an offset-based pointer

subtraction to translate between object types,

type safety can be guaranteed, regardless if the

ﬁeld locations may change. By centralizing the

translation of objects in this manner, the code

can be easier to audit in the event of change.

7.4 Reading and Writing Attributes

sysfs attempts to make reading and writing at-

tributes as simple as possible. When an at-

tribute is opened, a PAGE_SIZE buffer is al-

located for transferring the data between the

kernel and userspace. When an attribute

is read, this buffer is passed to a down-

stream function (e.g., struct device_

attribute::show() which is responsible

for ﬁlling in the data and formatting it appro-

priately. This data is then copied to userspace.

When a value is written to a sysfs attribute ﬁle,

the data is ﬁrst copied to the kernel buffer, then

it is passed to the downstream method, along

with the size of the buffer in bytes. This method

is responsible for parsing the data.

It is assumed that the data written to the buffer

is in ASCII format. It is also implied that the

size of the data written is less than one page in

2005 Linux Symposium • 323

size. If the adage of having one value per ﬁle

is followed, the data should be well under one

page in size. Having only one value per ﬁle also

eliminates the need for parsing complicated

strings. Many bugs, especially in text parsing,

are propogated throughout the kernel by copy-

ing and pasting code thought to be bug-free. By

making it easy to export one value per ﬁle, sysfs

eliminates the need for copy-and-paste devel-

opment, and prevents these bugs from propa-

gating.

7.5 Updating an attribute

If the data for an attribute changes, ker-

nel code can notify a userspace process that

may be waiting for updates by modifying the

timestamp of the ﬁle using sysfs_update_

file(). This function will also call dnotify,

which some applications use to wait for modi-

ﬁed ﬁles.

8 Object Relationships

A relationship between two objects can be ex-

pressed in sysfs by the use of a symbolic link.

The functions for manipulating symbolic links

in sysfs are shown in Table 11. A relationship

within the kernel may simply be a pointer be-

tween two different objects. If both of these ob-

jects are represented in sysfs with directories,

then a symbolic link can be created between

them and prevent the addition of redundant in-

formation in both objects’ directories.

When creating a symbolic link between two ob-

jects, the ﬁrst argument is the kobject that is be-

ing linked from. This represents the directory in

which the symlink will be created. The second

argument is the kobject which is being linked

to. This is the directory that the symlink will

point to. The third argument is the name of the

symlink that will appear in the ﬁlesystem.

To illustrate this, consider a PCI network device

and driver. When the system boots, the PCI de-

vice is discovered and a sysfs directory is cre-

ated for it, long before it is bound to a speciﬁc

driver. At some later time, the network driver

is loaded, which may or may not bind to any

devices. This is a different object type than the

physical PCI device represents, so a new direc-

tory is created for it.

Their association is illustrated in Table 12.

Shown is the driver’s directory in sysfs, which

is named after the name of the driver module.

This contains a symbolic link that points to the

devices to which it is bound (in this case, just

one). The name of the symbolic link and the

target directory are the same, and based on the

physical bus ID of the device.

9 Attribute Groups

The attribute group interface is a simpliﬁed in-

terface for easily adding and removing a set of

attributes with a single call. The attribute_

group data structure and the functions deﬁned

for manipulating them are listed in Table 13.

An attribute group is simply an array of at-

tributes to be added to an object, as represented

by the attrsﬁeld. The nameﬁeld is optional.

If speciﬁed, sysfs will create a subdirectory of

the object to store the attributes in the group.

This can be a useful aide in organizing large

numbers of attributes.

Attribute groups were created to make it easier

to keep track of errors when registering multi-

ple attributes at one time, and to make it more

compelling to clean up all attributes that a piece

of code may create for an object. Attributes can

324 • The sysfs Filesystem

int sysfs_create_link(struct kobject ∗kobj, struct kobject ∗target,

char ∗name);

void sysfs_remove_link(struct kobject ∗, char ∗name);

Table 11: Functions for manipulating symbolic links in sysfs

$ tree -d bus/pci/drivers/e1000/

bus/pci/drivers/e1000/

‘-- 0000:02:01.0 -> ../../../../devices/pci0000:00/0000:00:1e.0/0000:02:01.0

Table 12: An example of a symlink in sysfs.

be added and removed from the group without

having to change the registration and unregis-

tration functions.

When a group of attributes is added, the return

value is noted for each one. If any one fails to

be added (because of e.g. low memory condi-

tions or duplicate attribute names), the previ-

ously added attributes of that group will be re-

moved and the error code will be returned to the

caller. This allows downstream code to retain a

simple and elegant error handling mechanism,

no matter how many attributes it creates for an

object.

When an attribute group is removed, all of the

attributes contained in it are removed. If a sub-

directory was created to house the attributes, it

is also removed.

Good examples of attribute groups and their

uses can be found in the network device statis-

tics code. Its sysfs interface is in the ﬁle

net/core/net-sysfs.c.

10 Binary Attributes

Binary ﬁles are a special class of regular ﬁles

that can be exported via sysfs using the data

structure and functions listed in Table 14. They

exist to export binary data structures that are ei-

ther best left formatted and parsed in a more

ﬂexible environment, like userspace process

context because they have a known and stan-

dard format (e.g., PCI Conﬁguration Space

Registers); or because their use is strictly in bi-

nary format (e.g., binary ﬁrmware images).

The use of binary ﬁles is akin to the procfs

interface, though sysfs still traps the read and

write methods of the VFS before it calls the

methods in struct bin_attribute. It

allows more control over the format of the

data, but is more difﬁcult to manage. In gen-

eral, if there is a choice over which interface

to use—regular attributes or binary attributes,

there should be no compelling reasons to use

binary attributes. They should only be used for

speciﬁc purposes.

11 Current sysfs Users

The number of applications that use sysfs di-

rectly are few. It already provides a substantial

amount of useful information in an organized

format, so the need for utilities to extract and

parse data is minimal. However, there are a few

users of sysfs, and the infrastructure to support

more is already in place.

2005 Linux Symposium • 325

struct attribute_group {

char ∗name;

struct attribute ∗∗attrs;

};

int sysfs_create_group(struct kobject ∗,

const struct attribute_group ∗);

void sysfs_remove_group(struct kobject ∗,

const struct attribute_group ∗);

Table 13: Attribute Groups

struct bin_attribute {

struct attribute attr;

size_t size;

void ∗private;

ssize_t (∗read)(struct kobject ∗, char ∗, loff_t, size_t);

ssize_t (∗write)(struct kobject ∗, char ∗, loff_t, size_t);

int (∗mmap)(struct kobject ∗, struct bin_attribute ∗attr,

struct vm_area_struct ∗vma);

};

int sysfs_create_bin_file(struct kobject ∗ kobj,

struct bin_attribute ∗ attr);

int sysfs_remove_bin_file(struct kobject ∗ kobj,

struct bin_attribute ∗ attr);

Table 14: Binary Attributes

udev was written in 2003 to provide a

dynamic device naming service based on

user/administrator/distro-speciﬁed rules. It in-

teracts with the /sbin/hotplug program,

which gets called by the kernel when a variety

of different events occur. udev uses information

stored in sysfs about devices to name and con-

ﬁgure them. More importantly, it is used as a

building block by other components to provide

a feature-rich and user-friendly device manage-

ment environment.

Information about udev can be found at ker-

nel.org [2]. Information about HAL—an

aptly named hardware abstraction layer—can

be found at freedesktop.org [1].

udev is based on libsysfs, a C library written

to provide a robust programming interface for

accessing sysfs objects and attributes. Informa-

tion about libsysfs can be found at SourceForge

[3]. The udev source contains a version of lib-

sysfs that it builds against. On some distribu-

tions, it is already installed. If so, header ﬁles

can be found in /usr/include/sysfs/

and shared libraries can be found in /lib/

libsysfs.so.1.

The pciutils package has been updated to use

sysfs to access PCI conﬁguration information,

326 • The sysfs Filesystem

instead of using /proc/bus/pci/.

A simple application for extracting and pars-

ing data from sysfs called si has been written.

This utility can be used to display or modify

any attribute, though its true beneﬁt is efforts to

aggregate and format subsystem-speciﬁc infor-

mation into an intuitive format. At the time of

publication, it is still in early alpha stages. It

can be found at kernel.org [5].

12 Conclusion

sysfs is a ﬁlesystem that allows kernel subsys-

tems to export kernel objects, object attributes,

and object relationships to userspace. This in-

formation is strictly organized and usually for-

matted simply in ASCII, making it very acces-

sible to users and applications. It provides a

clear window into the kernel data structures and

the physical or virtual objects that they control.

sysfs provides a core piece of infrastructure in

the much larger effort of building ﬂexible de-

vice and system management tools. To do this

effectively, it retains a simple feature set that

eases the use of its interfaces and data repre-

sentations easy.

This paper has described the sysfs kernel inter-

faces and the userspace representation of kernel

constructs. This paper has hopefully demys-

tiﬁed sysfs enough to help readers understand

what sysfs does and how it works, and with a

bit of luck, encouraged them to dive head ﬁrst

into sysfs, whether it’s from a developer stand-

point, a user standpoint, or both.

References

[1] freedesktop.org. hal, 2005.

http://hal.freedesktop.org/

wiki/Software_2fhal.

[2] Greg Kroah-Hartman. udev, 2004.

http://www.kernel.org/pub/

linux/utils/kernel/hotplug/

udev.html.

[3] The libsysfs Developers. libsysfs, 2003.

http:

//linux-diag.sourceforge.

net/Sysfsutils.html.

[4] LWN.net. 2.6 driver porting series, 2003.

http://lwn.net/Articles/

driver-porting/.

[5] Patrick Mochel. si, 2005. http://

kernel.org/pub/linux/kernel/

people/mochel/tools/si/.

Proceedings of the

Linux Symposium

Volume One

July 20nd–23th, 2005

Ottawa, Ontario

Canada

Conference Organizers

Andrew J. Hutton, Steamballoon, Inc.

C. Craig Ross, Linux Symposium

Stephanie Donovan, Linux Symposium

Review Committee

Gerrit Huizenga, IBM

Matthew Wilcox, HP

Dirk Hohndel, Intel

Val Henson, Sun Microsystems

Jamal Hadi Salimi, Znyx

Matt Domsch, Dell

Andrew Hutton, Steamballoon, Inc.

Proceedings Formatting Team

John W. Lockhart, Red Hat, Inc.

Authors retain copyright to all submitted papers, but have granted unlimited redistribution rights

to all as a condition of submission.