fcdev 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (260) hide show
  1. package/README.md +21 -2
  2. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +164 -0
  3. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +157 -0
  4. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +123 -0
  5. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +51 -0
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +100 -0
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +103 -0
  8. package/docs/07-/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +74 -0
  9. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +72 -0
  10. package/docs/09-/345/217/221/345/270/203.md +67 -0
  11. package/docs/10-VS Code/346/211/251/345/261/225.md" +131 -0
  12. package/docs/nes/01-NES/347/233/256/346/240/207.md +52 -0
  13. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +252 -0
  14. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +797 -0
  15. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +27 -0
  16. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +46 -0
  17. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +10 -0
  18. package/package.json +4 -3
  19. package/src/api/header-parser.mjs +78 -0
  20. package/src/api/index.mjs +128 -0
  21. package/src/build/bank-link-config.mjs +74 -0
  22. package/src/build/index.mjs +1 -0
  23. package/src/build/program-builder.mjs +5 -2
  24. package/src/cli/commands/api-command.mjs +62 -0
  25. package/src/cli/commands/docs-command.mjs +58 -0
  26. package/src/cli/index.mjs +6 -0
  27. package/src/docs/doc-index.mjs +101 -0
  28. package/src/docs/doc-topics.mjs +38 -0
  29. package/src/docs/index.mjs +10 -0
  30. package/src/targets/target-registry.mjs +38 -0
  31. package/targets/nes/lib/fcnes.lib +0 -0
  32. package/targets/nes/lib/nes-font.o +0 -0
  33. package/targets/sb2000/api-reference.md +3295 -0
  34. package/targets/sb2000/api-unwrapped.json +36 -0
  35. package/targets/sb2000/asminc/sb2000.inc +203 -1
  36. package/targets/sb2000/include/sb2000-bank.h +74 -0
  37. package/targets/sb2000/include/sb2000-clock.h +68 -0
  38. package/targets/sb2000/include/sb2000-disk.h +141 -0
  39. package/targets/sb2000/include/sb2000-display.h +352 -0
  40. package/targets/sb2000/include/sb2000-file.h +273 -0
  41. package/targets/sb2000/include/sb2000-ime.h +158 -0
  42. package/targets/sb2000/include/sb2000-input.h +192 -0
  43. package/targets/sb2000/include/sb2000-math.h +228 -0
  44. package/targets/sb2000/include/sb2000-memory.h +115 -0
  45. package/targets/sb2000/include/sb2000-printer.h +116 -0
  46. package/targets/sb2000/include/sb2000-sound.h +134 -0
  47. package/targets/sb2000/include/sb2000-symbols.h +397 -1
  48. package/targets/sb2000/include/sb2000-system.h +219 -0
  49. package/targets/sb2000/include/sb2000-text.h +99 -0
  50. package/targets/sb2000/include/sb2000.h +13 -20
  51. package/targets/sb2000/lib/crt0.o +0 -0
  52. package/targets/sb2000/lib/sb2000.lib +0 -0
  53. package/targets/sb2000/lib-build.json +1 -1
  54. package/targets/sb2000/link-banked.cfg +42 -0
  55. package/targets/sb2000/src/crt0.s +89 -4
  56. package/targets/sb2000/src/lib/bank/sb-bank-current.c +18 -0
  57. package/targets/sb2000/src/lib/bank/sb-bank-select.c +21 -0
  58. package/targets/sb2000/src/lib/bank/sbi-bank-trampoline.s +46 -0
  59. package/targets/sb2000/src/lib/clock/sb-clock-get-date.c +17 -0
  60. package/targets/sb2000/src/lib/clock/sb-clock-get-time.c +17 -0
  61. package/targets/sb2000/src/lib/clock/sb-clock-set-date.c +21 -0
  62. package/targets/sb2000/src/lib/clock/sb-clock-set-time.c +17 -0
  63. package/targets/sb2000/src/lib/clock/sbi-date-from-fat.c +20 -0
  64. package/targets/sb2000/src/lib/clock/sbi-date-to-fat.c +24 -0
  65. package/targets/sb2000/src/lib/clock/sbi-time-from-fat.c +20 -0
  66. package/targets/sb2000/src/lib/clock/sbi-time-to-fat.c +19 -0
  67. package/targets/sb2000/src/lib/disk/sb-disk-format-track.c +18 -0
  68. package/targets/sb2000/src/lib/disk/sb-disk-free-bytes.c +38 -0
  69. package/targets/sb2000/src/lib/disk/sb-disk-init.c +16 -0
  70. package/targets/sb2000/src/lib/disk/sb-disk-read-sector.c +24 -0
  71. package/targets/sb2000/src/lib/disk/sb-disk-read-sectors.c +17 -0
  72. package/targets/sb2000/src/lib/disk/sb-disk-scan-track.c +27 -0
  73. package/targets/sb2000/src/lib/disk/sb-disk-start.c +16 -0
  74. package/targets/sb2000/src/lib/disk/sb-disk-stop.c +16 -0
  75. package/targets/sb2000/src/lib/disk/sb-disk-write-sector.c +19 -0
  76. package/targets/sb2000/src/lib/disk/sb-disk-write-sectors.c +17 -0
  77. package/targets/sb2000/src/lib/disk/sbi-disk-batch.c +23 -0
  78. package/targets/sb2000/src/lib/disk/sbi-disk-call.c +17 -0
  79. package/targets/sb2000/src/lib/disk/sbi-disk-set-position.c +18 -0
  80. package/targets/sb2000/src/lib/display/sb-cell-address.c +20 -0
  81. package/targets/sb2000/src/lib/display/sb-cells-copy.c +27 -0
  82. package/targets/sb2000/src/lib/display/sb-cells-fill.c +25 -0
  83. package/targets/sb2000/src/lib/display/sb-cells-rect.c +20 -0
  84. package/targets/sb2000/src/lib/display/sb-display-mode.c +16 -0
  85. package/targets/sb2000/src/lib/display/sb-glyph-address.c +28 -0
  86. package/targets/sb2000/src/lib/display/sb-image-fill-rect.c +26 -0
  87. package/targets/sb2000/src/lib/display/sb-image-load-raw.c +22 -0
  88. package/targets/sb2000/src/lib/display/sb-image-show-full.c +20 -0
  89. package/targets/sb2000/src/lib/display/sb-image-show.c +25 -0
  90. package/targets/sb2000/src/lib/display/sb-image-unpack-map.c +28 -0
  91. package/targets/sb2000/src/lib/display/sb-image-unpack-tiles.c +20 -0
  92. package/targets/sb2000/src/lib/display/sb-image-unpack-to-memory.c +22 -0
  93. package/targets/sb2000/src/lib/display/sb-palette-write.c +20 -0
  94. package/targets/sb2000/src/lib/display/sb-screen-clear.c +19 -0
  95. package/targets/sb2000/src/lib/display/sb-screen-flush.c +16 -0
  96. package/targets/sb2000/src/lib/display/sb-text-draw.c +22 -0
  97. package/targets/sb2000/src/lib/display/sb-text-field-ascii.c +25 -0
  98. package/targets/sb2000/src/lib/display/sb-text-field.c +25 -0
  99. package/targets/sb2000/src/lib/display/sb-text-to-memory.c +27 -0
  100. package/targets/sb2000/src/lib/display/sb-vram-bank.c +17 -0
  101. package/targets/sb2000/src/lib/display/sb-vram-fill.c +21 -0
  102. package/targets/sb2000/src/lib/display/sb-vram-load.c +21 -0
  103. package/targets/sb2000/src/lib/display/sb-window-compact.c +16 -0
  104. package/targets/sb2000/src/lib/display/sb-window-init.c +16 -0
  105. package/targets/sb2000/src/lib/display/sb-window-restore.c +17 -0
  106. package/targets/sb2000/src/lib/display/sb-window-save.c +21 -0
  107. package/targets/sb2000/src/lib/file/sb-dir-change.c +21 -0
  108. package/targets/sb2000/src/lib/file/sb-dir-current.c +27 -0
  109. package/targets/sb2000/src/lib/file/sb-dir-make.c +21 -0
  110. package/targets/sb2000/src/lib/file/sb-dir-open.c +61 -0
  111. package/targets/sb2000/src/lib/file/sb-dir-read.c +87 -0
  112. package/targets/sb2000/src/lib/file/sb-dir-remove.c +21 -0
  113. package/targets/sb2000/src/lib/file/sb-file-close.c +21 -0
  114. package/targets/sb2000/src/lib/file/sb-file-delete.c +21 -0
  115. package/targets/sb2000/src/lib/file/sb-file-get-attr.c +25 -0
  116. package/targets/sb2000/src/lib/file/sb-file-get-date.c +25 -0
  117. package/targets/sb2000/src/lib/file/sb-file-get-time.c +25 -0
  118. package/targets/sb2000/src/lib/file/sb-file-load.c +50 -0
  119. package/targets/sb2000/src/lib/file/sb-file-open.c +26 -0
  120. package/targets/sb2000/src/lib/file/sb-file-read.c +52 -0
  121. package/targets/sb2000/src/lib/file/sb-file-rename.c +30 -0
  122. package/targets/sb2000/src/lib/file/sb-file-save.c +31 -0
  123. package/targets/sb2000/src/lib/file/sb-file-set-attr.c +22 -0
  124. package/targets/sb2000/src/lib/file/sb-file-set-date.c +25 -0
  125. package/targets/sb2000/src/lib/file/sb-file-set-time.c +22 -0
  126. package/targets/sb2000/src/lib/file/sb-file-size.c +27 -0
  127. package/targets/sb2000/src/lib/file/sb-file-write-all.c +32 -0
  128. package/targets/sb2000/src/lib/file/sb-file-write.c +60 -0
  129. package/targets/sb2000/src/lib/file/sbi-dir-state.c +15 -0
  130. package/targets/sb2000/src/lib/file/sbi-dos-call.c +17 -0
  131. package/targets/sb2000/src/lib/file/sbi-load-sector.c +18 -0
  132. package/targets/sb2000/src/lib/file/sbi-select-handle.c +20 -0
  133. package/targets/sb2000/src/lib/file/sbi-set-path.c +26 -0
  134. package/targets/sb2000/src/lib/ime/sb-ime-get-method.c +17 -0
  135. package/targets/sb2000/src/lib/ime/sb-ime-get-state.c +18 -0
  136. package/targets/sb2000/src/lib/ime/sb-ime-hex.c +20 -0
  137. package/targets/sb2000/src/lib/ime/sb-ime-init.c +26 -0
  138. package/targets/sb2000/src/lib/ime/sb-ime-key-wait.c +19 -0
  139. package/targets/sb2000/src/lib/ime/sb-ime-key.c +19 -0
  140. package/targets/sb2000/src/lib/ime/sb-ime-parse.c +23 -0
  141. package/targets/sb2000/src/lib/ime/sb-ime-resume.c +16 -0
  142. package/targets/sb2000/src/lib/ime/sb-ime-select.c +19 -0
  143. package/targets/sb2000/src/lib/ime/sb-ime-set-state.c +18 -0
  144. package/targets/sb2000/src/lib/ime/sb-ime-set-width.c +16 -0
  145. package/targets/sb2000/src/lib/ime/sb-ime-suspend.c +16 -0
  146. package/targets/sb2000/src/lib/input/sb-break-disable.c +16 -0
  147. package/targets/sb2000/src/lib/input/sb-break-enable.c +16 -0
  148. package/targets/sb2000/src/lib/input/sb-key-count.c +17 -0
  149. package/targets/sb2000/src/lib/input/sb-key-flush.c +16 -0
  150. package/targets/sb2000/src/lib/input/sb-key-init.c +16 -0
  151. package/targets/sb2000/src/lib/input/sb-key-modifiers.c +16 -0
  152. package/targets/sb2000/src/lib/input/sb-key-poll.c +17 -0
  153. package/targets/sb2000/src/lib/input/sb-key-wait.c +17 -0
  154. package/targets/sb2000/src/lib/input/sb-keyboard-reset.c +17 -0
  155. package/targets/sb2000/src/lib/input/sb-mouse-buttons.c +21 -0
  156. package/targets/sb2000/src/lib/input/sb-mouse-position.c +18 -0
  157. package/targets/sb2000/src/lib/input/sb-mouse-reset.c +17 -0
  158. package/targets/sb2000/src/lib/input/sb-mouse-set-double-click.c +17 -0
  159. package/targets/sb2000/src/lib/input/sb-mouse-set-limits.c +26 -0
  160. package/targets/sb2000/src/lib/input/sb-mouse-set-position.c +18 -0
  161. package/targets/sb2000/src/lib/input/sb-pad-init.c +17 -0
  162. package/targets/sb2000/src/lib/input/sb-pad-poll.c +17 -0
  163. package/targets/sb2000/src/lib/input/sb-pad-state.c +16 -0
  164. package/targets/sb2000/src/lib/input/sb-pad-wait.c +17 -0
  165. package/targets/sb2000/src/lib/math/sb-float-add.c +19 -0
  166. package/targets/sb2000/src/lib/math/sb-float-div.c +19 -0
  167. package/targets/sb2000/src/lib/math/sb-float-from-text.c +18 -0
  168. package/targets/sb2000/src/lib/math/sb-float-mul.c +19 -0
  169. package/targets/sb2000/src/lib/math/sb-float-sub.c +19 -0
  170. package/targets/sb2000/src/lib/math/sb-float-to-text.c +19 -0
  171. package/targets/sb2000/src/lib/math/sb-int24-add.c +21 -0
  172. package/targets/sb2000/src/lib/math/sb-int24-div.c +26 -0
  173. package/targets/sb2000/src/lib/math/sb-int24-mul.c +20 -0
  174. package/targets/sb2000/src/lib/math/sb-int24-sub.c +21 -0
  175. package/targets/sb2000/src/lib/math/sb-int40-from-text.c +19 -0
  176. package/targets/sb2000/src/lib/math/sb-int40-to-text.c +27 -0
  177. package/targets/sb2000/src/lib/math/sb-line-step.c +21 -0
  178. package/targets/sb2000/src/lib/math/sb-math-div16.c +27 -0
  179. package/targets/sb2000/src/lib/math/sb-math-time-text.c +21 -0
  180. package/targets/sb2000/src/lib/math/sb-random-next.c +20 -0
  181. package/targets/sb2000/src/lib/math/sb-random-seed.c +19 -0
  182. package/targets/sb2000/src/lib/math/sb-random-warm-up.c +16 -0
  183. package/targets/sb2000/src/lib/math/sbi-peek.c +20 -0
  184. package/targets/sb2000/src/lib/math/sbi-poke.c +20 -0
  185. package/targets/sb2000/src/lib/memory/sb-address-to-far.c +20 -0
  186. package/targets/sb2000/src/lib/memory/sb-far-read-byte.c +17 -0
  187. package/targets/sb2000/src/lib/memory/sb-far-read.c +36 -0
  188. package/targets/sb2000/src/lib/memory/sb-far-write-byte.c +17 -0
  189. package/targets/sb2000/src/lib/memory/sb-far-write.c +36 -0
  190. package/targets/sb2000/src/lib/memory/sb-page-alloc.c +19 -0
  191. package/targets/sb2000/src/lib/memory/sb-page-free.c +19 -0
  192. package/targets/sb2000/src/lib/memory/sb-page-largest-free.c +17 -0
  193. package/targets/sb2000/src/lib/memory/sb-window-map-group.c +17 -0
  194. package/targets/sb2000/src/lib/memory/sb-window-map.c +18 -0
  195. package/targets/sb2000/src/lib/memory/sbi-far-copy-in.s +17 -0
  196. package/targets/sb2000/src/lib/memory/sbi-far-copy-out.s +17 -0
  197. package/targets/sb2000/src/lib/memory/sbi-far-read-byte.s +19 -0
  198. package/targets/sb2000/src/lib/memory/sbi-far-write-byte.s +17 -0
  199. package/targets/sb2000/src/lib/printer/sb-printer-carriage-return.c +16 -0
  200. package/targets/sb2000/src/lib/printer/sb-printer-feed.c +17 -0
  201. package/targets/sb2000/src/lib/printer/sb-printer-graphics-mode.c +16 -0
  202. package/targets/sb2000/src/lib/printer/sb-printer-home.c +16 -0
  203. package/targets/sb2000/src/lib/printer/sb-printer-init-port.c +16 -0
  204. package/targets/sb2000/src/lib/printer/sb-printer-page-left.c +16 -0
  205. package/targets/sb2000/src/lib/printer/sb-printer-page-length.c +17 -0
  206. package/targets/sb2000/src/lib/printer/sb-printer-position.c +18 -0
  207. package/targets/sb2000/src/lib/printer/sb-printer-reset.c +16 -0
  208. package/targets/sb2000/src/lib/printer/sb-printer-send-byte.c +18 -0
  209. package/targets/sb2000/src/lib/printer/sb-printer-text.c +29 -0
  210. package/targets/sb2000/src/lib/sb-internal.h +111 -0
  211. package/targets/sb2000/src/lib/sound/sb-sound-effect-from.c +19 -0
  212. package/targets/sb2000/src/lib/sound/sb-sound-play-from.c +18 -0
  213. package/targets/sb2000/src/lib/sound/sb-sound-play-wav-from.c +18 -0
  214. package/targets/sb2000/src/lib/sound/sb-sound-play-wav.c +16 -0
  215. package/targets/sb2000/src/lib/sound/sb-sound-repeat-wav-from.c +19 -0
  216. package/targets/sb2000/src/lib/sound/sb-sound-status.c +17 -0
  217. package/targets/sb2000/src/lib/sound/sb-sound-stop.c +16 -0
  218. package/targets/sb2000/src/lib/sound/sb-sound-tempo.c +17 -0
  219. package/targets/sb2000/src/lib/sound/sb-sound-transpose.c +17 -0
  220. package/targets/sb2000/src/lib/sound/sb-speech-off.c +16 -0
  221. package/targets/sb2000/src/lib/sound/sb-speech-send-entry-from.c +21 -0
  222. package/targets/sb2000/src/lib/sound/sb-speech-send-from.c +19 -0
  223. package/targets/sb2000/src/lib/sound/sb-speech-send.c +16 -0
  224. package/targets/sb2000/src/lib/system/sb-call-banked.c +19 -0
  225. package/targets/sb2000/src/lib/system/sb-context-restore.c +16 -0
  226. package/targets/sb2000/src/lib/system/sb-context-save.c +19 -0
  227. package/targets/sb2000/src/lib/system/sb-display-off.c +16 -0
  228. package/targets/sb2000/src/lib/system/sb-display-on.c +16 -0
  229. package/targets/sb2000/src/lib/system/sb-display-option.c +18 -0
  230. package/targets/sb2000/src/lib/system/sb-exec.c +22 -0
  231. package/targets/sb2000/src/lib/system/sb-irq-enable.c +19 -0
  232. package/targets/sb2000/src/lib/system/sb-irq-hook-reset.c +20 -0
  233. package/targets/sb2000/src/lib/system/sb-irq-hook-set.c +39 -0
  234. package/targets/sb2000/src/lib/system/sb-irq-mask.c +19 -0
  235. package/targets/sb2000/src/lib/system/sb-jump-banked.s +25 -0
  236. package/targets/sb2000/src/lib/system/sb-nmi-disable.c +16 -0
  237. package/targets/sb2000/src/lib/system/sb-nmi-enable.c +16 -0
  238. package/targets/sb2000/src/lib/system/sb-nmi-hook-reset.c +20 -0
  239. package/targets/sb2000/src/lib/system/sb-nmi-hook-set.c +33 -0
  240. package/targets/sb2000/src/lib/system/sb-nmi-service.c +19 -0
  241. package/targets/sb2000/src/lib/system/sb-stack-pointer.s +18 -0
  242. package/targets/sb2000/src/lib/system/sb-system-init.c +16 -0
  243. package/targets/sb2000/src/lib/system/sb-system-state.c +20 -0
  244. package/targets/sb2000/src/lib/system/sb-wait-frames.s +19 -0
  245. package/targets/sb2000/src/lib/system/sbi-exec-run.s +43 -0
  246. package/targets/sb2000/src/lib/system/sbi-interrupts-off.s +19 -0
  247. package/targets/sb2000/src/lib/system/sbi-interrupts-restore.s +17 -0
  248. package/targets/sb2000/src/lib/text/sb-beep.c +16 -0
  249. package/targets/sb2000/src/lib/text/sb-cursor-column.c +16 -0
  250. package/targets/sb2000/src/lib/text/sb-cursor-left.c +16 -0
  251. package/targets/sb2000/src/lib/text/sb-cursor-right.c +16 -0
  252. package/targets/sb2000/src/lib/text/sb-cursor-row.c +16 -0
  253. package/targets/sb2000/src/lib/text/sb-cursor-set-column.c +18 -0
  254. package/targets/sb2000/src/lib/text/sb-cursor-up.c +16 -0
  255. package/targets/sb2000/src/lib/text/sb-print-hex.c +22 -0
  256. package/targets/sb2000/src/lib/text/sb-print-uint.c +25 -0
  257. package/targets/sb2000/src/lib/text/sb-print.c +35 -0
  258. package/targets/sb2000/src/lib/text/sb-putc.c +26 -0
  259. package/targets/sb2000/src/sb2000.s +0 -3
  260. package/targets/sb2000/target.json +14 -0
