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__
9 #include <linux/compiler_types.h>
11 #include <linux/string.h>
16 * When accessing a memory region, depending on its location, users may have to
17 * access it with I/O operations or memory load/store operations. For example,
18 * copying to system memory could be done with memcpy(), copying to I/O memory
19 * would be done with memcpy_toio().
23 * void *vaddr = ...; // pointer to system memory
24 * memcpy(vaddr, src, len);
26 * void *vaddr_iomem = ...; // pointer to I/O memory
27 * memcpy_toio(vaddr_iomem, src, len);
29 * The user of such pointer may not have information about the mapping of that
30 * region or may want to have a single code path to handle operations on that
31 * buffer, regardless if it's located in system or IO memory. The type
32 * :c:type:`struct iosys_map <iosys_map>` and its helpers abstract that so the
33 * buffer can be passed around to other drivers or have separate duties inside
34 * the same driver for allocation, read and write operations.
36 * Open-coding access to :c:type:`struct iosys_map <iosys_map>` is considered
37 * bad style. Rather then accessing its fields directly, use one of the provided
38 * helper functions, or implement your own. For example, instances of
39 * :c:type:`struct iosys_map <iosys_map>` can be initialized statically with
40 * IOSYS_MAP_INIT_VADDR(), or at runtime with iosys_map_set_vaddr(). These
41 * helpers will set an address in system memory.
45 * struct iosys_map map = IOSYS_MAP_INIT_VADDR(0xdeadbeaf);
47 * iosys_map_set_vaddr(&map, 0xdeadbeaf);
49 * To set an address in I/O memory, use iosys_map_set_vaddr_iomem().
53 * iosys_map_set_vaddr_iomem(&map, 0xdeadbeaf);
55 * Instances of struct iosys_map do not have to be cleaned up, but
56 * can be cleared to NULL with iosys_map_clear(). Cleared mappings
57 * always refer to system memory.
61 * iosys_map_clear(&map);
63 * Test if a mapping is valid with either iosys_map_is_set() or
64 * iosys_map_is_null().
68 * if (iosys_map_is_set(&map) != iosys_map_is_null(&map))
71 * Instances of :c:type:`struct iosys_map <iosys_map>` can be compared for
72 * equality with iosys_map_is_equal(). Mappings that point to different memory
73 * spaces, system or I/O, are never equal. That's even true if both spaces are
74 * located in the same address space, both mappings contain the same address
75 * value, or both mappings refer to NULL.
79 * struct iosys_map sys_map; // refers to system memory
80 * struct iosys_map io_map; // refers to I/O memory
82 * if (iosys_map_is_equal(&sys_map, &io_map))
85 * A set up instance of struct iosys_map can be used to access or manipulate the
86 * buffer memory. Depending on the location of the memory, the provided helpers
87 * will pick the correct operations. Data can be copied into the memory with
88 * iosys_map_memcpy_to(). The address can be manipulated with iosys_map_incr().
92 * const void *src = ...; // source buffer
93 * size_t len = ...; // length of src
95 * iosys_map_memcpy_to(&map, src, len);
96 * iosys_map_incr(&map, len); // go to first byte after the memcpy
100 * struct iosys_map - Pointer to IO/system memory
101 * @vaddr_iomem: The buffer's address if in I/O memory
102 * @vaddr: The buffer's address if in system memory
103 * @is_iomem: True if the buffer is located in I/O memory, or false
108 void __iomem *vaddr_iomem;
115 * IOSYS_MAP_INIT_VADDR - Initializes struct iosys_map to an address in system memory
116 * @vaddr_: A system-memory address
118 #define IOSYS_MAP_INIT_VADDR(vaddr_) \
125 * IOSYS_MAP_INIT_OFFSET - Initializes struct iosys_map from another iosys_map
126 * @map_: The dma-buf mapping structure to copy from
127 * @offset_: Offset to add to the other mapping
129 * Initializes a new iosys_map struct based on another passed as argument. It
130 * does a shallow copy of the struct so it's possible to update the back storage
131 * without changing where the original map points to. It is the equivalent of
136 * iosys_map map = other_map;
137 * iosys_map_incr(&map, &offset);
143 * void foo(struct device *dev, struct iosys_map *base_map)
146 * struct iosys_map map = IOSYS_MAP_INIT_OFFSET(base_map, FIELD_OFFSET);
150 * The advantage of using the initializer over just increasing the offset with
151 * iosys_map_incr() like above is that the new map will always point to the
152 * right place of the buffer during its scope. It reduces the risk of updating
153 * the wrong part of the buffer and having no compiler warning about that. If
154 * the assignment to IOSYS_MAP_INIT_OFFSET() is forgotten, the compiler can warn
155 * about the use of uninitialized variable.
157 #define IOSYS_MAP_INIT_OFFSET(map_, offset_) ({ \
158 struct iosys_map copy = *map_; \
159 iosys_map_incr(©, offset_); \
164 * iosys_map_set_vaddr - Sets a iosys mapping structure to an address in system memory
165 * @map: The iosys_map structure
166 * @vaddr: A system-memory address
168 * Sets the address and clears the I/O-memory flag.
170 static inline void iosys_map_set_vaddr(struct iosys_map *map, void *vaddr)
173 map->is_iomem = false;
177 * iosys_map_set_vaddr_iomem - Sets a iosys mapping structure to an address in I/O memory
178 * @map: The iosys_map structure
179 * @vaddr_iomem: An I/O-memory address
181 * Sets the address and the I/O-memory flag.
183 static inline void iosys_map_set_vaddr_iomem(struct iosys_map *map,
184 void __iomem *vaddr_iomem)
186 map->vaddr_iomem = vaddr_iomem;
187 map->is_iomem = true;
191 * iosys_map_is_equal - Compares two iosys mapping structures for equality
192 * @lhs: The iosys_map structure
193 * @rhs: A iosys_map structure to compare with
195 * Two iosys mapping structures are equal if they both refer to the same type of memory
196 * and to the same address within that memory.
199 * True is both structures are equal, or false otherwise.
201 static inline bool iosys_map_is_equal(const struct iosys_map *lhs,
202 const struct iosys_map *rhs)
204 if (lhs->is_iomem != rhs->is_iomem)
206 else if (lhs->is_iomem)
207 return lhs->vaddr_iomem == rhs->vaddr_iomem;
209 return lhs->vaddr == rhs->vaddr;
213 * iosys_map_is_null - Tests for a iosys mapping to be NULL
214 * @map: The iosys_map structure
216 * Depending on the state of struct iosys_map.is_iomem, tests if the
220 * True if the mapping is NULL, or false otherwise.
222 static inline bool iosys_map_is_null(const struct iosys_map *map)
225 return !map->vaddr_iomem;
230 * iosys_map_is_set - Tests if the iosys mapping has been set
231 * @map: The iosys_map structure
233 * Depending on the state of struct iosys_map.is_iomem, tests if the
234 * mapping has been set.
237 * True if the mapping is been set, or false otherwise.
239 static inline bool iosys_map_is_set(const struct iosys_map *map)
241 return !iosys_map_is_null(map);
245 * iosys_map_clear - Clears a iosys mapping structure
246 * @map: The iosys_map structure
248 * Clears all fields to zero, including struct iosys_map.is_iomem, so
249 * mapping structures that were set to point to I/O memory are reset for
250 * system memory. Pointers are cleared to NULL. This is the default.
252 static inline void iosys_map_clear(struct iosys_map *map)
255 map->vaddr_iomem = NULL;
256 map->is_iomem = false;
263 * iosys_map_memcpy_to - Memcpy into offset of iosys_map
264 * @dst: The iosys_map structure
265 * @dst_offset: The offset from which to copy
266 * @src: The source buffer
267 * @len: The number of byte in src
269 * Copies data into a iosys_map with an offset. The source buffer is in
270 * system memory. Depending on the buffer's location, the helper picks the
271 * correct method of accessing the memory.
273 static inline void iosys_map_memcpy_to(struct iosys_map *dst, size_t dst_offset,
274 const void *src, size_t len)
277 memcpy_toio(dst->vaddr_iomem + dst_offset, src, len);
279 memcpy(dst->vaddr + dst_offset, src, len);
283 * iosys_map_memcpy_from - Memcpy from iosys_map into system memory
284 * @dst: Destination in system memory
285 * @src: The iosys_map structure
286 * @src_offset: The offset from which to copy
287 * @len: The number of byte in src
289 * Copies data from a iosys_map with an offset. The dest buffer is in
290 * system memory. Depending on the mapping location, the helper picks the
291 * correct method of accessing the memory.
293 static inline void iosys_map_memcpy_from(void *dst, const struct iosys_map *src,
294 size_t src_offset, size_t len)
297 memcpy_fromio(dst, src->vaddr_iomem + src_offset, len);
299 memcpy(dst, src->vaddr + src_offset, len);
303 * iosys_map_incr - Increments the address stored in a iosys mapping
304 * @map: The iosys_map structure
305 * @incr: The number of bytes to increment
307 * Increments the address stored in a iosys mapping. Depending on the
308 * buffer's location, the correct value will be updated.
310 static inline void iosys_map_incr(struct iosys_map *map, size_t incr)
313 map->vaddr_iomem += incr;
319 * iosys_map_memset - Memset iosys_map
320 * @dst: The iosys_map structure
321 * @offset: Offset from dst where to start setting value
322 * @value: The value to set
323 * @len: The number of bytes to set in dst
325 * Set value in iosys_map. Depending on the buffer's location, the helper
326 * picks the correct method of accessing the memory.
328 static inline void iosys_map_memset(struct iosys_map *dst, size_t offset,
329 int value, size_t len)
332 memset_io(dst->vaddr_iomem + offset, value, len);
334 memset(dst->vaddr + offset, value, len);
338 #define __iosys_map_rd_io_u64_case(val_, vaddr_iomem_) \
339 u64: val_ = readq(vaddr_iomem_)
340 #define __iosys_map_wr_io_u64_case(val_, vaddr_iomem_) \
341 u64: writeq(val_, vaddr_iomem_)
343 #define __iosys_map_rd_io_u64_case(val_, vaddr_iomem_) \
344 u64: memcpy_fromio(&(val_), vaddr_iomem_, sizeof(u64))
345 #define __iosys_map_wr_io_u64_case(val_, vaddr_iomem_) \
346 u64: memcpy_toio(vaddr_iomem_, &(val_), sizeof(u64))
349 #define __iosys_map_rd_io(val__, vaddr_iomem__, type__) _Generic(val__, \
350 u8: val__ = readb(vaddr_iomem__), \
351 u16: val__ = readw(vaddr_iomem__), \
352 u32: val__ = readl(vaddr_iomem__), \
353 __iosys_map_rd_io_u64_case(val__, vaddr_iomem__))
355 #define __iosys_map_rd_sys(val__, vaddr__, type__) \
356 val__ = READ_ONCE(*(type__ *)(vaddr__))
358 #define __iosys_map_wr_io(val__, vaddr_iomem__, type__) _Generic(val__, \
359 u8: writeb(val__, vaddr_iomem__), \
360 u16: writew(val__, vaddr_iomem__), \
361 u32: writel(val__, vaddr_iomem__), \
362 __iosys_map_wr_io_u64_case(val__, vaddr_iomem__))
364 #define __iosys_map_wr_sys(val__, vaddr__, type__) \
365 WRITE_ONCE(*(type__ *)(vaddr__), val__)
368 * iosys_map_rd - Read a C-type value from the iosys_map
370 * @map__: The iosys_map structure
371 * @offset__: The offset from which to read
372 * @type__: Type of the value being read
374 * Read a C type value (u8, u16, u32 and u64) from iosys_map. For other types or
375 * if pointer may be unaligned (and problematic for the architecture supported),
376 * use iosys_map_memcpy_from().
379 * The value read from the mapping.
381 #define iosys_map_rd(map__, offset__, type__) ({ \
383 if ((map__)->is_iomem) { \
384 __iosys_map_rd_io(val, (map__)->vaddr_iomem + (offset__), type__);\
386 __iosys_map_rd_sys(val, (map__)->vaddr + (offset__), type__); \
392 * iosys_map_wr - Write a C-type value to the iosys_map
394 * @map__: The iosys_map structure
395 * @offset__: The offset from the mapping to write to
396 * @type__: Type of the value being written
397 * @val__: Value to write
399 * Write a C type value (u8, u16, u32 and u64) to the iosys_map. For other types
400 * or if pointer may be unaligned (and problematic for the architecture
401 * supported), use iosys_map_memcpy_to()
403 #define iosys_map_wr(map__, offset__, type__, val__) ({ \
404 type__ val = (val__); \
405 if ((map__)->is_iomem) { \
406 __iosys_map_wr_io(val, (map__)->vaddr_iomem + (offset__), type__);\
408 __iosys_map_wr_sys(val, (map__)->vaddr + (offset__), type__); \
413 * iosys_map_rd_field - Read a member from a struct in the iosys_map
415 * @map__: The iosys_map structure
416 * @struct_offset__: Offset from the beggining of the map, where the struct
418 * @struct_type__: The struct describing the layout of the mapping
419 * @field__: Member of the struct to read
421 * Read a value from iosys_map considering its layout is described by a C struct
422 * starting at @struct_offset__. The field offset and size is calculated and its
423 * value read. If the field access would incur in un-aligned access, then either
424 * iosys_map_memcpy_from() needs to be used or the architecture must support it.
425 * For example: suppose there is a @struct foo defined as below and the value
426 * ``foo.field2.inner2`` needs to be read from the iosys_map:
439 * This is the expected memory layout of a buffer using iosys_map_rd_field():
441 * +------------------------------+--------------------------+
442 * | Address | Content |
443 * +==============================+==========================+
444 * | buffer + 0000 | start of mmapped buffer |
445 * | | pointed by iosys_map |
446 * +------------------------------+--------------------------+
448 * +------------------------------+--------------------------+
449 * | buffer + ``struct_offset__`` | start of ``struct foo`` |
450 * +------------------------------+--------------------------+
452 * +------------------------------+--------------------------+
453 * | buffer + wwww | ``foo.field2.inner2`` |
454 * +------------------------------+--------------------------+
456 * +------------------------------+--------------------------+
457 * | buffer + yyyy | end of ``struct foo`` |
458 * +------------------------------+--------------------------+
460 * +------------------------------+--------------------------+
461 * | buffer + zzzz | end of mmaped buffer |
462 * +------------------------------+--------------------------+
464 * Values automatically calculated by this macro or not needed are denoted by
465 * wwww, yyyy and zzzz. This is the code to read that value:
469 * x = iosys_map_rd_field(&map, offset, struct foo, field2.inner2);
472 * The value read from the mapping.
474 #define iosys_map_rd_field(map__, struct_offset__, struct_type__, field__) ({ \
476 iosys_map_rd(map__, struct_offset__ + offsetof(struct_type__, field__), \
477 typeof(s->field__)); \
481 * iosys_map_wr_field - Write to a member of a struct in the iosys_map
483 * @map__: The iosys_map structure
484 * @struct_offset__: Offset from the beggining of the map, where the struct
486 * @struct_type__: The struct describing the layout of the mapping
487 * @field__: Member of the struct to read
488 * @val__: Value to write
490 * Write a value to the iosys_map considering its layout is described by a C
491 * struct starting at @struct_offset__. The field offset and size is calculated
492 * and the @val__ is written. If the field access would incur in un-aligned
493 * access, then either iosys_map_memcpy_to() needs to be used or the
494 * architecture must support it. Refer to iosys_map_rd_field() for expected
495 * usage and memory layout.
497 #define iosys_map_wr_field(map__, struct_offset__, struct_type__, field__, val__) ({ \
499 iosys_map_wr(map__, struct_offset__ + offsetof(struct_type__, field__), \
500 typeof(s->field__), val__); \
503 #endif /* __IOSYS_MAP_H__ */