From 03b2f8472c8d4875a209920482cf44c7c6018eb7 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Pali=20Roh=C3=A1r?= Date: Sat, 17 Feb 2024 16:30:30 +0100 Subject: [PATCH] libpci: Document physmem API --- lib/physmem.h | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/lib/physmem.h b/lib/physmem.h index 46ee021..28152a1 100644 --- a/lib/physmem.h +++ b/lib/physmem.h @@ -15,5 +15,26 @@ int physmem_access(struct pci_access *a, int w); struct physmem *physmem_open(struct pci_access *a, int w); void physmem_close(struct physmem *physmem); long physmem_get_pagesize(struct physmem *physmem); + +/* + * physmem_map returns ptr on success, (void *)-1 on error and sets errno compatible with POSIX mmap(): + * - EBADF - invalid physmem argument + * - EINVAL - invalid or unaligned addr argument + * - EACCES - write access requested but physmem was opened without write access + * - ENOSYS - physmem argument does not support physical address mapping at all + * - ENXIO - addr/length range was rejected by system (e.g. range not accessible or not available) + * - EOVERFLOW - addr/length range is out of the physical address space (e.g. does not fit into signed 32-bit off_t type on 32-bit systems) + * - EACCES - generic unknown error for djgpp and windows + */ void *physmem_map(struct physmem *physmem, u64 addr, size_t length, int w); + +/* + * Unmap physical memory mapping, ptr and length must be exactly same as for physmem_map(), unmapping just subrange is not allowed. + * physmem_unmap returns 0 on success, -1 on error and sets errno: + * - EBADF - invalid physmem argument + * - EINVAL - invalid ptr/length argument + * - EPERM - ptr/length range cannot be unmapped due to access permission checks (e.g. page marked as immutable) + * - ENOSYS - physmem argument does not support physical address unmapping at all (e.g. every mapping stays active until application terminates) + * - EACCES - generic unknown error for djgpp and windows + */ int physmem_unmap(struct physmem *physmem, void *ptr, size_t length); -- 2.39.2