1 /* SPDX-License-Identifier: GPL-2.0-only */
3 * Pointer abstraction for IO/system memory
6 #ifndef __IOSYS_MAP_H__
7 #define __IOSYS_MAP_H__
10 #include <linux/string.h>
15 * When accessing a memory region, depending on its location, users may have to
16 * access it with I/O operations or memory load/store operations. For example,
17 * copying to system memory could be done with memcpy(), copying to I/O memory
18 * would be done with memcpy_toio().
22 * void *vaddr = ...; // pointer to system memory
23 * memcpy(vaddr, src, len);
25 * void *vaddr_iomem = ...; // pointer to I/O memory
26 * memcpy_toio(vaddr, _iomem, src, len);
28 * The user of such pointer may not have information about the mapping of that
29 * region or may want to have a single code path to handle operations on that
30 * buffer, regardless if it's located in system or IO memory. The type
31 * :c:type:`struct iosys_map <iosys_map>` and its helpers abstract that so the
32 * buffer can be passed around to other drivers or have separate duties inside
33 * the same driver for allocation, read and write operations.
35 * Open-coding access to :c:type:`struct iosys_map <iosys_map>` is considered
36 * bad style. Rather then accessing its fields directly, use one of the provided
37 * helper functions, or implement your own. For example, instances of
38 * :c:type:`struct iosys_map <iosys_map>` can be initialized statically with
39 * IOSYS_MAP_INIT_VADDR(), or at runtime with iosys_map_set_vaddr(). These
40 * helpers will set an address in system memory.
44 * struct iosys_map map = IOSYS_MAP_INIT_VADDR(0xdeadbeaf);
46 * iosys_map_set_vaddr(&map, 0xdeadbeaf);
48 * To set an address in I/O memory, use iosys_map_set_vaddr_iomem().
52 * iosys_map_set_vaddr_iomem(&map, 0xdeadbeaf);
54 * Instances of struct iosys_map do not have to be cleaned up, but
55 * can be cleared to NULL with iosys_map_clear(). Cleared mappings
56 * always refer to system memory.
60 * iosys_map_clear(&map);
62 * Test if a mapping is valid with either iosys_map_is_set() or
63 * iosys_map_is_null().
67 * if (iosys_map_is_set(&map) != iosys_map_is_null(&map))
70 * Instances of :c:type:`struct iosys_map <iosys_map>` can be compared for
71 * equality with iosys_map_is_equal(). Mappings that point to different memory
72 * spaces, system or I/O, are never equal. That's even true if both spaces are
73 * located in the same address space, both mappings contain the same address
74 * value, or both mappings refer to NULL.
78 * struct iosys_map sys_map; // refers to system memory
79 * struct iosys_map io_map; // refers to I/O memory
81 * if (iosys_map_is_equal(&sys_map, &io_map))
84 * A set up instance of struct iosys_map can be used to access or manipulate the
85 * buffer memory. Depending on the location of the memory, the provided helpers
86 * will pick the correct operations. Data can be copied into the memory with
87 * iosys_map_memcpy_to(). The address can be manipulated with iosys_map_incr().
91 * const void *src = ...; // source buffer
92 * size_t len = ...; // length of src
94 * iosys_map_memcpy_to(&map, src, len);
95 * iosys_map_incr(&map, len); // go to first byte after the memcpy
99 * struct iosys_map - Pointer to IO/system memory
100 * @vaddr_iomem: The buffer's address if in I/O memory
101 * @vaddr: The buffer's address if in system memory
102 * @is_iomem: True if the buffer is located in I/O memory, or false
107 void __iomem *vaddr_iomem;
114 * IOSYS_MAP_INIT_VADDR - Initializes struct iosys_map to an address in system memory
115 * @vaddr_: A system-memory address
117 #define IOSYS_MAP_INIT_VADDR(vaddr_) \
124 * IOSYS_MAP_INIT_OFFSET - Initializes struct iosys_map from another iosys_map
125 * @map_: The dma-buf mapping structure to copy from
126 * @offset_: Offset to add to the other mapping
128 * Initializes a new iosys_map struct based on another passed as argument. It
129 * does a shallow copy of the struct so it's possible to update the back storage
130 * without changing where the original map points to. It is the equivalent of
135 * iosys_map map = other_map;
136 * iosys_map_incr(&map, &offset);
142 * void foo(struct device *dev, struct iosys_map *base_map)
145 * struct iosys_map map = IOSYS_MAP_INIT_OFFSET(base_map, FIELD_OFFSET);
149 * The advantage of using the initializer over just increasing the offset with
150 * iosys_map_incr() like above is that the new map will always point to the
151 * right place of the buffer during its scope. It reduces the risk of updating
152 * the wrong part of the buffer and having no compiler warning about that. If
153 * the assignment to IOSYS_MAP_INIT_OFFSET() is forgotten, the compiler can warn
154 * about the use of uninitialized variable.
156 #define IOSYS_MAP_INIT_OFFSET(map_, offset_) ({ \
157 struct iosys_map copy = *map_; \
158 iosys_map_incr(©, offset_); \
163 * iosys_map_set_vaddr - Sets a iosys mapping structure to an address in system memory
164 * @map: The iosys_map structure
165 * @vaddr: A system-memory address
167 * Sets the address and clears the I/O-memory flag.
169 static inline void iosys_map_set_vaddr(struct iosys_map *map, void *vaddr)
172 map->is_iomem = false;
176 * iosys_map_set_vaddr_iomem - Sets a iosys mapping structure to an address in I/O memory
177 * @map: The iosys_map structure
178 * @vaddr_iomem: An I/O-memory address
180 * Sets the address and the I/O-memory flag.
182 static inline void iosys_map_set_vaddr_iomem(struct iosys_map *map,
183 void __iomem *vaddr_iomem)
185 map->vaddr_iomem = vaddr_iomem;
186 map->is_iomem = true;
190 * iosys_map_is_equal - Compares two iosys mapping structures for equality
191 * @lhs: The iosys_map structure
192 * @rhs: A iosys_map structure to compare with
194 * Two iosys mapping structures are equal if they both refer to the same type of memory
195 * and to the same address within that memory.
198 * True is both structures are equal, or false otherwise.
200 static inline bool iosys_map_is_equal(const struct iosys_map *lhs,
201 const struct iosys_map *rhs)
203 if (lhs->is_iomem != rhs->is_iomem)
205 else if (lhs->is_iomem)
206 return lhs->vaddr_iomem == rhs->vaddr_iomem;
208 return lhs->vaddr == rhs->vaddr;
212 * iosys_map_is_null - Tests for a iosys mapping to be NULL
213 * @map: The iosys_map structure
215 * Depending on the state of struct iosys_map.is_iomem, tests if the
219 * True if the mapping is NULL, or false otherwise.
221 static inline bool iosys_map_is_null(const struct iosys_map *map)
224 return !map->vaddr_iomem;
229 * iosys_map_is_set - Tests if the iosys mapping has been set
230 * @map: The iosys_map structure
232 * Depending on the state of struct iosys_map.is_iomem, tests if the
233 * mapping has been set.
236 * True if the mapping is been set, or false otherwise.
238 static inline bool iosys_map_is_set(const struct iosys_map *map)
240 return !iosys_map_is_null(map);
244 * iosys_map_clear - Clears a iosys mapping structure
245 * @map: The iosys_map structure
247 * Clears all fields to zero, including struct iosys_map.is_iomem, so
248 * mapping structures that were set to point to I/O memory are reset for
249 * system memory. Pointers are cleared to NULL. This is the default.
251 static inline void iosys_map_clear(struct iosys_map *map)
254 map->vaddr_iomem = NULL;
255 map->is_iomem = false;
262 * iosys_map_memcpy_to - Memcpy into offset of iosys_map
263 * @dst: The iosys_map structure
264 * @dst_offset: The offset from which to copy
265 * @src: The source buffer
266 * @len: The number of byte in src
268 * Copies data into a iosys_map with an offset. The source buffer is in
269 * system memory. Depending on the buffer's location, the helper picks the
270 * correct method of accessing the memory.
272 static inline void iosys_map_memcpy_to(struct iosys_map *dst, size_t dst_offset,
273 const void *src, size_t len)
276 memcpy_toio(dst->vaddr_iomem + dst_offset, src, len);
278 memcpy(dst->vaddr + dst_offset, src, len);
282 * iosys_map_memcpy_from - Memcpy from iosys_map into system memory
283 * @dst: Destination in system memory
284 * @src: The iosys_map structure
285 * @src_offset: The offset from which to copy
286 * @len: The number of byte in src
288 * Copies data from a iosys_map with an offset. The dest buffer is in
289 * system memory. Depending on the mapping location, the helper picks the
290 * correct method of accessing the memory.
292 static inline void iosys_map_memcpy_from(void *dst, const struct iosys_map *src,
293 size_t src_offset, size_t len)
296 memcpy_fromio(dst, src->vaddr_iomem + src_offset, len);
298 memcpy(dst, src->vaddr + src_offset, len);
302 * iosys_map_incr - Increments the address stored in a iosys mapping
303 * @map: The iosys_map structure
304 * @incr: The number of bytes to increment
306 * Increments the address stored in a iosys mapping. Depending on the
307 * buffer's location, the correct value will be updated.
309 static inline void iosys_map_incr(struct iosys_map *map, size_t incr)
312 map->vaddr_iomem += incr;
318 * iosys_map_memset - Memset iosys_map
319 * @dst: The iosys_map structure
320 * @offset: Offset from dst where to start setting value
321 * @value: The value to set
322 * @len: The number of bytes to set in dst
324 * Set value in iosys_map. Depending on the buffer's location, the helper
325 * picks the correct method of accessing the memory.
327 static inline void iosys_map_memset(struct iosys_map *dst, size_t offset,
328 int value, size_t len)
331 memset_io(dst->vaddr_iomem + offset, value, len);
333 memset(dst->vaddr + offset, value, len);
337 * iosys_map_rd - Read a C-type value from the iosys_map
339 * @map__: The iosys_map structure
340 * @offset__: The offset from which to read
341 * @type__: Type of the value being read
343 * Read a C type value from iosys_map, handling possible un-aligned accesses to
347 * The value read from the mapping.
349 #define iosys_map_rd(map__, offset__, type__) ({ \
351 iosys_map_memcpy_from(&val, map__, offset__, sizeof(val)); \
356 * iosys_map_wr - Write a C-type value to the iosys_map
358 * @map__: The iosys_map structure
359 * @offset__: The offset from the mapping to write to
360 * @type__: Type of the value being written
361 * @val__: Value to write
363 * Write a C-type value to the iosys_map, handling possible un-aligned accesses
366 #define iosys_map_wr(map__, offset__, type__, val__) ({ \
367 type__ val = (val__); \
368 iosys_map_memcpy_to(map__, offset__, &val, sizeof(val)); \
372 * iosys_map_rd_field - Read a member from a struct in the iosys_map
374 * @map__: The iosys_map structure
375 * @struct_offset__: Offset from the beggining of the map, where the struct
377 * @struct_type__: The struct describing the layout of the mapping
378 * @field__: Member of the struct to read
380 * Read a value from iosys_map considering its layout is described by a C struct
381 * starting at @struct_offset__. The field offset and size is calculated and its
382 * value read handling possible un-aligned memory accesses. For example: suppose
383 * there is a @struct foo defined as below and the value ``foo.field2.inner2``
384 * needs to be read from the iosys_map:
397 * This is the expected memory layout of a buffer using iosys_map_rd_field():
399 * +------------------------------+--------------------------+
400 * | Address | Content |
401 * +==============================+==========================+
402 * | buffer + 0000 | start of mmapped buffer |
403 * | | pointed by iosys_map |
404 * +------------------------------+--------------------------+
406 * +------------------------------+--------------------------+
407 * | buffer + ``struct_offset__`` | start of ``struct foo`` |
408 * +------------------------------+--------------------------+
410 * +------------------------------+--------------------------+
411 * | buffer + wwww | ``foo.field2.inner2`` |
412 * +------------------------------+--------------------------+
414 * +------------------------------+--------------------------+
415 * | buffer + yyyy | end of ``struct foo`` |
416 * +------------------------------+--------------------------+
418 * +------------------------------+--------------------------+
419 * | buffer + zzzz | end of mmaped buffer |
420 * +------------------------------+--------------------------+
422 * Values automatically calculated by this macro or not needed are denoted by
423 * wwww, yyyy and zzzz. This is the code to read that value:
427 * x = iosys_map_rd_field(&map, offset, struct foo, field2.inner2);
430 * The value read from the mapping.
432 #define iosys_map_rd_field(map__, struct_offset__, struct_type__, field__) ({ \
434 iosys_map_rd(map__, struct_offset__ + offsetof(struct_type__, field__), \
435 typeof(s->field__)); \
439 * iosys_map_wr_field - Write to a member of a struct in the iosys_map
441 * @map__: The iosys_map structure
442 * @struct_offset__: Offset from the beggining of the map, where the struct
444 * @struct_type__: The struct describing the layout of the mapping
445 * @field__: Member of the struct to read
446 * @val__: Value to write
448 * Write a value to the iosys_map considering its layout is described by a C struct
449 * starting at @struct_offset__. The field offset and size is calculated and the
450 * @val__ is written handling possible un-aligned memory accesses. Refer to
451 * iosys_map_rd_field() for expected usage and memory layout.
453 #define iosys_map_wr_field(map__, struct_offset__, struct_type__, field__, val__) ({ \
455 iosys_map_wr(map__, struct_offset__ + offsetof(struct_type__, field__), \
456 typeof(s->field__), val__); \
459 #endif /* __IOSYS_MAP_H__ */