Wordsmithing.

[pintos-anon] / doc / reference.texi

diff --git a/doc/reference.texi b/doc/reference.texi
index c34dfc7294d45b2af08d6c1933cd418996b55312..389dcebc0d82d19a0b9be6d48ff84404aa6b6f45 100644 (file)
--- a/doc/reference.texi
+++ b/doc/reference.texi
@@ -1357,17 +1357,17 @@ working with virtual addresses:
 
 @defmac PGSHIFT
 @defmacx PGBITS
 
 @defmac PGSHIFT
 @defmacx PGBITS

-The bit index (0) and number of bits (12) in the offset part of a
+The bit index (0) and number of bits (12) of the offset part of a

 virtual address, respectively.
 @end defmac
 
 @defmac PGMASK
 virtual address, respectively.
 @end defmac
 
 @defmac PGMASK

-A bit mask with value @t{0xfff}, so that the bits in the page offset are
-set to 1 and other bits set to 0.
+A bit mask with the bits in the page offset set to 1, the rest set to 0
+(@t{0xfff}).

 @end defmac
 
 @defmac PGSIZE
 @end defmac
 
 @defmac PGSIZE

-The page size in bytes (4096).
+The page size in bytes (4,096).

 @end defmac
 
 @deftypefun unsigned pg_ofs (const void *@var{va})
 @end defmac
 
 @deftypefun unsigned pg_ofs (const void *@var{va})


@@ -1388,8 +1388,8 @@ Returns @var{va} rounded up to the nearest page boundary.
 @end deftypefun
 
 Virtual memory in Pintos is divided into two regions: user virtual
 @end deftypefun
 
 Virtual memory in Pintos is divided into two regions: user virtual

