* [Qemu-devel] [PATCH v2 1/4] memory: make memory API parsable by gtkdoc-scan (v2)
2011-12-14 20:01 [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Anthony Liguori
@ 2011-12-14 20:01 ` Anthony Liguori
2011-12-15 9:28 ` Kevin Wolf
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2) Anthony Liguori
` (4 subsequent siblings)
5 siblings, 1 reply; 20+ messages in thread
From: Anthony Liguori @ 2011-12-14 20:01 UTC (permalink / raw)
To: qemu-devel; +Cc: Peter Maydell, Anthony Liguori, Avi Kivity, Stefan Weil
gtkdoc-scan cannot handle nested structs so remove those from the memory API.
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
---
v1 -> v2
- no need to use underscores anymore
---
memory.h | 73 ++++++++++++++++++++++++++++++++++---------------------------
1 files changed, 41 insertions(+), 32 deletions(-)
diff --git a/memory.h b/memory.h
index beae127..057aa34 100644
--- a/memory.h
+++ b/memory.h
@@ -30,6 +30,8 @@ typedef struct MemoryRegionOps MemoryRegionOps;
typedef struct MemoryRegion MemoryRegion;
typedef struct MemoryRegionPortio MemoryRegionPortio;
typedef struct MemoryRegionMmio MemoryRegionMmio;
+typedef struct MemoryRegionGuestConstraints MemoryRegionGuestConstraints;
+typedef struct MemoryRegionInternalConstraints MemoryRegionInternalConstraints;
/* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
* registration.
@@ -43,6 +45,42 @@ struct MemoryRegionMmio {
CPUWriteMemoryFunc *write[3];
};
+struct MemoryRegionGuestConstraints
+{
+ /* If nonzero, specify bounds on access sizes beyond which a machine
+ * check is thrown.
+ */
+ unsigned min_access_size;
+ unsigned max_access_size;
+ /* If true, unaligned accesses are supported. Otherwise unaligned
+ * accesses throw machine checks.
+ */
+ bool unaligned;
+ /*
+ * If present, and returns #false, the transaction is not accepted
+ * by the device (and results in machine dependent behaviour such
+ * as a machine check exception).
+ */
+ bool (*accepts)(void *opaque, target_phys_addr_t addr,
+ unsigned size, bool is_write);
+};
+
+struct MemoryRegionInternalConstraints
+{
+ /* If nonzero, specifies the minimum size implemented. Smaller sizes
+ * will be rounded upwards and a partial result will be returned.
+ */
+ unsigned min_access_size;
+ /* If nonzero, specifies the maximum size implemented. Larger sizes
+ * will be done as a series of accesses with smaller sizes.
+ */
+ unsigned max_access_size;
+ /* If true, unaligned accesses are supported. Otherwise all accesses
+ * are converted to (possibly multiple) naturally aligned accesses.
+ */
+ bool unaligned;
+};
+
/*
* Memory region callbacks
*/
@@ -61,39 +99,10 @@ struct MemoryRegionOps {
enum device_endian endianness;
/* Guest-visible constraints: */
- struct {
- /* If nonzero, specify bounds on access sizes beyond which a machine
- * check is thrown.
- */
- unsigned min_access_size;
- unsigned max_access_size;
- /* If true, unaligned accesses are supported. Otherwise unaligned
- * accesses throw machine checks.
- */
- bool unaligned;
- /*
- * If present, and returns #false, the transaction is not accepted
- * by the device (and results in machine dependent behaviour such
- * as a machine check exception).
- */
- bool (*accepts)(void *opaque, target_phys_addr_t addr,
- unsigned size, bool is_write);
- } valid;
+ MemoryRegionGuestConstraints valid;
+
/* Internal implementation constraints: */
- struct {
- /* If nonzero, specifies the minimum size implemented. Smaller sizes
- * will be rounded upwards and a partial result will be returned.
- */
- unsigned min_access_size;
- /* If nonzero, specifies the maximum size implemented. Larger sizes
- * will be done as a series of accesses with smaller sizes.
- */
- unsigned max_access_size;
- /* If true, unaligned accesses are supported. Otherwise all accesses
- * are converted to (possibly multiple) naturally aligned accesses.
- */
- bool unaligned;
- } impl;
+ MemoryRegionInternalConstraints impl;
/* If .read and .write are not present, old_portio may be used for
* backwards compatibility with old portio registration
--
1.7.4.1
^ permalink raw reply related [flat|nested] 20+ messages in thread* Re: [Qemu-devel] [PATCH v2 1/4] memory: make memory API parsable by gtkdoc-scan (v2)
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 1/4] memory: make memory API parsable by gtkdoc-scan (v2) Anthony Liguori
@ 2011-12-15 9:28 ` Kevin Wolf
2011-12-15 13:25 ` Anthony Liguori
0 siblings, 1 reply; 20+ messages in thread
From: Kevin Wolf @ 2011-12-15 9:28 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Peter Maydell, Stefan Weil, qemu-devel, Avi Kivity
Am 14.12.2011 21:01, schrieb Anthony Liguori:
> gtkdoc-scan cannot handle nested structs so remove those from the memory API.
>
> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
Surely the right thing to do then is fixing gtkdoc-scan?
Kevin
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 1/4] memory: make memory API parsable by gtkdoc-scan (v2)
2011-12-15 9:28 ` Kevin Wolf
@ 2011-12-15 13:25 ` Anthony Liguori
0 siblings, 0 replies; 20+ messages in thread
From: Anthony Liguori @ 2011-12-15 13:25 UTC (permalink / raw)
To: Kevin Wolf; +Cc: Peter Maydell, Avi Kivity, qemu-devel, Stefan Weil
On 12/15/2011 03:28 AM, Kevin Wolf wrote:
> Am 14.12.2011 21:01, schrieb Anthony Liguori:
>> gtkdoc-scan cannot handle nested structs so remove those from the memory API.
>>
>> Signed-off-by: Anthony Liguori<aliguori@us.ibm.com>
>
> Surely the right thing to do then is fixing gtkdoc-scan?
It's not quite that simple. gtkdoc uses a documentation format of:
Thing
Longer description of thing
- sub-bullets about things parameters and/or members
- another sub-bullet about things parameters and/or members.
So it's expecting to deal with only one level of nesting. You would have to
make significant changes to deal with multiple levels of nesting.
That said, I think using an anonymous named structure for grouping is a bit
dubious to begin with.
Regards,
Anthony Liguori
>
> Kevin
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* [Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2)
2011-12-14 20:01 [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Anthony Liguori
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 1/4] memory: make memory API parsable by gtkdoc-scan (v2) Anthony Liguori
@ 2011-12-14 20:01 ` Anthony Liguori
2012-03-12 20:48 ` Eduardo Habkost
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 3/4] memory: update documentation to be in gtk-doc format Anthony Liguori
` (3 subsequent siblings)
5 siblings, 1 reply; 20+ messages in thread
From: Anthony Liguori @ 2011-12-14 20:01 UTC (permalink / raw)
To: qemu-devel; +Cc: Peter Maydell, Anthony Liguori, Avi Kivity, Stefan Weil
By convention, documented headers now go in include/
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
---
v1 -> v2
- Require the user to specify a path to the special gtk-doc tool
- Better handling of includes
---
Makefile | 6 +++++-
Makefile.docs | 29 +++++++++++++++++++++++++++++
Makefile.hw | 1 +
Makefile.target | 1 +
QEMU-docs.xml | 31 +++++++++++++++++++++++++++++++
5 files changed, 67 insertions(+), 1 deletions(-)
create mode 100644 Makefile.docs
create mode 100644 QEMU-docs.xml
diff --git a/Makefile b/Makefile
index 2c03055..f6b068c 100644
--- a/Makefile
+++ b/Makefile
@@ -92,6 +92,8 @@ ifneq ($(wildcard config-host.mak),)
include $(SRC_PATH)/Makefile.objs
endif
+include $(SRC_PATH)/Makefile.docs
+
$(common-obj-y): $(GENERATED_HEADERS)
subdir-libcacard: $(oslib-obj-y) $(trace-obj-y) qemu-timer-common.o
@@ -113,6 +115,8 @@ QEMU_CFLAGS+=$(CURL_CFLAGS)
QEMU_CFLAGS+=$(GLIB_CFLAGS)
+QEMU_CFLAGS+=-I$(SRC_PATH)/include
+
ui/cocoa.o: ui/cocoa.m
ui/sdl.o audio/sdlaudio.o ui/sdl_zoom.o baum.o: QEMU_CFLAGS += $(SDL_CFLAGS)
@@ -220,7 +224,7 @@ qemu-ga$(EXESUF): qemu-ga.o $(qga-obj-y) $(qapi-obj-y) $(tools-obj-y) $(qobject-
QEMULIBS=libhw32 libhw64 libuser libdis libdis-user
-clean:
+clean: gtkdoc-clean
# avoid old build problems by removing potentially incorrect old files
rm -f config.mak op-i386.h opc-i386.h gen-op-i386.h op-arm.h opc-arm.h gen-op-arm.h
rm -f qemu-options.def
diff --git a/Makefile.docs b/Makefile.docs
new file mode 100644
index 0000000..202b2c3
--- /dev/null
+++ b/Makefile.docs
@@ -0,0 +1,29 @@
+# -*- Mode: makefile -*-
+
+GTKDOC_SCAN=$(DOC_PREFIX)/gtkdoc-scan
+GTKDOC_MKDB=$(DOC_PREFIX)/gtkdoc-mkdb
+GTKDOC_MKHTML=$(DOC_PREFIX)/gtkdoc-mkhtml
+GTKDOC_FIXXREF=$(DOC_PREFIX)/gtkdoc-fixxref
+
+DOC_SRC=$(wildcard $(SRC_PATH)/include/*.h)
+
+ifeq ($(wildcard $(DOC_PREFIX)/gtkdoc-scan),)
+gtkdoc:
+ @echo Please set DOC_PREFIX before calling to a built version of:
+ @echo " git://git.qemu.org/gtk-doc.git"
+ @exit 1
+else
+gtkdoc: html/index.html
+
+html/index.html: $(DOC_SRC)
+ $(GTKDOC_SCAN) --module=QEMU --source-dir=$(SRC_PATH)/include && \
+ cp $(SRC_PATH)/QEMU-docs.xml . && \
+ $(GTKDOC_MKDB) --module=QEMU --output-format=xml --source-dir=$(SRC_PATH)/include && \
+ mkdir -p html && \
+ (cd html && $(GTKDOC_MKHTML) QEMU ../QEMU-docs.xml && cd ..) && \
+ $(GTKDOC_FIXXREF) --module=QEMU --module-dir=html
+endif
+
+gtkdoc-clean:
+ $(RM) -r html xml
+ $(RM) $(SCAN_GEN) sgml.stamp *.bak html.stamp
diff --git a/Makefile.hw b/Makefile.hw
index 63eb7e4..7b8d068 100644
--- a/Makefile.hw
+++ b/Makefile.hw
@@ -11,6 +11,7 @@ $(call set-vpath, $(SRC_PATH):$(SRC_PATH)/hw)
QEMU_CFLAGS+=-I..
QEMU_CFLAGS += $(GLIB_CFLAGS)
+QEMU_CFLAGS += -I$(SRC_PATH)/include
include $(SRC_PATH)/Makefile.objs
diff --git a/Makefile.target b/Makefile.target
index 8be9b9a..da8e668 100644
--- a/Makefile.target
+++ b/Makefile.target
@@ -19,6 +19,7 @@ ifdef CONFIG_LINUX
QEMU_CFLAGS += -I../linux-headers
endif
QEMU_CFLAGS += -I.. -I$(TARGET_PATH) -DNEED_CPU_H
+QEMU_CFLAGS += -I$(SRC_PATH)/include
include $(SRC_PATH)/Makefile.objs
diff --git a/QEMU-docs.xml b/QEMU-docs.xml
new file mode 100644
index 0000000..ddc827a
--- /dev/null
+++ b/QEMU-docs.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+ <bookinfo>
+ <title>QEMU Reference Manual</title>
+ <releaseinfo>
+ for QEMU 1.0.
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://wiki.qemu.org/docs-internal/">http://wiki.qemu.org/docs-internal/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+
+ <chapter>
+ <title>Core Device APIs</title>
+
+ </chapter>
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="deprecated-api-index" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
--
1.7.4.1
^ permalink raw reply related [flat|nested] 20+ messages in thread* Re: [Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2)
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2) Anthony Liguori
@ 2012-03-12 20:48 ` Eduardo Habkost
2012-03-12 23:37 ` Andreas Färber
0 siblings, 1 reply; 20+ messages in thread
From: Eduardo Habkost @ 2012-03-12 20:48 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Peter Maydell, Stefan Weil, qemu-devel, Avi Kivity
I don't know if this is really the latest version of the series, but I don't
see any newer version on my qemu-devel folder, so:
On Wed, Dec 14, 2011 at 02:01:12PM -0600, Anthony Liguori wrote:
[...]
> +html/index.html: $(DOC_SRC)
> + $(GTKDOC_SCAN) --module=QEMU --source-dir=$(SRC_PATH)/include && \
> + cp $(SRC_PATH)/QEMU-docs.xml . && \
When trying to build the docs I get the following error. It looks like the rule
is assuming an out-of-tree build:
$ make gtkdoc DOC_PREFIX=/home/ehabkost/pessoal/proj/virt/gtk-doc
/home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-scan --module=QEMU --source-dir=/home/ehabkost/pessoal/proj/virt/qemu/include && \
cp /home/ehabkost/pessoal/proj/virt/qemu/QEMU-docs.xml . && \
/home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-mkdb --module=QEMU --output-format=xml --source-dir=/home/ehabkost/pessoal/proj/virt/qemu/include && \
mkdir -p html && \
(cd html && /home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-mkhtml QEMU ../QEMU-docs.xml && cd ..) && \
/home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-fixxref --module=QEMU --module-dir=html
cp: `/home/ehabkost/pessoal/proj/virt/qemu/QEMU-docs.xml' and `./QEMU-docs.xml' are the same file
make: *** [html/index.html] Error 1
--
Eduardo
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2)
2012-03-12 20:48 ` Eduardo Habkost
@ 2012-03-12 23:37 ` Andreas Färber
0 siblings, 0 replies; 20+ messages in thread
From: Andreas Färber @ 2012-03-12 23:37 UTC (permalink / raw)
To: Eduardo Habkost
Cc: Avi Kivity, Peter Maydell, Anthony Liguori, qemu-devel,
Stefan Weil
Am 12.03.2012 21:48, schrieb Eduardo Habkost:
>
> I don't know if this is really the latest version of the series, but I don't
> see any newer version on my qemu-devel folder, so:
FWIW I have a rebased version on my qom-cpu-wip branch (no functional
changes). Note that mine depends on the qom-user series due to some -I
CFLAGS addition.
> On Wed, Dec 14, 2011 at 02:01:12PM -0600, Anthony Liguori wrote:
> [...]
>> +html/index.html: $(DOC_SRC)
>> + $(GTKDOC_SCAN) --module=QEMU --source-dir=$(SRC_PATH)/include && \
>> + cp $(SRC_PATH)/QEMU-docs.xml . && \
>
> When trying to build the docs I get the following error. It looks like the rule
> is assuming an out-of-tree build:
>
> $ make gtkdoc DOC_PREFIX=/home/ehabkost/pessoal/proj/virt/gtk-doc
> /home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-scan --module=QEMU --source-dir=/home/ehabkost/pessoal/proj/virt/qemu/include && \
> cp /home/ehabkost/pessoal/proj/virt/qemu/QEMU-docs.xml . && \
> /home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-mkdb --module=QEMU --output-format=xml --source-dir=/home/ehabkost/pessoal/proj/virt/qemu/include && \
> mkdir -p html && \
> (cd html && /home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-mkhtml QEMU ../QEMU-docs.xml && cd ..) && \
> /home/ehabkost/pessoal/proj/virt/gtk-doc/gtkdoc-fixxref --module=QEMU --module-dir=html
> cp: `/home/ehabkost/pessoal/proj/virt/qemu/QEMU-docs.xml' and `./QEMU-docs.xml' are the same file
> make: *** [html/index.html] Error 1
Never tried an in-tree build of this myself...
Andreas
--
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg
^ permalink raw reply [flat|nested] 20+ messages in thread
* [Qemu-devel] [PATCH v2 3/4] memory: update documentation to be in gtk-doc format
2011-12-14 20:01 [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Anthony Liguori
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 1/4] memory: make memory API parsable by gtkdoc-scan (v2) Anthony Liguori
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2) Anthony Liguori
@ 2011-12-14 20:01 ` Anthony Liguori
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 4/4] memory: move header into include/ and add to QEMU docs Anthony Liguori
` (2 subsequent siblings)
5 siblings, 0 replies; 20+ messages in thread
From: Anthony Liguori @ 2011-12-14 20:01 UTC (permalink / raw)
To: qemu-devel; +Cc: Peter Maydell, Anthony Liguori, Avi Kivity, Stefan Weil
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
---
memory.h | 341 ++++++++++++++++++++++++++++++++++----------------------------
1 files changed, 188 insertions(+), 153 deletions(-)
diff --git a/memory.h b/memory.h
index 057aa34..04370ff 100644
--- a/memory.h
+++ b/memory.h
@@ -16,6 +16,15 @@
#ifndef CONFIG_USER_ONLY
+/**
+ * SECTION:memory
+ * @title:Memory API
+ * @short_description: interfaces for dispatching I/O to devices
+ *
+ * The memory API models the memory and I/O buses and controllers of a QEMU
+ * machine.
+ */
+
#include <stdint.h>
#include <stdbool.h>
#include "qemu-common.h"
@@ -45,72 +54,76 @@ struct MemoryRegionMmio {
CPUWriteMemoryFunc *write[3];
};
+/**
+ * MemoryRegionGuestConstraints:
+ * @min_access_size: If nonzero, specify bounds on access sizes beyond which a
+ * machine check is thrown.
+ * @max_access_size: If nonzero, specify bounds on access sizes beyond which a
+ * machine check is thrown.
+ * @unaligned: If true, unaligned accesses are supported. Otherwise unaligned
+ * accesses throw machine checks.
+ * @accepts: If present, and returns #false, the transaction is not accepted
+ * by the device (and results in machine dependent behaviour such
+ * as a machine check exception).
+ *
+ * Guest-visible constraints.
+ */
struct MemoryRegionGuestConstraints
{
- /* If nonzero, specify bounds on access sizes beyond which a machine
- * check is thrown.
- */
unsigned min_access_size;
unsigned max_access_size;
- /* If true, unaligned accesses are supported. Otherwise unaligned
- * accesses throw machine checks.
- */
bool unaligned;
- /*
- * If present, and returns #false, the transaction is not accepted
- * by the device (and results in machine dependent behaviour such
- * as a machine check exception).
- */
bool (*accepts)(void *opaque, target_phys_addr_t addr,
unsigned size, bool is_write);
};
+/**
+ * MemoryRegionInternalConstraints:
+ * @min_access_size: If nonzero, specifies the minimum size implemented.
+ * Smaller sizes will be rounded upwards and a partial result will be
+ * returned.
+ * @max_access_size: If nonzero, specifies the maximum size implemented.
+ * Larger sizes will be done as a series of accesses with smaller sizes.
+ * @unaligned: If true, unaligned accesses are supported. Otherwise all
+ * accesses are converted to (possibly multiple) naturally aligned accesses.
+ *
+ * Internal implementation constraints.
+ */
struct MemoryRegionInternalConstraints
{
- /* If nonzero, specifies the minimum size implemented. Smaller sizes
- * will be rounded upwards and a partial result will be returned.
- */
unsigned min_access_size;
- /* If nonzero, specifies the maximum size implemented. Larger sizes
- * will be done as a series of accesses with smaller sizes.
- */
unsigned max_access_size;
- /* If true, unaligned accesses are supported. Otherwise all accesses
- * are converted to (possibly multiple) naturally aligned accesses.
- */
bool unaligned;
};
-/*
- * Memory region callbacks
+/**
+ * MemoryRegionOps:
+ * @read: Read from the memory region. addr is relative to mr; size is in bytes.
+ * @write: Write to the memory region. addr is relative to mr; size is in bytes.
+ * @valid: Guest visible constraints.
+ * @impl: Internal implementation constraints.
+ * @old_portio: If @read and @write are not present, may be used for
+ * backwards compatibility with old portio registration.
+ * @old_mmio: If @read and @write are not present, may be used for
+ * backwards compatibility with old mmio registration.
+ *
+ * Memory region callbacks.
*/
struct MemoryRegionOps {
- /* Read from the memory region. @addr is relative to @mr; @size is
- * in bytes. */
uint64_t (*read)(void *opaque,
target_phys_addr_t addr,
unsigned size);
- /* Write to the memory region. @addr is relative to @mr; @size is
- * in bytes. */
void (*write)(void *opaque,
target_phys_addr_t addr,
uint64_t data,
unsigned size);
enum device_endian endianness;
- /* Guest-visible constraints: */
- MemoryRegionGuestConstraints valid;
- /* Internal implementation constraints: */
+ MemoryRegionGuestConstraints valid;
MemoryRegionInternalConstraints impl;
- /* If .read and .write are not present, old_portio may be used for
- * backwards compatibility with old portio registration
- */
const MemoryRegionPortio *old_portio;
- /* If .read and .write are not present, old_mmio may be used for
- * backwards compatibility with old mmio registration
- */
const MemoryRegionMmio old_mmio;
};
@@ -119,6 +132,7 @@ typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
struct MemoryRegion {
/* All fields are private - violators will be prosecuted */
+ /*< private >*/
const MemoryRegionOps *ops;
void *opaque;
MemoryRegion *parent;
@@ -156,30 +170,32 @@ struct MemoryRegionPortio {
#define PORTIO_END_OF_LIST() { }
/**
- * memory_region_init: Initialize a memory region
- *
- * The region typically acts as a container for other memory regions. Use
- * memory_region_add_subregion() to add subregions.
- *
+ * memory_region_init:
* @mr: the #MemoryRegion to be initialized
* @name: used for debugging; not visible to the user or ABI
* @size: size of the region; any subregions beyond this size will be clipped
+ *
+ * Initialize a memory region
+ *
+ * The region typically acts as a container for other memory regions. Use
+ * memory_region_add_subregion() to add subregions.
*/
void memory_region_init(MemoryRegion *mr,
const char *name,
uint64_t size);
/**
- * memory_region_init_io: Initialize an I/O memory region.
- *
- * Accesses into the region will cause the callbacks in @ops to be called.
- * if @size is nonzero, subregions will be clipped to @size.
- *
+ * memory_region_init_io:
* @mr: the #MemoryRegion to be initialized.
* @ops: a structure containing read and write callbacks to be used when
* I/O is performed on the region.
* @opaque: passed to to the read and write callbacks of the @ops structure.
* @name: used for debugging; not visible to the user or ABI
* @size: size of the region.
+ *
+ * Initialize an I/O memory region.
+ *
+ * Accesses into the region will cause the callbacks in @ops to be called.
+ * if @size is nonzero, subregions will be clipped to @size.
*/
void memory_region_init_io(MemoryRegion *mr,
const MemoryRegionOps *ops,
@@ -188,15 +204,16 @@ void memory_region_init_io(MemoryRegion *mr,
uint64_t size);
/**
- * memory_region_init_ram: Initialize RAM memory region. Accesses into the
- * region will modify memory directly.
- *
+ * memory_region_init_ram:
* @mr: the #MemoryRegion to be initialized.
- * @dev: a device associated with the region; may be %NULL.
+ * @dev: a device associated with the region; may be #NULL.
* @name: the name of the region; the pair (@dev, @name) must be globally
* unique. The name is part of the save/restore ABI and so cannot be
* changed.
* @size: size of the region.
+ *
+ * Initialize RAM memory region. Accesses into the region will modify memory
+ * directly.
*/
void memory_region_init_ram(MemoryRegion *mr,
DeviceState *dev, /* FIXME: layering violation */
@@ -204,17 +221,17 @@ void memory_region_init_ram(MemoryRegion *mr,
uint64_t size);
/**
- * memory_region_init_ram: Initialize RAM memory region from a user-provided.
- * pointer. Accesses into the region will modify
- * memory directly.
- *
+ * memory_region_init_ram:
* @mr: the #MemoryRegion to be initialized.
- * @dev: a device associated with the region; may be %NULL.
+ * @dev: a device associated with the region; may be #NULL.
* @name: the name of the region; the pair (@dev, @name) must be globally
* unique. The name is part of the save/restore ABI and so cannot be
* changed.
* @size: size of the region.
* @ptr: memory to be mapped; must contain at least @size bytes.
+ *
+ * Initialize RAM memory region from a user-provided pointer. Accesses into
+ * the region will modify memory directly.
*/
void memory_region_init_ram_ptr(MemoryRegion *mr,
DeviceState *dev, /* FIXME: layering violation */
@@ -223,15 +240,16 @@ void memory_region_init_ram_ptr(MemoryRegion *mr,
void *ptr);
/**
- * memory_region_init_alias: Initialize a memory region that aliases all or a
- * part of another memory region.
- *
+ * memory_region_init_alias:
* @mr: the #MemoryRegion to be initialized.
* @name: used for debugging; not visible to the user or ABI
* @orig: the region to be referenced; @mr will be equivalent to
* @orig between @offset and @offset + @size - 1.
* @offset: start of the section in @orig to be referenced.
* @size: size of the region.
+ *
+ * Initialize a memory region that aliases all or a part of another memory
+ * region.
*/
void memory_region_init_alias(MemoryRegion *mr,
const char *name,
@@ -240,16 +258,16 @@ void memory_region_init_alias(MemoryRegion *mr,
uint64_t size);
/**
- * memory_region_init_rom_device: Initialize a ROM memory region. Writes are
- * handled via callbacks.
- *
+ * memory_region_init_rom_device:
* @mr: the #MemoryRegion to be initialized.
* @ops: callbacks for write access handling.
- * @dev: a device associated with the region; may be %NULL.
+ * @dev: a device associated with the region; may be #NULL.
* @name: the name of the region; the pair (@dev, @name) must be globally
* unique. The name is part of the save/restore ABI and so cannot be
* changed.
* @size: size of the region.
+ *
+ * Initialize a ROM memory region. Writes are handled via callbacks.
*/
void memory_region_init_rom_device(MemoryRegion *mr,
const MemoryRegionOps *ops,
@@ -259,182 +277,192 @@ void memory_region_init_rom_device(MemoryRegion *mr,
uint64_t size);
/**
- * memory_region_destroy: Destroy a memory region and reclaim all resources.
- *
+ * memory_region_destroy:
* @mr: the region to be destroyed. May not currently be a subregion
* (see memory_region_add_subregion()) or referenced in an alias
* (see memory_region_init_alias()).
+ *
+ * Destroy a memory region and reclaim all resources.
*/
void memory_region_destroy(MemoryRegion *mr);
/**
- * memory_region_size: get a memory region's size.
- *
+ * memory_region_size:
* @mr: the memory region being queried.
+ *
+ * get a memory region's size.
*/
uint64_t memory_region_size(MemoryRegion *mr);
/**
- * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
+ * memory_region_get_ram_ptr:
+ * @mr: the memory region being queried.
+ *
+ * Get a pointer into a RAM memory region.
*
* Returns a host pointer to a RAM memory region (created with
* memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
* care.
- *
- * @mr: the memory region being queried.
*/
void *memory_region_get_ram_ptr(MemoryRegion *mr);
/**
- * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
- * callbacks.
+ * memory_region_set_offset:
+ *
+ * Sets an offset to be added to MemoryRegionOps callbacks.
*
- * This function is deprecated and should not be used in new code.
+ * Deprecated: This should not be used in new code.
*/
void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
/**
- * memory_region_set_log: Turn dirty logging on or off for a region.
+ * memory_region_set_log:
+ * @mr: the memory region being updated.
+ * @log: whether dirty logging is to be enabled or disabled.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Turn dirty logging on or off for a region.
*
* Turns dirty logging on or off for a specified client (display, migration).
* Only meaningful for RAM regions.
- *
- * @mr: the memory region being updated.
- * @log: whether dirty logging is to be enabled or disabled.
- * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
- * %DIRTY_MEMORY_VGA.
*/
void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
/**
- * memory_region_get_dirty: Check whether a page is dirty for a specified
- * client.
+ * memory_region_get_dirty:
+ * @mr: the memory region being queried.
+ * @addr: the address (relative to the start of the region) being queried.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Check whether a page is dirty for a specified client.
*
* Checks whether a page has been written to since the last
* call to memory_region_reset_dirty() with the same @client. Dirty logging
* must be enabled.
- *
- * @mr: the memory region being queried.
- * @addr: the address (relative to the start of the region) being queried.
- * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
- * %DIRTY_MEMORY_VGA.
*/
bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
unsigned client);
/**
- * memory_region_set_dirty: Mark a page as dirty in a memory region.
- *
- * Marks a page as dirty, after it has been dirtied outside guest code.
- *
+ * memory_region_set_dirty:
* @mr: the memory region being queried.
* @addr: the address (relative to the start of the region) being dirtied.
+ *
+ * Mark a page as dirty in a memory region.
+ *
+ * Marks a page as dirty, after it has been dirtied outside guest code.
*/
void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
/**
- * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
- * any external TLBs (e.g. kvm)
+ * memory_region_sync_dirty_bitmap:
+ * @mr: the region being flushed.
+ *
+ * Synchronize a region's dirty bitmap with any external TLBs (e.g. kvm)
*
* Flushes dirty information from accelerators such as kvm and vhost-net
* and makes it available to users of the memory API.
- *
- * @mr: the region being flushed.
*/
void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
/**
- * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
- * client.
- *
- * Marks a range of pages as no longer dirty.
- *
+ * memory_region_reset_dirty:
* @mr: the region being updated.
* @addr: the start of the subrange being cleaned.
* @size: the size of the subrange being cleaned.
- * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
- * %DIRTY_MEMORY_VGA.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Mark a range of pages as clean, for a specified client.
+ *
+ * Marks a range of pages as no longer dirty.
*/
void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
target_phys_addr_t size, unsigned client);
/**
- * memory_region_set_readonly: Turn a memory region read-only (or read-write)
+ * memory_region_set_readonly:
+ * @mr: the region being updated.
+ * @readonly: whether rhe region is to be ROM or RAM.
+ *
+ * Turn a memory region read-only (or read-write)
*
* Allows a memory region to be marked as read-only (turning it into a ROM).
* only useful on RAM regions.
- *
- * @mr: the region being updated.
- * @readonly: whether rhe region is to be ROM or RAM.
*/
void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
/**
- * memory_region_rom_device_set_readable: enable/disable ROM readability
+ * memory_region_rom_device_set_readable:
+ * @mr: the memory region to be updated
+ * @readable: whether reads are satisified directly (#true) or via callbacks
+ * (#false)
+ *
+ * Enable/disable ROM readability
*
* Allows a ROM device (initialized with memory_region_init_rom_device() to
* to be marked as readable (default) or not readable. When it is readable,
* the device is mapped to guest memory. When not readable, reads are
* forwarded to the #MemoryRegion.read function.
- *
- * @mr: the memory region to be updated
- * @readable: whether reads are satisified directly (%true) or via callbacks
- * (%false)
*/
void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
/**
- * memory_region_set_coalescing: Enable memory coalescing for the region.
+ * memory_region_set_coalescing:
+ * @mr: the memory region to be write coalesced
+ *
+ * Enable memory coalescing for the region.
*
* Enabled writes to a region to be queued for later processing. MMIO ->write
* callbacks may be delayed until a non-coalesced MMIO is issued.
* Only useful for IO regions. Roughly similar to write-combining hardware.
- *
- * @mr: the memory region to be write coalesced
*/
void memory_region_set_coalescing(MemoryRegion *mr);
/**
- * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
- * a region.
- *
- * Like memory_region_set_coalescing(), but works on a sub-range of a region.
- * Multiple calls can be issued coalesced disjoint ranges.
- *
+ * memory_region_add_coalescing:
* @mr: the memory region to be updated.
* @offset: the start of the range within the region to be coalesced.
* @size: the size of the subrange to be coalesced.
+ *
+ * Enable memory coalescing for a sub-range of a region.
+ *
+ * Like memory_region_set_coalescing(), but works on a sub-range of a region.
+ * Multiple calls can be issued coalesced disjoint ranges.
*/
void memory_region_add_coalescing(MemoryRegion *mr,
target_phys_addr_t offset,
uint64_t size);
/**
- * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
+ * memory_region_clear_coalescing:
+ * @mr: the memory region to be updated.
+ *
+ * Disable MMIO coalescing for the region.
*
* Disables any coalescing caused by memory_region_set_coalescing() or
* memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
* hardware.
- *
- * @mr: the memory region to be updated.
*/
void memory_region_clear_coalescing(MemoryRegion *mr);
/**
- * memory_region_add_eventfd: Request an eventfd to be triggered when a word
- * is written to a location.
- *
- * Marks a word in an IO region (initialized with memory_region_init_io())
- * as a trigger for an eventfd event. The I/O callback will not be called.
- * The caller must be prepared to handle failure (that is, take the required
- * action if the callback _is_ called).
- *
+ * memory_region_add_eventfd:
* @mr: the memory region being updated.
* @addr: the address within @mr that is to be monitored
* @size: the size of the access to trigger the eventfd
* @match_data: whether to match against @data, instead of just @addr
* @data: the data to match against the guest write
* @fd: the eventfd to be triggered when @addr, @size, and @data all match.
+ *
+ * Request an eventfd to be triggered when a word is written to a location.
+ *
+ * Marks a word in an IO region (initialized with memory_region_init_io())
+ * as a trigger for an eventfd event. The I/O callback will not be called.
+ * The caller must be prepared to handle failure (that is, take the required
+ * action if the callback _is_ called).
**/
void memory_region_add_eventfd(MemoryRegion *mr,
target_phys_addr_t addr,
@@ -444,17 +472,18 @@ void memory_region_add_eventfd(MemoryRegion *mr,
int fd);
/**
- * memory_region_del_eventfd: Cancel an eventfd.
- *
- * Cancels an eventfd trigger requested by a previous
- * memory_region_add_eventfd() call.
- *
+ * memory_region_del_eventfd:
* @mr: the memory region being updated.
* @addr: the address within @mr that is to be monitored
* @size: the size of the access to trigger the eventfd
* @match_data: whether to match against @data, instead of just @addr
* @data: the data to match against the guest write
* @fd: the eventfd to be triggered when @addr, @size, and @data all match.
+ *
+ * Cancel an eventfd.
+ *
+ * Cancels an eventfd trigger requested by a previous
+ * memory_region_add_eventfd() call.
*/
void memory_region_del_eventfd(MemoryRegion *mr,
target_phys_addr_t addr,
@@ -463,24 +492,32 @@ void memory_region_del_eventfd(MemoryRegion *mr,
uint64_t data,
int fd);
/**
- * memory_region_add_subregion: Add a subregion to a container.
+ * memory_region_add_subregion:
+ * @mr: the region to contain the new subregion; must be a container
+ * initialized with memory_region_init().
+ * @offset: the offset relative to @mr where @subregion is added.
+ * @subregion: the subregion to be added.
+ *
+ * Add a subregion to a container.
*
* Adds a subregion at @offset. The subregion may not overlap with other
* subregions (except for those explicitly marked as overlapping). A region
* may only be added once as a subregion (unless removed with
* memory_region_del_subregion()); use memory_region_init_alias() if you
* want a region to be a subregion in multiple locations.
- *
- * @mr: the region to contain the new subregion; must be a container
- * initialized with memory_region_init().
- * @offset: the offset relative to @mr where @subregion is added.
- * @subregion: the subregion to be added.
*/
void memory_region_add_subregion(MemoryRegion *mr,
target_phys_addr_t offset,
MemoryRegion *subregion);
/**
- * memory_region_add_subregion: Add a subregion to a container, with overlap.
+ * memory_region_add_subregion:
+ * @mr: the region to contain the new subregion; must be a container
+ * initialized with memory_region_init().
+ * @offset: the offset relative to @mr where @subregion is added.
+ * @subregion: the subregion to be added.
+ * @priority: used for resolving overlaps; highest priority wins.
+ *
+ * Add a subregion to a container, with overlap.
*
* Adds a subregion at @offset. The subregion may overlap with other
* subregions. Conflicts are resolved by having a higher @priority hide a
@@ -488,30 +525,27 @@ void memory_region_add_subregion(MemoryRegion *mr,
* A region may only be added once as a subregion (unless removed with
* memory_region_del_subregion()); use memory_region_init_alias() if you
* want a region to be a subregion in multiple locations.
- *
- * @mr: the region to contain the new subregion; must be a container
- * initialized with memory_region_init().
- * @offset: the offset relative to @mr where @subregion is added.
- * @subregion: the subregion to be added.
- * @priority: used for resolving overlaps; highest priority wins.
*/
void memory_region_add_subregion_overlap(MemoryRegion *mr,
target_phys_addr_t offset,
MemoryRegion *subregion,
unsigned priority);
/**
- * memory_region_del_subregion: Remove a subregion.
- *
- * Removes a subregion from its container.
- *
+ * memory_region_del_subregion:
* @mr: the container to be updated.
* @subregion: the region being removed; must be a current subregion of @mr.
+ *
+ * Remove a subregion.
+ *
+ * Removes a subregion from its container.
*/
void memory_region_del_subregion(MemoryRegion *mr,
MemoryRegion *subregion);
/**
- * memory_region_transaction_begin: Start a transaction.
+ * memory_region_transaction_begin:
+ *
+ * Start a transaction.
*
* During a transaction, changes will be accumulated and made visible
* only when the transaction ends (is commited).
@@ -519,8 +553,9 @@ void memory_region_del_subregion(MemoryRegion *mr,
void memory_region_transaction_begin(void);
/**
- * memory_region_transaction_commit: Commit a transaction and make changes
- * visible to the guest.
+ * memory_region_transaction_commit:
+ *
+ * Commit a transaction and make changes visible to the guest.
*/
void memory_region_transaction_commit(void);
--
1.7.4.1
^ permalink raw reply related [flat|nested] 20+ messages in thread* [Qemu-devel] [PATCH v2 4/4] memory: move header into include/ and add to QEMU docs
2011-12-14 20:01 [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Anthony Liguori
` (2 preceding siblings ...)
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 3/4] memory: update documentation to be in gtk-doc format Anthony Liguori
@ 2011-12-14 20:01 ` Anthony Liguori
2011-12-14 20:54 ` [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Marc-André Lureau
2012-03-12 21:03 ` Lluís Vilanova
5 siblings, 0 replies; 20+ messages in thread
From: Anthony Liguori @ 2011-12-14 20:01 UTC (permalink / raw)
To: qemu-devel; +Cc: Peter Maydell, Anthony Liguori, Avi Kivity, Stefan Weil
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
---
QEMU-docs.xml | 1 +
include/memory.h | 566 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
memory.h | 566 ------------------------------------------------------
3 files changed, 567 insertions(+), 566 deletions(-)
create mode 100644 include/memory.h
delete mode 100644 memory.h
diff --git a/QEMU-docs.xml b/QEMU-docs.xml
index ddc827a..9c9db77 100644
--- a/QEMU-docs.xml
+++ b/QEMU-docs.xml
@@ -16,6 +16,7 @@
<chapter>
<title>Core Device APIs</title>
+ <xi:include href="xml/memory.xml"/>
</chapter>
<index id="api-index-full">
diff --git a/include/memory.h b/include/memory.h
new file mode 100644
index 0000000..04370ff
--- /dev/null
+++ b/include/memory.h
@@ -0,0 +1,566 @@
+/*
+ * Physical memory management API
+ *
+ * Copyright 2011 Red Hat, Inc. and/or its affiliates
+ *
+ * Authors:
+ * Avi Kivity <avi@redhat.com>
+ *
+ * This work is licensed under the terms of the GNU GPL, version 2. See
+ * the COPYING file in the top-level directory.
+ *
+ */
+
+#ifndef MEMORY_H
+#define MEMORY_H
+
+#ifndef CONFIG_USER_ONLY
+
+/**
+ * SECTION:memory
+ * @title:Memory API
+ * @short_description: interfaces for dispatching I/O to devices
+ *
+ * The memory API models the memory and I/O buses and controllers of a QEMU
+ * machine.
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+#include "qemu-common.h"
+#include "cpu-common.h"
+#include "targphys.h"
+#include "qemu-queue.h"
+#include "iorange.h"
+#include "ioport.h"
+#include "int128.h"
+
+typedef struct MemoryRegionOps MemoryRegionOps;
+typedef struct MemoryRegion MemoryRegion;
+typedef struct MemoryRegionPortio MemoryRegionPortio;
+typedef struct MemoryRegionMmio MemoryRegionMmio;
+typedef struct MemoryRegionGuestConstraints MemoryRegionGuestConstraints;
+typedef struct MemoryRegionInternalConstraints MemoryRegionInternalConstraints;
+
+/* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
+ * registration.
+ */
+#define DIRTY_MEMORY_VGA 0
+#define DIRTY_MEMORY_CODE 1
+#define DIRTY_MEMORY_MIGRATION 3
+
+struct MemoryRegionMmio {
+ CPUReadMemoryFunc *read[3];
+ CPUWriteMemoryFunc *write[3];
+};
+
+/**
+ * MemoryRegionGuestConstraints:
+ * @min_access_size: If nonzero, specify bounds on access sizes beyond which a
+ * machine check is thrown.
+ * @max_access_size: If nonzero, specify bounds on access sizes beyond which a
+ * machine check is thrown.
+ * @unaligned: If true, unaligned accesses are supported. Otherwise unaligned
+ * accesses throw machine checks.
+ * @accepts: If present, and returns #false, the transaction is not accepted
+ * by the device (and results in machine dependent behaviour such
+ * as a machine check exception).
+ *
+ * Guest-visible constraints.
+ */
+struct MemoryRegionGuestConstraints
+{
+ unsigned min_access_size;
+ unsigned max_access_size;
+ bool unaligned;
+ bool (*accepts)(void *opaque, target_phys_addr_t addr,
+ unsigned size, bool is_write);
+};
+
+/**
+ * MemoryRegionInternalConstraints:
+ * @min_access_size: If nonzero, specifies the minimum size implemented.
+ * Smaller sizes will be rounded upwards and a partial result will be
+ * returned.
+ * @max_access_size: If nonzero, specifies the maximum size implemented.
+ * Larger sizes will be done as a series of accesses with smaller sizes.
+ * @unaligned: If true, unaligned accesses are supported. Otherwise all
+ * accesses are converted to (possibly multiple) naturally aligned accesses.
+ *
+ * Internal implementation constraints.
+ */
+struct MemoryRegionInternalConstraints
+{
+ unsigned min_access_size;
+ unsigned max_access_size;
+ bool unaligned;
+};
+
+/**
+ * MemoryRegionOps:
+ * @read: Read from the memory region. addr is relative to mr; size is in bytes.
+ * @write: Write to the memory region. addr is relative to mr; size is in bytes.
+ * @valid: Guest visible constraints.
+ * @impl: Internal implementation constraints.
+ * @old_portio: If @read and @write are not present, may be used for
+ * backwards compatibility with old portio registration.
+ * @old_mmio: If @read and @write are not present, may be used for
+ * backwards compatibility with old mmio registration.
+ *
+ * Memory region callbacks.
+ */
+struct MemoryRegionOps {
+ uint64_t (*read)(void *opaque,
+ target_phys_addr_t addr,
+ unsigned size);
+ void (*write)(void *opaque,
+ target_phys_addr_t addr,
+ uint64_t data,
+ unsigned size);
+
+ enum device_endian endianness;
+
+ MemoryRegionGuestConstraints valid;
+ MemoryRegionInternalConstraints impl;
+
+ const MemoryRegionPortio *old_portio;
+ const MemoryRegionMmio old_mmio;
+};
+
+typedef struct CoalescedMemoryRange CoalescedMemoryRange;
+typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
+
+struct MemoryRegion {
+ /* All fields are private - violators will be prosecuted */
+ /*< private >*/
+ const MemoryRegionOps *ops;
+ void *opaque;
+ MemoryRegion *parent;
+ Int128 size;
+ target_phys_addr_t addr;
+ target_phys_addr_t offset;
+ bool backend_registered;
+ void (*destructor)(MemoryRegion *mr);
+ ram_addr_t ram_addr;
+ IORange iorange;
+ bool terminates;
+ bool readable;
+ bool readonly; /* For RAM regions */
+ MemoryRegion *alias;
+ target_phys_addr_t alias_offset;
+ unsigned priority;
+ bool may_overlap;
+ QTAILQ_HEAD(subregions, MemoryRegion) subregions;
+ QTAILQ_ENTRY(MemoryRegion) subregions_link;
+ QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
+ const char *name;
+ uint8_t dirty_log_mask;
+ unsigned ioeventfd_nb;
+ MemoryRegionIoeventfd *ioeventfds;
+};
+
+struct MemoryRegionPortio {
+ uint32_t offset;
+ uint32_t len;
+ unsigned size;
+ IOPortReadFunc *read;
+ IOPortWriteFunc *write;
+};
+
+#define PORTIO_END_OF_LIST() { }
+
+/**
+ * memory_region_init:
+ * @mr: the #MemoryRegion to be initialized
+ * @name: used for debugging; not visible to the user or ABI
+ * @size: size of the region; any subregions beyond this size will be clipped
+ *
+ * Initialize a memory region
+ *
+ * The region typically acts as a container for other memory regions. Use
+ * memory_region_add_subregion() to add subregions.
+ */
+void memory_region_init(MemoryRegion *mr,
+ const char *name,
+ uint64_t size);
+/**
+ * memory_region_init_io:
+ * @mr: the #MemoryRegion to be initialized.
+ * @ops: a structure containing read and write callbacks to be used when
+ * I/O is performed on the region.
+ * @opaque: passed to to the read and write callbacks of the @ops structure.
+ * @name: used for debugging; not visible to the user or ABI
+ * @size: size of the region.
+ *
+ * Initialize an I/O memory region.
+ *
+ * Accesses into the region will cause the callbacks in @ops to be called.
+ * if @size is nonzero, subregions will be clipped to @size.
+ */
+void memory_region_init_io(MemoryRegion *mr,
+ const MemoryRegionOps *ops,
+ void *opaque,
+ const char *name,
+ uint64_t size);
+
+/**
+ * memory_region_init_ram:
+ * @mr: the #MemoryRegion to be initialized.
+ * @dev: a device associated with the region; may be #NULL.
+ * @name: the name of the region; the pair (@dev, @name) must be globally
+ * unique. The name is part of the save/restore ABI and so cannot be
+ * changed.
+ * @size: size of the region.
+ *
+ * Initialize RAM memory region. Accesses into the region will modify memory
+ * directly.
+ */
+void memory_region_init_ram(MemoryRegion *mr,
+ DeviceState *dev, /* FIXME: layering violation */
+ const char *name,
+ uint64_t size);
+
+/**
+ * memory_region_init_ram:
+ * @mr: the #MemoryRegion to be initialized.
+ * @dev: a device associated with the region; may be #NULL.
+ * @name: the name of the region; the pair (@dev, @name) must be globally
+ * unique. The name is part of the save/restore ABI and so cannot be
+ * changed.
+ * @size: size of the region.
+ * @ptr: memory to be mapped; must contain at least @size bytes.
+ *
+ * Initialize RAM memory region from a user-provided pointer. Accesses into
+ * the region will modify memory directly.
+ */
+void memory_region_init_ram_ptr(MemoryRegion *mr,
+ DeviceState *dev, /* FIXME: layering violation */
+ const char *name,
+ uint64_t size,
+ void *ptr);
+
+/**
+ * memory_region_init_alias:
+ * @mr: the #MemoryRegion to be initialized.
+ * @name: used for debugging; not visible to the user or ABI
+ * @orig: the region to be referenced; @mr will be equivalent to
+ * @orig between @offset and @offset + @size - 1.
+ * @offset: start of the section in @orig to be referenced.
+ * @size: size of the region.
+ *
+ * Initialize a memory region that aliases all or a part of another memory
+ * region.
+ */
+void memory_region_init_alias(MemoryRegion *mr,
+ const char *name,
+ MemoryRegion *orig,
+ target_phys_addr_t offset,
+ uint64_t size);
+
+/**
+ * memory_region_init_rom_device:
+ * @mr: the #MemoryRegion to be initialized.
+ * @ops: callbacks for write access handling.
+ * @dev: a device associated with the region; may be #NULL.
+ * @name: the name of the region; the pair (@dev, @name) must be globally
+ * unique. The name is part of the save/restore ABI and so cannot be
+ * changed.
+ * @size: size of the region.
+ *
+ * Initialize a ROM memory region. Writes are handled via callbacks.
+ */
+void memory_region_init_rom_device(MemoryRegion *mr,
+ const MemoryRegionOps *ops,
+ void *opaque,
+ DeviceState *dev, /* FIXME: layering violation */
+ const char *name,
+ uint64_t size);
+
+/**
+ * memory_region_destroy:
+ * @mr: the region to be destroyed. May not currently be a subregion
+ * (see memory_region_add_subregion()) or referenced in an alias
+ * (see memory_region_init_alias()).
+ *
+ * Destroy a memory region and reclaim all resources.
+ */
+void memory_region_destroy(MemoryRegion *mr);
+
+/**
+ * memory_region_size:
+ * @mr: the memory region being queried.
+ *
+ * get a memory region's size.
+ */
+uint64_t memory_region_size(MemoryRegion *mr);
+
+/**
+ * memory_region_get_ram_ptr:
+ * @mr: the memory region being queried.
+ *
+ * Get a pointer into a RAM memory region.
+ *
+ * Returns a host pointer to a RAM memory region (created with
+ * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
+ * care.
+ */
+void *memory_region_get_ram_ptr(MemoryRegion *mr);
+
+/**
+ * memory_region_set_offset:
+ *
+ * Sets an offset to be added to MemoryRegionOps callbacks.
+ *
+ * Deprecated: This should not be used in new code.
+ */
+void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
+
+/**
+ * memory_region_set_log:
+ * @mr: the memory region being updated.
+ * @log: whether dirty logging is to be enabled or disabled.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Turn dirty logging on or off for a region.
+ *
+ * Turns dirty logging on or off for a specified client (display, migration).
+ * Only meaningful for RAM regions.
+ */
+void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
+
+/**
+ * memory_region_get_dirty:
+ * @mr: the memory region being queried.
+ * @addr: the address (relative to the start of the region) being queried.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Check whether a page is dirty for a specified client.
+ *
+ * Checks whether a page has been written to since the last
+ * call to memory_region_reset_dirty() with the same @client. Dirty logging
+ * must be enabled.
+ */
+bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
+ unsigned client);
+
+/**
+ * memory_region_set_dirty:
+ * @mr: the memory region being queried.
+ * @addr: the address (relative to the start of the region) being dirtied.
+ *
+ * Mark a page as dirty in a memory region.
+ *
+ * Marks a page as dirty, after it has been dirtied outside guest code.
+ */
+void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
+
+/**
+ * memory_region_sync_dirty_bitmap:
+ * @mr: the region being flushed.
+ *
+ * Synchronize a region's dirty bitmap with any external TLBs (e.g. kvm)
+ *
+ * Flushes dirty information from accelerators such as kvm and vhost-net
+ * and makes it available to users of the memory API.
+ */
+void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
+
+/**
+ * memory_region_reset_dirty:
+ * @mr: the region being updated.
+ * @addr: the start of the subrange being cleaned.
+ * @size: the size of the subrange being cleaned.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Mark a range of pages as clean, for a specified client.
+ *
+ * Marks a range of pages as no longer dirty.
+ */
+void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
+ target_phys_addr_t size, unsigned client);
+
+/**
+ * memory_region_set_readonly:
+ * @mr: the region being updated.
+ * @readonly: whether rhe region is to be ROM or RAM.
+ *
+ * Turn a memory region read-only (or read-write)
+ *
+ * Allows a memory region to be marked as read-only (turning it into a ROM).
+ * only useful on RAM regions.
+ */
+void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
+
+/**
+ * memory_region_rom_device_set_readable:
+ * @mr: the memory region to be updated
+ * @readable: whether reads are satisified directly (#true) or via callbacks
+ * (#false)
+ *
+ * Enable/disable ROM readability
+ *
+ * Allows a ROM device (initialized with memory_region_init_rom_device() to
+ * to be marked as readable (default) or not readable. When it is readable,
+ * the device is mapped to guest memory. When not readable, reads are
+ * forwarded to the #MemoryRegion.read function.
+ */
+void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
+
+/**
+ * memory_region_set_coalescing:
+ * @mr: the memory region to be write coalesced
+ *
+ * Enable memory coalescing for the region.
+ *
+ * Enabled writes to a region to be queued for later processing. MMIO ->write
+ * callbacks may be delayed until a non-coalesced MMIO is issued.
+ * Only useful for IO regions. Roughly similar to write-combining hardware.
+ */
+void memory_region_set_coalescing(MemoryRegion *mr);
+
+/**
+ * memory_region_add_coalescing:
+ * @mr: the memory region to be updated.
+ * @offset: the start of the range within the region to be coalesced.
+ * @size: the size of the subrange to be coalesced.
+ *
+ * Enable memory coalescing for a sub-range of a region.
+ *
+ * Like memory_region_set_coalescing(), but works on a sub-range of a region.
+ * Multiple calls can be issued coalesced disjoint ranges.
+ */
+void memory_region_add_coalescing(MemoryRegion *mr,
+ target_phys_addr_t offset,
+ uint64_t size);
+
+/**
+ * memory_region_clear_coalescing:
+ * @mr: the memory region to be updated.
+ *
+ * Disable MMIO coalescing for the region.
+ *
+ * Disables any coalescing caused by memory_region_set_coalescing() or
+ * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
+ * hardware.
+ */
+void memory_region_clear_coalescing(MemoryRegion *mr);
+
+/**
+ * memory_region_add_eventfd:
+ * @mr: the memory region being updated.
+ * @addr: the address within @mr that is to be monitored
+ * @size: the size of the access to trigger the eventfd
+ * @match_data: whether to match against @data, instead of just @addr
+ * @data: the data to match against the guest write
+ * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
+ *
+ * Request an eventfd to be triggered when a word is written to a location.
+ *
+ * Marks a word in an IO region (initialized with memory_region_init_io())
+ * as a trigger for an eventfd event. The I/O callback will not be called.
+ * The caller must be prepared to handle failure (that is, take the required
+ * action if the callback _is_ called).
+ **/
+void memory_region_add_eventfd(MemoryRegion *mr,
+ target_phys_addr_t addr,
+ unsigned size,
+ bool match_data,
+ uint64_t data,
+ int fd);
+
+/**
+ * memory_region_del_eventfd:
+ * @mr: the memory region being updated.
+ * @addr: the address within @mr that is to be monitored
+ * @size: the size of the access to trigger the eventfd
+ * @match_data: whether to match against @data, instead of just @addr
+ * @data: the data to match against the guest write
+ * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
+ *
+ * Cancel an eventfd.
+ *
+ * Cancels an eventfd trigger requested by a previous
+ * memory_region_add_eventfd() call.
+ */
+void memory_region_del_eventfd(MemoryRegion *mr,
+ target_phys_addr_t addr,
+ unsigned size,
+ bool match_data,
+ uint64_t data,
+ int fd);
+/**
+ * memory_region_add_subregion:
+ * @mr: the region to contain the new subregion; must be a container
+ * initialized with memory_region_init().
+ * @offset: the offset relative to @mr where @subregion is added.
+ * @subregion: the subregion to be added.
+ *
+ * Add a subregion to a container.
+ *
+ * Adds a subregion at @offset. The subregion may not overlap with other
+ * subregions (except for those explicitly marked as overlapping). A region
+ * may only be added once as a subregion (unless removed with
+ * memory_region_del_subregion()); use memory_region_init_alias() if you
+ * want a region to be a subregion in multiple locations.
+ */
+void memory_region_add_subregion(MemoryRegion *mr,
+ target_phys_addr_t offset,
+ MemoryRegion *subregion);
+/**
+ * memory_region_add_subregion:
+ * @mr: the region to contain the new subregion; must be a container
+ * initialized with memory_region_init().
+ * @offset: the offset relative to @mr where @subregion is added.
+ * @subregion: the subregion to be added.
+ * @priority: used for resolving overlaps; highest priority wins.
+ *
+ * Add a subregion to a container, with overlap.
+ *
+ * Adds a subregion at @offset. The subregion may overlap with other
+ * subregions. Conflicts are resolved by having a higher @priority hide a
+ * lower @priority. Subregions without priority are taken as @priority 0.
+ * A region may only be added once as a subregion (unless removed with
+ * memory_region_del_subregion()); use memory_region_init_alias() if you
+ * want a region to be a subregion in multiple locations.
+ */
+void memory_region_add_subregion_overlap(MemoryRegion *mr,
+ target_phys_addr_t offset,
+ MemoryRegion *subregion,
+ unsigned priority);
+/**
+ * memory_region_del_subregion:
+ * @mr: the container to be updated.
+ * @subregion: the region being removed; must be a current subregion of @mr.
+ *
+ * Remove a subregion.
+ *
+ * Removes a subregion from its container.
+ */
+void memory_region_del_subregion(MemoryRegion *mr,
+ MemoryRegion *subregion);
+
+/**
+ * memory_region_transaction_begin:
+ *
+ * Start a transaction.
+ *
+ * During a transaction, changes will be accumulated and made visible
+ * only when the transaction ends (is commited).
+ */
+void memory_region_transaction_begin(void);
+
+/**
+ * memory_region_transaction_commit:
+ *
+ * Commit a transaction and make changes visible to the guest.
+ */
+void memory_region_transaction_commit(void);
+
+void mtree_info(fprintf_function mon_printf, void *f);
+
+#endif
+
+#endif
diff --git a/memory.h b/memory.h
deleted file mode 100644
index 04370ff..0000000
--- a/memory.h
+++ /dev/null
@@ -1,566 +0,0 @@
-/*
- * Physical memory management API
- *
- * Copyright 2011 Red Hat, Inc. and/or its affiliates
- *
- * Authors:
- * Avi Kivity <avi@redhat.com>
- *
- * This work is licensed under the terms of the GNU GPL, version 2. See
- * the COPYING file in the top-level directory.
- *
- */
-
-#ifndef MEMORY_H
-#define MEMORY_H
-
-#ifndef CONFIG_USER_ONLY
-
-/**
- * SECTION:memory
- * @title:Memory API
- * @short_description: interfaces for dispatching I/O to devices
- *
- * The memory API models the memory and I/O buses and controllers of a QEMU
- * machine.
- */
-
-#include <stdint.h>
-#include <stdbool.h>
-#include "qemu-common.h"
-#include "cpu-common.h"
-#include "targphys.h"
-#include "qemu-queue.h"
-#include "iorange.h"
-#include "ioport.h"
-#include "int128.h"
-
-typedef struct MemoryRegionOps MemoryRegionOps;
-typedef struct MemoryRegion MemoryRegion;
-typedef struct MemoryRegionPortio MemoryRegionPortio;
-typedef struct MemoryRegionMmio MemoryRegionMmio;
-typedef struct MemoryRegionGuestConstraints MemoryRegionGuestConstraints;
-typedef struct MemoryRegionInternalConstraints MemoryRegionInternalConstraints;
-
-/* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
- * registration.
- */
-#define DIRTY_MEMORY_VGA 0
-#define DIRTY_MEMORY_CODE 1
-#define DIRTY_MEMORY_MIGRATION 3
-
-struct MemoryRegionMmio {
- CPUReadMemoryFunc *read[3];
- CPUWriteMemoryFunc *write[3];
-};
-
-/**
- * MemoryRegionGuestConstraints:
- * @min_access_size: If nonzero, specify bounds on access sizes beyond which a
- * machine check is thrown.
- * @max_access_size: If nonzero, specify bounds on access sizes beyond which a
- * machine check is thrown.
- * @unaligned: If true, unaligned accesses are supported. Otherwise unaligned
- * accesses throw machine checks.
- * @accepts: If present, and returns #false, the transaction is not accepted
- * by the device (and results in machine dependent behaviour such
- * as a machine check exception).
- *
- * Guest-visible constraints.
- */
-struct MemoryRegionGuestConstraints
-{
- unsigned min_access_size;
- unsigned max_access_size;
- bool unaligned;
- bool (*accepts)(void *opaque, target_phys_addr_t addr,
- unsigned size, bool is_write);
-};
-
-/**
- * MemoryRegionInternalConstraints:
- * @min_access_size: If nonzero, specifies the minimum size implemented.
- * Smaller sizes will be rounded upwards and a partial result will be
- * returned.
- * @max_access_size: If nonzero, specifies the maximum size implemented.
- * Larger sizes will be done as a series of accesses with smaller sizes.
- * @unaligned: If true, unaligned accesses are supported. Otherwise all
- * accesses are converted to (possibly multiple) naturally aligned accesses.
- *
- * Internal implementation constraints.
- */
-struct MemoryRegionInternalConstraints
-{
- unsigned min_access_size;
- unsigned max_access_size;
- bool unaligned;
-};
-
-/**
- * MemoryRegionOps:
- * @read: Read from the memory region. addr is relative to mr; size is in bytes.
- * @write: Write to the memory region. addr is relative to mr; size is in bytes.
- * @valid: Guest visible constraints.
- * @impl: Internal implementation constraints.
- * @old_portio: If @read and @write are not present, may be used for
- * backwards compatibility with old portio registration.
- * @old_mmio: If @read and @write are not present, may be used for
- * backwards compatibility with old mmio registration.
- *
- * Memory region callbacks.
- */
-struct MemoryRegionOps {
- uint64_t (*read)(void *opaque,
- target_phys_addr_t addr,
- unsigned size);
- void (*write)(void *opaque,
- target_phys_addr_t addr,
- uint64_t data,
- unsigned size);
-
- enum device_endian endianness;
-
- MemoryRegionGuestConstraints valid;
- MemoryRegionInternalConstraints impl;
-
- const MemoryRegionPortio *old_portio;
- const MemoryRegionMmio old_mmio;
-};
-
-typedef struct CoalescedMemoryRange CoalescedMemoryRange;
-typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
-
-struct MemoryRegion {
- /* All fields are private - violators will be prosecuted */
- /*< private >*/
- const MemoryRegionOps *ops;
- void *opaque;
- MemoryRegion *parent;
- Int128 size;
- target_phys_addr_t addr;
- target_phys_addr_t offset;
- bool backend_registered;
- void (*destructor)(MemoryRegion *mr);
- ram_addr_t ram_addr;
- IORange iorange;
- bool terminates;
- bool readable;
- bool readonly; /* For RAM regions */
- MemoryRegion *alias;
- target_phys_addr_t alias_offset;
- unsigned priority;
- bool may_overlap;
- QTAILQ_HEAD(subregions, MemoryRegion) subregions;
- QTAILQ_ENTRY(MemoryRegion) subregions_link;
- QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
- const char *name;
- uint8_t dirty_log_mask;
- unsigned ioeventfd_nb;
- MemoryRegionIoeventfd *ioeventfds;
-};
-
-struct MemoryRegionPortio {
- uint32_t offset;
- uint32_t len;
- unsigned size;
- IOPortReadFunc *read;
- IOPortWriteFunc *write;
-};
-
-#define PORTIO_END_OF_LIST() { }
-
-/**
- * memory_region_init:
- * @mr: the #MemoryRegion to be initialized
- * @name: used for debugging; not visible to the user or ABI
- * @size: size of the region; any subregions beyond this size will be clipped
- *
- * Initialize a memory region
- *
- * The region typically acts as a container for other memory regions. Use
- * memory_region_add_subregion() to add subregions.
- */
-void memory_region_init(MemoryRegion *mr,
- const char *name,
- uint64_t size);
-/**
- * memory_region_init_io:
- * @mr: the #MemoryRegion to be initialized.
- * @ops: a structure containing read and write callbacks to be used when
- * I/O is performed on the region.
- * @opaque: passed to to the read and write callbacks of the @ops structure.
- * @name: used for debugging; not visible to the user or ABI
- * @size: size of the region.
- *
- * Initialize an I/O memory region.
- *
- * Accesses into the region will cause the callbacks in @ops to be called.
- * if @size is nonzero, subregions will be clipped to @size.
- */
-void memory_region_init_io(MemoryRegion *mr,
- const MemoryRegionOps *ops,
- void *opaque,
- const char *name,
- uint64_t size);
-
-/**
- * memory_region_init_ram:
- * @mr: the #MemoryRegion to be initialized.
- * @dev: a device associated with the region; may be #NULL.
- * @name: the name of the region; the pair (@dev, @name) must be globally
- * unique. The name is part of the save/restore ABI and so cannot be
- * changed.
- * @size: size of the region.
- *
- * Initialize RAM memory region. Accesses into the region will modify memory
- * directly.
- */
-void memory_region_init_ram(MemoryRegion *mr,
- DeviceState *dev, /* FIXME: layering violation */
- const char *name,
- uint64_t size);
-
-/**
- * memory_region_init_ram:
- * @mr: the #MemoryRegion to be initialized.
- * @dev: a device associated with the region; may be #NULL.
- * @name: the name of the region; the pair (@dev, @name) must be globally
- * unique. The name is part of the save/restore ABI and so cannot be
- * changed.
- * @size: size of the region.
- * @ptr: memory to be mapped; must contain at least @size bytes.
- *
- * Initialize RAM memory region from a user-provided pointer. Accesses into
- * the region will modify memory directly.
- */
-void memory_region_init_ram_ptr(MemoryRegion *mr,
- DeviceState *dev, /* FIXME: layering violation */
- const char *name,
- uint64_t size,
- void *ptr);
-
-/**
- * memory_region_init_alias:
- * @mr: the #MemoryRegion to be initialized.
- * @name: used for debugging; not visible to the user or ABI
- * @orig: the region to be referenced; @mr will be equivalent to
- * @orig between @offset and @offset + @size - 1.
- * @offset: start of the section in @orig to be referenced.
- * @size: size of the region.
- *
- * Initialize a memory region that aliases all or a part of another memory
- * region.
- */
-void memory_region_init_alias(MemoryRegion *mr,
- const char *name,
- MemoryRegion *orig,
- target_phys_addr_t offset,
- uint64_t size);
-
-/**
- * memory_region_init_rom_device:
- * @mr: the #MemoryRegion to be initialized.
- * @ops: callbacks for write access handling.
- * @dev: a device associated with the region; may be #NULL.
- * @name: the name of the region; the pair (@dev, @name) must be globally
- * unique. The name is part of the save/restore ABI and so cannot be
- * changed.
- * @size: size of the region.
- *
- * Initialize a ROM memory region. Writes are handled via callbacks.
- */
-void memory_region_init_rom_device(MemoryRegion *mr,
- const MemoryRegionOps *ops,
- void *opaque,
- DeviceState *dev, /* FIXME: layering violation */
- const char *name,
- uint64_t size);
-
-/**
- * memory_region_destroy:
- * @mr: the region to be destroyed. May not currently be a subregion
- * (see memory_region_add_subregion()) or referenced in an alias
- * (see memory_region_init_alias()).
- *
- * Destroy a memory region and reclaim all resources.
- */
-void memory_region_destroy(MemoryRegion *mr);
-
-/**
- * memory_region_size:
- * @mr: the memory region being queried.
- *
- * get a memory region's size.
- */
-uint64_t memory_region_size(MemoryRegion *mr);
-
-/**
- * memory_region_get_ram_ptr:
- * @mr: the memory region being queried.
- *
- * Get a pointer into a RAM memory region.
- *
- * Returns a host pointer to a RAM memory region (created with
- * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
- * care.
- */
-void *memory_region_get_ram_ptr(MemoryRegion *mr);
-
-/**
- * memory_region_set_offset:
- *
- * Sets an offset to be added to MemoryRegionOps callbacks.
- *
- * Deprecated: This should not be used in new code.
- */
-void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
-
-/**
- * memory_region_set_log:
- * @mr: the memory region being updated.
- * @log: whether dirty logging is to be enabled or disabled.
- * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
- * #DIRTY_MEMORY_VGA.
- *
- * Turn dirty logging on or off for a region.
- *
- * Turns dirty logging on or off for a specified client (display, migration).
- * Only meaningful for RAM regions.
- */
-void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
-
-/**
- * memory_region_get_dirty:
- * @mr: the memory region being queried.
- * @addr: the address (relative to the start of the region) being queried.
- * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
- * #DIRTY_MEMORY_VGA.
- *
- * Check whether a page is dirty for a specified client.
- *
- * Checks whether a page has been written to since the last
- * call to memory_region_reset_dirty() with the same @client. Dirty logging
- * must be enabled.
- */
-bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
- unsigned client);
-
-/**
- * memory_region_set_dirty:
- * @mr: the memory region being queried.
- * @addr: the address (relative to the start of the region) being dirtied.
- *
- * Mark a page as dirty in a memory region.
- *
- * Marks a page as dirty, after it has been dirtied outside guest code.
- */
-void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
-
-/**
- * memory_region_sync_dirty_bitmap:
- * @mr: the region being flushed.
- *
- * Synchronize a region's dirty bitmap with any external TLBs (e.g. kvm)
- *
- * Flushes dirty information from accelerators such as kvm and vhost-net
- * and makes it available to users of the memory API.
- */
-void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
-
-/**
- * memory_region_reset_dirty:
- * @mr: the region being updated.
- * @addr: the start of the subrange being cleaned.
- * @size: the size of the subrange being cleaned.
- * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
- * #DIRTY_MEMORY_VGA.
- *
- * Mark a range of pages as clean, for a specified client.
- *
- * Marks a range of pages as no longer dirty.
- */
-void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
- target_phys_addr_t size, unsigned client);
-
-/**
- * memory_region_set_readonly:
- * @mr: the region being updated.
- * @readonly: whether rhe region is to be ROM or RAM.
- *
- * Turn a memory region read-only (or read-write)
- *
- * Allows a memory region to be marked as read-only (turning it into a ROM).
- * only useful on RAM regions.
- */
-void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
-
-/**
- * memory_region_rom_device_set_readable:
- * @mr: the memory region to be updated
- * @readable: whether reads are satisified directly (#true) or via callbacks
- * (#false)
- *
- * Enable/disable ROM readability
- *
- * Allows a ROM device (initialized with memory_region_init_rom_device() to
- * to be marked as readable (default) or not readable. When it is readable,
- * the device is mapped to guest memory. When not readable, reads are
- * forwarded to the #MemoryRegion.read function.
- */
-void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
-
-/**
- * memory_region_set_coalescing:
- * @mr: the memory region to be write coalesced
- *
- * Enable memory coalescing for the region.
- *
- * Enabled writes to a region to be queued for later processing. MMIO ->write
- * callbacks may be delayed until a non-coalesced MMIO is issued.
- * Only useful for IO regions. Roughly similar to write-combining hardware.
- */
-void memory_region_set_coalescing(MemoryRegion *mr);
-
-/**
- * memory_region_add_coalescing:
- * @mr: the memory region to be updated.
- * @offset: the start of the range within the region to be coalesced.
- * @size: the size of the subrange to be coalesced.
- *
- * Enable memory coalescing for a sub-range of a region.
- *
- * Like memory_region_set_coalescing(), but works on a sub-range of a region.
- * Multiple calls can be issued coalesced disjoint ranges.
- */
-void memory_region_add_coalescing(MemoryRegion *mr,
- target_phys_addr_t offset,
- uint64_t size);
-
-/**
- * memory_region_clear_coalescing:
- * @mr: the memory region to be updated.
- *
- * Disable MMIO coalescing for the region.
- *
- * Disables any coalescing caused by memory_region_set_coalescing() or
- * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
- * hardware.
- */
-void memory_region_clear_coalescing(MemoryRegion *mr);
-
-/**
- * memory_region_add_eventfd:
- * @mr: the memory region being updated.
- * @addr: the address within @mr that is to be monitored
- * @size: the size of the access to trigger the eventfd
- * @match_data: whether to match against @data, instead of just @addr
- * @data: the data to match against the guest write
- * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
- *
- * Request an eventfd to be triggered when a word is written to a location.
- *
- * Marks a word in an IO region (initialized with memory_region_init_io())
- * as a trigger for an eventfd event. The I/O callback will not be called.
- * The caller must be prepared to handle failure (that is, take the required
- * action if the callback _is_ called).
- **/
-void memory_region_add_eventfd(MemoryRegion *mr,
- target_phys_addr_t addr,
- unsigned size,
- bool match_data,
- uint64_t data,
- int fd);
-
-/**
- * memory_region_del_eventfd:
- * @mr: the memory region being updated.
- * @addr: the address within @mr that is to be monitored
- * @size: the size of the access to trigger the eventfd
- * @match_data: whether to match against @data, instead of just @addr
- * @data: the data to match against the guest write
- * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
- *
- * Cancel an eventfd.
- *
- * Cancels an eventfd trigger requested by a previous
- * memory_region_add_eventfd() call.
- */
-void memory_region_del_eventfd(MemoryRegion *mr,
- target_phys_addr_t addr,
- unsigned size,
- bool match_data,
- uint64_t data,
- int fd);
-/**
- * memory_region_add_subregion:
- * @mr: the region to contain the new subregion; must be a container
- * initialized with memory_region_init().
- * @offset: the offset relative to @mr where @subregion is added.
- * @subregion: the subregion to be added.
- *
- * Add a subregion to a container.
- *
- * Adds a subregion at @offset. The subregion may not overlap with other
- * subregions (except for those explicitly marked as overlapping). A region
- * may only be added once as a subregion (unless removed with
- * memory_region_del_subregion()); use memory_region_init_alias() if you
- * want a region to be a subregion in multiple locations.
- */
-void memory_region_add_subregion(MemoryRegion *mr,
- target_phys_addr_t offset,
- MemoryRegion *subregion);
-/**
- * memory_region_add_subregion:
- * @mr: the region to contain the new subregion; must be a container
- * initialized with memory_region_init().
- * @offset: the offset relative to @mr where @subregion is added.
- * @subregion: the subregion to be added.
- * @priority: used for resolving overlaps; highest priority wins.
- *
- * Add a subregion to a container, with overlap.
- *
- * Adds a subregion at @offset. The subregion may overlap with other
- * subregions. Conflicts are resolved by having a higher @priority hide a
- * lower @priority. Subregions without priority are taken as @priority 0.
- * A region may only be added once as a subregion (unless removed with
- * memory_region_del_subregion()); use memory_region_init_alias() if you
- * want a region to be a subregion in multiple locations.
- */
-void memory_region_add_subregion_overlap(MemoryRegion *mr,
- target_phys_addr_t offset,
- MemoryRegion *subregion,
- unsigned priority);
-/**
- * memory_region_del_subregion:
- * @mr: the container to be updated.
- * @subregion: the region being removed; must be a current subregion of @mr.
- *
- * Remove a subregion.
- *
- * Removes a subregion from its container.
- */
-void memory_region_del_subregion(MemoryRegion *mr,
- MemoryRegion *subregion);
-
-/**
- * memory_region_transaction_begin:
- *
- * Start a transaction.
- *
- * During a transaction, changes will be accumulated and made visible
- * only when the transaction ends (is commited).
- */
-void memory_region_transaction_begin(void);
-
-/**
- * memory_region_transaction_commit:
- *
- * Commit a transaction and make changes visible to the guest.
- */
-void memory_region_transaction_commit(void);
-
-void mtree_info(fprintf_function mon_printf, void *f);
-
-#endif
-
-#endif
--
1.7.4.1
^ permalink raw reply related [flat|nested] 20+ messages in thread* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-14 20:01 [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Anthony Liguori
` (3 preceding siblings ...)
2011-12-14 20:01 ` [Qemu-devel] [PATCH v2 4/4] memory: move header into include/ and add to QEMU docs Anthony Liguori
@ 2011-12-14 20:54 ` Marc-André Lureau
2011-12-14 21:08 ` Anthony Liguori
2012-03-12 21:03 ` Lluís Vilanova
5 siblings, 1 reply; 20+ messages in thread
From: Marc-André Lureau @ 2011-12-14 20:54 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Peter Maydell, Stefan Weil, qemu-devel, Avi Kivity
[-- Attachment #1: Type: text/plain, Size: 467 bytes --]
Hi
On Wed, Dec 14, 2011 at 9:01 PM, Anthony Liguori <aliguori@us.ibm.com>wrote:
> For v2, I'm relying on a fork of gtk-doc that removes the underscore
> requirements. I really hate to do this but I like it better than not
> having
> documentation. I'm poking in the gtk+ community to see if there's an
> upstream
> compromise possible.
>
Can you point out a discussion/bug, What is the "underscode requirements"?
thanks
--
Marc-André Lureau
[-- Attachment #2: Type: text/html, Size: 785 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-14 20:54 ` [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Marc-André Lureau
@ 2011-12-14 21:08 ` Anthony Liguori
2011-12-15 5:22 ` Andreas Färber
0 siblings, 1 reply; 20+ messages in thread
From: Anthony Liguori @ 2011-12-14 21:08 UTC (permalink / raw)
To: Marc-André Lureau; +Cc: Peter Maydell, Avi Kivity, qemu-devel, Stefan Weil
[-- Attachment #1: Type: text/plain, Size: 638 bytes --]
On 12/14/2011 02:54 PM, Marc-André Lureau wrote:
> Hi
>
> On Wed, Dec 14, 2011 at 9:01 PM, Anthony Liguori<aliguori@us.ibm.com>wrote:
>
>> For v2, I'm relying on a fork of gtk-doc that removes the underscore
>> requirements. I really hate to do this but I like it better than not
>> having
>> documentation. I'm poking in the gtk+ community to see if there's an
>> upstream
>> compromise possible.
>>
>
> Can you point out a discussion/bug, What is the "underscode requirements"?
The following is what I need to make it work. I'm still trying to find out
where to even have this discussion.
Regards,
Anthony Liguori
>
> thanks
>
[-- Attachment #2: 0001-Don-t-assume-struct-names-are-prefixed-with-_.patch --]
[-- Type: text/x-patch, Size: 4279 bytes --]
>From f3894f803b417bbfc19d282fda348ff9e0d6ce26 Mon Sep 17 00:00:00 2001
From: Anthony Liguori <aliguori@us.ibm.com>
Date: Wed, 14 Dec 2011 13:23:12 -0600
Subject: [PATCH] Don't assume struct names are prefixed with '_'.
---
gtkdoc-mkdb.in | 4 ++--
gtkdoc-scan.in | 18 +++++++++---------
2 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 339203e..096266d 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -1489,7 +1489,7 @@ sub OutputStruct {
my $decl_out = "";
if ($declaration =~ m/^\s*$/) {
#print "Found opaque struct: $symbol\n";
- $decl_out = "typedef struct _$symbol $symbol;";
+ $decl_out = "typedef struct _?$symbol $symbol;";
} elsif ($declaration =~ m/^\s*struct\s+\w+\s*;\s*$/) {
#print "Found opaque struct: $symbol\n";
$decl_out = "struct $symbol;";
@@ -1535,7 +1535,7 @@ sub OutputStruct {
# empty struct declaration.
if ($decl_out eq "") {
if ($has_typedef) {
- $decl_out = "typedef struct _$symbol $symbol;";
+ $decl_out = "typedef struct _?$symbol $symbol;";
} else {
$decl_out = "struct $symbol;";
}
diff --git a/gtkdoc-scan.in b/gtkdoc-scan.in
index 04bfb4a..b435a20 100755
--- a/gtkdoc-scan.in
+++ b/gtkdoc-scan.in
@@ -461,7 +461,7 @@ sub ScanHeader {
# ENUMS
- } elsif (s/^\s*enum\s+_(\w+)\s+\{/enum $1 {/) {
+ } elsif (s/^\s*enum\s+_?(\w+)\s+\{/enum $1 {/) {
# We assume that 'enum _<enum_name> {' is really the
# declaration of enum <enum_name>.
$symbol = $1;
@@ -483,7 +483,7 @@ sub ScanHeader {
# STRUCTS AND UNIONS
- } elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) {
+ } elsif (m/^\s*typedef\s+(struct|union)\s+_?(\w+)\s+\2\s*;/) {
# We've found a 'typedef struct _<name> <name>;'
# This could be an opaque data structure, so we output an
# empty declaration. If the structure is actually found that
@@ -492,11 +492,11 @@ sub ScanHeader {
@TRACE@("$structsym typedef: $2");
$forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n"
- } elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) {
+ } elsif (m/^\s*(?:struct|union)\s+_?(\w+)\s*;/) {
# Skip private structs/unions.
@TRACE@("private struct/union");
- } elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) {
+ } elsif (m/^\s*(struct|union)\s+_?(\w+)\s*;/) {
# Do a similar thing for normal structs as for typedefs above.
# But we output the declaration as well in this case, so we
# can differentiate it from a typedef.
@@ -504,7 +504,7 @@ sub ScanHeader {
@TRACE@("$structsym: $2");
$forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$_$deprecated</$structsym>\n";
- } elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) {
+ } elsif (m/^\s*typedef\s+(struct|union)\s*_?\w*\s*{/) {
$symbol = "";
$decl = $_;
$level = 0;
@@ -659,11 +659,11 @@ sub ScanHeader {
# STRUCTS
- } elsif (m/^\s*struct\s+_(\w+)\s*\*/) {
+ } elsif (m/^\s*struct\s+_?(\w+)\s*\*/) {
# Skip 'struct _<struct_name> *', since it could be a
# return type on its own line.
- } elsif (m/^\s*struct\s+_(\w+)/) {
+ } elsif (m/^\s*struct\s+_?(\w+)/) {
# We assume that 'struct _<struct_name>' is really the
# declaration of struct <struct_name>.
$symbol = $1;
@@ -676,9 +676,9 @@ sub ScanHeader {
# UNIONS
- } elsif (m/^\s*union\s+_(\w+)\s*\*/) {
+ } elsif (m/^\s*union\s+_?(\w+)\s*\*/) {
# Skip 'union _<union_name> *' (see above)
- } elsif (m/^\s*union\s+_(\w+)/) {
+ } elsif (m/^\s*union\s+_?(\w+)/) {
$symbol = $1;
$decl = $_;
$level = 0;
--
1.7.4.1
^ permalink raw reply related [flat|nested] 20+ messages in thread* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-14 21:08 ` Anthony Liguori
@ 2011-12-15 5:22 ` Andreas Färber
2011-12-15 9:32 ` Stefan Weil
0 siblings, 1 reply; 20+ messages in thread
From: Andreas Färber @ 2011-12-15 5:22 UTC (permalink / raw)
To: Anthony Liguori
Cc: Peter Maydell, Stefan Weil, Marc-André Lureau, Avi Kivity,
qemu-devel
Am 14.12.2011 22:08, schrieb Anthony Liguori:
> On 12/14/2011 02:54 PM, Marc-André Lureau wrote:
>> On Wed, Dec 14, 2011 at 9:01 PM, Anthony
>> Liguori<aliguori@us.ibm.com>wrote:
>>
>>> For v2, I'm relying on a fork of gtk-doc that removes the underscore
>>> requirements. I really hate to do this but I like it better than not
>>> having
>>> documentation. I'm poking in the gtk+ community to see if there's an
>>> upstream
>>> compromise possible.
>>
>> Can you point out a discussion/bug, What is the "undersco[r]e
>> requirements"?
>
> The following is what I need to make it work. I'm still trying to find
> out where to even have this discussion.
Their website has the following:
"GTK-Doc wasn't originally intended to be a general-purpose
documentation tool, so it can be a bit awkward to setup and use. For a
more polished general-purpose documentation tool you may want to look at
Doxygen. However GTK-Doc has some special code to document the signals
and properties of GTK+ widgets and GObject classes which other tools may
not have."
http://www.gtk.org/gtk-doc/
Don't know if Doxygen has less restrictions though.
Andreas
--
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 5:22 ` Andreas Färber
@ 2011-12-15 9:32 ` Stefan Weil
2011-12-15 10:04 ` Daniel P. Berrange
2011-12-15 10:21 ` Kevin Wolf
0 siblings, 2 replies; 20+ messages in thread
From: Stefan Weil @ 2011-12-15 9:32 UTC (permalink / raw)
To: Andreas Färber
Cc: Peter Maydell, Marc-André Lureau, Avi Kivity, qemu-devel
Am 15.12.2011 06:22, schrieb Andreas Färber:
> Their website has the following:
>
> "GTK-Doc wasn't originally intended to be a general-purpose
> documentation tool, so it can be a bit awkward to setup and use. For a
> more polished general-purpose documentation tool you may want to look at
> Doxygen. However GTK-Doc has some special code to document the signals
> and properties of GTK+ widgets and GObject classes which other tools may
> not have."
> http://www.gtk.org/gtk-doc/
>
> Don't know if Doxygen has less restrictions though.
>
> Andreas
With doxygen, the documentation looks like this:
http://qemu.weilnetz.de/doxygen/
I only modified the first lines of memory.h to get
the global C functions, but of course more changes
are needed if we choose doxygen as our standard.
Regards,
Stefan Weil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 9:32 ` Stefan Weil
@ 2011-12-15 10:04 ` Daniel P. Berrange
2011-12-15 10:29 ` Stefan Weil
2011-12-15 10:21 ` Kevin Wolf
1 sibling, 1 reply; 20+ messages in thread
From: Daniel P. Berrange @ 2011-12-15 10:04 UTC (permalink / raw)
To: Stefan Weil
Cc: qemu-devel, Peter Maydell, Marc-André Lureau,
Andreas Färber, Avi Kivity
On Thu, Dec 15, 2011 at 10:32:20AM +0100, Stefan Weil wrote:
> Am 15.12.2011 06:22, schrieb Andreas Färber:
> >Their website has the following:
> >
> >"GTK-Doc wasn't originally intended to be a general-purpose
> >documentation tool, so it can be a bit awkward to setup and use. For a
> >more polished general-purpose documentation tool you may want to look at
> >Doxygen. However GTK-Doc has some special code to document the signals
> >and properties of GTK+ widgets and GObject classes which other tools may
> >not have."
> >http://www.gtk.org/gtk-doc/
> >
> >Don't know if Doxygen has less restrictions though.
> >
> >Andreas
>
> With doxygen, the documentation looks like this:
> http://qemu.weilnetz.de/doxygen/
I don't know about others, but I find Doxygen output really unpleasant
to read & navigate. I really despair whenever I find an API I need to
learn that uses Doxygen. The output of GTK-DOC by comparison is so much
more pleasant to consume.
Regards,
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 10:04 ` Daniel P. Berrange
@ 2011-12-15 10:29 ` Stefan Weil
2011-12-15 11:36 ` Andreas Färber
0 siblings, 1 reply; 20+ messages in thread
From: Stefan Weil @ 2011-12-15 10:29 UTC (permalink / raw)
To: Daniel P. Berrange
Cc: Avi Kivity, Anthony Liguori, qemu-devel, Andreas Färber
Am 15.12.2011 11:04, schrieb Daniel P. Berrange:
> On Thu, Dec 15, 2011 at 10:32:20AM +0100, Stefan Weil wrote:
>> Am 15.12.2011 06:22, schrieb Andreas Färber:
>>> Their website has the following:
>>>
>>> "GTK-Doc wasn't originally intended to be a general-purpose
>>> documentation tool, so it can be a bit awkward to setup and use. For a
>>> more polished general-purpose documentation tool you may want to look at
>>> Doxygen. However GTK-Doc has some special code to document the signals
>>> and properties of GTK+ widgets and GObject classes which other tools may
>>> not have."
>>> http://www.gtk.org/gtk-doc/
>>>
>>> Don't know if Doxygen has less restrictions though.
>>>
>>> Andreas
>>
>> With doxygen, the documentation looks like this:
>> http://qemu.weilnetz.de/doxygen/
>
> I don't know about others, but I find Doxygen output really unpleasant
> to read & navigate. I really despair whenever I find an API I need to
> learn that uses Doxygen. The output of GTK-DOC by comparison is so much
> more pleasant to consume.
>
> Regards,
> Daniel
I think that does not depend on the tools but on the people
who use them.
The output for the memory API is basically the same with
gtkdoc and doxygen:
http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html
http://qemu.weilnetz.de/doxygen/memory_8h.html#a13a3b6850223d2f5a691c618eee54610
(The doxygen output contains some additional information
because I selected to add graphs. Its information is partially
badly formatted or missing simply because the input file
was written for gtkdot and not for doxygen).
Good navigation needs special documentation input either
in the source code or in additional files and is possible with
doxygen as well (I use it since a couple of years).
Maybe those projects with good gtkdoc documentation
care more for their documentation (and spend more time)
than those projects which only have less good doxygen
documentation.
Cheers,
Stefan Weil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 10:29 ` Stefan Weil
@ 2011-12-15 11:36 ` Andreas Färber
2011-12-15 11:46 ` Kevin Wolf
0 siblings, 1 reply; 20+ messages in thread
From: Andreas Färber @ 2011-12-15 11:36 UTC (permalink / raw)
To: Stefan Weil; +Cc: Anthony Liguori, qemu-devel, Avi Kivity
Am 15.12.2011 11:29, schrieb Stefan Weil:
> Am 15.12.2011 11:04, schrieb Daniel P. Berrange:
>> On Thu, Dec 15, 2011 at 10:32:20AM +0100, Stefan Weil wrote:
>>> Am 15.12.2011 06:22, schrieb Andreas Färber:
>>>> Their website has the following:
>>>>
>>>> "GTK-Doc wasn't originally intended to be a general-purpose
>>>> documentation tool, so it can be a bit awkward to setup and use. For a
>>>> more polished general-purpose documentation tool you may want to
>>>> look at
>>>> Doxygen. However GTK-Doc has some special code to document the signals
>>>> and properties of GTK+ widgets and GObject classes which other tools
>>>> may
>>>> not have."
>>>> http://www.gtk.org/gtk-doc/
>>>>
>>>> Don't know if Doxygen has less restrictions though.
>>>>
>>>> Andreas
>>>
>>> With doxygen, the documentation looks like this:
>>> http://qemu.weilnetz.de/doxygen/
>>
>> I don't know about others, but I find Doxygen output really unpleasant
>> to read & navigate. I really despair whenever I find an API I need to
>> learn that uses Doxygen. The output of GTK-DOC by comparison is so much
>> more pleasant to consume.
>>
>> Regards,
>> Daniel
>
> I think that does not depend on the tools but on the people
> who use them.
>
> The output for the memory API is basically the same with
> gtkdoc and doxygen:
>
> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html
> http://qemu.weilnetz.de/doxygen/memory_8h.html#a13a3b6850223d2f5a691c618eee54610
>
>
> (The doxygen output contains some additional information
> because I selected to add graphs. Its information is partially
> badly formatted or missing simply because the input file
> was written for gtkdot and not for doxygen).
>
> Good navigation needs special documentation input either
> in the source code or in additional files and is possible with
> doxygen as well (I use it since a couple of years).
Hm, the navigation is what I dislike about the doxygen-generated example:
http://wiki.qemu.org/docs-internal/
http://qemu.weilnetz.de/doxygen/
doxygen looks to be oriented more towards C++, with a "Class Hierarchy"
that's completely flat.
Is either of the two able to understand qdev or QOM inheritance?
Andreas
--
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 11:36 ` Andreas Färber
@ 2011-12-15 11:46 ` Kevin Wolf
0 siblings, 0 replies; 20+ messages in thread
From: Kevin Wolf @ 2011-12-15 11:46 UTC (permalink / raw)
To: Andreas Färber; +Cc: Stefan Weil, Anthony Liguori, qemu-devel, Avi Kivity
Am 15.12.2011 12:36, schrieb Andreas Färber:
> Am 15.12.2011 11:29, schrieb Stefan Weil:
>> Am 15.12.2011 11:04, schrieb Daniel P. Berrange:
>>> On Thu, Dec 15, 2011 at 10:32:20AM +0100, Stefan Weil wrote:
>>>> Am 15.12.2011 06:22, schrieb Andreas Färber:
>>>>> Their website has the following:
>>>>>
>>>>> "GTK-Doc wasn't originally intended to be a general-purpose
>>>>> documentation tool, so it can be a bit awkward to setup and use. For a
>>>>> more polished general-purpose documentation tool you may want to
>>>>> look at
>>>>> Doxygen. However GTK-Doc has some special code to document the signals
>>>>> and properties of GTK+ widgets and GObject classes which other tools
>>>>> may
>>>>> not have."
>>>>> http://www.gtk.org/gtk-doc/
>>>>>
>>>>> Don't know if Doxygen has less restrictions though.
>>>>>
>>>>> Andreas
>>>>
>>>> With doxygen, the documentation looks like this:
>>>> http://qemu.weilnetz.de/doxygen/
>>>
>>> I don't know about others, but I find Doxygen output really unpleasant
>>> to read & navigate. I really despair whenever I find an API I need to
>>> learn that uses Doxygen. The output of GTK-DOC by comparison is so much
>>> more pleasant to consume.
>>>
>>> Regards,
>>> Daniel
>>
>> I think that does not depend on the tools but on the people
>> who use them.
>>
>> The output for the memory API is basically the same with
>> gtkdoc and doxygen:
>>
>> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html
>> http://qemu.weilnetz.de/doxygen/memory_8h.html#a13a3b6850223d2f5a691c618eee54610
>>
>>
>> (The doxygen output contains some additional information
>> because I selected to add graphs. Its information is partially
>> badly formatted or missing simply because the input file
>> was written for gtkdot and not for doxygen).
>>
>> Good navigation needs special documentation input either
>> in the source code or in additional files and is possible with
>> doxygen as well (I use it since a couple of years).
>
> Hm, the navigation is what I dislike about the doxygen-generated example:
>
> http://wiki.qemu.org/docs-internal/
> http://qemu.weilnetz.de/doxygen/
>
> doxygen looks to be oriented more towards C++, with a "Class Hierarchy"
> that's completely flat.
>
> Is either of the two able to understand qdev or QOM inheritance?
For C code, you can tell doxygen manually about inheritance by adding a
tag in the doxygen comments (iirc, it was something like "@extends
DeviceState").
Kevin
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 9:32 ` Stefan Weil
2011-12-15 10:04 ` Daniel P. Berrange
@ 2011-12-15 10:21 ` Kevin Wolf
2011-12-18 12:00 ` Stefan Weil
1 sibling, 1 reply; 20+ messages in thread
From: Kevin Wolf @ 2011-12-15 10:21 UTC (permalink / raw)
To: Stefan Weil
Cc: qemu-devel, Peter Maydell, Marc-André Lureau,
Andreas Färber, Avi Kivity
Am 15.12.2011 10:32, schrieb Stefan Weil:
> Am 15.12.2011 06:22, schrieb Andreas Färber:
>> Their website has the following:
>>
>> "GTK-Doc wasn't originally intended to be a general-purpose
>> documentation tool, so it can be a bit awkward to setup and use. For a
>> more polished general-purpose documentation tool you may want to look at
>> Doxygen. However GTK-Doc has some special code to document the signals
>> and properties of GTK+ widgets and GObject classes which other tools may
>> not have."
>> http://www.gtk.org/gtk-doc/
>>
>> Don't know if Doxygen has less restrictions though.
>>
>> Andreas
>
> With doxygen, the documentation looks like this:
> http://qemu.weilnetz.de/doxygen/
>
> I only modified the first lines of memory.h to get
> the global C functions, but of course more changes
> are needed if we choose doxygen as our standard.
You seem to have included Anthony's patches (specifically the one to
split out nested structs). Is Doxygen really as broken as gtk-doc seems
to be or can we do without it?
Kevin
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-15 10:21 ` Kevin Wolf
@ 2011-12-18 12:00 ` Stefan Weil
0 siblings, 0 replies; 20+ messages in thread
From: Stefan Weil @ 2011-12-18 12:00 UTC (permalink / raw)
To: Kevin Wolf; +Cc: Avi Kivity, Anthony Liguori, qemu-devel, Andreas Färber
Am 15.12.2011 11:21, schrieb Kevin Wolf:
> Am 15.12.2011 10:32, schrieb Stefan Weil:
>> Am 15.12.2011 06:22, schrieb Andreas Färber:
>>> Their website has the following:
>>>
>>> "GTK-Doc wasn't originally intended to be a general-purpose
>>> documentation tool, so it can be a bit awkward to setup and use. For a
>>> more polished general-purpose documentation tool you may want to look at
>>> Doxygen. However GTK-Doc has some special code to document the signals
>>> and properties of GTK+ widgets and GObject classes which other tools may
>>> not have."
>>> http://www.gtk.org/gtk-doc/
>>>
>>> Don't know if Doxygen has less restrictions though.
>>>
>>> Andreas
>> With doxygen, the documentation looks like this:
>> http://qemu.weilnetz.de/doxygen/
>>
>> I only modified the first lines of memory.h to get
>> the global C functions, but of course more changes
>> are needed if we choose doxygen as our standard.
> You seem to have included Anthony's patches (specifically the one to
> split out nested structs). Is Doxygen really as broken as gtk-doc seems
> to be or can we do without it?
>
> Kevin
Yes, the previous results were based on QEMU with Anthony's
latest gtkdoc patches.
Here is the result from unpatched QEMU code:
http://qemu.weilnetz.de/doxygen2/ or
http://qemu.weilnetz.de/doxygen2/memory_8h.html
I had to remove most graphics because they needed more than
1 GB disk space and filled all available space on my server.
Regards,
Stefan
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
2011-12-14 20:01 [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Anthony Liguori
` (4 preceding siblings ...)
2011-12-14 20:54 ` [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) Marc-André Lureau
@ 2012-03-12 21:03 ` Lluís Vilanova
5 siblings, 0 replies; 20+ messages in thread
From: Lluís Vilanova @ 2012-03-12 21:03 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Peter Maydell, Stefan Weil, qemu-devel, Avi Kivity
Anthony Liguori writes:
[...]
> For v2, I'm relying on a fork of gtk-doc that removes the underscore
> requirements. I really hate to do this but I like it better than not having
> documentation. I'm poking in the gtk+ community to see if there's an upstream
> compromise possible.
I don't want to start any kind of flame, but did you consider the possibility of
using doxygen instead?
>From my experience, it's pretty complete and also contains all kinds of
predefined keywords for documenting pre/post-conditions, notes, warnings, etc.
Besides, it offers the possibility to document "things" separately from the code
(e.g., auto-generated structures, or elements declared differently depending on
defines), which I was unable to do with some quick tests I had with gtkdoc.
Lluis
--
"And it's much the same thing with knowledge, for whenever you learn
something new, the whole world becomes that much richer."
-- The Princess of Pure Reason, as told by Norton Juster in The Phantom
Tollbooth
^ permalink raw reply [flat|nested] 20+ messages in thread