Assemble a native ARMv8 library, and call Android Java methods from its procedures invoked by an Android App, using the JNI conventions.


This document demonstrates how to :

  • write functions (procedures), using the ARMv8 64-bit Gnu AS syntax, that will use the JNI library to call back Java functions from the Android app that called them
  • assemble these procedures into a native library, using the GNU Gold linker
  • write the code of the Android app that will call these native functions, and define the Java methods that will be called by the native functions called.

What will happen is that :

  • The Android app will be executed on an ARMv8 Android Phone/Tablet/Emulator
  • The Android app will call a native function in the native libraries we assembled.
  • The native function will build an UTF-16 Java String object, using the content defined inside the native library assembly script.
  • The native function will call back an Android app function, using the JNI library, and pass the UTF-16 String.
  • The Android app will then display the provided String on the screen.
  • The Android app function will then return.
  • The native function will also return.
  • And then the Android app will be left with the message on the screen, as long as it is running.


The terms procedure and functions have the same meaning in this document. They are considered to be parameterized series of executable instructions. The term symbols refer to names stored in the libraries. If you create a library with a function named my_function or my_procedure, the library will contain the symbol my_function or my_procedure.

We assume that Android executes “Java” code, even if it’s not technically the case, since the same JNI conventions and the libraries are used.


This document assumes that :

  • You know how to create and install a basic Android application, either manually (gradlew) or with tools like Android Studio.
  • You know how to invoke a shell, or a command prompt, in a specific directory and execute commands in this shell or command prompt.
  • You have basic Java knowledge.


In order to assemble the library and install the Android Application, you will need :

  • An Android SDK (Required by the Android application)
  • A cross-assembling GNU Sourceware AS that can interpret ARMv8 assembly and output ARMv8 machine code. (Required to generate the objects files from the assembly listings)
  • A cross-linking Gnu GOLD able to generate ARMv8 shared libraries. (Required to generate the native shared library)
  • An ARMv8 64-bits Android phone, tablet or emulator. (Required to run and test the produced application)

All the code written in this document is also on the following Git repository :


Calling Conventions

Native code calling conventions : ARMv8-A Application Procedure Call Standard

Now, in order make the logic of the following code clearer, I’ll restate some parts of the ARMv8-A 64 bits Application Procedure Call Standard (AAPCS), which is a convention that is followed by every compiler and manual assembler, to produce procedures in order that can cooperate smoothly. This document can be read here :

x0..x7 means all the registers between x0 and x7, that is x0, x1, x2, x3, x4, x5, x6 and x7.

When following the AAPCS :

  • Procedures (aka functions) arguments are first passed in x0..x7. This means that you can pass up to 8 arguments through registers.
  • Procedures can return up to 8 values through the same registers, x0..x7. This means that these registers can and will often be overwritten by the procedures you call, in order to return values.
  • Procedures can use the registers x9..x15 to store temporary values, without second thought. This means that these registers can and will also be overwritten by the procedures you call.
  • Procedures must backup the registers between x19..x28 before overwriting their content. This means that these registers should be kept intact by the procedures you call.

So, if we need to save an argument for later use, x19..x28 is our best bet.

  • The content of x9..x15 will require a push/pop in the stack on every sub-procedure call, or else we might loose their contents.
  • We could also directly push/pop x0..x7 on every sub-procedure call, when we need to save/load their content again.
  • However x19..x28 only require one push/pop operation in an entire procedure, since every sub-procedure will save their contents by convention.

Java to Native code convention : Java Native Interface

Now, when trying to call native function from Java, in order to find the address of the native function to execute, the “JVM” will search in the loaded libraries, a symbol formed like this :

So, for example, here :

  • our Package name is adventurers.decyphering.secrets.decyphapp
  • our Class name is DecypherActivity
  • our native function name is decypherArcaneSecrets

So the symbol looked up will be Java_adventurers_decyphering_secrets_decyphapp_DecypherActivity_decypherArcaneSecrets

  • The first two arguments that a native function will always receive are :
    • x0 ← The address of an address of a _JNIEnv structure, a.k.a. **JNINativeInterface or *JNIEnv in C.
      This *JNIEnv is passed as argument to almost every function provided through the JNINativeInterface structure, so we need to keep it until we’re done with the JNI functions.
    • (x1) ← A reference to the object instance calling this native method. We will use it to get a Method object, representing the method defined in the Android app to display the Java String built.

