LCOV - code coverage report
Current view: top level - lkbce/include/linux - scatterlist.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 2 2 100.0 %
Date: 2017-01-25 Functions: 0 0 -

          Line data    Source code
       1             : #ifndef _LINUX_SCATTERLIST_H
       2             : #define _LINUX_SCATTERLIST_H
       3             : 
       4             : #include <asm/types.h>
       5             : #include <asm/scatterlist.h>
       6             : #include <linux/mm.h>
       7             : #include <linux/string.h>
       8             : #include <asm/io.h>
       9             : 
      10             : struct sg_table {
      11             :         struct scatterlist *sgl;        /* the list */
      12             :         unsigned int nents;             /* number of mapped entries */
      13             :         unsigned int orig_nents;        /* original size of list */
      14             : };
      15             : 
      16             : /*
      17             :  * Notes on SG table design.
      18             :  *
      19             :  * Architectures must provide an unsigned long page_link field in the
      20             :  * scatterlist struct. We use that to place the page pointer AND encode
      21             :  * information about the sg table as well. The two lower bits are reserved
      22             :  * for this information.
      23             :  *
      24             :  * If bit 0 is set, then the page_link contains a pointer to the next sg
      25             :  * table list. Otherwise the next entry is at sg + 1.
      26             :  *
      27             :  * If bit 1 is set, then this sg entry is the last element in a list.
      28             :  *
      29             :  * See sg_next().
      30             :  *
      31             :  */
      32             : 
      33             : #define SG_MAGIC        0x87654321
      34             : 
      35             : /*
      36             :  * We overload the LSB of the page pointer to indicate whether it's
      37             :  * a valid sg entry, or whether it points to the start of a new scatterlist.
      38             :  * Those low bits are there for everyone! (thanks mason :-)
      39             :  */
      40             : #define sg_is_chain(sg)         ((sg)->page_link & 0x01)
      41             : #define sg_is_last(sg)          ((sg)->page_link & 0x02)
      42             : #define sg_chain_ptr(sg)        \
      43             :         ((struct scatterlist *) ((sg)->page_link & ~0x03))
      44             : 
      45             : /**
      46             :  * sg_assign_page - Assign a given page to an SG entry
      47             :  * @sg:             SG entry
      48             :  * @page:           The page
      49             :  *
      50             :  * Description:
      51             :  *   Assign page to sg entry. Also see sg_set_page(), the most commonly used
      52             :  *   variant.
      53             :  *
      54             :  **/
      55             : static inline void sg_assign_page(struct scatterlist *sg, struct page *page)
      56             : {
      57             :         unsigned long page_link = sg->page_link & 0x3;
      58             : 
      59             :         /*
      60             :          * In order for the low bit stealing approach to work, pages
      61             :          * must be aligned at a 32-bit boundary as a minimum.
      62             :          */
      63             :         BUG_ON((unsigned long) page & 0x03);
      64             : #ifdef CONFIG_DEBUG_SG
      65             :         BUG_ON(sg->sg_magic != SG_MAGIC);
      66             :         BUG_ON(sg_is_chain(sg));
      67             : #endif
      68             :         sg->page_link = page_link | (unsigned long) page;
      69             : }
      70             : 
      71             : /**
      72             :  * sg_set_page - Set sg entry to point at given page
      73             :  * @sg:          SG entry
      74             :  * @page:        The page
      75             :  * @len:         Length of data
      76             :  * @offset:      Offset into page
      77             :  *
      78             :  * Description:
      79             :  *   Use this function to set an sg entry pointing at a page, never assign
      80             :  *   the page directly. We encode sg table information in the lower bits
      81             :  *   of the page pointer. See sg_page() for looking up the page belonging
      82             :  *   to an sg entry.
      83             :  *
      84             :  **/
      85             : static inline void sg_set_page(struct scatterlist *sg, struct page *page,
      86             :                                unsigned int len, unsigned int offset)
      87             : {
      88             :         sg_assign_page(sg, page);
      89             :         sg->offset = offset;
      90             :         sg->length = len;
      91             : }
      92             : 
      93             : static inline struct page *sg_page(struct scatterlist *sg)
      94             : {
      95             : #ifdef CONFIG_DEBUG_SG
      96             :         BUG_ON(sg->sg_magic != SG_MAGIC);
      97             :         BUG_ON(sg_is_chain(sg));
      98             : #endif
      99             :         return (struct page *)((sg)->page_link & ~0x3);
     100             : }
     101             : 
     102             : /**
     103             :  * sg_set_buf - Set sg entry to point at given data
     104             :  * @sg:          SG entry
     105             :  * @buf:         Data
     106             :  * @buflen:      Data length
     107             :  *
     108             :  **/
     109             : static inline void sg_set_buf(struct scatterlist *sg, const void *buf,
     110             :                               unsigned int buflen)
     111             : {
     112             :         sg_set_page(sg, virt_to_page(buf), buflen, offset_in_page(buf));
     113             : }
     114             : 
     115             : /*
     116             :  * Loop over each sg element, following the pointer to a new list if necessary
     117             :  */
     118             : #define for_each_sg(sglist, sg, nr, __i)        \
     119             :         for (__i = 0, sg = (sglist); __i < (nr); __i++, sg = sg_next(sg))
     120             : 
     121             : /**
     122             :  * sg_chain - Chain two sglists together
     123             :  * @prv:        First scatterlist
     124             :  * @prv_nents:  Number of entries in prv
     125             :  * @sgl:        Second scatterlist
     126             :  *
     127             :  * Description:
     128             :  *   Links @prv@ and @sgl@ together, to form a longer scatterlist.
     129             :  *
     130             :  **/
     131             : static inline void sg_chain(struct scatterlist *prv, unsigned int prv_nents,
     132             :                             struct scatterlist *sgl)
     133             : {
     134             : #ifndef ARCH_HAS_SG_CHAIN
     135             :         BUG();
     136             : #endif
     137             : 
     138             :         /*
     139             :          * offset and length are unused for chain entry.  Clear them.
     140             :          */
     141             :         prv[prv_nents - 1].offset = 0;
     142             :         prv[prv_nents - 1].length = 0;
     143             : 
     144             :         /*
     145             :          * Set lowest bit to indicate a link pointer, and make sure to clear
     146             :          * the termination bit if it happens to be set.
     147             :          */
     148             :         prv[prv_nents - 1].page_link = ((unsigned long) sgl | 0x01) & ~0x02;
     149             : }
     150             : 
     151             : /**
     152             :  * sg_mark_end - Mark the end of the scatterlist
     153             :  * @sg:          SG entryScatterlist
     154             :  *
     155             :  * Description:
     156             :  *   Marks the passed in sg entry as the termination point for the sg
     157             :  *   table. A call to sg_next() on this entry will return NULL.
     158             :  *
     159             :  **/
     160             : static inline void sg_mark_end(struct scatterlist *sg)
     161             : {
     162             : #ifdef CONFIG_DEBUG_SG
     163             :         BUG_ON(sg->sg_magic != SG_MAGIC);
     164             : #endif
     165             :         /*
     166             :          * Set termination bit, clear potential chain bit
     167             :          */
     168             :         sg->page_link |= 0x02;
     169             :         sg->page_link &= ~0x01;
     170             : }
     171             : 
     172             : /**
     173             :  * sg_phys - Return physical address of an sg entry
     174             :  * @sg:      SG entry
     175             :  *
     176             :  * Description:
     177             :  *   This calls page_to_phys() on the page in this sg entry, and adds the
     178             :  *   sg offset. The caller must know that it is legal to call page_to_phys()
     179             :  *   on the sg page.
     180             :  *
     181             :  **/
     182             : static inline dma_addr_t sg_phys(struct scatterlist *sg)
     183             : {
     184             :         return page_to_phys(sg_page(sg)) + sg->offset;
     185             : }
     186             : 
     187             : /**
     188             :  * sg_virt - Return virtual address of an sg entry
     189             :  * @sg:      SG entry
     190             :  *
     191             :  * Description:
     192             :  *   This calls page_address() on the page in this sg entry, and adds the
     193             :  *   sg offset. The caller must know that the sg page has a valid virtual
     194             :  *   mapping.
     195             :  *
     196             :  **/
     197             : static inline void *sg_virt(struct scatterlist *sg)
     198             : {
     199             :         return page_address(sg_page(sg)) + sg->offset;
     200             : }
     201             : 
     202             : struct scatterlist *sg_next(struct scatterlist *);
     203             : struct scatterlist *sg_last(struct scatterlist *s, unsigned int);
     204             : void sg_init_table(struct scatterlist *, unsigned int);
     205             : void sg_init_one(struct scatterlist *, const void *, unsigned int);
     206             : 
     207             : typedef struct scatterlist *(sg_alloc_fn)(unsigned int, gfp_t);
     208             : typedef void (sg_free_fn)(struct scatterlist *, unsigned int);
     209             : 
     210             : void __sg_free_table(struct sg_table *, unsigned int, sg_free_fn *);
     211             : void sg_free_table(struct sg_table *);
     212             : int __sg_alloc_table(struct sg_table *, unsigned int, unsigned int, gfp_t,
     213             :                      sg_alloc_fn *);
     214             : int sg_alloc_table(struct sg_table *, unsigned int, gfp_t);
     215             : 
     216             : size_t sg_copy_from_buffer(struct scatterlist *sgl, unsigned int nents,
     217             :                            void *buf, size_t buflen);
     218             : size_t sg_copy_to_buffer(struct scatterlist *sgl, unsigned int nents,
     219             :                          void *buf, size_t buflen);
     220             : 
     221             : /*
     222             :  * Maximum number of entries that will be allocated in one piece, if
     223             :  * a list larger than this is required then chaining will be utilized.
     224             :  */
     225             : #define SG_MAX_SINGLE_ALLOC             (PAGE_SIZE / sizeof(struct scatterlist))
     226             : 
     227             : 
     228             : /*
     229             :  * Mapping sg iterator
     230             :  *
     231             :  * Iterates over sg entries mapping page-by-page.  On each successful
     232             :  * iteration, @miter->page points to the mapped page and
     233             :  * @miter->length bytes of data can be accessed at @miter->addr.  As
     234             :  * long as an interation is enclosed between start and stop, the user
     235             :  * is free to choose control structure and when to stop.
     236             :  *
     237             :  * @miter->consumed is set to @miter->length on each iteration.  It
     238             :  * can be adjusted if the user can't consume all the bytes in one go.
     239             :  * Also, a stopped iteration can be resumed by calling next on it.
     240             :  * This is useful when iteration needs to release all resources and
     241             :  * continue later (e.g. at the next interrupt).
     242             :  */
     243             : 
     244             : #define SG_MITER_ATOMIC         (1 << 0)   /* use kmap_atomic */
     245             : #define SG_MITER_TO_SG          (1 << 1)  /* flush back to phys on unmap */
     246             : #define SG_MITER_FROM_SG        (1 << 2)  /* nop */
     247             : 
     248             : struct sg_mapping_iter {
     249             :         /* the following three fields can be accessed directly */
     250             :         struct page             *page;          /* currently mapped page */
     251             :         void                    *addr;          /* pointer to the mapped area */
     252             :         size_t                  length;         /* length of the mapped area */
     253             :         size_t                  consumed;       /* number of consumed bytes */
     254             : 
     255             :         /* these are internal states, keep away */
     256             :         struct scatterlist      *__sg;          /* current entry */
     257             :         unsigned int            __nents;        /* nr of remaining entries */
     258             :         unsigned int            __offset;       /* offset within sg */
     259             :         unsigned int            __flags;
     260             : };
     261             : 
     262             : void sg_miter_start(struct sg_mapping_iter *miter, struct scatterlist *sgl,
     263             :                     unsigned int nents, unsigned int flags);
     264             : bool sg_miter_next(struct sg_mapping_iter *miter);
     265             : void sg_miter_stop(struct sg_mapping_iter *miter);
     266           1 : 
     267             : #endif /* _LINUX_SCATTERLIST_H */

Generated by: LCOV version 1.10