12 KiB
12 KiB
核集合、亲和性清单与容量绑定合同 v1
本工程只规划逻辑加速器核心的元数据,不查询宿主,不执行任务,也不测量真实cache、迁移或性能。这里的文本和二进制格式是本工程明确规定的交换格式;不要求兼容某个SDK或Linux系统调用的完整格式。公开C++17 API在affinity.hpp。
值、集合与错误
- 逻辑core ID为0..255,数值0是普通合法核心,不是空值。CoreSet是包含这些ID的值;直接由调用方构造的CoreSet允许任意顺序,但不得重复、不得含256..65535。空集合合法。所有成功返回的CoreSet.ids严格递增。
- valid_job_id接受1..32字节,仅ASCII字母、数字、下划线、连字符;大小写敏感。空串、NUL、高位字节、空白、点、斜线均不合法,不解释路径或Unicode。
- 所有输入只读,输出拥有自己的字符串/容器,旧结果及不同调用互不影响。每次调用的输入对象与输出对象互异,调用方保证对象及其元素在调用期间有效;不要求处理分配失败或被移动后的对象。API没有可变全局业务状态。
- Error仅none=0与invalid=1。parse_list/parse_mask/combine任意错误都把output.ids全清空;format_list/format_mask错误把output字符串清空。canonical_problem/decode_problem错误把output变为默认空Problem;encode_problem错误清空字节vector;make_plan错误把output变为默认Plan,accepted=retained=0且bindings/loads全空。成功及失败都覆盖旧输出,不保留半成品。
核列表文本
- parse_list输入至多4096字节,空串表示空集合。非空时为逗号分隔的一个或多个item;不允许任何空item、空白、正负号、NUL或非ASCII字节,不修剪首尾空白。所有十进制字段只用ASCII数字,允许任意数量前导零但仍受总长限制,不能回绕或只读取合法前缀。
- item只能是A、A-B或A-B:U/G。A/B数值在0..255且A<=B;U/G数值在1..256且U<=G。分组形式必须有A-B,单个A后不能直接带冒号;每个分隔符及字段都必须完整,不能多一个连字符、冒号或斜线。A==B的范围合法。
- A选择自身;A-B选择闭区间全部ID。A-B:U/G从A开始每G个一组,每组选择前U个:恰选择所有A<=c<=B且(c-A)%G<U的c。最后不足G个的尾组仍按同一条件选择。U不是步长,也不是要选的总个数;G可大于范围长度。
- 多item按集合并集合并,item顺序、范围重叠和重复出现均合法,不使parse_list失败。整个text必须完整验证:即使某个坏item在已有集合里不增加ID,仍返回invalid。文本允许重复与01对直接CoreSet值的“不重复”是两个不同输入合同。
- format_list先按01验证整个CoreSet,成功输出最大连续区间的规范十进制列表:单个ID写A,至少两个连续ID写A-B,逗号连接,无前导零/空白/分组后缀。空集合输出空串。输入任意顺序不影响结果;例如{3,1,2,7}输出1-3,7。
十六进制多word mask
- parse_mask输入为1..4096字节的非空文本,恰有1..8个逗号分隔的group;每group为1..8个十六进制数字,大小写均可,允许前导零。禁止空group、空白、正负号、0x前缀、NUL、高位字节或其它字符。即使都是零也不能有第9个group或单group超过8位;空文本invalid。
- 每group恰代表32个核心位,最右group对应ID0..31,倒数第二group对应32..63,依此类推,最左是最高group。每group最低有效bit为该组最小ID。缺省的更高group为零;最左前导零group合法,但仍受8组限制。例:1,0表示{32},0,1表示{0},80000000,00000001表示{0,63}。不得把字符顺序或组顺序当成低核到高核。
- format_mask按01验证CoreSet。空集合输出0;否则只输出到最高非零group,不输出更高零group;最高group用最短小写hex,其余每group恰8位小写hex并保留必要前导零,逗号连接。例如{0,32}输出1,00000001,{0}输出1。parse_mask的合法非规范输入可以比format结果有更多零位/零group。
- combine按01分别完整验证两个输入,operation只允许unite=0/intersect=1/subtract=2;其它枚举值invalid。成功分别返回并集/交集/left减right,严格递增,不原地修改任何输入。即使一个集合为空也不跳过另一个输入或operation的校验。
Problem编译
- Problem.cores含0..32个在线逻辑核心,每个Core.id按01且唯一,capacity在1..8。没有列出的ID视为offline,不是格式错误;core ID无需连续,输入顺序任意。列表中capacity=0不表示offline,而是invalid。所有cores均完整验证,即使jobs为空。
- Problem.jobs含0..24个Job,id按02且唯一;priority是完整有符号int32,包括INT32_MIN、负数、0、INT32_MAX,越大越优先。allowed按01,允许空集合,允许包含当前没有列出的offline ID。previous为null或0..255的ID;它可offline或不在allowed,不因此invalid,不自动加入allowed。
- canonical_problem先完整验证14–15,成功独立拷贝全部数据;cores按数值id升序,jobs按priority降序、相同priority时job.id按ASCII字典序升序,allowed.ids按数值升序。所有其它字段原样保留。没有任务时不丢弃cores,空cores时不丢弃jobs。
- 所有后续接口也接受14–15范围内任意顺序的Problem,不要求调用者先canonical_problem。encode_problem/make_plan同样完整验证整个输入,不能因无可绑定任务、空cores或优先级低而跳过坏字段;错误不污染后续合法调用。
容量绑定的三个目标
- 规划的Job顺序固定为16的规范顺序。每Job要么unassigned(core=null),要么绑定一个既在其allowed中又在Problem.cores中的ID。同一core上绑定的Job数不得大于该Core.capacity。每Job只消耗一个位置,priority不是位置数量,previous不预占容量。
- 第一目标:在全部可行绑定中,按18的Job顺序组成accepted布尔向量(assigned=true),取字典序最大的向量,其中true大于false。这要求优先容纳较早Job;不能为容纳后面任务而牺牲前面可容纳任务。也不能因先前临时绑定占住位置就拒绝一个实际上可通过改绑同时容纳的Job。没有eligible core的Job只会unassigned,不使整个Problem invalid。
- 固定19的最优accepted集合后,第二目标是最大化retained:assigned且previous非null且assigned core恰等于previous的Job数量。它是所有这些Job的全局计数,不是逐Job贪心留在旧核;不在allowed/online的previous不可能被计数。unassigned不计retained,即使previous也是null。
- 固定19与20的最优值后,第三目标是使按18顺序排列的assigned core ID向量字典序最小;unassigned在该向量中统一视为65535。19已固定哪些位置unassigned,不把0当空值,也不把core在输入cores数组里的下标当core ID。以上三目标先后严格固定,不用其它隐含优先级、负载均衡或输入顺序打破平手。
- make_plan成功返回一条绑定对应每个Job,包括unassigned,bindings按18顺序且Binding.job恰为原Job.id;accepted为assigned数量,retained为20定义的数量。loads列出全部online core(包括used=0),按数值core ID升序;used是此Plan实际绑定数。返回的选择必须同时满足18–21,不只报告正确数量而提供另一份不合规绑定。
- 高优先A allowed={0,1}、低优先B allowed={0}、core0/1各capacity=1时,两者必须都接受,A->1/B->0。只first-free先让A占0再拒绝B违反19。相同priority按job ID排序,不能用输入排列替代。
- core0/1/2各capacity=1,规范顺序A/B/C的allowed分别{0,1}/{0,2}/{1,2},previous分别0/0/2。全部可接受时,A->0/B->2/C->1只保留1个;正确第二目标是A->1/B->0/C->2保留2个。完整19优先于这个保留数,最后仍须按21判断其它平手。
- 空jobs成功返回accepted=retained=0、bindings空、loads仍列全部online core且used=0。空cores且jobs非空成功返回全部unassigned、loads空;allowed空或只含offline ID的Job合法。不同Problem、不同输入排列、重复调用、保存旧Plan后处理另一个Problem,均按同一纯值规则,不共享业务状态。
固定字节清单
- encode_problem把17的合法Problem按16规范化后编码,不编码Plan。全部多字节整数均little-endian,字节索引从0开始:头部8字节为ASCII AFF1(0..3)、core_count:u16(4..5)、job_count:u16(6..7)。随后恰core_count个4字节Core记录,再随后恰job_count个变长Job记录,无尾部字节、对齐padding或checksum。
- Core记录依次为id:u16、capacity:u8、reserved:u8;Core记录和Job记录中的reserved均必须为0。encode按core ID升序。Job记录头40字节依次为id_length:u8、reserved:u8、previous:u16、priority:i32、allowed_bitmap:32字节,再接恰id_length个Job.id原字节。previous=0xffff表示null;其它合法previous为0..255。priority按32位补码编码,INT32_MIN不得经绝对值或错误无符号比较改变。
- allowed_bitmap第j字节的bit k表示core ID=8*j+k,j=0..31、k=0..7;所有256位完整保留,包括offline ID。二进制bitmap的低ID字节在前,与文本mask的高group在左是两个不同公开顺序。Job无额外终结NUL。encode中的Job按16顺序,bitmap不依赖allowed输入排列。
- decode_problem接受任意0..4096字节vector,必须精确符合26–28的头部magic/计数/记录长度/保留字段及14–15全部值约束。输入Core与Job记录允许任意顺序,合法时返回16的规范Problem;重复core/job ID、非法capacity、previous既非0xffff又大于255、非法Job.id均invalid。不得只验证将被选择的Job,也不接受尾部padding或忽略截断末项。
- decode需读完验证整份输入才发布output;任何错误按04清空,不能泄漏前几条合法记录。decode成功后encode得到唯一规范字节清单,可能不同于原合法乱序清单;encode→decode与canonical_problem语义一致。无真实文件系统、指针或ABI结构体padding参与这个格式。
构建与观察
- 工程使用已有g++ -std=c++17 -O2 -Wall -Wextra -pedantic及标准库,make构建。四候选core_text.cpp/problem_model.cpp/problem_image.cpp/placement.cpp可任意重组内部算法与数据结构,不要求特定搜索或匹配实现。不能添加正式评分依赖的额外源码/库。
- 评分在干净临时目录重建四候选及同一公开affinity.hpp/观察器;构建限30秒,单次观察程序15秒,整体验收120秒。24任务/32核及规定上界均属有效范围,不能只为小输入正确或靠无界枚举挂死;固定输入,不用真实性能测量制造难度。
- 行协议见docs/console.md,观察器只解析wire、调用API、打印返回值/输出/输入前后比较,不嵌正确答案或断言。每条有效命令(包括业务invalid)正常输出一条JSON并最终exit0;stdout仅协议,stderr允许诊断与UTF-8。wire格式错误exit2。
- valid_job_id/所有解析/集合操作/Problem编译/清单编解码/规划均观察完整输入调用前后是否不变。输出预置旧值以检验04;保存的Plan、bytes及Problem在后续成功/失败、不同bank和不同文本调用后保持独立。不得硬编码公开Job名、核数量或固定mask。
- 本工程不要求保持宿主线程/CPU亲和性,不创建任务,不读proc/sysfs,不测延迟,不要求任何core ID在实际主机存在。所有核心可用性只由Problem.cores给定;软件模型通过不构成真实硬件绑定证明。