EKA2L1

https://eka2l1.github.io/docs
Admin
EKA2L1 is an experimental Symbian OS emulator that enables running Symbian mobile apps and games...
Tokens:5,682
Snippets:75
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### getCurrentProcess

Source: https://eka2l1.github.io/docs/modules/kernel.html

Get the current running process on the current emulated core.

```APIDOC
## getCurrentProcess()

### Description
Get the current running process on the current emulated core.

### Returns
- **process** (object) - The current process.
```

--------------------------------

### kernel.thread:exitReason

Source: https://eka2l1.github.io/docs/modules/kernel.html

Gets the exit reason code for the thread.

```APIDOC
## kernel.thread:exitReason()

### Description
Get the reason this thread exited. The reason is a code, which will be 0 if the thread is still running.

### Returns
- (integer) - 32-bit integer code indicating the exit reason.
```

--------------------------------

### kernel.codeseg:codeSize

Source: https://eka2l1.github.io/docs/modules/kernel.html

Get the size of the segment's code section.

```APIDOC
## kernel.codeseg:codeSize()

### Description
Get the size of the segment's code section.

### Returns
- **size** (32-bit integer) - The code size.
```

--------------------------------

### Connect GDB to EKA2L1

Source: https://eka2l1.github.io/docs/topics/debuggingwithgdb.md.html

Connect a GDB instance with ARM support to the emulator's remote stub.

```bash
target remote localhost:<gdb_port>
```

--------------------------------

### Configure GDB Breakpoints and Timeouts

Source: https://eka2l1.github.io/docs/topics/debuggingwithgdb.md.html

Commands to set the ARM/Thumb fallback mode, define breakpoints at specific memory addresses, and extend the remote connection timeout.

```bash
set arm fallback-mode <arm/thumb>
break *0x<hex_address>
set remotetimeout <num_in_seconds>
```

--------------------------------

### getSp()

Source: https://eka2l1.github.io/docs/modules/cpu.html

Retrieves the current stack pointer (SP) of the CPU.

```APIDOC
## getSp()

### Description
Get the current stack pointer (SP) of the CPU. This is equivalent to calling getReg(13).

### Returns
- **value** (integer) - Register SP's value.
```

--------------------------------

### registerIpcHook(serverName, opcode, when, func)

Source: https://eka2l1.github.io/docs/modules/events.html

Registers a callback for IPC request interception.

```APIDOC
## registerIpcHook(serverName, opcode, when, func)

### Description
Registers a callback on IPC request send or completion. The callback receives an ipc.context object.

### Parameters
- **serverName** (string) - Required - Name of the server to intercept.
- **opcode** (integer) - Required - The target message opcode.
- **when** (constant) - Required - The event timing (EVENT_IPC_SEND or EVENT_IPC_COMPLETE).
- **func** (function) - Required - Callback function receiving an ipc.context object.

### Returns
- **handle** (integer) - A handle to the callback (> 0) or INVALID_HOOK_HANDLE on failure.
```

--------------------------------

### registerIpcHook

Source: https://eka2l1.github.io/docs/modules/events.html

Registers a callback for IPC request events.

```APIDOC
## registerIpcHook(serverName, opcode, when, func)

### Description
Register a callback on IPC request send or completion.

### Parameters
- **serverName** (string) - The name of the IPC server.
- **opcode** (number) - The IPC opcode.
- **when** (constant) - The event timing (use EVENT_IPC_SEND or EVENT_IPC_COMPLETE).
- **func** (function) - The callback function to execute.
```

--------------------------------

### log(str)

Source: https://eka2l1.github.io/docs/modules/common.html

Logs a string message to the emulator's log sinks with INFO severity and Scripting category.

```APIDOC
## log(str)

### Description
Prints a string into the emulator's log sinks. The severity of the log is set to INFO and the category is Scripting.

### Parameters
- **str** (string) - Required - The string to be logged out.
```

--------------------------------

### getPc()

Source: https://eka2l1.github.io/docs/modules/cpu.html

Retrieves the current program counter (PC) of the CPU.

```APIDOC
## getPc()

### Description
Get the current program counter (PC) of the CPU. This is equivalent to calling getReg(15).

### Returns
- **value** (integer) - Register PC's value.
```

--------------------------------

### readQword(addr)

Source: https://eka2l1.github.io/docs/modules/mem.html

Reads a 64-bit qword value from the specified memory address.

```APIDOC
## readQword(addr)

### Description
Reads the qword value (64-bit) at the specified address.

### Parameters
- **addr** (number) - The address to perform the read.

### Returns
- **value** (number) - Qword value stored at the given address.
```

--------------------------------

### getLr()

Source: https://eka2l1.github.io/docs/modules/cpu.html

Retrieves the current link register (LR) of the CPU.

