Patchwork memory: minor documentation fixes/enhancements

login
register
mail settings
Submitter Ademar de Souza Reis Jr
Date Dec. 5, 2011, 7:54 p.m.
Message ID <1323114854-28049-1-git-send-email-areis@redhat.com>
Download mbox | patch
Permalink /patch/129403/
State New
Headers show

Comments

Ademar de Souza Reis Jr - Dec. 5, 2011, 7:54 p.m.
Fix typos and minor documentation errors in both memory.h and
docs/memory.txt.

Also add missing documentation formatting tags to transaction
functions.

Signed-off-by: Ademar de Souza Reis Jr <areis@redhat.com>
---
 docs/memory.txt |    6 +++---
 memory.h        |   38 ++++++++++++++++++++++----------------
 2 files changed, 25 insertions(+), 19 deletions(-)
Stefan Weil - Dec. 5, 2011, 9:48 p.m.
Am 05.12.2011 20:54, schrieb Ademar de Souza Reis Jr:
> Fix typos and minor documentation errors in both memory.h and
> docs/memory.txt.
>
> Also add missing documentation formatting tags to transaction
> functions.
>
> Signed-off-by: Ademar de Souza Reis Jr<areis@redhat.com>
> ---
>   docs/memory.txt |    6 +++---
>   memory.h        |   38 ++++++++++++++++++++++----------------
>   2 files changed, 25 insertions(+), 19 deletions(-)
>
> diff --git a/docs/memory.txt b/docs/memory.txt
> index 3fc1683..5bbee8e 100644
> --- a/docs/memory.txt
> +++ b/docs/memory.txt
> @@ -7,7 +7,7 @@ machine.  It attempts to allow modelling of:
>    - ordinary RAM
>    - memory-mapped I/O (MMIO)
>    - memory controllers that can dynamically reroute physical memory regions
> -  to different destinations
> +   to different destinations
>
>   The memory model provides support for
>
> @@ -121,7 +121,7 @@ pci (0-2^32-1)
>
>   ram: ram@0x00000000-0xffffffff
>
> -The is a (simplified) PC memory map. The 4GB RAM block is mapped into the
> +This is a (simplified) PC memory map. The 4GB RAM block is mapped into the
>   system address space via two aliases: "lomem" is a 1:1 mapping of the first
>   3.5GB; "himem" maps the last 0.5GB at address 4GB.  This leaves 0.5GB for the
>   so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with
> @@ -164,7 +164,7 @@ various constraints can be supplied to control how these callbacks are called:
>    - .impl.min_access_size, .impl.max_access_size define the access sizes
>      (in bytes) supported by the *implementation*; other access sizes will be
>      emulated using the ones available.  For example a 4-byte write will be
> -   emulated using four 1-byte write, if .impl.max_access_size = 1.
> +   emulated using four 1-byte writes, if .impl.max_access_size = 1.
>    - .impl.valid specifies that the *implementation* only supports unaligned
>      accesses; unaligned accesses will be emulated by two aligned accesses.
>    - .old_portio and .old_mmio can be used to ease porting from code using
> diff --git a/memory.h b/memory.h
> index 53bf261..beae127 100644
> --- a/memory.h
> +++ b/memory.h
> @@ -149,7 +149,7 @@ struct MemoryRegionPortio {
>   /**
>    * memory_region_init: Initialize a memory region
>    *
> - * The region typically acts as a container for other memory regions.  Us
> + * The region typically acts as a container for other memory regions.  Use
>    * memory_region_add_subregion() to add subregions.
>    *
>    * @mr: the #MemoryRegion to be initialized
> @@ -162,7 +162,7 @@ void memory_region_init(MemoryRegion *mr,
>   /**
>    * memory_region_init_io: Initialize an I/O memory region.
>    *
> - * Accesses into the region will be cause the callbacks in @ops to be called.
> + * Accesses into the region will cause the callbacks in @ops to be called.
>    * if @size is nonzero, subregions will be clipped to @size.
>    *
>    * @mr: the #MemoryRegion to be initialized.
> @@ -180,7 +180,7 @@ void memory_region_init_io(MemoryRegion *mr,
>
>   /**
>    * memory_region_init_ram:  Initialize RAM memory region.  Accesses into the
> - *                          region will be modify memory directly.
> + *                          region will modify memory directly.
>    *
>    * @mr: the #MemoryRegion to be initialized.
>    * @dev: a device associated with the region; may be %NULL.
> @@ -196,7 +196,7 @@ void memory_region_init_ram(MemoryRegion *mr,
>
>   /**
>    * memory_region_init_ram:  Initialize RAM memory region from a user-provided.
> - *                          pointer.  Accesses into the region will be modify
> + *                          pointer.  Accesses into the region will modify
>    *                          memory directly.
>    *
>    * @mr: the #MemoryRegion to be initialized.
> @@ -250,7 +250,7 @@ void memory_region_init_rom_device(MemoryRegion *mr,
>                                      uint64_t size);
>
>   /**
> - * memory_region_destroy: Destroy a memory region and relaim all resources.
> + * memory_region_destroy: Destroy a memory region and reclaim all resources.
>    *
>    * @mr: the region to be destroyed.  May not currently be a subregion
>    *      (see memory_region_add_subregion()) or referenced in an alias
> @@ -417,7 +417,7 @@ void memory_region_clear_coalescing(MemoryRegion *mr);
>    *
>    * 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 (hat is, take the required
> + * The caller must be prepared to handle failure (that is, take the required
>    * action if the callback _is_ called).
>    *
>    * @mr: the memory region being updated.
> @@ -435,10 +435,10 @@ void memory_region_add_eventfd(MemoryRegion *mr,
>                                  int fd);
>
>   /**
> - * memory_region_del_eventfd: Cancel and eventfd.
> + * memory_region_del_eventfd: Cancel an eventfd.
>    *
> - * Cancels an eventfd trigger request by a previous memory_region_add_eventfd()
> - * call.
> + * Cancels an eventfd trigger requested by a previous
> + * memory_region_add_eventfd() call.
>    *
>    * @mr: the memory region being updated.
>    * @addr: the address within @mr that is to be monitored
> @@ -454,9 +454,9 @@ void memory_region_del_eventfd(MemoryRegion *mr,
>                                  uint64_t data,
>                                  int fd);
>   /**
> - * memory_region_add_subregion: Add a sub-region to a container.
> + * memory_region_add_subregion: Add a subregion to a container.
>    *
> - * Adds a sub-region at @offset.  The sub-region may not overlap with other
> + * 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
> @@ -471,9 +471,9 @@ void memory_region_add_subregion(MemoryRegion *mr,
>                                    target_phys_addr_t offset,
>                                    MemoryRegion *subregion);
>   /**
> - * memory_region_add_subregion: Add a sub-region to a container, with overlap.
> + * memory_region_add_subregion: Add a subregion to a container, with overlap.
>    *
> - * Adds a sub-region at @offset.  The sub-region may overlap with other
> + * 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
> @@ -501,11 +501,17 @@ void memory_region_add_subregion_overlap(MemoryRegion *mr,
>   void memory_region_del_subregion(MemoryRegion *mr,
>                                    MemoryRegion *subregion);
>
> -/* Start a transaction; changes will be accumulated and made visible only
> - * when the transaction ends.
> +/**
> + * 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);
> -/* 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);
>    

Looks good. It does not change code and can be committed via qemu-trivial.

Reviewed-by: Stefan Weil <sw@weilnetz.de>
Stefan Hajnoczi - Dec. 6, 2011, 10:45 a.m.
On Mon, Dec 05, 2011 at 10:48:37PM +0100, Stefan Weil wrote:
> Am 05.12.2011 20:54, schrieb Ademar de Souza Reis Jr:
> >Fix typos and minor documentation errors in both memory.h and
> >docs/memory.txt.
> >
> >Also add missing documentation formatting tags to transaction
> >functions.
> >
> >Signed-off-by: Ademar de Souza Reis Jr<areis@redhat.com>
> >---
> >  docs/memory.txt |    6 +++---
> >  memory.h        |   38 ++++++++++++++++++++++----------------
> >  2 files changed, 25 insertions(+), 19 deletions(-)

Thanks, applied to the trivial-patches -next tree.

Stefan

Patch

diff --git a/docs/memory.txt b/docs/memory.txt
index 3fc1683..5bbee8e 100644
--- a/docs/memory.txt
+++ b/docs/memory.txt
@@ -7,7 +7,7 @@  machine.  It attempts to allow modelling of:
  - ordinary RAM
  - memory-mapped I/O (MMIO)
  - memory controllers that can dynamically reroute physical memory regions
-  to different destinations
+   to different destinations
 
 The memory model provides support for
 
@@ -121,7 +121,7 @@  pci (0-2^32-1)
 
 ram: ram@0x00000000-0xffffffff
 
-The is a (simplified) PC memory map. The 4GB RAM block is mapped into the
+This is a (simplified) PC memory map. The 4GB RAM block is mapped into the
 system address space via two aliases: "lomem" is a 1:1 mapping of the first
 3.5GB; "himem" maps the last 0.5GB at address 4GB.  This leaves 0.5GB for the
 so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with
@@ -164,7 +164,7 @@  various constraints can be supplied to control how these callbacks are called:
  - .impl.min_access_size, .impl.max_access_size define the access sizes
    (in bytes) supported by the *implementation*; other access sizes will be
    emulated using the ones available.  For example a 4-byte write will be
-   emulated using four 1-byte write, if .impl.max_access_size = 1.
+   emulated using four 1-byte writes, if .impl.max_access_size = 1.
  - .impl.valid specifies that the *implementation* only supports unaligned
    accesses; unaligned accesses will be emulated by two aligned accesses.
  - .old_portio and .old_mmio can be used to ease porting from code using
diff --git a/memory.h b/memory.h
index 53bf261..beae127 100644
--- a/memory.h
+++ b/memory.h
@@ -149,7 +149,7 @@  struct MemoryRegionPortio {
 /**
  * memory_region_init: Initialize a memory region
  *
- * The region typically acts as a container for other memory regions.  Us
+ * The region typically acts as a container for other memory regions.  Use
  * memory_region_add_subregion() to add subregions.
  *
  * @mr: the #MemoryRegion to be initialized
@@ -162,7 +162,7 @@  void memory_region_init(MemoryRegion *mr,
 /**
  * memory_region_init_io: Initialize an I/O memory region.
  *
- * Accesses into the region will be cause the callbacks in @ops to be called.
+ * Accesses into the region will cause the callbacks in @ops to be called.
  * if @size is nonzero, subregions will be clipped to @size.
  *
  * @mr: the #MemoryRegion to be initialized.
@@ -180,7 +180,7 @@  void memory_region_init_io(MemoryRegion *mr,
 
 /**
  * memory_region_init_ram:  Initialize RAM memory region.  Accesses into the
- *                          region will be modify memory directly.
+ *                          region will modify memory directly.
  *
  * @mr: the #MemoryRegion to be initialized.
  * @dev: a device associated with the region; may be %NULL.
@@ -196,7 +196,7 @@  void memory_region_init_ram(MemoryRegion *mr,
 
 /**
  * memory_region_init_ram:  Initialize RAM memory region from a user-provided.
- *                          pointer.  Accesses into the region will be modify
+ *                          pointer.  Accesses into the region will modify
  *                          memory directly.
  *
  * @mr: the #MemoryRegion to be initialized.
@@ -250,7 +250,7 @@  void memory_region_init_rom_device(MemoryRegion *mr,
                                    uint64_t size);
 
 /**
- * memory_region_destroy: Destroy a memory region and relaim all resources.
+ * memory_region_destroy: Destroy a memory region and reclaim all resources.
  *
  * @mr: the region to be destroyed.  May not currently be a subregion
  *      (see memory_region_add_subregion()) or referenced in an alias
@@ -417,7 +417,7 @@  void memory_region_clear_coalescing(MemoryRegion *mr);
  *
  * 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 (hat is, take the required
+ * The caller must be prepared to handle failure (that is, take the required
  * action if the callback _is_ called).
  *
  * @mr: the memory region being updated.
@@ -435,10 +435,10 @@  void memory_region_add_eventfd(MemoryRegion *mr,
                                int fd);
 
 /**
- * memory_region_del_eventfd: Cancel and eventfd.
+ * memory_region_del_eventfd: Cancel an eventfd.
  *
- * Cancels an eventfd trigger request by a previous memory_region_add_eventfd()
- * call.
+ * Cancels an eventfd trigger requested by a previous
+ * memory_region_add_eventfd() call.
  *
  * @mr: the memory region being updated.
  * @addr: the address within @mr that is to be monitored
@@ -454,9 +454,9 @@  void memory_region_del_eventfd(MemoryRegion *mr,
                                uint64_t data,
                                int fd);
 /**
- * memory_region_add_subregion: Add a sub-region to a container.
+ * memory_region_add_subregion: Add a subregion to a container.
  *
- * Adds a sub-region at @offset.  The sub-region may not overlap with other
+ * 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
@@ -471,9 +471,9 @@  void memory_region_add_subregion(MemoryRegion *mr,
                                  target_phys_addr_t offset,
                                  MemoryRegion *subregion);
 /**
- * memory_region_add_subregion: Add a sub-region to a container, with overlap.
+ * memory_region_add_subregion: Add a subregion to a container, with overlap.
  *
- * Adds a sub-region at @offset.  The sub-region may overlap with other
+ * 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
@@ -501,11 +501,17 @@  void memory_region_add_subregion_overlap(MemoryRegion *mr,
 void memory_region_del_subregion(MemoryRegion *mr,
                                  MemoryRegion *subregion);
 
-/* Start a transaction; changes will be accumulated and made visible only
- * when the transaction ends.
+/**
+ * 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);
-/* 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);