Subversion Repositories NedoOS

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

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

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

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

хост(host) - точка подключения

errno - номер ошибки

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

SOCKET - дескриптор сокета. Знаковое 8-битное число.

sockaddr_in - структура, размером 15 байт, со следующими полями:
        sin_family - семейство адресов, беззнаковое 8-битное число.
                в текущей реализации допускается только значение 2 (AF_INET).
        sin_port - номер порта, 16-битное беззнаковое big-endian число.
        sin_addr - IP-адрес. Массив из четырёх 8-битных беззнаковых чисел.
                к примеру IP-адрес 1.2.3.4 располагается в памяти как defb 1,2,3,4
        sin_zero - зарезервировано. массив из 8 байт.

************************* Возможные номера ошибок (errno)*************************
SHUT_RDWR               EQU 2
ERR_EAGAIN              EQU 35          ;/* Try again */
ERR_EWOULDBLOCK EQU ERR_EAGAIN  ;/* Operation would block */
ERR_INTR                EQU 4
ERR_NFILE               EQU 23
ERR_ALREADY     EQU 37
ERR_NOTSOCK     EQU 38
ERR_EMSGSIZE    EQU 40    ;/* Message too long */
ERR_PROTOTYPE   EQU 41
ERR_AFNOSUPPORT EQU 47
ERR_HOSTUNREACH EQU 65
ERR_ECONNABORTED EQU    53      /* Software caused connection abort */
ERR_CONNRESET   EQU 54
ERR_NOTCONN     EQU 57

************************* Протоколы соединений *************************
SOCK_STREAM EQU 0x01            ;tcp/ip
SOCK_ICMP       EQU 0x02                ;icmp
SOCK_DGRAM      EQU 0x03                ;udp/ip

AF_INET EQU 2

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

Все вызовы не блокирующие(за исключением OS_NETCONNECT), т.е. 
не ожидадают отправку\прием данных, либо подключения.
При необходимости использования блокирующих функций - реализовывать самостоятельно внутри процесса.

*********************** OS_NETSOCKET **********************
        Создаёт сокет.
        Макрос вызова функции ядра.
        Все аргументы в регистрах:
                D - семейство адресов, беззнаковое 8-битное число, допускается только значение 2 (AF_INET).
                E - протокол соединения(0x01 tcp/ip, 0x02 icmp, 0x03 udp/ip)
        Возвращаемые значения в регистрах:
                L - SOCKET при положительном значении, при отрицательном значении  - функция завершилась с ошибкой.
                А - errno при ошибке.
                
        Возможные ошибки:
                ERR_AFNOSUPPORT - семейство адресов не поддерживается
                ERR_NFILE               - нет свободных сокетов
                ERR_PROTOTYPE   - протокол не поддерживается
                
        Пример создания TCP/IP сокета:
                LD D,AF_INET;2
                LD E,SOCK_STREAM
                OS_NETSOCKET
                BIT 7,L
                JP NZ,ERR_EXIT  ;обработка ошибки
                LD A,L
                LD (SOC),A              ;сохраняем дескриптор сокета.
                
        Примечания:
                При закрытии процесса, закрываются все сокеты созданные этим процессом.
                Сокеты защищены от использования другим процессом.
                Номер исходящего порта присваивается автоматически из диапазона 49152...65535
                
*********************** OS_NETSHUTDOWN **********************
        Закрытие сокета.
        Макрос вызова функции ядра.
        Все аргументы в регистрах:
                A - SOCKET
                E - Варианты закрытия, 0 - закрыть немедленно, 1 - закрыть только если буфер отправки пуст.
        Возвращаемые значения в регистрах:
                L - При отрицательном значении  - функция завершилась с ошибкой.
                А - errno при ошибке.
        
        Пример закрытия сокета с ожиданием опустошения буфера отправки:
close_wait:
                LD A,(SOC)
                LD E,1
                OS_NETSHUTDOWN
                BIT 7,L
                RET Z                   ;сокет закрылся
                CP ERR_EAGAIN
                JP NZ,ERR_EXIT          ;обработка ошибки не связанной с ожиданием отправки.
                OS_YIELD                ;не обязательно. Если время не критично,
                                                ;то отдадим квант времени системе.
                JR close_wait ;ожидаем отправки данных
                
        Возможные ошибки:
                ERR_NOTSOCK - не действительный дескриптор сокета
                ERR_EAGAIN      - буфер отправки не пуст
                
        Примечание: Керналь закрывает сокеты процесса при закрытии процесса. 
                Но, ввиду ограниченного количества сокетов, рекомендуется закрывать сокет 
                как только он становится не нужен.
        