```APIDOC
## getLr()

### Description
Get the current link register (LR) of the CPU. This is equivalent to calling getReg(14).

### Returns
- **value** (integer) - Register LR's value.
```

--------------------------------

### kernel.process:writeMemory

Source: https://eka2l1.github.io/docs/modules/kernel.html

Write a byte array into the process's memory space.

```APIDOC
## kernel.process:writeMemory(addr, buffer)

### Description
Write a byte array into the process's memory space. This function will call error on failure.

### Parameters
- **addr** (integer) - The address to write the byte array to.
- **buffer** (byte array) - The data to write.
```

--------------------------------

### std.descriptor16:rawData

Source: https://eka2l1.github.io/docs/modules/std.html

Retrieves the raw data contained within a 16-bit descriptor.

```APIDOC
## std.descriptor16:rawData()

### Description
Get the raw data that this descriptor is containing.

### Returns
- **data** (FFI byte array) - A raw FFI byte array containing data.
```

--------------------------------

### kernel.thread:getSp

Source: https://eka2l1.github.io/docs/modules/kernel.html

Retrieves the saved stack pointer (SP) register value.

```APIDOC
## kernel.thread:getSp()

### Description
Retrieve the value in the SP (stack pointer) register. The SP register is identical to the R13 register.

### Returns
- (integer) - The value of the SP as a 32-bit integer.
```

--------------------------------

### registerLibraryHook(libName, ord, processUid, func)

Source: https://eka2l1.github.io/docs/modules/events.html

Registers a callback on a library function call using its ordinal for consistent address detection across devices.

```APIDOC
## registerLibraryHook(libName, ord, processUid, func)

### Description
Registers a callback on a library function being called. This is preferred for cross-device compatibility as it uses the function ordinal rather than a hardcoded address.

### Parameters
- **libName** (string) - Required - Name of the library containing the target function.
- **ord** (integer) - Required - The ordinal of the function inside the library.
- **processUid** (integer) - Required - UID3 of the process to trigger on (use 0 for any).
- **func** (function) - Required - Callback function with no parameters and no return.

### Returns
- **handle** (integer) - A handle to the callback (> 0) or INVALID_HOOK_HANDLE on failure.
```

--------------------------------

### std.descriptor8:rawData

Source: https://eka2l1.github.io/docs/modules/std.html

Retrieves the raw data contained within an 8-bit descriptor.

```APIDOC
## std.descriptor8:rawData()

### Description
Get the raw data that this descriptor is containing.

### Returns
- **data** (FFI byte array) - A raw FFI byte array containing data.
```

--------------------------------

### loadCodeseg

Source: https://eka2l1.github.io/docs/modules/kernel.html

Load a new code segment.

```APIDOC
## loadCodeseg(path)

### Description
Load a new code segment. This code segment is not attached to any process during this function.

### Parameters
- **path** (string) - The emulated system's path to the codeseg to load.

### Returns
- **codeseg** (class) - The codeseg class if successful, else nil.
```

--------------------------------

### kernel.process:readMemory

Source: https://eka2l1.github.io/docs/modules/kernel.html

Read a certain amount of data from the process's memory.

```APIDOC
## kernel.process:readMemory(addr, size)

### Description
Read a certain amount of data from the process's memory.

### Parameters
- **addr** (integer) - The address to read data from.
- **size** (integer) - The number of bytes to read.

### Returns
- **data** (byte array) - The read result.
```

--------------------------------

### kernel.thread:getPc

Source: https://eka2l1.github.io/docs/modules/kernel.html

Retrieves the saved program counter (PC) register value.

```APIDOC
## kernel.thread:getPc()

### Description
Retrieve the value in the PC (program counter) register. The PC register is identical to the R15 register.

### Returns
- (integer) - The value of the PC as a 32-bit integer.
```

--------------------------------

### IpcContext.arguments:value

Source: https://eka2l1.github.io/docs/modules/ipc.context.html

Retrieves the raw 32-bit integer value of an IPC argument.

```APIDOC
## IpcContext.arguments:value(idx)

### Description
Get the raw argument value.

### Parameters
- **idx** (number) - Required - The index of the argument to retrieve value from.

### Returns
- **value** (number) - Argument in the form of 32-bit integer value.
```

--------------------------------

### IpcContext.context:rawArgument

Source: https://eka2l1.github.io/docs/modules/ipc.context.html

Retrieves the raw 32-bit integer value of an IPC argument (alias for IpcContext.arguments:value).

```APIDOC
## IpcContext.context:rawArgument(idx)

### Description
Get the raw argument value.

### Parameters
- **idx** (number) - Required - The index of the argument to retrieve value from.

### Returns
- **value** (number) - Argument in the form of 32-bit integer value.
```

--------------------------------

### kernel.codeseg:lookup

Source: https://eka2l1.github.io/docs/modules/kernel.html

