harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nadi...@apache.org
Subject svn commit: r651183 - /harmony/enhanced/drlvm/trunk/vm/port/doc/PortReadme.htm
Date Thu, 24 Apr 2008 08:01:57 GMT
Author: nadinem
Date: Thu Apr 24 01:01:55 2008
New Revision: 651183

URL: http://svn.apache.org/viewvc?rev=651183&view=rev
Log:
HARMONY-5736

Modified:
    harmony/enhanced/drlvm/trunk/vm/port/doc/PortReadme.htm

Modified: harmony/enhanced/drlvm/trunk/vm/port/doc/PortReadme.htm
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/doc/PortReadme.htm?rev=651183&r1=651182&r2=651183&view=diff
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/doc/PortReadme.htm (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/doc/PortReadme.htm Thu Apr 24 01:01:55 2008
@@ -22,81 +22,178 @@
 <html>
 
 <head>
-<title>PVL Porting Layer Notes</title>
+<title>Porting Layer Notes</title>
 </head>
 
 <body>
 
-<h3>1. Design notes</h3>
+<h3>1. Design  Notes</h3>
 
-The porting layer design adheres to concepts of APR (<a href="http://apr.apache.org/docs/apr/">Apache
Portable Runtime libraries</a>). These particularly include:
+The porting layer design adheres to concepts of APR (<a href="http://apr.apache.org/docs/apr/">Apache
+Portable Runtime libraries</a>), specifically:
 <ul>
-<li>	explicit memory management based on pools;
-<li>	consistent error reporting approach via returned status value;
-<li>	incomplete types to enforce platform abstraction.
+<li>Explicit memory management based on pools
+<li>Consistent error reporting approach via returned status value
+<li>Incomplete types to enforce platform abstraction
 </ul>
-Detailed APIs mainly follow APR standard, but there may not be strict correspondence in signatures.
Pure C should be used for implementation.
+Detailed APIs mainly follow the APR standard, but there may not be strict correspondence
+in signatures. Pure C should be used for implementation.
 
 <h4>Using APR binaries directly</h4>
-We define our own headers (aligned with APR), but do not wrap APR functions in code (no delegating
calls). 
-Instead, we map our signatures to APR functions directly, where it is possible, - via a set
of defines, like this:
+Harmony defines its own headers aligned with APR, but does not wrap APR functions
+in code (no delegating calls). Instead, signatures are mapped directly to APR functions
+where possible - via a set of defines, as follows:
 <pre>
 #define port_allocator_create(allocator) apr_allocator_create(allocator)
 #define port_allocator_destroy(allocator) apr_allocator_destroy(allocator)
 </pre>
-So, there is no runtime performance penalty at all. 
-<p>
-Why don't we use APR headers directly?
-Because, current approach has several advantages which we consider significant:
+<p>In this case, no run-time performance penalty is incurred. </p>
+<p>The current approach has several significant advantages over using APR headers
+  directly: </p>
 <ul>
-<li>Flexibility to switch portlib implementation at any moment - to j9 or any other,
including our own. In other words, we hide internal portlib issues from API customers.
-<li>We have a number of extensions (currently there are over 20 functions in portlib,
which are not in APR). So we have consistent naming of all portlib API
-<li>Easy to bugfix or tune particular functions. We already discovered cases, when
certain APR functions have flaws or do not suite VM needs properly - and we can replace single
functions very easily. The same is applicable for VAV.
-<li>When (if) the time comes for dynamic linking of porting layer, or for multi-VM
support, our headers are more suitable for organizing vtables than APR ones (which somewhere
use defines instead of real functions).
-<li>APR has its own build organization, completely different from DRL. Namely, there
are different sets of headers for each platform, with specific defines. We avoid extra inconveniences
by introducing common headers.
-<li>Clearly identified subset of APR functionality, which is actually used - will be
helpful for further VM porting
+<li>Flexibility to switch the portlib implementation to j9 or any other, including
+  our own, at any time. In other words, the  internal portlib
+  issues are hidden from API customers.
+<li>Extensions to APR; currently, over 20 functions are implemented that are not
+  part of APR. 
+<li>Consistent naming of the whole porting API.
+<li> Simplified bug fixing and tuning: several APR functions have been
+  encountered that have flaws or are not suitable for DRLVM; these functions are
+  easily replaced with Harmony's extensions.The same is applicable for VAV.
+<li>Easier potential support for dynamic linking or multi-VM support with Harmony
+  headers than with APR is: Harmony can organize VTables easier, unlike APR, which
+  sometimes uses defines instead of real functions.
+<li>Common headers to unify porting module build system with the DRLVM system: the
+  APR build organization is completely different in that it uses different sets of
+  headers for each platform, with specific defines. 
+<li>Clearly identified subset of APR functionality, which is actually used, which
+  may  be helpful for further VM porting.
 </ul>
 
-Of course, we also realize drawbacks of it:
+The key drawbacks of the current approach: 
 <ul>
-<li>Need for duplication of headers and documentation (though we may simply use redirection
links to APR docs).
-<li>Potential compatibility issues with future APR development (e.g. on extension boundaries).
-<li>Some space for confusion in open community, especially for those experienced in
APR applications.
+<li>Need for duplication of headers and documentation, though  redirection links
+  to APR docs can be used to work around this flaw. 
+<li>Potential compatibility issues with future APR development, for instance, on
+  extension boundaries.
+<li>Potential confusion in the open community, especially for those experienced in
+  APR applications.
 </ul>
 
 <h3>2. Directory structure</h3>
 
-Porting functionality is split to several groups (atomics, file I/O, mempools, etc). Each
group has a base directory, which contains subdirectories with actual code. These subdirectories
are named after the platforms and/or architectures they are compiled on. If there is a strong
dependency on both OS and machine architecture, the subdirectory name should combine both.
For example:
-<pre>
-   Port
-	|
-	 -> file_io
-	|	|
-	|	 -> linux
-	|	|
-	|	 -> windows
-	|
-	 -> atomics
-		|
-		 -> linux_em64t
-		|
-		 -> linux_ia32
-		|
-		 -> windows
+Porting functionality is split to several groups: atomics, file I/O, mempools, etc.
+Each group has a base directory, which contains subdirectories with actual code.
+These subdirectories are named after the platforms and/or architectures they are
+compiled on. If there is a strong dependency on both OS and machine architecture,
+the subdirectory name should combine both. The current directory structure looks
+as follows:
+<pre>port
+|->build
+|->doc
+|->include
+|  ->tl
+ ->src
+  |->atomic
+  | |->linux
+  | |->linux_ipf
+  |  ->win
+  |->barriers
+  |  ->linux_ipf
+  |->crash_handler
+  | |->em64t
+  | |->ia32
+  | |->include
+  | |->ipf
+  | |->linux
+  | |  ->include
+  |  ->win
+  |->disasm
+  | |->linux
+  |  ->win
+  |->encoder
+  |  ->ia32_em64t
+  |->file_io
+  | |->linux
+  |  ->win
+  |->lil
+  |  ->em64t
+  |->logger
+  |->malloc
+  |->memaccess
+  | |->linux
+  |  ->win
+  |->misc
+  | |->linux
+  |  ->win
+  |->modules
+  | |->linux
+  |  ->win
+  |->signals
+  | |->include
+  | |->linux
+  |  ->win
+  |->thread
+  | |->linux
+  |  ->win
+  |->time
+  |->tl
+   ->vmem
+    |->linux
+     ->win	 
 </pre>
+<p>
+Public headers are kept in a separate base directory named <code>include/</code>.
+Implementation headers may be kept in the source directories.
+
+<h3>3. Memory management</h3>
+
+The port layer contains wrappers for standard memory allocation functions in the <code>port_malloc.h</code>
file.
+They are presented as defines with names like <code>STD_MALLOC</code> for malloc,
<code>STD_FREE</code> for
+free etc. By default, they are simply equal to relative functions, but if <code>_MEMMGR</code>
is
+defined, they are replaced with another set of functions like <code>port_malloc</code>,
<code>port_free</code> etc.
+These functions provide additional functionality at the expense of lower performance.
+<p>
+Newly provided features:
+
+<ul>
+<li>Report allocation and de-allocation log
+<li>Check and report double free calling
+<li>Report not freed memory at VM shutdown
+<li>Provide precise info about currently used memory via the <code>java.lang.management</code>
interface
+<li>Provide separate memory allocation for the stress running conditions, like after
+  crash handler occurring
+</ul>
+
+<h4>Instructions on using these features</h4>
+<p>To switch on allocation and de-allocation logging, define the <code>_MEMMGR_LOG</code>
macro.
+  This macro also enables double free calling notifications. </p>
+<p>For the final not freed
+        memory reporting, define the <code>_MEMMGR_REPORT</code> macro. </p>
+<p>
+Currently, the stress memory allocator is defined not yet implemented, and just
+  redirects to standard malloc. To switch on stress allocation, define the <code>STRESS_MALLOC</code>
macro.
+    <p>
+The memory management module cannot use port logging because it leads to infinite
+  recursion. Its own primitive logging system uses the file in the current directory
+  with name <code>malloc.log</code> for
+  both logging and reporting. A different file name and location can be defining <code>MALLOC_LOG_FILE_NAME</code>.
+    <p>
+Used memory could be obtained by means of the <code>java.lang.management</code>
interface.
+It is presented as non-heap memory pool with name <code>Native Memory Pool</code>.
+Different pool name could be set by redefining <code>NATIVE_POOL_NAME</code>.
 
-Public headers are kept in a separate base directory named include. Implementation headers
may be kept in source directories?
 
-<h3>3. Build system</h3>
+    <h3>4. Build system</h3>
 
-Currently we reuse VM build system  based on MakeCommon. <br>
+Currently we reuse VM build system. <br>
 TODO - document platform defines and macros.
 
-<h3>4. APR issues </h3>
+<h3>5. APR issues </h3>
 <ul>
-<li>	Non-buffered file I/O on Windows has bad support for <code>apr_file_eof();</code>
-<li>	On Windows, <code>apr_dso_load()</code> fails on NULL path - 
-		which is meant for obtaining a handle for the calling module itself;
+<li>	Non-buffered file I/O on Windows* OS has bad support for <code>apr_file_eof()</code>
+<li>	On Windows OS, <code>apr_dso_load()</code> fails on NULL path - 
+		which is meant for obtaining a handle for the calling module itself
 </ul>
 
 



Mime
View raw message