API 參考
本頁面提供 Gthulhu 和 SCX GoLand Core 的完整 API 參考文檔。
SCX GoLand Core API
核心模組
core.LoadSched()
載入 BPF 調度器程式。
參數:
- bpfObjectFile
: BPF 物件檔案路徑 (如: main.bpf.o
)
回傳值:
- *BPFModule
: BPF 模組實例
範例:
BPFModule.AssignUserSchedPid()
設定使用者空間調度器的 PID。
參數:
- pid
: 使用者空間調度器的程序 ID
範例:
pid := os.Getpid()
err := bpfModule.AssignUserSchedPid(pid)
if err != nil {
log.Printf("AssignUserSchedPid failed: %v", err)
}
BPFModule.Attach()
附加 BPF 程式到核心。
範例:
BPFModule.ReceiveProcExitEvt()
接收程序退出事件。
回傳值:
- int
: 退出程序的 PID,如果沒有事件則回傳 -1
範例:
go func() {
for {
if pid := bpfModule.ReceiveProcExitEvt(); pid != -1 {
sched.DeletePidFromTaskInfo(pid)
} else {
time.Sleep(100 * time.Millisecond)
}
}
}()
快取模組 (util
套件)
cache.InitCacheDomains()
初始化 CPU 快取域。
參數:
- bpfModule
: BPF 模組實例
範例:
err := cache.InitCacheDomains(bpfModule)
if err != nil {
log.Panicf("InitCacheDomains failed: %v", err)
}
調度模組 (sched
套件)
sched.DeletePidFromTaskInfo()
從任務資訊中刪除指定 PID。
參數:
- pid
: 要刪除的程序 ID
BPF 程式 API
Map 結構
task_info_map
儲存任務資訊的 Hash Map。
struct {
__uint(type, BPF_MAP_TYPE_HASH);
__uint(max_entries, MAX_TASKS);
__type(key, pid_t);
__type(value, struct task_info);
} task_info_map SEC(".maps");
struct task_info
任務資訊結構體。
struct task_info {
__u64 vruntime; // 虛擬執行時間
__u32 weight; // 任務權重
__u32 slice_ns; // 時間片 (奈秒)
__u64 exec_start; // 執行開始時間
__u64 sum_exec_runtime; // 累計執行時間
__u32 voluntary_ctxt_switches; // 自願上下文切換次數
__u32 nonvoluntary_ctxt_switches; // 非自願上下文切換次數
};
BPF 程式進入點
sched_ext_ops
調度器操作結構體。
SEC(".struct_ops.link")
struct sched_ext_ops gthulhu_ops = {
.select_cpu = (void *)gthulhu_select_cpu,
.enqueue = (void *)gthulhu_enqueue,
.dispatch = (void *)gthulhu_dispatch,
.running = (void *)gthulhu_running,
.stopping = (void *)gthulhu_stopping,
.enable = (void *)gthulhu_enable,
.init = (void *)gthulhu_init,
.exit = (void *)gthulhu_exit,
.name = "gthulhu",
};
核心函數
gthulhu_select_cpu()
選擇適合的 CPU 核心。
參數:
- p
: 任務結構體指標
- prev_cpu
: 前一個 CPU 編號
- wake_flags
: 喚醒標誌
回傳值:
- s32
: 選中的 CPU 編號
gthulhu_enqueue()
將任務加入佇列。
gthulhu_dispatch()
調度任務執行。
配置選項
環境變數
變數名 | 說明 | 預設值 | 類型 |
---|---|---|---|
GTHULHU_DEBUG |
啟用調試模式 | false |
bool |
GTHULHU_LOG_LEVEL |
日誌等級 | INFO |
string |
GTHULHU_MAX_TASKS |
最大任務數 | 4096 |
int |
執行時參數
時間片設定
// 基礎時間片 (奈秒)
#define BASE_SLICE_NS 5000000ULL // 5ms
// 最小時間片
#define MIN_SLICE_NS 1000000ULL // 1ms
// 最大時間片
#define MAX_SLICE_NS 20000000ULL // 20ms
權重設定
// Nice 值對應的權重表
static const int prio_to_weight[40] = {
/* -20 */ 88761, 71755, 56483, 46273, 36291,
/* -15 */ 29154, 23254, 18705, 14949, 11916,
/* -10 */ 9548, 7620, 6100, 4904, 3906,
/* -5 */ 3121, 2501, 1991, 1586, 1277,
/* 0 */ 1024, 820, 655, 526, 423,
/* 5 */ 335, 272, 215, 172, 137,
/* 10 */ 110, 87, 70, 56, 45,
/* 15 */ 36, 29, 23, 18, 15,
};
錯誤處理
常見錯誤碼
錯誤碼 | 說明 | 解決方案 |
---|---|---|
-EPERM |
權限不足 | 使用 root 權限執行 |
-ENOENT |
BPF 檔案不存在 | 確認 BPF 物件檔案路徑 |
-EINVAL |
無效參數 | 檢查函數參數 |
-ENOMEM |
記憶體不足 | 增加系統記憶體 |
錯誤處理範例
// 錯誤處理模式
if err := bpfModule.Attach(); err != nil {
switch {
case strings.Contains(err.Error(), "permission denied"):
log.Fatal("需要 root 權限")
case strings.Contains(err.Error(), "no such file"):
log.Fatal("BPF 檔案不存在")
default:
log.Fatalf("未知錯誤: %v", err)
}
}
調試 API
統計資訊
// 獲取調度器統計資訊
type SchedulerStats struct {
TotalTasks uint64
ActiveTasks uint64
ContextSwitches uint64
AverageLatency time.Duration
CPUUtilization float64
}
func GetSchedulerStats() *SchedulerStats {
// 實作細節...
}
調試工具函數
// BPF 調試巨集
#define bpf_debug(fmt, args...) \
bpf_trace_printk(fmt, sizeof(fmt), ##args)
// 追蹤任務狀態變化
static void trace_task_state(struct task_struct *p, const char *event) {
bpf_debug("Task %d: %s (vruntime=%llu)\n",
p->pid, event, get_task_vruntime(p));
}
效能調優 API
動態參數調整
// 調整調度參數
type SchedulingParams struct {
BaseSliceNs uint64
MinSliceNs uint64
MaxSliceNs uint64
LatencyFactor float64
WeightMultiplier float64
}
func UpdateSchedulingParams(params *SchedulingParams) error {
// 實作細節...
}
效能監控
// 效能計數器
struct perf_counters {
__u64 dispatch_count;
__u64 enqueue_count;
__u64 context_switch_count;
__u64 total_runtime;
__u64 idle_time;
};
API 版本
當前 API 版本: v0.1.x
API 穩定性: Alpha (可能會有破壞性變更)
更多範例
更多使用範例請參考專案原始碼中的 examples/
目錄。