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 than 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_INIT_VADDR_IOMEM() or
 50 * iosys_map_set_vaddr_iomem().
 51 *
 52 * .. code-block:: c
 53 *
 54 *	struct iosys_map map = IOSYS_MAP_INIT_VADDR_IOMEM(0xdeadbeaf);
 55 *
 56 *	iosys_map_set_vaddr_iomem(&map, 0xdeadbeaf);
 57 *
 58 * Instances of struct iosys_map do not have to be cleaned up, but
 59 * can be cleared to NULL with iosys_map_clear(). Cleared mappings
 60 * always refer to system memory.
 61 *
 62 * .. code-block:: c
 63 *
 64 *	iosys_map_clear(&map);
 65 *
 66 * Test if a mapping is valid with either iosys_map_is_set() or
 67 * iosys_map_is_null().
 68 *
 69 * .. code-block:: c
 70 *
 71 *	if (iosys_map_is_set(&map) != iosys_map_is_null(&map))
 72 *		// always true
 73 *
 74 * Instances of :c:type:`struct iosys_map <iosys_map>` can be compared for
 75 * equality with iosys_map_is_equal(). Mappings that point to different memory
 76 * spaces, system or I/O, are never equal. That's even true if both spaces are
 77 * located in the same address space, both mappings contain the same address
 78 * value, or both mappings refer to NULL.
 79 *
 80 * .. code-block:: c
 81 *
 82 *	struct iosys_map sys_map; // refers to system memory
 83 *	struct iosys_map io_map; // refers to I/O memory
 84 *
 85 *	if (iosys_map_is_equal(&sys_map, &io_map))
 86 *		// always false
 87 *
 88 * A set up instance of struct iosys_map can be used to access or manipulate the
 89 * buffer memory. Depending on the location of the memory, the provided helpers
 90 * will pick the correct operations. Data can be copied into the memory with
 91 * iosys_map_memcpy_to(). The address can be manipulated with iosys_map_incr().
 92 *
 93 * .. code-block:: c
 94 *
 95 *	const void *src = ...; // source buffer
 96 *	size_t len = ...; // length of src
 97 *
 98 *	iosys_map_memcpy_to(&map, src, len);
 99 *	iosys_map_incr(&map, len); // go to first byte after the memcpy
