编程规范

差異處

這裏顯示兩個版本的差異處。

--- wiki:自动化与科技指导:minecoprocessors:编程规范 [2023/12/08 15:03] – nikoqw
+++ wiki:自动化与科技指导:minecoprocessors:编程规范 [2023/12/08 16:04] (目前版本) – [CDecl] nikoqw
@@ 行 2: / 行 2: @@
 为了能够重复利用现有代码，在代码与代码之间调用，所有程序必须遵守本编程规范。
-===== 汇编语言风格 =====
+<wrap cjk-em>约定</wrap>是必须遵守的规定，是程序之间沟通的桥梁，不遵守会导致程序不能与现有的程序库交互。
+<wrap cjk-em>规范</wrap>是强烈建议遵守的规定，是为了方便开发者理解代码，使代码易于维护，方便不同开发者使用相同的方法理解不同人编写的代码。
+===== 用户程序约定 =====
+  * 用户程序代码必须在所有库函数代码之后。
+  * 用户程序必须包含一个 ''_start'' 函数，在其中编写用户代码。
+===== 汇编语言风格规范 =====
 ==== 指令 ====
 每个指令与其操作数使用一个空格隔开。操作数之间使用一个逗号 + 空格（'', ''）隔开。
@@ 行 9: / 行 17: @@
 </code>
 ==== 标签 ====
-所有标签使用下划线分词。除[[#Calling convention|编程规范]]所规定的特殊前后缀外，一律使用小写字母。
+所有标签使用下划线分词。除 [[#Calling convention|Calling convention]] 所规定的特殊前后缀外，一律使用小写字母。
 <code ASM>
 nimshab_miga:
 </code>
 ==== 注释 ====
-使用一个分号 + 空格 + 正文。
+如果注释为自然语言，使用一个分号 + 空格 + 正文，确保首字母大写，且在单词间换行时使用连字符。
-如果注释为自然语言，确保首字母大写。如果是对应的 C 代码，则首字母小写。
+如果是汇编对应的 C 代码，使用两个分号 + 正文，确保首字母小写。
 <code ASM>
-; 测试核反应堆
+; Test running n
-; out_h_for_whi
+; -uclear reactor
-; le(0, 5);
+; for a while
+;;out_h_for_whi
+;;le(0, 5);
 MOV c, 0
-MOC d, 5
+MOV d, 5
-CALL  out_h_for_while
+CALL out_h_for_while
 </code>
@@ 行 30: / 行 40: @@
   * 0 1 2 3 分别代表前、后、左、右四个 I/O 口。
-===== 函数 =====
+===== 函数规范 =====
 ==== 结构 ====
 若函数所遵循的调用约定规定要在函数中通过压栈的方式暂存寄存器状态，则分三块结构编写：
@@ 行 40: / 行 50: @@
 遵照如下所示的结构：
 <code ASM>
-; 【FUNC】====
+; 【FUNC】<参数及返回值说明>====
 <函数名>:
 ; Init regs
@@ 行 58: / 行 68: @@
 <code ASM>
+; 【FUNC】<参数及返回值说明>====
 <函数名>:
 ; Init regs
@@ 行 85: / 行 96: @@
 **汇编**
 <code ASM>
-; 【FUNC】====
+; 【FUNC】d,c====
+; d: b fast_boot
 start_machine:
-; if(fast_boot)
+; Init regs.
-CMP pf, 0xff
+PUSH c
+; Main logic.
+;;if(fast_boot)
+CMP d, 0
 JZ sm__if_fbot
 JMP sm__if_fbot_el
-; {
+;;{
 sm__if_fbot:
 ; 快速启动 逻辑
 JMP sm__ps_if_fbot
-; } else {
+;;} else {
 sm__if_fbot_el:
 ; 慢速启动 逻辑
 sm__ps_if_fbot:
-; }
+;;}
-; 检查启动是否成功 逻辑
+; 通知启动成功 逻辑
+MOV c, 0x10
+MOV d, 0
+CALL out_h_for_while
+; Exit.
+POP c
 RET
 </code>
@@ 行 109: / 行 131: @@
 #include <stdbool.h>
-void start_machine() {
+void start_machine(bool fast_boot) {
-    bool fast_boot = pf;
     if (fast_boot) {
         // 快速启动  逻辑
@@ 行 116: / 行 137: @@
         // 慢速启动  逻辑
     }
-    // 检查启动是否成功  逻辑
+    // 通知启动成功  逻辑
+    out_h_for_while(0, 0x10);
 }
 </code>
@@ 行 122: / 行 144: @@
 </WRAP>
-==== 注释 ====
+==== 如何写参数及返回值说明 ====
-每个非内部函数（与其他程序共享的函数而非自己使用的函数）都需要具备注释。注释需要按顺序阐明：
+函数标记中包含「参数及返回值说明」。它的规则如下：
+如果函数没有返回用寄存器列表，则使用下面的语法：
+<code ASM>
+[传参用寄存器列表][,内部使用的寄存器列表]
+</code>
+如果函数有返回用寄存器列表，则使用下面的语法：
+<code ASM>
+[传参用寄存器列表],[内部使用的寄存器列表],[返回用寄存器列表]
+</code>
+如果函数既没有传参用寄存器，也没有内部使用的寄存器和返回用寄存器，则使用下面的语法：
+<code ASM>
+</code>
+==== 文档 ====
+每个非内部函数（与其他程序共享的函数而非自己使用的函数）都需要具备文档。文档需要按顺序阐明：
   - 调用约定，若为 StdCall 则不写。
   - 作用
@@ 行 134: / 行 173: @@
 StdCall, StdCallR, QCall, CDecl
+''_start'' 函数是例外的，它不遵守任何调用约定。''_start'' 函数不需要做任何额外的事情（如 PUSH 内部用到的寄存器）。
 ==== StdCall ====
@@ 行 140: / 行 181: @@
 使用寄存器传参，没有返回值。
-采用 StdCall 的函数必须使用 d c b a 的顺序用寄存器保存参数。
+采用 StdCall 的函数最好使用 d c b a 的顺序用寄存器保存参数。
 采用 StdCall 的函数不加任何后缀。
@@ 行 169: / 行 210: @@
 无论调用方使用是否使用了被调用函数内部使用的寄存器，调用方在 CALL 函数前都必须将<wrap cjk-em>被调用函数内部使用的寄存器</wrap>通过压栈的方式暂存状态，CALL 结束后自行择机复原寄存器状态。
+被调用的函数在退出前不复原自身使用的寄存器的状态。
 ==== CDecl ====
-“C Declaration”，C 语言的调用约定。本调用约定是为了应对数量较多的参数。
+“C declaration”，C 语言的调用约定。本调用约定是为了应对数量较多的参数。
 使用栈传参，使用寄存器返回值。