@@ -0,0 +1,100 @@
1
+ # 模拟器与调试
2
+
3
+ `fcdev` 自带一个调试用模拟器:VirtuaNES 的改造版,带调试服务,能运行 NES 游戏,以及 SB2000 等学习机的固件与程序。它的源码在本仓库的 `virtuanes/` 目录,由本仓库维护;构建脚本把它编成平台包 `@rujianjs/fcdev-emulator-win32-x64` 随 npm 发布。模拟器的改动清单见 [virtuanes/README.md](https://gitee.com/sungbin/fcdev/blob/master/virtuanes/README.md),调试服务的命令表见第 5.1 节。
4
+
5
+ ## 1. 模拟器包
6
+
7
+ - 只支持 Windows(Win32、DirectX)。许可证 GPL-3.0-only,包里附许可文件与 `SOURCE.txt`(写明源码仓库、目录、提交和编译命令)。
8
+ - 模拟器是 32 位程序,`bin/` 里随带 `vcruntime140.dll`、`msvcp140.dll`(应用本地部署)。
9
+ - 包内容:`bin/VirtuaNES.exe`、`bin/Chinese.vlp`、两个运行库、`LICENSE`、`SOURCE.txt`、`manifest.json`、`package.json`。入库的只有 `package.json` 与 `SOURCE.txt`,其余是生成物。
10
+ - 模拟器运行时会在 `bin/` 里写 `VirtuaNES.ini` 与 `save/`,发布前要删除;`release-check` 会把它们当作清单之外的文件报错。
11
+
12
+ 构建:
13
+
14
+ ```bash
15
+ node tools/build-emulator.mjs
16
+ ```
17
+
18
+ [tools/build-emulator.mjs](https://gitee.com/sungbin/fcdev/blob/master/tools/build-emulator.mjs) 只能在 Windows 上运行,需要 Visual Studio(含“使用 C++ 的桌面开发”)。它调用 `virtuanes/build.ps1 -Configuration Release`,把 `VirtuaNES.exe` 与 `Chinese.vlp` 复制进 `bin/`,再用 `vswhere` 找到 Visual Studio 里 32 位的 VC++ 运行库一并放入,最后写 `LICENSE`、`SOURCE.txt`、`manifest.json`(当前提交、`virtuanes/` 有无未提交改动 `sourceDirty`、各文件的 SHA-256)与 `package.json`。编译前先关闭正在运行的模拟器。
19
+
20
+ ## 2. 定位模拟器
21
+
22
+ 按顺序查找,找到即停:
23
+
24
+ 1. 配置项 `emulator`。
25
+ 2. 环境变量 `FCDEV_EMULATOR`。
26
+ 3. 平台包 `@rujianjs/fcdev-emulator-<系统>-<架构>` 里的 `bin/VirtuaNES.exe`。
27
+
28
+ 指定的路径不存在时报“找不到模拟器”。不是 Windows 且没有指定自备模拟器时报“模拟器只支持 Windows”,构建不受影响;自备的模拟器需要支持同样的调试服务才能用调试命令。
29
+
30
+ ## 3. `fcdev run`
31
+
32
+ 先构建,再按目标的运行方案启动模拟器。目标没有运行方案时报错。
33
+
34
+ | 运行方案 | 做法 |
35
+ | --- | --- |
36
+ | `rom` | 模拟器直接加载产物,不需要固件;没有 `--debug` 时启动后立即返回 |
37
+ | `firmware-disk` | 要求 `fcdev.json` 配置 `firmware`;构建并生成磁盘镜像,以调试模式启动模拟器,依次发 `disk <镜像>`、`reset`、`live`;等 DOS 启动后在提示符下输入程序名 |
38
+
39
+ - `--debug` 时不发 `live`,模拟器停在调试服务,只在收到 `run` 命令时运行;`firmware-disk` 方案总是以调试模式启动,因为要用调试服务挂载镜像。
40
+ - `--port` 指定调试端口,默认 5699。
41
+ - 调试模式启动前先检查端口是否被占用,被占用就报错,不去连接,避免连到别的模拟器;启动后最多等 30 秒,等到调试服务回应 `running=1`,超时则结束模拟器进程并报错。
42
+ - 模拟器进程与命令行脱离,命令行退出后窗口保持打开,工作目录是模拟器所在目录(语言包按相对文件名加载)。
43
+ - 非调试模式下沿用模拟器的单实例规则:已有普通模拟器窗口时,会把程序交给它打开。
44
+
45
+ ## 4. `fcdev debug`
46
+
47
+ ```bash
48
+ fcdev debug run 60
49
+ fcdev debug shot screen.png
50
+ ```
51
+
52
+ - 把命令原样转发给调试服务,打印应答;应答首行以 `OK` 开头时退出码为 0,否则为 1。
53
+ - 端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
54
+ - 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save` 的前缀;`off` 不处理;`disk` 的路径可含空格,取剩余全部。
55
+ - `run`、`step` 的应答超时是 10 分钟,其余命令 30 秒。
56
+
57
+ ## 5. 调试服务协议
58
+
59
+ - 模拟器只在设置了环境变量 `FCDEV_DEBUG_PORT` 时启动调试服务,只监听 `127.0.0.1`。
60
+ - 一行一个命令;应答若干行文本,以单独的 `.` 行结束;应答首行以 `OK` 或 `ERR` 开头。一次只处理一条命令。
61
+ - 客户端在 [src/emulator/debug-client.mjs](../src/emulator/debug-client.mjs):`DebugClient.connect` 连接(5 秒超时),`send` 发命令并等应答。
62
+ - `fcdev` 只经这套协议与模拟器通信,协议保持稳定;以后把内核集成进 VS Code 时,只要协议不变,`fcdev` 不用改。
63
+ - 命令表见下面的第 5.1 节。`live` 命令由 `fcdev` 新增:把模拟器切换为自由运行,供 `fcdev run` 把窗口交给用户操作。
64
+
65
+ ### 5.1 命令表
66
+
67
+ 直接发给服务的路径必须是绝对路径;数字默认按十六进制解析(地址、扫描码、寄存器),帧数、长度、次数按十进制。
68
+
69
+ | 命令 | 说明 |
70
+ | --- | --- |
71
+ | `status` | 运行状态、寄存器与 bank 寄存器 |
72
+ | `run <帧数>` | 运行指定帧数,遇到断点提前停止 |
73
+ | `step <条数>` | 单步指定条数的指令 |
74
+ | `bp x\|r\|w <地址> [结束地址]` | 添加执行、读、写断点;`bp list`、`bp del <编号\|all>` |
75
+ | `regs [pc=.. a=.. x=.. y=.. s=.. p=..]` | 读取或修改寄存器 |
76
+ | `read <空间> <地址> <长度>` | 读内存;空间为 `cpu`、`rom`、`pram`、`vram`、`cram`、`eram`、`wram`、`ram` |
77
+ | `write <空间> <地址> <十六进制字节>` | 写内存 |
78
+ | `resolve <地址>` | 把 CPU 地址解析为物理空间与偏移 |
79
+ | `key <扫描码> <0\|1>`、`key clear` | 按下或松开键盘键(DirectInput 扫描码) |
80
+ | `mouse move <dx> <dy>`、`mouse btn <掩码>` | 鼠标移动与按键 |
81
+ | `shot <文件.png>` | 截图 |
82
+ | `trace <文件> [最大行数]`、`trace off` | 记录每条指令与中断 |
83
+ | `io <文件> [最大行数] [w]`、`io off` | 记录 `$2000-$4FFF` 的读写;加 `w` 只记录写 |
84
+ | `pad <0-3> <十六进制掩码>`、`pad <0-3> clear` | 注入手柄按键(A=01、B=02、Select=04、Start=08、上=10、下=20、左=40、右=80),与真实输入合并 |
85
+ | `disklog <文件> [最大行数]`、`disklog off` | 记录软驱控制器读写的 LBA |
86
+ | `calllog <文件> <pc> <地址:长度[,...]> [最大次数] [skip=地址=值[,...]]`、`calllog off` | 每次执行到 `pc` 就记录寄存器、栈顶与内存段;`skip` 表示该地址字节等于值(十六进制)时不记录;可添加多条,`off` 全部关闭 |
87
+ | `cdl on\|off\|clear\|save <前缀>` | 代码数据标记,保存为 `<前缀>-rom.cdl`、`<前缀>-pram.cdl` |
88
+ | `disk <镜像>`、`savedisk` | 挂载或保存软盘镜像 |
89
+ | `fdc eject\|insert\|wp <0\|1>\|noindex <0\|1>\|seekfail <0\|1>\|dead <0\|1>\|bad <逻辑扇区...>\|clear\|status` | 软驱故障注入。`eject`、`insert` 取出、放回盘片(取出后控制器对 READ ID 报找不到地址标志);`wp` 写保护;`noindex` 没有索引脉冲(READ ID、读写、格式化命令一直不结束);`seekfail` 磁头卡住(SEEK、RECALIBRATE 不移动,已在 0 磁道时回 0 磁道仍成功);`dead` 控制器收到命令字节后不再处理;`bad` 指定的逻辑扇区(十进制)读时报数据校验错,写不受影响;`clear` 关闭全部故障、放回盘片并取消写保护;`status` 显示当前状态。`disk` 挂载新镜像时也会清掉全部故障 |
90
+ | `audio fast\|real` | 声音播放速度:`fast` 时语音与 DAC(开机音乐、WAV)不再等声卡按真实时间播放,采样直接丢弃,模拟器内部时序不变;`real` 为默认的真实时间。开关是全局状态,复位后保持;验证工具只在开机阶段打开,开机完成后恢复 |
91
+ | `reset`、`softreset`、`savestate <文件>`、`loadstate <文件>` | `reset` 是硬复位(回到 BIOS),`softreset` 只复位 CPU、手柄与 APU、保留映射器状态(游戏中的软复位);另有状态存取 |
92
+ | `live` | 切换为自由运行:模拟器按正常速度连续运行,不再由 `run` 授权帧数;此后只建议使用 `key`、`pad`、`mouse`、`shot`、`quit`,读写内存与断点类命令与模拟线程并行,结果不可靠。`fcdev run` 用它把窗口交给用户操作 |
93
+ | `quit` | 关闭模拟器 |
94
+
95
+ ## 6. 对 `virtuanes/` 的约定
96
+
97
+ - 改动处按文件头约定标明,改动清单写在 `virtuanes/README.md` 的“相对上游的改动”。
98
+ - 调试模式(设置了 `FCDEV_DEBUG_PORT`)下,`WinMain.cpp` 不把命令行转交给已运行的实例,调试模式的模拟器可以与用户平时用的普通实例同时运行。
99
+ - `WinMain.cpp` 含 Shift-JIS 编码的内容,不要用编辑工具整体改写。
100
+ - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供。
@@ -0,0 +1,103 @@
1
+ # 反汇编
2
+
3
+ `fcdev disasm` 把 NES 程序或平铺二进制反汇编成 `ca65` 可直接汇编的源码,并保证汇编回去后与原映像逐字节一致。代码在 `packages/fcdev/src/disasm/`。
4
+
5
+ ## 1. 做法
6
+
7
+ 指令解码与源码文本输出交给 cc65 自带的 `da65`,不改 `da65` 的 C 代码;前端脚本负责分析,并把分析结果写成 `da65` 的信息文件。只有实测发现信息文件无法表达时,才修改 `da65` 的 C 源码,并把每处修改写进 `cc65/README-FCDEV.txt`。
8
+
9
+ 流程(`disassembler.mjs`):
10
+
11
+ 1. 读取输入,判断格式,取出映像(字节、第一个字节的地址、中断向量)。
12
+ 2. 收集入口:中断向量、`--entry`、`--trace` 里的地址、CDL 里每段连续代码的起点。没有任何入口时报错。
13
+ 3. 静态追踪,标出每个字节是指令的操作码、操作数还是未知。
14
+ 4. 生成 `da65` 信息文件。
15
+ 5. 运行 `da65 -i <信息文件> --multi-pass`,得到 ca65 源码。
16
+ 6. 回读校验:用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较;不一致就报错,指出第一个差异的偏移与地址,不输出“成功”。
17
+
18
+ ## 2. 命令
19
+
20
+ ```bash
21
+ fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
22
+ ```
23
+
24
+ | 选项 | 说明 |
25
+ | --- | --- |
26
+ | `--format ines\|binary` | 输入格式;缺省时按文件头判断,以 `NES` 加 `$1A` 开头为 iNES,否则为平铺二进制 |
27
+ | `--base <地址>` | 平铺二进制的加载地址,十六进制,可带 `$` 或 `0x`;平铺二进制必须给 |
28
+ | `--entry <地址>` | 追踪代码的入口,可重复;iNES 自动使用中断向量 |
29
+ | `--cdl <文件>` | CDL 文件,其中代码段的起点也当作入口 |
30
+ | `--trace <文件>` | 模拟器 `trace` 命令记录的指令轨迹,执行过的指令地址都当作入口 |
31
+ | `--symbols <文件>` | 符号文件,给地址起名字 |
32
+ | `--out <目录>` | 输出目录,默认 `build/disasm/<输入文件名>` |
33
+
34
+ 平铺二进制要有入口:用 `--entry`,或用 `--cdl`、`--trace` 提供运行记录;不会自动取程序头部的 `JMP`。
35
+
36
+ 输出目录里的文件:
37
+
38
+ | 文件 | 内容 |
39
+ | --- | --- |
40
+ | `<名>.bin` | 反汇编的映像(iNES 只含 PRG) |
41
+ | `<名>.info` | `da65` 信息文件 |
42
+ | `<名>.s` | ca65 源码 |
43
+ | `<名>.roundtrip.*` | 回读用的目标文件、链接配置与结果 |
44
+
45
+ `<名>` 取输入文件名(不含扩展名),非字母、数字、下划线、连字符的字符换成下划线。回读不一致时这些文件仍然保留。命令成功时输出映像大小、指令条数与字节数,以及“回读校验通过”;追踪中放弃某一路的警告最多显示 10 条。
46
+
47
+ ## 3. 输入
48
+
49
+ ### 3.1 映像
50
+
51
+ - iNES:只支持映射器 0(NROM),PRG 为 16K 或 32K。32K 映在 `$8000`,16K 映在 `$C000`;跳过 trainer;从 PRG 末尾读出 NMI、复位、IRQ 三个向量。其他映射器报错,可先导出某个 bank,用 `--format binary` 并指定加载地址。
52
+ - 平铺二进制:按 `--base` 放置,不得超出 `$FFFF`,不能为空。
53
+
54
+ ### 3.2 CDL
55
+
56
+ 每个字节一个标志,位 0 表示被当作代码执行过,位 1 表示被当作数据读取过。支持 FCEUX 与 Mesen 的格式;Mesen CDLv2 开头多出的 9 个字节会自动跳过;只取与 PRG 对应的前 PRG 大小个字节,比 PRG 短时报错。
57
+
58
+ ### 3.3 指令轨迹
59
+
60
+ 模拟器 `trace` 命令的日志,每行以 `T` 开头,第二列是指令地址。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。
61
+
62
+ ### 3.4 符号文件
63
+
64
+ 每行“名字 = 地址”或“名字 地址”,地址为十六进制,可带 `$` 或 `0x`;以 `;` 或 `#` 开头的行是注释,空行忽略。名字必须是合法的 ca65 标识符。同一地址有多个名字时只用第一个。中断向量对应的地址自动命名为 `reset`、`nmi`、`irq`。
65
+
66
+ 信息文件里总是引入 NES 的 `fcnes.inc`,所以 PPU 寄存器地址会显示成符号名;对平铺二进制也一样。
67
+
68
+ ## 4. 静态追踪
69
+
70
+ 规则(`analysis.mjs`):
71
+
72
+ - 顺序执行继续;条件分支两路都追;`JMP` 只追目标;`JSR` 追目标并假定会返回。
73
+ - `RTS`、`RTI`、`BRK` 与间接 `JMP` 结束这一路。
74
+ - 遇到非法操作码、超出映像末尾或与已识别的指令重叠时,放弃这一路并记入警告。
75
+ - 没被追到的字节都按数据输出,这不影响回读校验。
76
+
77
+ 指令表在 `opcode-table.mjs`,共 151 条官方指令,数据取自 `da65` 的 `cc65/src/da65/opc6502.c`;非官方(非法)操作码不在表里。
78
+
79
+ ## 5. 信息文件
80
+
81
+ `info-writer.mjs` 把整个映像划分成首尾相接、互不重叠的段,没有遗漏,否则 `da65` 会把没说明的字节默认当成代码:
82
+
83
+ | 段类型 | 用于 |
84
+ | --- | --- |
85
+ | `Code` | 追踪到的指令 |
86
+ | `ByteTable` | 没被追到的字节 |
87
+ | `AddrTable` | iNES 末尾 6 字节的中断向量表 |
88
+
89
+ 另有 `GLOBAL`(输入输出文件名、起始地址、CPU)、`ASMINC`(符号定义文件)与 `LABEL`(用户符号与中断向量名)。
90
+
91
+ ## 6. 验证与限制
92
+
93
+ 验证(见 [08-测试与验证](08-测试与验证.md)):`fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥,由环境变量 `FCDEV_TEST_NES_ROM` 提供)回读都与原文件逐字节一致。静态追踪追不到 `RTS` 跳转表与间接调用,所以马里奥只追到约 2320 字节代码,其余按数据输出,回读仍一致;补充 CDL 或 `trace` 能扩大覆盖。
94
+
95
+ 限制:
96
+
97
+ - iNES 只支持 NROM。
98
+ - 不识别例程内联的跳转表,也不把数据识别成地址表或字符串,未追到的字节都是 `ByteTable`。
99
+ - 模拟器自带的 CDL 只对 SB2K 映射器有效。
100
+ - SB2000 固件页的 CDL 验证没有做。
101
+ - `da65` 输出的源码是 CRLF 换行。
102
+
103
+ 以后要做的项目登记在 [待办备忘](待办备忘.md)。
@@ -0,0 +1,74 @@
1
+ # 创建包与模板
2
+
3
+ `create-fcdev` 是 `npm create fcdev` 运行的包:在空目录生成开发结构与示例程序,之后用 `npm run build` 构建。代码在 `packages/create-fcdev/`,只依赖 Node,不引入其他依赖。
4
+
5
+ ## 1. 命令
6
+
7
+ ```bash
8
+ npm create fcdev@latest [目录] [-- 选项]
9
+ ```
10
+
11
+ | 选项 | 说明 |
12
+ | --- | --- |
13
+ | `[目录]` | 默认当前目录,`.` 表示当前目录;不存在时会创建 |
14
+ | `--target <名>` | 目标,如 `nes`、`sb2000`;缺省时交互询问 |
15
+ | `--template <语言>` | `c` 或 `asm`;缺省时交互询问 |
16
+ | `--no-install` | 不运行 `npm install` 与 `npm run sync` |
17
+ | `-h`、`--help` | 显示帮助 |
18
+ | `-v`、`--version` | 显示版本 |
19
+
20
+ - 交互用 `node:readline`,让用户输入序号或名称选择;输入不合法时重新询问,同一问题最多 3 次。
21
+ - 不能交互(例如在脚本里)又没同时给出 `--target` 与 `--template` 时报错。
22
+ - 目标目录必须为空(允许已有 `.git`),否则报错退出,不覆盖已有文件。
23
+ - 没有该目标与语言的模板时报错,并列出可用的目标。
24
+
25
+ ## 2. 流程
26
+
27
+ 1. 解析参数,确定目标与语言。
28
+ 2. 检查目录并复制模板,写入公共文件、`package.json` 与 `fcdev.json`。
29
+ 3. 没有 `--no-install` 时运行 `npm install`,再运行 `npm run sync` 生成 IDE 配置;任何一步失败都报错,项目文件已经生成,提示用户在目录里手动重试。
30
+ 4. 打印下一步命令,以及模板里的补充说明。
31
+
32
+ 模板内置在创建包里,不从网络下载。
33
+
34
+ ## 3. 生成的项目
35
+
36
+ ```text
37
+ <项目>/
38
+ package.json 名称取目录名;scripts: build、start、sync(模板的 template.json 声明了额外脚本时再加,目前 SB2000 模板有 disk);devDependencies 的 fcdev 与创建包同版本
39
+ fcdev.json { "target": "...", "name": "hello" }
40
+ .gitignore node_modules/、build/、compile_flags.txt、.vscode/c_cpp_properties.json
41
+ README.md 该模板的使用说明,其中的 {{name}} 换成项目名
42
+ src/hello.c 或 src/hello.s
43
+ ```
44
+
45
+ - 脚本:`build` 是 `fcdev build src`,`start` 是 `fcdev run src`,`sync` 是 `fcdev sync`,SB2000 模板另有 `disk` 是 `fcdev disk src`。
46
+ - 包名由目录名转小写,非法字符换成连字符;没有可用字符时用 `fcdev-app`。
47
+ - 程序名固定为 `hello`,同时是 `fcdev.json` 的 `name`,也是 DOS 里要输入的命令。
48
+ - `.gitignore` 在模板里叫 `gitignore`(不带点),因为 npm 发布时会丢掉 `.gitignore`,生成项目时改名。
49
+ - `.vscode/c_cpp_properties.json` 与 `compile_flags.txt` 由 `fcdev sync` 生成,含本机路径,所以被忽略。
50
+
51
+ ## 4. 模板
52
+
53
+ 每个模板是 `templates/<目标>-<语言>/` 目录,包含:
54
+
55
+ | 文件 | 说明 |
56
+ | --- | --- |
57
+ | `template.json` | `target`、`language`、`title`,可选 `scripts`(额外的 npm 脚本)与 `notes`(创建完成后提示的说明);目录名必须等于 `<target>-<language>` |
58
+ | `README.md` | 生成项目的说明,可用 `{{name}}`;末尾有“文档”一节,写明开发文档随 `fcdev` 安装在 `node_modules/fcdev/docs/`,并给出对应目标的 `npx fcdev docs <主题>` |
59
+ | `src/hello.c` 或 `src/hello.s` | 示例程序 |
60
+
61
+ 目录名以 `_` 开头的是公共文件目录,不是模板,目前只有 `_common/gitignore`。
62
+
63
+ 四个模板:
64
+
65
+ | 模板 | hello world |
66
+ | --- | --- |
67
+ | `nes-c` | 设置调色板,`nes_print` 在屏幕中间显示 `HELLO, NES!`,打开画面后死循环 |
68
+ | `nes-asm` | 同样的行为,汇编直接写 PPU 寄存器,`.include "fcnes.inc"`,导出 `_main` |
69
+ | `sb2000-c` | `sb_puts` 显示英文与中文(GB2312)各一行,`sb_getkey` 等键后返回 |
70
+ | `sb2000-asm` | 同样的行为,汇编调用 `_sb_puts`、`_sb_getkey`,导出 `_main` |
71
+
72
+ ## 5. 新增模板
73
+
74
+ 新增机型的目标后,在 `templates/` 下加 `<目标>-c` 与 `<目标>-asm` 两个目录,写 `template.json`、`README.md` 与示例程序;目标需要额外脚本或提示时写进 `template.json`。模板必须能用 `fcdev build` 构建成功,`npm run release:verify` 会逐个验证,见 [09-发布](09-发布.md)。
@@ -0,0 +1,72 @@
1
+ # 测试与验证
2
+
3
+ 本文说明测试的分层、运行方法和用到的环境变量。测试用 Node 内置的 `node:test`,不引入测试框架。
4
+
5
+ ## 1. 运行
6
+
7
+ | 命令 | 作用 |
8
+ | --- | --- |
9
+ | `npm test` | 运行全部测试;运行前自动执行 `npm run build:libs` 编译各目标的运行库 |
10
+ | `npm run boundaries` | 检查主包的分层依赖,见 [01-软件架构设计](01-软件架构设计.md) 第 5 节 |
11
+ | `npm run check` | 依赖边界检查加测试 |
12
+ | `npm run release:check` | 发布前检查,见 [09-发布](09-发布.md) |
13
+ | `npm run release:verify` | 打包后在临时目录里创建、安装并构建四个模板 |
14
+
15
+ 测试文件在 `packages/fcdev/test/`、`packages/create-fcdev/test/` 与仓库根的 `test/`,文件名以 `.test.mjs` 结尾。
16
+
17
+ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;在 `vscode/` 目录运行 `npm run check`,见 [10-VS Code扩展](10-VS%20Code扩展.md) 第 5 节。
18
+
19
+ 找不到 cc65 工具链时,需要真实工具的用例会跳过,并在跳过说明里写明原因;纯逻辑的用例不受影响。
20
+
21
+ ## 2. 环境变量
22
+
23
+ | 变量 | 作用 |
24
+ | --- | --- |
25
+ | `FCDEV_CC65_HOME` | 指向自备的 cc65 目录;没有平台包时用它跑集成测试 |
26
+ | `FCDEV_EMULATOR` | 指向自备的模拟器 |
27
+ | `FCDEV_TEST_FIRMWARE` | 指向 SB2000 的 BIOS 文件;设置后额外运行“SB2000 程序在模拟器里运行”的用例(仓库不提供 BIOS) |
28
+ | `FCDEV_TEST_NES_ROM` | 指向一个 NROM 的 `.nes` 文件;设置后额外对它做完整反汇编与回读 |
29
+ | `FCDEV_SKIP_GUI_TESTS` | 设为 `1` 时跳过会打开模拟器窗口的用例 |
30
+
31
+ ## 3. 测试分层
32
+
33
+ | 层次 | 文件 | 内容 |
34
+ | --- | --- | --- |
35
+ | 单元测试 | `args-parser`、`config`、`build-helpers`、`targets-packagers`、`fat12-image` | 参数解析、配置查找与未知项报错、源文件收集、依赖文件解析、工具参数、目标字段校验、程序名规则、各打包器、FAT12 镜像 |
36
+ | 命令行与构建 | `cli`、`build`、`toolchain` | 帮助、版本、错误输出与退出码、`build`、`info`、`sync`;构建计划的路径规则;增量与错误提示;工具链定位的优先级与不完整报错 |
37
+ | 目标 | `sb2000`(主包) | 构建 C 与汇编程序,文件头、大小与内存布局,运行库一个函数一个目标文件、链接只带用到的函数,多页程序的文件页序、库页不够与超过上限的提示,`disk` 命令,缺少固件的提示 |
38
+ | 模拟器 | `emulator`、`sb2000`、`sb2000-library` | 调试客户端的应答解析与超时、模拟器定位、端口检查、`debug` 命令的路径换算;真实模拟器里运行 NES 程序并截图;设置固件后运行 SB2000 程序,以及运行库每个模块的测试程序(约 15 个用例,共数百项检查,文件与磁盘类用例把镜像读回核对;换页的用例覆盖 9 个库页与上限 113 个库页),见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节 |
39
+ | 反汇编 | `disasm` | 映像读取、CDL 与轨迹解析、静态追踪、信息文件、回读校验;对 `fcdev` 自己构建的 NES 与 SB2000 程序做完整反汇编;设置 `FCDEV_TEST_NES_ROM` 时对真实游戏做反汇编 |
40
+ | 创建包 | `create`(`create-fcdev`) | 参数解析、模板列表、项目生成、目录检查、交互选择、安装流程;四个模板都能用 `fcdev` 构建 |
41
+ | 接口文档 | `api-command`(主包)、`sb2000-api`(仓库) | `fcdev api` 命令的各种查询与错误提示、头文件文档注释的解析、系统调用标签的匹配;SB2000 接口检查(函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因);入库的 `api-reference.md` 与头文件生成的结果一致 |
42
+ | 仓库 | `cc65-tools`、`sb2000-header`、`structure` | `cc65/` 里的必要路径与平台包的校验值;入库的 `sb2000-symbols.h` 与生成结果一致;分层检查对违规的识别 |
43
+ | 文档 | `docs-command`(主包) | `fcdev docs` 命令的列表、按主题名、文件名与关键词查询、`--json`、错误提示;文档主题登记与 `docs/` 目录里的文件一一对应(包内其他位置的登记项文件必须存在),主题名合法且不重复,架构文档的文档清单列全了每个主题 |
44
+
45
+ 集成测试用真实的 cc65 构建四个模板,检查产物头部与大小。
46
+
47
+ ## 4. 模拟器验证
48
+
49
+ - NES hello 与 SB2000 的 C、汇编 hello 在模拟器里运行,用调试服务的 `shot` 命令截图,核对屏幕文字:NES 显示 `HELLO, NES!`,SB2000 显示 `Hello, SB2000!` 与“你好,小霸王!”并能返回 DOS。
50
+ - SB2000 的程序运行环境验证(V01 到 V10)的结论见 [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) 第 9 节。
51
+ - 运行库测试程序的停靠点用写断点实现(对全局变量 `sb_test_stop` 设断点),不对函数入口设执行断点,原因见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节。
52
+ - 用调试服务验证时一律显式指定端口,避免连到别的模拟器;只结束本仓库启动的模拟器进程。
53
+
54
+ ## 5. 反汇编验证
55
+
56
+ `fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥)回读后都与原文件逐字节一致,详见 [06-反汇编](06-反汇编.md) 第 6 节。
57
+
58
+ ## 6. 安装验证
59
+
60
+ `npm run release:verify`([tools/verify-install.mjs](https://gitee.com/sungbin/fcdev/blob/master/tools/verify-install.mjs)):
61
+
62
+ 1. 把四个包用 `npm pack` 打成 `.tgz`。
63
+ 2. 在临时目录里从本地 `.tgz` 安装 `create-fcdev`,不访问 npm 仓库,也不执行 `npm publish`。
64
+ 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev` 与两个平台包,运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
65
+ 4. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
66
+
67
+ 只验证构建,不启动模拟器。
68
+
69
+ ## 7. 注意事项
70
+
71
+ - 带真实模拟器的用例运行后会在模拟器平台包的 `bin/` 里生成 `VirtuaNES.ini` 与 `save/`;发布前必须删除,`release:check` 会把它们当作清单之外的文件报错。
72
+ - 没有目测的界面输出,汇报时写明。
@@ -0,0 +1,67 @@
1
+ # 发布
2
+
3
+ 本文说明四个 npm 包的发布顺序、前提、检查和元数据。npm 的登录与 `npm publish` 由用户执行,不在代码或文档里记录任何凭据。
4
+
5
+ ## 1. 包与版本
6
+
7
+ | 包 | 说明 |
8
+ | --- | --- |
9
+ | `@rujianjs/fcdev-cc65-win32-x64` | 工具链平台包,目录 `packages/fcdev-cc65-win32-x64` |
10
+ | `@rujianjs/fcdev-emulator-win32-x64` | 模拟器平台包,目录 `packages/fcdev-emulator-win32-x64` |
11
+ | `fcdev` | 主包,对两个平台包写精确版本的 `optionalDependencies` |
12
+ | `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
13
+
14
+ - 四个包同一个版本号,由 `release-check` 检查;`fcdev` 对平台包的依赖版本必须与之相同。
15
+ - 两个平台包的包名带 `@rujianjs` 作用域,目录名不带。作用域包默认不能公开发布,所以它们的 `package.json` 写了 `publishConfig.access` 为 `public`,`release-check` 会检查这一项,以及平台包的包名是否都在 `fcdev` 的 `optionalDependencies` 里。
16
+ - 平台包不带作用域的名字发布时被 npm 的垃圾包名检测拦截(403),所以改用作用域,见 [01-软件架构设计](01-软件架构设计.md) 的 D02。
17
+ - 两个平台包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs` 与 `node tools/build-emulator.mjs`。
18
+ - 每个包的 `package.json` 写 `license`、`repository`、`engines`(`node >=22`)、`files`。作者与邮箱为 `sungbin`、`sungbin@3578.cn`,仓库地址为 `https://gitee.com/sungbin/fcdev.git`。
19
+
20
+ ## 2. 发布前提
21
+
22
+ 1. 所有改动已提交。
23
+ 2. 在已提交的状态下重新运行 `node tools/build-emulator.mjs`,使模拟器平台包清单里的 `sourceDirty` 为 `false`。`sourceDirty` 只看 `virtuanes/` 目录有没有未提交的改动,构建脚本重写 `SOURCE.txt`(记录新的提交号)不会让它变成 `true`。
24
+ 3. 平台包都已构建:`node tools/build-cc65.mjs`、`node tools/build-emulator.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
25
+ 4. 模拟器平台包的 `bin/` 里没有 `VirtuaNES.ini` 与 `save/`,见 [08-测试与验证](08-测试与验证.md) 第 7 节。
26
+ 5. `npm run release:check` 不带 `--allow-dirty` 通过。
27
+
28
+ ## 3. 检查
29
+
30
+ `npm run release:check`([tools/release-check.mjs](https://gitee.com/sungbin/fcdev/blob/master/tools/release-check.mjs))只检查,不修改任何文件,也不执行 `npm publish`:
31
+
32
+ - 四个包的版本一致,都写了 `license`,`fcdev` 对平台包的依赖版本一致;平台包的包名都在 `fcdev` 的依赖里,作用域包声明了公开发布。
33
+ - 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
34
+ - `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
35
+ - 两个平台包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
36
+ - 模拟器清单的 `sourceDirty` 为 `true` 时报错;加 `--allow-dirty` 降为警告,只用于发布前的演练。
37
+ - 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
38
+
39
+ `npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
40
+
41
+ ## 4. 发布顺序
42
+
43
+ 先发工具链与模拟器平台包,再发 `fcdev`,最后发 `create-fcdev`:
44
+
45
+ 1. `@rujianjs/fcdev-cc65-win32-x64`
46
+ 2. `@rujianjs/fcdev-emulator-win32-x64`
47
+ 3. `fcdev`
48
+ 4. `create-fcdev`
49
+
50
+ `npm publish` 需要先登录 npm,可能还要二次验证。可以先对每个包运行 `npm publish --dry-run`,核对内容清单与体积。
51
+
52
+ ## 5. 包的体积
53
+
54
+ `npm publish --dry-run` 的结果(版本 0.1.0):
55
+
56
+ | 包 | 文件数 | 包大小 |
57
+ | --- | --- | --- |
58
+ | `fcdev` | 71 | 64 kB |
59
+ | `create-fcdev` | 23 | 15 kB |
60
+ | `@rujianjs/fcdev-cc65-win32-x64` | 223 | 1.9 MB(解压 6.2 MB) |
61
+ | `@rujianjs/fcdev-emulator-win32-x64` | 8 | 0.7 MB(解压 1.8 MB) |
62
+
63
+ 体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
64
+
65
+ ## 6. 其他平台
66
+
67
+ 首批只发布 `win32-x64`。`darwin-arm64`、`linux-x64` 的构建脚本相同,但没有在这些系统上运行或验证;验证后再发布,发布前主包不列出它们,见 [待办备忘](待办备忘.md)。
@@ -0,0 +1,131 @@
1
+ # VS Code 扩展
2
+
3
+ 扩展放在仓库的 `vscode/` 目录,包名 `fcdev`,显示名“fcdev 6502 开发”。首版做 ca65 汇编的语法高亮,以及 ca65 汇编与 cc65 的 C 的智能感知。扩展不内置编译器,只经 `node_modules` 里的 `fcdev` 命令行读取项目信息。
4
+
5
+ ## 1. 范围
6
+
7
+ 首版包含:
8
+
9
+ - ca65 汇编(`.s`、`.asm`、`.inc`)的悬停、补全、转到定义、文档符号。
10
+ - C 代码的智能感知:自动运行 `fcdev sync`,让 C/C++ 扩展与 clangd 找到 cc65 的头文件与宏。
11
+ - 头文件里符号与函数的文档注释(`/** */`),悬停时显示。
12
+ - ca65 汇编的语法高亮(TextMate 语法)。C 用 VS Code 内置的 C 语法,不另提供。
13
+
14
+ 首版不含,登记在 [待办备忘](待办备忘.md):任务与问题匹配器、构建与运行命令、新建项目、调试。
15
+
16
+ ## 2. 语言支持的分工
17
+
18
+ | 语言 | 由谁提供 | 做法 |
19
+ | --- | --- | --- |
20
+ | C | VS Code 的 C/C++ 扩展或 clangd | 本扩展运行 `fcdev sync`,生成 `.vscode/c_cpp_properties.json` 与 `compile_flags.txt`,里面有头文件目录与预定义宏 |
21
+ | 汇编 | 本扩展 | 自己解析 ca65 源码,不依赖其他扩展 |
22
+
23
+ 本扩展的 `package.json` 用 `extensionPack` 带上 C/C++ 扩展(`ms-vscode.cpptools`),安装本扩展时一并安装;用户仍可单独卸载它,改用 clangd。
24
+
25
+ C 的头文件注释用 Doxygen 的 `/** */` 写法,C/C++ 扩展与 clangd 都会在悬停时显示;`sb2000-symbols.h` 里每个常量宏上方的注释由 `tools/gen-sb2000-header.mjs` 从 `sb2000.inc` 的行尾注释生成。
26
+
27
+ ### 2.1 C 的配置同步
28
+
29
+ | 触发 | 行为 |
30
+ | --- | --- |
31
+ | 扩展激活(工作区里有 `fcdev.json`) | 同步所有工作区文件夹里的 fcdev 项目 |
32
+ | 工作区文件夹增减 | 同步 |
33
+ | `fcdev.json` 新建或修改 | 丢弃该项目的信息缓存,合并 500 毫秒内的连续变化后同步该项目 |
34
+ | 命令“fcdev:同步 C/C++ 智能感知配置” | 手动同步,带进度,结束后弹出结果;没有 fcdev 项目时提示 |
35
+
36
+ 自动同步只写日志,失败也不弹提示;日志在“输出”面板的 fcdev 通道。设置 `fcdev.intelliSense.autoSync`(默认开启)可关闭自动同步。
37
+
38
+ `fcdev sync` 的预定义宏里带 `__fastcall__`、`__cdecl__` 两个空宏:cc65 的头文件用它们标注调用约定,C/C++ 扩展与 clangd 不认识,不定义会报语法错误。这两个宏只出现在 `info` 与 `sync` 的输出里,不参与构建。
39
+
40
+ #### 提示选择配置
41
+
42
+ C/C++ 扩展用哪个配置,只保存在它自己的工作区状态里,其他扩展无法读写,所以本扩展不能自动切换到 `fcdev` 配置。`.vscode/c_cpp_properties.json` 里除 `fcdev` 外还有其他配置时(例如名为 `Win32` 的默认配置),C/C++ 扩展可能选的不是 `fcdev`,这时 cc65 的头文件不会生效。扩展在同步成功后检查这个文件,条件满足时弹出提示:
43
+
44
+ - 提示带“选择配置”按钮,点击后运行 C/C++ 扩展的命令 `C_Cpp.ConfigurationSelect`,由用户在列表里点选 `fcdev`。
45
+ - 只在安装了 C/C++ 扩展(`ms-vscode.cpptools`)时提示;只用 clangd 的项目不受影响。
46
+ - 每个项目每次 VS Code 会话只提示一次;在同一次同步里有多个项目时合并成一条。
47
+ - 设置 `fcdev.intelliSense.promptConfigurationSelection`(默认开启)可关闭提示。
48
+ - 只检查同步成功的项目;读取配置文件出错只写日志,不影响同步。
49
+
50
+ ### 2.2 汇编
51
+
52
+ | 功能 | 行为 |
53
+ | --- | --- |
54
+ | 悬停 | 6502 指令:功能、影响的标志位、寻址方式的写法与字节数;ca65 伪指令:写法与说明;符号:定义写法、种类、常量的值(同时给出十进制、十六进制与二进制)、源码里的说明注释、所在分组与文件行号 |
55
+ | 补全 | 指令助记符、伪指令(输入 `.` 触发)、局部标签(输入 `@` 触发)、可见的符号 |
56
+ | 转到定义 | 标签、常量、宏等符号跳到定义处;同名定义在同一范围内有多处时全部列出 |
57
+ | 文档符号 | 大纲与面包屑里列出标签、常量、`.define`、宏、`.proc`、`.scope`、`.struct`、`.enum` |
58
+
59
+ 可见的符号来自:
60
+
61
+ 1. 当前文件,含局部标签与未保存的修改;名字重名时优先取这里的定义。
62
+ 2. 当前文件 `.include` 的文件,最多展开 8 层;路径先按当前文件所在目录找,再按 `fcdev info --json` 给出的汇编引入目录找(含目标的 `asminclude`,所以 `sb2000.inc` 的符号能直接看到)。
63
+ 3. 工作区里其他汇编文件里的非局部符号。
64
+
65
+ 后两项读自磁盘并缓存;汇编文件变化时,丢弃该文件的解析缓存与工作区文件列表。扩展不理解条件汇编的取舍,`.if` 里的符号都会被收集。
66
+
67
+ ### 2.3 汇编的语法高亮
68
+
69
+ 语法文件是 `syntaxes/ca65.tmLanguage.json`,作用域名 `source.ca65`,对 `.s`、`.asm`、`.inc` 生效。它按行匹配,不理解上下文,所以只靠行首位置和固定词表分类。
70
+
71
+ | 内容 | 作用域 |
72
+ | --- | --- |
73
+ | `;` 注释 | `comment.line.semicolon.ca65` |
74
+ | `"..."`、`'...'` 字符串(行尾自动结束,字符串里的分号不算注释) | `string.quoted.double.ca65`、`string.quoted.single.ca65` |
75
+ | 行首的标签定义(`name:`、`@local:`、`name::`),行首的 `:` 匿名标签 | `entity.name.function.label.ca65`、`entity.name.function.label.anonymous.ca65` |
76
+ | 行首的常量定义(`NAME = 值`、`NAME := 值`) | `variable.other.constant.ca65` |
77
+ | `.proc`、`.macro` 后的名字;`.scope`、`.struct`、`.enum` 后的名字 | `entity.name.function.ca65`、`entity.name.type.ca65` |
78
+ | `.if` 系列、`.else`、`.elseif`、`.endif` | `keyword.control.conditional.ca65` |
79
+ | 伪函数(`.defined`、`.sizeof`、`.lobyte` 等) | `support.function.pseudo.ca65` |
80
+ | 其他以 `.` 开头的汇编指令 | `keyword.other.directive.ca65` |
81
+ | 分支、跳转、返回指令(`bcc`、`jmp`、`jsr`、`rts`、`brk` 等) | `keyword.control.flow.ca65` |
82
+ | 其他 6502 指令 | `keyword.other.mnemonic.ca65` |
83
+ | `asl a` 等的累加器、`,x`、`,y` | `variable.language.register.ca65` |
84
+ | `$` 十六进制、`%` 二进制、十进制数 | `constant.numeric.hex.ca65`、`constant.numeric.binary.ca65`、`constant.numeric.decimal.ca65` |
85
+ | `#` 立即数标记 | `keyword.operator.immediate.ca65` |
86
+ | `@name` 局部标签引用、`:+`、`:-` 匿名标签引用 | `variable.other.local.ca65`、`variable.other.anonymous.ca65` |
87
+
88
+ - 指令与汇编指令不分大小写。
89
+ - 标签定义要求冒号紧跟在名字后面,行首 `bne :+` 因此不会被当成标签。
90
+ - 宏的调用与不在词表里的标识符不着色,因为单行匹配无法区分它们与符号。
91
+ - 指令词表与 [指令参考](https://gitee.com/sungbin/fcdev/blob/master/vscode/src/shared/assembly/instruction-reference.ts)、[伪指令参考](https://gitee.com/sungbin/fcdev/blob/master/vscode/src/shared/assembly/directive-reference.ts) 的覆盖,由 `test/syntaxes/ca65-grammar.test.ts` 逐条检查。
92
+
93
+ ## 3. 项目信息的来源
94
+
95
+ 扩展经 `node <项目根>/node_modules/fcdev/bin/fcdev.mjs` 调用命令行,不经 shell,不依赖全局安装。
96
+
97
+ | 命令 | 用途 |
98
+ | --- | --- |
99
+ | `fcdev info --json` | 读取目标、头文件目录、汇编引入目录与预定义宏;每个项目缓存一份,`fcdev.json` 变化后失效 |
100
+ | `fcdev sync` | 生成 C/C++ 扩展的配置 |
101
+
102
+ 项目没有安装 `fcdev` 或命令失败时,汇编智能感知只用当前文件与工作区里的源码,引入目录里的符号看不到;原因写在日志里,不弹提示。
103
+
104
+ ## 4. 目录与分层
105
+
106
+ 按分层组织,层内再按功能分目录,具体类只在组装根创建:
107
+
108
+ | 目录 | 职责 |
109
+ | --- | --- |
110
+ | `src/contracts` | 接口:汇编智能感知服务、汇编源文件存取、C 配置同步服务、C/C++ 配置检查器、命令行执行器、项目信息提供者 |
111
+ | `src/shared` | 纯函数与数据:ca65 解析、行内词法、数字格式、指令与伪指令参考、悬停文字、项目信息与 c_cpp_properties.json 的解析 |
112
+ | `src/logic` | 业务:符号解析(含 `.include` 展开)、汇编智能感知服务、C 配置同步服务 |
113
+ | `src/infra` | 与外部交互:读工作区文件、调用命令行、查找项目、读取 c_cpp_properties.json |
114
+ | `src/entry` | VS Code 入口:四个汇编提供者、命令与文件监视器 |
115
+ | `src/platform` | 日志(输出通道) |
116
+ | `src/bootstrap` | 组装根 `extension.ts` |
117
+ | `syntaxes` | ca65 的 TextMate 语法文件(静态资源,不经分层) |
118
+
119
+ - 层之间的依赖方向、文件头、注释宽度与 `package.json` 声明和代码的一致性,由 `test/structure.test.ts` 检查。
120
+ - 各层之间只经 `contracts` 里的接口协作;只有 `entry`、`platform`、`infra` 可以引用 `vscode`。
121
+
122
+ ## 5. 构建、测试与打包
123
+
124
+ 在 `vscode/` 目录运行:
125
+
126
+ | 命令 | 用途 |
127
+ | --- | --- |
128
+ | `npm run check` | 类型检查、oxlint、测试、构建 |
129
+ | `npm run package` | 生成 `.vsix`(不入库);发布到应用市场需要发布者账号,由用户操作 |
130
+
131
+ 测试在 Node 环境里运行,`vscode` 模块用 `test/support/vscode-mock.ts` 替代;入口层的测试验证提供者与命令的行为,真实 VS Code 里的显示效果要手动打开项目核对。语法文件的测试用开发依赖 `vscode-textmate` 与 `vscode-oniguruma` 真实加载语法并分词,不依赖 VS Code;颜色由用户的主题决定,只检查作用域名。
@@ -0,0 +1,52 @@
1
+ # NES 目标
2
+
3
+ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它之上加了一个辅助库 `fcnes` 和 ASCII 字库,使 hello 程序保持单文件。目标目录是 [packages/fcdev/targets/nes](../../targets/nes),字段含义见 [03-目标规范](../03-目标规范.md)。
4
+
5
+ ## 1. 目标定义
6
+
7
+ | 项 | 值 |
8
+ | --- | --- |
9
+ | 目标名 | `nes` |
10
+ | `cc65Target` | `nes` |
11
+ | 链接配置 | `toolchain:cfg/nes.cfg` |
12
+ | 启动代码 | 无,用 `nes.lib` 自带的;`forceImports` 为 `__STARTUP__`,保证纯汇编程序也链接启动代码 |
13
+ | 库 | `lib/fcnes.lib`、`toolchain:lib/nes.lib` |
14
+ | 打包器 | `ines`,产物 `.nes` |
15
+ | 程序名规则 | 不限制 |
16
+ | 磁盘镜像 | 不支持 |
17
+ | 运行方案 | `rom`,不需要固件 |
18
+
19
+ ## 2. 内存与映射器
20
+
21
+ 只支持 `nes.cfg` 的 NROM:16K PRG(`$8000` 起)加 8K CHR,`$FFFA` 起是中断向量。cc65 参数栈 3 页,在 `$0500` 起;`DATA` 装入 ROM,运行时复制到 `$6000` 起的 8K RAM;`BSS` 也在这块 RAM。其他映射器不在首批范围。
22
+
23
+ ## 3. 头文件与函数
24
+
25
+ - C 程序用 `cc65` 的 `nes.h` 和本目标的 `fcnes.h`,汇编程序用 `fcnes.inc`,它定义 PPU 寄存器地址 `PPUCTRL`、`PPUMASK`、`PPUSTATUS`、`OAMADDR`、`OAMDATA`、`PPUSCROLL`、`PPUADDR`、`PPUDATA`。
26
+ - 文字用 ASCII 字库,图块号等于字符码,背景图案表为 `$0000`;画面关闭时才能写显存。
27
+
28
+ `fcnes.h` 的函数:
29
+
30
+ | 函数 | 作用 |
31
+ | --- | --- |
32
+ | `void nes_screen_off(void)` | 关闭画面,之后可以写显存 |
33
+ | `void nes_screen_on(void)` | 打开背景与精灵显示(含最左 8 列),并把滚动位置复位到 (0, 0) |
34
+ | `void __fastcall__ nes_set_palette(const unsigned char *colors)` | 写入 32 字节调色板:前 16 字节为背景,后 16 字节为精灵 |
35
+ | `void __fastcall__ nes_print(unsigned char x, unsigned char y, const char *s)` | 在名称表 (x, y) 处写零结尾字符串,x 为 0 到 31,y 为 0 到 29;要先关闭画面 |
36
+ | `void nes_wait_vblank(void)` | 等待下一次垂直消隐开始 |
37
+
38
+ 汇编程序可直接调用对应的 `_nes_*` 符号,参数约定是 cc65 的 `fastcall`:最后一个参数在 A(低字节)与 X(高字节),其余参数在 C 栈上,由被调用者弹出。
39
+
40
+ ## 4. 字库
41
+
42
+ - 字库数据来自公有领域的 `font8x8_basic`(Daniel Hepper,源自 IBM 公共领域 VGA 字体),原文件保留在 `chr/font8x8_basic.h`,已转成 `chr/ascii-8x8.chr`(ASCII `$20` 到 `$7F` 的 8×8 字模,共 1536 字节)。
43
+ - `src/nes-font.s` 把字库放进 `CHARS` 段:前 `$200` 字节留空(对应 `$20` 之前的 32 个图块),之后是字模。
44
+ - 目标选项 `font`(布尔,默认 `true`)为 `true` 时链接 `lib/nes-font.o`。在 `fcdev.json` 里写 `"targetOptions": { "font": false }` 可关闭,由程序自己提供 CHR 数据。
45
+
46
+ ## 5. 运行库
47
+
48
+ `lib-build.json` 把 `src/fcnes.s` 编成 `lib/fcnes.lib`,把 `src/nes-font.s` 编成 `lib/nes-font.o`,`.incbin` 的搜索目录是 `chr`。构建方法见 [03-目标规范](../03-目标规范.md) 第 5 节。
49
+
50
+ ## 6. 运行
51
+
52
+ `fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。