seq_file operations, with PPP dump implimentation

<1>intro

with kernel module and function impliment, we usually export some info to let others know its running status.

and to make it, to traditional way is to write an "proc" entry by "create_proc_entry". but you'll always think that to achieve this simple purpose to much extra works are done but not the task you should force on.

linux kernel do have a better way! that's the seq_file way.

all the centrel is to present your data with "seq_start/next/show/stop", just like what misc driver do for char device modules.

<2>ppp impl

as it is not a new topic for this, and i just find one place to have a try.

+//=======================================================+#ifdef CONFIG_PROC_FS+struct ppp_seq_iter {+    struct seq_net_private p;+    int index;+};++static void *ppp_channel_seq_start(struct seq_file *m, loff_t *pos) {+    struct ppp_seq_iter *iter = m->private;+    struct ppp_net *pn = ppp_pernet(seq_file_net(m));+    struct channel *pch;+    int index = iter->index;+    if (*pos == 0) {+        printk(KERN_INFO "ppp_channel_seq_start: pos==0\n");+        return SEQ_START_TOKEN;+    }++    //initialed as index 0 here, after stopped, it should also be 0+    if(index == 0) return NULL;+    mutex_lock(&ppp_mutex);++    spin_lock_bh(&pn->all_channels_lock);+    pch = ppp_find_channel(pn, index);+    if(pch) atomic_inc(&pch->file.refcnt);+    spin_unlock_bh(&pn->all_channels_lock);++    mutex_unlock(&ppp_mutex);++    return pch;+}++static void *ppp_channel_seq_next(struct seq_file *m, void *v, loff_t *pos) {+    struct ppp_seq_iter *iter = m->private;+    struct ppp_net *pn = ppp_pernet(seq_file_net(m));+    struct channel *pch;+    int index = iter->index - 1;++    mutex_lock(&ppp_mutex);++    spin_lock_bh(&pn->all_channels_lock);+    //first search+    if(v == SEQ_START_TOKEN) {+        index = pn->last_channel_index;+    }++    while (index >= 0) {+    pch = ppp_find_channel(pn, index);+    if(pch) {+        iter->index = index;+    break;+        }+    index--;+    }+    if(pch) atomic_inc(&pch->file.refcnt);+    spin_unlock_bh(&pn->all_channels_lock);++    mutex_unlock(&ppp_mutex);++    return pch;+}++static int ppp_channel_seq_show(struct seq_file *m, void *v) {+    struct channel *pch = v;+    struct ppp_net *pn = ppp_pernet(seq_file_net(m));++    if (v == SEQ_START_TOKEN) {+        seq_printf(m, " total channel: %d\n", atomic_read(&channel_count));+        seq_puts(m, "- - - - -\n");+        seq_printf(m, " channel dead \t %-12s %-12s %16s %s closing\n",+            "xq", "rq", "chan", "ppp");+        seq_puts(m, "---------\n");+    } else {+    //printk(KERN_INFO " ppp_channel_seq_show: %d <> %d in m\n",+        //pch->file.index, ((struct ppp_seq_iter *)(m->private))->index);+    if (pch != NULL) {+        //pch->file.refcnt > 0, no lock needed, just care the ppp+        mutex_lock(&pn->all_ppp_mutex);+        seq_printf(m, " %-8d %d \t %-12u %-12u %p %s %-4d\n",+            pch->file.index, pch->file.dead,+            skb_queue_len(&pch->file.xq), skb_queue_len(&pch->file.rq),+            pch->chan, (pch->ppp&&pch->ppp->dev)? pch->ppp->dev->name: "NULL",+            pch->ppp? pch->ppp->closing: -1);+        mutex_unlock(&pn->all_ppp_mutex);++        if (atomic_dec_and_test(&pch->file.refcnt)) {+            ppp_destroy_channel(pch);+        }+    } else {+        seq_printf(m, " channel: %d not exists!\n",+            ((struct ppp_seq_iter *)(m->private))->index-1);+    }+    }++       return 0;+}++static void ppp_channel_seq_stop(struct seq_file *m, void *v) {+    struct ppp_seq_iter *iter = m->private;+    iter->index=0;+}++static const struct seq_operations raw_seq_ops = {+       .start = ppp_channel_seq_start,+       .next  = ppp_channel_seq_next,+       .stop  = ppp_channel_seq_stop,+       .show  = ppp_channel_seq_show,+};++static int ppp_seq_open(struct inode *inode, struct file *file)+{+       return seq_open_net(inode, file, &raw_seq_ops,+                sizeof(struct ppp_seq_iter));+}++static const struct file_operations ppp_seq_fops = {+       .owner   = THIS_MODULE,+       .open    = ppp_seq_open,+       .read    = seq_read,+       .llseek  = seq_lseek,+       .release = seq_release_net,+};+#endif+ static __net_init int ppp_init_net(struct net *net) {        struct ppp_net *pn = net_generic(net, ppp_net_id);@@ -887,6 +1018,12 @@ static __net_init int ppp_init_net(struct net *net)         spin_lock_init(&pn->all_channels_lock); +#ifdef CONFIG_PROC_FS+       if (!proc_create("pppnet", S_IRUGO, net->proc_net, &ppp_seq_fops)) {+               printk(KERN_INFO "ppp sysfs create fail\n");+    }+#endif+        return 0; }