*********************** OS_NETCONNECT **********************
        Подключить TCP/IP сокет к хосту.
        Макрос вызова функции ядра.
        Все аргументы в регистрах:
                A - SOCKET
                DE - указатель на структуру sockaddr_in содержащую IP адрес и порт хоста.
        Возвращаемые значения в регистрах:
                L - При отрицательном значении  - функция завершилась с ошибкой.
                А - errno при ошибке.
        Возможные ошибки:
                ERR_NOTSOCK     - не действительный дескриптор сокета
                ERR_ALREADY     - сокет уже подключен
                ERR_HOSTUNREACH - хост не доступн, либо отверг подключение.
                
        Пример подключения к хосту с IP адресом 1.2.3.4 на порт 80:
                LD A,(SOC)
                LD DE,destination_host
                OS_NETCONNECT
                BIT 7,L
                JP NZ,ERR_EXIT  ;обработка ошибки
                ... ;подключились
                
destination_host                
                DEFB AF_INET 
                DEFB 0,80                               ;порт назначения
                DEFB 1,2,3,4                    ;IP адрес назначения
                DEFB 0,0,0,0,0,0,0,0    ;резерв
                
        Примечание: Данная функция применима только к TCP/IP сокетам.

*********************** OS_BIND **********************
        Присвоение сокету конкретного номера исходящего порта.
        Макрос вызова функции ядра.
        Все аргументы в регистрах:
                A - SOCKET
                DE - указатель на структуру sockaddr_in содержащую номер исходящего порта.
                        (остальные поля структуры не используются, но обязаны присутствовать)
        Возвращаемые значения в регистрах:
                L - При отрицательном значении - функция завершилась с ошибкой.
                А - errno при ошибке.
        Возможные ошибки:
                ERR_NOTSOCK     - не действительный дескриптор сокета
                
        Пример присвоения сокету исходяего порта 433:
                LD A,(SOC)
                LD DE,source_host
                OS_BIND
                BIT 7,L
                JP NZ,ERR_EXIT  ;обработка ошибки
                ... ;удачно, продолжаем работу
                
source_host             
                DEFB AF_INET 
                DEFB high(433),low(433) ;исходящий порт
                DEFB 0,0,0,0                    ;исходящий IP адрес (не используется в текущей реализации)
                DEFB 0,0,0,0,0,0,0,0    ;резерв
        Примечание: В режиме TCP/IP функция вызывается(если нужна) до вызовов OS_NETCONNECT или OS_LISTEN.
        
*********************** OS_LISTEN **********************
        Включить режим прослушивания исходящего порта(режим сервера) TCP/IP сокета.
        Макрос вызова функции ядра.
        Все аргументы в регистрах:
                A - SOCKET
        Возвращаемые значения в регистрах:
                L - При отрицательном значении - функция завершилась с ошибкой.
                А - errno при ошибке.
        Возможные ошибки:
                ERR_NOTSOCK     - не действительный дескриптор сокета
                ERR_ALREADY     - сокет уже подключен
                
        Пример включения режима прослушивания:
                LD A,(SOC)
                OS_LISTEN
                BIT 7,L
                JP NZ,ERR_EXIT  ;обработка ошибки
                ... ;удачно, продолжаем работу
                
        Примечание: Данная функция применима только к TCP/IP сокетам.
                Как правило функция вызывается(если нужна) после вызова OS_BIND.
                
*********************** OS_ACCEPT **********************
        Принять входящее TCP/IP подключение.
        Макрос вызова функции ядра.
        Все аргументы в регистрах:
                A - SOCKET
        Возвращаемые значения в регистрах:
                L - SOCKET при положительном значении, при отрицательном значении  - функция завершилась с ошибкой.
                А - errno при ошибке.
        Возможные ошибки:
                ERR_NOTSOCK             - не действительный дескриптор сокета
                ERR_ECONNABORTED        - общая ошибка сокета
                ERR_EAGAIN                      - входящих подключений пока нет
                
        Пример принятия соединения с ожиданием подключения:
WAIT_CLIENTS
                LD A,(SOC)
                OS_ACCEPT
                BIT 7,L
                JR Z,ESTABLISHED
                CP ERR_EAGAIN
                JP NZ,ERR_EXIT  ;обработка ошибки
                OS_YIELD                ;не обязательно. Если время реагирования на подключение не критично,
                                                ;то отдадим квант времени системе.
                JR WAIT_CLIENTS ;никто не подключился, ждём
