Mode Switch

Lichee-Jack uses a SP3T (Single Pole Triple Throw) hardware switch to select different operating modes at runtime. The switch itself is purely hardware, but its state is interpreted in software via a dedicated Linux kernel driver.

This design allows Lichee-Jack to boot once and dynamically change behavior based on the switch position, without rebooting or reflashing the system.

Mode Definition

By default, the three switch positions are mapped as follows:

Payload behavior is fully user-defined. The system only reports the switch state; how it is used is up to user-space software.

More details can be found in SWITCH

Kernel Driver Overview

Lichee-Jack implements the mode switch using an in-tree Linux kernel driver named:

mod-switch

The driver exposes a character device to user space:

/dev/modsw

User-space programs can read the current mode simply by:

cat /dev/modsw

The output is always a single ASCII character:

'0', '1', or '2'

This minimal interface makes the mode switch easy to integrate into shell scripts, init systems, or long-running daemons.

Hardware Logic

The SP3T switch is wired to two GPIO input lines:

• GPIOA_15
• GPIOA_24

Each switch position drives a unique GPIO combination:

This encoding avoids floating states and allows simple, robust detection.

Driver Internal Logic

Internally, the driver:

1. Periodically polls GPIO states
2. Converts GPIO combinations into a logical mode value
3. Stores the result as a single character ('0', '1', '2')
4. Exposes it through a read-only character device

Pseudo Code

static char switch_state = '0';
 
/**
 * modsw_get_state - Read GPIO pins and determine switch state
 *
 * This function reads the values of GPIOA_15 and GPIOA_24, then
 * maps the pin combination to a logical switch state.
 *
 * Return:
 * * '1' - switch in position 1 (GPIO15=0, GPIO24=1)
 * * '2' - switch in position 2 (GPIO15=1, GPIO24=0)
 * * '0' - idle or invalid state (any other combination)
 */
static char modsw_get_state(void)
{
    u32 val = readl(gpio_base + GPIO_EXT);
    int a15 = !!(val & (1 << GPIO_LINE1));
    int a24 = !!(val & (1 << GPIO_LINE2));
 
    if (!a15 && a24)
        return '1';
    else if (a15 && !a24)
        return '2';
    else
        return '0';
}
 
/**
 * modsw_thread_fn - Polling thread for MOD-SWITCH state
 * @data: unused thread data
 *
 * This kernel thread runs in the background and periodically polls
 * the GPIO pins to detect switch state changes. It updates the
 * global @switch_state variable every 20 ms.
 */
static int modsw_thread_fn(void *data)
{
    while (!kthread_should_stop()) {
        switch_state = modsw_get_state();
        msleep(20);
    }
    return 0;
}
 
/**
 * modsw_read - Read current switch state from device
 *
 * Reads one byte representing the switch state ('0', '1', '2')
 * into the user buffer.
 */
static ssize_t modsw_read(struct file *file, char __user *buf,
                          size_t count, loff_t *ppos)
{
    if (*ppos > 0)
        return 0;
 
    if (copy_to_user(buf, &switch_state, 1))
        return -EFAULT;
 
    *ppos += 1;
    return 1;
}

User-Space Usage Example

Shell Script

MODE=$(cat /dev/modsw)
 
case "$MODE" in
  0)
    echo "Debug mode"
    ;;
  1)
    echo "Run payload 1"
    ;;
  2)
    echo "Run payload 2"
    ;;
 esac

Daemon / Init Integration

Typical use cases include:

• Selecting different startup services in systemd/jack-coreutils.service
• Switching network behavior (USB gadget / Ethernet / stealth mode)
• Triggering different payloads for red-team / blue-team / SE testing

Design Notes

• Polling interval: 20 ms (fast enough for human interaction)
• Read-only interface: prevents accidental state corruption
• ASCII output: trivial to parse in any language
• No userspace debounce required

Summary

The Lichee-Jack mode switch provides:

• Simple hardware control
• Clean kernel abstraction
• Minimal and robust user-space interface

This makes it ideal for security tools, payload launchers, and embedded automation workflows.