Обновлена документация на DSS

Docs/DSS_1.71_Functions.asm

@@ -22,6 +22,7 @@ DSS_Version:			; Версия DSS
  RST ToDSS			; D - номер версии
 				; E - модификация
 				; BC - номер сборки
+				; HL = 0
 
 ;███████████████████████████████████████████████████████████████████████████████████████████████████████
 ;			2. Функции для работы с диском
@@ -31,7 +32,7 @@ DSS_Version:			; Версия DSS
 DSS_ChDisk:			; Смена текущего диска
  LD A,disk_num			; номер диска (0-A:, 1-B:, ...)
  LD C,Dss.ChDisk		; #01
- RST ToDSS			; CF=0: A - максимальный номер диска в системе
+ RST ToDSS			; CF=0: A - номер последнего диска в системе
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
@@ -44,10 +45,18 @@ DSS_CurDisk:			; Номер текущего диска
 ;-------------------------------------------------------------------------------------------------------
 DSS_DskInfo:			; Информация о диске
  LD A,disk_num			; номер диска (0-A:, 1-B:, ..., #FF - текущий)
-				; если A bit7=1 и A != #FF:
+				; A bit7=1 (A != #FF) - расширенный запрос:
-				;   HL - буфер 256 байт для расширенных данных
+				;   номер диска = A and #7F
-				;   (формат: длина поля, данные, ...)
+				;   HL - буфер для расширенных данных, формат
-				; B = 0 - не подсчитывать свободные кластеры
+				;   (длина поля, затем данные):
+				;     5 - тип ФС "FAT12"/"FAT16"/"FAT32"
+				;     4 - серийный номер тома
+				;    11 - метка тома
+				;     2 - физ. номер диска, номер раздела
+				;     0 - конец данных
+				;   B != 0 - пересчитать свободные кластеры,
+				;   B  = 0 - вернуть кэшированное значение
+				; B учитывается только при A bit7=1
  LD C,Dss.DskInfo		; #03
  RST ToDSS			; CF=0: A - размер кластера в секторах
 				;        HL':HL - общее количество кластеров
@@ -57,7 +66,7 @@ DSS_DskInfo:			; Информация о диске
 
 ;-------------------------------------------------------------------------------------------------------
 DSS_G_Entry:			; Зарезервированная функция
- LD C,#04			; #04
+ LD C,Dss.G_ENTRY		; #04
  RST ToDSS			; не используется
 
 ;-------------------------------------------------------------------------------------------------------
@@ -72,8 +81,11 @@ DSS_BootDSK:			; Номер системного диска (подфункци
  RST ToDSS			; CF=0: A - номер системного диска (0-A:, ...)
 				; CF=1: A - код ошибки
 				; --- Установить системный диск ---
+				; (служебная: используется boot-загрузчиком;
+				;  после первого успешного вызова недоступна)
  LD BC,Dss.BootDSK.Set		; B=1, C=#09
- LD A,disk_num			; номер системного диска
+ LD H,device_num		; номер устройства
+ LD L,partition			; номер раздела на устройстве
  RST ToDSS			; CF=0: успешно
 				; CF=1: A - код ошибки
 
@@ -84,7 +96,7 @@ DSS_BootDSK:			; Номер системного диска (подфункци
 ;-------------------------------------------------------------------------------------------------------
 DSS_Create:			; Создание файла (если существует, перезаписывается)
  LD HL,filespec			; указатель на файловую спецификацию (строка с 0)
- LD A,file_attr			; атрибут файла
+ LD A,file_attr			; атрибут файла (биты DIR и VOLUME_ID снимаются)
  LD C,Dss.Create		; #0A
  RST ToDSS			; CF=0: A - файловый манипулятор
 				; CF=1: A - код ошибки
@@ -92,7 +104,7 @@ DSS_Create:			; Создание файла (если существует, пе
 ;-------------------------------------------------------------------------------------------------------
 DSS_Creat_N:			; Создание нового файла (если существует, ошибка)
  LD HL,filespec			; указатель на файловую спецификацию
- LD A,file_attr			; атрибут файла
+ LD A,file_attr			; атрибут файла (биты DIR и VOLUME_ID снимаются)
  LD C,Dss.Creat_N		; #0B
  RST ToDSS			; CF=0: A - файловый манипулятор
 				; CF=1: A - код ошибки
@@ -123,7 +135,7 @@ DSS_Open:			; Открытие файла
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_Close:			; Закрытие файла
+DSS_Close:			; Закрытие файла (ACCESS_DENIED, если манипулятор чужой задачи)
  LD A,file_handle		; файловый манипулятор
  LD C,Dss.Close			; #12
  RST ToDSS			; CF=0: успешно
@@ -153,19 +165,19 @@ DSS_Write:			; Запись в файл
 ;-------------------------------------------------------------------------------------------------------
 DSS_Move_FP:			; Перемещение указателя в файле
  LD A,file_handle		; файловый манипулятор
- LD HL,offs_low			; смещение (младшая часть)
+ LD HL,offs_high		; смещение (старшая часть, биты 16-31)
- LD IX,offs_high		; смещение (старшая часть)
+ LD IX,offs_low			; смещение (младшая часть, биты 0-15)
-				; (полное смещение = HL:IX)
+				; (полное смещение = HL:IX, HL - старшая)
  LD B,move_method		; способ перемещения:
 				; B=0 - от начала файла
 				; B=1 - от текущей позиции
 				; B=2 - от конца файла
  LD C,Dss.Move_FP		; #15
- RST ToDSS			; CF=0: HL:IX - новое значение указателя
+ RST ToDSS			; CF=0: HL:IX - новое значение (HL старш., IX младш.)
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_Attrib:			; Получение/изменение атрибутов файла
+DSS_Attrib:			; Получение/изменение атрибутов файла (B>=2 - ошибка INVALID_FUNCTION)
 	; -- Получить атрибут --;
  LD BC,Dss.Attrib.Get		; B=0, C=#16
  LD HL,filespec			; указатель на файловую спецификацию
@@ -174,8 +186,8 @@ DSS_Attrib:			; Получение/изменение атрибутов фай
 	; - Установить атрибут -;
  LD BC,Dss.Attrib.Set		; B=1, C=#16
  LD HL,filespec			; указатель на файловую спецификацию
- LD A,new_attr			; новый атрибут
+ LD A,new_attr			; новый атрибут (бит VOLUME_ID снимается)
- RST ToDSS			; CF=0: успешно
+ RST ToDSS			; CF=0: A - установленный атрибут
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
@@ -207,11 +219,12 @@ DSS_Put_D_T:			; Установка даты и времени файла
 DSS_F_First:			; Поиск первого совпадающего файла
  LD A,search_attr		; атрибуты, используемые при поиске
  LD HL,filespec			; указатель на файловую спецификацию
- LD DE,buffer			; рабочий буфер (44 или 46 байт в зависимости от B)
+ LD DE,buffer			; буфер: 44 байта (B=0, FAT-имя) или 46 байт (B=1, DOS-имя)
  LD B,name_format		; формат имени:
 				; B=0 - 11 байт "FILENAMEEXT"
 				; B=1 - DOS-строка "filename.ext",0
-				; или с флагом поиска всех файлов:
+				; флаг поиска всех файлов (#80/#81)
+				; в v1.71 НЕ реализован (!TODO):
 				; LD BC,Dss.F_First.All_DOSname ; B=1 + старший бит = #81, C=#19
  LD C,Dss.F_First		; #19
  RST ToDSS			; CF=0: буфер DE заполнен информацией о файле
@@ -246,8 +259,8 @@ DSS_ChDir:			; Смена текущего каталога
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_CurDir:			; Получение текущего каталога
+DSS_CurDir:			; Получение текущего каталога (CF=1: TOO_DEEP_DIR_DEPTH)
- LD HL,buffer			; буфер размером 256 байт
+ LD HL,buffer			; буфер для строки пути (размер DIRECTORY_PATH_LENGTH)
  LD C,Dss.CurDir		; #1E
  RST ToDSS			; CF=0: буфер заполнен строкой пути
 				; CF=1: A - код ошибки
@@ -276,8 +289,8 @@ DSS_SetTime:			; Установить текущую дату и время
  LD L,minute			; минуты
  LD B,second			; секунды
  LD C,Dss.SetTime		; #22
- RST ToDSS			; CF=0: успешно
+ RST ToDSS			; всегда CF=0 (ошибок нет);
-				; CF=1: A - код ошибки
+				; день недели вычисляется автоматически
 
 ;███████████████████████████████████████████████████████████████████████████████████████████████████████
 ;			5. Функции управления памятью
@@ -327,21 +340,21 @@ DSS_InfoMem:			; Информация о памяти
 				; BC - количество свободных страниц
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_GetMem:			; Выделение блока памяти
+DSS_GetMem:			; Выделение блока памяти (закрепляется за задачей)
  LD B,num_pages			; размер блока в страницах (16 Кбайт каждая)
  LD C,Dss.GetMem		; #3D
  RST ToDSS			; CF=0: A - идентификатор блока памяти
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_FreeMem:			; Освобождение блока памяти
+DSS_FreeMem:			; Освобождение блока памяти (только свой, иначе INVALID_MEMORY_HND)
  LD A,mem_blk_id		; идентификатор блока
  LD C,Dss.FreeMem		; #3E
  RST ToDSS			; CF=0: успешно
 				; CF=1: A - код ошибки
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_SetMem:			; Изменение размера блока памяти
+DSS_SetMem:			; Изменение размера блока памяти (только свой блок)
  LD A,mem_blk_id		; идентификатор блока
  LD B,new_size			; новый размер в страницах
  LD C,Dss.SetMem		; #3F
@@ -359,6 +372,7 @@ DSS_WaitKey:			; Ожидание символа с клавиатуры
 				; E - ASCII-код
 				; C - режим клавиатуры:
 				;	bit7: RUS/LAT
+				;	bit6: Pause Lock
 				;	bit3: Num Lock
 				;	bit2: Scroll Lock
 				;	bit1: Insert
@@ -388,21 +402,28 @@ DSS_EchoKey:			; Ожидание символа с печатью без скр
 DSS_CTRLKey:			; Получить состояние клавиатуры (без символа)
  LD C,Dss.CTRLKey		; #33
  RST ToDSS			; A = 0 - нет символов в буфере
+				; A = #FF - в буфере есть символы
 				; C,B - состояние клавиатуры (как у WaitKey)
 
 ;-------------------------------------------------------------------------------------------------------
 DSS_K_CLEAR:			; Очистить буфер клавиатуры и выполнить функцию
  LD B,fn_number			; номер функции:	#30 (WaitKey), #31 (ScanKey),
-				;			#32 (EchoKey), #33 (CTRLKey) или #34 (EDIT)
+				;			#32 (EchoKey), #33 (CTRLKey)
+				;			#34 (EDIT) - не реализовано в v1.71
  LD C,Dss.K_CLEAR		; #35
  RST ToDSS			; выходные значения как у вызванной функции
+				; B вне #30..#34 -> CF=1, A=1 (INVALID_FUNCTION)
 
 ;-------------------------------------------------------------------------------------------------------
 DSS_K_SETUP:			; Управление настройками клавиатуры
-	; --- Установить раскладку ---
+	; --- Чтение/запись таблицы раскладки клавиатуры ---
  LD BC,Dss.K_SETUP.SetLayout	; B=0, C=#36
- LD A,layout_num		; номер раскладки (0-7)
+ LD HL,keymap_buf		; буфер таблицы раскладки
- RST ToDSS
+ LD A,layout_sel		; bit7=0 - запись (Set), bit7=1 - чтение (Get)
+				; биты0-2 - номер подтаблицы 0-7:
+				; 0=NormLat 1=ShiftLat 2=CapsLat 3=Shift2Lat
+				; 4=NormRus 5=ShiftRus 6=CapsRus 7=Shift2Rus
+ RST ToDSS			; CF=1, A=#13 (INVALID_ACCESS) при B>=5
 	; --- Получить звуковые переменные ---
  LD BC,Dss.K_SETUP.GetSoundVars	; B=1, C=#36
  RST ToDSS			; A - значение переменных
@@ -430,11 +451,13 @@ DSS_TestKey:			; Опрос буфера клавиатуры (без извле
 ;-------------------------------------------------------------------------------------------------------
 DSS_Exec:			; Загрузить и выполнить файл
  LD HL,filespec			; указатель на файловую спецификацию
- LD B,search_mode		; 0 - с поиском в PATH
+ LD B,search_mode		; 0 - с поиском в PATH (только если в
+				;     спецификации нет '\')
 				; 1 - без поиска в PATH
  LD C,Dss.Exec			; #40
  RST ToDSS			; CF=0: A - код завершения программы
-				; CF=1: A - код ошибки
+				; CF=1: A - код ошибки (а также при
+				;       аварийном завершении дочерней программы)
 
 ;-------------------------------------------------------------------------------------------------------
 DSS_Exit:			; Завершение текущей программы
@@ -466,7 +489,7 @@ DSS_DosName:			; Преобразование имени файла (11 симв
  LD BC,#00*256 + Dss.DosName	; B=0, C=#44
  LD HL,name_11			; указатель на 11-символьное имя
  LD DE,dos_buf			; буфер для DOS-имени
- RST ToDSS			; CF=0: успешно, CF=1: A - код ошибки
+ RST ToDSS			; B=0: всегда успех (ошибок нет)
 	; --- DOS-имя -> 11-символьное ---
  LD BC,#01*256 + Dss.DosName	; B=1, C=#44
  LD HL,dos_name			; указатель на DOS-строку
@@ -508,11 +531,18 @@ DSS_EX_Path:			; Расширенный разбор командной стро
  LD BC,Dss.EX_Path.GET_ALL_EX	; B=5, C=#45
  LD HL,cmd_line
  LD DE,components_table		; адрес таблицы из 8 байт:
-				; DE+0: адрес буфера для диска
+				; +0: адрес буфера для диска (2 байта)
-				; DE+2: адрес буфера для директории
+				; +2: адрес буфера для директории (2 байта)
-				; DE+3: адрес буфера для имени файла
+				; +4: адрес буфера для имени файла (2 байта)
-				; DE+4: адрес буфера для расширения
+				; +6: адрес буфера для расширения (2 байта)
  RST ToDSS			; CF=0: A - результат, буферы заполнены
+	; --- B=6: зарезервировано (возвращает INVALID_FUNCTION) ---
+	; --- Выделить параметр командной строки (= функция #43) ---
+ LD BC,Dss.EX_Path.GSWITCH	; B=7, C=#45
+ LD HL,cmd_line			; указатель на командную строку
+ LD DE,param_buf		; буфер для параметра
+ RST ToDSS			; HL - на следующий параметр;
+				; CF=0: ещё есть параметры; CF=1: конец строки
 	; --- Преобразовать 11-символьное имя -> DOS ---
  LD BC,Dss.EX_Path.GETNAME	; B=8, C=#45
  LD HL,name_11
@@ -530,6 +560,10 @@ DSS_EX_Path:			; Расширенный разбор командной стро
 
 ;-------------------------------------------------------------------------------------------------------
 DSS_Environ:			; Работа с системным окружением
+	; --- Инициализация окружения (служебная!) ---
+	; ВНИМАНИЕ: сбрасывает всё окружение к умолчанию (только BOOTDSK=)
+ LD BC,Dss.Environ.Init		; B=255, C=#46
+ RST ToDSS			; CF=0: успешно
 	; --- Получить всё окружение ---
  LD BC,Dss.Environ.Read		; B=0, C=#46
  LD HL,buffer			; буфер для строк окружения
@@ -538,14 +572,14 @@ DSS_Environ:			; Работа с системным окружением
  LD BC,Dss.Environ.Get		; B=1, C=#46
  LD HL,var_name			; указатель на имя переменной
  LD DE,value_buf		; буфер для значения
- RST ToDSS			; CF=0: A=0 - найдена, A=#FF - не найдена
+ RST ToDSS			; CF=0: A=#FF - найдена, A=0 - не найдена
 	; --- Установить/удалить переменную ---
  LD BC,Dss.Environ.Set		; B=2, C=#46
  LD HL,var_string		; указатель на строку "ПЕРЕМЕННАЯ=ЗНАЧЕНИЕ"
  RST ToDSS			; CF=0: успех
 
 ;-------------------------------------------------------------------------------------------------------
-DSS_AppInfo:			; Информация о текущем приложении
+DSS_AppInfo:			; Информация о текущем приложении (B>=3 - INVALID_FUNCTION)
 	; --- Параметры командной строки ---
  LD BC,Dss.AppInfo.CMD_Param	; B=0, C=#47
  LD HL,buffer			; буфер для параметров
@@ -553,7 +587,7 @@ DSS_AppInfo:			; Информация о текущем приложении
 	; --- Полный путь к каталогу программы ---
  LD BC,Dss.AppInfo.EXE_HomeDir	; B=1, C=#47
  LD HL,buffer			; буфер для пути
- RST ToDSS
+ RST ToDSS			; CF=1: A=COMMON_ERROR при ошибке разбора
 	; --- Полный путь и имя файла программы ---
  LD BC,Dss.AppInfo.EXE_FullPath	; B=2, C=#47
  LD HL,buffer
@@ -564,10 +598,11 @@ DSS_AppInfo:			; Информация о текущем приложении
 ;███████████████████████████████████████████████████████████████████████████████████████████████████████
 ;-------------------------------------------------------------------------------------------------------
 DSS_SetVMod:			; Выбор видеорежима
- LD A,video_mode		; режим: 02h - текст 40x32
+ LD A,video_mode		; режим: 02h - текст 40x32 (16 цветов)
-				;        03h - текст 80x32
+				;        03h - текст 80x32 (16 цветов)
-				;        81h - графика 320x256
+				;        81h - графика 320x256x256
-				;        82h - графика 640x256
+				;        82h - графика 640x256x16
+				; (00h,01h,80h,83h не реализованы -> ошибка)
  LD B,screen_page		; номер страницы экрана, которая будет активна (0/1)
  LD C,Dss.SetVMod		; #50
  RST ToDSS			; CF=0: успех, CF=1: A - код ошибки
@@ -603,9 +638,11 @@ DSS_Scroll:			; Прокрутка окна
  LD H,height			; высота окна в строках
  LD L,width			; ширина окна в символах
  LD B,direction			; 1 = вверх, 2 = вниз
- LD A,clear_mode		; 0 = очищать освободившуюся строку пробелами
+				; (иное -> CF=1, A=INVALID_FUNCTION)
+ LD A,clear_mode		; 0 = очищать строку пробелами,
+				; иначе - не очищать
  LD C,Dss.Scroll		; #55
- RST ToDSS
+ RST ToDSS			; CF=1, A=код ошибки при B вне {1,2}
 
 ;-------------------------------------------------------------------------------------------------------
 DSS_Clear:			; Очистка прямоугольной области экрана
@@ -666,13 +703,14 @@ DSS_PutChar:			; Печать символа в текущей позиции к
 DSS_PChars:			; Печать строки в текущей позиции курсора
  LD HL,string			; указатель на строку (заканчивается 0)
  LD C,Dss.PChars		; #5C
- RST ToDSS			; HL - указатель на байт за концом строки
+ RST ToDSS			; строка печатается до байта 0 (HL после вызова не определён)
 
 ;-------------------------------------------------------------------------------------------------------;!FIXIT
 DSS_Lib_Sub:			; Библиотечные подфункции
 				; --- Восстановить системный шрифт ---
  LD BC,Dss.Lib_Sub.RestoreFont	; B=1, C=#5D
  RST ToDSS			; восстанавливает знакогенератор по умолчанию
+				; (B != 1 -> CF=1, A не изменяется)
 
 ;███████████████████████████████████████████████████████████████████████████████████████████████████████
 ;			11. Функции для печати на принтере
@@ -682,4 +720,53 @@ DSS_Print:			; Вывод символа на принтер без ожидан
  LD A,char			; символ для печати
  LD C,Dss.Print			; #5F
  RST ToDSS			; CF=0: символ отправлен в порт принтера
-				; CF=1: принтер не готов, B - символ не выведен
+				; CF=1: A - байт состояния принтера, B - символ не выведен
+
+;███████████████████████████████████████████████████████████████████████████████████████████████████████
+;			12. Коды ошибок DSS (регистр A при CF=1)
+;███████████████████████████████████████████████████████████████████████████████████████████████████████
+; #00 - нет ошибки / неизвестная ошибка
+; #01 - неверный номер функции
+; #02 - неверный номер диска/устройства
+; #03 - файл не найден
+; #04 - путь не найден
+; #05 - неверный файловый манипулятор
+; #06 - нет свободных файловых манипуляторов (слишком много открытых файлов)
+; #07 - файл уже существует
+; #08 - файл только для чтения
+; #09 - переполнение корневого каталога (ROOT)
+; #0A - нет свободного места на диске
+; #0B - каталог не пуст
+; #0C - попытка удалить текущий каталог
+; #0D - неизвестный формат / неверный носитель
+; #0E - недопустимая операция/доступ
+; #0F - каталог уже существует
+; #10 - неверное имя
+; #11 - неверный EXE-файл
+; #12 - неподдерживаемый формат EXE-файла
+; #13 - доступ запрещён (ACCESS_DENIED)
+; #14 - устройство не готово
+; #15 - ошибка позиционирования
+; #16 - сектор не найден
+; #17 - ошибка CRC
+; #18 - диск защищён от записи
+; #19 - ошибка чтения
+; #1A - ошибка записи
+; #1B - сбой диска
+; #1C - носитель сменён
+; #1D - устройство занято / нет носителя
+; #1E - недостаточно памяти
+; #1F - неверный идентификатор блока памяти
+; #20 - операция не поддерживается
+; #21 - превышен максимальный размер переменной окружения
+; #22 - (зарезервировано)
+; #23 - слишком много файлов в каталоге
+; #24 - слишком глубокая вложенность каталогов или число папок > 1023
+; #25 - операция прервана пользователем
+; #26 - общая ошибка
+; #27 - неожиданное завершение приложения
+; #30 - неверный видеорежим
+; #28..#2F, #31..#7F - зарезервировано
+; Ошибки драйверов имеют установленный бит #80 (маска DRV_MASK),
+; ошибки ATAPI - дополнительную маску. Полный список см.
+; в Shared_Includes/constants/dss_equ.inc (модуль DSS_Error).