Re: [cdi-devel] [RFC PATCH] mem.h: Handling memory areas [edit: documentation]

[Matthew Iselin <matthew@xxxxxxxxxxxxxx>]

Just updated the header documentation a little to make
cdi_mem_require_flags make more sense.

I'm now happy for this to be committed when necessary.

Signed-off-by: Matthew Iselin <matthew@xxxxxxxxxxxxxx>
Signed-off-by: Kevin Wolf <kevin@xxxxxxxxxx>
---
 include/cdi/mem.h |  165 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 165 insertions(+), 0 deletions(-)
 create mode 100644 include/cdi/mem.h

diff --git a/include/cdi/mem.h b/include/cdi/mem.h
new file mode 100644
index 0000000..852c258
--- /dev/null
+++ b/include/cdi/mem.h
@@ -0,0 +1,165 @@
+/*
+ * Copyright (c) 2007 Kevin Wolf
+ *
+ * This program is free software. It comes without any warranty, to
+ * the extent permitted by applicable law. You can redistribute it
+ * and/or modify it under the terms of the Do What The Fuck You Want
+ * To Public License, Version 2, as published by Sam Hocevar. See
+ * http://sam.zoy.org/projects/COPYING.WTFPL for more details.
+ */
+
+#ifndef _CDI_MEM_H_
+#define _CDI_MEM_H_
+
+#include <stdint.h>
+#include "cdi.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \german
+ * Beschreibt Anforderungen an einen Speicherbereich
+ * \endgerman
+ * \english
+ * Describes requirements for a memory area
+ * \endenglish
+ */
+typedef enum {
+    /**
+     * \german
+     * Physisch zusammenhängenden Speicher anfordern
+     * \endgerman
+     * \english
+     * Request physically contiguous memory
+     * \endenglish
+     */
+    CDI_MEM_PHYS_CONTIGUOUS = 0x1,
+
+    /**
+     * \german
+     * Physischen Speicher < 16 MB anfordern
+     * \endgerman
+     * \english
+     * Request physical memory < 16 MB
+     * \endenglish
+     */
+    CDI_MEM_DMA_16M         = 0x2,
+
+    /**
+     * \german
+     * Physischen Speicher < 4 GB anfordern
+     * \endgerman
+     * \english
+     * Request physical memory < 4 GB
+     * \endenglish
+     */
+    CDI_MEM_DMA_4G          = 0x4,
+
+    /**
+     * \german
+     * Speicher muss nicht initialisiert werden (verhindert Kopie bei
+     * cdi_mem_require_flags)
+     * \endgerman
+     * \english
+     * Memory doesn't need to be initialised (avoids copy in
+     * cdi_mem_require_flags)
+     * \endenglish
+     */
+    CDI_MEM_NOINIT          = 0x8,
+} cdi_mem_flags_t;
+
+struct cdi_mem_area {
+    size_t      size;
+    void*       vaddr;
+    uintptr_t   paddr;
+
+    cdi_mem_osdep osdep;
+}
+
+/**
+ * \german
+ * Reserviert einen Speicherbereich. Die Funktion arbeitet nur mit ganzen
+ * Pages.
+ *
+ * @param size Größe des Speicherbereichs in Bytes
+ * @param flags Flags, die zusätzliche Anforderungen beschreiben
+ * \endgerman
+ * \english
+ * Allocates a memory area. The function only works with complete pages.
+ *
+ * @param size Size of the memory area in bytes
+ * @param flags Flags that describe additional requirements
+ * \endenglish
+ */
+struct cdi_mem_area* cdi_mem_alloc(size_t size, cdi_mem_flags_t flags);
+
+/**
+ * \german
+ * Gibt einen durch cdi_mem_alloc reservierten Speicherbereich frei
+ * \endgerman
+ * \english
+ * Frees a memory area that was previously allocated by cdi_mem_alloc
+ * \endenglish
+ */
+void cdi_mem_free(struct cdi_memory_area* p);
+
+/**
+ * \german
+ * Gibt einen Speicherbereich zurück, der dieselben Daten wie @a p beschreibt,
+ * aber mindestens die gegebenen Flags gesetzt hat.
+ *
+ * Diese Funktion kann denselben virtuellen und physischen Speicherbereich wie
+ * @p benutzen oder sogar @p selbst zurückzugeben, solange der gemeinsam
+ * benutzte Speicher erst dann freigegeben wird, wenn sowohl @a p als auch der
+ * Rückgabewert durch cdi_mem_free freigegeben worden sind.
+ *
+ * Ansonsten wird ein neuer Speicherbereich reserviert und (außer wenn das
+ * Flag CDI_MEM_NOINIT gesetzt ist) die Daten werden aus @a p in den neu
+ * reservierten Speicher kopiert.
+ * \endgerman
+ * \english
+ * Returns a memory area that describes the same data as @a p does, but for
+ * which at least the given flags are set.
+ *
+ * This function may use the same virtual and physical memory areas as used in
+ * @a p, or it may even return @a p itself. In this case it must ensure that
+ * the commonly used memory is only freed when both @a p and the return value
+ * of this function have been freed by cdi_mem_free.
+ *
+ * Otherwise, a new memory area is allocated and data is copied from @a p into
+ * the newly allocated memory (unless CDI_MEM_NOINIT is set).
+ * \endenglish
+ */
+struct cdi_mem_area* cdi_mem_require_flags(struct cdi_mem_area* p,
+    cdi_mem_flags_t flags);
+
+/**
+ * \german
+ * Kopiert die Daten von @a src nach @a dest. Beide Speicherbereiche müssen
+ * gleich groß sein.
+ *
+ * @return 0 bei Erfolg, -1 sonst
+ * \endgerman
+ * \english
+ * Copies data from @a src to @a dest. Both memory areas must be of the same
+ * size.
+ *
+ *
+ * @return 0 on success, -1 otherwise
+ * \endenglish
+ */
+int cdi_mem_copy(struct cdi_mem_area* dest, struct cdi_mem_area* src);
+
+#ifdef __cplusplus
+}; // extern "C"
+#endif
+
+#endif
+