sg_next() for struct scatterlist is confusing

sg_next() for struct scatterlist is confusing

[Robert P. J. Day]

  according to the inline comments in include/linux/scatterlist.h:

"* If bit 0 is set, then the page_link contains a pointer to the next sg
 * table list. Otherwise the next entry is at sg + 1."

but if that's the case, then the implementation of sg_next() seems a
bit weird:

=================================
/**
 * sg_next - return the next scatterlist entry in a list
 * @sg:         The current sg entry
 *
 * Description:
 *   Usually the next entry will be @sg@ + 1, but if this sg element is part
 *   of a chained scatterlist, it could jump to the start of a new
 *   scatterlist array.
 *
 **/
static inline struct scatterlist *sg_next(struct scatterlist *sg)
{
#ifdef CONFIG_DEBUG_SG
        BUG_ON(sg->sg_magic != SG_MAGIC);
#endif
        if (sg_is_last(sg))
                return NULL;

        sg++;
        if (unlikely(sg_is_chain(sg)))
                sg = sg_chain_ptr(sg);

        return sg;
}
================================

  note how the comment says that the next entry will "usually" be
sg+1, "but" not if it's actually a pointer.

  however, as i read the code above, sg is *always* incremented before
that testing.  is that correct?  am i just misreading something?  or
could the comment have been a bit clearer?

rday


-- 
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: sg_next() for struct scatterlist is confusing

[Haavard Skinnemoen]

On Sat, 27 Oct 2007 07:39:40 -0400 (EDT)
"Robert P. J. Day" <rpjday@crashcourse.ca> wrote:

>   note how the comment says that the next entry will "usually" be
> sg+1, "but" not if it's actually a pointer.
> 
>   however, as i read the code above, sg is *always* incremented before
> that testing.  is that correct?  am i just misreading something?  or
> could the comment have been a bit clearer?

If it increments sg and finds a "chain" entry, it will follow it to the
next sg array instead of just returning it. Which makes sense because
the chain entry itself isn't a valid entry in the sg list.

Håvard

Re: sg_next() for struct scatterlist is confusing

[Robert P. J. Day]

On Sat, 27 Oct 2007, Haavard Skinnemoen wrote:

> On Sat, 27 Oct 2007 07:39:40 -0400 (EDT)
> "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
>
> >   note how the comment says that the next entry will "usually" be
> > sg+1, "but" not if it's actually a pointer.
> >
> >   however, as i read the code above, sg is *always* incremented before
> > that testing.  is that correct?  am i just misreading something?  or
> > could the comment have been a bit clearer?
>
> If it increments sg and finds a "chain" entry, it will follow it to
> the next sg array instead of just returning it. Which makes sense
> because the chain entry itself isn't a valid entry in the sg list.

yes, i finally twigged on that after a few more minutes.  it, of
course, makes sense, but it sure doesn't match the comment that's at
the top of that file.

rday
-- 
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================