linux-toradex.git/Documentation/driver-api/dma-buf.rst, branch v6.3

Documentation: driver-api: correct spelling

2023-02-02T18:05:16+00:00

Correct spelling problems for Documentation/driver-api/ as reported
by codespell.

Signed-off-by: Randy Dunlap 
Cc: Mauro Carvalho Chehab 
Cc: linux-media@vger.kernel.org
Cc: Vishal Verma 
Cc: Dave Jiang 
Cc: nvdimm@lists.linux.dev
Cc: Vinod Koul 
Cc: dmaengine@vger.kernel.org
Cc: linux-raid@vger.kernel.org
Cc: linux-usb@vger.kernel.org
Acked-by: Dan Williams 
Acked-by: Song Liu 
Acked-by: Greg Kroah-Hartman 
Link: https://lore.kernel.org/r/20230129231053.20863-3-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet

dma-buf: Add "dma-buf" to title of documentation

2023-01-31T20:56:05+00:00

To make it easier to find the dma-buf documentation when looking through
tables-of-contents etc., put the name "dma-buf" in the title.

Signed-off-by: Jonathan Neuschäfer 
Link: https://lore.kernel.org/r/20230129115917.1229529-1-j.neuschaefer@gmx.net
Signed-off-by: Jonathan Corbet

dma-buf: Document dynamic locking convention

2022-10-17T22:21:53+00:00

Add documentation for the dynamic locking convention. The documentation
tells dma-buf API users when they should take the reservation lock and
when not.

Acked-by: Sumit Semwal 
Reviewed-by: Christian König 
Signed-off-by: Dmitry Osipenko 
Link: https://patchwork.freedesktop.org/patch/msgid/20221017172229.42269-20-dmitry.osipenko@collabora.com

dma-buf: add dma_fence_unwrap v2

2022-03-25T13:18:28+00:00

Add a general purpose helper to deep dive into dma_fence_chain/dma_fence_array
structures and iterate over all the fences in them.

This is useful when we need to flatten out all fences in those structures.

v2: some selftests cleanup, improved function naming and documentation

Signed-off-by: Christian König 
Reviewed-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20220311110244.1245-1-christian.koenig@amd.com

dma-buf-map: Rename to iosys-map

2022-02-08T00:35:35+00:00

Rename struct dma_buf_map to struct iosys_map and corresponding APIs.
Over time dma-buf-map grew up to more functionality than the one used by
dma-buf: in fact it's just a shim layer to abstract system memory, that
can be accessed via regular load and store, from IO memory that needs to
be acessed via arch helpers.

The idea is to extend this API so it can fulfill other needs, internal
to a single driver. Example: in the i915 driver it's desired to share
the implementation for integrated graphics, which uses mostly system
memory, with discrete graphics, which may need to access IO memory.

The conversion was mostly done with the following semantic patch:

	@r1@
	@@
	- struct dma_buf_map
	+ struct iosys_map

	@r2@
	@@
	(
	- DMA_BUF_MAP_INIT_VADDR
	+ IOSYS_MAP_INIT_VADDR
	|
	- dma_buf_map_set_vaddr
	+ iosys_map_set_vaddr
	|
	- dma_buf_map_set_vaddr_iomem
	+ iosys_map_set_vaddr_iomem
	|
	- dma_buf_map_is_equal
	+ iosys_map_is_equal
	|
	- dma_buf_map_is_null
	+ iosys_map_is_null
	|
	- dma_buf_map_is_set
	+ iosys_map_is_set
	|
	- dma_buf_map_clear
	+ iosys_map_clear
	|
	- dma_buf_map_memcpy_to
	+ iosys_map_memcpy_to
	|
	- dma_buf_map_incr
	+ iosys_map_incr
	)

	@@
	@@
	- #include 
	+ #include 

Then some files had their includes adjusted and some comments were
update to remove mentions to dma-buf-map.

Since this is not specific to dma-buf anymore, move the documentation to
the "Bus-Independent Device Accesses" section.

v2:
  - Squash patches

v3:
  - Fix wrong removal of dma-buf.h from MAINTAINERS
  - Move documentation from dma-buf.rst to device-io.rst

v4:
  - Change documentation title and level

Signed-off-by: Lucas De Marchi 
Acked-by: Christian König 
Acked-by: Sumit Semwal 
Acked-by: Thomas Zimmermann 
Link: https://patchwork.freedesktop.org/patch/msgid/20220204170541.829227-1-lucas.demarchi@intel.com

dma-buf: cleanup kerneldoc of removed component

2021-09-02T11:14:40+00:00

The seqno-fence was removed, cleanup the kerneldoc include as well.

Signed-off-by: Christian König 
Acked-by: Sumit Semwal 
Fixes: 992c238188a8 ("dma-buf: nuke seqno-fence")
Link: https://patchwork.freedesktop.org/patch/msgid/20210901080002.5892-1-christian.koenig@amd.com

dma-buf: Document DMA_BUF_IOCTL_SYNC (v3)

2021-06-17T19:46:37+00:00

This adds a new "DMA Buffer ioctls" section to the dma-buf docs and adds
documentation for DMA_BUF_IOCTL_SYNC.

v2 (Daniel Vetter):
 - Fix a couple typos
 - Add commentary about synchronization with other devices
 - Use item list format for describing flags

