Index: xdocs/downloads.xml =================================================================== --- xdocs/downloads.xml (revision 517589) +++ xdocs/downloads.xml (working copy) @@ -52,47 +52,47 @@
We offer the following - snapshots : + snapshots:
Note
- These are snapshot builds - untested builds provided for your convenience. They + These are snapshot builds - untested builds provided for your convenience. They have not been tested, and are not official releases of the Apache Harmony project or the Apache Software Foundation.
- Java Development Kit (JDK) +- The JDK lets you build and run your Java programs. It include javac and other standard JDK tools. - Note that it's safest to set JAVA_HOME to the root directory - of the distribution, and put the bin/ directory on your PATH. -
+ The JDK lets you build and run your Java programs. It include javac and other standard JDK tools. + Note that it's safest to setJAVA_HOME to the root directory
+ of the distribution, and put the bin/ directory on your PATH.
+
- - The JRE lets you run your Java programs. Note that it's safest to set JAVA_HOME to the root directory - of the distribution, and put the bin/ directory on your PATH. +
+ The JRE lets you run your Java programs. Note that it's safest to set JAVA_HOME to the root directory
+of the distribution, and put the bin/ directory on your PATH.
- The HDK is targetted at Harmony developers. It includes the pre-built class library and VM binaries, + The HDK is targetted at Harmony developers. It includes the pre-built class library and VM binaries, necessary include files, test cases, and dependencies. It is not a replacement for the common JDK.
@@ -140,7 +140,7 @@These are not official releases of the Apache Software Foundation, nor are they - complete or compatible with the Java specification. They are snapshots provided + complete or compatible with the Java specification. They are snapshots provided to make testing and experimentation easier.
@@ -157,3 +157,4 @@ + Index: xdocs/faq.xml =================================================================== --- xdocs/faq.xml (revision 517589) +++ xdocs/faq.xml (working copy) @@ -1,12 +1,11 @@ - +ANT_OPTS environment variable to something bigger than
+ the default. At the time of this writing, best practice is to set:
+ set ANT_OPTS="-Xmx256M"+
- set ANT_OPTS="-Xmx256M" --
+ Our latest snapshots have + lots of new fixes and features. The VM has a new GC, + almost complete JVMTI, and now can co-exist with + the IBM VME in + the Harmony JRE structure. Our classlibrary continues to grow with new + classes, notably CORBA, thanks to + Apache Yoko. + Also, the classlibrary includes many new fixes and updates. + Choose the JRE to test your favorite applications, and + give us feedback on how + we are doing, or use the HDK to enable faster development of the Harmony classlibrary. + (2006-09-28) +
++ We're happy to help + (2006-08-16) +
+- New JRE and HDK Snapshots Posted -
- Our latest snapshots have - lots of new fixes and features. The VM has a new GC, - almost complete JVMTI, and now can co-exist with - the IBM VME in - the Harmony JRE structure. Our classlibrary continues to grow with new - classes, notably CORBA, thanks to - Apache Yoko. Also, the classlibrary includes many new fixes and updates. - Choose the JRE to test your favorite applications, and - give us feedback on how - we are doing, or use the HDK to enable faster development of the Harmony classlibrary. - (2006-09-28) -- -
- Can Apache Harmony Help Sun Open Java? -
- We're happy to help - (2006-08-16) -- -
- New Snapshot Posted -
- Lots of fixes and additions in the latest snapshot. - (2006-08-16) -- -
- DRLVM Documentation Update -
- Check our new documentation on - DRLVM - including guides for building, using, debugging, - GC architecture and execution manager - architecture. - (2006-08-05) -- -
- New HDK and JRE Snapshots Available -
- New - snapshots - of the HDK and JRE are now available with lots of bugfixes. - (2006-08-04) -- -
- HDK and JRE Snapshots Available -
- Harmony now - offers a snapshot - of it's JRE and HDK builds. - The JRE snapshot is our in-progress Java Runtime Environment, - including both the virtual machine and classlibrary. Note that - this isn't stable, complete or compatible software. However, - you can use this to run your favorite Java applications and - help the project find and fix bugs, and help direct our efforts - to complete the most popular parts of the classlibrary first. The HDK - snapshot is a developers build, complete with classlibrary jars and - native libraries, header files, and build scripts. - (2006-07-22) -- -
- New class library snapshot build available -
- A new stable snapshot of the class libraries code is available - for download from the - Harmony downloads page. - These are made available for people to evaluate and experiment - with the code. This snapshot contains the recently integrated - Swing, AWT, and Java2D code. As always, please report bugs - (and successes!) to the - Harmony developers mailing list. - (2006-06-30) -- -
- AWT, Java2D and Swing Code Contribution -
- On May 30th, 2006 the Apache Harmony project received a - substantial - contribution of class library code into the project. The code for - AWT, Java2D, and Swing implementation has been contributed by Alexey - Petrenko on behalf of Intel corp. The full announcement can be found - on the - Harmony developers mailing list. Thanks to - Alexey and his colleagues in the Intel Middleware Products Division! - (2006-05-31) -- - -
- New class library snapshot build available -
- A new stable snapshot of the class libraries code is available - for download from the - Harmony downloads page. - There are source and binary downloads available for people to - evaluate and experiment with the code. As always, please report bugs - (and successes!) to the - Harmony developers mailing list. - (2006-05-12) -- - -
- DRL Virtual Machine Contribution -
- On May 3rd, 2006 the Apache Harmony project received a - substantial - contribution of virtual machine (VM) code into the project, containing - a JIT, core VM, GC, bytecode verifier, etc. This was contributed by - Andrey Chernyshev on behalf of Intel Corp. The full announcement can - be found on the - Harmony developers mailing list. - (2006-05-03) -- - -
- Java Security Code Contribution -
- On December 30th, 2005 the Apache Harmony project accepted additional - class library code into the project. The code had been contributed by - Mikhail Loenko on behalf of Intel corp. The new class library code - includes security, cryptography, javax.net and unit tests. Thanks to - Mikhail and his collegues in the Intel Managed Runtime Division! - (2006-01-16) -- - -
- VM Interface and Core Classes Contribution -
- IBM has offered the Apache Harmony project a set of core - Java classes and an implementation of a VM/class library - interface. Tim Ellison wrote : - -- - -I'm delighted to be able to make a code contribution to the - Harmony project on behalf of IBM. The code comprises a concrete implementation - of the interface between virtual machine and class library that we have - been discussing recently, together with a set of core Java classes. -- This contribution is sufficient to run Ant and the Eclipse Java - compiler, to provide a basic self-hosting environment. IBM also - made a version of their J9 VM - - available for use by the project in evaluating this contribution. - Thanks Tim and IBM :) - (2005-11-08) -
- "Bootstrap JVM" Contributed to Apache Harmony -
- Daniel Lydickto the Harmony project of a basic Java - Virtual Machine entitled the "Apache Harmony Bootstrap JVM." - Dan offered the VM with the following goals in mind : -- - --
- Thanks Dan! - (2005-09-30) -- Basic platform for learning about VMs
-- Boostrap and runtime framework for our eventual 'production' VM
-- Help spur architectural discussion about core - component designs
-
- Source for JCVM Contributed to Apache Harmony -
- Archie Cobbs has offered for contribution to the Apache Harmony project - a copy of the JCVM - codebase. Come and help us build on this interesting - VM. Thanks Archie! - (2005-09-25) -- -
- Project accepted by Apache Incubator -
- The Apache Harmony project was accepted formally accepted for - inubation by the Apache Incubator PMC. - (2005-05-18) -- +
+ Lots of fixes and additions in the latest snapshot. (2006-08-16) +
++ Check our new documentation on DRLVM + including guides for building, using, debugging, GC architecture and execution manager + architecture. (2006-08-05) +
++ New snapshots + of the HDK and JRE are now available with lots of bugfixes. (2006-08-04) +
++ Harmony now offers a snapshot + of it's JRE and HDK builds. + The JRE snapshot is our in-progress Java Runtime Environment, + including both the virtual machine and classlibrary. Note that + this isn't stable, complete or compatible software. However, + you can use this to run your favorite Java applications and + help the project find and fix bugs, and help direct our efforts + to complete the most popular parts of the classlibrary first. The HDK + snapshot is a developers build, complete with classlibrary jars and + native libraries, header files, and build scripts. (2006-07-22) +
++ A new stable snapshot of the class libraries code is available + for download from the Harmony downloads page. + These are made available for people to evaluate and experiment + with the code. This snapshot contains the recently integrated + Swing, AWT, and Java2D code. As always, please report bugs + (and successes!) to the Harmony developers mailing list. + (2006-06-30) +
++ On May 30th, 2006 the Apache Harmony project received a + + substantial contribution of class library code into the project. + The code for AWT, Java2D, and Swing implementation has been contributed by Alexey + Petrenko on behalf of Intel corp. The full announcement can be found + on the Harmony developers mailing list. Thanks to + Alexey and his colleagues in the Intel Middleware Products Division! + (2006-05-31) +
++ A new stable snapshot of the class libraries code is available + for download from the Harmony downloads page. + There are source and binary downloads available for people to + evaluate and experiment with the code. As always, please report bugs + (and successes!) to the Harmony developers mailing list. + (2006-05-12) +
++ On May 3rd, 2006 the Apache Harmony project received a + + substantial contribution of virtual machine (VM) code into the project, + containing a JIT, core VM, GC, bytecode verifier, etc. This was contributed by + Andrey Chernyshev on behalf of Intel Corp. The full announcement can + be found on the Harmony developers mailing list. + (2006-05-03) +
++ On December 30th, 2005 the Apache Harmony project accepted additional + class library code into the project. The code had been contributed by + Mikhail Loenko on behalf of Intel corp. The new class library code + includes security, cryptography, javax.net and unit tests. Thanks to + Mikhail and his collegues in the Intel Managed Runtime Division! + (2006-01-16) +
++ IBM has offered the Apache Harmony project a set of core + Java classes and an implementation of a VM/class library + interface. Tim Ellison wrote: +
++ + I'm delighted to be able to make a code contribution to the + Harmony project on behalf of IBM. The code comprises a concrete implementation + of the interface between virtual machine and class library that we have + been discussing recently, together with a set of core Java classes. + +
++ This contribution is sufficient to run Ant and the Eclipse Java + compiler, to provide a basic self-hosting environment. IBM also + made a version of their J9 VM + + available for use by the project in evaluating this contribution. + Thanks Tim and IBM :) (2005-11-08) +
++ Daniel Lydickto the Harmony project of a basic Java Virtual Machine entitled + the "Apache Harmony Bootstrap JVM." Dan offered the VM with the following goals in mind: +
+ Archie Cobbs has offered for contribution to the Apache Harmony project + a copy of the JCVM codebase. Come and + help us build on this interesting VM. Thanks Archie! (2005-09-25) +
++ The Apache Harmony project was accepted formally accepted for + inubation by the Apache Incubator PMC. (2005-05-18) +
+As part of the JDK that Harmony will distribute, we'll include @@ -174,7 +173,7 @@
- 2. Modularity +From the beginning of our project, we've had a strong interest and focus on modularity This dedication has paid off in our class library development, @@ -371,9 +370,7 @@ Documentation TODO
Another motivation of the Harmony project is to provide a @@ -415,9 +412,7 @@
As we now have a fairly usable class library and virtual machine, we wish to make it easy for the broad Java user community to help us ensure that @@ -448,3 +443,4 @@ + Index: xdocs/subcomponents/classlibrary/ASN1Framework.html =================================================================== --- xdocs/subcomponents/classlibrary/ASN1Framework.html (revision 517589) +++ xdocs/subcomponents/classlibrary/ASN1Framework.html (working copy) @@ -18,218 +18,193 @@ -
- -- Revision History -
- - -- Purpose -
- - - -- About -
- -- ASN.1 Framework in Harmony -
-- About -
-- Mapping between ASN.1 and Java Types -
- -- Encoding Rules -
-- Implementing ASN.1 Notations -
- -- References -
-| - Version + Version | - Version Information + Version Information | - Date + Date | -
|---|---|---|
| - Initial version + Initial version |
- Nadya Morozova, Stepan Mishura: document created + Nadya Morozova, Stepan Mishura: document created Special thanks to Sergey Dmitriev for assistance |
- November 16, 2005 + November 16, 2005 | -
| - Formatting update + Formatting update | - Nadya Morozova + Nadya Morozova | - September 21, 2006 + September 21, 2006 | -
- This document introduces the ASN.1 (Abstract Syntax Notation) - framework delivered as part of the Harmony classlibrary. This document - provides an overview of ASN.1 types and encoding rules with focus on - the characteristics of the current implementation. The document gives - details on the framework design and provides an overall description of - the ASN.1 package. -
-- The target audience for the document includes a wide community of - engineers interested in using ASN.1 and in further work with the - product to contribute to its development. The document assumes that - readers are familiar with the ASN.1 notation and the Java* programming language. -
-- This document uses the unified - conventions for the Harmony documentation kit. -
-- Back to Top -
-- ASN.1 (Abstract Syntax Notation One) is an international standard of - notation used to specify data structures with a high level of - abstraction, which is reflected in the ASN.1 specification [2]. ASN.1 is fully platform- and - language-independent. ASN.1 goes with the encoding rules, which - determine how to represent a value of an abstract type as a string of - octets [3]. -
-- The Java* API specification [1] employs ASN.1 in the following ways: -
-- To learn more about ASN.1, you can use online documentation [4], [5], and - publications [6], [7]. -
-- Back to Top -
-- ASN.1 has the following basic types: -
-ANY and
- CHOICE.
- - These types are used to specify a wide range of other abstract types, - as shown in Example 1. -
- -- This example is based on RFC 3280 [8]. -
--+
+ This document introduces the ASN.1 (Abstract Syntax Notation) framework delivered + as part of the Harmony classlibrary. This document provides an overview of ASN.1 + types and encoding rules with focus on the characteristics of the current implementation. + The document gives details on the framework design and provides an overall description + of the ASN.1 package. +
++ The target audience for the document includes a wide community of engineers interested + in using ASN.1 and in further work with the product to contribute to its development. + The document assumes that readers are familiar with the ASN.1 notation and the Java* programming language. +
++ This document uses the unified conventions + for the Harmony documentation kit. +
++ Back to Top +
++ ASN.1 (Abstract Syntax Notation One) is an international standard of notation used + to specify data structures with a high level of abstraction, which is reflected + in the ASN.1 specification [2]. ASN.1 is fully platform- + and language-independent. ASN.1 goes with the encoding rules, which determine + how to represent a value of an abstract type as a string of octets [3]. +
++ The Java* API specification [1] employs + ASN.1 in the following ways: +
++ To learn more about ASN.1, you can use online documentation [4], + [5], and publications [6], [7]. +
++ Back to Top +
++ ASN.1 has the following basic types: +
+ANY and CHOICE.
+ + These types are used to specify a wide range of other abstract types, as shown in + Example 1. +
+ ++ This example is based on RFC 3280 [8]. +
+
Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension
Extension ::= SEQUENCE {
@@ -240,102 +215,84 @@
Version ::= INTEGER { v1(0), v2(1), v3(2) }
-
-
- In this example, the basic ASN.1 types SEQUENCE,
- OBJECT IDENTIFIER, BOOLEAN and OCTET
- STRING are used to specify a new abstract type
- Extension. The newly created type is then used with
- another basic type SEQUENCE OF to describe the
- Extensions type. The ASN.1 INTEGER type is
- used to specify the Version abstract type and to provide
- constraints for this type.
-
- Back to Top -
-- This section part of the document describes the ASN.1 framework as a - whole, defines the mapping principles to establish the correspondence - between ASN.1 and Java* types, and represents the - hierarchy of ASN.1 types representation in the current framework. -
-- The ASN.1 framework provides a common, easy and efficient approach for - working with ASN.1 basic types, notations and encoding rules. This - framework can be described as a layer between a Java* - object and its ASN.1 encoded form, as shown in Figure 1. -
-
-
-
- Figure 1: ASN.1 Framework Layer -
-- The Harmony ASN.1 framework is characterized by: -
-- The framework enables the following: -
-- Note -
-- The current ASN.1 framework is a partial implementation of the ASN.1 - and encoding rules specifications. This framework covers certain ASN.1 - basic types and basic encoding rules (BER), and provides most - restrictions employed by the distinguished encoding rules (DER). -
-- The framework maps all ASN.1 abstract types and notations to Java* primitive types or Java* classes. -
- -- The notations in Example 1 can be represented - as the following Java* classes: -
---++ In this example, the basic ASN.1 types
+SEQUENCE,OBJECT IDENTIFIER, +BOOLEANandOCTET STRINGare used to specify a new abstract + typeExtension. The newly created type is then used with another basic + typeSEQUENCE OFto describe theExtensionstype. The + ASN.1INTEGERtype is used to specify theVersionabstract + type and to provide constraints for this type. ++ Back to Top +
++ ASN.1 Framework in Harmony +
++ This section part of the document describes the ASN.1 framework as a whole, defines + the mapping principles to establish the correspondence between ASN.1 and Java* + types, and represents the hierarchy of ASN.1 types representation in the current + framework. +
++ About +
++ The ASN.1 framework provides a common, easy and efficient approach for working with + ASN.1 basic types, notations and encoding rules. This framework can be described + as a layer between a Java* object and its ASN.1 encoded form, as + shown in Figure 1. +
+
+
++
++
+ Figure 1: ASN.1 Framework Layer +
++ The Harmony ASN.1 framework is characterized by: +
++
+- A clear API for decoding and encoding objects
+- Low resource consuming
+- Thread safety
++ The framework enables the following: +
++
+- Create a Java* object instance from its encoded octet string
+- Verify that an octet string is a valid encoded string
+- Generate an encoded octet string for a particular object
++ Note +
++ The current ASN.1 framework is a partial implementation of the ASN.1 and encoding + rules specifications. This framework covers certain ASN.1 basic types and basic + encoding rules (BER), and provides most restrictions employed by the distinguished + encoding rules (DER). +
++ Mapping between ASN.1 and Java* Types +
++ The framework maps all ASN.1 abstract types and notations to Java* + primitive types or Java* classes. +
+ ++ The notations in Example 1 can be represented as the following + Java* classes: +
+public class Extension { private String extnID; private boolean critical; @@ -347,753 +304,640 @@ private List extensions; }-
- The Extension notation corresponds to a Java* class with three fields, where every field corresponds
- to one entry in the Extension notation. For example, the
- critical BOOLEAN DEFAULT FALSE field in the
- Extension notation corresponds to the boolean
- critical field in the Java* class. The
- Extensions notation equals to a Java*
- class with a field that contains an ordered collection of the
- instances of the Extension class.
-
- The table below describes the default mapping ASN.1 types to Java* types, and indicates the class providing the specified - mapping in the current framework. -
-|
- ASN.1 Type
+
+ The + The table below describes the default mapping ASN.1 types to Java* + types, and indicates the class providing the specified mapping in the current framework. + +
- Back to Top - -- Harmony ASN.1 - Classes --
- Basic ASN.1 types are in the
-
- - Figure 2: Class Hierarchy - -- The subsequent sections provide as short description of the classes - included in the package. - - -
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+ Back to Top +
+
+ Basic ASN.1 types are in the org.apache.harmony.security.asn1 package
+ in accordance with the hierarchy shown in Figure 2.
+
+
+
+ Figure 2: Class Hierarchy +
++ The subsequent sections provide as short description of the classes included in + the package. +
+ +INTEGER type that denotes an arbitrary
+ integer with positive, negative, or zero values and any magnitude. Because an integer
+ value is not restricted, it is up to the application class to choose the Java*
+ type for storing the integer value, for example, an instance of the java.math.BigInteger
+ class. By default, an integer value is stored in an array of bytes.
+ ENUMERATED type that denotes a set
+ of integer values. The implementation of this class is similar to that of the
+ ASN1Integer class.
+ OBJECT IDENTIFIER type. This type is
+ a sequence of integer components that identifies an entity, such as an organization
+ or an algorithm. Integer components have no negative values. An OBJECT IDENTIFIER
+ value includes at least two components. The corresponding Java*
+ type is an array of integer values.
+ BOOLEAN type, which corresponds to
+ the java.lang.Boolean Java* class.
+ BMPString, IA5String,
+ GeneralString, PrintableString, TeletexString, UniversalString, and UTF8String.
+ The class maps all these types to the java.lang.String object.
- Note + Note
- The current implementation does not verify allowed characters
- for any of ASN.1 restricted characters types. The class only
- stores and retrieves contents bytes to and from the
- String object.
+ The current implementation does not verify allowed characters for any of ASN.1 restricted
+ characters types. The class only stores and retrieves contents bytes to and from
+ the String object.
BitString type. The
- corresponding Java* class is
- BitString included in the asn1 package.
- The class provides implementation for decoding or encoding
- BitString objects.
+ BitString type. The corresponding Java* class is BitString included in the asn1
+ package. The class provides implementation for decoding or encoding BitString
+ objects.
- Note + Note
- A special use case for this ASN.1 type exists, when the type is
- declared as Named BitString. For example:
+ A special use case for this ASN.1 type exists, when the type is declared as Named
+ BitString. For example:
---+Keys ::= BIT STRING { Key1 (0), Key2 (1), MyKey (2) }-
- In this case, the BER specification [3] enables adding and removing any number
- of trailing to and from the basic encoding. To provide a correct
- type implementation, use the
- ASN1Bitstring.ASN1NamedBitList class. By default,
- the class maps the ASN.1 Named BitString type to an
- array of primitive boolean values.
+ In this case, the BER specification [3] enables adding
+ and removing any number of trailing to and from the basic encoding. To provide a
+ correct type implementation, use the ASN1Bitstring.ASN1NamedBitList
+ class. By default, the class maps the ASN.1 Named BitString type to
+ an array of primitive boolean values.
OctetString type,
- which corresponds to the Java* type of an array of
- bytes.
- UTCTime type. The
- corresponding Java* class is
- java.util.Date.
- GeneralizedTime type.
- The corresponding Java* class is
- java.util.Date.
- integer, boolean, ANY, then
- an initialization array must contain three class instances in the
- same order: ASN1Boolean, ASN1Integer,
+ OctetString type, which corresponds
+ to the Java* type of an array of bytes.
+ UTCTime type. The corresponding Java* class is java.util.Date.
+ GeneralizedTime type. The corresponding
+ Java* class is java.util.Date.
+ integer,
+ boolean, ANY, then an initialization array must contain
+ three class instances in the same order: ASN1Boolean, ASN1Integer,
ASN1Any.
- SEQUENCE OF type denotes an ordered collection of
- one or more values of the selected ASN.1 type. An instance of the
- class is initialized with an instance of the ASN.1 class according
- to the type notation. The passed instance is used to decode or
- encode all values in an collection.
- SET OF type denotes an unordered collection of one
- or more values of the selected ASN.1 type. This class is similar to
- the ASN1SequenceOf class.
- EXPLICIT type tagging.
- Explicit tagging denotes a type derived from another type
- by adding an outer tag to the base type. This type can be
- represented as a sequence type with only one component, so that the
- implementation class acts as a container for another ASN.1 type.
- IMPLICIT type tagging.
- An implicitly tagged type is a type derived from another
- type by changing a tag of the base type. The implementation class
- for this type changes only the tag when decoding or encoding the
- base type.
- ANY type. The type
- denotes any ASN.1 type that can be defined by a value of the
- OBJECT IDENTIFIER or by an integer index. The class
- handles only raw data represented as a Java* byte
- array. It is up to the application class to select the appropriate
- decoder or encoder for retrieving or storing the content
- respectively.
- CHOICE type. The type
- represents a list of one more type alternatives with distinct tags.
- an instance of the class is initialized with the Java* array of ASN.1 classes, which corresponds to a type
+ SEQUENCE OF type denotes an ordered collection of one or more values
+ of the selected ASN.1 type. An instance of the class is initialized with an instance
+ of the ASN.1 class according to the type notation. The passed instance is used to
+ decode or encode all values in an collection.
+ SET OF type denotes an unordered collection of one or more values
+ of the selected ASN.1 type. This class is similar to the ASN1SequenceOf
+ class.
+ EXPLICIT type tagging. Explicit tagging
+ denotes a type derived from another type by adding an outer tag to the base type.
+ This type can be represented as a sequence type with only one component, so that
+ the implementation class acts as a container for another ASN.1 type.
+ IMPLICIT type tagging. An implicitly
+ tagged type is a type derived from another type by changing a tag of the
+ base type. The implementation class for this type changes only the tag when decoding
+ or encoding the base type.
+ ANY type. The type denotes any ASN.1
+ type that can be defined by a value of the OBJECT IDENTIFIER or by
+ an integer index. The class handles only raw data represented as a Java*
+ byte array. It is up to the application class to select the appropriate decoder
+ or encoder for retrieving or storing the content respectively.
+ CHOICE type. The type represents a list
+ of one more type alternatives with distinct tags. an instance of the class is initialized
+ with the Java* array of ASN.1 classes, which corresponds to a type
notation.CHOICE type is specified as a list
- of boolean, OctetString and
- UTCTime, then an initialization array contains
- instances of the ASN1Boolean,
- ASN1OctetString and ASN1UTCTime classes.
- During decoding or encoding, a required type alternative is
- selected.
- - Back to Top -
-
- Encoding rules specify how to represent an ASN.1 type as a sequence of
- octets. ASN.1 encoding rules are represented in the
- org.apache.harmony.security.asn1 package, as follows:
-
BerInputStream and DerInputStream provide
- decoding and verifying functionality for corresponding notation
- rules.
- BerOutputStream and DerOutputStream
- provide the encoding functionality.
- - Back to Top -
-
- Encoding an object is the process of extracting all required
- information from an object and storing it in a sequence of octets
- according to the specified ASN.1 notation and encoding rules. The
- common encoding functionality is implemented in the
- BerOutputStream class. Encoding for DER is represented by
- the DEROutputStream class.
-
- The encoding of data for each ASN.1 type includes: -
-- DER Encoding -
-- In contrast to BER, DER enables using only the definite form of length - encoding. That is why, before encoding an ASN.1 type value, the ASN.1 - framework must obtain the length of the value. This requirement - determines the whole process of DER encoding: to calculate the length - of a constructed ASN.1 type, the framework calculates lengths of its - components, which can also be constructed, and so on. DER encoding - goes in the following stages: -
-- Decoding or verifying the provided encoded form is a - sequential process of parsing strings of octets according to the - specified ASN.1 notation and encoding rules. -
-
- An iteration of decoding an ASN.1 type includes decoding its tag,
- length, and content octets. The class BerInputStream
- provides a common decoding implementation for all basic ASN.1 types.
- To provide specific decoding for a basic ASN.1 type, a derived class
- must override one of the corresponding methods. For example,
- DerInputStream provides a custom implementation for
- decoding the ASN.1 Boolean type by overriding the method
- readBoolean().
-
- Back to Top -
-- In the current framework, the basic classes meet the following - requirements: -
-getInstance()
- method.- Back to Top -
-
- Classes from the asn1 package that represent ASN.1 basic
- types are used as building blocks for implementing a custom
- ASN.1 encoding or decoding class. A custom ASN.1 class provides
- mapping of an abstract ASN.1 type to a definite Java*
- class.
-
- Two approaches for implementing custom ASN.1 classes are available. - Custom classes can be designed as singleton Java* - classes or not. The choice depends on further use of the class - decoder. The singleton approach is not efficient when decoding only - one Java* object. However, for decoding a series of - encodings (for example, with an application server), the singleton - approach is rather effective because only one reusable decoder - instance exists. Creating a new decoder object for each decoded or - encoded Java* object leads to performance penalties. -
-- To implement the singleton approach, a custom ASN.1 class must meet - the following requirements: -
-- Example 3 -
-
- This example illustrates the singleton approach to static instances of
- ASN.1 custom classes for the Extensions and
- Extension classes used in Example
- 2 . For this, create an instance of a custom ASN.1 class as an
- instance of an anonymous class as shown below.
-
--+ For example, if aCHOICEtype is specified as a list ofboolean, +OctetStringandUTCTime, then an initialization array + contains instances of theASN1Boolean,ASN1OctetString+ andASN1UTCTimeclasses. During decoding or encoding, a required type + alternative is selected. + + ++ Back to Top +
++ Encoding Rules +
++ Encoding rules specify how to represent an ASN.1 type as a sequence of octets. ASN.1 + encoding rules are represented in the
+org.apache.harmony.security.asn1+ package, as follows: ++
+- +
BerInputStreamandDerInputStreamprovide decoding and + verifying functionality for corresponding notation rules.- +
BerOutputStreamandDerOutputStreamprovide the encoding + functionality.+ Back to Top +
++ Encoding +
++ Encoding an object is the process of extracting all required information + from an object and storing it in a sequence of octets according to the specified + ASN.1 notation and encoding rules. The common encoding functionality is implemented + in the
+BerOutputStreamclass. Encoding for DER is represented by the +DEROutputStreamclass. ++ The encoding of data for each ASN.1 type includes: +
++
+- identifier octets (for example, tag)
+- length octets
+- content octets
+- end-of-content octets
++ DER Encoding +
++ In contrast to BER, DER enables using only the definite form of length encoding. + That is why, before encoding an ASN.1 type value, the ASN.1 framework must obtain + the length of the value. This requirement determines the whole process of DER encoding: + to calculate the length of a constructed ASN.1 type, the framework calculates lengths + of its components, which can also be constructed, and so on. DER encoding goes in + the following stages: +
++
+- Collection: Step by step, the DER encoder extracts all data to be encoded, + processes the data, calculates an encoding length for each item, and stores all + calculations and processed data. Then, the encoder calculates the overall encoding + length and allocates required space.
+- Encoding: The DER encoder retrieves stored information, encodes it according + to the rules and writes the encoding to the allocated byte array.
++ Decoding +
++ Decoding or verifying the provided encoded form is a sequential process + of parsing strings of octets according to the specified ASN.1 notation and encoding + rules. +
++ An iteration of decoding an ASN.1 type includes decoding its tag, length, and content + octets. The class
+BerInputStreamprovides a common decoding implementation + for all basic ASN.1 types. To provide specific decoding for a basic ASN.1 type, + a derived class must override one of the corresponding methods. For example,DerInputStream+ provides a custom implementation for decoding theASN.1 Booleantype + by overriding the methodreadBoolean(). ++ Back to Top +
++ Implementing + ASN.1 Notations +
++ Basic Classes +
++ In the current framework, the basic classes meet the following requirements: +
++
+- All basic classes are thread-safe classes.
+
+ This means that an instance of an ASN.1 class can be used by many threads simultaneously + for decoding or encoding a particular class of Java* objects. An + instance of an ASN.1 class does not keep any specific data for a selected object. + It only provides a way for a decoder stream to store decoded data in a Java* + object, and a way for an encoder stream to extract a data to be encoded from a Java* object.- All classes for string and primitive ASN.1 types provide access to a reusable class + instance via the static
+getInstance()method.
+ If a separate instance of an ASN.1 class is not required, this method is used instead + of a constructor. A constructor is provided for inheritance purposes only.+ Back to Top +
++ Custom Classes +
++ Classes from the
+asn1package that represent ASN.1 basic types are + used as building blocks for implementing a custom ASN.1 encoding or decoding + class. A custom ASN.1 class provides mapping of an abstract ASN.1 type to a definite + Java* class. ++ Two approaches for implementing custom ASN.1 classes are available. Custom classes + can be designed as singleton Java* classes or not. The choice depends + on further use of the class decoder. The singleton approach is not efficient when + decoding only one Java* object. However, for decoding a series + of encodings (for example, with an application server), the singleton approach is + rather effective because only one reusable decoder instance exists. Creating a new + decoder object for each decoded or encoded Java* object leads to + performance penalties. +
++ To implement the singleton approach, a custom ASN.1 class must meet the following + requirements: +
++
+- Class has only one reusable instance and provides a way to access it.
+- Class is thread-safe. Thread safety is provided by passing all required data via + parameters of methods. All data specific for a Java* object is + stored in the decoding or encoding stream.
++ Example 3 +
++ This example illustrates the singleton approach to static instances of ASN.1 custom + classes for the
+ExtensionsandExtensionclasses used + in Example 2 . For this, create an instance of a custom + ASN.1 class as an instance of an anonymous class as shown below. +class Extensions { // instance of decoder/encoder public static final ASN1SequenceOf ASN1 = @@ -1124,59 +968,52 @@ }-
- The static final ASN1 field instance provides a mapping
- between the Java* Extension class and
- its ASN.1 notation. The field is initialized so that it reflects the
- ASN.1 notation of the class: it is the instance of the
- ASN1Sequence class that is initialized with instances of
- the ASN1Oid, ASN1Boolean and
- ASN1OctetString classes.
-
- The Extensions class has a similar field. The field also
- reflects the ASN.1 notation: it is the instance of the
- ASN1SequenceOf class and it is initialized by the
- ASN1 field from the Extension class.
-
- Figure 3 displays the correspondence between the application object - tree and the object tree of ASN.1 custom classes. -
-
-
-
- Figure 3: Java Object and ASN.1 Custom Class Trees -
-- Back to Top -
-- This section demonstrates the usage of the ASN.1 framework. -
-
- An abstract type can be defined as ASN.1 Boolean, for
- example:
-
--++ The
+static final ASN1field instance provides a mapping between the + Java*Extensionclass and its ASN.1 notation. The + field is initialized so that it reflects the ASN.1 notation of the class: it is + the instance of theASN1Sequenceclass that is initialized with instances + of theASN1Oid,ASN1BooleanandASN1OctetString+ classes. ++ The
+Extensionsclass has a similar field. The field also reflects the + ASN.1 notation: it is the instance of theASN1SequenceOfclass and + it is initialized by theASN1field from theExtension+ class. ++ Figure 3 displays the correspondence between the application object tree and the + object tree of ASN.1 custom classes. +
++
++
+ Figure 3: Java Object and ASN.1 Custom Class Trees +
++ Back to Top +
++ Appendix: Usage Examples +
++ This section demonstrates the usage of the ASN.1 framework. +
++ ASN.1 Boolean +
++ An abstract type can be defined as
+ASN.1 Boolean, for example: +MyBooleanType ::= BOOLEAN;-
- Then the following code can be used to decode and encode values of - this type: -
---++ Then the following code can be used to decode and encode values of this type: +
+// represents encoded ASN.1 Boolean type: false value byte encoding[] = new byte[] {0x01, 0x01, 0x00}; @@ -1191,29 +1028,23 @@ // an array value equals to {0x01, 0x01, 0xFF} byte enc[] = asn1.encode(Boolean.TRUE);-
- The following ASN.1 notation can be used to define a tagged type: -
---++ ASN.1 Tagged Types +
++ The following ASN.1 notation can be used to define a tagged type: +
+MyTaggedType ::= [APPLICATION 0] EXPLICIT BOOLEAN;-
- By default, a tagged type, MyTaggedType, is mapped to the
- same Java* type as a basic type, see ASN.1
- BOOLEAN above.
-
- Then the following code can be used to decode and encode the values of - this type: -
---++ By default, a tagged type,
+MyTaggedType, is mapped to the same Java* type as a basic type, see ASN.1BOOLEANabove. ++ Then the following code can be used to decode and encode the values of this type: +
+// represents encoded explicitly tagged ASN.1 Boolean type: false value byte encoding[] = new byte[] {0x60, 0x03, 0x01, 0x01, 0x00}; @@ -1232,33 +1063,27 @@ // an array value equals to {0x60, 0x03,0x01, 0x01, 0xFF} byte enc[] = asn1.encode(Boolean.TRUE);-
- A constructed ASN.1 type notation can go as follows. -
---++ ASN.1 Sequence Type +
++ A constructed ASN.1 type notation can go as follows. +
+MyConstructedType ::= SEQUENCE { classVersion INTEGER, isExtendable BOOLEAN DEFAULT FALSE }-
- By default, a sequence type is mapped to an array of objects. In the
- example, it is an array of two objects: the first object represents
- classVersion and the second object represents the
- isExtendable flag.
-
- The following code can be used to decode and encode the values of this - type: -
---++ By default, a sequence type is mapped to an array of objects. In the example, it + is an array of two objects: the first object represents
+classVersion+ and the second object represents theisExtendableflag. ++ The following code can be used to decode and encode the values of this type: +
+// create an instance custom decoder/encoder ASN1Type asn1 = new ASN1Sequence(new ASN1Type[] {ASN1Integer.getInstance(), // classVersion @@ -1281,14 +1106,12 @@ // second value (ASN.1 Boolean) is mapped by default to a Boolean object Boolean isCritical = (Boolean)value[1];-
- When it is necessary to change the default mapping of an array of
- objects for the ASN.1 Sequence type to a custom Java* class, two methods are overridden.
-
--++ When it is necessary to change the default mapping of an array of objects for the + ASN.1
+Sequencetype to a custom Java* class, two methods + are overridden. +// class for storing MyConstructedType values class A { int version; @@ -1343,67 +1166,54 @@ a2.isExtendable = true; byte enc[] = asn1.encode(a);-
- Back to Top -
-- [1] Java API - Specification, http://java.sun.com/j2se/1.5.0/docs/api/ -
-- [2] Abstract Syntax Notation One - (ASN.1) Specification of Basic Notation ITU-T Rec. X.680 (2002) | - ISO/IEC 8824-1:2002 -
-- [3] Specification of Basic - Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished - Encoding Rules (DER) ITU-T Rec. X.690 (2002) | ISO/IEC 8825-1:2002 -
-- [4] ASN.1 Information Site, http://asn1.elibel.tm.fr/en/standards/index.htm -
-- [5] A Layman's Guide - to a Subset of ASN.1, BER, and DER, http://luca.ntop.org/Teaching/Appunti/asn1.html -
-- [6] Olivier Dubuisson, translated by - Philippe Fouquart, ASN.1 - Communication between heterogeneous - systems, http://www.oss.com/asn1/dubuisson.html -
-- [7] Professor John Larmouth, - ASN.1 Complete, http://www.oss.com/asn1/larmouth.html -
-- [8] The Internet Engineering Task Force, - Requests for Comments, http://www.ietf.org/ -
-- Back to Top -
- -- * Other brands and names are the property of - their respective owners. -
- ++ Back to Top +
++ [1] Java API Specification, http://java.sun.com/j2se/1.5.0/docs/api/ +
++ [2] Abstract Syntax Notation One (ASN.1) Specification + of Basic Notation ITU-T Rec. X.680 (2002) | ISO/IEC 8824-1:2002 +
++ [3] Specification of Basic Encoding Rules + (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) ITU-T + Rec. X.690 (2002) | ISO/IEC 8825-1:2002 +
++ [4] ASN.1 Information Site, http://asn1.elibel.tm.fr/en/standards/index.htm +
++ [5] A Layman's Guide to a Subset of + ASN.1, BER, and DER, http://luca.ntop.org/Teaching/Appunti/asn1.html +
++ [6] Olivier Dubuisson, translated by Philippe Fouquart, + ASN.1 - Communication between heterogeneous systems, http://www.oss.com/asn1/dubuisson.html +
++ [7] Professor John Larmouth, ASN.1 Complete, + http://www.oss.com/asn1/larmouth.html +
++ [8] The Internet Engineering Task Force, Requests for + Comments, http://www.ietf.org/ +
++ Back to Top +
++ * Other brands and names are the property of their respective + owners. +
+ - - - Index: xdocs/subcomponents/classlibrary/compat.xml =================================================================== --- xdocs/subcomponents/classlibrary/compat.xml (revision 517589) +++ xdocs/subcomponents/classlibrary/compat.xml (working copy) @@ -3,11 +3,11 @@ - - + -- This document gives practical instructions on how to debug - the DRL virtual machine and its baseline just-in-time - compiler Jitrino.JET. For a definition of components and - details on their internal structure, consult the DRL - Virtual Machine Developer’s Guide supplied with - the DRLVM image. -
-- The document includes two groups of debugging tips, one for - VM tips, and the other for JIT compiler tips, as shown - below. -
- -- Debugging the Virtual Machine -
--++
Debugging DRL Virtual Machine and JIT Compiler + + ++ Debugging the DRL Virtual Machine and the JIT Compiler +
++ This document gives practical instructions on how to debug the DRL virtual machine + and its baseline just-in-time compiler Jitrino.JET. For a definition of components + and details on their internal structure, consult the + DRL Virtual Machine Developer’s Guide supplied with the DRLVM image. +
++ The document includes two groups of debugging tips, one for VM tips, and the other + for JIT compiler tips, as shown below. +
++ Debugging the Virtual Machine +
++ - --- Debugging the Jitrino.JET Baseline - Compiler -
--- -- How to enable tracing in - Jitrino.JET? -
- - -- Back to top -
-- Debugging the Virtual Machine -
-- This section gives an insight into debugging the DRL virtual - machine version 1.0 and provides tips on resolving - non-standard debugging issues. -
-- How to debug the VM? -
-- This section gives instructions on different scenarios of - debugging the VM source code. -
-- Basic Debugging Steps -
-- For ordinary tests, start the ij executable with the - debugger enabled, as follows: -
-- On Windows* -
--
-- - Start Microsoft Visual Studio* and open - the solution file
-vm\build\vm.sln. -- - Open the source code that you need to debug, set - breakpoints and perform all other preliminary steps. -
-- - Select the vmcore project and open its properties to - specify the location of the
-ijexecutable. - Select the Debugging tab and specify the - command and command arguments. -- - Copy the ZLib tool library
-zlib1.dllto the - location of the VM executable. -- - Start debugging via the menu Debug > - Start, click NO in the - popup dialog offering to build the project. -
-- On Linux* -
--
- - Set up the
LD_LIBRARY_PATHto point to the -deploy/jre/bindirectory. Change the working - directory to the location of the VM executable and run: -+ + +
+ Debugging the Jitrino.JET Baseline Compiler +
++++ How to enable tracing in Jitrino.JET? +
+ + +
+ Back to top +
++ This section gives an insight into debugging the DRL virtual machine version 1.0 + and provides tips on resolving non-standard debugging issues. +
++ This section gives instructions on different scenarios of debugging the VM source + code. +
++ For ordinary tests, start the ij executable with the debugger enabled, as follows: +
++ On Windows*
+
+ vm\build\vm.sln. ij executable. Select the Debugging tab and specify
+ the command and command arguments. zlib1.dll to the location of the VM executable.
+ + On Linux*
+LD_LIBRARY_PATH to point to the deploy/jre/bin
+ directory. Change the working directory to the location of the VM executable and
+ run:
+ gdb ij-
+
run <your_params>-
- Back to top -
-- To attach to the running VM process, do the following: -
-- On Windows* -
-- On Linux* -
-- Run: -
-+ + ++ Back to top +
++ Attaching the Debugger to the Live Process +
++ To attach to the running VM process, do the following: +
++ On Windows*
++
+- Start Visual Studio* .
+- Go Debug > Processes.
+- Select the VM process and click Attach.
+
+ If you built the VM in the debug mode, the Microsoft Debug Runtime + window appears. Click the Debug button to go to the crash point. ++ On Linux*
++ Run: +
+gdb –p <PID of ij>-- If the VM crashed during execution, use the core dump to - analyze the crash: -
-++ If the VM crashed during execution, use the core dump to analyze the crash: +
+gdb ij core-- Back to top -
-- How to get more from your - debugging? -
-- This section includes some tips on optimizing the debug - process and getting more debug information. -
-- Configuration of tracing -
-- Consult the Getting Started guide delivered with - DRLVM bundle for information on VM standard and non-standard - configuration options. Tracing-related options might be - useful for debugging purposes. -
-- Native stack examination -
-- The debugger might draw the stack incorrectly when the JIT - or native stubs are involved. To avoid this, set esp as the - memory location and 4-byte integer values as the output - format. As a result, you can examine the stack word by word - and look into the code for each number 0x00… by using - the Disassembly window. -
---- When the VM has crashed -
-- A very specific case on Windows*: the VM - has crashed and you only see the stack frame in the call - stack
-0x00000000. This means that the - program has jumped or called to a null pointer. -- You might still get the stack trace. For that, do the - following: -
--
-- - Open the Disassembly window. -
-- - Find any ret instruction with no parameters in the - memory space.
-
- Open any source file, open the context menu, and - select Go to - Disassembly to find any -retinstruction. -- - When found, select the ret instruction and click - Set Next Statement in the context - menu. -
-- - Type
-F11to go a single instruction.
- You may see several instructions near the current - point of execution. If you see a call instruction, you - have found an appropriate call site and you can see - the call stack in the Call Stack - window. If you have found a wrong call site, repeat - the instruction from step 2. -- Back to top -
-- Java* stack examination -
-- On Windows* -
-- Running the VM in the interpreter mode, you can get Java* methods stack trace almost at any point of - execution. For that, break the execution of the VM and - select the Interpreter frame in the Visual - Studio* Call Stack window. - Then, in the watch window, add the watch -
-stack_dump(). The stack dump appears in VM - output window. Running the VM in the JIT mode, use the -st_print()function for the same purpose. -- On Linux* -
-- Use the
-gdbcommand print and specify the -stack_dumporst_printin the - interpreter or the JIT compiler mode respectively. -- Setting smart breakpoints -
-- On Windows* / IA-32 -
-- Place breakpoints in source code by inserting calls to the - _CrtDbgBreak() function. Placing the call inside a condition - calls the function only for the specified case you need to - debug. Analogously, you can use the Windows* API function DebugBreak() or print INT 3. -
-- Note
-
- This requires recompiling the VM. -- On Linux* -
-- Run the following: -
-++ Back to top +
++ How to get more from your debugging? +
++ This section includes some tips on optimizing the debug process and getting more + debug information. +
++ Configuration of tracing +
++ Consult the Getting Started + guide delivered with DRLVM bundle for information on VM standard and non-standard + configuration options. Tracing-related options might be useful for debugging purposes. +
++ Native stack examination +
++ The debugger might draw the stack incorrectly when the JIT or native stubs are involved. + To avoid this, set esp as the memory location and 4-byte integer values as the output + format. As a result, you can examine the stack word by word and look into the code + for each number 0x00… by using the Disassembly window. +
++ When the VM has crashed +
++ A very specific case on Windows*: the VM has crashed and you only + see the stack frame in the call stack
+0x00000000. This means that the + program has jumped or called to a null pointer. ++ You might still get the stack trace. For that, do the following: +
++
+- Open the Disassembly window.
+- Find any ret instruction with no parameters in the memory space.
+
+ Open any source file, open the context menu, and select Go to + Disassembly to find anyretinstruction.- When found, select the ret instruction and click Set Next Statement + in the context menu.
+- Type
+F11to go a single instruction.
+ You may see several instructions near the current point of execution. If you see + a call instruction, you have found an appropriate call site and you can see the + call stack in the Call Stack window. If you have found a wrong + call site, repeat the instruction from step 2.+ Back to top +
++ Java* stack examination +
++ On Windows*
++ Running the VM in the interpreter mode, you can get Java* methods + stack trace almost at any point of execution. For that, break the execution of the + VM and select the Interpreter frame in the Visual Studio* + Call Stack window. Then, in the watch window, add the watch
+stack_dump(). + The stack dump appears in VM output window. Running the VM in the JIT mode, use + thest_print()function for the same purpose. ++ On Linux*
++ Use the
+gdbcommand print and specify thestack_dumpor +st_printin the interpreter or the JIT compiler mode respectively. ++ Setting smart breakpoints +
++ On Windows* / IA-32
++ Place breakpoints in source code by inserting calls to the
+_CrtDbgBreak()+ function. Placing the call inside a condition calls the function only for the specified + case you need to debug. Analogously, you can use the Windows* API + functionDebugBreak()or printINT 3. ++ Note
++ This requires recompiling the VM.
++ On Linux*
++ Run the following: +
+__asm {int 3}-- Back to top -
-- Handling Java* threads as native threads -
-- DRL VM has 1:1 mapping between native threads visible in the - debugger and Java* threads.
-
- To work with Java* threads individually, - freeze the threads you do not need with the help of the - debugger, and continue execution of other threads. -- Debugging deadlocks with the CriticalSection synchronization - primitive -
-- The
-CriticalSectionprimitive is a common cause - of deadlocks. If the code has stopped at a critical section, - you can try to find the thread that owns this primitive. -- On Windows* -
-- The file WinNT.H located in <PlatformSDK>\Include - contains the definition for the structure - _RTL_CRITICAL_SECTION, which contains the description of the - CriticalSection primitive. You can get the owning thread for - the CriticalSection primitive in a number of ways, as - indicated below. -
---- Lookup in Memory -
-- On Windows* -
-- While debugging the code in Visual Studio, do the - following: -
--
-- - Go Debug > - Windows > Memory - 1. -
-- - In the address line, enter the address of the critical - section. -
-- - Open the context menu and select 4-byte Integers. This - sets the fourth DWORD from the beginning of the - critical section as the owning thread ID in - hexadecimal representation. -
-- Note
-
- Visual Studio* displays thread IDs - in decimal representation. -- In the watch window --- In the watch window of Visual Studio*, - insert the following: -
-++ Back to top +
++ Handling Java* threads as native threads +
++ DRL VM has 1:1 mapping between native threads visible in the debugger and Java* threads.
+
+ To work with Java* threads individually, freeze the threads you + do not need with the help of the debugger, and continue execution of other threads. ++ Debugging deadlocks with the CriticalSection synchronization primitive +
++ The
+CriticalSectionprimitive is a common cause of deadlocks. If the + code has stopped at a critical section, you can try to find the thread that owns + this primitive. ++ On Windows*
++ The file
+WinNT.Hlocated in<PlatformSDK>\Include+ contains the definition for the structure_RTL_CRITICAL_SECTION, which + contains the description of the CriticalSection primitive. You can get the owning + thread for the CriticalSection primitive in a number of ways, as indicated below. ++ Lookup in Memory
++ While debugging the code in Visual Studio, do the following: +
++
+- Go Debug > Windows > Memory 1. +
+- In the address line, enter the address of the critical section.
+- Open the context menu and select 4-byte Integers. This sets the fourth DWORD from + the beginning of the critical section as the owning thread ID in hexadecimal representation. +
++ Note
++ Visual Studio* displays thread IDs in decimal representation.
++ In the watch window
++ In the watch window of Visual Studio*, insert the following: +
+* ((int* )<cs-ptr>+3)-- Where
-<cs-ptr>is the address of your - critical section -- On Linux* -
-- The file
-/usr/include/bits/pthreadtypes.h- contains the description of thepthread_mutex_t- type. To get the ID of the thread owning the -CriticalSectionprimitive, in gdb execute: -++ Where
+<cs-ptr>is the address of your critical section ++ On Linux*
++ The file
+/usr/include/bits/pthreadtypes.hcontains the description + of thepthread_mutex_ttype. To get the ID of the thread owning the +CriticalSectionprimitive, ingdbexecute: +x/4w <address of your mutex primitive>-- The third word in the output contains the owning thread - descriptor you are looking for. -
-- Getting a class name for an object -
-- You can often need to find out the class name for a Java* object used in VM code. For example, you may - need to get the class name for an object of the type -
-ManagedObject *(which is a direct pointer to - the heap). For that, insert the following expression into - the watch window in Visual Studio on Windows* or print the command ofgdbon - Linux* : -((VTable*)(*((int - *)obj)))->clss->name->bytes-- Variables of the types jobject and -
-Object_Handleare references to -ManagedObject *types. These structures contain - a single element, a pointer toManagedObject *- type object. To use the expression above, de-reference the - variable, for example, substitutingobjin the - expression above with a cast to(ManagedObject - *)(*(int *)obj). -- Back to top -
-- Debugging the Jitrino.JET - Baseline Compiler -
-- To use debugging and tracing in Jitrino.JET, use the debug - build or the release build with the
-JET_PROTO- macro defined. See the filejdefs.hfor a - definition of the available flags. -- How to enable tracing in - Jitrino.JET? -
-- Currently, Jitrino.JET provides no interface or command line - to control tracing options. To enable tracing, set the -
-compile_flagsvariable at the entry point to - the methodCompiler::compile(). At that point, - the global variableCompiler::g_methodsSeen- contains the ID of the method being compiled, and the - instance variablem_fnamecontains its fully - qualified name with no signature. Obtain these options - through a call to -Compiler::m_infoBlock.get_flags(). -- How to configure trace - logging? -
-- Tracing flags control compilation results output and trace - run-time execution, as described below. Tracing results are - created in each run in the directory where the -
-ijexecutable starts: compilation results are - injet.log, and run-time output is in -jet.rt.log. -- Group 1: Compilation Results Tracing -
-- The following flags control tracing compilation of a method: -
-
DBG_TRACE_SUMM prints a
- short summary about the compiled method: the compilation
- status (success or failure), the name, signature,
- bytecode size, the start and end addresses of the
- generated code, and the compilation ID (the sequential
- number of the method compiled by Jitrino.JET).
- DBG_DUMP_BBS dumps the
- bytecode and marks up basic blocks boundaries.
- DBG_TRACE_CG prints
- information about each compiled bytecode instruction: the
- state of the Java* operand stack before
- the instruction, the known state of local variables at
- the given point, and the native code generated for the
- instruction. The order instructions appear in the log
- file is the depth-first order, the same as when
- processing instructions during compilation. See the file
- trace.cpp, function toStr2() for the legend
- of the operand stack items print-out.
- DBG_TRACE_LAYOUT prints the
- results of the code layout, mostly, the address ranges
- for the basic blocks.
- DBG_DUMP_CODE dumps
- generated code for the given method, the method’s
- actual addresses, intermixed with appropriate bytecode
- instructions.
-
- Note
- For DBG_DUMP_CODE and
- DBG_TRACE_CG, Jitrino.JET can print
- disassembled code in addition to raw hexadecimal
- dumps. For that, the compiler requires an external
- disassembler. Currently, Jitrino.JET is configured to
- use the external library
- lwdis.dll/liblwdis.so that must be
- located in the same directory as
- jitrino.dll/libjitrino.so. The name lwdis
- stands for light weight disassembler. The library must
- export the function disasm(). Refer to
- the file trace.cpp, the DISFUNC
- definition for details on calling convention and
- signature.
+
+ The third word in the output contains the owning thread descriptor you are looking + for. +
+
+ You can often need to find out the class name for a Java* object
+ used in VM code. For example, you may need to get the class name for an object of
+ the type ManagedObject * (which is a direct pointer to the heap). For
+ that, insert the following expression into the watch window in Visual Studio on
+ Windows* or print the command of gdb on Linux*
+ :
+
((VTable*)(*((int*)obj)))->clss->name->bytes+
+ Variables of the types jobject and Object_Handle are references to
+ ManagedObject * types. These structures contain a single element, a
+ pointer to ManagedObject * type object. To use the expression above,
+ de-reference the variable, for example, substituting obj in the expression
+ above with a cast to (ManagedObject *)(*(int *)obj).
+
+ Back to top +
+
+ To use debugging and tracing in Jitrino.JET, use the debug build or the release
+ build with the JET_PROTO macro defined. See the file jdefs.h
+ for a definition of the available flags.
+
+ Currently, Jitrino.JET provides no interface or command line to control tracing
+ options. To enable tracing, set the compile_flags variable at the entry
+ point to the method Compiler::compile(). At that point, the global
+ variable Compiler::g_methodsSeen contains the ID of the method being
+ compiled, and the instance variable m_fname contains its fully qualified
+ name with no signature. Obtain these options through a call to Compiler::m_infoBlock.get_flags().
+
+ Tracing flags control compilation results output and trace run-time execution, as
+ described below. Tracing results are created in each run in the directory where
+ the ij executable starts: compilation results are in jet.log,
+ and run-time output is in jet.rt.log.
+
+ The following flags control tracing compilation of a method: +
+DBG_TRACE_SUMM prints a short summary about the compiled
+ method: the compilation status (success or failure), the name, signature, bytecode
+ size, the start and end addresses of the generated code, and the compilation ID
+ (the sequential number of the method compiled by Jitrino.JET). DBG_DUMP_BBS dumps the bytecode and marks up basic
+ blocks boundaries. DBG_TRACE_CG prints information about each compiled
+ bytecode instruction: the state of the Java* operand stack before
+ the instruction, the known state of local variables at the given point, and the
+ native code generated for the instruction. The order instructions appear in the
+ log file is the depth-first order, the same as when processing instructions during
+ compilation. See the file trace.cpp, function toStr2() for the legend
+ of the operand stack items print-out. DBG_TRACE_LAYOUT prints the results of the code layout,
+ mostly, the address ranges for the basic blocks. DBG_DUMP_CODE dumps generated code for the given method,
+ the method’s actual addresses, intermixed with appropriate bytecode instructions.
+ + Note
+
+ For DBG_DUMP_CODE and DBG_TRACE_CG, Jitrino.JET can print
+ disassembled code in addition to raw hexadecimal dumps. For that, the compiler requires
+ an external disassembler. Currently, Jitrino.JET is configured to use the external
+ library lwdis.dll/liblwdis.so that must be located in the same directory
+ as jitrino.dll/libjitrino.so. The name lwdis stands for light weight
+ disassembler. The library must export the function disasm(). Refer
+ to the file trace.cpp, the DISFUNC definition for details on calling
+ convention and signature.
DBG_CHECK_STACK prints
- nothing but instruments code to check stack integrity.
- The methods compiled by Jitrino.JET use EBP-based frames.
- These frames can mask errors, for example, wrong
- convention usage with a VM helper call. Using this option
- performs run-time checks and INT3 raised in case the
- stack integrity broken.
- DBG_BRK inserts INT3 at the
- method entry point, so it can be stopped in the debugger.
-
-
- Note
- An instance variable of class
- Compiler, dbg_break_pc can
- be used to insert INT3 at the specified
- program counter of a method.
+
DBG_CHECK_STACK prints nothing but instruments code
+ to check stack integrity. The methods compiled by Jitrino.JET use EBP-based frames.
+ These frames can mask errors, for example, wrong convention usage with a VM helper
+ call. Using this option performs run-time checks and INT3 raised in case the stack
+ integrity broken. DBG_BRK inserts INT3 at the method entry point, so
+ it can be stopped in the debugger.
+ + Note
+
+ An instance variable of class Compiler, dbg_break_pc can
+ be used to insert INT3 at the specified program counter of a method.
- Back to top -
-- The following flags trace run-time life of the method: -
-DBG_TRACE_EE prints
- entering: <method-name> and exiting:
- <method-name> at the method entrance
- and exit points.+ Back to top +
++ The following flags trace run-time life of the method: +
+DBG_TRACE_EE prints entering: <method-name>
+ and exiting: <method-name> at the method entrance and exit points.DBG_TRACE_BC traces
- execution of every bytecode instruction by printing a
- string of the following format before executing the
- instruction: <method-name> @
- PC=<pc>DBG_TRACE_BC traces execution of every bytecode instruction
+ by printing a string of the following format before executing the instruction:
+ <method-name> @ PC=<pc>- Notes -
-
- The output string for DBG_TRACE_EE and
- DBG_TRACE_BC uses a specific format: before the
- string, an estimated call depth is printed and the string
- gets indentation based on the call depth. After the string,
- the string ID is printed. The estimated call depth may help
- to identify where a method was called from. The string ID
- can be helpful for setting a conditional breakpoint in the
- debugger for a complex scenario. For that, set a condition
- for the static variable cnt in the function
- rt_dbg, file trace.cpp.
-
- Turning on the option DBG_TRACE_BC may slow
- down execution extremely and may result to a gigantic file
- jet.rt.log.
-
DBG_TRACE_RT traces
- run-time support calls, for example, getting address of
- ‘this’, support for root set enumeration and
- stack unwinding.+ Notes
+
+ The output string for DBG_TRACE_EE and DBG_TRACE_BC uses
+ a specific format: before the string, an estimated call depth is printed and the
+ string gets indentation based on the call depth. After the string, the string ID
+ is printed. The estimated call depth may help to identify where a method was called
+ from. The string ID can be helpful for setting a conditional breakpoint in the debugger
+ for a complex scenario. For that, set a condition for the static variable cnt in
+ the function rt_dbg, file trace.cpp.
+ Turning on the option DBG_TRACE_BC may slow down execution extremely
+ and may result to a gigantic file jet.rt.log.
+
DBG_TRACE_RT traces run-time support calls, for example,
+ getting address of ‘this’, support for root set enumeration and stack
+ unwinding.
- Note
- The output goes to jet.log, with the address (both
- native and PC) where the event happens, and some other info.
-
- Back to top -
-- To identify one or more problematic methods with another - stable JIT compiler, use the execution manager. With this - technique, some methods are compiled by the stable JIT, and - the rest goes to the JIT being debugged. With a simple - binary search, you can find the problematic method rather - quickly. -
-
- Note
- Try turning off parallel compilation when using this
- technique (refer to VM’s
- -Xno_parallel_jit option).
-
- To get details in case of a crash with no adequate - stack trace or IP location available, turn on the option - DBG_TRACE_EE to see, in which method the crash happens. As - the second step, turn on DBG_TRACE_BC for this particular - method to find the exact bytecode instruction. Often, this - cuts the code to analyze down to 5-10 native instructions. -
-- To set a breakpoint and stop execution at a specific - point, use trace.cpp:rt_dbg to break execution at the - specified bytecode instruction or at the entry point of the - specified method. -
-- Back to top -
-
- This is an example of code that turns on various tracing
- scenarios. The code must be placed in the method
- Compiler::compile().
-
- #if defined(_DEBUG) || defined(JET_PROTO) -
-- // - Turns on a short summary of all methods -
-- compile_flags |= DBG_TRACE_SUMM; -
-- // A - handy constant -
-- static const unsigned TRACE_CG = DBG_DUMP_BBS | DBG_TRACE_CG | -
-- DBG_TRACE_LAYOUT - | DBG_TRACE_SUMM | -
-- DBG_DUMP_CODE; -
-- // For - methods in the range (1000;15000), print out the complete - code generator dumps -
-- if (g_methodsSeen>1000 && g_methodsSeen<15000) { -
-- compile_flags |= TRACE_CG; -
-- } -
-- // For - methods getSomeValue() and for all methods in class - MyClass, -
-- // - trace enter and exit -
-- if (NULL != strstr(m_fname, "::getSomeValue") || -
-- NULL != strstr(m_fname, "MyClass::") ) { -
-- compile_flags |= DBG_TRACE_EE; -
-- } -
-- // For - the method crashes_some_times() in class MyClass trace - every -
-- // - bytecode execution: the last bytecode in the log is the most - probable -
-- // - cause of the failure -
-- if (!strcmp(m_fname, - "MyClass::crashes_some_times")) { -
-- compile_flags |= DBG_TRACE_EE|DBG_TRACE_BC; -
-- } -
-- // - Break into debugger (INT3) at the entry of the - stop_at_entry() method -
-- if (!strcmp(m_fname, "MyClass::stop_at_entry")) - { -
-- compile_flags |= DBG_BRK; -
-- } -
-- // - Break into debugger (INT3) inside the method -
-- if (!strcmp(m_fname, - "MyClass::stop_somewhere_in_the_middle")) { -
-- dbg_break_pc = 50; -
-- } -
-- // - Trace run-time support calls: unwind, getting the address of - 'this', root -
-- // set - enumeration -
-- if (!strcmp(m_fname, - "MyClass::something_wrong_with_unwind_here")) { -
-- compile_flags |= DBG_TRACE_RT; -
-- } -
-- // - By-pass run-time tracing for java/* classes -
-- if (m_fname == strstr(m_fname, "java/")) { -
-- compile_flags &= ~(DBG_TRACE_EE|DBG_TRACE_BC); -
-- } -
-- #endif -
- -- Back to top -
-- * Other brands and names are the property of - their respective owners. -
- ++ Note
++ The output goes to jet.log, with the address (both native and PC) where the event + happens, and some other info. +
++ Back to top +
++ To identify one or more problematic methods with another stable JIT compiler, use + the execution manager. With this technique, some methods are compiled by the stable + JIT, and the rest goes to the JIT being debugged. With a simple binary search, you + can find the problematic method rather quickly. +
++ Note
+
+ Try turning off parallel compilation when using this technique (refer to VM’s
+ -Xno_parallel_jit option).
+
+ To get details in case of a crash with no adequate stack trace or IP location
+ available, turn on the option DBG_TRACE_EE to see, in which method
+ the crash happens. As the second step, turn on DBG_TRACE_BC for this
+ particular method to find the exact bytecode instruction. Often, this cuts the code
+ to analyze down to 5-10 native instructions.
+
+ To set a breakpoint and stop execution at a specific point, use trace.cpp:rt_dbg
+ to break execution at the specified bytecode instruction or at the entry point of
+ the specified method.
+
+ Back to top +
+
+ This is an example of code that turns on various tracing scenarios. The code must
+ be placed in the method Compiler::compile().
+
+ #if + + defined(_DEBUG) || + defined(JET_PROTO) +
++ + // Turns on a short summary of all methods +
++ + compile_flags |= DBG_TRACE_SUMM; +
++ + // A handy constant +
++ + static const unsigned + TRACE_CG = DBG_DUMP_BBS + | DBG_TRACE_CG | +
++ + DBG_TRACE_LAYOUT | DBG_TRACE_SUMM | +
++ + DBG_DUMP_CODE; +
++ + // For methods in the range (1000;15000), print out the complete code generator + dumps +
++ + if (g_methodsSeen>1000 && + g_methodsSeen<15000) { +
++ + compile_flags |= TRACE_CG; +
++ } +
++ + // For methods getSomeValue() and for all methods in class MyClass, +
++ + // trace enter and exit +
++ + if (NULL != + strstr(m_fname, "::getSomeValue") + || +
++ + NULL != strstr(m_fname, + "MyClass::") ) { +
++ + compile_flags |= DBG_TRACE_EE; +
++ } +
++ + // For the method crashes_some_times() in class MyClass trace every +
++ + // bytecode execution: the last bytecode in the log is the most probable +
++ + // cause of the failure +
++ + if (!strcmp(m_fname, + "MyClass::crashes_some_times")) { +
++ + compile_flags |= DBG_TRACE_EE|DBG_TRACE_BC; +
++ } +
++ + // Break into debugger (INT3) at the entry of the stop_at_entry() method +
++ + if (!strcmp(m_fname, + "MyClass::stop_at_entry")) { +
++ + compile_flags |= DBG_BRK; +
++ } +
++ + // Break into debugger (INT3) inside the method +
++ + if (!strcmp(m_fname, + "MyClass::stop_somewhere_in_the_middle")) { +
++ + dbg_break_pc = 50; +
++ } +
++ + // Trace run-time support calls: unwind, getting the address of 'this', root +
++ + // set enumeration +
++ + if (!strcmp(m_fname, + "MyClass::something_wrong_with_unwind_here")) { +
++ + compile_flags |= DBG_TRACE_RT; +
++ } +
++ + // By-pass run-time tracing for java/* classes +
++ + if (m_fname == + strstr(m_fname, "java/")) { +
++ + compile_flags &= ~(DBG_TRACE_EE|DBG_TRACE_BC); +
++ } +
++ #endif +
++ Back to top +
++ * Other brands and names are the property of their respective owners. +
+