Native to Java method call convention : Java Native Interface

When looking for methods, using the native JNI library helpers, you will need to provide the signature of the name of the method, and its signature in the form of a descriptor.

The descriptor states :

  • The list of the method arguments types within parentheses.
  • The return thype.

The types are described using Java internal codes provided below, and also provided in the Java Native Interface documentation :

Java Type Internal Code
void V
boolean Z
byte B
char C
short S
int I
long J
float F
double D
Array [component_type_code
Class Lfully/qualified/name;

So for example, the Descriptor of our Java method void revealTheSecret(String) needs to be written like this (Ljava/lang/String;)V.

Note that the fully qualified name of the Java String object is java.lang.String .
The ; MUST be present, when describing classes
The [ IS NOT MATCHED with a closing bracket.
Generics are ignored. Meaning that Hashtable<String,String> is equivalent to Hashtable
Example : String[] a(Hashtable<String,Object>[]) descriptor is ([Ljava/util/Hashtable;)Ljava/lang/String;

Once you understand these parts, the logic of the following assembly code should be easier to understand.

The example

This example is heavily commented, in order to help people new to ARM Assembly, or the Assembly “language” in general.

So the point of the library assembled in this tutorial is to provide a procedure, that will generate a Java String object containing a specific text defined in the assembly listing. The text itself in encoded in UTF-16. The text contained in this Java String will then be passed to a Java function defined in the Android Application which will display the provided String on the screen, using appropriate Android SDK Widgets.

So, in simple terms, we need to :

  • Generate a Java String using our secret data.
  • Get the method void revealTheSecret(String) from our calling object.
  • Call it with the String we generated.

To do this, we will use the following functions available from _JNIEnv :

The Assembly listing


	.asciz "revealTheSecret"
	.asciz "(Ljava/lang/String;)V"

// Our UTF16-LE encoded secret message
	.hword 55357, 56892, 85, 110, 32, 99, 104, 97, 116, 10
	.hword 55357, 56377, 12495, 12512, 12473, 12479, 12540, 10
	.hword 55357, 56360, 27193, 29066, 10
	.hword 55357, 56445, 65, 110, 32, 97, 108, 105, 101, 110, 10
secret_len = (. - secret) / 2

.align 2
.globl Java_adventurers_decyphering_secrets_decyphapp_DecypherActivity_decypherArcaneSecrets
.type Java_adventurers_decyphering_secrets_decyphapp_DecypherActivity_decypherArcaneSecrets, %function
	sub sp, sp, 48 // Prepare to push x19, x20, x21, x22 and lr (x30)
	               // 5 registers of 8 bytes each -> 40 bytes
	               // Unless you like to deal with corner cases, you'll
	               // have to keep the stack aligned on 16 bytes.
	               // 40 % 16 != 0 but 48 % 16 == 0, so we use 48 bytes.
	stp x19, x20, [sp]
	stp x21, x22, [sp, 16]
	stp x23, x30, [sp, 32]

	// Passed parameters - x0 : *_JNIEnv, x1 : thisObject

	mov x19, x0   // x19 <- Backup of *JNIEnv as we'll use it very often
	mov x20, x1   // x20 <- Backup of thisObject as we'll invoke methods on it
	ldr x21, [x0] // x21 <- Backup of *_JNINativeInterface, located at *_JNIEnv,
	              //      since we'll also use it a lot

	/* Preparing to call NewString(*_JNIEnv : x0, 
	                     *string_characters : x1, 
	                          string_length : x2).
	   *_JNIEnv is still in x0.

	adr x1, secret       // x1 <- *secret : The UTF16-LE characters composing 
	                     //                 the java.lang.String we'll pass to
	                     //                 the Java method called afterwards.
	mov x2, #secret_len  // x2 <- secret_len : The length of that java.lang.String
	ldr x3, [x21, #1304] // x3 <- *JNINativeInterface->NewString function. 
	                     // +1304 is NewString's offset in the JNINativeInterface
	                     // structure.
	blr x3               // secret_java_string : x0 <- NewString(*_JNIEnv : x0, 
	                     //                                       *secret : x1,
	                     //                                    secret_len : x2)

	mov x22, x0          // x22 <- secret_java_string
	                     // Keep the returned string for later use

	/* Calling showText(java.lang.String) through the JNI
	   First : We need the class of thisObject. We could pass it directly
	   to the procedure but, for learning purposes, we'll use JNI methods
	   to get it.

	// Preparing to call GetObjectClass(*_JNIEnv : x0, thisObject : x1)
	mov x0, x19         // x0 <- *_JNIEnv (previously saved in x19)
	mov x1, x20         // x1 <- thisObject (previously saved in x20)
	ldr x2, [x21, #248] // x2 <- Get *JNINativeInterface->GetObjectClass (*JNINativeInterface+248)
	blr x2              // jclass : x0 <- GetObjectClass(*JNIEnv : x0, 
	                    //                            thisObject : x1)
	/* Second : We need the JNI ID of the method we want to call
	   Preparing for GetMethodId(*JNIEnv : x0, 
	                              jclass : x1, 
	                         method_name : x2, 
	                    method_signature : x3)

	mov x1, x0  // x1 <- jclass returned by GetObjectClass
	mov x0, x19 // x0 <- *JNIEnv, previously backed up in x19
	adr x2, java_method_name      // x2 <- &java_method_name : The method name
	adr x3, java_method_signature // x3 <- &java_method_signature : The method signature
	ldr x4, [x21, #264]           // Get *JNINativeInterface->GetMethodId (+264)

	blr x4     // revealTheSecretID : x0 <- GetMethodId(*_JNIEnv : x0, 
	           //                                         jclass : x1, 
	           //                                   &method_name : x2, 
	           //                              &method_signature : x3)

	// Finally : Call the method. Since it's a method returning void, 
	// we'll use CallVoidMethod.
	// Preparing to call CallVoidMethod(*_JNIEnv : x0, 
	//                                thisObject : x1,
	//                         revealTheSecretID : x2,
	//                             secret_string : x3)

	mov x2, x0          // x2 <- revealTheSecretID
	mov x1, x20         // x1 <- thisObject (previously saved in x20)
	mov x0, x19         // x0 <- *_JNIEnv (previously saved in x19)
	mov x3, x22         // x3 <- secret_java_string (previously saved in x22)
	ldr x4, [x21, #488] // x4 <- *_JNINativeInterface->CallVoidMethod (+488).
	blr x4 // CallVoidMethod(*_JNIEnv : x0, 
	       //              thisObject : x1,
	       //       revealTheSecretID : x2,
	       //              the_string : x3)
	       // => Java : revealTheSecret(the_string)

	ldp x19, x20, [sp]
	ldp x21, x22, [sp, 16]
	ldp x23, x30, [sp, 32]
	add sp, sp, 48

Then assemble and link this example library :

export PREFIX="aarch64-linux-gnu-"
$PREFIX-as -o decypherArcane.o decypherArcane.S
$ -shared --dynamic-linker=/system/bin/linker --hash-style=sysv -o decypherArcane.o

Calling this from Android

Now that our library is assembled, we’ll just need to create a class that will define :

  • The Java function that display a provided String on the screen, using the Android SDK Widgets.
    This will be the function that will be called by our native procedure, so we need to keep the same name in both the Java code and the native procedure.
  • The name of the native procedure that will be called by the Android App.
  • Load our library containing this native procedure in memory using loadLibrary.
  • Call the native procedure from our App.

So, to do that we’ll generate a project with :

  • the right package name : adventurers.decyphering.secrets.decyphapp
  • an activity named DecypherActivity using this package name defining :
    • a Java method public void revealTheSecret(String text) that will display the provided String, using a TextView here.
    • a native void decypherArcaneSecrets() function.

package adventurers.decyphering.secrets.decyphapp;

import android.os.Bundle;
import android.widget.TextView;

public class DecypherActivity extends AppCompatActivity {

	static { System.loadLibrary("arcane"); }
	native void decypherArcaneSecrets();

	TextView mContentView;

	public void revealTheSecret(String text) {

	protected void onCreate(Bundle savedInstanceState) {


		mContentView = (TextView) findViewById(;

Here’s the XML of the interface used by this Activity


<FrameLayout xmlns:android=""

  <!-- The primary full-screen view. This can be replaced with whatever view
  is needed to present your content, e.g. VideoView, SurfaceView,
  TextureView, etc. -->



Create a directory named jniLibs in $YourProjectRootFolder/app/src/main if it doesn’t exist

Then create a directory named arm64-v8 in it. Once done, the following path should exist :


Copy the previously assembled in that folder.

Then install the app on your phone, using the standard installation procedure. That is, either :

  • ./gradlew installDebug from the root folder of your Android App
  • The Run button of Android Studio

Then run it on your select terminal (phone, tablet, emulator) and you should see something like this :

Screenshot of the running app on a Huawei Honor 9

Special notes

Getting the Descriptor of a Java method

Even with the whole format provided, finding the Descriptor of a method can be difficult at first. Fortunately, there are two ways to handle this issue.

Using javap

One method is to create a simple Java project and define a Java function using the same signature (same return type, same name, same parameters types). Just provide a minimalist useless implementation, compile your project and use javap on the class containing your method, like this :

javap -s your/package/name/Class

For example, if your class :

  • was compiled from a file named
  • contained a function declared like this : void a(int a, long b, String c, HashMap[] d, boolean e)

This should output something like this :

Compiled from ""


    void a(int, long, java.lang.String, java.util.HashMap[], boolean);

        descriptor: (IJLjava/lang/String;[Ljava/util/HashMap;Z)V


Using Java reflect methods

Now, generating sample Java projects (or test files), just to copy-paste a function, compile it and analyse it through javap can be cumbersome. So another way is to simply use Java.lang.reflect methods, from your application, to get the signatures of every declared function in a Class and rebuild the appropriate Descriptor of these methods manually.

Here’s a sample code that help you do that


import java.lang.reflect.Method;
import java.util.HashMap;

import android.util.Log;

public class MethodsHelpers {

  static public HashMap<Class, String> primitive_types_codes;
  static public String LOG_TAG = "MY_APP";

  static {
    primitive_types_codes = new HashMap<Class,String>();
    primitive_types_codes.put(void.class,    "V");
    primitive_types_codes.put(boolean.class, "Z");
    primitive_types_codes.put(byte.class,    "B");
    primitive_types_codes.put(short.class,   "S");
    primitive_types_codes.put(char.class,    "C");
    primitive_types_codes.put(int.class,     "I");
    primitive_types_codes.put(long.class,    "J");
    primitive_types_codes.put(float.class,   "F");
    primitive_types_codes.put(double.class,  "D");

  public static String code_of(final Class class_object) {
    final StringBuilder class_name_builder = new StringBuilder(20);
    Class component_class = class_object;
    while (component_class.isArray()) {
      component_class = component_class.getComponentType();
    if (component_class.isPrimitive())
    else {
        component_class.getCanonicalName().replace(".", "/")
    return class_name_builder.toString();

  public static void print_methods_descriptors_of(Class analysed_class) {
    StringBuilder descriptor_builder = new StringBuilder(32);
    Method[] methods = analysed_class.getDeclaredMethods();
    for (Method meth : methods) {

      for (Class param_class : meth.getParameterTypes())



                          "Name       : %s\n"+
                          "Descriptor : %s\n\n",

      descriptor_builder.delete(0, descriptor_builder.length());


Just use it like this :

import static your_package_name.MethodHelpers.print_methods_descriptors_of;



And then you should see something like on the output :

    D/MY_APP  (22564): void,long,java.lang.String,java.util.HashMap[],boolean)

    D/MY_APP  (22564): Name       : a

    D/MY_APP  (22564): Descriptor : (IJLjava/lang/String;[Ljava/util/HashMap;Z)V

How to write a native library in ARMv7 assembly, call it from an Android Activity and get back a Java byte[] array

Here’s a little demonstration about how to assemble a native library, written in the GNU flavor of the ARMv7 assembly, that will be called through the Java Native Interface, using an Android project as an example.

The procedure will return a Java byte[] array object containing the content of a static string, defined in the library.

In most cases, C/C++ will do a far better job. However, for the record, this document provide informations about how to do that without a C compiler (You’ll still need an ARMv7 assembler, though…).

This document complements Assemble a native ARMv7 library, and call Android Java methods from its procedures invoked by an Android App, using the JNI conventions.

The example

Coding the library

This example is heavily commented as I wrote it while learning assembly. This should provide a clear understanding of this example for people new to ARM Assembly.

If you’re a professional, you might find it more comfortable to strip the comments with the editor of your choice.



  .ascii  "A wild Assembly appears !\n"
msg_len = . - msg

.align 2
.globl Java_your_pack_testactivity_TestActivity_testMe
.type Java_your_pack_testactivity_TestActivity_testMe, %function
  stmfd sp!, {r4-r6, lr} // Prologue. We will use r4 and r6. Is push more useful than stmfd ?
  // Useful passed parameters - r0 : *_JNIEnv
  mov r4, r0 // Save *_JNIEnv for the second method

  // Preparing to call NewByteArray(*_JNIEnv : r0, size_of_array : r1). *_JNIEnv is already loaded.
  mov r1, #msg_len   // r1 : size_of_array = msg_len
  ldr r5, [r0]       // Getting NewByteArray : Get *JNINativeInterface from *_JNIEnv. *JNINativeInterface is preserved for later use.
  ldr r3, [r5, #704] // Get *JNINativeInterface->NewByteArray. +704 is NewByteArray 's offset
  blx r3             // r0 : *bytearray <- NewByteArray(*_JNIEnv : r0, size_of_array : r1)
  mov r6, r0         // We need to keep *bytearray elsewhere as it will be returned by our procedure. r0 is needed for *_JNIEnv

  /* Note : Calculting offset in a structure containing only function pointers is equivalent to :
     Number of functions pointers declared before the desired function pointer * Size in bytes of a function address (4 in 32-bit)
     Preparing to call *JNativeInteface->SetByteArrayRegion(*_JNIEnv : r0, *bytearray r1, 0 : r2, int bytes_to_copy : r3, *from : sp) */

  mov r1, r0         // r1 : *bytearray - The return value of NewByteArray
  mov r0, r4         // r0 : *_JNIEnv - Previously saved in r4
  mov r2, #0         // r2 : 0 - Define the starting index for the array-copy procedure of SetByteArrayRegion
  mov r3, #msg_len   // r3 : bytes_to_copy = msg_len
  sub sp, sp, #4     // Preparing the stack in which we'll store the address of msg
  ldr r4, =msg       // We won't need our previous copy of *_JNIEnv anymore, so we replace it by *msg.
  str r4, [sp]       // sp : *from = msg address - the native byte array to copy inside the Java byte[] array
  ldr r5, [r5, #832] // r5 <- r5 : *JNativeInterface->SetByteArrayRegion (+832). We don't need r5 after this so we store the function address directly in it.
  blx r5             // SetByteArrayRegion(*_JNIEnv : r0, *bytearray : r1, 0 : r2, size_of_msg : r3, *msg : sp)
  add sp, sp, #4        // Get our stack space back !
  mov r0, r6             // *bytearray : Our return value
  ldmfd sp!, {r4-r6, pc} // Restoring the scratch-registers and returning by loading the link-register into the program-counter

Then assemble and link this example library :

export PREFIX="armv7a-hardfloat-linux-gnueabi" # Replace this by the prefix of your toolset or remove '$PREFIX-' from the next commands
export DEST="/path/to/your/TestActivityProject/app/src/main/jniLibs" # Skip this if you don't have an Android project
$PREFIX-as -o wild.o wild.s
$ -shared --dynamic-linker=/system/bin/linker -shared --hash-style=sysv -o wild.o
cp $DEST/armeabi/ # Skip this if you don't have an Android project
cp $DEST/armeabi-v7a/ # Skip this if you don't have an Android project

Calling this from Android

Generate a project with :

  • the same package name you used in the assembly listing (your.pack.testactivity),
  • an activity named TestActivity

And define native byte[] testMe() in it.

package your.pack.testactivity;

import android.os.Bundle;
import android.widget.TextView;

public class TestActivity extends AppCompatActivity {

  /* Basically, the android system will look for a "" in the 
     app's private and public folders. */
  static { System.loadLibrary("wildAssembly"); }

  /* And then look for a symbol named :
    The current package name is : your.pack.testactivity
    The current class name is : TestActivity 
    The method name is testMe
    So the android linker will look for a symbol named :
    There is no signature or return value check in assembly, so your
    java compiler will compile this class EVEN if the library is not
    there or if the symbol name is invalid.
    There is no such things as "return type" or "parameters type" in 
    assembly so no such check will be performed ever. */
  static native byte[] testMe();
  protected void onCreate(Bundle savedInstanceState) {


    TextView mContentView = (TextView) findViewById(;
    mContentView.setText(new String(testMe()));


  /* Try it : Redeclare testMe() as 'native int testMe()' and 
     new String(testMe()) by String.format(Locale.C, "%d", testMe()) */


<FrameLayout xmlns:android=""

  <!-- The primary full-screen view. This can be replaced with whatever view
         is needed to present your content, e.g. VideoView, SurfaceView,
         TextureView, etc. -->


Copy the generated native library inside the Android project

Create a directory named jniLibs in $YourProjectRootFolder/app/src/main if it doesn’t exist

Then create two directories armeabi and armeabi-v7a in it so you have :

  • $YourProjectRootFolder/app/src/main/jniLibs/armeabi
  • $YourProjectRootFolder/app/src/main/jniLibs/armeabi-v7a

Copy your library in those folders

Then compile and install the project on your phone, using either : * gradle installDebug * The ‘Run’ button on Android Studio

How it works, basically

For what I understand, when you define the following in a Java class :

package your.package

public class YourClass ... {
  ... {
  native return_type methodName(parameters...)
  • The JVM (or Dalvik) will first search for the library “name” in a way typical to the current system.
    Using the same example, on Android systems (Linux), Dalvik will search for in places referenced by the current LD_LIBRARY_PATH.
  • Then, it will look for a symbol following this pattern in the library found :
  • Once the symbol found, it will execute the instructions at the symbol address, passing the following arguments using the standard procedure call convention :
    • the address of the data structure representing the current Java environment (*_JNIEnv in C programs) (in r0 on ARM)
    • the address of the data structure representing the current Java object (this) on which the method is called (jobject thisObj) (in r1)
    • the other arguments (in r2, r3 and the stack accessible through sp)

If you look in the jni.h file provided with your NDK, you’ll see that _JNIEnv is a data structure defined like this :

struct _JNIEnv {  
   const struct JNINativeInterface* functions;  
  /* C++ specific hacks around 'functions' */

The JNINativeInterface is a data structure composed only by function pointers, plus a starting padding (of 4 void* pointers).

So basically, _JNIEnv* equates to :

*_JNIEnv ->
	*JNINativeInterface ->

Getting the address offset of a function pointer defined in JNINativeInterface tends to boil down to :

Size of a procedure address (4) * number of statements preceding the statement defining the function pointer

For example, the offset of NewByteArray, preceded by 176 statements, is 176*4 = 704.

Note that the JNI documentation actually provides the index of each function pointer in JNINativeInterface.
If you look at the documentation, you’ll see that the index of NewByteArray is 176. Then multiply by 4 octets, the size of an address on ARMv7 architectures, and you’ll get the same offset : 704.

Since the argument provided by the JNI to the native procedure is a pointer to _JNIEnv, calling NewByteArray requires to :

  • Get the data structure pointed by r0
  • Get the data structure pointed in result + 704
  • Prepare to pass the first parameter in r1
  • Call the result

However, note that most of the JNI functions require *_JNIEnv, so you’ll have to save r0 somewhere in order to call the different functions correctly.

Once you know that, the rest is kinda easy.

Look up the appropriate functions to call in the JNI documentation and call them with the right arguments.