api_base

Определения, описанные в этом документе, объявлены в файле 'sys_h.asm',
который в свою очередь линкует файл 'sysdefs.asm'.

Данный документ подразумевает использование асм-компилятора sjasmplus из репозитория NedoOS.
sjasmplus поставляется в виде исполнияемого файла sjasmplus.exe для OS Windows.
А также в виде исходного кода для самостоятельной сбоки под вами используюмую OS.

************************* Используемые выражения *************************
байт - минимальня единица хранения данных в ОЗУ ZX-Spectrum, равная 8 битам.

0x - приставка к константе, обозначающая число представленное в шестнадцатиричной систаме измерения.

little-endian - представление числа в ОЗУ. Это представление использует процессор z80.
	Сначала младший байт, затем старший. В этом документе, по умолчанию, все числа little-endian.
	К примеру 16 битное число 0x1234 располагается в памяти как DEFB 0x34,0x12

string(строка) - нуль-терминированный массив байтов, как правило содержащий строку символов.
	Пример: DEFB "Hello Work!",0

страница ОЗУ(page) - 16килобайт физического ОЗУ.

окно(окно памяти) - окно адрестного пространства процессора z80.
	В NedoOS используется четыре окна располагаемых в адресах
		0x0000...0x3fff, 0x4000...0x7fff, 0x8000...0xbfff, 0xc000...0xffff

Палитра - палитра цветов видеовывода

фокус - доступность вывода на экран и чтение клавиатуры.
	В момент времени фокус может принадлежать только одному процессу, остальным процессам в этот момент фокус недоступен.
	Фокус переключается при вызове OS_SETGFX, при закрытии процесса, а так же хоткеем.

процесс - задача.
	Процессу доступно адресное пространство PROGSTART...0xffff.
	Стек(регистр SP) процесса может располагатся в диапазоне адресов 0x3b00...0xffff.
	У каждого процесса свой квант времени, переключение процессов происходит
	по сигналу n_int процессора, либо если процесс отдал свой квант времени.
	У каждого процесса своя палитра.
	При создании процесса ему выделяется четыре страницы ОЗУ, которые подключаются
	во все 4 окна адресного пространства. Адреса 0x0000...0x00ff заполняются служебной информацией.
	Также устанавливается системная цветовая палитра.
	При старте процесса управление передается на адрес PROGSTART

программа - исполняемый файл с расширением '.com', максимальный размер программы 0x10000-PROGSTART
	При запуске программы она помещается в отдельный процесс.
	Исходный код программы, как правило, начинается строками:
		DEVICE ZXSPECTRUM128
		include "../_sdk/sys_h.asm"
		ORG PROGSTART
	И заканчивается строкой
		savebin "progname.com",PROGSTART,$-PROGSTART

8.3 - формат имени файла либо директории, до 8 символов имя и до 3 символов расширение.
		В случае присутствия раширения, используется символ '.' в качестве разделителя имени и расширения

***********************************************************
*********************** Определения ***********************
***********************************************************
При вызове функций ядра считается, что возможна порча всех регистров(за исключением SP).

*********************** PROGSTART **********************
	Идентификатор, определяющий начало компиляции и стартовый адрес программы.
	В текущей реализации равен 0x0100

	Пример использования, а также минимальный исходный код программы:
		DEVICE ZXSPECTRUM128
		include "../_sdk/sys_h.asm"
		ORG PROGSTART
		;исходный код программы
		QUIT
		savebin "progname.com",PROGSTART,$-PROGSTART

*********************** QUIT **********************
	Макрос, вызова функции ядра.
	Закрывает текущий процесс, освобождая все используемые им страницы ОЗУ,
		дескрипторы файлов и сокетов.
	Переключает исполнение и фокус видеовывода на следующий процесс.

	Аргументы не используются.

	Пример использования смотри в описании PROGSTART


*********************** OS_SETGFX **********************
	Макрос вызова функции ядра.
	Устанавливает видео-режим.
	При старте процесса вывод на экран, процессом, недоступен без установки видеорежима.

	Все аргументы в регистрах:
		E - видеорежим, допустимы следующие значения:
			0 - EGA
			2 - Аппаратный мультиколор
			3 - 6912
			6 - текстовый видеорежим, так же устанвливает фокус на процесс
			-1 - отключает видеовывод и переключает фокус видеовывода на следующий процесс
	Возвращаемые значения в регистрах:
		E - видеорежим до вызова OS_SETGFX

	Пример установки текстового видеорежима:
		LD E,6
		OS_SETGFX


*********************** PRCHAR **********************
	Макрос вызова функции ядра.
	Выводит символ на экран, ипользуется только в текстовом видеорежиме.
	Фактичеси вывод происходит только процессом с фокусом.

	Все аргументы в регистрах:
		A - символ. символы '\r' и '\n' являются управляющими.
	Возвращаемых значений нет.

	Пример печати строки "Hello Work!":
		DEVICE ZXSPECTRUM128
		include "../_sdk/sys_h.asm"
		ORG PROGSTART
		LD E,6
		OS_SETGFX
		LD HL,STR_HELLO
PRINT_LOOP:
		LD A,(HL)
		OR A
		JR Z,PRINT_LOOP_END
		PUSH HL
		PRCHAR
		POP HL
		INC HL
		JR PRINT_LOOP
PRINT_LOOP_END:
		QUIT
STR_HELLO:
		DEFB "Hello Work!",0
		savebin "progname.com",PROGSTART,$-PROGSTART

*********************** GET_KEY **********************
	Макрос вызова функции ядра.
	Возвращает нажатую кнопку клавиатуры, кнопки мыши и координаты мыши.
	Фактичеси чтение происходит только процессом с фокусом.

	Аргументов нет.
	Возвращаемые значения в регистрах:
		A - код символа(кнопки). Допустимые коды смотри в 'sysdefs.asm' секция 'Internal keyboard values'
		C - код символа(кнопки) без учёта языковой раскладки.
		DE - позиция мыши (y,x)
		L - кнопки мыши (bits 0,1,2: 0=pressed)

	Пример ожидания символа:
		LD E,6
		OS_SETGFX
WAIT_LOOP:
		GET_KEY
		OR A
		JR Z,WAIT_LOOP
		CP key_esc
		JP Z,CLOSE_PROC
		;получили код символа в A
		...
CLOSE_PROC:
		QUIT

		Примечание: желательна обработка кода key_esc для завершения программы.

*********************** OS_OPENHANDLE **********************
	Макрос вызова функции ядра.
	Открывает существующий файл для чтения/записи.

	Все аргументы в регистрах:
		DE - строка с именем файла, может содержать относительный либо абсолютный путь к файлу.
			в текущей реализации поддержан формат имен 8.3
	Возвращаемые значения в регистрах:
		А - ошибка. Если 0x00 то ошибки нет.
		B - дескриптор файла если нет ошибки.

	Пример открытия файла 'pyraster.txt' располеженного в директории '../fu/ckco':
		LD DE,FILE_NAME
		OS_OPENHANDLE
		OR A
		JP NZ,ERR_EXIT	;обработка ошибок
		LD A,B
		LD (FILE),A	;сохраняем дескриптор
		...
FILE_NAME:
		DEFB "../fu/ckco/pyraster.txt",0