: MEMSTICK: My 2 drivers for 2.6.38 inclusion

While developing memstick driver for legacy memsticks I found the need in few helpers that I think should be in common scatterlist library

The functions that were added:

* sg_nents/sg_total_len - iterate over scatterlist to figure out total length of memory it covers / number of entries. Useful for not keeping that information in side channels.

* sg_copy/sg_advance - Allow to break scatterlists apart into smaller chunks. sg_copy creates smaller scatterlist, spanning first 'len' bytes, while sg_advance edits the scatterlist in such way that it skips over 'len' bytes.

* sg_compare_to_buffer - another function to hide gory details of access to sg list by CPU.
Allows to transparently compare contents of the sg list to given linear buffer.
If needed later, a function that compares two sgs can be added.

All of this code is used by my ms_block.c driver.

---
 include/linux/scatterlist.h |    6 ++
 lib/scatterlist.c           |  137 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+), 0 deletions(-)

lib/scatterlist.c +0 -0

index 4ceb05d..2f18938 100644

lib/scatterlist.c +22 -0

+ */
+struct scatterlist *sg_advance(struct scatterlist *sg, int consumed)
+{
+	while (consumed >= sg->length) {
+		consumed -= sg->length;
+
+		sg = sg_next(sg);
+		if (!sg)
+			break;
+	}
+
+	WARN_ON(!sg && consumed);
+
+	if (!sg)
+		return NULL;
+
+	sg->offset += consumed;
+	sg->length -= consumed;
+
+	if (sg->offset >= PAGE_SIZE) {
+		struct page *page =
+			nth_page(sg_page(sg), sg->offset / PAGE_SIZE);

lib/scatterlist.c +6 -0

+ * assumption that last entry is NULL
+ */
+int sg_nents(struct scatterlist *sg)
+{
+	int nents = 0;
+	while (sg) {

lib/scatterlist.c +14 -0

+ * based on assumption that list ends with a NULL entry
+ */
+int sg_total_len(struct scatterlist *sg)
+{
+	int len = 0;
+	while (sg) {
+		len += sg->length;
+		sg = sg_next(sg);
+	}
+	return len;
+}
+EXPORT_SYMBOL(sg_total_len);
+
+/**
  * sg_last - return the last scatterlist entry in a list
  * @sgl:	First entry in the scatterlist
  * @nents:	Number of entries in the scatterlist

lib/scatterlist.c +24 -0

+ */
+int sg_copy(struct scatterlist *sg_from, struct scatterlist *sg_to, int len)
+{
+	while (len > sg_from->length) {
+		len -= sg_from->length;
+
+		sg_set_page(sg_to, sg_page(sg_from),
+				sg_from->length, sg_from->offset);
+
+		sg_to = sg_next(sg_to);
+		sg_from = sg_next(sg_from);
+
+		if (len && (!sg_from || !sg_to))
+			return -ENOMEM;
+	}
+
+	if (len)
+		sg_set_page(sg_to, sg_page(sg_from),
+				len, sg_from->offset);
+	sg_mark_end(sg_to);
+	return 0;
+}
+EXPORT_SYMBOL(sg_copy);
+
 /*
  * The default behaviour of sg_alloc_table() is to use these kmalloc/kfree
  * helpers.

Quoted 4 lines

/**
+ * sg_advance - advance scatterlist by 'consumed' bytes
+ * @sg - the current sg entry
+ * @consumed - how much bytes to advance

kernel-doc notation for parameters is like so:

Quoted 5 lines · On Tue, 11 Jan 2011 15:51:24 -0800 Randy Dunlap <[email protected]> wrote:

Quoted 4 lines

/**
+ * sg_advance - advance scatterlist by 'consumed' bytes
+ * @sg - the current sg entry
+ * @consumed - how much bytes to advance

Quoted 1 line

kernel-doc notation for parameters is like so:

I think I fixed most of this. Probably missed some though.

Teach checkpatch to check kerneldoc ;)

From: Andrew Morton <[email protected]>

fix general disaster in code comments

Cc Alex Dubov <[email protected]>

Cc James Bottomley <[email protected]>

Cc Jens Axboe <[email protected]>

Cc Maxim Levitsky <[email protected]>

Cc Tejun Heo <[email protected]>

Signed-off-by Andrew Morton <[email protected]>

---

 lib/scatterlist.c |   31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff -puN lib/scatterlist.c~scatterlist-new-helper-functions-fix lib/scatterlist.c

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +2 -2

  *
- * Allows to calculate dynamicly the lenght of the sg table, based on
- * assumption that last entry is NULL
+ * Allows to calculate aldynamicly the length of the sg table, based on an
+ * assumption that the last entry is NULL
  */
 int sg_nents(struct scatterlist *sg)
 {

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +9 -3

+ * based on an assumption that the list ends with a NULL entry
  */
 int sg_total_len(struct scatterlist *sg)
 {

@@ -182,8 +182,14 @@ void sg_init_one(struct scatterlist *sg,
 EXPORT_SYMBOL(sg_init_one);
 
 /**
- * sg_copy - copies sg entries from sg_from to sg_to, such
- * as sg_to covers first 'len' bytes from sg_from.
+ * sg_copy - copy sg entries
+ * @sg_from: source
+ * @sg_to: destination
+ *
+ * Copies from @sg_from to @sg_to.  @sg_to covers first 'len' bytes from
+ * @sg_from.
+ *
+ * Returns zero on success, else a -ve errno.
  */
 int sg_copy(struct scatterlist *sg_from, struct scatterlist *sg_to, int len)
 {

@@ -616,13 +622,12 @@ size_t sg_copy_to_buffer(struct scatterl
 }
 EXPORT_SYMBOL(sg_copy_to_buffer);
 
-

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +0 -0

  */
 bool sg_compare_to_buffer(struct scatterlist *sg, u8 *buffer, size_t len)
 {

_

Quoted 8 lines · On Tue, 11 Jan 2011 15:55:11 -0800 Andrew Morton wrote:

Quoted 5 lines · On Tue, 11 Jan 2011 15:51:24 -0800 Randy Dunlap <[email protected]> wrote:

Quoted 4 lines

/**
+ * sg_advance - advance scatterlist by 'consumed' bytes
+ * @sg - the current sg entry
+ * @consumed - how much bytes to advance

Quoted 6 lines

Quoted 1 line

kernel-doc notation for parameters is like so:

I think I fixed most of this. Probably missed some though.

Teach checkpatch to check kerneldoc ;)

ugh, no thanks.

Quoted 21 lines

From: Andrew Morton <[email protected]>

fix general disaster in code comments

Cc Alex Dubov <[email protected]>

Cc James Bottomley <[email protected]>

Cc Jens Axboe <[email protected]>

Cc Maxim Levitsky <[email protected]>

Cc Tejun Heo <[email protected]>

Signed-off-by Andrew Morton <[email protected]>

---

 lib/scatterlist.c |   31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff -puN lib/scatterlist.c~scatterlist-new-helper-functions-fix lib/scatterlist.c

lib/scatterlist.c EXPORT_SYMBOL(sg_next); · line 44

Quoted 5 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +1 -1

@@ -41,7 +41,7 @@ EXPORT_SYMBOL(sg_next);
 /**
  * sg_advance - advance scatterlist by 'consumed' bytes
  * @sg - the current sg entry
- * @consumed - how much bytes to advance
+ * @consumed - how many bytes to advance

* @consumed: how many bytes to advance

lib/scatterlist.c EXPORT_SYMBOL(sg_advance); · line 77

Quoted 6 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +0 -0

  *
  */
 struct scatterlist *sg_advance(struct scatterlist *sg, int consumed)

@@ -76,8 +76,8 @@ EXPORT_SYMBOL(sg_advance);
  * sg_nents - calculate number of sg entries in sg list
  * @sg - the current sg entry

* @sg:

Quoted 9 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +2 -2

  *
- * Allows to calculate dynamicly the lenght of the sg table, based on
- * assumption that last entry is NULL
+ * Allows to calculate aldynamicly the length of the sg table, based on an
+ * assumption that the last entry is NULL
  */
 int sg_nents(struct scatterlist *sg)
 {

lib/scatterlist.c int sg_nents(struct scatterlist *sg) · line 96

Quoted 6 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +1 -1

@@ -92,11 +92,11 @@ int sg_nents(struct scatterlist *sg)
 EXPORT_SYMBOL(sg_nents);
 
 /**
- * sg_total_len - calculate total lenght of scatterlist
+ * sg_total_len - calculate total length of scatterlist
  * @sg - the current sg entry

* @sg:

lib/scatterlist.c int sg_nents(struct scatterlist *sg) · line 98

Quoted 4 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +1 -2

  *
- * Dynamicly calculate total number of bytes in a sg list
- * based on assumption that list ends with a NULL entry
+ * Dynamically calculate total number of bytes in a sg list

preferably:
in an sg list

Quoted 25 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +9 -2

+ * based on an assumption that the list ends with a NULL entry
  */
 int sg_total_len(struct scatterlist *sg)
 {

@@ -182,8 +182,14 @@ void sg_init_one(struct scatterlist *sg,
 EXPORT_SYMBOL(sg_init_one);
 
 /**
- * sg_copy - copies sg entries from sg_from to sg_to, such
- * as sg_to covers first 'len' bytes from sg_from.
+ * sg_copy - copy sg entries
+ * @sg_from: source
+ * @sg_to: destination
+ *
+ * Copies from @sg_from to @sg_to.  @sg_to covers first 'len' bytes from
+ * @sg_from.
+ *
+ * Returns zero on success, else a -ve errno.
  */
 int sg_copy(struct scatterlist *sg_from, struct scatterlist *sg_to, int len)
 {

@@ -616,13 +622,12 @@ size_t sg_copy_to_buffer(struct scatterl
 }
 EXPORT_SYMBOL(sg_copy_to_buffer);
 

lib/scatterlist.c size_t sg_copy_to_buffer(struct scatterl · line 630

Quoted 11 lines

lib/scatterlist.c renamed from lib/scatterlist.c~scatterlist-new-helper-functions-fix +4 -5

-
 /**
- * sg_compare_to_buffer - compare contents of the data pointeted by sg table
+ * sg_compare_to_buffer - compare contents of the data covered by an sg table
  * to a kernel ram buffer
- * @sg - the current sg entry
- * @buffer - linear buffer to compare with
- * @len - lenght of that buffer
+ * @sg: the current sg entry
+ * @buffer: linear buffer to compare with
+ * @len: length of that buffer

Returns what??

Quoted 11 lines

Quoted 10 lines

/**
- * sg_compare_to_buffer - compare contents of the data pointeted by sg table
+ * sg_compare_to_buffer - compare contents of the data covered by an sg table
* to a kernel ram buffer
- * @sg - the current sg entry
- * @buffer - linear buffer to compare with
- * @len - lenght of that buffer
+ * @sg: the current sg entry
+ * @buffer: linear buffer to compare with
+ * @len: length of that buffer

Quoted 1 line

Returns what??

0 if equal and 1 otherwise.
Was too lazy to implement full strcmp compliance. Is that needed?

All very fair comments.
Will check everything once again. Thanks for a review!

Best regards,
Maxim Levitsky

--