使用手册

本手册介绍如何在龙架构应用中接入龙芯NBL，并通过一个Hello World示例演示完整的调用流程。当前为初版，后续会持续完善。

完整的签名规则与API说明见SDK压缩包内的doc/目录，也可参考include/nbl.h。

环境要求

• 64位LoongArch Linux平台
• 已验证环境：Loongnix 20

接入步骤

1. 在应用中引入nbl.h，并链接libnbl.so。
2. 调用nbl_load()创建Nbl实例。
3. 将宿主侧原有的dlopen / dlsym等调用替换为nbl->对应接口。
4. 按需调用register_hostfunc*()或register_hostdata()注册宿主函数、数据符号。
5. 使用完成后调用nbl->dlclose()和nbl_unload()释放资源。

Hello World

步骤 1：准备x86_64共享库

先在x86_64环境中准备一个简单的共享库libhello.so。

/* libhello.c，以x86_64为目标编译 */
const char* hello(void)
{
    return "Hello from x86_64";
}

gcc -shared -fPIC -o libhello.so libhello.c
file libhello.so

file命令应显示x86-64。如果显示的是LoongArch，说明编译环境不对，必须在x86_64机器上编译，或使用x86_64交叉编译器。

步骤 2：复制到龙架构机器

将生成的libhello.so复制到龙架构机器的某个目录，例如：

scp libhello.so <user>@<la-host>:/path/to/

下文宿主程序中的/path/to/libhello.so需替换为该文件在龙架构机器上的实际路径。

步骤 3：编写并编译宿主程序

该函数原型为const char* hello(void)，对应的nbl_signature为pFv。其中p表示返回指针，F表示函数，v表示无参数。

在龙架构侧编写宿主程序。nbl_load()的第二个参数是SDK解压根目录，即包含libnbl.so与libbox64-shared.so的目录。

/* hello_host.c，以龙架构为目标编译 */
#include <stdio.h>
#include <nbl.h>

int main(void)
{
    /* 1. 创建Nbl实例；第二个参数为SDK解压根目录（含libnbl.so与libbox64-shared.so） */
    Nbl* nbl = nbl_load(1, "/path/to/nbl-sdk", false);
    if (nbl == NULL) {
        fprintf(stderr, "nbl_load failed\n");
        return 1;
    }

    /* 2. 加载x86_64共享对象 */
    void* h = nbl->dlopen("/path/to/libhello.so", RTLD_NOW);
    if (h == NULL) {
        fprintf(stderr, "dlopen failed: %s\n", nbl->dlerror());
        nbl_unload(nbl);
        return 1;
    }

    /* 3. 按签名取得可调用的包装桩
       "pFv"：p=返回指针，F=函数，v=无参数
       NBL据此自动生成跨架构调用桩 */
    const char* (*hello)(void) =
        (const char* (*)(void))nbl->dlsym_with_signature(h, "hello", "pFv");
    if (hello == NULL) {
        fprintf(stderr, "dlsym failed: %s\n", nbl->dlerror());
        nbl->dlclose(h);
        nbl_unload(nbl);
        return 1;
    }

    /* 4. 像本地函数一样调用x86_64实现 */
    printf("%s\n", hello());

    /* 5. 释放句柄与Nbl实例 */
    nbl->dlclose(h);
    nbl_unload(nbl);
    return 0;
}

编译宿主程序（/path/to/nbl-sdk按实际解压位置替换）。

gcc hello_host.c -I/path/to/nbl-sdk/include -L/path/to/nbl-sdk -lnbl -o hello_host

步骤 4：运行

libnbl.so需要在运行时被找到。LD_LIBRARY_PATH同样指向SDK解压根目录（与nbl_load()的第二个参数一致）：

LD_LIBRARY_PATH=/path/to/nbl-sdk ./hello_host

预期输出：

Hello from x86_64