v3 (Pekka Paalanen):
 - Clarify stalling requirements.
 - Be more clear that that DMA_BUF_IOCTL_SYNC with SINC_END has to be
   called before more GPU work happens.

Signed-off-by: Jason Ekstrand 
Reviewed-by: Daniel Vetter 
Acked-by: Christian König 
Acked-by: Pekka Paalanen 
Cc: Sumit Semwal 
Signed-off-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20210617194258.579011-1-jason@jlekstrand.net

dmabuf: Add the capability to expose DMA-BUF stats in sysfs

2021-06-15T09:50:24+00:00

Overview
========
The patch adds DMA-BUF statistics to /sys/kernel/dmabuf/buffers. It
allows statistics to be enabled for each DMA-BUF in sysfs by enabling
the config CONFIG_DMABUF_SYSFS_STATS.

The following stats will be exposed by the interface:

/sys/kernel/dmabuf/buffers//exporter_name
/sys/kernel/dmabuf/buffers//size
/sys/kernel/dmabuf/buffers//attachments//device
/sys/kernel/dmabuf/buffers//attachments//map_counter

The inode_number is unique for each DMA-BUF and was added earlier [1]
in order to allow userspace to track DMA-BUF usage across different
processes.

Use Cases
=========
The interface provides a way to gather DMA-BUF per-buffer statistics
from production devices. These statistics will be used to derive DMA-BUF
per-exporter stats and per-device usage stats for Android Bug reports.
The corresponding userspace changes can be found at [2].
Telemetry tools will also capture this information(along with other
memory metrics) periodically as well as on important events like a
foreground app kill (which might have been triggered by Low Memory
Killer). It will also contribute to provide a snapshot of the system
memory usage on other events such as OOM kills and Application Not
Responding events.

Background
==========
Currently, there are two existing interfaces that provide information
about DMA-BUFs.
1) /sys/kernel/debug/dma_buf/bufinfo
debugfs is however unsuitable to be mounted in production systems and
cannot be considered as an alternative to the sysfs interface being
proposed.
2) proc//fdinfo/
The proc//fdinfo/ files expose information about DMA-BUF fds.
However, the existing procfs interfaces can only provide information
about the buffers for which processes hold fds or have the buffers
mmapped into their address space. Since the procfs interfaces alone
cannot provide a full picture of all DMA-BUFs in the system, there is
the need for an alternate interface to provide this information on
production systems.

The patch contains the following major improvements over v1:
1) Each attachment is represented by its own directory to allow creating
a symlink to the importing device and to also provide room for future
expansion.
2) The number of distinct mappings of each attachment is exposed in a
separate file.
3) The per-buffer statistics are now in /sys/kernel/dmabuf/buffers
inorder to make the interface expandable in future.

All of the improvements above are based on suggestions/feedback from
Daniel Vetter and Christian König.

A shell script that can be run on a classic Linux environment to read
out the DMA-BUF statistics can be found at [3](suggested by John
Stultz).

[1]: https://lore.kernel.org/patchwork/patch/1088791/
[2]: https://android-review.googlesource.com/q/topic:%22dmabuf-sysfs%22+(status:open%20OR%20status:merged)
[3]: https://android-review.googlesource.com/c/platform/system/memory/libmeminfo/+/1549734

Reviewed-by: Greg Kroah-Hartman 
Signed-off-by: Hridya Valsaraju 
Reported-by: kernel test robot 
Signed-off-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20210603214758.2955251-1-hridya@google.com

drm/doc: Include fence chain api

2021-06-03T08:32:49+00:00

We have this nice kerneldoc, but forgot to include it.

Reviewed-by: Christian König 
Signed-off-by: Daniel Vetter 
Cc: Sumit Semwal 
Cc: "Christian König" 
Cc: linux-media@vger.kernel.org
Cc: linaro-mm-sig@lists.linaro.org
Link: https://patchwork.freedesktop.org/patch/msgid/20210521082457.1656333-1-daniel.vetter@ffwll.ch

dma-fence: Document recoverable page fault implications

2021-03-12T14:10:03+00:00

Recently there was a fairly long thread about recoreable hardware page
faults, how they can deadlock, and what to do about that.

While the discussion is still fresh I figured good time to try and
document the conclusions a bit. This documentation section explains
what's the potential problem, and the remedies we've discussed,
roughly ordered from best to worst.

v2: Linus -> Linux typoe (Dave)

v3:
- Make it clear drivers only need to implement one option (Christian)
- Make it clearer that implicit sync is out the window with exclusive
  fences (Christian)
- Add the fairly theoretical option of segementing the memory (either
  statically or through dynamic checks at runtime for which piece of
  memory is managed how) and explain why it's not a great idea (Felix)

References: https://lore.kernel.org/dri-devel/20210107030127.20393-1-Felix.Kuehling@amd.com/
Reviewed-by: Christian König 
Acked-by: Thomas Hellström 
Reviewed-by: Felix Kuehling 
c: Dave Airlie 
Cc: Maarten Lankhorst 
Cc: Thomas Hellström 
Cc: "Christian König" 
Cc: Jerome Glisse 
Cc: Felix Kuehling 
Signed-off-by: Daniel Vetter 
Cc: Sumit Semwal 
Cc: linux-media@vger.kernel.org
Cc: linaro-mm-sig@lists.linaro.org
Link: https://patchwork.freedesktop.org/patch/msgid/20210203152921.2429937-1-daniel.vetter@ffwll.ch