binary2sharp-mz-700-tape-wav

binary2sharp-mz-700-tape-wav

A simple convert program for converting binary file into SHARP MZ-700 Tape wave file.

中文文档

版本说明 & ChangeLog

目前是第一个发布的版本。

本程序是按照 这篇文档 制作的，在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官方定义的文件类型列表见附录。

磁带文件名： 磁带文件的文件名。最长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官方定义的文件类型列表见附录。
• --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文件结构的定义结构体代码，用作参考。

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