-memory and kernel virtual memory.  The boundary between them is
-@code{PHYS_BASE}:
+memory and kernel virtual memory (@pxref{Virtual Memory Layout}).  The
+boundary between them is @code{PHYS_BASE}:

 
 @defmac PHYS_BASE
 Base address of kernel virtual memory.  It defaults to @t{0xc0000000} (3
 
 @defmac PHYS_BASE
 Base address of kernel virtual memory.  It defaults to @t{0xc0000000} (3


@@ -1482,37 +1482,35 @@ encapsulated by a page table.  They work on both active and inactive
 page tables (that is, those for running and suspended processes),
 flushing the TLB as necessary.
 
 page tables (that is, those for running and suspended processes),
 flushing the TLB as necessary.
 

-User page parameters (@var{upage})to these functions should be user
-virtual addresses.  Kernel page parameters (@var{kpage}) should be
-kernel virtual addresses and should have been obtained from the user
-pool with @code{palloc_get_page(PAL_USER)} (@pxref{Why PAL_USER?}).
-

 @deftypefun bool pagedir_set_page (uint32_t *@var{pd}, void *@var{upage}, void *@var{kpage}, bool @var{writable})
 @deftypefun bool pagedir_set_page (uint32_t *@var{pd}, void *@var{upage}, void *@var{kpage}, bool @var{writable})

-Adds to @var{pd} a mapping from page @var{upage} to the frame identified
+Adds to @var{pd} a mapping from user page @var{upage} to the frame identified

 by kernel virtual address @var{kpage}.  If @var{writable} is true, the
 page is mapped read/write; otherwise, it is mapped read-only.
 
 by kernel virtual address @var{kpage}.  If @var{writable} is true, the
 page is mapped read/write; otherwise, it is mapped read-only.
 

-Page @var{upage} must not already be mapped.  If it is, the kernel
-panics.
+User page @var{upage} must not already be mapped in @var{pd}.
+
+Kernel page @var{kpage} should be a kernel virtual address obtained from
+the user pool with @code{palloc_get_page(PAL_USER)} (@pxref{Why
+PAL_USER?}).

 
 Returns true if successful, false on failure.  Failure will occur if
 additional memory required for the page table cannot be obtained.
 @end deftypefun
 
 @deftypefun {void *} pagedir_get_page (uint32_t *@var{pd}, const void *@var{uaddr})
 
 Returns true if successful, false on failure.  Failure will occur if
 additional memory required for the page table cannot be obtained.
 @end deftypefun
 
 @deftypefun {void *} pagedir_get_page (uint32_t *@var{pd}, const void *@var{uaddr})

-Looks up the frame mapped to @var{upage} in @var{pd}.  Returns the
-kernel virtual address for that frame, if @var{upage} is mapped, or a
+Looks up the frame mapped to @var{uaddr} in @var{pd}.  Returns the
+kernel virtual address for that frame, if @var{uaddr} is mapped, or a

 null pointer if it is not.
 @end deftypefun
 
 null pointer if it is not.
 @end deftypefun
 

-@deftypefun void pagedir_clear_page (uint32_t *@var{pd}, void *@var{upage})
-Marks page @var{upage} ``not present'' in @var{pd}.  Later accesses to
+@deftypefun void pagedir_clear_page (uint32_t *@var{pd}, void *@var{page})
+Marks @var{page} ``not present'' in @var{pd}.  Later accesses to

 the page will fault.
 
 the page will fault.
 

-Other bits in the page table for @var{upage} are preserved, permitting
+Other bits in the page table for @var{page} are preserved, permitting

 the accessed and dirty bits (see the next section) to be checked.
 
 the accessed and dirty bits (see the next section) to be checked.
 

-If @var{upage} is not mapped, this function has no effect.
+This function has no effect if @var{page} is not mapped.

 @end deftypefun
 
 @node Page Table Accessed and Dirty Bits
 @end deftypefun
 
 @node Page Table Accessed and Dirty Bits


@@ -1637,13 +1635,13 @@ with raw page tables:
 
 @defmac PTSHIFT
 @defmacx PTBITS
 
 @defmac PTSHIFT
 @defmacx PTBITS

-The bit index (12) and number of bits (10), respectively, in a page table
-index within a virtual address.
+The starting bit index (12) and number of bits (10), respectively, in a
+page table index.

 @end defmac
 
 @defmac PTMASK
 @end defmac
 
 @defmac PTMASK

-A bit mask with the bits in the page table index set to 1 and other bits
-set to 0.
+A bit mask with the bits in the page table index set to 1 and the rest
+set to 0 (@t{0x3ff000}).

 @end defmac
 
 @defmac PTSPAN
 @end defmac
 
 @defmac PTSPAN


@@ -1653,13 +1651,13 @@ page covers (4,194,304 bytes, or 4 MB).
 
 @defmac PDSHIFT
 @defmacx PDBITS
 
 @defmac PDSHIFT
 @defmacx PDBITS

-The bit index (22) and number of bits (10), respectively, in a page
-directory index within a virtual address.
+The starting bit index (22) and number of bits (10), respectively, in a
+page directory index.

 @end defmac
 
 @defmac PDMASK
 A bit mask with the bits in the page directory index set to 1 and other
 @end defmac
 
 @defmac PDMASK
 A bit mask with the bits in the page directory index set to 1 and other

-bits set to 0.
+bits set to 0 (@t{0xffc00000}).

 @end defmac
 
 @deftypefun uintptr_t pd_no (const void *@var{va})
 @end defmac
 
 @deftypefun uintptr_t pd_no (const void *@var{va})


@@ -1762,7 +1760,7 @@ marked read/write; otherwise, it will be read-only.
 @deftypefun {void *} pte_get_page (uint32_t @var{pte})
 Returns the kernel virtual address for the frame that @var{pte} points
 to.  The @var{pte} may be present or not-present; if it is not-present
 @deftypefun {void *} pte_get_page (uint32_t @var{pte})
 Returns the kernel virtual address for the frame that @var{pte} points
 to.  The @var{pte} may be present or not-present; if it is not-present

-then the pointer return is only meaningful if the proper bits in the PTE
+then the pointer returned is only meaningful if the address bits in the PTE

 actually represent a physical address.
 @end deftypefun
 
 actually represent a physical address.
 @end deftypefun
 


@@ -1783,7 +1781,7 @@ marked read/write.
 
 @deftypefun {uint32_t *} pde_get_pt (uint32_t @var{pde})
 Returns the kernel virtual address for the page table page that
 
 @deftypefun {uint32_t *} pde_get_pt (uint32_t @var{pde})
 Returns the kernel virtual address for the page table page that

-@var{pde} points to.  The @var{pde} must be marked present.
+@var{pde}, which must be marked present, points to.

 @end deftypefun
 
 @node Hash Table
 @end deftypefun
 
 @node Hash Table