Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | #ifndef _LINUX_SCATTERLIST_H |
| 2 | #define _LINUX_SCATTERLIST_H |
| 3 | |
Hugh Dickins | 85cdffc | 2007-10-25 09:55:05 +0200 | [diff] [blame] | 4 | #include <asm/types.h> |
Herbert Xu | d32311f | 2005-09-17 14:41:40 +1000 | [diff] [blame] | 5 | #include <asm/scatterlist.h> |
| 6 | #include <linux/mm.h> |
| 7 | #include <linux/string.h> |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 8 | #include <asm/io.h> |
| 9 | |
| 10 | /* |
| 11 | * Notes on SG table design. |
| 12 | * |
| 13 | * Architectures must provide an unsigned long page_link field in the |
| 14 | * scatterlist struct. We use that to place the page pointer AND encode |
| 15 | * information about the sg table as well. The two lower bits are reserved |
| 16 | * for this information. |
| 17 | * |
| 18 | * If bit 0 is set, then the page_link contains a pointer to the next sg |
| 19 | * table list. Otherwise the next entry is at sg + 1. |
| 20 | * |
| 21 | * If bit 1 is set, then this sg entry is the last element in a list. |
| 22 | * |
| 23 | * See sg_next(). |
| 24 | * |
| 25 | */ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 26 | |
Jens Axboe | d6ec084 | 2007-10-22 20:01:06 +0200 | [diff] [blame] | 27 | #define SG_MAGIC 0x87654321 |
| 28 | |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 29 | /** |
Jens Axboe | 642f149 | 2007-10-24 11:20:47 +0200 | [diff] [blame] | 30 | * sg_assign_page - Assign a given page to an SG entry |
| 31 | * @sg: SG entry |
| 32 | * @page: The page |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 33 | * |
| 34 | * Description: |
Jens Axboe | 642f149 | 2007-10-24 11:20:47 +0200 | [diff] [blame] | 35 | * Assign page to sg entry. Also see sg_set_page(), the most commonly used |
| 36 | * variant. |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 37 | * |
| 38 | **/ |
Jens Axboe | 642f149 | 2007-10-24 11:20:47 +0200 | [diff] [blame] | 39 | static inline void sg_assign_page(struct scatterlist *sg, struct page *page) |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 40 | { |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 41 | unsigned long page_link = sg->page_link & 0x3; |
| 42 | |
Jens Axboe | de26103 | 2007-10-23 20:35:58 +0200 | [diff] [blame] | 43 | /* |
| 44 | * In order for the low bit stealing approach to work, pages |
| 45 | * must be aligned at a 32-bit boundary as a minimum. |
| 46 | */ |
| 47 | BUG_ON((unsigned long) page & 0x03); |
Jens Axboe | d6ec084 | 2007-10-22 20:01:06 +0200 | [diff] [blame] | 48 | #ifdef CONFIG_DEBUG_SG |
| 49 | BUG_ON(sg->sg_magic != SG_MAGIC); |
| 50 | #endif |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 51 | sg->page_link = page_link | (unsigned long) page; |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 52 | } |
| 53 | |
Jens Axboe | 642f149 | 2007-10-24 11:20:47 +0200 | [diff] [blame] | 54 | /** |
| 55 | * sg_set_page - Set sg entry to point at given page |
| 56 | * @sg: SG entry |
| 57 | * @page: The page |
| 58 | * @len: Length of data |
| 59 | * @offset: Offset into page |
| 60 | * |
| 61 | * Description: |
| 62 | * Use this function to set an sg entry pointing at a page, never assign |
| 63 | * the page directly. We encode sg table information in the lower bits |
| 64 | * of the page pointer. See sg_page() for looking up the page belonging |
| 65 | * to an sg entry. |
| 66 | * |
| 67 | **/ |
| 68 | static inline void sg_set_page(struct scatterlist *sg, struct page *page, |
| 69 | unsigned int len, unsigned int offset) |
| 70 | { |
| 71 | sg_assign_page(sg, page); |
| 72 | sg->offset = offset; |
| 73 | sg->length = len; |
| 74 | } |
| 75 | |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 76 | #define sg_page(sg) ((struct page *) ((sg)->page_link & ~0x3)) |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 77 | |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 78 | /** |
| 79 | * sg_set_buf - Set sg entry to point at given data |
| 80 | * @sg: SG entry |
| 81 | * @buf: Data |
| 82 | * @buflen: Data length |
| 83 | * |
| 84 | **/ |
Herbert Xu | 03fd9ce | 2006-08-14 23:11:53 +1000 | [diff] [blame] | 85 | static inline void sg_set_buf(struct scatterlist *sg, const void *buf, |
Herbert Xu | d32311f | 2005-09-17 14:41:40 +1000 | [diff] [blame] | 86 | unsigned int buflen) |
| 87 | { |
Jens Axboe | 642f149 | 2007-10-24 11:20:47 +0200 | [diff] [blame] | 88 | sg_set_page(sg, virt_to_page(buf), buflen, offset_in_page(buf)); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 89 | } |
| 90 | |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 91 | /* |
| 92 | * We overload the LSB of the page pointer to indicate whether it's |
| 93 | * a valid sg entry, or whether it points to the start of a new scatterlist. |
| 94 | * Those low bits are there for everyone! (thanks mason :-) |
| 95 | */ |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 96 | #define sg_is_chain(sg) ((sg)->page_link & 0x01) |
| 97 | #define sg_is_last(sg) ((sg)->page_link & 0x02) |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 98 | #define sg_chain_ptr(sg) \ |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 99 | ((struct scatterlist *) ((sg)->page_link & ~0x03)) |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 100 | |
| 101 | /** |
| 102 | * sg_next - return the next scatterlist entry in a list |
| 103 | * @sg: The current sg entry |
| 104 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 105 | * Description: |
| 106 | * Usually the next entry will be @sg@ + 1, but if this sg element is part |
| 107 | * of a chained scatterlist, it could jump to the start of a new |
| 108 | * scatterlist array. |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 109 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 110 | **/ |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 111 | static inline struct scatterlist *sg_next(struct scatterlist *sg) |
| 112 | { |
Jens Axboe | d6ec084 | 2007-10-22 20:01:06 +0200 | [diff] [blame] | 113 | #ifdef CONFIG_DEBUG_SG |
| 114 | BUG_ON(sg->sg_magic != SG_MAGIC); |
| 115 | #endif |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 116 | if (sg_is_last(sg)) |
| 117 | return NULL; |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 118 | |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 119 | sg++; |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 120 | if (unlikely(sg_is_chain(sg))) |
| 121 | sg = sg_chain_ptr(sg); |
| 122 | |
| 123 | return sg; |
| 124 | } |
Jens Axboe | 96b418c | 2007-05-09 09:02:57 +0200 | [diff] [blame] | 125 | |
| 126 | /* |
| 127 | * Loop over each sg element, following the pointer to a new list if necessary |
| 128 | */ |
| 129 | #define for_each_sg(sglist, sg, nr, __i) \ |
| 130 | for (__i = 0, sg = (sglist); __i < (nr); __i++, sg = sg_next(sg)) |
| 131 | |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 132 | /** |
| 133 | * sg_last - return the last scatterlist entry in a list |
| 134 | * @sgl: First entry in the scatterlist |
| 135 | * @nents: Number of entries in the scatterlist |
| 136 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 137 | * Description: |
| 138 | * Should only be used casually, it (currently) scan the entire list |
| 139 | * to get the last entry. |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 140 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 141 | * Note that the @sgl@ pointer passed in need not be the first one, |
| 142 | * the important bit is that @nents@ denotes the number of entries that |
| 143 | * exist from @sgl@. |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 144 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 145 | **/ |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 146 | static inline struct scatterlist *sg_last(struct scatterlist *sgl, |
| 147 | unsigned int nents) |
| 148 | { |
| 149 | #ifndef ARCH_HAS_SG_CHAIN |
| 150 | struct scatterlist *ret = &sgl[nents - 1]; |
| 151 | #else |
| 152 | struct scatterlist *sg, *ret = NULL; |
Chuck Lever | 74eb94f | 2007-10-26 19:29:47 +0200 | [diff] [blame] | 153 | unsigned int i; |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 154 | |
| 155 | for_each_sg(sgl, sg, nents, i) |
| 156 | ret = sg; |
| 157 | |
| 158 | #endif |
Jens Axboe | d6ec084 | 2007-10-22 20:01:06 +0200 | [diff] [blame] | 159 | #ifdef CONFIG_DEBUG_SG |
| 160 | BUG_ON(sgl[0].sg_magic != SG_MAGIC); |
| 161 | BUG_ON(!sg_is_last(ret)); |
| 162 | #endif |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 163 | return ret; |
| 164 | } |
| 165 | |
| 166 | /** |
| 167 | * sg_chain - Chain two sglists together |
| 168 | * @prv: First scatterlist |
| 169 | * @prv_nents: Number of entries in prv |
| 170 | * @sgl: Second scatterlist |
| 171 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 172 | * Description: |
| 173 | * Links @prv@ and @sgl@ together, to form a longer scatterlist. |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 174 | * |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 175 | **/ |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 176 | static inline void sg_chain(struct scatterlist *prv, unsigned int prv_nents, |
| 177 | struct scatterlist *sgl) |
| 178 | { |
| 179 | #ifndef ARCH_HAS_SG_CHAIN |
| 180 | BUG(); |
| 181 | #endif |
Jens Axboe | 73fd546 | 2007-10-26 09:32:16 +0200 | [diff] [blame] | 182 | /* |
| 183 | * Set lowest bit to indicate a link pointer, and make sure to clear |
| 184 | * the termination bit if it happens to be set. |
| 185 | */ |
| 186 | prv[prv_nents - 1].page_link = ((unsigned long) sgl | 0x01) & ~0x02; |
Jens Axboe | 70eb804 | 2007-07-16 21:17:16 +0200 | [diff] [blame] | 187 | } |
| 188 | |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 189 | /** |
| 190 | * sg_mark_end - Mark the end of the scatterlist |
Jens Axboe | c46f233 | 2007-10-31 12:06:37 +0100 | [diff] [blame] | 191 | * @sg: SG entryScatterlist |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 192 | * |
| 193 | * Description: |
Jens Axboe | c46f233 | 2007-10-31 12:06:37 +0100 | [diff] [blame] | 194 | * Marks the passed in sg entry as the termination point for the sg |
| 195 | * table. A call to sg_next() on this entry will return NULL. |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 196 | * |
| 197 | **/ |
Jens Axboe | c46f233 | 2007-10-31 12:06:37 +0100 | [diff] [blame] | 198 | static inline void sg_mark_end(struct scatterlist *sg) |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 199 | { |
Jens Axboe | c46f233 | 2007-10-31 12:06:37 +0100 | [diff] [blame] | 200 | #ifdef CONFIG_DEBUG_SG |
| 201 | BUG_ON(sg->sg_magic != SG_MAGIC); |
| 202 | #endif |
| 203 | /* |
| 204 | * Set termination bit, clear potential chain bit |
| 205 | */ |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 206 | sg->page_link |= 0x02; |
Jens Axboe | c46f233 | 2007-10-31 12:06:37 +0100 | [diff] [blame] | 207 | sg->page_link &= ~0x01; |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 208 | } |
| 209 | |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 210 | /** |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 211 | * sg_init_table - Initialize SG table |
| 212 | * @sgl: The SG table |
| 213 | * @nents: Number of entries in table |
| 214 | * |
| 215 | * Notes: |
| 216 | * If this is part of a chained sg table, sg_mark_end() should be |
| 217 | * used only on the last table part. |
| 218 | * |
| 219 | **/ |
| 220 | static inline void sg_init_table(struct scatterlist *sgl, unsigned int nents) |
| 221 | { |
| 222 | memset(sgl, 0, sizeof(*sgl) * nents); |
Jens Axboe | d6ec084 | 2007-10-22 20:01:06 +0200 | [diff] [blame] | 223 | #ifdef CONFIG_DEBUG_SG |
| 224 | { |
Chuck Lever | 513f54b | 2007-10-26 19:29:48 +0200 | [diff] [blame] | 225 | unsigned int i; |
Jens Axboe | d6ec084 | 2007-10-22 20:01:06 +0200 | [diff] [blame] | 226 | for (i = 0; i < nents; i++) |
| 227 | sgl[i].sg_magic = SG_MAGIC; |
| 228 | } |
| 229 | #endif |
Jens Axboe | c46f233 | 2007-10-31 12:06:37 +0100 | [diff] [blame] | 230 | sg_mark_end(&sgl[nents - 1]); |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 231 | } |
| 232 | |
| 233 | /** |
Jens Axboe | 013fb33 | 2007-10-30 10:34:33 +0100 | [diff] [blame] | 234 | * sg_init_one - Initialize a single entry sg list |
| 235 | * @sg: SG entry |
| 236 | * @buf: Virtual address for IO |
| 237 | * @buflen: IO length |
| 238 | * |
| 239 | * Notes: |
| 240 | * This should not be used on a single entry that is part of a larger |
| 241 | * table. Use sg_init_table() for that. |
| 242 | * |
| 243 | **/ |
| 244 | static inline void sg_init_one(struct scatterlist *sg, const void *buf, |
| 245 | unsigned int buflen) |
| 246 | { |
| 247 | sg_init_table(sg, 1); |
| 248 | sg_set_buf(sg, buf, buflen); |
| 249 | } |
| 250 | |
| 251 | /** |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 252 | * sg_phys - Return physical address of an sg entry |
| 253 | * @sg: SG entry |
| 254 | * |
| 255 | * Description: |
| 256 | * This calls page_to_phys() on the page in this sg entry, and adds the |
| 257 | * sg offset. The caller must know that it is legal to call page_to_phys() |
| 258 | * on the sg page. |
| 259 | * |
| 260 | **/ |
Hugh Dickins | 85cdffc | 2007-10-25 09:55:05 +0200 | [diff] [blame] | 261 | static inline dma_addr_t sg_phys(struct scatterlist *sg) |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 262 | { |
| 263 | return page_to_phys(sg_page(sg)) + sg->offset; |
| 264 | } |
| 265 | |
| 266 | /** |
| 267 | * sg_virt - Return virtual address of an sg entry |
Jens Axboe | 18dabf4 | 2007-10-22 19:57:20 +0200 | [diff] [blame] | 268 | * @sg: SG entry |
Jens Axboe | 82f66fb | 2007-10-22 17:07:37 +0200 | [diff] [blame] | 269 | * |
| 270 | * Description: |
| 271 | * This calls page_address() on the page in this sg entry, and adds the |
| 272 | * sg offset. The caller must know that the sg page has a valid virtual |
| 273 | * mapping. |
| 274 | * |
| 275 | **/ |
| 276 | static inline void *sg_virt(struct scatterlist *sg) |
| 277 | { |
| 278 | return page_address(sg_page(sg)) + sg->offset; |
| 279 | } |
| 280 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 281 | #endif /* _LINUX_SCATTERLIST_H */ |