The Kernel Newbie Corner: Kernel Debugging with proc "Sequence" Files--Part 2

This week, we'll pick up where we left off last week and continue discussing simple kernel and module debugging using seq_file-based proc files. And given the amount of material left to cover, we'll spend this week finishing off the issues related to the simpler, non-sequence proc files, and leave the complicated topic of sequenced writes for a final Part 3 next week, so this will be a relatively short column.

(The archive of all previous "Kernel Newbie Corner" articles can be found here.)

This is ongoing content from the Linux Foundation training program. If you want more content, please consider signing up for one of these classes.

A Quick Recap

As a refresher, let's consider a simple loadable module that represents a solution to last week's exercise and creates the proc file /proc/hz that, when read, displays the kernel tick rate (a value that shouldn't change no matter how many times you display it):

 #include <linux/module.h>
 #include <linux/init.h>
 #include <linux/kernel.h>
 #include <linux/fs.h>
 #include <linux/proc_fs.h>
 #include <linux/seq_file.h>

 static int 
 hz_show(struct seq_file *m, void *v)
 {
     seq_printf(m, "%d\n", HZ);
     return 0;
 }

 static int
 hz_open(struct inode *inode, struct file *file)
 {
     return single_open(file, hz_show, NULL);
 }

 static const struct file_operations hz_fops = {
     .owner	= THIS_MODULE,
     .open	= hz_open,
     .read	= seq_read,
     .llseek	= seq_lseek,
     .release	= single_release,
 };

 static int __init 
 hz_init(void)
 {
     printk(KERN_INFO "Loading hz module, HZ = %d.\n", HZ);
     proc_create("hz", 0, NULL, &hz_fops);
     return 0;
 }

 static void __exit
 hz_exit(void)
 {
     remove_proc_entry("hz", NULL);
     printk(KERN_INFO "Unloading hz module.\n");
 }

 module_init(hz_init);
 module_exit(hz_exit);

 MODULE_LICENSE("GPL"); 

Some quick observations about the above:

• Even though we're continuing to use the seq_file implementation of proc files which supports sequenced writes, we're still showing examples that print so little output that we can use the simpler, "single" variation designed to print all of the output we care about in a single operation. This will change when we finally get to Part 3 next week.
• In case you hadn't figured it out yet, the kernel tick rate is available via the global kernel macro HZ, which is all we need to print.
• Even though we're using printk() to generate some syslog messages upon module entry and exit, those calls are clearly not essential for proper operation of our proc file and, in many cases, proc files like this won't generate any log messages unless something goes wrong.
• We're so confident that nothing can go wrong with our module that we're not even bothering to check return codes in our module entry routine. That's not actually lazy--if you recall, even some of the kernel routines take the same shortcut.

And now that we're all back up to speed, where do we go from here?

What Exactly Can We "Print" From Our proc File?

Notice above how you generate the output from your proc file--with a fairly self-explanatory call to seq_printf(). But there are a number of output primitives you can use for that output, all declared in the kernel header file include/linux/seq_file.h, which you can combine any way you want to produce that output:

 int seq_printf(struct seq_file *, const char *, ...)
 int seq_putc(struct seq_file *m, char c);
 int seq_puts(struct seq_file *m, const char *s);
 int seq_write(struct seq_file *seq, const void *data, size_t len);
 int seq_escape(struct seq_file *, const char *, const char *);
 int seq_path(struct seq_file *, struct path *, char *);
 int seq_dentry(struct seq_file *, struct dentry *, char *);
 int seq_path_root(struct seq_file *m, struct path *path, struct path *root,
                   char *esc); 

The purpose of the first few should be obvious, and you can see the actual implementation and explanations of all of them in the corresponding kernel source file fs/seq_file.c. What's curious is that not all of those output primitives are exported to make them available to modules. The seq_path() function is exported, while the functionally similar seq_path_root() and seq_dentry() functions are not. And for extra confusion, the routine that they are all based on in that same source file, mangle_path() is exported. Does anyone else find that a bit odd?

In any event, it should be clear how you can generate your proc file output with any combination of printing strings, characters, or arbitrary sequences of bytes with any of the above.

Finally, make sure you consider exactly what format you want your proc file output to have. You might be tempted to spruce up the output with labels and headings, but that's just going to get in the way if you want to feed that output into another program. Your best bet is to keep things simple, and generate raw output data, then decide what to do with it from there.

Creating Hierarchical proc Files

Finally, rather than cluttering up the /proc directory with your personal proc files at the top level, you can create a subdirectory and keep multiple proc files in the same place. Here's the relevant snippets from a modified HZ module that creates the file /proc/rday/hz:

 #include <linux/module.h>
 #include <linux/init.h>
 #include <linux/kernel.h>
 #include <linux/fs.h>
 #include <linux/proc_fs.h>
 #include <linux/seq_file.h>

 static struct proc_dir_entry* rday_dir;  // pointer to new dir

 ... snip ...

 static int __init
 hz_init(void)
 {
     rday_dir = proc_mkdir("rday", NULL);
     proc_create("hz", 0, rday_dir, &hz_fops);
     return 0;
 }

 static void __exit
 hz_exit(void)
 {
     remove_proc_entry("hz", rday_dir);
     remove_proc_entry("rday", NULL);
 } 

Note what's changed here. Rather than create my HZ proc file under the (default location of) /proc, I first have to create (and save a global reference to) a new directory called "rday", underneath which I'll create my file. Conversely, if I do it this way, I have to make sure I undo those operations in the reverse order when I unload the module, as you can see above in the exit routine. Simple, no? There's just one new complication.

It's quite possible to write a module that creates a number of useful proc files but, at that point, you might consider actually checking return codes while creating all of your files and directories in case something goes wrong. As you've seen, if you're creating a single file, you can generally cheat and assume it's going to work. But if it gets more complicated, it might be time to start examining return codes, as in:

 static struct proc_dir_entry* rday_dir;

 static int __init
 hz_init(void)
 {
     int retval = 0;
     struct proc_dir_entry* hz_file;

     rday_dir = proc_mkdir("rday", NULL);
     if (rday_dir == NULL) {   // directory creation failed
         retval = -ENOMEM;
         goto out;
     }

     hz_file = proc_create("hz", 0, rday_dir, &hz_fops);
     if (hz_file == NULL) {   // file creation failed
         retval = -ENOMEM;
         goto badfile;
     }

     return 0;

 badfile:
     remove_proc_entry("rday", NULL);
 out:
     return retval;
 } 

Recall from an earlier column that, if things go badly during your module entry routine, it's your responsibility to undo everything you did, and return all claimed resources back to the kernel.

Exercise for the reader: For a more complicated example that creates a number of files and symbolic links, see the file Documentation/DocBook/procfs_example.c in the kernel source tree. That example doesn't actually use the seq_file implementation of proc files, but it is a good example of how much error-checking can be done in a single loadable module.

http://www.linux.com/learn/linux-career-center/39972-kernel-debugging-with-proc-qsequenceq-files-part-2-of-3