100 */
101
102/**
103 * struct iosys_map - Pointer to IO/system memory
104 * @vaddr_iomem:	The buffer's address if in I/O memory
105 * @vaddr:		The buffer's address if in system memory
106 * @is_iomem:		True if the buffer is located in I/O memory, or false
107 *			otherwise.
108 */
109struct iosys_map {
110	union {
111		void __iomem *vaddr_iomem;
112		void *vaddr;
113	};
114	bool is_iomem;
115};
116
117/**
118 * IOSYS_MAP_INIT_VADDR - Initializes struct iosys_map to an address in system memory
119 * @vaddr_:	A system-memory address
120 */
121#define IOSYS_MAP_INIT_VADDR(vaddr_)	\
122	{				\
123		.vaddr = (vaddr_),	\
124		.is_iomem = false,	\
125	}
126
127/**
128 * IOSYS_MAP_INIT_VADDR_IOMEM - Initializes struct iosys_map to an address in I/O memory
129 * @vaddr_iomem_:	An I/O-memory address
130 */
131#define IOSYS_MAP_INIT_VADDR_IOMEM(vaddr_iomem_)	\
132	{						\
133		.vaddr_iomem = (vaddr_iomem_),		\
134		.is_iomem = true,			\
135	}
136
137/**
138 * IOSYS_MAP_INIT_OFFSET - Initializes struct iosys_map from another iosys_map
139 * @map_:	The dma-buf mapping structure to copy from
140 * @offset_:	Offset to add to the other mapping
141 *
142 * Initializes a new iosys_map struct based on another passed as argument. It
143 * does a shallow copy of the struct so it's possible to update the back storage
144 * without changing where the original map points to. It is the equivalent of
145 * doing:
146 *
147 * .. code-block:: c
148 *
149 *	iosys_map map = other_map;
150 *	iosys_map_incr(&map, &offset);
151 *
152 * Example usage:
153 *
154 * .. code-block:: c
155 *
156 *	void foo(struct device *dev, struct iosys_map *base_map)
157 *	{
158 *		...
159 *		struct iosys_map map = IOSYS_MAP_INIT_OFFSET(base_map, FIELD_OFFSET);
160 *		...
161 *	}
162 *
163 * The advantage of using the initializer over just increasing the offset with
164 * iosys_map_incr() like above is that the new map will always point to the
165 * right place of the buffer during its scope. It reduces the risk of updating
166 * the wrong part of the buffer and having no compiler warning about that. If
167 * the assignment to IOSYS_MAP_INIT_OFFSET() is forgotten, the compiler can warn
168 * about the use of uninitialized variable.
169 */
170#define IOSYS_MAP_INIT_OFFSET(map_, offset_) ({				\
171	struct iosys_map copy_ = *map_;					\
172	iosys_map_incr(&copy_, offset_);				\
173	copy_;								\
174})
175
176/**
177 * iosys_map_set_vaddr - Sets a iosys mapping structure to an address in system memory
178 * @map:	The iosys_map structure
179 * @vaddr:	A system-memory address
180 *
181 * Sets the address and clears the I/O-memory flag.
182 */
183static inline void iosys_map_set_vaddr(struct iosys_map *map, void *vaddr)
184{
185	map->vaddr = vaddr;
186	map->is_iomem = false;
187}
188
189/**
190 * iosys_map_set_vaddr_iomem - Sets a iosys mapping structure to an address in I/O memory
191 * @map:		The iosys_map structure
192 * @vaddr_iomem:	An I/O-memory address
193 *
194 * Sets the address and the I/O-memory flag.
195 */
196static inline void iosys_map_set_vaddr_iomem(struct iosys_map *map,
197					     void __iomem *vaddr_iomem)
198{
199	map->vaddr_iomem = vaddr_iomem;
200	map->is_iomem = true;
201}
202
203/**
204 * iosys_map_is_equal - Compares two iosys mapping structures for equality
205 * @lhs:	The iosys_map structure
206 * @rhs:	A iosys_map structure to compare with
207 *
208 * Two iosys mapping structures are equal if they both refer to the same type of memory
209 * and to the same address within that memory.
210 *
211 * Returns:
212 * True is both structures are equal, or false otherwise.
213 */
214static inline bool iosys_map_is_equal(const struct iosys_map *lhs,
215				      const struct iosys_map *rhs)
216{
217	if (lhs->is_iomem != rhs->is_iomem)
218		return false;
219	else if (lhs->is_iomem)
220		return lhs->vaddr_iomem == rhs->vaddr_iomem;
221	else
222		return lhs->vaddr == rhs->vaddr;
223}
224
225/**
226 * iosys_map_is_null - Tests for a iosys mapping to be NULL
227 * @map:	The iosys_map structure
228 *
229 * Depending on the state of struct iosys_map.is_iomem, tests if the
230 * mapping is NULL.
231 *
232 * Returns:
233 * True if the mapping is NULL, or false otherwise.
234 */
235static inline bool iosys_map_is_null(const struct iosys_map *map)
236{
237	if (map->is_iomem)
238		return !map->vaddr_iomem;
239	return !map->vaddr;
240}
241
242/**
243 * iosys_map_is_set - Tests if the iosys mapping has been set
244 * @map:	The iosys_map structure
245 *
246 * Depending on the state of struct iosys_map.is_iomem, tests if the
247 * mapping has been set.
248 *
249 * Returns:
250 * True if the mapping is been set, or false otherwise.
251 */
252static inline bool iosys_map_is_set(const struct iosys_map *map)
253{
254	return !iosys_map_is_null(map);
255}
256
257/**
258 * iosys_map_clear - Clears a iosys mapping structure
259 * @map:	The iosys_map structure
260 *
261 * Clears all fields to zero, including struct iosys_map.is_iomem, so
262 * mapping structures that were set to point to I/O memory are reset for
263 * system memory. Pointers are cleared to NULL. This is the default.
264 */
265static inline void iosys_map_clear(struct iosys_map *map)
266{
267	memset(map, 0, sizeof(*map));
268}
269
270/**
271 * iosys_map_memcpy_to - Memcpy into offset of iosys_map
272 * @dst:	The iosys_map structure
273 * @dst_offset:	The offset from which to copy
274 * @src:	The source buffer
275 * @len:	The number of byte in src
276 *
277 * Copies data into a iosys_map with an offset. The source buffer is in
278 * system memory. Depending on the buffer's location, the helper picks the
279 * correct method of accessing the memory.
280 */
281static inline void iosys_map_memcpy_to(struct iosys_map *dst, size_t dst_offset,
282				       const void *src, size_t len)
283{
284	if (dst->is_iomem)
285		memcpy_toio(dst->vaddr_iomem + dst_offset, src, len);
286	else
287		memcpy(dst->vaddr + dst_offset, src, len);
288}
289
290/**
291 * iosys_map_memcpy_from - Memcpy from iosys_map into system memory
292 * @dst:	Destination in system memory
293 * @src:	The iosys_map structure
294 * @src_offset:	The offset from which to copy
295 * @len:	The number of byte in src
296 *
297 * Copies data from a iosys_map with an offset. The dest buffer is in
298 * system memory. Depending on the mapping location, the helper picks the
299 * correct method of accessing the memory.
300 */
301static inline void iosys_map_memcpy_from(void *dst, const struct iosys_map *src,
302					 size_t src_offset, size_t len)
303{
304	if (src->is_iomem)
305		memcpy_fromio(dst, src->vaddr_iomem + src_offset, len);
306	else
307		memcpy(dst, src->vaddr + src_offset, len);
308}
309
310/**
311 * iosys_map_incr - Increments the address stored in a iosys mapping
312 * @map:	The iosys_map structure
313 * @incr:	The number of bytes to increment
314 *
315 * Increments the address stored in a iosys mapping. Depending on the
316 * buffer's location, the correct value will be updated.
317 */
318static inline void iosys_map_incr(struct iosys_map *map, size_t incr)
319{
320	if (map->is_iomem)
321		map->vaddr_iomem += incr;
322	else
323		map->vaddr += incr;
324}
325
326/**
327 * iosys_map_memset - Memset iosys_map
328 * @dst:	The iosys_map structure
329 * @offset:	Offset from dst where to start setting value
330 * @value:	The value to set
331 * @len:	The number of bytes to set in dst
332 *
333 * Set value in iosys_map. Depending on the buffer's location, the helper
334 * picks the correct method of accessing the memory.
335 */
336static inline void iosys_map_memset(struct iosys_map *dst, size_t offset,
337				    int value, size_t len)
338{
339	if (dst->is_iomem)
340		memset_io(dst->vaddr_iomem + offset, value, len);
341	else
342		memset(dst->vaddr + offset, value, len);
343}
344
345#ifdef CONFIG_64BIT
346#define __iosys_map_rd_io_u64_case(val_, vaddr_iomem_)				\
347	u64: val_ = readq(vaddr_iomem_)
348#define __iosys_map_wr_io_u64_case(val_, vaddr_iomem_)				\
349	u64: writeq(val_, vaddr_iomem_)
350#else
351#define __iosys_map_rd_io_u64_case(val_, vaddr_iomem_)				\
352	u64: memcpy_fromio(&(val_), vaddr_iomem_, sizeof(u64))
353#define __iosys_map_wr_io_u64_case(val_, vaddr_iomem_)				\
354	u64: memcpy_toio(vaddr_iomem_, &(val_), sizeof(u64))
355#endif
356
357#define __iosys_map_rd_io(val__, vaddr_iomem__, type__) _Generic(val__,		\
358	u8: val__ = readb(vaddr_iomem__),					\
359	u16: val__ = readw(vaddr_iomem__),					\
360	u32: val__ = readl(vaddr_iomem__),					\
361	__iosys_map_rd_io_u64_case(val__, vaddr_iomem__))
362
363#define __iosys_map_rd_sys(val__, vaddr__, type__)				\
364	val__ = READ_ONCE(*(type__ *)(vaddr__))
365
366#define __iosys_map_wr_io(val__, vaddr_iomem__, type__) _Generic(val__,		\
367	u8: writeb(val__, vaddr_iomem__),					\
368	u16: writew(val__, vaddr_iomem__),					\
369	u32: writel(val__, vaddr_iomem__),					\
370	__iosys_map_wr_io_u64_case(val__, vaddr_iomem__))
371
372#define __iosys_map_wr_sys(val__, vaddr__, type__)				\
373	WRITE_ONCE(*(type__ *)(vaddr__), val__)
374
375/**
376 * iosys_map_rd - Read a C-type value from the iosys_map
377 *
378 * @map__:	The iosys_map structure
379 * @offset__:	The offset from which to read
380 * @type__:	Type of the value being read
381 *
382 * Read a C type value (u8, u16, u32 and u64) from iosys_map. For other types or
383 * if pointer may be unaligned (and problematic for the architecture supported),
384 * use iosys_map_memcpy_from().
385 *
386 * Returns:
387 * The value read from the mapping.
388 */
389#define iosys_map_rd(map__, offset__, type__) ({					\
390	type__ val_;									\
391	if ((map__)->is_iomem) {							\
392		__iosys_map_rd_io(val_, (map__)->vaddr_iomem + (offset__), type__);	\
393	} else {									\
394		__iosys_map_rd_sys(val_, (map__)->vaddr + (offset__), type__);		\
395	}										\
396	val_;										\
397})
398
399/**
400 * iosys_map_wr - Write a C-type value to the iosys_map
401 *
402 * @map__:	The iosys_map structure
403 * @offset__:	The offset from the mapping to write to
404 * @type__:	Type of the value being written
405 * @val__:	Value to write
406 *
407 * Write a C type value (u8, u16, u32 and u64) to the iosys_map. For other types
408 * or if pointer may be unaligned (and problematic for the architecture
409 * supported), use iosys_map_memcpy_to()
410 */
411#define iosys_map_wr(map__, offset__, type__, val__) ({					\
412	type__ val_ = (val__);								\
413	if ((map__)->is_iomem) {							\
414		__iosys_map_wr_io(val_, (map__)->vaddr_iomem + (offset__), type__);	\
415	} else {									\
416		__iosys_map_wr_sys(val_, (map__)->vaddr + (offset__), type__);		\
417	}										\
418})
419
420/**
421 * iosys_map_rd_field - Read a member from a struct in the iosys_map
422 *
423 * @map__:		The iosys_map structure
424 * @struct_offset__:	Offset from the beginning of the map, where the struct
425 *			is located
426 * @struct_type__:	The struct describing the layout of the mapping
427 * @field__:		Member of the struct to read
428 *
429 * Read a value from iosys_map considering its layout is described by a C struct
430 * starting at @struct_offset__. The field offset and size is calculated and its
431 * value read. If the field access would incur in un-aligned access, then either
432 * iosys_map_memcpy_from() needs to be used or the architecture must support it.
433 * For example: suppose there is a @struct foo defined as below and the value
434 * ``foo.field2.inner2`` needs to be read from the iosys_map:
435 *
436 * .. code-block:: c
437 *
438 *	struct foo {
439 *		int field1;
440 *		struct {
441 *			int inner1;
442 *			int inner2;
443 *		} field2;
444 *		int field3;
445 *	} __packed;
446 *
447 * This is the expected memory layout of a buffer using iosys_map_rd_field():
448 *
449 * +------------------------------+--------------------------+
450 * | Address                      | Content                  |
451 * +==============================+==========================+
452 * | buffer + 0000                | start of mmapped buffer  |
453 * |                              | pointed by iosys_map     |
454 * +------------------------------+--------------------------+
455 * | ...                          | ...                      |
456 * +------------------------------+--------------------------+
457 * | buffer + ``struct_offset__`` | start of ``struct foo``  |
458 * +------------------------------+--------------------------+
459 * | ...                          | ...                      |
460 * +------------------------------+--------------------------+
461 * | buffer + wwww                | ``foo.field2.inner2``    |
462 * +------------------------------+--------------------------+
463 * | ...                          | ...                      |
464 * +------------------------------+--------------------------+
465 * | buffer + yyyy                | end of ``struct foo``    |
466 * +------------------------------+--------------------------+
467 * | ...                          | ...                      |
468 * +------------------------------+--------------------------+
469 * | buffer + zzzz                | end of mmaped buffer     |
470 * +------------------------------+--------------------------+
471 *
472 * Values automatically calculated by this macro or not needed are denoted by
473 * wwww, yyyy and zzzz. This is the code to read that value:
474 *
475 * .. code-block:: c
476 *
477 *	x = iosys_map_rd_field(&map, offset, struct foo, field2.inner2);
478 *
479 * Returns:
480 * The value read from the mapping.
481 */
482#define iosys_map_rd_field(map__, struct_offset__, struct_type__, field__) ({	\
483	struct_type__ *s_;							\
484	iosys_map_rd(map__, struct_offset__ + offsetof(struct_type__, field__),	\
485		     typeof(s_->field__));					\
486})
487
488/**
489 * iosys_map_wr_field - Write to a member of a struct in the iosys_map
490 *
491 * @map__:		The iosys_map structure
492 * @struct_offset__:	Offset from the beginning of the map, where the struct
493 *			is located
494 * @struct_type__:	The struct describing the layout of the mapping
495 * @field__:		Member of the struct to read
496 * @val__:		Value to write
497 *
498 * Write a value to the iosys_map considering its layout is described by a C
499 * struct starting at @struct_offset__. The field offset and size is calculated
500 * and the @val__ is written. If the field access would incur in un-aligned
501 * access, then either iosys_map_memcpy_to() needs to be used or the
502 * architecture must support it. Refer to iosys_map_rd_field() for expected
503 * usage and memory layout.
504 */
505#define iosys_map_wr_field(map__, struct_offset__, struct_type__, field__, val__) ({	\
506	struct_type__ *s_;								\
507	iosys_map_wr(map__, struct_offset__ + offsetof(struct_type__, field__),		\
508		     typeof(s_->field__), val__);					\
509})
510
511#endif /* __IOSYS_MAP_H__ */