Merge branch 'master' into jwt27

Author: jwt27

include/dpmi.h

@@ -203,7 +203,7 @@ int	__dpmi_resize_linear_memory(__dpmi_meminfo *_info, int _commit);			/* DPMI 1
 int	__dpmi_get_page_attributes(__dpmi_meminfo *_info, short *_buffer);			/* DPMI 1.0 AX=0506 */
 int	__dpmi_set_page_attributes(__dpmi_meminfo *_info, short *_buffer);			/* DPMI 1.0 AX=0507 */
 int	__dpmi_map_device_in_memory_block(__dpmi_meminfo *_info, unsigned long _physaddr);	/* DPMI 1.0 AX=0508 */
-int	__dpmi_map_conventional_memory_in_memory_block(__dpmi_meminfo *_info, unsigned long _physaddr); /* DPMI 1.0 AX=0509 */
+int	__dpmi_map_conventional_memory_in_memory_block(__dpmi_meminfo *_info, unsigned long _linaddr); /* DPMI 1.0 AX=0509 */
 int	__dpmi_get_memory_block_size_and_base(__dpmi_meminfo *_info);				/* DPMI 1.0 AX=050a */
 int	__dpmi_get_memory_information(__dpmi_memory_info *_buffer);				/* DPMI 1.0 AX=050b */
 

src/libc/dpmi/api/d0509.txh

@@ -6,7 +6,7 @@
 #include <dpmi.h>
 
 int __dpmi_map_conventional_memory_in_memory_block(
-        __dpmi_meminfo *info, unsigned long physaddr
+        __dpmi_meminfo *info, unsigned long linaddr
 );
 @end smallexample
 
@@ -19,8 +19,11 @@ the DPMI Overview (@pxref{DPMI Overview}) for general information.
 DPMI function AX = 0x0509 (DPMI 1.0 only).  Supported by CWSDPMI, but
 not by Windows.
 
-This function maps conventional memory (even when virtualized) to
-virtual memory.  Pass the handle, offset, and number of pages.
+This function maps/aliases conventional memory specified by the linear
+address @var{linaddr} (even when virtualized) to virtual memory
+specified by the handle and offset fields in @var{info}.  Pass the
+handle, offset relative to the start of the block, and number of
+pages to map.
 
 @subheading Return Value
 

src/libc/dpmi/helper/mapmem.txh

@@ -21,6 +21,22 @@ be set to @code{EINVAL} and the routine will fail.
 This routine properly handles memory ranges that span multiple DPMI
 handles, while @code{__dpmi_map_device_in_memory_block} does not.
 
+Every page in the specified address range @var{out_addr}, @var{num_bytes}
+must belong to some DPMI handle in @code{__djgpp_memory_handle_list}
+allocated by @code{sbrk}.
+
+To accommodate page-aligning and existence of DPMI handle for memory
+@var{out_addr}, the easiest option is to allocate page-aligned memory
+by @code{valloc} function (which internally uses @code{sbrk}) and
+then pass it to @code{__djgpp_map_physical_memory}.
+
+To unmap physical memory range created by @code{__djgpp_map_physical_memory},
+use @code{__djgpp_set_page_attributes} function and change page
+attributes of every page to committed type and read/write access
+without setting initial page access and dirty bits.  After that
+@var{our_addr} memory allocated by @code{valloc} can be returned
+back to the memory pool by @code{free}.
+
 Consult DPMI documentation on function 0508H for details on how this
 function works.  Note: since 0508H is a DPMI service new with DPMI
 1.0, this call will fail on most DPMI 0.9 servers.  For your program
@@ -42,7 +58,30 @@ DPMI server rejected the mapping request.
 @subheading Example
 
 @example
+void *my_page_aligned_memory = valloc (16384);
+if (!my_page_aligned_memory)
+{
+  printf ("Failed to allocate page-aligned memory!\n");
+  return;
+}
+
 if (__djgpp_map_physical_memory (my_page_aligned_memory, 16384,
                                  0x40000000))
+{
   printf ("Failed to map physical addresses!\n");
+}
+else
+{
+  /* code which access mapped my_page_aligned_memory */
+}
+
+if (__djgpp_set_page_attributes (my_page_aligned_memory, 16384,
+                                 (0<<4) | (1<<3) | 1))
+{
+  printf ("Failed to unmap physical addresses!\n");
+}
+else
+{
+  free (my_page_aligned_memory);
+}
 @end example