Search for a function with specified index (ordinal) in the library and retrieve its address.

```APIDOC
## kernel.codeseg:lookup(process, ord)

### Description
Search for a function with specified index (ordinal) in the library and retrieve its address.

### Parameters
- **process** (object) - A process object where the address should be retrieved.
- **ord** (integer) - The ordinal identifying the library function.

### Returns
- **address** (32-bit integer) - The address to the function, or 0 on failure.
```

--------------------------------

### registerLibraryHook

Source: https://eka2l1.github.io/docs/modules/events.html

Registers a callback function to be executed when a specific library function is called.

```APIDOC
## registerLibraryHook(libName, ord, processUid, func)

### Description
Registers a callback on a library function being called.

### Parameters
- **libName** (string) - The name of the library.
- **ord** (number) - The ordinal of the function.
- **processUid** (number) - The UID of the process.
- **func** (function) - The callback function to execute.
```

--------------------------------

### std.requestStatus:value

Source: https://eka2l1.github.io/docs/modules/std.html

Retrieves the current value of the request status.

```APIDOC
## std.requestStatus:value()

### Description
Retrieve the current value of the request status.

### Returns
- **value** (integer) - A 32-bit integer as the status code.
```

--------------------------------

### rawUtf16ToString

Source: https://eka2l1.github.io/docs/modules/std.html

Converts a raw 8-bit C FFI byte array into a 16-bit Unicode string.

```APIDOC
## rawUtf16ToString(raw, length)

### Description
Convert a raw 8-bit C FFI byte array into a 16-bit Unicode string.

### Parameters
- **raw** (FFI byte array) - The raw byte array to convert.
- **length** (number) - The number of characters that the result string should produce.

### Returns
- **string** (string) - Converted string object.
```

--------------------------------

### registerBreakpointHook(libName, addr, processUid, func)

Source: https://eka2l1.github.io/docs/modules/events.html

Registers a callback on a specific memory breakpoint address.

```APIDOC
## registerBreakpointHook(libName, addr, processUid, func)

### Description
Registers a callback on a breakpoint. The address is relative to the library's base address unless 'constantaddr' is specified for libName.

### Parameters
- **libName** (string) - Required - Name of the library or 'constantaddr'.
- **addr** (integer) - Required - The address of the breakpoint.
- **processUid** (integer) - Required - UID3 of the process to trigger on (use 0 for any).
- **func** (function) - Required - Callback function with no parameters and no return.

### Returns
- **handle** (integer) - A handle to the callback (> 0) or INVALID_HOOK_HANDLE on failure.
```

--------------------------------

### kernel.thread:getRegister

Source: https://eka2l1.github.io/docs/modules/kernel.html

Retrieves the saved value of a specific register (R0-R15) for the thread.

```APIDOC
## kernel.thread:getRegister(idx)

### Description
Retrieve the value in register from R0 to R15. This is the saved value from the last time this thread ran.

### Parameters
- **idx** (integer) - Required - The index of the register to retrieve (0 - 15).

### Returns
- (integer) - The value of the target register as a 32-bit integer.
```

--------------------------------

### kernel.ipcMessage:arg

Source: https://eka2l1.github.io/docs/modules/kernel.html

Retrieves an argument value from an IPC message.

```APIDOC
## kernel.ipcMessage:arg(idx)

### Description
Get the argument value of the message. Each message stores 4 integer arguments.

### Parameters
- **idx** (integer) - Required - The index of the argument to retrieve (0 - 3).

### Returns
- (integer) - The value of the argument.
```

--------------------------------

### getReg(idx)

Source: https://eka2l1.github.io/docs/modules/cpu.html

Reads the value of a general-purpose register from R0 to R15.

```APIDOC
## getReg(idx)

### Description
Reads the value of a general-purpose register from R0 to R15.

### Parameters
- **idx** (integer) - Required - The index of the register (0 - 15).

### Returns
- **value** (integer) - The value currently stored in the targeted register.
```

--------------------------------

### IpcContext.context:argument

Source: https://eka2l1.github.io/docs/modules/ipc.context.html

Retrieves the processed value of an IPC argument.

```APIDOC
## IpcContext.context:argument(idx)

### Description
Get the value of the argument processed. For descriptor argument types, this returns a std.descriptor8 or std.descriptor16 class; otherwise, it returns a 32-bit integer.

### Parameters
- **idx** (number) - Required - The index of the argument to retrieve value from.

### Returns
- **value** (any) - The value at the target index processed.
```

--------------------------------

### std.requestStatus:flags

Source: https://eka2l1.github.io/docs/modules/std.html

Retrieves the current flags of the request status.

```APIDOC
## std.requestStatus:flags()

### Description
Retrieve the current flags of the request status.

### Returns
- **flags** (integer) - A 32-bit integer, with each bit as a flag.
```

