include/linux/iosys-map.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * Pointer abstraction for IO/system memory
   4  */
   5
   6 #ifndef __IOSYS_MAP_H__
   7 #define __IOSYS_MAP_H__
   8
   9 #include <linux/compiler_types.h>
  10 #include <linux/io.h>
  11 #include <linux/string.h>
  12
  13 /**
  14  * DOC: overview
  15  *
  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().
  20  *
  21  * .. code-block:: c
  22  *
  23  *      void *vaddr = ...; // pointer to system memory
  24  *      memcpy(vaddr, src, len);
  25  *
  26  *      void *vaddr_iomem = ...; // pointer to I/O memory
  27  *      memcpy_toio(vaddr_iomem, src, len);
  28  *
  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.
  35  *
  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.
  42  *
  43  * .. code-block:: c
  44  *
  45  *      struct iosys_map map = IOSYS_MAP_INIT_VADDR(0xdeadbeaf);
  46  *
  47  *      iosys_map_set_vaddr(&map, 0xdeadbeaf);
  48  *
  49  * To set an address in I/O memory, use iosys_map_set_vaddr_iomem().
  50  *
  51  * .. code-block:: c
  52  *
  53  *      iosys_map_set_vaddr_iomem(&map, 0xdeadbeaf);
  54  *
  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.
  58  *
  59  * .. code-block:: c
  60  *
  61  *      iosys_map_clear(&map);
  62  *
  63  * Test if a mapping is valid with either iosys_map_is_set() or
  64  * iosys_map_is_null().
  65  *
  66  * .. code-block:: c
  67  *
  68  *      if (iosys_map_is_set(&map) != iosys_map_is_null(&map))
  69  *              // always true
  70  *
  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.
  76  *
  77  * .. code-block:: c
  78  *
  79  *      struct iosys_map sys_map; // refers to system memory
  80  *      struct iosys_map io_map; // refers to I/O memory
  81  *
  82  *      if (iosys_map_is_equal(&sys_map, &io_map))
  83  *              // always false
  84  *
  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().
  89  *
  90  * .. code-block:: c
  91  *
  92  *      const void *src = ...; // source buffer
  93  *      size_t len = ...; // length of src
  94  *
  95  *      iosys_map_memcpy_to(&map, src, len);
  96  *      iosys_map_incr(&map, len); // go to first byte after the memcpy
  97  */
  98
  99 /**
 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
 104  *                      otherwise.
 105  */
 106 struct iosys_map {
 107         union {
 108                 void __iomem *vaddr_iomem;
 109                 void *vaddr;
 110         };
 111         bool is_iomem;
 112 };
 113
 114 /**
 115  * IOSYS_MAP_INIT_VADDR - Initializes struct iosys_map to an address in system memory
 116  * @vaddr_:     A system-memory address
 117  */
 118 #define IOSYS_MAP_INIT_VADDR(vaddr_)    \
 119         {                               \
 120                 .vaddr = (vaddr_),      \
 121                 .is_iomem = false,      \
 122         }
 123
 124 /**
 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
 128  *
 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
 132  * doing:
 133  *
 134  * .. code-block:: c
 135  *
 136  *      iosys_map map = other_map;
 137  *      iosys_map_incr(&map, &offset);
 138  *
 139  * Example usage:
 140  *
 141  * .. code-block:: c
 142  *
 143  *      void foo(struct device *dev, struct iosys_map *base_map)
 144  *      {
 145  *              ...
 146  *              struct iosys_map map = IOSYS_MAP_INIT_OFFSET(base_map, FIELD_OFFSET);
 147  *              ...
 148  *      }
 149  *
 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.
 156  */
 157 #define IOSYS_MAP_INIT_OFFSET(map_, offset_) ({                         \
 158         struct iosys_map copy = *map_;                                  \
 159         iosys_map_incr(&copy, offset_);                                 \
 160         copy;                                                           \
 161 })
 162
 163 /**
 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
 167  *
 168  * Sets the address and clears the I/O-memory flag.
 169  */
 170 static inline void iosys_map_set_vaddr(struct iosys_map *map, void *vaddr)
 171 {
 172         map->vaddr = vaddr;
 173         map->is_iomem = false;
 174 }
 175
 176 /**
 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
 180  *
 181  * Sets the address and the I/O-memory flag.
 182  */
 183 static inline void iosys_map_set_vaddr_iomem(struct iosys_map *map,
 184                                              void __iomem *vaddr_iomem)
 185 {
 186         map->vaddr_iomem = vaddr_iomem;
 187         map->is_iomem = true;
 188 }
 189
 190 /**
 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
 194  *
 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.
 197  *
 198  * Returns:
 199  * True is both structures are equal, or false otherwise.
 200  */
 201 static inline bool iosys_map_is_equal(const struct iosys_map *lhs,
 202                                       const struct iosys_map *rhs)
 203 {
 204         if (lhs->is_iomem != rhs->is_iomem)
 205                 return false;
 206         else if (lhs->is_iomem)
 207                 return lhs->vaddr_iomem == rhs->vaddr_iomem;
 208         else
 209                 return lhs->vaddr == rhs->vaddr;
 210 }
 211
 212 /**
 213  * iosys_map_is_null - Tests for a iosys mapping to be NULL
 214  * @map:        The iosys_map structure
 215  *
 216  * Depending on the state of struct iosys_map.is_iomem, tests if the
 217  * mapping is NULL.
 218  *
 219  * Returns:
 220  * True if the mapping is NULL, or false otherwise.
 221  */
 222 static inline bool iosys_map_is_null(const struct iosys_map *map)
 223 {
 224         if (map->is_iomem)
 225                 return !map->vaddr_iomem;
 226         return !map->vaddr;
 227 }
 228
 229 /**
 230  * iosys_map_is_set - Tests if the iosys mapping has been set
 231  * @map:        The iosys_map structure
 232  *
 233  * Depending on the state of struct iosys_map.is_iomem, tests if the
 234  * mapping has been set.
 235  *
 236  * Returns:
 237  * True if the mapping is been set, or false otherwise.
 238  */
 239 static inline bool iosys_map_is_set(const struct iosys_map *map)
 240 {
 241         return !iosys_map_is_null(map);
 242 }
 243
 244 /**
 245  * iosys_map_clear - Clears a iosys mapping structure
 246  * @map:        The iosys_map structure
 247  *
 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.
 251  */
 252 static inline void iosys_map_clear(struct iosys_map *map)
 253 {
 254         if (map->is_iomem) {
 255                 map->vaddr_iomem = NULL;
 256                 map->is_iomem = false;
 257         } else {
 258                 map->vaddr = NULL;
 259         }
 260 }
 261
 262 /**
 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
 268  *
 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.
 272  */
 273 static inline void iosys_map_memcpy_to(struct iosys_map *dst, size_t dst_offset,
 274                                        const void *src, size_t len)
 275 {
 276         if (dst->is_iomem)
 277                 memcpy_toio(dst->vaddr_iomem + dst_offset, src, len);
 278         else
 279                 memcpy(dst->vaddr + dst_offset, src, len);
 280 }
 281
 282 /**
 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
 288  *
 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.
 292  */
 293 static inline void iosys_map_memcpy_from(void *dst, const struct iosys_map *src,
 294                                          size_t src_offset, size_t len)
 295 {
 296         if (src->is_iomem)
 297                 memcpy_fromio(dst, src->vaddr_iomem + src_offset, len);
 298         else
 299                 memcpy(dst, src->vaddr + src_offset, len);
 300 }
 301
 302 /**
 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
 306  *
 307  * Increments the address stored in a iosys mapping. Depending on the
 308  * buffer's location, the correct value will be updated.
 309  */
 310 static inline void iosys_map_incr(struct iosys_map *map, size_t incr)
 311 {
 312         if (map->is_iomem)
 313                 map->vaddr_iomem += incr;
 314         else
 315                 map->vaddr += incr;
 316 }
 317
 318 /**
 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
 324  *
 325  * Set value in iosys_map. Depending on the buffer's location, the helper
 326  * picks the correct method of accessing the memory.
 327  */
 328 static inline void iosys_map_memset(struct iosys_map *dst, size_t offset,
 329                                     int value, size_t len)
 330 {
 331         if (dst->is_iomem)
 332                 memset_io(dst->vaddr_iomem + offset, value, len);
 333         else
 334                 memset(dst->vaddr + offset, value, len);
 335 }
 336
 337 #ifdef CONFIG_64BIT
 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_)
 342 #else
 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))
 347 #endif
 348
 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__))
 354
 355 #define __iosys_map_rd_sys(val__, vaddr__, type__)                              \
 356         val__ = READ_ONCE(*(type__ *)(vaddr__))
 357
 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__))
 363
 364 #define __iosys_map_wr_sys(val__, vaddr__, type__)                              \
 365         WRITE_ONCE(*(type__ *)(vaddr__), val__)
 366
 367 /**
 368  * iosys_map_rd - Read a C-type value from the iosys_map
 369  *
 370  * @map__:      The iosys_map structure
 371  * @offset__:   The offset from which to read
 372  * @type__:     Type of the value being read
 373  *
 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().
 377  *
 378  * Returns:
 379  * The value read from the mapping.
 380  */
 381 #define iosys_map_rd(map__, offset__, type__) ({                                \
 382         type__ val;                                                             \
 383         if ((map__)->is_iomem) {                                                \
 384                 __iosys_map_rd_io(val, (map__)->vaddr_iomem + (offset__), type__);\
 385         } else {                                                                \
 386                 __iosys_map_rd_sys(val, (map__)->vaddr + (offset__), type__);   \
 387         }                                                                       \
 388         val;                                                                    \
 389 })
 390
 391 /**
 392  * iosys_map_wr - Write a C-type value to the iosys_map
 393  *
 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
 398  *
 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()
 402  */
 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__);\
 407         } else {                                                                \
 408                 __iosys_map_wr_sys(val, (map__)->vaddr + (offset__), type__);   \
 409         }                                                                       \
 410 })
 411
 412 /**
 413  * iosys_map_rd_field - Read a member from a struct in the iosys_map
 414  *
 415  * @map__:              The iosys_map structure
 416  * @struct_offset__:    Offset from the beggining of the map, where the struct
 417  *                      is located
 418  * @struct_type__:      The struct describing the layout of the mapping
 419  * @field__:            Member of the struct to read
 420  *
 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:
 427  *
 428  * .. code-block:: c
 429  *
 430  *      struct foo {
 431  *              int field1;
 432  *              struct {
 433  *                      int inner1;
 434  *                      int inner2;
 435  *              } field2;
 436  *              int field3;
 437  *      } __packed;
 438  *
 439  * This is the expected memory layout of a buffer using iosys_map_rd_field():
 440  *
 441  * +------------------------------+--------------------------+
 442  * | Address                      | Content                  |
 443  * +==============================+==========================+
 444  * | buffer + 0000                | start of mmapped buffer  |
 445  * |                              | pointed by iosys_map     |
 446  * +------------------------------+--------------------------+
 447  * | ...                          | ...                      |
 448  * +------------------------------+--------------------------+
 449  * | buffer + ``struct_offset__`` | start of ``struct foo``  |
 450  * +------------------------------+--------------------------+
 451  * | ...                          | ...                      |
 452  * +------------------------------+--------------------------+
 453  * | buffer + wwww                | ``foo.field2.inner2``    |
 454  * +------------------------------+--------------------------+
 455  * | ...                          | ...                      |
 456  * +------------------------------+--------------------------+
 457  * | buffer + yyyy                | end of ``struct foo``    |
 458  * +------------------------------+--------------------------+
 459  * | ...                          | ...                      |
 460  * +------------------------------+--------------------------+
 461  * | buffer + zzzz                | end of mmaped buffer     |
 462  * +------------------------------+--------------------------+
 463  *
 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:
 466  *
 467  * .. code-block:: c
 468  *
 469  *      x = iosys_map_rd_field(&map, offset, struct foo, field2.inner2);
 470  *
 471  * Returns:
 472  * The value read from the mapping.
 473  */
 474 #define iosys_map_rd_field(map__, struct_offset__, struct_type__, field__) ({   \
 475         struct_type__ *s;                                                       \
 476         iosys_map_rd(map__, struct_offset__ + offsetof(struct_type__, field__), \
 477                      typeof(s->field__));                                       \
 478 })
 479
 480 /**
 481  * iosys_map_wr_field - Write to a member of a struct in the iosys_map
 482  *
 483  * @map__:              The iosys_map structure
 484  * @struct_offset__:    Offset from the beggining of the map, where the struct
 485  *                      is located
 486  * @struct_type__:      The struct describing the layout of the mapping
 487  * @field__:            Member of the struct to read
 488  * @val__:              Value to write
 489  *
 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.
 496  */
 497 #define iosys_map_wr_field(map__, struct_offset__, struct_type__, field__, val__) ({    \
 498         struct_type__ *s;                                                               \
 499         iosys_map_wr(map__, struct_offset__ + offsetof(struct_type__, field__),         \
 500                      typeof(s->field__), val__);                                        \
 501 })
 502
 503 #endif /* __IOSYS_MAP_H__ */