|
@@ -1,3 +1,234 @@
|
|
|
# binary2sharp-mz-700-tape-wav
|
|
|
|
|
|
-A simple convert program for converting binary file into SHARP MZ-700 Tape wave file.
|
|
|
+A simple convert program for converting binary file into SHARP MZ-700 Tape wave file.
|
|
|
+
|
|
|
+## 中文文档
|
|
|
+
|
|
|
+### 版本说明 & ChangeLog
|
|
|
+
|
|
|
+目前是第一个发布的版本。
|
|
|
+
|
|
|
+本程序是按照
|
|
|
+[这篇文档](https://www.sharpmz.no/articles/the-mz-series/mz-80/mz-80-knowhow/mz-80-tape-data-structure/)
|
|
|
+制作的,在SHARP MZ-700上测试过,MZ-80A/B/K和MZ-800未测试(作者没有这些机器)。
|
|
|
+
|
|
|
+### 命令行说明
|
|
|
+
|
|
|
+命令行具有的子命令: `simple` `from-yaml` `example-yaml` `convert-ascii` `help`
|
|
|
+
|
|
|
+其中`simple`可简写作`s`, `from-yaml`可简写作`fy`,`example-yaml`可简写作`ey`,
|
|
|
+`convert-yaml`可简写作`ca`。
|
|
|
+具体可以所以`help`命令或者`-h`全局标志查看程序内置的命令行帮助说明。
|
|
|
+
|
|
|
+用户接口设计逻辑:
|
|
|
+
|
|
|
+* `simple`子命令提供最基础的将一个二进制文件制作成SHARP MZ Tape的音频文件的功能。
|
|
|
+* 如果需要更复杂的高级功能,需要写一个yaml格式配置文件代替命令行参数输入,并使用`from-yaml`命令,
|
|
|
+程序将根据yaml文件进行磁带音频生成。
|
|
|
+* 使用`example-yaml`命令,可以提供和`simple`命令相同的命令行标志,生成一个样例yaml文件
|
|
|
+* 使用`convert-ascii`命令可以对文本文件在MZ-700 ASCII和标准ASCII之间进行转换。
|
|
|
+
|
|
|
+在本帮助文档中暂时不对每一条命令行参数进行详解,只是说明一下使用的思路和提供几个例子。
|
|
|
+具体的每个命令行参数请使用`-h`标志查询。`-h`中所说`See documentation`的部分请看本文档的附录。
|
|
|
+
|
|
|
+以下是使用说明。
|
|
|
+
|
|
|
+#### 概念解释
|
|
|
+
|
|
|
+**输出文件:** 输出的磁带WAV文件,可以录制成磁带通过SHARP MZ系列机器加载,
|
|
|
+或者通过其它方式替输入到机器中。
|
|
|
+
|
|
|
+**目标机器:** 生成的输出文件应用到的机器型号。支持的机器列表见[附录](#支持的机器列表)。
|
|
|
+
|
|
|
+**磁带文件:** 注意同`输出文件`区别。在SHARP MZ系列机器的磁带格式设计中,存在`文件`的概念。
|
|
|
+一盘磁带中可以录制一个或多个磁带文件,每个文件具有`HEADER`信息,
|
|
|
+在本文档中我们称之为`元数据`,`元数据`描述了磁带文件的文件属性、文件名等信息。
|
|
|
+一盘磁带可以有多个文件,但是,在MZ系列机器的`MONITOR`程序(例如MZ-700的`1Z-013A`)
|
|
|
+中执行命令`L`(或者`LOAD`)一次只会加载一个文件,磁带便会暂停。如果磁带中录制了多个文件,
|
|
|
+您可能需要自己编写一个LOADER程序将它们全部加载,然后将LOADER程序作为第一个文件,
|
|
|
+在MONITOR执行`L`命令后会加载和运行这个LOADER程序以加载所有文件。
|
|
|
+本文档中暂时不详细介绍具体实现的方式,如果后续有时间可能会增补这部分内容至本文档附录。
|
|
|
+
|
|
|
+**元数据:** 在上一条目`磁带文件`中已经提到。
|
|
|
+
|
|
|
+**文件类型:** 指定该磁带文件的类型。存储在元数据中。
|
|
|
+SHARP官方定义的文件类型列表见[附录](#SHARP官方规定的文件类型列表)。
|
|
|
+
|
|
|
+**磁带文件名:** 磁带文件的文件名。最长17字节。
|
|
|
+
|
|
|
+**加载地址:** 磁带文件被加载到的存储器地址。
|
|
|
+
|
|
|
+**执行地址:** 使用MONTIOR程序的`L`命令加载磁带文件,加载完成后,
|
|
|
+MONITOR程序将跳转到该地址。MONITOR程序一定会在加载完成后进行跳转,
|
|
|
+所以如果您想加载完磁带文件后回到MONITOR程序,
|
|
|
+需要跳转到MONITOR程序的Warm Start Subroutine(在MZ-700上是0x00AD)。
|
|
|
+如果想在加载完成后RESET,跳转到0x0000。
|
|
|
+
|
|
|
+**文件注释:** 在元数据内有一段104字节的注释区,可用于自定义用途。
|
|
|
+
|
|
|
+#### 基本的转换
|
|
|
+
|
|
|
+一个很经典的例子:
|
|
|
+
|
|
|
+```
|
|
|
+bin2mz700wav simple -o test.wav --mt mz-700 \
|
|
|
+ --fa 01 --fn TestTape --la 0x1200 --ea 0x1200 --in hello.bin -v
|
|
|
+```
|
|
|
+
|
|
|
+使用以上命令行可以将hello.bin转换成MZ-700磁带音频文件。
|
|
|
+使用磁带时,MZ-700将会将hello.bin的内容加载到0x1200,
|
|
|
+加载完成后从0x1200开始执行。
|
|
|
+
|
|
|
+* `simple`是子命令名,也可以简写作`s`。
|
|
|
+* `-o test.wav`指定输出文件为`test.wav`,若不指定,默认是`tape.wav`
|
|
|
+* `--mt mz-700`指定目标机器型号为`mz-700`,`--mt`标志是`--machine`的简写。
|
|
|
+见[附录](#支持的机器列表)。若不指定该标志,默认是`mz-700`。
|
|
|
+* `--fa 01`指定磁带文件的类型。使用十六进制表示,范围00~FF,无需前缀0x或后缀h。
|
|
|
+`--fa`是`--file-attrib`的简写。
|
|
|
+SHARP官方定义的文件类型列表见[附录](#SHARP官方规定的文件类型列表)。
|
|
|
+* `--fn TestTape`指定磁带文件名为`TestTape`,`--fn`是`--file-name`的简写。
|
|
|
+* `--la 0x1200`指定加载地址为0x1200。支持十进制、十六进制、八进制、二进制。
|
|
|
+不指定前后缀默认为十进制,指定前缀`0x`或后缀`H`则为十六进制,
|
|
|
+指定后缀`O`则为八进制,指定后缀`B`则为二进制。`--la`是`--load-addr`的简写。
|
|
|
+* `--ea 0x1200`指定执行地址为0x1200,执行地址概念详见[概念解释](#概念解释),
|
|
|
+若不指定该标志,则该地址被指定为MONITOR程序的Warm Start Subrountine。
|
|
|
+* `--in hello.bin`指定磁带文件的数据来自`hello.bin`。
|
|
|
+来自您计算机上的该文件将被转换到磁带文件中。
|
|
|
+* 使用`-v`标志,程序将在转换过程中在标准输出打印出详细的信息。
|
|
|
+`-v`是`--verbose`的简写。
|
|
|
+
|
|
|
+一个很简单的例子:
|
|
|
+
|
|
|
+```
|
|
|
+bin2mz700wav s --fa 01 --fn TestTape --la 0x1200 --in hello.bin
|
|
|
+```
|
|
|
+
|
|
|
+以上例子大部分标志参数都使用了默认值。
|
|
|
+
|
|
|
+#### 使用YAML配置文件
|
|
|
+
|
|
|
+如果您需要生成较复杂的输出文件,例如包含多个磁带文件的输出文件,
|
|
|
+您需要编写YAML配置文件,并使用`from-yaml`子命令从YAML配置生成输出文件。
|
|
|
+
|
|
|
+例子:
|
|
|
+
|
|
|
+```
|
|
|
+bin2mz700wav fy --yaml test.yaml
|
|
|
+```
|
|
|
+
|
|
|
+YAML的每个字段的说明,将在后续完善,本次发布的文档暂未完成这部分的编写。
|
|
|
+
|
|
|
+您可以使用`example-yaml`子命令生成一示例YAML文件,并编辑修改。
|
|
|
+
|
|
|
+`example-yaml`子命令的标志参数和`simple`子命令基本一致,
|
|
|
+但是需要指定`--yaml`标志指定输出YAML文件的文件名,以及,没有`--verbose`标志。
|
|
|
+
|
|
|
+例子:
|
|
|
+
|
|
|
+```
|
|
|
+bin2mz700wav ey --fa 01 --fn TestTape --la 0x1200 --in hello.bin --yaml test.yaml
|
|
|
+```
|
|
|
+
|
|
|
+以下是YAML文件结构的定义结构体代码,用作参考。
|
|
|
+
|
|
|
+```go
|
|
|
+package main
|
|
|
+
|
|
|
+type ConfigDef struct {
|
|
|
+ OutputWav string `yaml:"output_wav"`
|
|
|
+ MachineType string `yaml:"machine_type"`
|
|
|
+ InvertPolarity bool `yaml:"invert_polarity"`
|
|
|
+ TapeFiles []ConfigItemTapeFile `yaml:"tape_files"`
|
|
|
+}
|
|
|
+
|
|
|
+type ConfigItemTapeFile struct {
|
|
|
+ FileAttribute string `yaml:"file_attrib"`
|
|
|
+ FileName string `yaml:"filename"`
|
|
|
+ LoadAddress uint16 `yaml:"load_addr"`
|
|
|
+ ExecuteAfterLoad bool `yaml:"exec_after_load"`
|
|
|
+ ExecuteAddress uint16 `yaml:"exec_addr"`
|
|
|
+ UseRawCommentFromFile bool `yaml:"use_raw_comment_from_file"`
|
|
|
+ RawCommentFileName string `yaml:"comment_from_filename"`
|
|
|
+ StringComment string `yaml:"text_comment"`
|
|
|
+ DateSource string `yaml:"data_source"`
|
|
|
+ FileDataSource string `yaml:"binary_filename"`
|
|
|
+ ASCIITextFileDataSource string `yaml:"ascii_text_filename"`
|
|
|
+ IgnoreNonDisplayChar bool `yaml:"ignore_non_disp_char"`
|
|
|
+ IgnoreCR bool `yaml:"ignore_cr"`
|
|
|
+ RawData *[]byte `yaml:"raw_data"`
|
|
|
+}
|
|
|
+```
|
|
|
+#### 文本文件转换
|
|
|
+
|
|
|
+使用`convert-ascii`子命令可以对文本文件在MZ ASCII和标准ASCII之间互相转换。
|
|
|
+
|
|
|
+该子命令有`mz2ascii`(简写`m2a`)和`ascii2mz`(简写`a2m`)两个子命令。
|
|
|
+
|
|
|
+两个子命令共有的标志参数如下:
|
|
|
+
|
|
|
+* `--in`指定输入的文件
|
|
|
+* `--out`指定输出的文件
|
|
|
+* `--ignore-non-disp-char`标志,若指定该标志,则对于不显示的字符不作转换。
|
|
|
+
|
|
|
+例子:
|
|
|
+
|
|
|
+```
|
|
|
+bin2mz700wav ca a2m -i input.txt -o output.bin
|
|
|
+```
|
|
|
+
|
|
|
+```
|
|
|
+bin2mz700wav ca m2a -i input.bin -o output.txt --ign
|
|
|
+```
|
|
|
+
|
|
|
+关于忽略不显示字符和换行符处理详见[附录](#文本文件转换的规则)
|
|
|
+
|
|
|
+
|
|
|
+### 附录
|
|
|
+
|
|
|
+#### 支持的机器列表
|
|
|
+| 型号 | 在本程序中的命名 | 是否测试 |
|
|
|
+| :--:| :--: | :-- |
|
|
|
+| MZ-700 | mz-700 | 已测试 |
|
|
|
+| MZ-80A | mz-80a | 未测试 |
|
|
|
+| MZ-80B | mz-80b | 未测试 |
|
|
|
+| MZ-80K | mz-80k | 未测试 |
|
|
|
+| MZ-800 | mz-800 | 未测试 |
|
|
|
+
|
|
|
+#### SHARP官方规定的文件类型列表
|
|
|
+
|
|
|
+| 文件类型(十六进制) | 说明 |
|
|
|
+| :--:| :---- |
|
|
|
+| 01 | Machine code program file |
|
|
|
+| 02 | MZ-80 BASIC program file |
|
|
|
+| 03 | MZ-80 data file |
|
|
|
+| 04 | MZ-700 data file |
|
|
|
+| 05 | MZ-700 BASIC program file |
|
|
|
+
|
|
|
+#### 文本文件转换的规则
|
|
|
+
|
|
|
+在对MZ ASCII和标准ASCII互转的时候,本程序按照以下规则进行转换:
|
|
|
+
|
|
|
+* 对于标准ASCII的0x20至0x5D范围内的字符,MZ ASCII和标准ASCII完全一一对应,故不作转换直接输出。
|
|
|
+* 对于标准ASCII的0x5E至0x7E范围内的字符,在MZ ASCII内有相同的字符,
|
|
|
+但其对应的码和标准ASCII不一致,将进行对应的转换。
|
|
|
+* 对于换行符,请参见下方换行符说明
|
|
|
+* 对于其它字符,如果`--ignore-non-disp-char`标志未设置,则原样输出,若设置,则忽略。
|
|
|
+
|
|
|
+**换行符的处理:**
|
|
|
+
|
|
|
+在标准ASCII中,有两个和换行有关的字符:`CR`(`\r`,0x0D)和`LF`(`\n`,0x0A)。
|
|
|
+
|
|
|
+在MZ ASCII中,只有一种换行符:0x0D。
|
|
|
+
|
|
|
+从标准ASCII转换到MZ ASCII,若指定了`--ignore-return`标志,则`CR`会被忽略,
|
|
|
+`LF`会被转换到0x0D,适用于Windows等使用CR+LF换行的平台的文本文件。
|
|
|
+因为CR+LF最终会变成MZ ASCII的0x0D换行符。若不指定该标志,则将`LF`转换为0x0D,
|
|
|
+`CR`本身标准ASCII码就是0x0D,将继续保留原样。对于CR+LF换行的文件,
|
|
|
+这样转换后换行符将变成两个0x0D。
|
|
|
+
|
|
|
+从MZ ASCII转换到标准ASCII,若指定了`use-cr-lf`标志,则0x0D会被替换为CR+LF,否则替换为LF。
|
|
|
+
|
|
|
+# English Documentation
|
|
|
+
|
|
|
+**TODO: Complete English Documentation**
|
|
|
+
|