[Qemu-devel] [PATCH 0/4] GTK-DOC build integration

[Qemu-devel] [PATCH 0/4] GTK-DOC build integration

[Anthony Liguori]

This series integrates GTK-DOC into our build process via a gtkdoc build target.
This is to provide internal API documentation in a more accessible format.  Once
this gets merged into the tree, I'll add a nightly cron job on qemu.org so that
there is always a copy of the latest internal API documentation on the website.

I've posted the output of already on qemu.org at:

   http://wiki.qemu.org/docs-internal/

All it takes to add to this is to submit a patch converting a file to use
gtk-doc syntax and then move the header into include/

For more information on gtk-doc, see:

   http://developer.gnome.org/gtk-doc-manual/unstable/

Anthony Liguori (4):
  memory: make memory API parsable by gtkdoc-scan
  docs: add build infrastructure for gtkdocs
  memory: update documentation to be in gtk-doc format
  memory: move header into include/ and add to QEMU docs

 Makefile         |    6 +-
 Makefile.docs    |   15 ++
 QEMU-docs.xml    |   32 +++
 include/memory.h |  566 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 ioport.h         |   14 +-
 memory.c         |    6 +-
 memory.h         |  522 -------------------------------------------------
 7 files changed, 628 insertions(+), 533 deletions(-)
 create mode 100644 Makefile.docs
 create mode 100644 QEMU-docs.xml
 create mode 100644 include/memory.h
 delete mode 100644 memory.h

-- 
1.7.4.1

[Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

GTK/glib uses a convenient of:

    typedef struct _CamelCase CamelCase;

The reason that they use a separate struct name is that in C++, the struct
namespace not a separate namespace from the type namespace.  This is actually a
reasonable policy for QEMU to adopt as we eventually start exporting C libraries
that may be consumed by C++ programs.

I think the use of _ does not violate the C specification as the struct
namespace is not the same as the type namespace which is what the C spec refers
to if I understand it correctly.

Additionally, gtkdoc-scan cannot handle nested structs so remove those from the
memory API.

Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
---
 ioport.h |   14 ++++----
 memory.c |    6 ++--
 memory.h |   99 +++++++++++++++++++++++++++++++++----------------------------
 3 files changed, 64 insertions(+), 55 deletions(-)

diff --git a/ioport.h b/ioport.h
index ae3e9da..99345d8 100644
--- a/ioport.h
+++ b/ioport.h
@@ -52,24 +52,24 @@ uint8_t cpu_inb(pio_addr_t addr);
 uint16_t cpu_inw(pio_addr_t addr);
 uint32_t cpu_inl(pio_addr_t addr);
 
-struct MemoryRegion;
-struct MemoryRegionPortio;
+struct _MemoryRegion;
+struct _MemoryRegionPortio;
 
 typedef struct PortioList {
-    const struct MemoryRegionPortio *ports;
-    struct MemoryRegion *address_space;
+    const struct _MemoryRegionPortio *ports;
+    struct _MemoryRegion *address_space;
     unsigned nr;
-    struct MemoryRegion **regions;
+    struct _MemoryRegion **regions;
     void *opaque;
     const char *name;
 } PortioList;
 
 void portio_list_init(PortioList *piolist,
-                      const struct MemoryRegionPortio *callbacks,
+                      const struct _MemoryRegionPortio *callbacks,
                       void *opaque, const char *name);
 void portio_list_destroy(PortioList *piolist);
 void portio_list_add(PortioList *piolist,
-                     struct MemoryRegion *address_space,
+                     struct _MemoryRegion *address_space,
                      uint32_t addr);
 void portio_list_del(PortioList *piolist);
 
diff --git a/memory.c b/memory.c
index adfdf14..76a7ae6 100644
--- a/memory.c
+++ b/memory.c
@@ -72,12 +72,12 @@ static AddrRange addrrange_intersection(AddrRange r1, AddrRange r2)
     return addrrange_make(start, int128_sub(end, start));
 }
 
