diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 44c08a6..342e646 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,11 +4,14 @@ build: os: "ubuntu-22.04" tools: python: "3.9" - apt_packages: - - libisal-dev jobs: pre_build: + - doxygen docs/Doxyfile - make -C build/linux doc +python: + install: + - requirements: docs/requirements.txt + sphinx: configuration: docs/conf.py diff --git a/build/linux/Makefile b/build/linux/Makefile index ae6c292..0cd090e 100644 --- a/build/linux/Makefile +++ b/build/linux/Makefile @@ -15,7 +15,7 @@ $(EXEC): $(MAIN) $(OBJS) %.o: $(PTH)/%.c $(PTH)/%.h $(CC) $(CFLAGS) -c $< -../../docs/cli.rst: ../../docs/cli_template.rst $(EXEC) +../../docs/cli.rst: ../../docs/cli_template.rst_ $(EXEC) cp $< $@ && ./$(EXEC) -h >> $@ clean: diff --git a/doc/mzf2wavs1.gif b/doc/mzf2wavs1.gif deleted file mode 100644 index c6c4ce1..0000000 Binary files a/doc/mzf2wavs1.gif and /dev/null differ diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..cb86b3d --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,10 @@ +INPUT = src/ +OUTPUT_DIRECTORY = docs/ + +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES + +INLINE_SIMPLE_STRUCTS = YES + +FILE_PATTERNS = *.c *.h diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..0a5c933 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,12 @@ +API documentation +================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :glob: + + api/wav + api/mzf + api/write + api/methods diff --git a/docs/api/methods.rst b/docs/api/methods.rst new file mode 100644 index 0000000..8917d3f --- /dev/null +++ b/docs/api/methods.rst @@ -0,0 +1,8 @@ +Tape write methods +================== + +.. code-block:: cpp + + #include "methods.h" + +.. doxygenfile:: methods.h diff --git a/docs/api/mzf.rst b/docs/api/mzf.rst new file mode 100644 index 0000000..d81183e --- /dev/null +++ b/docs/api/mzf.rst @@ -0,0 +1,8 @@ +MZF files +========= + +.. code-block:: cpp + + #include "mzf.h" + +.. doxygenfile:: mzf.h diff --git a/docs/api/wav.rst b/docs/api/wav.rst new file mode 100644 index 0000000..c6d750f --- /dev/null +++ b/docs/api/wav.rst @@ -0,0 +1,8 @@ +WAV files +========= + +.. code-block:: cpp + + #include "wav.h" + +.. doxygenfile:: wav.h diff --git a/docs/api/write.rst b/docs/api/write.rst new file mode 100644 index 0000000..1ad4985 --- /dev/null +++ b/docs/api/write.rst @@ -0,0 +1,8 @@ +Tape write functions +==================== + +.. code-block:: cpp + + #include "write.h" + +.. doxygenfile:: write.h diff --git a/docs/cli_template.rst b/docs/cli_template.rst_ similarity index 100% rename from docs/cli_template.rst rename to docs/cli_template.rst_ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0582761 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,12 @@ +project = 'mzf2wav' +author = 'Jeroen F.J. Laros' +copyright = '2003-2023, {}'.format(author) + +extensions = ['breathe'] +breathe_projects = {'doxygen': 'xml'} +breathe_default_project = 'doxygen' +breathe_default_members = ('members',) + +master_doc = 'index' + +highlight_language = 'none' diff --git a/docs/index.rst b/docs/index.rst index 3819a4d..15acf1e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,4 +8,5 @@ install cli usage + api credits diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..55928ee --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +breathe>=4.3.1 +docutils>=0.17.1 diff --git a/docs/usage.rst b/docs/usage.rst index 04bf13b..89d49ce 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -9,70 +9,82 @@ named ``image.wav``: mzf2wav image.mzf image.wav -Operation modes ---------------- +Modes of operation +------------------ -Conventional sending mode -~~~~~~~~~~~~~~~~~~~~~~~~~ +MZF2WAV supports different writing techniques that can shorten the loading +time considerably. Please see the tape_ data processing page for more +background information. -This is the safest (and slowest) way to transfer an image, everything is done -according to the Sharp MZ series conventions: A long gap is 22000 pulses, a -short gap is 11000 pulses. The header and body are transferred twice to allow -for errors. - -Fast sending mode +Conventional mode ~~~~~~~~~~~~~~~~~ -This is the easiest way to transfer a file. In this mode the long gap (a tape -marker) is 4000 pulses and the short gap is 5000 pulses. Both the header and -the MZF image body are transferred once. +In this mode, everything is done according to the Sharp MZ series +conventions. A long gap is 22000 pulses, a short gap is 11000 pulses. The +header and body are written twice to allow for errors. This mode can be +selected using the ``-c`` command line option. + +Fast mode +~~~~~~~~~ -Turbo sending mode -~~~~~~~~~~~~~~~~~~ +In this mode, the long gap is 4000 pulses and the short gap is 5000 pulses. +Both the header and the MZF image body are written once. This is the default +mode. -In this mode, the turbo loader is transferred using fast sending mode, this -turbo loader enables the MZ to operate at higher transfer speeds. The MZF -image is then sent using fast sending mode, but now at a higher speed. +Turbo mode +~~~~~~~~~~ -The speed at which the turbo loader is transferred is controlled with the -``-i`` option, the speed at which the MZF image is sent is controlled with the -``-t`` option. +In this mode, a turbo loader is written using fast sending mode, which +enables the MZ to operate at higher speeds. The MZF image is then sent using +fast sending mode, but now at a higher speed. This mode can be selected using +the ``-t`` command line option. Speeds ------ Apart from increasing the pulse frequency, the waveforms themselves can be -altered in order to increase speed. The "fast waveform" was found by minimising -the high and the low states of the pulses independently. +altered in order to increase speed. + +For conventional and fast mode, two predefined waveform configurations are +available that can be selected using the ``-n`` command line option. + +For turbo mode, three predefined waveform configurations are available that +can be selected using the ``-s`` command line option. This option can be +combined with the ``-n`` option to also write the turbo loader at a higher +speed. For example: + +:: -At this time, five speeds are implemented: + mzf2wav -t -n 1 -s 2 image.mzf image.wav -- Speed 0: normal speed with normal waveforms. -- Speed 1: normal speed with fast waveforms. -- Speed 2: 2x speed with normal waveforms. -- Speed 3: 3x speed with normal waveforms. -- Speed 4: 3x speed with fast waveforms. -These speeds can be set for all operation modes, although some combinations may -not work. The most commonly used speeds are: speed 0 or 1 for initial speed -mode and speed 2 or higher for turbo speed mode. +Pulse customisation +~~~~~~~~~~~~~~~~~~~ -If multiple images are transferred, using speed 3 or 4 with fast sending mode -may be preferred. +Next to the predefined waveform configurations, it is possible to make custom +waveform configurations using the ``-N`` (conventional and fast mode) and +``-S`` (turbo mode) options. For example: -Corrections -~~~~~~~~~~~ +:: + + mzf2wav -t -N 480,494,260,264 -S 248,248,113,140 image.mzf image.wav -Because the waveforms used by speeds 1 and 4 may not always work, two -correction factors for these speeds are implemented, controlled with the ``-1`` -and ``-2`` options. +The pulse configuration consists of four comma separated values giving the +length of the long pulse up, long pulse down, short pulse up and short pulse +down times in microseconds. Polarity -------- -The polarity can be revered with the ``-p`` option. +The polarity can be inverted using the ``-p`` option. + + +Bit rate +-------- + +The bit rate is set using the ``-b`` option. Related software @@ -83,6 +95,6 @@ Please check out MZF2WAVGUI_, a graphical user interface for this project directly connect to an MZ. -.. _operation modes: https://github.com/jfjlaros/mzput#operation-modes .. _MZF2WAVGUI: https://github.com/rickyelqasem/MZF2WAVGUI .. _tutorial: https://www.youtube.com/watch?v=iwD3-5ENyE8 +.. _tape: https://web.archive.org/web/20201127232159/https://original.sharpmz.org/mz-700/tapeproc.htm diff --git a/src/argparse.c b/src/argparse.c index ac4da2b..86212c1 100644 --- a/src/argparse.c +++ b/src/argparse.c @@ -15,30 +15,6 @@ uint16_t const turboDefaults_[][4] = { Options const default_ = { NULL, NULL, fast, false, 44100, {0}, {0}, false, false, false}; -char const usage[] = - "usage: %s [-c] [-t] [-p] [-b BITRATE] [-n SPEED] [-s SPEED] " - "[-N FMT] [-S FMT] MZF WAV\n\n" - "positional arguments:\n" - " MZF input file in MZF format\n" - " WAV input file in WAV format\n\n" - "options:\n" - " -h display help information and exit\n" - " -v display version information and exit\n" - " -c conventional mode\n" - " -t turbo mode\n" - " -p invert polarity\n" - " -b BITRATE bit rate (dafault: 44100)\n" - " -n SPEED normal mode speed 0 or 1 (default: 0)\n" - " -s SPEED turbo mode speed 0, 1 or 2 (default: 0)\n" - " -N FMT custom waveform for normal mode\n" - " -S FMT custom waveform for turbo mode\n\n" - "FMT: long_up,long_down,short_up,short_down\n"; - -char const version[] = - "MZF2WAV version 2.0.0\n" - "Copyright (c) 2003-2023 Jeroen F.J. Laros \n" - "Homepage: https://mzf2wav.readthedocs.io\n"; - size_t parseInt_(char const *const text, size_t const range) { size_t idx = strtoul(text, NULL, 10); diff --git a/src/argparse.h b/src/argparse.h index 5059637..41a9db0 100644 --- a/src/argparse.h +++ b/src/argparse.h @@ -17,9 +17,6 @@ typedef struct { bool version; //!< Version. } Options; -extern char const usage[]; // Usage string. -extern char const version[]; // Version string. - /*! Parse command line arguments. * diff --git a/src/mzf2wav.c b/src/mzf2wav.c index 1676c20..e76d290 100644 --- a/src/mzf2wav.c +++ b/src/mzf2wav.c @@ -3,6 +3,30 @@ #include "argparse.h" +char const usage_[] = + "usage: %s [-c] [-t] [-p] [-b BITRATE] [-n SPEED] [-s SPEED] " + "[-N FMT] [-S FMT] MZF WAV\n\n" + "positional arguments:\n" + " MZF input file in MZF format\n" + " WAV input file in WAV format\n\n" + "options:\n" + " -h display help information and exit\n" + " -v display version information and exit\n" + " -c conventional mode\n" + " -t turbo mode\n" + " -p invert polarity\n" + " -b BITRATE bit rate (dafault: 44100)\n" + " -n SPEED normal mode speed 0 or 1 (default: 0)\n" + " -s SPEED turbo mode speed 0, 1 or 2 (default: 0)\n" + " -N FMT custom waveform for normal mode\n" + " -S FMT custom waveform for turbo mode\n\n" + "FMT: long_up,long_down,short_up,short_down\n"; + +char const version_[] = + "MZF2WAV version 2.0.0\n" + "Copyright (c) 2003-2023 Jeroen F.J. Laros \n" + "Homepage: https://mzf2wav.readthedocs.io\n"; + unsigned int fileSize_(FILE *handle) { fseek(handle, 0, SEEK_END); @@ -79,14 +103,16 @@ bool mzf2wav(Options const *const options) { int main(int const argc, char *const *const argv) { Options options = argParse(argc, argv); - if (options.version) { - printf(version); + if (options.help) { + printf(usage_, argv[0]); return 0; } - if (options.help || options.error) { - printf(usage, argv[0]); + if (options.version) { + printf(version_); + return 0; } if (options.error || !mzf2wav(&options)) { + printf(usage_, argv[0]); return 1; } } diff --git a/src/wav.c b/src/wav.c index fa8ef29..2f9c43c 100644 --- a/src/wav.c +++ b/src/wav.c @@ -24,8 +24,8 @@ void writeInt_(FILE *const output, uint32_t const data) { void writeBit(FILE *const output, bool const bit, bool const invert) { - uint8_t const zero = 0x30; // TODO: 0x00? - uint8_t const one = 0xd0; // TODO: 0xff? + uint8_t const zero = 0x00; + uint8_t const one = 0xff; if (bit != invert) { fprintf(output, "%c", one);