From 69ddaf6659c006599b530feb50604a584c79f329 Mon Sep 17 00:00:00 2001 From: Ademar de Souza Reis Jr Date: Mon, 5 Dec 2011 16:54:14 -0300 Subject: [PATCH] memory: minor documentation fixes/enhancements Fix typos and minor documentation errors in both memory.h and docs/memory.txt. Also add missing documentation formatting tags to transaction functions. Reviewed-by: Stefan Weil Signed-off-by: Ademar de Souza Reis Jr Signed-off-by: Stefan Hajnoczi --- 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); -- 2.7.4