home *** CD-ROM | disk | FTP | other *** search
/ C/C++ User's Journal & Wi…eveloper's Journal Tools / C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso / sysembed / memory.edh < prev    next >
Encoding:
Text File  |  1995-03-30  |  7.3 KB  |  188 lines
  1. [10. Kernel Memory Management]
  2.              EMBEDDED DOS KERNEL MEMORY MANAGEMENT SERVICES
  3. ════════════════════════════════════════════════════════════════════════
  4. The pool object is an extremely fast, centralized, near heap used for
  5. scratch memory allocation at any time, including interrupt time.  While
  6. system pool is limited, it helps conserve code space by keeping only one
  7. memory allocator in memory, and it overcommits clients' memory needs,
  8. thereby saving data space.
  9.  
  10. Pool memory is allocated from only one segment, so that all pointers to
  11. objects carved out of pool have an implied and well-known segment or
  12. selector.  The segment component of the address is passed around in the
  13. portable form of the requests.
  14.  
  15. System pool should be used in situations where either a very small amount
  16. of memory (under 128 bytes) is allocated to represent some other object
  17. (as the kernel does to allocate mutex objects, timer objects, and so on).
  18. It may also be used to allocate larger blocks that will quickly leave the
  19. system.  For example, LAN packet drivers could acquire a 2kb block of
  20. system pool to represent an incoming packet, and upon process completion
  21. a millisecond later, the block could be released back to the system.
  22.  
  23. The kernel proper and all of the other Embedded DOS system components
  24. use system pool to build file objects, disk cache buffers, and so on.
  25.  
  26. The size of the system memory pool is configurable at system build time,
  27. and may be up to 65535 bytes in size.  The minimum allocation size is
  28. also configurable at build time, and is used to control fragmentation.
  29.  
  30. 1.  AllocatePool
  31.  
  32. A block of memory is allocated from system pool with the
  33. AllocatePool kernel function.  Once the block is allocated, it
  34. may be used for read/write/execute access until deallocated with
  35. DeallocatePool.
  36.  
  37. All blocks allocated with this request are addressable in the
  38. same segment; therefore, the pointer to a block of pool memory is
  39. a near pointer relative to a well-known segment/selector.  The
  40. system pool segment/selector is automatically returned in the
  41. portable form of this request to form a far pointer.  The macro
  42. instruction form of this request returns the offset portion of
  43. the block in the (DI) general purpose register.
  44.  
  45. Upon return, the macro instruction call clears the carry flag if
  46. the operation was successful, and sets it if the operation was
  47. not performed.
  48.  
  49. Assembly Language Format:
  50.  
  51.      mov  ax, <BlockSize>       ; (AX) = size of block in bytes.
  52.      mov  dl, SYS_ALLOCATE_POOL
  53.      int  2dh                   ; (DI) = ofs FWA, allocated block.
  54.      jc   Failure
  55.  
  56. Macro Instruction Format:
  57.  
  58. label     AllocatePool   <BlockSize>
  59.  
  60. Portable Request Format:
  61.  
  62. STATUS AllocatePool(
  63.      IN USHORT BlockSize,
  64.      OUT PVOID * BlockPtr
  65.      );
  66.  
  67. Parameters:
  68.  
  69.      BlockSize - Specifies 16-bit general purpose register, a
  70.           literal constant, or a pointer to a word in memory that
  71.           contains the requested size of the block to be
  72.           allocated in bytes.  The kernel reserves the right to
  73.           overallocate the block without notification.
  74.  
  75.      BlockPtr - Specifies a pointer to a pointer that will be
  76.           initialized by the kernel to point to the allocated
  77.           block of storage.  In the macro instruction form of the
  78.           request, a near pointer is passed in (DI).
  79.  
  80. 2.  DeallocatePool
  81.  
  82. A block of allocated system pool is returned to the system with
  83. the DeallocatePool kernel function.  Once the block is
  84. deallocated, it is no longer available to the caller, and the
  85. address of the block becomes invalid.  The caller must assume
  86. that the system recycles the system pool at a very rapid rate,
  87. and upon return from this function, will have most likely already
  88. allocated the address to another system component.
  89.  
  90. The macro instruction form of this request assumes that the
  91. offset pointer to the block is already in the (DI) general
  92. purpose register when the macro is executed.  The portable form
  93. of this request passes the entire pointer in the calling
  94. convention of the high-level language.
  95.  
  96. The kernel keeps a reference count on a block of pool memory.
  97. When the block is initially allocated, this reference count is
  98. set to 1.  When the DeallocatePool request is executed, this
  99. reference count is decremented, and if the reference count drops
  100. to zero, the block is deallocated.  Otherwise, the block remains
  101. locked in memory until the reference count is decremented with
  102. sufficient DeallocatePool requests to bring the reference count
  103. to zero.  The reference count is incremented artificially with
  104. the KeepPool kernel function.  This allows communicating kernel
  105. components to pass a data structure around without engaging in
  106. ownership protocol.
  107.  
  108. Upon return, the macro instruction call clears the carry flag if
  109. the operation was successful, and sets it if the operation was
  110. not performed.
  111.  
  112. Assembly Language Format:
  113.  
  114.      mov  di, <AllocatedBlockOffset>    ; (DI) = ofs FWA, block.
  115.      mov  dl, SYS_DEALLOCATE_POOL
  116.      int  2dh
  117.      jc   Failure
  118.  
  119. Macro Instruction Format:
  120.  
  121. label     DeallocatePool
  122.  
  123. Portable Request Format:
  124.  
  125. STATUS DeallocatePool(
  126.      IN PVOID BlockPtr
  127.      );
  128.  
  129. Parameters:
  130.  
  131.      BlockPtr - Specifies a pointer to a block of memory
  132.           allocated with the AllocatePool kernel function.  The
  133.           address must not be normalized with segment arithmetic,
  134.           because only the offset portion is examined by the kernel.
  135.  
  136. 3.  KeepPool
  137.  
  138. The KeepPool kernel function increments the reference count on a
  139. block of previously allocated pool memory, so that ownership is
  140. implicitly granted to the caller of the KeepPool function instead
  141. of the AllocatePool function.
  142.  
  143. The kernel keeps a reference count on a block of pool memory.
  144. When the block is initially allocated, this reference count is
  145. set to 1.  When the DeallocatePool request is executed, this
  146. reference count is decremented, and if the reference count drops
  147. to zero, the block is deallocated.  Otherwise, the block remains
  148. locked in memory until the reference count is decremented with
  149. sufficient DeallocatePool requests to bring the reference count
  150. to zero.  The reference count is incremented artificially with
  151. the KeepPool kernel function.  This allows communicating kernel
  152. components to pass a data structure around without engaging in
  153. ownership protocol.
  154.  
  155. In the macro instruction format of this request, the offset
  156. address of the block to be kept is passed in the (DI) general
  157. purpose register.  In the portable form of this request, the far
  158. pointer is passed according to the calling conventions of the
  159. high level language.
  160.  
  161. Upon return, the macro instruction call clears the carry flag if
  162. the operation was successful, and sets it if the operation was
  163. not performed.
  164.  
  165. Assembly Language Format:
  166.  
  167.      mov  di, <AllocatedBlockOffset>    ; (DI) = ofs FWA, block.
  168.      mov  dl, SYS_KEEP_POOL
  169.      int  2dh
  170.      jc   Failure
  171.  
  172. Macro Instruction Format:
  173.  
  174. label     KeepPool  <BlockPtr>
  175.  
  176. Portable Request Format:
  177.  
  178. STATUS KeepPool(
  179.      IN PVOID BlockPtr
  180.      );
  181.  
  182. Parameters:
  183.  
  184.      BlockPtr - Specifies a pointer to a block of memory
  185.           allocated with the AllocatePool kernel function.  The
  186.           address must not be normalized as the kernel only uses
  187.           the offset component of the address to locate the block
  188.           of system pool.