Creating embedded program

Creating own embedded Program

This page explains how to create a custom program for ALX Wiremod E2 OS using the current program architecture.

Programs can run on the CPU, GPU, or both depending on their purpose.

• CPU side — contains the program logic that runs on the CPU. If the program requires GPU functionality, the CPU side can start the corresponding GPU program.
• GPU side — contains the program implementation that runs on the GPU. This is required when the program needs GPU functionality, such as displaying output on a screen.

1. Create the Program

Create a new E2 source file inside:

alx_pc/gpu/alxos/

For example:

testprog.txt

The program should include the GPU ALXOS main library and provide an initialization function:

@name Test Program

#include "alx_pc/gpu/alxos/_main_"

function alxos_testprog_init(Args:table) {
    print("HELLO")
}

The initialization function receives the arguments passed to the program.

2. Register the Program on the GPU

Open:

alx_pc/gpu/alxos/_prog_.txt

Add a program entry:

ALXOS_PROGS["alxos_testprog",number] = 1
function alxos_testprog(Args:table) {
    #include "alx_pc/gpu/alxos/testprog"
    alxos_testprog_init(Args)
}

The name used in ALXOS_PROGS is the program name used by ALXOS when launching the program.

3. Register the Program on the CPU

Open:

alx_pc/cpu/alxos/_prog_.txt

Add the CPU-side launcher:

ALXOS_PROGS["alxos_testprog",number] = 1
function alxos_testprog(FInfo:table) {
    dsSendDirect("alxos_runprog",E2_GPU,table("alxos_testprog",FInfo))
}

The CPU does not contain the program implementation. It sends a request to the GPU to run the registered GPU program.

4. Update the CPU and GPU

After adding or changing a program:

1. Save all modified files.
2. Upload the updated CPU.txt to the CPU chip.
3. Upload the updated GPU.txt to the GPU chip.
4. Reboot the system.
5. Create a text file inside ALX OS containing alxos_testprog and name it testprog.e2e (the extension is important!).
6. If everything is configured correctly, executing the created file will print HELLO to your chat/console.

Now you have to use the built-in functions to manage what you want. You should look inside other programs to understand how they work.

You can add your own persist variables and inputs/outputs to your program, and they will be added to the GPU automatically. Keep in mind that variable and function names must be unique to prevent conflicts between programs.

Anyway, here is a small list of the main functions and variables for GPU programs:

egpClear()  - clears EGP and GPU data
DsHandler   - Direct Signal handler function
KeyHandler  - keyboard handler function

Much of the other functionality can be found in:

alx_pc/gpu_main_.txt
alx_pc/gpu/alxos_main_.txt

There are also useful functions in the alx_pc/shared/ files.

Good luck! And sorry for the lack of documentation on how to use all this stuff.

Program Structure

The current ALXOS program system uses the following structure:

CPU
 └─ ALXOS_PROGS
      └─ sends alxos_runprog
             ↓
           GPU
            └─ ALXOS_PROGS
                 └─ includes program source
                      └─ calls *_init()

Programs can use the existing ALXOS handlers and functions provided by the shared GPU code. Look at existing programs in:

alx_pc/gpu/alxos/

for examples of GUI handling, keyboard input, Direct Signals, filesystem access, and other ALXOS functionality.