it is an diff for "drivers/net/ppp/ppp_generic.c" as above shows.

all file_operations are done for us and only one "open" left. and in that open functions you provide the real seq_operations needed and an size of any size according.

there is much more manual details about it from lkmpg/x861 and seqfile howto, you can check it directly, so i'll not repeat.

<3>seq_file secrets

the screct of seq_file is just from its "open" function

 int seq_open(struct file *file, const struct seq_operations *op)  {          struct seq_file *p;            WARN_ON(file->private_data);            p = kzalloc(sizeof(*p), GFP_KERNEL);          if (!p)                  return -ENOMEM;            file->private_data = p;            mutex_init(&p->lock);          p->op = op;  #ifdef CONFIG_USER_NS          p->user_ns = file->f_cred->user_ns;  #endif  void *__seq_open_private(struct file *f, const struct seq_operations *ops,                 int psize) {         int rc;         void *private;         struct seq_file *seq;          private = kzalloc(psize, GFP_KERNEL);         if (private == NULL)                 goto out;          rc = seq_open(f, ops);         if (rc < 0)                 goto out_free;          seq = f->private_data;         seq->private = private;         return private;  out_free:         kfree(private); out:         return NULL; } EXPORT_SYMBOL(__seq_open_private);  int seq_open_private(struct file *filp, const struct seq_operations *ops,                 int psize) {         return __seq_open_private(filp, ops, psize) ? 0 : -ENOMEM; } EXPORT_SYMBOL(seq_open_private);

it alloc and initialize an seq_file object and attach your implimented operations to the original file struct, it also alloc memory for your transfered private data size.

and this memory is just for your own usage. you can do wahtever you'd like for that.

all other seq_open_XXX functions just an wrap of seq_open_private with changing the private data size, namely the param "psize".

our seq_open_net just make it alloc more memory to store our net struct if needed. and i just defined another own struct which wrapped the original net_private struct to store one more integer value.

all other seq_XXX functions related to file_operations call an traver function:

"static int traverse(struct seq_file *m, loff_t offset)"

its logic is just what our previous linked "lkmpg/x861" elaborates, it is really worh reading.

as i'm not able to repeat as clear as the referenced article do, just paste the code directly

          m->version = 0;         index = 0;         m->count = m->from = 0;         if (!offset) {                 m->index = index;                 return 0;         }         if (!m->buf) {                 m->buf = seq_buf_alloc(m->size = PAGE_SIZE);                 if (!m->buf)                         return -ENOMEM;         }         p = m->op->start(m, &index);//------------------<---your own start function         while (p) {                 error = PTR_ERR(p);                 if (IS_ERR(p))                         break;                 error = m->op->show(m, p);//------------<---your own show function                 if (error < 0)                         break;                 if (unlikely(error)) {                         error = 0;                         m->count = 0;                 }                 if (seq_has_overflowed(m))                         goto Eoverflow;                 if (pos + m->count > offset) {                         m->from = offset - pos;                         m->count -= m->from;                         m->index = index;                         break;                 }                 pos += m->count;                 m->count = 0;                 if (pos == offset) {                         index++;                         m->index = index;                         break;                 }                 p = m->op->next(m, p, &index);//------------<---your own next function         }         m->op->stop(m, p);//--------------------------------<---your own stop function         m->index = index;         return error;  Eoverflow:         m->op->stop(m, p);         kvfree(m->buf);         m->count = 0;         m->buf = seq_buf_alloc(m->size <<= 1);         return !m->buf ? -ENOMEM : -EAGAIN; }

it starts with your start function and end with stop function, using next function to traverse all data entrys and show them accordingly till NULL got.

just repeat one as below for it is really impartant.

BE CARREFUL: when a sequence is finished, another one starts. That means that at the end of function stop(), the function start() is called again. This loop finishes when the function start() returns NULL. You can see a scheme of this in the figure "How seq_file works".

the figure lie in the lkmpg link.

one other notice from my own, not lock, is that:

do learn your own data entriy structures clear to make sure it is rightly shown under any conditions.

<4>references

http://lxr.free-electrons.com/source/fs/seq_file.c

http://kernelnewbies.org/Documents/SeqFileHowTo

http://linux.die.net/lkmpg/x861.html