--------------------------------

### setReg(idx, val)

Source: https://eka2l1.github.io/docs/modules/cpu.html

Sets the value of a general-purpose register from R0 to R15.

```APIDOC
## setReg(idx, val)

### Description
Set the value of a register from R0 - R15.

### Parameters
- **idx** (integer) - Required - The index of the register (0 - 15).
- **val** (integer) - Required - The value to write to the register.
```

--------------------------------

### writeByte(addr, data)

Source: https://eka2l1.github.io/docs/modules/mem.html

Writes an 8-bit byte to the specified memory address.

```APIDOC
## writeByte(addr, data)

### Description
Write a byte (8-bit) to the specified address.

### Parameters
- **addr** (number) - The address to perform the write.
- **data** (number) - The byte to write.

### Returns
- **success** (boolean) - True if the write operation performed successfully.
```

--------------------------------

### IpcContext.context:ownThread

Source: https://eka2l1.github.io/docs/modules/ipc.context.html

Retrieves the thread that owns the IPC context.

```APIDOC
## IpcContext.context:ownThread()

### Description
Get the thread owning the context. This is the thread that wants to send the IPC message.

### Returns
- **thread** (kernel.thread) - Own thread as kernel.thread.
```

--------------------------------

### IpcContext.arguments:valueType

Source: https://eka2l1.github.io/docs/modules/ipc.context.html

Retrieves the type of an IPC argument.

```APIDOC
## IpcContext.arguments:valueType(idx)

### Description
Get the type of an argument.

### Parameters
- **idx** (number) - Required - The argument index to retrieve the type for.

### Returns
- **type** (constant) - One of the IPC_ARGUMENT_TYPE_ constants.
```

--------------------------------

### registerBreakpointHook

Source: https://eka2l1.github.io/docs/modules/events.html

Registers a callback function to be executed when a breakpoint is hit.

```APIDOC
## registerBreakpointHook(libName, addr, processUid, func)

### Description
Register a callback on a breakpoint. It is recommended to keep the callback execution time short to avoid impacting emulator performance.

### Parameters
- **libName** (string) - The name of the library.
- **addr** (number) - The memory address of the breakpoint.
- **processUid** (number) - The UID of the process.
- **func** (function) - The callback function to execute.
```

--------------------------------

### clearHook

Source: https://eka2l1.github.io/docs/modules/events.html

Unregisters a previously registered callback.

```APIDOC
## clearHook(handle)

### Description
Unregister a callback using its handle.

### Parameters
- **handle** (number) - The handle returned from the registration function.
```

--------------------------------

### readByte(addr)

Source: https://eka2l1.github.io/docs/modules/mem.html

Reads an 8-bit byte value from the specified memory address.

```APIDOC
## readByte(addr)

### Description
Reads the byte value (8-bit) at the specified address.

### Parameters
- **addr** (number) - The address to perform the read.

### Returns
- **value** (number) - Byte value stored at the given address.
```

--------------------------------

### kernel.ipcMessage:requestStatusAddress

Source: https://eka2l1.github.io/docs/modules/kernel.html

Retrieves the request status address in the sender process's memory space. It is recommended to use the std.requestStatus class to interpret the status condition.

```APIDOC
## kernel.ipcMessage:requestStatusAddress()

### Description
Get the request status address in the sender process's memory space.

### Returns
- **address** (32-bit integer) - The address to the request status.
```

--------------------------------

### readWord(addr)

Source: https://eka2l1.github.io/docs/modules/mem.html

Reads a 16-bit word value from the specified memory address.

```APIDOC
## readWord(addr)

### Description
Reads the word value (16-bit) at the specified address.

### Parameters
- **addr** (number) - The address to perform the read.

### Returns
- **value** (number) - Word value stored at the given address.
```

--------------------------------

### getCpsr()

Source: https://eka2l1.github.io/docs/modules/cpu.html

Reads the current value of the CPSR register.

```APIDOC
## getCpsr()

### Description
Reads the CPSR register value.

### Returns
- **value** (integer) - CPSR register value.
```

--------------------------------

### clearHook(handle)

Source: https://eka2l1.github.io/docs/modules/events.html

Unregisters a previously registered callback.

```APIDOC
## clearHook(handle)

### Description
Unregisters a callback using its handle. This method is safe to call inside a callback.

### Parameters
- **handle** (integer) - Required - The handle retrieved from the registration function.
```

--------------------------------

### readDword(addr)

Source: https://eka2l1.github.io/docs/modules/mem.html

Reads a 32-bit dword value from the specified memory address.

```APIDOC
## readDword(addr)

### Description
Reads the dword value (32-bit) at the specified address.

### Parameters
- **addr** (number) - The address to perform the read.

### Returns
- **value** (number) - Dword value stored at the given address.
```
Tokens:
Raw