Linux Kernel seq_file 接口

14
struct seq_operations;
15

16
struct seq_file {
17
    // buffer
18
    char *buf;
19
    // buffer size
20
    size_t size;
21
    // remaining start
22
    size_t from;
23
    // remaining size
24
    size_t count;
25
    size_t pad_until;
26
    // last show index in list
27
    loff_t index;
28
    // last fd read_pos
29
    loff_t read_pos;
30
    // fd thread-safe guard
31
    struct mutex lock;
32
    const struct seq_operations *op;
33
    int poll_event;
34
    const struct file *file;
35
    // preserve data pointer to any data we want to store
36
    void *private;
37
};
38

39
struct seq_operations {
40
    // setup seq_file with index, return the item pointer
41
    // e.g. we can lock write lock and find the item by index(named pos)
42
    void * (*start) (struct seq_file *m, loff_t *pos);
43
    // finish/cleanup seq_file feeding with given item
44
    // e.g. we can unlock write lock
45
    void (*stop) (struct seq_file *m, void *v);
46
    // roll to next item in list given pos and last item, return new item
47
    // e.g. go throught next pointer and update last_pos
48
    void * (*next) (struct seq_file *m, void *v, loff_t *pos);
49
    // dump item pointer to buffer in seq_file
50
    // e.g. snprintf or memcpy and update count/size
51
    int (*show) (struct seq_file *m, void *v);
52
};

40
/**
41
 * seq_has_overflowed - check if the buffer has overflowed
42
 * @m: the seq_file handle
43
 *
44
 * seq_files have a buffer which may overflow. When this happens a larger
45
 * buffer is reallocated and all the data will be printed again.
46
 * The overflow state is true when m->count == m->size.
47
 *
48
 * Returns true if the buffer received more than it can hold.
49
 */
50
static inline bool seq_has_overflowed(struct seq_file *m)
51
{
52
    return m->count == m->size;
53
}

216
static __always_inline __must_check
217
size_t copy_to_iter(const void *addr, size_t bytes, struct iov_iter *i)
218
{
219
    if (check_copy_size(addr, bytes, true))
220
        return _copy_to_iter(addr, bytes, i);
221
    return 0;
222
}

90
static int traverse(struct seq_file *m, loff_t offset)
91
{
92
    loff_t pos = 0;
93
    int error = 0;
94
    void *p;
95

96
    m->index = 0;
97
    m->count = m->from = 0;
98
    if (!offset)
99
        return 0;
100

101
    if (!m->buf) {
102
        // init default size buffer
103
        m->buf = seq_buf_alloc(m->size = PAGE_SIZE);
104
        if (!m->buf)
105
            return -ENOMEM;
106
    }
107
    // start with given index
108
    p = m->op->start(m, &m->index);
109
    while (p) {
110
        error = PTR_ERR(p);
111
        if (IS_ERR(p))
112
            break;
113
        // dump current item
114
        error = m->op->show(m, p);
115
        if (error < 0)
116
            break;
117
        if (unlikely(error)) {
118
            error = 0;
119
            m->count = 0;
120
        }
121
        if (seq_has_overflowed(m))
122
            goto Eoverflow;
123
        // go next item
124
        p = m->op->next(m, p, &m->index);
125
        // if current buffer exceed required offset
126
        // update from and buffer remaining count
127
        if (pos + m->count > offset) {
128
            m->from = offset - pos;
129
            m->count -= m->from;
130
            break;
131
        }
132
        // otherwise just keep iterate till it reached
133
        pos += m->count;
134
        // update buffer remaining size to zero caused it's before required offset
135
        m->count = 0;
136
        // if reached/perfect match
137
        if (pos == offset)
138
            break;
139
    }
140
    // cleanup
141
    m->op->stop(m, p);
142
    return error;
143

144
Eoverflow:
145
    m->op->stop(m, p);
146
    kvfree(m->buf);
147
    m->count = 0;
148
    // if overflow get bigger buffer and redo the process
149
    m->buf = seq_buf_alloc(m->size <<= 1);
150
    return !m->buf ? -ENOMEM : -EAGAIN;
151
}