ESTABLISHED
                LD A,L                          ;㤠筮
                LD (SOC_CLIENT),A       ;сохраняем дескриптор сокета.
                ... ;продолжаем работу
                
        Примечания: Данная функция применима только к TCP/IP сокетам.
                Функция вызывается после вызова OS_LISTEN.
                Возвращает новый дескриптор сокета с принятым соединением. Сокет прослушки продолжает слушать.
                Если дальнейшая прослушка не требуется, то рекомендуется сразу закрывать слушающий сокет.
                При недостатке сокетов, возвращается дескриптор подключенного сокета прослушки, 
                в этом случае нет дальнейшего прослушивания.
                Т.е. при закрытии слушающего сокета, необходимо проверить(путем сравнения дескрипторов)
                не является ли он сокетом с принятым соединением.
                
*********************** OS_WIZNETREAD **********************
        Прочитать входящие данные.
        Макрос вызова функции ядра.
        
        При протоколе TCP/IP все аргументы в регистрах:
                A - SOCKET
                DE - указатель на буфер для принятия данных
                HL - размер буфера(в байтах)
        При протоколе отличном от TCP/IP все аргументы в регистрах:
                A - SOCKET
                DE - указатель на структуру sockaddr_in, в неё помещается(ядром) IP-адрес и порт хоста отправившего данные.
                IX - указатель на буфер для принятия данных
                HL - размер буфера(в байтах)
        Возвращаемые значения в регистрах:
                HL - при отрицательном значении функция завершилась с ошибкой,
                        про значении больше нуля возвращается действительный размер(в байтах) принятых данных,
                        нулевого значения вызов не возвращает.
                А - errno при ошибке.
        Возможные ошибки:
                ERR_NOTSOCK - не действительный дескриптор сокета
                ERR_EAGAIN      - входящих данных пока нет
                ERR_NOTCONN     - сокет с неустановленным\пропавшем соединением(при протоколе TCP/IP)
                
        Пример принятия данных по протоколу TCP/IP с ожиданием данных:
WAIT_DATA
                LD A,(SOC)
                LD DE,BUF
                LD HL,BUF_SIZE
                OS_WIZNETREAD
                BIT 7,H
                JR Z,RECEIVED   ;ошибок нет
                CP ERR_EAGAIN
                JP NZ,ERR_EXIT  ;обработка ошибки
                OS_YIELD                ;не обязательно. Если время реагирования на пришедшие данные не критично,
                                                ;то отдадим квант времени системе.
                JR WAIT_DATA    ;данных нет, ждём
RECEIVED
                LD (DATA_SIZE),HL       ;удачно. если требуется, то сохраняем количество принятых данных.
                ... ;продолжаем работу

BUF             DEFS 1000
BUF_SIZE EQU $-BUF
        
        Примечания: При протоколе отличном от TCP/IP, необходимо единовременно прочитать весь пакет, 
                иначе недовычитанные данные пакета игнорируются.

*********************** OS_WIZNETWRITE **********************
        Отправить пакет данных.
        Макрос вызова функции ядра.
        
        При протоколе TCP/IP все аргументы в регистрах:
                A - SOCKET
                DE - указатель на буфер с данными
                HL - размер данных(в байтах), в текущей реализации максимум 8192 байта
        При протоколе отличном от TCP/IP все аргументы в регистрах:
                A - SOCKET
                DE - указатель на структуру sockaddr_in, в неё необходимо поместить IP-адрес и порт хоста получателя
                IX - указатель на буфер с данными
                HL - размер данных(в байтах), в текущей реализации максимум 8192 байта
        Возвращаемые значения в регистрах:
                HL - при отрицательном значении функция завершилась с ошибкой,
                        иначе возвращается действительный размер(в байтах) отправленных данных,
                А - errno при ошибке.
        Возможные ошибки:
                ERR_NOTSOCK - не действительный дескриптор сокета
                ERR_NOTCONN     - сокет с неустановленным\пропавшем соединением(при протоколе TCP/IP)
                ERR_EMSGSIZE - в буфере отправки нет места, либо пакет слишком большой
                
        Пример отправки данных по протоколу TCP/IP с ожиданием данных:
WAIT_SEND
                LD A,(SOC)
                LD DE,BUF
                LD HL,BUF_SIZE
                OS_WIZNETWRITE
                BIT 7,H
                JR Z,SEND_OK    ;ошибок нет
                CP ERR_EMSGSIZE
                JP NZ,ERR_EXIT  ;обработка ошибки
                OS_YIELD                ;не обязательно. Если время не критично,
                                                ;то отдадим квант времени системе.
                JR WAIT_SEND    ;буфер отправки переполнен, ждём освобождения
SEND_OK
                LD (DATA_SIZE),HL       ;удачно. если требуется, то сохраняем количество отправленных данных.
                ... ;продолжаем работу
        
BUF             DEFB "Hello World!"
BUF_SIZE EQU $-BUF