lib/scatterlist.c

   1 /*
   2  * Copyright (C) 2007 Jens Axboe <jens.axboe@oracle.com>
   3  *
   4  * Scatterlist handling helpers.
   5  *
   6  * This source code is licensed under the GNU General Public License,
   7  * Version 2. See the file COPYING for more details.
   8  */
   9 #include <linux/export.h>
  10 #include <linux/slab.h>
  11 #include <linux/scatterlist.h>
  12 #include <linux/highmem.h>
  13 #include <linux/kmemleak.h>
  14
  15 /**
  16  * sg_next - return the next scatterlist entry in a list
  17  * @sg:         The current sg entry
  18  *
  19  * Description:
  20  *   Usually the next entry will be @sg@ + 1, but if this sg element is part
  21  *   of a chained scatterlist, it could jump to the start of a new
  22  *   scatterlist array.
  23  *
  24  **/
  25 struct scatterlist *sg_next(struct scatterlist *sg)
  26 {
  27         if (sg_is_last(sg))
  28                 return NULL;
  29
  30         sg++;
  31         if (unlikely(sg_is_chain(sg)))
  32                 sg = sg_chain_ptr(sg);
  33
  34         return sg;
  35 }
  36 EXPORT_SYMBOL(sg_next);
  37
  38 /**
  39  * sg_nents - return total count of entries in scatterlist
  40  * @sg:         The scatterlist
  41  *
  42  * Description:
  43  * Allows to know how many entries are in sg, taking into acount
  44  * chaining as well
  45  *
  46  **/
  47 int sg_nents(struct scatterlist *sg)
  48 {
  49         int nents;
  50         for (nents = 0; sg; sg = sg_next(sg))
  51                 nents++;
  52         return nents;
  53 }
  54 EXPORT_SYMBOL(sg_nents);
  55
  56 /**
  57  * sg_nents_for_len - return total count of entries in scatterlist
  58  *                    needed to satisfy the supplied length
  59  * @sg:         The scatterlist
  60  * @len:        The total required length
  61  *
  62  * Description:
  63  * Determines the number of entries in sg that are required to meet
  64  * the supplied length, taking into acount chaining as well
  65  *
  66  * Returns:
  67  *   the number of sg entries needed, negative error on failure
  68  *
  69  **/
  70 int sg_nents_for_len(struct scatterlist *sg, u64 len)
  71 {
  72         int nents;
  73         u64 total;
  74
  75         if (!len)
  76                 return 0;
  77
  78         for (nents = 0, total = 0; sg; sg = sg_next(sg)) {
  79                 nents++;
  80                 total += sg->length;
  81                 if (total >= len)
  82                         return nents;
  83         }
  84
  85         return -EINVAL;
  86 }
  87 EXPORT_SYMBOL(sg_nents_for_len);
  88
  89 /**
  90  * sg_last - return the last scatterlist entry in a list
  91  * @sgl:        First entry in the scatterlist
  92  * @nents:      Number of entries in the scatterlist
  93  *
  94  * Description:
  95  *   Should only be used casually, it (currently) scans the entire list
  96  *   to get the last entry.
  97  *
  98  *   Note that the @sgl@ pointer passed in need not be the first one,
  99  *   the important bit is that @nents@ denotes the number of entries that
 100  *   exist from @sgl@.
 101  *
 102  **/
 103 struct scatterlist *sg_last(struct scatterlist *sgl, unsigned int nents)
 104 {
 105         struct scatterlist *sg, *ret = NULL;
 106         unsigned int i;
 107
 108         for_each_sg(sgl, sg, nents, i)
 109                 ret = sg;
 110
 111         BUG_ON(!sg_is_last(ret));
 112         return ret;
 113 }
 114 EXPORT_SYMBOL(sg_last);
 115
 116 /**
 117  * sg_init_table - Initialize SG table
 118  * @sgl:           The SG table
 119  * @nents:         Number of entries in table
 120  *
 121  * Notes:
 122  *   If this is part of a chained sg table, sg_mark_end() should be
 123  *   used only on the last table part.
 124  *
 125  **/
 126 void sg_init_table(struct scatterlist *sgl, unsigned int nents)
 127 {
 128         memset(sgl, 0, sizeof(*sgl) * nents);
 129         sg_init_marker(sgl, nents);
 130 }
 131 EXPORT_SYMBOL(sg_init_table);
 132
 133 /**
 134  * sg_init_one - Initialize a single entry sg list
 135  * @sg:          SG entry
 136  * @buf:         Virtual address for IO
 137  * @buflen:      IO length
 138  *
 139  **/
 140 void sg_init_one(struct scatterlist *sg, const void *buf, unsigned int buflen)
 141 {
 142         sg_init_table(sg, 1);
 143         sg_set_buf(sg, buf, buflen);
 144 }
 145 EXPORT_SYMBOL(sg_init_one);
 146
 147 /*
 148  * The default behaviour of sg_alloc_table() is to use these kmalloc/kfree
 149  * helpers.
 150  */
 151 static struct scatterlist *sg_kmalloc(unsigned int nents, gfp_t gfp_mask)
 152 {
 153         if (nents == SG_MAX_SINGLE_ALLOC) {
 154                 /*
 155                  * Kmemleak doesn't track page allocations as they are not
 156                  * commonly used (in a raw form) for kernel data structures.
 157                  * As we chain together a list of pages and then a normal
 158                  * kmalloc (tracked by kmemleak), in order to for that last
 159                  * allocation not to become decoupled (and thus a
 160                  * false-positive) we need to inform kmemleak of all the
 161                  * intermediate allocations.
 162                  */
 163                 void *ptr = (void *) __get_free_page(gfp_mask);
 164                 kmemleak_alloc(ptr, PAGE_SIZE, 1, gfp_mask);
 165                 return ptr;
 166         } else
 167                 return kmalloc(nents * sizeof(struct scatterlist), gfp_mask);
 168 }
 169
 170 static void sg_kfree(struct scatterlist *sg, unsigned int nents)
 171 {
 172         if (nents == SG_MAX_SINGLE_ALLOC) {
 173                 kmemleak_free(sg);
 174                 free_page((unsigned long) sg);
 175         } else
 176                 kfree(sg);
 177 }
 178
 179 /**
 180  * __sg_free_table - Free a previously mapped sg table
 181  * @table:      The sg table header to use
 182  * @max_ents:   The maximum number of entries per single scatterlist
 183  * @skip_first_chunk: don't free the (preallocated) first scatterlist chunk
 184  * @free_fn:    Free function
 185  *
 186  *  Description:
 187  *    Free an sg table previously allocated and setup with
 188  *    __sg_alloc_table().  The @max_ents value must be identical to
 189  *    that previously used with __sg_alloc_table().
 190  *
 191  **/
 192 void __sg_free_table(struct sg_table *table, unsigned int max_ents,
 193                      bool skip_first_chunk, sg_free_fn *free_fn)
 194 {
 195         struct scatterlist *sgl, *next;
 196
 197         if (unlikely(!table->sgl))
 198                 return;
 199
 200         sgl = table->sgl;
 201         while (table->orig_nents) {
 202                 unsigned int alloc_size = table->orig_nents;
 203                 unsigned int sg_size;
 204
 205                 /*
 206                  * If we have more than max_ents segments left,
 207                  * then assign 'next' to the sg table after the current one.
 208                  * sg_size is then one less than alloc size, since the last
 209                  * element is the chain pointer.
 210                  */
 211                 if (alloc_size > max_ents) {
 212                         next = sg_chain_ptr(&sgl[max_ents - 1]);
 213                         alloc_size = max_ents;
 214                         sg_size = alloc_size - 1;
 215                 } else {
 216                         sg_size = alloc_size;
 217                         next = NULL;
 218                 }
 219
 220                 table->orig_nents -= sg_size;
 221                 if (skip_first_chunk)
 222                         skip_first_chunk = false;
 223                 else
 224                         free_fn(sgl, alloc_size);
 225                 sgl = next;
 226         }
 227
 228         table->sgl = NULL;
 229 }
 230 EXPORT_SYMBOL(__sg_free_table);
 231
 232 /**
 233  * sg_free_table - Free a previously allocated sg table
 234  * @table:      The mapped sg table header
 235  *
 236  **/
 237 void sg_free_table(struct sg_table *table)
 238 {
 239         __sg_free_table(table, SG_MAX_SINGLE_ALLOC, false, sg_kfree);
 240 }
 241 EXPORT_SYMBOL(sg_free_table);
 242
 243 /**
 244  * __sg_alloc_table - Allocate and initialize an sg table with given allocator
 245  * @table:      The sg table header to use
 246  * @nents:      Number of entries in sg list
 247  * @max_ents:   The maximum number of entries the allocator returns per call
 248  * @gfp_mask:   GFP allocation mask
 249  * @alloc_fn:   Allocator to use
 250  *
 251  * Description:
 252  *   This function returns a @table @nents long. The allocator is
 253  *   defined to return scatterlist chunks of maximum size @max_ents.
 254  *   Thus if @nents is bigger than @max_ents, the scatterlists will be
 255  *   chained in units of @max_ents.
 256  *
 257  * Notes:
 258  *   If this function returns non-0 (eg failure), the caller must call
 259  *   __sg_free_table() to cleanup any leftover allocations.
 260  *
 261  **/
 262 int __sg_alloc_table(struct sg_table *table, unsigned int nents,
 263                      unsigned int max_ents, struct scatterlist *first_chunk,
 264                      gfp_t gfp_mask, sg_alloc_fn *alloc_fn)
 265 {
 266         struct scatterlist *sg, *prv;
 267         unsigned int left;
 268
 269         memset(table, 0, sizeof(*table));
 270
 271         if (nents == 0)
 272                 return -EINVAL;
 273 #ifndef CONFIG_ARCH_HAS_SG_CHAIN
 274         if (WARN_ON_ONCE(nents > max_ents))
 275                 return -EINVAL;
 276 #endif
 277
 278         left = nents;
 279         prv = NULL;
 280         do {
 281                 unsigned int sg_size, alloc_size = left;
 282
 283                 if (alloc_size > max_ents) {
 284                         alloc_size = max_ents;
 285                         sg_size = alloc_size - 1;
 286                 } else
 287                         sg_size = alloc_size;
 288
 289                 left -= sg_size;
 290
 291                 if (first_chunk) {
 292                         sg = first_chunk;
 293                         first_chunk = NULL;
 294                 } else {
 295                         sg = alloc_fn(alloc_size, gfp_mask);
 296                 }
 297                 if (unlikely(!sg)) {
 298                         /*
 299                          * Adjust entry count to reflect that the last
 300                          * entry of the previous table won't be used for
 301                          * linkage.  Without this, sg_kfree() may get
 302                          * confused.
 303                          */
 304                         if (prv)
 305                                 table->nents = ++table->orig_nents;
 306
 307                         return -ENOMEM;
 308                 }
 309
 310                 sg_init_table(sg, alloc_size);
 311                 table->nents = table->orig_nents += sg_size;
 312
 313                 /*
 314                  * If this is the first mapping, assign the sg table header.
 315                  * If this is not the first mapping, chain previous part.
 316                  */
 317                 if (prv)
 318                         sg_chain(prv, max_ents, sg);
 319                 else
 320                         table->sgl = sg;
 321
 322                 /*
 323                  * If no more entries after this one, mark the end
 324                  */
 325                 if (!left)
 326                         sg_mark_end(&sg[sg_size - 1]);
 327
 328                 prv = sg;
 329         } while (left);
 330
 331         return 0;
 332 }
 333 EXPORT_SYMBOL(__sg_alloc_table);
 334
 335 /**
 336  * sg_alloc_table - Allocate and initialize an sg table
 337  * @table:      The sg table header to use
 338  * @nents:      Number of entries in sg list
 339  * @gfp_mask:   GFP allocation mask
 340  *
 341  *  Description:
 342  *    Allocate and initialize an sg table. If @nents@ is larger than
 343  *    SG_MAX_SINGLE_ALLOC a chained sg table will be setup.
 344  *
 345  **/
 346 int sg_alloc_table(struct sg_table *table, unsigned int nents, gfp_t gfp_mask)
 347 {
 348         int ret;
 349
 350         ret = __sg_alloc_table(table, nents, SG_MAX_SINGLE_ALLOC,
 351                                NULL, gfp_mask, sg_kmalloc);
 352         if (unlikely(ret))
 353                 __sg_free_table(table, SG_MAX_SINGLE_ALLOC, false, sg_kfree);
 354
 355         return ret;
 356 }
 357 EXPORT_SYMBOL(sg_alloc_table);
 358
 359 /**
 360  * __sg_alloc_table_from_pages - Allocate and initialize an sg table from
 361  *                               an array of pages
 362  * @sgt:         The sg table header to use
 363  * @pages:       Pointer to an array of page pointers
 364  * @n_pages:     Number of pages in the pages array
 365  * @offset:      Offset from start of the first page to the start of a buffer
 366  * @size:        Number of valid bytes in the buffer (after offset)
 367  * @max_segment: Maximum size of a scatterlist node in bytes (page aligned)
 368  * @gfp_mask:    GFP allocation mask
 369  *
 370  *  Description:
 371  *    Allocate and initialize an sg table from a list of pages. Contiguous
 372  *    ranges of the pages are squashed into a single scatterlist node up to the
 373  *    maximum size specified in @max_segment. An user may provide an offset at a
 374  *    start and a size of valid data in a buffer specified by the page array.
 375  *    The returned sg table is released by sg_free_table.
 376  *
 377  * Returns:
 378  *   0 on success, negative error on failure
 379  */
 380 int __sg_alloc_table_from_pages(struct sg_table *sgt, struct page **pages,
 381                                 unsigned int n_pages, unsigned int offset,
 382                                 unsigned long size, unsigned int max_segment,
 383                                 gfp_t gfp_mask)
 384 {
 385         unsigned int chunks, cur_page, seg_len, i;
 386         int ret;
 387         struct scatterlist *s;
 388
 389         if (WARN_ON(!max_segment || offset_in_page(max_segment)))
 390                 return -EINVAL;
 391
 392         /* compute number of contiguous chunks */
 393         chunks = 1;
 394         seg_len = 0;
 395         for (i = 1; i < n_pages; i++) {
 396                 seg_len += PAGE_SIZE;
 397                 if (seg_len >= max_segment ||
 398                     page_to_pfn(pages[i]) != page_to_pfn(pages[i - 1]) + 1) {
 399                         chunks++;
 400                         seg_len = 0;
 401                 }
 402         }
 403
 404         ret = sg_alloc_table(sgt, chunks, gfp_mask);
 405         if (unlikely(ret))
 406                 return ret;
 407
 408         /* merging chunks and putting them into the scatterlist */
 409         cur_page = 0;
 410         for_each_sg(sgt->sgl, s, sgt->orig_nents, i) {
 411                 unsigned int j, chunk_size;
 412
 413                 /* look for the end of the current chunk */
 414                 seg_len = 0;
 415                 for (j = cur_page + 1; j < n_pages; j++) {
 416                         seg_len += PAGE_SIZE;
 417                         if (seg_len >= max_segment ||
 418                             page_to_pfn(pages[j]) !=
 419                             page_to_pfn(pages[j - 1]) + 1)
 420                                 break;
 421                 }
 422
 423                 chunk_size = ((j - cur_page) << PAGE_SHIFT) - offset;
 424                 sg_set_page(s, pages[cur_page],
 425                             min_t(unsigned long, size, chunk_size), offset);
 426                 size -= chunk_size;
 427                 offset = 0;
 428                 cur_page = j;
 429         }
 430
 431         return 0;
 432 }
 433 EXPORT_SYMBOL(__sg_alloc_table_from_pages);
 434
 435 /**
 436  * sg_alloc_table_from_pages - Allocate and initialize an sg table from
 437  *                             an array of pages
 438  * @sgt:         The sg table header to use
 439  * @pages:       Pointer to an array of page pointers
 440  * @n_pages:     Number of pages in the pages array
 441  * @offset:      Offset from start of the first page to the start of a buffer
 442  * @size:        Number of valid bytes in the buffer (after offset)
 443  * @gfp_mask:    GFP allocation mask
 444  *
 445  *  Description:
 446  *    Allocate and initialize an sg table from a list of pages. Contiguous
 447  *    ranges of the pages are squashed into a single scatterlist node. A user
 448  *    may provide an offset at a start and a size of valid data in a buffer
 449  *    specified by the page array. The returned sg table is released by
 450  *    sg_free_table.
 451  *
 452  * Returns:
 453  *   0 on success, negative error on failure
 454  */
 455 int sg_alloc_table_from_pages(struct sg_table *sgt, struct page **pages,
 456                               unsigned int n_pages, unsigned int offset,
 457                               unsigned long size, gfp_t gfp_mask)
 458 {
 459         return __sg_alloc_table_from_pages(sgt, pages, n_pages, offset, size,
 460                                            SCATTERLIST_MAX_SEGMENT, gfp_mask);
 461 }
 462 EXPORT_SYMBOL(sg_alloc_table_from_pages);
 463
 464 #ifdef CONFIG_SGL_ALLOC
 465
 466 /**
 467  * sgl_alloc_order - allocate a scatterlist and its pages
 468  * @length: Length in bytes of the scatterlist. Must be at least one
 469  * @order: Second argument for alloc_pages()
 470  * @chainable: Whether or not to allocate an extra element in the scatterlist
 471  *      for scatterlist chaining purposes
 472  * @gfp: Memory allocation flags
 473  * @nent_p: [out] Number of entries in the scatterlist that have pages
 474  *
 475  * Returns: A pointer to an initialized scatterlist or %NULL upon failure.
 476  */
 477 struct scatterlist *sgl_alloc_order(unsigned long long length,
 478                                     unsigned int order, bool chainable,
 479                                     gfp_t gfp, unsigned int *nent_p)
 480 {
 481         struct scatterlist *sgl, *sg;
 482         struct page *page;
 483         unsigned int nent, nalloc;
 484         u32 elem_len;
 485
 486         nent = round_up(length, PAGE_SIZE << order) >> (PAGE_SHIFT + order);
 487         /* Check for integer overflow */
 488         if (length > (nent << (PAGE_SHIFT + order)))
 489                 return NULL;
 490         nalloc = nent;
 491         if (chainable) {
 492                 /* Check for integer overflow */
 493                 if (nalloc + 1 < nalloc)
 494                         return NULL;
 495                 nalloc++;
 496         }
 497         sgl = kmalloc_array(nalloc, sizeof(struct scatterlist),
 498                             (gfp & ~GFP_DMA) | __GFP_ZERO);
 499         if (!sgl)
 500                 return NULL;
 501
 502         sg_init_table(sgl, nalloc);
 503         sg = sgl;
 504         while (length) {
 505                 elem_len = min_t(u64, length, PAGE_SIZE << order);
 506                 page = alloc_pages(gfp, order);
 507                 if (!page) {
 508                         sgl_free(sgl);
 509                         return NULL;
 510                 }
 511
 512                 sg_set_page(sg, page, elem_len, 0);
 513                 length -= elem_len;
 514                 sg = sg_next(sg);
 515         }
 516         WARN_ONCE(length, "length = %lld\n", length);
 517         if (nent_p)
 518                 *nent_p = nent;
 519         return sgl;
 520 }
 521 EXPORT_SYMBOL(sgl_alloc_order);
 522
 523 /**
 524  * sgl_alloc - allocate a scatterlist and its pages
 525  * @length: Length in bytes of the scatterlist
 526  * @gfp: Memory allocation flags
 527  * @nent_p: [out] Number of entries in the scatterlist
 528  *
 529  * Returns: A pointer to an initialized scatterlist or %NULL upon failure.
 530  */
 531 struct scatterlist *sgl_alloc(unsigned long long length, gfp_t gfp,
 532                               unsigned int *nent_p)
 533 {
 534         return sgl_alloc_order(length, 0, false, gfp, nent_p);
 535 }
 536 EXPORT_SYMBOL(sgl_alloc);
 537
 538 /**
 539  * sgl_free_n_order - free a scatterlist and its pages
 540  * @sgl: Scatterlist with one or more elements
 541  * @nents: Maximum number of elements to free
 542  * @order: Second argument for __free_pages()
 543  *
 544  * Notes:
 545  * - If several scatterlists have been chained and each chain element is
 546  *   freed separately then it's essential to set nents correctly to avoid that a
 547  *   page would get freed twice.
 548  * - All pages in a chained scatterlist can be freed at once by setting @nents
 549  *   to a high number.
 550  */
 551 void sgl_free_n_order(struct scatterlist *sgl, int nents, int order)
 552 {
 553         struct scatterlist *sg;
 554         struct page *page;
 555         int i;
 556
 557         for_each_sg(sgl, sg, nents, i) {
 558                 if (!sg)
 559                         break;
 560                 page = sg_page(sg);
 561                 if (page)
 562                         __free_pages(page, order);
 563         }
 564         kfree(sgl);
 565 }
 566 EXPORT_SYMBOL(sgl_free_n_order);
 567
 568 /**
 569  * sgl_free_order - free a scatterlist and its pages
 570  * @sgl: Scatterlist with one or more elements
 571  * @order: Second argument for __free_pages()
 572  */
 573 void sgl_free_order(struct scatterlist *sgl, int order)
 574 {
 575         sgl_free_n_order(sgl, INT_MAX, order);
 576 }
 577 EXPORT_SYMBOL(sgl_free_order);
 578
 579 /**
 580  * sgl_free - free a scatterlist and its pages
 581  * @sgl: Scatterlist with one or more elements
 582  */
 583 void sgl_free(struct scatterlist *sgl)
 584 {
 585         sgl_free_order(sgl, 0);
 586 }
 587 EXPORT_SYMBOL(sgl_free);
 588
 589 #endif /* CONFIG_SGL_ALLOC */
 590
 591 void __sg_page_iter_start(struct sg_page_iter *piter,
 592                           struct scatterlist *sglist, unsigned int nents,
 593                           unsigned long pgoffset)
 594 {
 595         piter->__pg_advance = 0;
 596         piter->__nents = nents;
 597
 598         piter->sg = sglist;
 599         piter->sg_pgoffset = pgoffset;
 600 }
 601 EXPORT_SYMBOL(__sg_page_iter_start);
 602
 603 static int sg_page_count(struct scatterlist *sg)
 604 {
 605         return PAGE_ALIGN(sg->offset + sg->length) >> PAGE_SHIFT;
 606 }
 607
 608 bool __sg_page_iter_next(struct sg_page_iter *piter)
 609 {
 610         if (!piter->__nents || !piter->sg)
 611                 return false;
 612
 613         piter->sg_pgoffset += piter->__pg_advance;
 614         piter->__pg_advance = 1;
 615
 616         while (piter->sg_pgoffset >= sg_page_count(piter->sg)) {
 617                 piter->sg_pgoffset -= sg_page_count(piter->sg);
 618                 piter->sg = sg_next(piter->sg);
 619                 if (!--piter->__nents || !piter->sg)
 620                         return false;
 621         }
 622
 623         return true;
 624 }
 625 EXPORT_SYMBOL(__sg_page_iter_next);
 626
 627 /**
 628  * sg_miter_start - start mapping iteration over a sg list
 629  * @miter: sg mapping iter to be started
 630  * @sgl: sg list to iterate over
 631  * @nents: number of sg entries
 632  *
 633  * Description:
 634  *   Starts mapping iterator @miter.
 635  *
 636  * Context:
 637  *   Don't care.
 638  */
 639 void sg_miter_start(struct sg_mapping_iter *miter, struct scatterlist *sgl,
 640                     unsigned int nents, unsigned int flags)
 641 {
 642         memset(miter, 0, sizeof(struct sg_mapping_iter));
 643
 644         __sg_page_iter_start(&miter->piter, sgl, nents, 0);
 645         WARN_ON(!(flags & (SG_MITER_TO_SG | SG_MITER_FROM_SG)));
 646         miter->__flags = flags;
 647 }
 648 EXPORT_SYMBOL(sg_miter_start);
 649
 650 static bool sg_miter_get_next_page(struct sg_mapping_iter *miter)
 651 {
 652         if (!miter->__remaining) {
 653                 struct scatterlist *sg;
 654                 unsigned long pgoffset;
 655
 656                 if (!__sg_page_iter_next(&miter->piter))
 657                         return false;
 658
 659                 sg = miter->piter.sg;
 660                 pgoffset = miter->piter.sg_pgoffset;
 661
 662                 miter->__offset = pgoffset ? 0 : sg->offset;
 663                 miter->__remaining = sg->offset + sg->length -
 664                                 (pgoffset << PAGE_SHIFT) - miter->__offset;
 665                 miter->__remaining = min_t(unsigned long, miter->__remaining,
 666                                            PAGE_SIZE - miter->__offset);
 667         }
 668
 669         return true;
 670 }
 671
 672 /**
 673  * sg_miter_skip - reposition mapping iterator
 674  * @miter: sg mapping iter to be skipped
 675  * @offset: number of bytes to plus the current location
 676  *
 677  * Description:
 678  *   Sets the offset of @miter to its current location plus @offset bytes.
 679  *   If mapping iterator @miter has been proceeded by sg_miter_next(), this
 680  *   stops @miter.
 681  *
 682  * Context:
 683  *   Don't care if @miter is stopped, or not proceeded yet.
 684  *   Otherwise, preemption disabled if the SG_MITER_ATOMIC is set.
 685  *
 686  * Returns:
 687  *   true if @miter contains the valid mapping.  false if end of sg
 688  *   list is reached.
 689  */
 690 bool sg_miter_skip(struct sg_mapping_iter *miter, off_t offset)
 691 {
 692         sg_miter_stop(miter);
 693
 694         while (offset) {
 695                 off_t consumed;
 696
 697                 if (!sg_miter_get_next_page(miter))
 698                         return false;
 699
 700                 consumed = min_t(off_t, offset, miter->__remaining);
 701                 miter->__offset += consumed;
 702                 miter->__remaining -= consumed;
 703                 offset -= consumed;
 704         }
 705
 706         return true;
 707 }
 708 EXPORT_SYMBOL(sg_miter_skip);
 709
 710 /**
 711  * sg_miter_next - proceed mapping iterator to the next mapping
 712  * @miter: sg mapping iter to proceed
 713  *
 714  * Description:
 715  *   Proceeds @miter to the next mapping.  @miter should have been started
 716  *   using sg_miter_start().  On successful return, @miter->page,
 717  *   @miter->addr and @miter->length point to the current mapping.
 718  *
 719  * Context:
 720  *   Preemption disabled if SG_MITER_ATOMIC.  Preemption must stay disabled
 721  *   till @miter is stopped.  May sleep if !SG_MITER_ATOMIC.
 722  *
 723  * Returns:
 724  *   true if @miter contains the next mapping.  false if end of sg
 725  *   list is reached.
 726  */
 727 bool sg_miter_next(struct sg_mapping_iter *miter)
 728 {
 729         sg_miter_stop(miter);
 730
 731         /*
 732          * Get to the next page if necessary.
 733          * __remaining, __offset is adjusted by sg_miter_stop
 734          */
 735         if (!sg_miter_get_next_page(miter))
 736                 return false;
 737
 738         miter->page = sg_page_iter_page(&miter->piter);
 739         miter->consumed = miter->length = miter->__remaining;
 740
 741         if (miter->__flags & SG_MITER_ATOMIC)
 742                 miter->addr = kmap_atomic(miter->page) + miter->__offset;
 743         else
 744                 miter->addr = kmap(miter->page) + miter->__offset;
 745
 746         return true;
 747 }
 748 EXPORT_SYMBOL(sg_miter_next);
 749
 750 /**
 751  * sg_miter_stop - stop mapping iteration
 752  * @miter: sg mapping iter to be stopped
 753  *
 754  * Description:
 755  *   Stops mapping iterator @miter.  @miter should have been started
 756  *   using sg_miter_start().  A stopped iteration can be resumed by
 757  *   calling sg_miter_next() on it.  This is useful when resources (kmap)
 758  *   need to be released during iteration.
 759  *
 760  * Context:
 761  *   Preemption disabled if the SG_MITER_ATOMIC is set.  Don't care
 762  *   otherwise.
 763  */
 764 void sg_miter_stop(struct sg_mapping_iter *miter)
 765 {
 766         WARN_ON(miter->consumed > miter->length);
 767
 768         /* drop resources from the last iteration */
 769         if (miter->addr) {
 770                 miter->__offset += miter->consumed;
 771                 miter->__remaining -= miter->consumed;
 772
 773                 if ((miter->__flags & SG_MITER_TO_SG) &&
 774                     !PageSlab(miter->page))
 775                         flush_kernel_dcache_page(miter->page);
 776
 777                 if (miter->__flags & SG_MITER_ATOMIC) {
 778                         WARN_ON_ONCE(preemptible());
 779                         kunmap_atomic(miter->addr);
 780                 } else
 781                         kunmap(miter->page);
 782
 783                 miter->page = NULL;
 784                 miter->addr = NULL;
 785                 miter->length = 0;
 786                 miter->consumed = 0;
 787         }
 788 }
 789 EXPORT_SYMBOL(sg_miter_stop);
 790
 791 /**
 792  * sg_copy_buffer - Copy data between a linear buffer and an SG list
 793  * @sgl:                 The SG list
 794  * @nents:               Number of SG entries
 795  * @buf:                 Where to copy from
 796  * @buflen:              The number of bytes to copy
 797  * @skip:                Number of bytes to skip before copying
 798  * @to_buffer:           transfer direction (true == from an sg list to a
 799  *                       buffer, false == from a buffer to an sg list
 800  *
 801  * Returns the number of copied bytes.
 802  *
 803  **/
 804 size_t sg_copy_buffer(struct scatterlist *sgl, unsigned int nents, void *buf,
 805                       size_t buflen, off_t skip, bool to_buffer)
 806 {
 807         unsigned int offset = 0;
 808         struct sg_mapping_iter miter;
 809         unsigned int sg_flags = SG_MITER_ATOMIC;
 810
 811         if (to_buffer)
 812                 sg_flags |= SG_MITER_FROM_SG;
 813         else
 814                 sg_flags |= SG_MITER_TO_SG;
 815
 816         sg_miter_start(&miter, sgl, nents, sg_flags);
 817
 818         if (!sg_miter_skip(&miter, skip))
 819                 return false;
 820
 821         while ((offset < buflen) && sg_miter_next(&miter)) {
 822                 unsigned int len;
 823
 824                 len = min(miter.length, buflen - offset);
 825
 826                 if (to_buffer)
 827                         memcpy(buf + offset, miter.addr, len);
 828                 else
 829                         memcpy(miter.addr, buf + offset, len);
 830
 831                 offset += len;
 832         }
 833
 834         sg_miter_stop(&miter);
 835
 836         return offset;
 837 }
 838 EXPORT_SYMBOL(sg_copy_buffer);
 839
 840 /**
 841  * sg_copy_from_buffer - Copy from a linear buffer to an SG list
 842  * @sgl:                 The SG list
 843  * @nents:               Number of SG entries
 844  * @buf:                 Where to copy from
 845  * @buflen:              The number of bytes to copy
 846  *
 847  * Returns the number of copied bytes.
 848  *
 849  **/
 850 size_t sg_copy_from_buffer(struct scatterlist *sgl, unsigned int nents,
 851                            const void *buf, size_t buflen)
 852 {
 853         return sg_copy_buffer(sgl, nents, (void *)buf, buflen, 0, false);
 854 }
 855 EXPORT_SYMBOL(sg_copy_from_buffer);
 856
 857 /**
 858  * sg_copy_to_buffer - Copy from an SG list to a linear buffer
 859  * @sgl:                 The SG list
 860  * @nents:               Number of SG entries
 861  * @buf:                 Where to copy to
 862  * @buflen:              The number of bytes to copy
 863  *
 864  * Returns the number of copied bytes.
 865  *
 866  **/
 867 size_t sg_copy_to_buffer(struct scatterlist *sgl, unsigned int nents,
 868                          void *buf, size_t buflen)
 869 {
 870         return sg_copy_buffer(sgl, nents, buf, buflen, 0, true);
 871 }
 872 EXPORT_SYMBOL(sg_copy_to_buffer);
 873
 874 /**
 875  * sg_pcopy_from_buffer - Copy from a linear buffer to an SG list
 876  * @sgl:                 The SG list
 877  * @nents:               Number of SG entries
 878  * @buf:                 Where to copy from
 879  * @buflen:              The number of bytes to copy
 880  * @skip:                Number of bytes to skip before copying
 881  *
 882  * Returns the number of copied bytes.
 883  *
 884  **/
 885 size_t sg_pcopy_from_buffer(struct scatterlist *sgl, unsigned int nents,
 886                             const void *buf, size_t buflen, off_t skip)
 887 {
 888         return sg_copy_buffer(sgl, nents, (void *)buf, buflen, skip, false);
 889 }
 890 EXPORT_SYMBOL(sg_pcopy_from_buffer);
 891
 892 /**
 893  * sg_pcopy_to_buffer - Copy from an SG list to a linear buffer
 894  * @sgl:                 The SG list
 895  * @nents:               Number of SG entries
 896  * @buf:                 Where to copy to
 897  * @buflen:              The number of bytes to copy
 898  * @skip:                Number of bytes to skip before copying
 899  *
 900  * Returns the number of copied bytes.
 901  *
 902  **/
 903 size_t sg_pcopy_to_buffer(struct scatterlist *sgl, unsigned int nents,
 904                           void *buf, size_t buflen, off_t skip)
 905 {
 906         return sg_copy_buffer(sgl, nents, buf, buflen, skip, true);
 907 }
 908 EXPORT_SYMBOL(sg_pcopy_to_buffer);
 909
 910 /**
 911  * sg_zero_buffer - Zero-out a part of a SG list
 912  * @sgl:                 The SG list
 913  * @nents:               Number of SG entries
 914  * @buflen:              The number of bytes to zero out
 915  * @skip:                Number of bytes to skip before zeroing
 916  *
 917  * Returns the number of bytes zeroed.
 918  **/
 919 size_t sg_zero_buffer(struct scatterlist *sgl, unsigned int nents,
 920                        size_t buflen, off_t skip)
 921 {
 922         unsigned int offset = 0;
 923         struct sg_mapping_iter miter;
 924         unsigned int sg_flags = SG_MITER_ATOMIC | SG_MITER_TO_SG;
 925
 926         sg_miter_start(&miter, sgl, nents, sg_flags);
 927
 928         if (!sg_miter_skip(&miter, skip))
 929                 return false;
 930
 931         while (offset < buflen && sg_miter_next(&miter)) {
 932                 unsigned int len;
 933
 934                 len = min(miter.length, buflen - offset);
 935                 memset(miter.addr, 0, len);
 936
 937                 offset += len;
 938         }
 939
 940         sg_miter_stop(&miter);
 941         return offset;
 942 }
 943 EXPORT_SYMBOL(sg_zero_buffer);