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 0 : 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 0 : return page_address(sg_page(sg)) + sg->offset;
200 0 : }
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 1 : typedef struct scatterlist *(sg_alloc_fn)(unsigned int, gfp_t);
208 1 : 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 */
|