-struct CoalescedMemoryRange {
+struct _CoalescedMemoryRange {
     AddrRange addr;
-    QTAILQ_ENTRY(CoalescedMemoryRange) link;
+    QTAILQ_ENTRY(_CoalescedMemoryRange) link;
 };
 
-struct MemoryRegionIoeventfd {
+struct _MemoryRegionIoeventfd {
     AddrRange addr;
     bool match_data;
     uint64_t data;
diff --git a/memory.h b/memory.h
index beae127..3aa8404 100644
--- a/memory.h
+++ b/memory.h
@@ -26,10 +26,12 @@
 #include "ioport.h"
 #include "int128.h"
 
-typedef struct MemoryRegionOps MemoryRegionOps;
-typedef struct MemoryRegion MemoryRegion;
-typedef struct MemoryRegionPortio MemoryRegionPortio;
-typedef struct MemoryRegionMmio MemoryRegionMmio;
+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.
@@ -38,15 +40,51 @@ typedef struct MemoryRegionMmio MemoryRegionMmio;
 #define DIRTY_MEMORY_CODE      1
 #define DIRTY_MEMORY_MIGRATION 3
 
-struct MemoryRegionMmio {
+struct _MemoryRegionMmio {
     CPUReadMemoryFunc *read[3];
     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
  */
-struct MemoryRegionOps {
+struct _MemoryRegionOps {
     /* Read from the memory region. @addr is relative to @mr; @size is
      * in bytes. */
     uint64_t (*read)(void *opaque,
@@ -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
@@ -105,10 +114,10 @@ struct MemoryRegionOps {
     const MemoryRegionMmio old_mmio;
 };
 
-typedef struct CoalescedMemoryRange CoalescedMemoryRange;
-typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
+typedef struct _CoalescedMemoryRange CoalescedMemoryRange;
+typedef struct _MemoryRegionIoeventfd MemoryRegionIoeventfd;
 
-struct MemoryRegion {
+struct _MemoryRegion {
     /* All fields are private - violators will be prosecuted */
     const MemoryRegionOps *ops;
     void *opaque;
@@ -127,16 +136,16 @@ struct MemoryRegion {
     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;
+    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 {
+struct _MemoryRegionPortio {
     uint32_t offset;
     uint32_t len;
     unsigned size;
-- 
1.7.4.1

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[malc]

On Wed, 14 Dec 2011, Anthony Liguori wrote:

> GTK/glib uses a convenient of:
> 
>     typedef struct _CamelCase CamelCase;
> 
> The reason that they use a separate struct name is that in C++, the struct
> namespace not a separate namespace from the type namespace.  This is actually a
> reasonable policy for QEMU to adopt as we eventually start exporting C libraries
> that may be consumed by C++ programs.
> 
> I think the use of _ does not violate the C specification as the struct
> namespace is not the same as the type namespace which is what the C spec refers
> to if I understand it correctly.

It does violate the standard _ followed by upper case letter is reserved
in all contexts.

> 
> Additionally, gtkdoc-scan cannot handle nested structs so remove those from the
> memory API.
> 
> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
> ---
>  ioport.h |   14 ++++----
>  memory.c |    6 ++--
>  memory.h |   99 +++++++++++++++++++++++++++++++++----------------------------
>  3 files changed, 64 insertions(+), 55 deletions(-)
> 
> diff --git a/ioport.h b/ioport.h
> index ae3e9da..99345d8 100644
> --- a/ioport.h
> +++ b/ioport.h
> @@ -52,24 +52,24 @@ uint8_t cpu_inb(pio_addr_t addr);
>  uint16_t cpu_inw(pio_addr_t addr);
>  uint32_t cpu_inl(pio_addr_t addr);
>  
> -struct MemoryRegion;
> -struct MemoryRegionPortio;
> +struct _MemoryRegion;
> +struct _MemoryRegionPortio;
>  
>  typedef struct PortioList {
> -    const struct MemoryRegionPortio *ports;
> -    struct MemoryRegion *address_space;
> +    const struct _MemoryRegionPortio *ports;
> +    struct _MemoryRegion *address_space;
>      unsigned nr;
> -    struct MemoryRegion **regions;
> +    struct _MemoryRegion **regions;
>      void *opaque;
>      const char *name;
>  } PortioList;
>  
>  void portio_list_init(PortioList *piolist,
> -                      const struct MemoryRegionPortio *callbacks,
> +                      const struct _MemoryRegionPortio *callbacks,
>                        void *opaque, const char *name);
>  void portio_list_destroy(PortioList *piolist);
>  void portio_list_add(PortioList *piolist,
> -                     struct MemoryRegion *address_space,
> +                     struct _MemoryRegion *address_space,
>                       uint32_t addr);
>  void portio_list_del(PortioList *piolist);
>  
> diff --git a/memory.c b/memory.c
> index adfdf14..76a7ae6 100644
> --- a/memory.c
> +++ b/memory.c
> @@ -72,12 +72,12 @@ static AddrRange addrrange_intersection(AddrRange r1, AddrRange r2)
>      return addrrange_make(start, int128_sub(end, start));
>  }
>  
> -struct CoalescedMemoryRange {
> +struct _CoalescedMemoryRange {
>      AddrRange addr;
> -    QTAILQ_ENTRY(CoalescedMemoryRange) link;
> +    QTAILQ_ENTRY(_CoalescedMemoryRange) link;
>  };
>  
> -struct MemoryRegionIoeventfd {
> +struct _MemoryRegionIoeventfd {
>      AddrRange addr;
>      bool match_data;
>      uint64_t data;
> diff --git a/memory.h b/memory.h
> index beae127..3aa8404 100644
> --- a/memory.h
> +++ b/memory.h
> @@ -26,10 +26,12 @@
>  #include "ioport.h"
>  #include "int128.h"
>  
> -typedef struct MemoryRegionOps MemoryRegionOps;
> -typedef struct MemoryRegion MemoryRegion;
> -typedef struct MemoryRegionPortio MemoryRegionPortio;
> -typedef struct MemoryRegionMmio MemoryRegionMmio;
> +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.
> @@ -38,15 +40,51 @@ typedef struct MemoryRegionMmio MemoryRegionMmio;
>  #define DIRTY_MEMORY_CODE      1
>  #define DIRTY_MEMORY_MIGRATION 3
>  
> -struct MemoryRegionMmio {
> +struct _MemoryRegionMmio {
>      CPUReadMemoryFunc *read[3];
>      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
>   */
> -struct MemoryRegionOps {
> +struct _MemoryRegionOps {
>      /* Read from the memory region. @addr is relative to @mr; @size is
>       * in bytes. */
>      uint64_t (*read)(void *opaque,
> @@ -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
> @@ -105,10 +114,10 @@ struct MemoryRegionOps {
>      const MemoryRegionMmio old_mmio;
>  };
>  
> -typedef struct CoalescedMemoryRange CoalescedMemoryRange;
> -typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
> +typedef struct _CoalescedMemoryRange CoalescedMemoryRange;
> +typedef struct _MemoryRegionIoeventfd MemoryRegionIoeventfd;
>  
> -struct MemoryRegion {
> +struct _MemoryRegion {
>      /* All fields are private - violators will be prosecuted */
>      const MemoryRegionOps *ops;
>      void *opaque;
> @@ -127,16 +136,16 @@ struct MemoryRegion {
>      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;
> +    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 {
> +struct _MemoryRegionPortio {
>      uint32_t offset;
>      uint32_t len;
>      unsigned size;
> 

-- 
mailto:av1474@comtv.ru

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 10:34 AM, malc wrote:
> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>
>> GTK/glib uses a convenient of:
>>
>>      typedef struct _CamelCase CamelCase;
>>
>> The reason that they use a separate struct name is that in C++, the struct
>> namespace not a separate namespace from the type namespace.  This is actually a
>> reasonable policy for QEMU to adopt as we eventually start exporting C libraries
>> that may be consumed by C++ programs.
>>
>> I think the use of _ does not violate the C specification as the struct
>> namespace is not the same as the type namespace which is what the C spec refers
>> to if I understand it correctly.
>
> It does violate the standard _ followed by upper case letter is reserved
> in all contexts.

I think in this case, we're just going to have to deviate from the standard. 
The benefit is great, the practice is widespread, and there's no immediate 
likelihood of changing glib's coding style practices.

I still think we should adhere to this policy where ever possible but I think 
we'll have to make an exception for extracting documentation.

Regards,

Anthony Liguori

>>
>> Additionally, gtkdoc-scan cannot handle nested structs so remove those from the
>> memory API.
>>
>> Signed-off-by: Anthony Liguori<aliguori@us.ibm.com>
>> ---
>>   ioport.h |   14 ++++----
>>   memory.c |    6 ++--
>>   memory.h |   99 +++++++++++++++++++++++++++++++++----------------------------
>>   3 files changed, 64 insertions(+), 55 deletions(-)
>>
>> diff --git a/ioport.h b/ioport.h
>> index ae3e9da..99345d8 100644
>> --- a/ioport.h
>> +++ b/ioport.h
>> @@ -52,24 +52,24 @@ uint8_t cpu_inb(pio_addr_t addr);
>>   uint16_t cpu_inw(pio_addr_t addr);
>>   uint32_t cpu_inl(pio_addr_t addr);
>>
>> -struct MemoryRegion;
>> -struct MemoryRegionPortio;
>> +struct _MemoryRegion;
>> +struct _MemoryRegionPortio;
>>
>>   typedef struct PortioList {
>> -    const struct MemoryRegionPortio *ports;
>> -    struct MemoryRegion *address_space;
>> +    const struct _MemoryRegionPortio *ports;
>> +    struct _MemoryRegion *address_space;
>>       unsigned nr;
>> -    struct MemoryRegion **regions;
>> +    struct _MemoryRegion **regions;
>>       void *opaque;
>>       const char *name;
>>   } PortioList;
>>
>>   void portio_list_init(PortioList *piolist,
>> -                      const struct MemoryRegionPortio *callbacks,
>> +                      const struct _MemoryRegionPortio *callbacks,
>>                         void *opaque, const char *name);
>>   void portio_list_destroy(PortioList *piolist);
>>   void portio_list_add(PortioList *piolist,
>> -                     struct MemoryRegion *address_space,
>> +                     struct _MemoryRegion *address_space,
>>                        uint32_t addr);
>>   void portio_list_del(PortioList *piolist);
>>
>> diff --git a/memory.c b/memory.c
>> index adfdf14..76a7ae6 100644
>> --- a/memory.c
>> +++ b/memory.c
>> @@ -72,12 +72,12 @@ static AddrRange addrrange_intersection(AddrRange r1, AddrRange r2)
>>       return addrrange_make(start, int128_sub(end, start));
>>   }
>>
>> -struct CoalescedMemoryRange {
>> +struct _CoalescedMemoryRange {
>>       AddrRange addr;
>> -    QTAILQ_ENTRY(CoalescedMemoryRange) link;
>> +    QTAILQ_ENTRY(_CoalescedMemoryRange) link;
>>   };
>>
>> -struct MemoryRegionIoeventfd {
>> +struct _MemoryRegionIoeventfd {
>>       AddrRange addr;
>>       bool match_data;
>>       uint64_t data;
>> diff --git a/memory.h b/memory.h
>> index beae127..3aa8404 100644
>> --- a/memory.h
>> +++ b/memory.h
>> @@ -26,10 +26,12 @@
>>   #include "ioport.h"
>>   #include "int128.h"
>>
>> -typedef struct MemoryRegionOps MemoryRegionOps;
>> -typedef struct MemoryRegion MemoryRegion;
>> -typedef struct MemoryRegionPortio MemoryRegionPortio;
>> -typedef struct MemoryRegionMmio MemoryRegionMmio;
>> +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.
>> @@ -38,15 +40,51 @@ typedef struct MemoryRegionMmio MemoryRegionMmio;
>>   #define DIRTY_MEMORY_CODE      1
>>   #define DIRTY_MEMORY_MIGRATION 3
>>
>> -struct MemoryRegionMmio {
>> +struct _MemoryRegionMmio {
>>       CPUReadMemoryFunc *read[3];
>>       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
>>    */
>> -struct MemoryRegionOps {
>> +struct _MemoryRegionOps {
>>       /* Read from the memory region. @addr is relative to @mr; @size is
>>        * in bytes. */
>>       uint64_t (*read)(void *opaque,
>> @@ -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
>> @@ -105,10 +114,10 @@ struct MemoryRegionOps {
>>       const MemoryRegionMmio old_mmio;
>>   };
>>
>> -typedef struct CoalescedMemoryRange CoalescedMemoryRange;
>> -typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
>> +typedef struct _CoalescedMemoryRange CoalescedMemoryRange;
>> +typedef struct _MemoryRegionIoeventfd MemoryRegionIoeventfd;
>>
>> -struct MemoryRegion {
>> +struct _MemoryRegion {
>>       /* All fields are private - violators will be prosecuted */
>>       const MemoryRegionOps *ops;
>>       void *opaque;
>> @@ -127,16 +136,16 @@ struct MemoryRegion {
>>       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;
>> +    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 {
>> +struct _MemoryRegionPortio {
>>       uint32_t offset;
>>       uint32_t len;
>>       unsigned size;
>>
>

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Peter Maydell]

On 14 December 2011 16:55, Anthony Liguori <anthony@codemonkey.ws> wrote:
> I think in this case, we're just going to have to deviate from the standard.
> The benefit is great, the practice is widespread, and there's no immediate
> likelihood of changing glib's coding style practices.
>
> I still think we should adhere to this policy where ever possible but I
> think we'll have to make an exception for extracting documentation.

Disagree. A docs tool that requires us to change our coding/naming
conventions (as opposed to merely how we mark stuff up in comments
or whatever) is a broken tool. Doubly so if it mandates violation
of the C standards.

We want to be able to document the structs/whatever we have now,
not only after we've done some enormous change to every struct we
have to bring it into line with somebody else's conventions.

-- PMM

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 11:11 AM, Peter Maydell wrote:
> On 14 December 2011 16:55, Anthony Liguori<anthony@codemonkey.ws>  wrote:
>> I think in this case, we're just going to have to deviate from the standard.
>> The benefit is great, the practice is widespread, and there's no immediate
>> likelihood of changing glib's coding style practices.
>>
>> I still think we should adhere to this policy where ever possible but I
>> think we'll have to make an exception for extracting documentation.
>
> Disagree. A docs tool that requires us to change our coding/naming
> conventions (as opposed to merely how we mark stuff up in comments
> or whatever) is a broken tool. Doubly so if it mandates violation
> of the C standards.
>
> We want to be able to document the structs/whatever we have now,
> not only after we've done some enormous change to every struct we
> have to bring it into line with somebody else's conventions.

If you have a better suggestion, I'm all for it.  But since C is not the most 
parseable language ever invented, basically every tool comes with constraints 
about coding style.

We can spend forever searching for the perfect tool, invent one ourselves, or 
just suck it up and use what's already out there.

The C language enforcement police aren't going to come knocking at our doors 
tomorrow.  This doesn't create a bug or remove a feature.

At some level, we need to be pragmatic.

Regards,

Anthony Liguori

>
> -- PMM
>

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Peter Maydell]

On 14 December 2011 17:19, Anthony Liguori <anthony@codemonkey.ws> wrote:
> If you have a better suggestion, I'm all for it.

Shrug. I'm not sure what problem you're solving here. The bits
of QEMU that are the worst to understand are the ones which aren't
documented at all, and the bits where the general structure and
underlying assumptions aren't documented. I'm happy to look in a
header file for specific function API info.

-- PMM

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 11:26 AM, Peter Maydell wrote:
> On 14 December 2011 17:19, Anthony Liguori<anthony@codemonkey.ws>  wrote:
>> If you have a better suggestion, I'm all for it.
>
> Shrug. I'm not sure what problem you're solving here.

To introduce the infrastructure such that we can have high quality internal 
documentation such that I can use that infrastructure with QEMU Object Model.

> The bits
> of QEMU that are the worst to understand are the ones which aren't
> documented at all,

What are the bits that aren't documented at all?  An easy answer to that would 
be "anything that isn't present on http://wiki.qemu.org/docs-internal"

How does someone help documented the undocumented things?  Send a patch adding 
gtk-doc style documentation to a file and then once it's merged it will 
automagically appear on qemu.org.

I think that goes a long way to solving the problem.

> and the bits where the general structure and
> underlying assumptions aren't documented. I'm happy to look in a
> header file for specific function API info.

I really prefer reading it in the form of a reference document.  It also helps 
enforce a certain amount of consistency in the format of the documentation which 
is hard to do if there isn't some sort of tool running against it.

Regards,

Anthony Liguori

> -- PMM
>

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Stefan Weil]

Am 14.12.2011 18:19, schrieb Anthony Liguori:
> On 12/14/2011 11:11 AM, Peter Maydell wrote:
>> On 14 December 2011 16:55, Anthony Liguori<anthony@codemonkey.ws>  
>> wrote:
>>> I think in this case, we're just going to have to deviate from the 
>>> standard.
>>> The benefit is great, the practice is widespread, and there's no 
>>> immediate
>>> likelihood of changing glib's coding style practices.
>>>
>>> I still think we should adhere to this policy where ever possible but I
>>> think we'll have to make an exception for extracting documentation.
>>
>> Disagree. A docs tool that requires us to change our coding/naming
>> conventions (as opposed to merely how we mark stuff up in comments
>> or whatever) is a broken tool. Doubly so if it mandates violation
>> of the C standards.
>>
>> We want to be able to document the structs/whatever we have now,
>> not only after we've done some enormous change to every struct we
>> have to bring it into line with somebody else's conventions.
>
> If you have a better suggestion, I'm all for it.  But since C is not 
> the most parseable language ever invented, basically every tool comes 
> with constraints about coding style.
>
> We can spend forever searching for the perfect tool, invent one 
> ourselves, or just suck it up and use what's already out there.
>
> The C language enforcement police aren't going to come knocking at our 
> doors tomorrow.  This doesn't create a bug or remove a feature.
>
> At some level, we need to be pragmatic.
>
> Regards,
>
> Anthony Liguori


Would 's' instead of '_' work?

struct sCamelCase;

typedef struct sCamelCase {
   // ...
} CamelCase;

It does not violate any standard...

Regards,

Stefan Weil

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Avi Kivity]

On 12/14/2011 07:55 PM, Stefan Weil wrote:
>
>
> Would 's' instead of '_' work?
>
> struct sCamelCase;
>
> typedef struct sCamelCase {
>   // ...
> } CamelCase;
>
> It does not violate any standard...

Would '' instead of 's' work?

typedes struct CamelCase {
   ...
} CamelCase;

-- 
error compiling committee.c: too many arguments to function

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/15/2011 03:20 AM, Avi Kivity wrote:
> On 12/14/2011 07:55 PM, Stefan Weil wrote:
>>
>>
>> Would 's' instead of '_' work?
>>
>> struct sCamelCase;
>>
>> typedef struct sCamelCase {
>>    // ...
>> } CamelCase;
>>
>> It does not violate any standard...
>
> Would '' instead of 's' work?
>
> typedes struct CamelCase {
>     ...
> } CamelCase;

Not in upstream gtk-doc.  The '_' is explicitly looked for.

Regards,

Anthony Liguori

>

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Stefan Weil]

Am 14.12.2011 17:34, schrieb malc:
> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>
>> GTK/glib uses a convenient of:
>>
>> typedef struct _CamelCase CamelCase;
>>
>> The reason that they use a separate struct name is that in C++, the 
>> struct
>> namespace not a separate namespace from the type namespace. This is 
>> actually a
>> reasonable policy for QEMU to adopt as we eventually start exporting 
>> C libraries
>> that may be consumed by C++ programs.
>>
>> I think the use of _ does not violate the C specification as the struct
>> namespace is not the same as the type namespace which is what the C 
>> spec refers
>> to if I understand it correctly.
>
> It does violate the standard _ followed by upper case letter is reserved
> in all contexts.

sCamelCase instead of _CamelCase seems to work, too.

I just finished a first test with gtk-doc and had no problems.

So it's possible to support gtk-doc (which is a good thing) _and_
keep the standard (which is very important, too).

The new rule for structure declarations in QEMU could be like this:

/* forward declaration */
struct sCamelCase;

/* struct definition */
typedef struct sCamelCase {
   /* values follow here ... */
} CamelCase;

Structures which don't need a forward declaration can use
simplified definitions:

typedef struct {
   /* values follow here ... */
} CamelCaseWithoutForwardDeclaration;

Regards,

Stefan Weil

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 12:54 PM, Stefan Weil wrote:
> Am 14.12.2011 17:34, schrieb malc:
>> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>>
>>> GTK/glib uses a convenient of:
>>>
>>> typedef struct _CamelCase CamelCase;
>>>
>>> The reason that they use a separate struct name is that in C++, the struct
>>> namespace not a separate namespace from the type namespace. This is actually a
>>> reasonable policy for QEMU to adopt as we eventually start exporting C libraries
>>> that may be consumed by C++ programs.
>>>
>>> I think the use of _ does not violate the C specification as the struct
>>> namespace is not the same as the type namespace which is what the C spec refers
>>> to if I understand it correctly.
>>
>> It does violate the standard _ followed by upper case letter is reserved
>> in all contexts.
>
> sCamelCase instead of _CamelCase seems to work, too.

Are you sure?

Take a look at:

html/QEMU-Memory-API.html#MemoryRegionOps

It's supposed to look like:

http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps

Regards,

Anthony Liguori

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Stefan Weil]

Am 14.12.2011 20:03, schrieb Anthony Liguori:
> On 12/14/2011 12:54 PM, Stefan Weil wrote:
>> Am 14.12.2011 17:34, schrieb malc:
>>> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>>>
>>>> GTK/glib uses a convenient of:
>>>>
>>>> typedef struct _CamelCase CamelCase;
>>>>
>>>> The reason that they use a separate struct name is that in C++, the 
>>>> struct
>>>> namespace not a separate namespace from the type namespace. This is 
>>>> actually a
>>>> reasonable policy for QEMU to adopt as we eventually start 
>>>> exporting C libraries
>>>> that may be consumed by C++ programs.
>>>>
>>>> I think the use of _ does not violate the C specification as the 
>>>> struct
>>>> namespace is not the same as the type namespace which is what the C 
>>>> spec refers
>>>> to if I understand it correctly.
>>>
>>> It does violate the standard _ followed by upper case letter is 
>>> reserved
>>> in all contexts.
>>
>> sCamelCase instead of _CamelCase seems to work, too.
>
> Are you sure?
>
> Take a look at:
>
> html/QEMU-Memory-API.html#MemoryRegionOps
>
> It's supposed to look like:
>
> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>
> Regards,
>
> Anthony Liguori

I took a look. The html documentation claims that there is a
"struct MemoryRegion". There isn't, it's a typedef.
Users of the API should use a pointer to a MemoryRegion
without knowing details of MemoryRegion, not even whether
it is a struct, long or something else.

What problems do you see from using sCamelCase?
Maybe I am looking in the wrong corner.

Regards,

Stefan Weil

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 02:48 PM, Stefan Weil wrote:
> Am 14.12.2011 20:03, schrieb Anthony Liguori:
>> On 12/14/2011 12:54 PM, Stefan Weil wrote:
>>> Am 14.12.2011 17:34, schrieb malc:
>>>> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>>>>
>>>>> GTK/glib uses a convenient of:
>>>>>
>>>>> typedef struct _CamelCase CamelCase;
>>>>>
>>>>> The reason that they use a separate struct name is that in C++, the struct
>>>>> namespace not a separate namespace from the type namespace. This is actually a
>>>>> reasonable policy for QEMU to adopt as we eventually start exporting C
>>>>> libraries
>>>>> that may be consumed by C++ programs.
>>>>>
>>>>> I think the use of _ does not violate the C specification as the struct
>>>>> namespace is not the same as the type namespace which is what the C spec
>>>>> refers
>>>>> to if I understand it correctly.
>>>>
>>>> It does violate the standard _ followed by upper case letter is reserved
>>>> in all contexts.
>>>
>>> sCamelCase instead of _CamelCase seems to work, too.
>>
>> Are you sure?
>>
>> Take a look at:
>>
>> html/QEMU-Memory-API.html#MemoryRegionOps
>>
>> It's supposed to look like:
>>
>> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>>
>> Regards,
>>
>> Anthony Liguori
>
> I took a look. The html documentation claims that there is a
> "struct MemoryRegion". There isn't, it's a typedef.
> Users of the API should use a pointer to a MemoryRegion
> without knowing details of MemoryRegion, not even whether
> it is a struct, long or something else.

You should see documentation for each parameter.

At this point, I just patched gtk-doc such that now gtk-doc doesn't require the 
underscore.

At least the latest version of gtk-doc definitely requires an underscore so 
having a patched version will be necessary.

Regards,

Anthony Liguori

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Stefan Weil]

Am 14.12.2011 21:54, schrieb Anthony Liguori:
> On 12/14/2011 02:48 PM, Stefan Weil wrote:
>> Am 14.12.2011 20:03, schrieb Anthony Liguori:
>>> On 12/14/2011 12:54 PM, Stefan Weil wrote:
>>>> Am 14.12.2011 17:34, schrieb malc:
>>>>> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>>>>>
>>>>>> GTK/glib uses a convenient of:
>>>>>>
>>>>>> typedef struct _CamelCase CamelCase;
>>>>>>
>>>>>> The reason that they use a separate struct name is that in C++, 
>>>>>> the struct
>>>>>> namespace not a separate namespace from the type namespace. This 
>>>>>> is actually a
>>>>>> reasonable policy for QEMU to adopt as we eventually start 
>>>>>> exporting C
>>>>>> libraries
>>>>>> that may be consumed by C++ programs.
>>>>>>
>>>>>> I think the use of _ does not violate the C specification as the 
>>>>>> struct
>>>>>> namespace is not the same as the type namespace which is what the 
>>>>>> C spec
>>>>>> refers
>>>>>> to if I understand it correctly.
>>>>>
>>>>> It does violate the standard _ followed by upper case letter is 
>>>>> reserved
>>>>> in all contexts.
>>>>
>>>> sCamelCase instead of _CamelCase seems to work, too.
>>>
>>> Are you sure?
>>>
>>> Take a look at:
>>>
>>> html/QEMU-Memory-API.html#MemoryRegionOps
>>>
>>> It's supposed to look like:
>>>
>>> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>>>
>>> Regards,
>>>
>>> Anthony Liguori
>>
>> I took a look. The html documentation claims that there is a
>> "struct MemoryRegion". There isn't, it's a typedef.
>> Users of the API should use a pointer to a MemoryRegion
>> without knowing details of MemoryRegion, not even whether
>> it is a struct, long or something else.
>
> You should see documentation for each parameter.
>
> At this point, I just patched gtk-doc such that now gtk-doc doesn't 
> require the underscore.
>
> At least the latest version of gtk-doc definitely requires an 
> underscore so having a patched version will be necessary.
>
> Regards,
>
> Anthony Liguori
>


See http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html for
the result which I get with latest QEMU sources, your patch
series v2 and gtk-doc from Debian Squeeze.

Regards,
Stefan Weil

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 03:26 PM, Stefan Weil wrote:
> Am 14.12.2011 21:54, schrieb Anthony Liguori:
>> On 12/14/2011 02:48 PM, Stefan Weil wrote:
>>> Am 14.12.2011 20:03, schrieb Anthony Liguori:
>>>> On 12/14/2011 12:54 PM, Stefan Weil wrote:
>>>>> Am 14.12.2011 17:34, schrieb malc:
>>>>>> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>>>>>>
>>>>>>> GTK/glib uses a convenient of:
>>>>>>>
>>>>>>> typedef struct _CamelCase CamelCase;
>>>>>>>
>>>>>>> The reason that they use a separate struct name is that in C++, the struct
>>>>>>> namespace not a separate namespace from the type namespace. This is
>>>>>>> actually a
>>>>>>> reasonable policy for QEMU to adopt as we eventually start exporting C
>>>>>>> libraries
>>>>>>> that may be consumed by C++ programs.
>>>>>>>
>>>>>>> I think the use of _ does not violate the C specification as the struct
>>>>>>> namespace is not the same as the type namespace which is what the C spec
>>>>>>> refers
>>>>>>> to if I understand it correctly.
>>>>>>
>>>>>> It does violate the standard _ followed by upper case letter is reserved
>>>>>> in all contexts.
>>>>>
>>>>> sCamelCase instead of _CamelCase seems to work, too.
>>>>
>>>> Are you sure?
>>>>
>>>> Take a look at:
>>>>
>>>> html/QEMU-Memory-API.html#MemoryRegionOps
>>>>
>>>> It's supposed to look like:
>>>>
>>>> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>>>>
>>>> Regards,
>>>>
>>>> Anthony Liguori
>>>
>>> I took a look. The html documentation claims that there is a
>>> "struct MemoryRegion". There isn't, it's a typedef.
>>> Users of the API should use a pointer to a MemoryRegion
>>> without knowing details of MemoryRegion, not even whether
>>> it is a struct, long or something else.
>>
>> You should see documentation for each parameter.
>>
>> At this point, I just patched gtk-doc such that now gtk-doc doesn't require
>> the underscore.
>>
>> At least the latest version of gtk-doc definitely requires an underscore so
>> having a patched version will be necessary.
>>
>> Regards,
>>
>> Anthony Liguori
>>
>
>
> See http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html for
> the result which I get with latest QEMU sources, your patch
> series v2 and gtk-doc from Debian Squeeze.

Look carefully at:

http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html#MemoryRegionOps

vs:

http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps

There's a significant difference :-)

Regards,

Anthony Liguori

>
> Regards,
> Stefan Weil
>
>

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Stefan Weil]

Am 14.12.2011 22:51, schrieb Anthony Liguori:
>
> Look carefully at:
>
> http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html#MemoryRegionOps
>
> vs:
>
> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>
> There's a significant difference :-)
>
> Regards,
>
> Anthony Liguori

I tried the following declaration:

typedef struct sMemoryRegionOps {
     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;
} MemoryRegionOps;

See the result here:
http://qemu.weilnetz.de/gtkdoc4/QEMU-Memory-API.html#MemoryRegionOps

Regards,
Stefan Weil

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 04:23 PM, Stefan Weil wrote:
> Am 14.12.2011 22:51, schrieb Anthony Liguori:
>>
>> Look carefully at:
>>
>> http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html#MemoryRegionOps
>>
>> vs:
>>
>> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>>
>> There's a significant difference :-)
>>
>> Regards,
>>
>> Anthony Liguori
>
> I tried the following declaration:
>
> typedef struct sMemoryRegionOps {
> 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;
> } MemoryRegionOps;
>
> See the result here:
> http://qemu.weilnetz.de/gtkdoc4/QEMU-Memory-API.html#MemoryRegionOps

Interesting, but it wouldn't be possible to do a forward declaration?

I think my patch to gtk-doc (make _ optional) seems reasonable and I think 
that's a bit nicer than doing struct sCamelCase too.

That doesn't help with C++ compatibility but now that it is not in favor of my 
argument, I no longer care about it ;-) (j/k)

Regards,

Anthony Liguori

> Regards,
> Stefan Weil
>
>

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 682 bytes --]

On 12/14/2011 11:54 AM, Stefan Weil wrote:
>> It does violate the standard _ followed by upper case letter is reserved
>> in all contexts.
> 
> sCamelCase instead of _CamelCase seems to work, too.

What about _camelCase instead of _CamelCase?  That preserves the leading
underscore, but no longer uses the reserved _ followed by a capital.

At any rate, that's the convention libvirt is using; all public structs
are prefixed with vir, so things like:

typedef struct _virConnect virConnect;

are both parseable by gtkdocs as well as C standard compliant.

-- 
Eric Blake   eblake@redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 620 bytes --]

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[malc]

On Wed, 14 Dec 2011, Eric Blake wrote:

> On 12/14/2011 11:54 AM, Stefan Weil wrote:
> >> It does violate the standard _ followed by upper case letter is reserved
> >> in all contexts.
> > 
> > sCamelCase instead of _CamelCase seems to work, too.
> 
> What about _camelCase instead of _CamelCase?  That preserves the leading
> underscore, but no longer uses the reserved _ followed by a capital.
> 
> At any rate, that's the convention libvirt is using; all public structs
> are prefixed with vir, so things like:
> 
> typedef struct _virConnect virConnect;
> 
> are both parseable by gtkdocs as well as C standard compliant.
> 
> 

7.1.3

7.1.3 Reserved identifiers
1 Each header declares or defines all identifiers listed in its
associated subclause, and optionally declares or defines identifiers
listed in its associated future library directions subclause and
identifiers which are always reserved either for any use or for use as
file scope identifiers.

- All identifiers that begin with an underscore and either an
  uppercase letter or another underscore are always reserved for any use.

- All identifiers that begin with an underscore are always reserved
  for use as identifiers with file scope in both the ordinary and tag
  name spaces

[..snip..]

IOW - no, that's not good either.

-- 
mailto:av1474@comtv.ru

Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori]

On 12/14/2011 02:23 PM, Eric Blake wrote:
> On 12/14/2011 11:54 AM, Stefan Weil wrote:
>>> It does violate the standard _ followed by upper case letter is reserved
>>> in all contexts.
>>
>> sCamelCase instead of _CamelCase seems to work, too.
>
> What about _camelCase instead of _CamelCase?  That preserves the leading
> underscore, but no longer uses the reserved _ followed by a capital.
>
> At any rate, that's the convention libvirt is using; all public structs
> are prefixed with vir, so things like:
>
> typedef struct _virConnect virConnect;
>
> are both parseable by gtkdocs as well as C standard compliant.

I just hacked gtk-doc.  That seems like the easiest solution to the problem.

Regards,

Anthony Liguori

>

[Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Anthony Liguori]

By convention, documented headers now go in include/

Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
---
 Makefile      |    6 +++++-
 Makefile.docs |   15 +++++++++++++++
 QEMU-docs.xml |   31 +++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletions(-)
 create mode 100644 Makefile.docs
 create mode 100644 QEMU-docs.xml

diff --git a/Makefile b/Makefile
index 2c03055..d7974af 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+=$(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..bea0833
--- /dev/null
+++ b/Makefile.docs
@@ -0,0 +1,15 @@
+DOC_SRC=$(wildcard $(SRC_PATH)/include/*.h)
+
+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
+
+gtkdoc-clean:
+	$(RM) -r html xml
+	$(RM) $(SCAN_GEN) sgml.stamp *.bak html.stamp
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

Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Avi Kivity]

On 12/14/2011 06:20 PM, Anthony Liguori wrote:
> By convention, documented headers now go in include/

Dislike.

> +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+=$(SRC_PATH)/include
> +
>  ui/cocoa.o: ui/cocoa.m

Documentation should be built by default, so that errors in the format
are detected (and break the build).

>  
> +
> +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
> +

Does this thing not support incremental builds?

> +++ 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.

1.1.

-- 
error compiling committee.c: too many arguments to function

Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Stefan Weil]

Am 15.12.2011 10:37, schrieb Avi Kivity:
> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>> By convention, documented headers now go in include/
>
> Dislike.
>> +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+=$(SRC_PATH)/include
>> +
>> ui/cocoa.o: ui/cocoa.m
>
> Documentation should be built by default, so that errors in the format
> are detected (and break the build).

I agree. It is built by default today, and there is a configure option
to disable this default behavior.

>>
>> +
>> +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
>> +
>
> Does this thing not support incremental builds?

I don't know the answer for gtkdoc, but at least for doxygen incremental 
builds
are not useful if you want to use advanced features like cross reference 
listings:
bidirectional references must parse all files (or would need rather 
complicated
dependency lists).

Parsing of the QEMU code and generation of advanced html output (which
includes style sheets and graphics) with doxygen takes about 4 min on my 
server
and creates 70 MB of data.

If only some public interfaces are analyzed (like memory.h), this takes 
of course
much less time. Keeping those public interfaces in one place (in 
directory 'include',
for example) supports this approach.

Regards,
Stefan Weil

Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Anthony Liguori]

On 12/15/2011 03:37 AM, Avi Kivity wrote:
> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>> By convention, documented headers now go in include/
>
> Dislike.

I've been planning on doing this for a while.  I think it's a useful way to help 
improve internal modularity.  It provides a consistent way to indicate which 
headers represent "public" internal interfaces (like the memory API) verses 
things that are really private headers specific to a submodule (say block_int.h).

We have a real problem internally with headers too.  It's almost surprising how 
many lack guards, don't have proper #includes, etc.  By moving all public 
headers to include/, it gives us a systematic way to go through, clean up 
various headers, and have an idea of how much work is left to be done.

>
>> +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+=$(SRC_PATH)/include
>> +
>>   ui/cocoa.o: ui/cocoa.m
>
> Documentation should be built by default, so that errors in the format
> are detected (and break the build).

I agree, but since we now are dealing with a fork of a common tool, I didn't 
want to add a hard build dependency until I can get some feedback on whether 
upstream is willing to consider our patch.

>>
>> +
>> +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
>> +
>
> Does this thing not support incremental builds?

As best as I can tell, no.  Every other tool I've looked as suffers from the 
same problem.

Regards,

Anthony Liguori

>> +++ 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.
>
> 1.1.
>

Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Avi Kivity]

On 12/15/2011 03:30 PM, Anthony Liguori wrote:
> On 12/15/2011 03:37 AM, Avi Kivity wrote:
>> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>>> By convention, documented headers now go in include/
>>
>> Dislike.
>
> I've been planning on doing this for a while.  I think it's a useful
> way to help improve internal modularity.  It provides a consistent way
> to indicate which headers represent "public" internal interfaces (like
> the memory API) verses things that are really private headers specific
> to a submodule (say block_int.h).

If a submodule needs an internal header, it probably wants its own subdir.

>
> We have a real problem internally with headers too.  It's almost
> surprising how many lack guards, don't have proper #includes, etc.  By
> moving all public headers to include/, it gives us a systematic way to
> go through, clean up various headers, and have an idea of how much
> work is left to be done.

Still dislike.  But it's just dislike, not an opening shot into an
extended discussion that will expand into coding style, proposals for
changing the programming language, merging qemu into a subdirectory of
another project, etc, as much fun as it promises to be.  Do it if you
must, I'll live with it somehow.

>> Documentation should be built by default, so that errors in the format
>> are detected (and break the build).
>
> I agree, but since we now are dealing with a fork of a common tool, I
> didn't want to add a hard build dependency until I can get some
> feedback on whether upstream is willing to consider our patch.

Let's avoid a fork, either get it merged or find some other tool.

>> Does this thing not support incremental builds?
>
> As best as I can tell, no.  Every other tool I've looked as suffers
> from the same problem.

Yeah, it's equivalent to a compiler doing most of its work during the
link phase (=idea for patch).

-- 
error compiling committee.c: too many arguments to function

Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Anthony Liguori]

On 12/15/2011 07:43 AM, Avi Kivity wrote:
> On 12/15/2011 03:30 PM, Anthony Liguori wrote:
>> On 12/15/2011 03:37 AM, Avi Kivity wrote:
>>> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>>>> By convention, documented headers now go in include/
>>>
>>> Dislike.
>>
>> I've been planning on doing this for a while.  I think it's a useful
>> way to help improve internal modularity.  It provides a consistent way
>> to indicate which headers represent "public" internal interfaces (like
>> the memory API) verses things that are really private headers specific
>> to a submodule (say block_int.h).
>
> If a submodule needs an internal header, it probably wants its own subdir.
>
>>
>> We have a real problem internally with headers too.  It's almost
>> surprising how many lack guards, don't have proper #includes, etc.  By
>> moving all public headers to include/, it gives us a systematic way to
>> go through, clean up various headers, and have an idea of how much
>> work is left to be done.
>
> Still dislike.  But it's just dislike, not an opening shot into an
> extended discussion that will expand into coding style, proposals for
> changing the programming language, merging qemu into a subdirectory of
> another project, etc, as much fun as it promises to be.  Do it if you
> must, I'll live with it somehow.

Man, it's just not easy anymore to start epic flame wars...  I guess I'll have 
to go back to coding.

>>> Documentation should be built by default, so that errors in the format
>>> are detected (and break the build).
>>
>> I agree, but since we now are dealing with a fork of a common tool, I
>> didn't want to add a hard build dependency until I can get some
>> feedback on whether upstream is willing to consider our patch.
>
> Let's avoid a fork, either get it merged or find some other tool.

This is definitely the best tool for the job.  If we're not willing to live with 
underscores and upstream won't carry the patch, forking is our only option.  We 
can do it as a git submodule though which will make life fairly easy.

Regards,

Anthony Liguori

>>> Does this thing not support incremental builds?
>>
>> As best as I can tell, no.  Every other tool I've looked as suffers
>> from the same problem.
>
> Yeah, it's equivalent to a compiler doing most of its work during the
> link phase (=idea for patch).
>

Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Andreas Färber]

Am 15.12.2011 14:30, schrieb Anthony Liguori:
> On 12/15/2011 03:37 AM, Avi Kivity wrote:
>> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>>> By convention, documented headers now go in include/
>>
>> Dislike.

+1

> I've been planning on doing this for a while.  I think it's a useful way
> to help improve internal modularity.  It provides a consistent way to
> indicate which headers represent "public" internal interfaces (like the
> memory API) verses things that are really private headers specific to a
> submodule (say block_int.h).

So far you've always opposed the idea of a stable public API. If that's
still not what you want, then there's no real distinction here and an
include/ directory would give a wrong impression.

If you just want a TODO list, then surely having a shell script print
the *.h file names and copying them into the Wiki would be easier.

Andreas

-- 
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg

[Qemu-devel] [PATCH 3/4] memory: update documentation to be in gtk-doc format

[Anthony Liguori]

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 3aa8404..4d76df3 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

Re: [Qemu-devel] [PATCH 3/4] memory: update documentation to be in gtk-doc format

[Avi Kivity]

On 12/14/2011 06:20 PM, Anthony Liguori wrote:
> 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 3aa8404..4d76df3 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.
> + */
> +

Can we have a space after the colon, or is that disallowed by the format?

-- 
error compiling committee.c: too many arguments to function

Re: [Qemu-devel] [PATCH 3/4] memory: update documentation to be in gtk-doc format

[Anthony Liguori]

On 12/15/2011 03:26 AM, Avi Kivity wrote:
> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>> 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 3aa8404..4d76df3 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.
>> + */
>> +
>
> Can we have a space after the colon, or is that disallowed by the format?

Ugh, I hate reading perl code..

All of the docs and usage in gtk seem to not use a space for SECTION at least. 
I can try removing it and see what happens but I suspect it's better to be 
consistent with gtk here to avoid future breakages.

Regards,

Anthony Liguori

Re: [Qemu-devel] [PATCH 3/4] memory: update documentation to be in gtk-doc format

[Avi Kivity]

On 12/15/2011 03:33 PM, Anthony Liguori wrote:
>> Can we have a space after the colon, or is that disallowed by the
>> format?
>
>
> Ugh, I hate reading perl code..

Ah, it's called "reading"?  Let's really avoid a fork.



-- 
error compiling committee.c: too many arguments to function

[Qemu-devel] [PATCH 4/4] memory: move header into include/ and add to QEMU docs

[Anthony Liguori]

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..4d76df3
--- /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 4d76df3..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

Re: [Qemu-devel] [PATCH 4/4] memory: move header into include/ and add to QEMU docs

[Avi Kivity]

On 12/14/2011 06:20 PM, Anthony Liguori wrote:
> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
> ---
>  QEMU-docs.xml    |    1 +
>  include/memory.h |  566 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  memory.h         |  566 ------------------------------------------------------

Enable rename detection, this makes the patch much more reviewable.

Why the move to include/?  I like to keep my headers close.

-- 
error compiling committee.c: too many arguments to function

Re: [Qemu-devel] [PATCH 4/4] memory: move header into include/ and add to QEMU docs

[Anthony Liguori]

On 12/15/2011 03:24 AM, Avi Kivity wrote:
> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>> Signed-off-by: Anthony Liguori<aliguori@us.ibm.com>
>> ---
>>   QEMU-docs.xml    |    1 +
>>   include/memory.h |  566 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>   memory.h         |  566 ------------------------------------------------------
>
> Enable rename detection, this makes the patch much more reviewable.

Is there a git config for it?

> Why the move to include/?  I like to keep my headers close.

See other thread.

Regards,

Anthony Liguori

Re: [Qemu-devel] [PATCH 4/4] memory: move header into include/ and add to QEMU docs

[Avi Kivity]

On 12/15/2011 03:34 PM, Anthony Liguori wrote:
> On 12/15/2011 03:24 AM, Avi Kivity wrote:
>> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>>> Signed-off-by: Anthony Liguori<aliguori@us.ibm.com>
>>> ---
>>>   QEMU-docs.xml    |    1 +
>>>   include/memory.h |  566
>>> ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>   memory.h         |  566
>>> ------------------------------------------------------
>>
>> Enable rename detection, this makes the patch much more reviewable.
>
> Is there a git config for it?

  diff.renames true

>
>> Why the move to include/?  I like to keep my headers close.
>
> See other thread.

Yeah.

-- 
error compiling committee.c: too many arguments to function

Re: [Qemu-devel] [PATCH 4/4] memory: move header into include/ and add to QEMU docs

[Anthony Liguori]

On 12/15/2011 07:45 AM, Avi Kivity wrote:
> On 12/15/2011 03:34 PM, Anthony Liguori wrote:
>> On 12/15/2011 03:24 AM, Avi Kivity wrote:
>>> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
>>>> Signed-off-by: Anthony Liguori<aliguori@us.ibm.com>
>>>> ---
>>>>    QEMU-docs.xml    |    1 +
>>>>    include/memory.h |  566
>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>>    memory.h         |  566
>>>> ------------------------------------------------------
>>>
>>> Enable rename detection, this makes the patch much more reviewable.
>>
>> Is there a git config for it?
>
>    diff.renames true

Thanks!

Regards,

Anthony Liguori

>
>>
>>> Why the move to include/?  I like to keep my headers close.
>>
>> See other thread.
>
> Yeah.
>