41
/**
42
 *  seq_open -  initialize sequential file
43
 *  @file: file we initialize
44
 *  @op: method table describing the sequence
45
 *
46
 *  seq_open() sets @file, associating it with a sequence described
47
 *  by @op.  @op->start() sets the iterator up and returns the first
48
 *  element of sequence. @op->stop() shuts it down.  @op->next()
49
 *  returns the next element of sequence.  @op->show() prints element
50
 *  into the buffer.  In case of error ->start() and ->next() return
51
 *  ERR_PTR(error).  In the end of sequence they return %NULL. ->show()
52
 *  returns 0 in case of success and negative number in case of error.
53
 *  Returning SEQ_SKIP means "discard this element and move on".
54
 *  Note: seq_open() will allocate a struct seq_file and store its
55
 *  pointer in @file->private_data. This pointer should not be modified.
56
 */
57
int seq_open(struct file *file, const struct seq_operations *op)
58
{
59
    struct seq_file *p;
60

61
    WARN_ON(file->private_data);
62

63
    p = kmem_cache_zalloc(seq_file_cache, GFP_KERNEL);
64
    if (!p)
65
        return -ENOMEM;
66

67
    // set private data to seq_file struct
68
    file->private_data = p;
69

70
    mutex_init(&p->lock);
71
    p->op = op;
72

73
    // No refcounting: the lifetime of 'p' is constrained
74
    // to the lifetime of the file.
75
    p->file = file;
76

77
    /*
78
     * seq_files support lseek() and pread().  They do not implement
79
     * write() at all, but we clear FMODE_PWRITE here for historical
80
     * reasons.
81
     *
82
     * If a client of seq_files a) implements file.write() and b) wishes to
83
     * support pwrite() then that client will need to implement its own
84
     * file.open() which calls seq_open() and then sets FMODE_PWRITE.
85
     */
86
    file->f_mode &= ~FMODE_PWRITE;
87
    return 0;
88
}
89
EXPORT_SYMBOL(seq_open);

142
/**
143
 *  seq_read -  ->read() method for sequential files.
144
 *  @file: the file to read from
145
 *  @buf: the buffer to read to
146
 *  @size: the maximum number of bytes to read
147
 *  @ppos: the current position in the file
148
 *
149
 *  Ready-made ->f_op->read()
150
 */
151
ssize_t seq_read(struct file *file, char __user *buf, size_t size, loff_t *ppos)
152
{
153
    // construct a iov request from one-time read
154
    struct iovec iov = { .iov_base = buf, .iov_len = size};
155
    struct kiocb kiocb;
156
    struct iov_iter iter;
157
    ssize_t ret;
158

159
    init_sync_kiocb(&kiocb, file);
160
    iov_iter_init(&iter, ITER_DEST, &iov, 1, size);
161

162
    kiocb.ki_pos = *ppos;
163
    // enter real read function
164
    ret = seq_read_iter(&kiocb, &iter);
165
    *ppos = kiocb.ki_pos;
166
    return ret;
167
}
168
EXPORT_SYMBOL(seq_read);
169

170
/*
171
 * Ready-made ->f_op->read_iter()
172
 */
