Improve documentation of '__djgpp_map_physical_memory'.

Document requirements / restrictions for out_addr/num_bytes
parameters, and extend example of how to use this function.
Patch from Pali <pali@pali.im>.

Author: Eli-Zaretskii

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