173
ssize_t seq_read_iter(struct kiocb *iocb, struct iov_iter *iter)
174
{
175
    struct seq_file *m = iocb->ki_filp->private_data;
176
    size_t copied = 0;
177
    size_t n;
178
    void *p;
179
    int err = 0;
180

181
    // if request to read 0 byte
182
    if (!iov_iter_count(iter))
183
        return 0;
184

185
    // make sure only one thread enter
186
    mutex_lock(&m->lock);
187

188
    /*
189
     * if request is to read from zero offset, reset iterator to first
190
     * record as it might have been already advanced by previous requests
191
     */
192
    if (iocb->ki_pos == 0) {
193
        m->index = 0;
194
        m->count = 0;
195
    }
196

197
    /* Don't assume ki_pos is where we left it */
198
    if (unlikely(iocb->ki_pos != m->read_pos)) {
199
        // because our record position doesn't match the required position
200
        // it's likely because user want to read from a discrete position
201
        // so we need to re-find/reach to that position from beginning by calling traverse
202
        while ((err = traverse(m, iocb->ki_pos)) == -EAGAIN)
203
            ;
204
        if (err) {
205
            /* With prejudice... */
206
            m->read_pos = 0;
207
            m->index = 0;
208
            m->count = 0;
209
            goto Done;
210
        } else {
211
            m->read_pos = iocb->ki_pos;
212
        }
213
    }
214

215
    /* grab buffer if we didn't have one */
216
    if (!m->buf) {
217
        m->buf = seq_buf_alloc(m->size = PAGE_SIZE);
218
        if (!m->buf)
219
            goto Enomem;
220
    }
221
    // something left in the buffer - copy it out first
222
    if (m->count) {
223
        n = copy_to_iter(m->buf + m->from, m->count, iter);
224
        m->count -= n;
225
        // update start from position for next read(if still something remaining)
226
        m->from += n;
227
        copied += n;
228
        if (m->count)   // hadn't managed to copy everything
229
            goto Done;
230
    }
231
    // get a non-empty record in the buffer
232
    m->from = 0;
233
    p = m->op->start(m, &m->index);
234
    // then fetch one non-empty item into buffer
235
    while (1) {
236
        err = PTR_ERR(p);
237
        if (!p || IS_ERR(p))    // EOF or an error
238
            break;
239
        err = m->op->show(m, p);
240
        if (err < 0)        // hard error
241
            break;
242
        if (unlikely(err))  // ->show() says "skip it"
243
            m->count = 0;
244
        if (unlikely(!m->count)) { // empty record
245
            p = m->op->next(m, p, &m->index);
246
            continue;
247
        }
248
        if (!seq_has_overflowed(m)) // got it
249
            goto Fill;
250
        // need a bigger buffer
251
        m->op->stop(m, p);
252
        kvfree(m->buf);
253
        m->count = 0;
254
        m->buf = seq_buf_alloc(m->size <<= 1);
255
        if (!m->buf)
256
            goto Enomem;
257
        p = m->op->start(m, &m->index);
258
    }
259
    // EOF or an error
260
    m->op->stop(m, p);
261
    m->count = 0;
262
    goto Done;
263
Fill:
264
    // one non-empty record is in the buffer; if they want more,
265
    // try to fit more in, but in any case we need to advance
266
    // the iterator once for every record shown.
267
    while (1) {
268
        size_t offs = m->count;
269
        loff_t pos = m->index;
270

271
        p = m->op->next(m, p, &m->index);
272
        if (pos == m->index) {
273
            pr_info_ratelimited("buggy .next function %ps did not update position index\n",
274
                        m->op->next);
275
            m->index++;
276
        }
277
        if (!p || IS_ERR(p))    // no next record for us
278
            break;
279
        if (m->count >= iov_iter_count(iter))
280
            break;
281
        err = m->op->show(m, p);
282
        if (err > 0) {      // ->show() says "skip it"
283
            m->count = offs;
284
        } else if (err || seq_has_overflowed(m)) {
285
            m->count = offs;
286
            break;
287
        }
288
    }
289
    m->op->stop(m, p);
290
    // feed the request from buffer
291
    n = copy_to_iter(m->buf, m->count, iter);
292
    copied += n;
293
    m->count -= n;
294
    m->from = n;
295
Done:
296
    if (unlikely(!copied)) {
297
        copied = m->count ? -EFAULT : err;
298
    } else {
299
        iocb->ki_pos += copied;
300
        m->read_pos += copied;
301
    }
302
    mutex_unlock(&m->lock);
303
    return copied;
304
Enomem:
305
    err = -ENOMEM;
306
    goto Done;
307
}
308
EXPORT_SYMBOL(seq_read_iter);