Subversion Repositories Kolibri OS

Дата последней правки 26/07/2013.

Last edit: 26/07/2013

Подсистема событий ядра может понадобиться при написании драйверов и сервисов, работающих в режиме ядра.

Kernel event subsystem may be useful when writing drivers and kernel space

Она не имеет отношения к подсистеме событий пользовательского интерфейса.

services. It is not related to the subsystem of GUI events. An event, from the

С точки зрения ядра событие - объект ядра и принадлежит создавшему его потоку.

kernel's point of view, is a kernel space object which is owned by the thread

   .bk          dd ?    ; prev object in list

   .bk          dd ?    ; prev object in list

   .pid         dd ?    ; owner id. идентификатор владельца (потока)

   .pid         dd ?    ; owner (thread) id

   .id          dd ?    ; event uid. уникальный идентификатор события (просто номерок)

   .id          dd ?    ; event uid. (just a number)

   .state       dd ?    ; internal flags; см. далее.

   .state       dd ?    ; internal flags; see below

   .code        dd ?    ; старший байт класс события, ; следующий байт приоритет 

   .code        dd ?    ; MSB: event class; next byte: priority

                        ; (будет использоваться только внутри ядра, при чтении всегда 0),

                        ; (used by kernel only, always 0 for reading),

                        ; Чем больше численное значение двойного слова тем важнее событие.

                        ; The higher dword value the higher event priority.

                        ; два младших байта код события. 

                        ; Two LSBs: event code.

                        ; от поля .code. (Здесь можно передавать какие-то свои данные,

                rd 5    ; .data: the structure of this field is not defined and

}

}

        RT_INP_FULL       = 0xFF000003

        RT_INP_FULL       = 0xFF000003

        RT_OUT_FULL       = 0xFF000004

        RT_OUT_FULL       = 0xFF000004

Flags of EVENT.state field are defined in gui/event.inc.

Флаги поля EVENT.state определены в gui/event.inc.

        EVENT_WATCHED    = 0x10000000 ; bit 28: owner thread is waiting for the

	EVENT_SIGNALED   = 0x20000000 ;бит 29  событие активно/неактивно;

        MANUAL_RESET     = 0x40000000 ; bit 30: do not deactivate event

	EVENT_WATCHED    = 0x10000000 ;бит 28, поток-владелец ожидает активации события;

                                      :         automatically on receive

Код находится в gui/event.inc.

Code is located in gui/event.inc.

Сами события как обьекты существуют в памяти ядра в виде двусвязного списка (см. поля .bk и .fd).

Event objects live in kernel memory as a double-linked list (see fields .bk and

При инициализации ядро резервирует память и создает 512 таких обьектов, помещая их в список FreeEvents

.fd). While initialization the kernel reserves memory, creates 512 events and

(свободных событий). При нехватке событий (все заняты, а нужно ещё) ядро создает ещё 512 свободных

places them into FreeEvents list. When out of free event, kernel creates another

и т.д. Каждый поток имеет свои (двусвязные) списки (в которые может быть помещено событие):

placed to:

ObjList - список объектов ядра, ассоциированных с этим потоком; 

        ObjList -- a list of kernel objects associated with the thread;

EventList - список событий ядра для потока.

        EventList -- a list of kernel events for the thread.

Сами события, физически, при перемещении между списками и смене очередности в списке не перемещаются

When events are moved between lists or reordered their data are not copied. This

и не копируются. Это происходит только благодаря модификации полей .fd и .bk. Принцип работы списков,

is done only via modification of .fd and .bk fields. These lists work as FIFO

как очередей - FIFO. Использутся неблокирующая отправка и блокирующее получение. Адресация - прямая

queues. Sending does not block, receiving blocks. Addressing is direct, by

(у события всегда есть поток-владелец), по идентификатору потока. 

thread id. There always is an owner thread for an event.

Жизненый цикл событий определяется флагами при создании. По умолчанию ядро использует значения 

Event's life cycle is defined by flags while creation. By default the kernel

MANUAL_RESET = 0 и MANUAL_DESTROY = 0. Такое событие является "одноразовым", и автоматически освобождается 

uses values MANUAL_RESET = 0 and MANUAL_DESTROY = 0. Such an event is oneshot

ядром, возвращаясь в список свободных событий после получения.

and is automatically freed by the kernel and returned to the FreeEvents list

Событие с флагом MANUAL_DESTROY = 1 после получения переходит в неактивное состояние, но остаётся в списке 

when received. An event with flag MANUAL_DESTROY = 1 becomes inactive when

объектов потока и может использоваться снова. Событие с флагами MANUAL_DESTROY =1 и MANUAL_RESET = 1 

received but remains in thread's object list and can be reused. An event with

остаётся активным после получения и может быть сброшено вызовом ClearEvent.

can be reset via call to ClearEvent.

Пример (вариант) жизненного цикла события из звуковой подсистемы:

A life cycle example of a sound subsystem event:

Для зукового буфера (их может быть несколько) драйвер создает событие в списке ObjList с помощью

   by calling CreateEvent with flag MANUAL_DESTROY.

CreateEvent и флагом MANUAL_DESTROY. Далее драйвер вызывает WaitEvent для этого события (ожидает флага

 * Then driver calls WaitEvent for the event (waits for EVENT_SIGNALED event

EVENT_SIGNALED в событии) и блокируется, в ожидании запроса на пополнение буфера. Запрос отправляется

   flag) and blocks waiting for buffer update request.

с помощью RaiseEvent из другого потока. Отправка (RaiseEvent) и получение (WaitEvent) циклически 

 * The buffer update request is sent with RaiseEvent from another thread.

повторяются при опустошении буфера. При остановке воспроизведения драйвер деактивирует событие с помощью

 * Sending (RaiseEvent) and receiving (WaitEvent) are repeated as buffer gets

ClearEvent.

 * Driver deactivates the event with ClearEvent when playback is stopped.

Вообще говоря, структура события приведена здесь только лишь для понимания принципов работы подсистемы.

Actually, the event structure is described here only for understanding of

Самостоятельная работа с полями не приветствуется, ввиду возможных в будущем проблем с совместимостью.

subsystem work principles. Direct field access is discouraged due to possible

которым предоставляет функция. При этом пару "указатель на событие" и "уникальный идентификатор события"

compatibility issues in the future. Only API calls should be used. A pair

следует рассматривать как один 64-х битный уникальный идентификатор. (Если вы вызвали CreateEvent, напимер,

"pointer to an event" and "event id" is considered a single 64-bit id. This id

его нужно запомнить где-нибудь [если это нужно] для дальнейшей работы с событием).

event.

        WaitEvent

        WaitEvent

        WaitEventTimeout

        WaitEventTimeout

        Для пользовательских приложений Ф68.14 (GetEvent с обёрткой)

        For user applications sysfn 68.14 (a wrapper to GetEvent)

---------------------------------------------------------------------------------------------

--------------------------------------------------------------------------------

CreateEvent:

CreateEvent:

        Создаёт новое событие в очереди ObjList текущего потока. 

        Creates a new event in ObjList queue of current thread.

        Устанавливает:

        Sets:

                EVENT.destroy   <= внутренний деструктор по умолчанию;

                EVENT.destroy   <= default internal destructor

                EVENT.pid       <= текущий Process id;

                EVENT.pid       <= current Process id

                EVENT.id        <= уникальный идентификатор;

                EVENT.id        <= unique id

                EVENT.state     <= ecx - флаги;

                EVENT.state     <= ecx: flags

                EVENT.code      <= [esi], (если esi=0, то не копирует), размер 6*dword;

                EVENT.code      <= [esi]: size is 6*dword, do not copy if esi=0

        Возвращает:

        Returns:

                edx - Event.id.

                edx -- Event.id.

        Портит: eax,ebx,edx,ecx,esi,edi     

        Destroys: eax,ebx,edx,ecx,esi,edi

---------------------------------------------------------------------------------------------        

--------------------------------------------------------------------------------

RaiseEvent:

RaiseEvent:

        Активирует уже существующее событие (может принадлежать другому потоку) установкой 

        Activates existing event (may be owned by another thread) by setting

        флага EVENT_SIGNALED. Если необходимо, -  устанавливает данные EVENT.code.

        EVENT_SIGNALED flag. Sets EVENT.code data if necessary. Does nothing

        Если флаг EVENT_SIGNALED в самом событии уже активен - больше ничего не делает. 

        EVENT_SIGNALED flag is not set in the event it will be set, except when

                {EVENT_WATCHED в edx=1 и EVENT_WATCHED в событии=0}.

        EVENT_WATCHED in edx = 1 and EVENT_WATCHED in the event = 0. I.e. while

        Т.е. при установке EVENT_WATCHED в edx, проверяется, ожидает ли поток-владелец активации

        setting EVENT_WATCHED in edx it is checked if owner thread is waiting

        события.

        for event activation. No flags, except EVENT_SIGNALED, are modified in

        Кроме EVENT_SIGNALED в событии никакие другие флаги не модифицируются.

        the event.

        Принимает:

                eax     -- pointer to event

                eax     - указатель на событие;

                ebx     -- id

                ebx     - id, уникальный идентификатор события;

                edx     -- flags (see EVENT.state)

                edx     - флаги для операции (формат EVENT.state);

        Sets:

        Возвращает: ?

        Returns: ?

        Портит: eax,ebx,edx,ecx,esi,edi .

        Destroys: eax,ebx,edx,ecx,esi,edi

---------------------------------------------------------------------------------------------        

--------------------------------------------------------------------------------

ClearEvent:

ClearEvent:

        Перемещает событие в список ObjList потока-владельца. (Возможно оно там и находилось.)

        Move event to ObjList of owner thread. (May be it was already there.)

        Сбрасывает флаги EVENT_SIGNALED, EVENT_WATCHED. С остальными полями (.code, .id),

        Reset flags EVENT_SIGNALED and EVENT_WATCHED, keep other fields (.code,

        ничего не делает.

        .id).

        Принимает:

        Gets:

                eax     - указатель на событие;

                eax     -- pointer to event

        Возвращает: ?

        Returns: ?

        Портит: eax,ebx,ecx,edi .

        Destroys: eax,ebx,ecx,edi

---------------------------------------------------------------------------------------------        

--------------------------------------------------------------------------------

SendEvent:

SendEvent:

        Создаёт новое событие в списке событий целевого потока. Устанавливает в событии

        Create a new event in the event list of target thread. Sets

        флаг EVENT_SIGNALED.

        EVENT_SIGNALED flag in the event.

        Принимает:

        Gets:

                EVENT.pid       <= eax     - pid, идентификатор целевого потока;

                EVENT.pid       <= eax: target thread id;

                EVENT.code      <= [esi], (если esi=0, то не копирует), размер 6*dword;

                EVENT.code      <= [esi]: size is 6*dword, do not copy if esi=0

        Возвращает:

        Returns:

                edx - Event.id. уникальный идентификатор.

                edx -- Event.id

        Портит: eax,ebx,ecx,esi,edi .

        Destroys: eax,ebx,ecx,esi,edi

---------------------------------------------------------------------------------------------        

--------------------------------------------------------------------------------

DestroyEvent:

DestroyEvent:

        Переносит EVENT в список FreeEvents, чистит поля .magic,.destroy,.pid,.id.

        Moves event to FreeEvents, clears fields .magic, .destroy, .pid, .id.

        Событие может принадлежать другому потоку.

        The event may be owned by other thread.

        Принимает:

        Gets:

                eax     - указатель на событие;

                eax     -- pointer to event

                ebx     - id, уникальный идентификатор события.

                ebx     -- event id

                eax     - 0 при ошибке, не 0 при успехе.

                eax     -- 0 for error, non-zero for success

        Портит: eax,ebx,ecx .

        Destroy: eax,ebx,ecx

---------------------------------------------------------------------------------------------        

--------------------------------------------------------------------------------

WaitEvent:

WaitEvent:

        Бесконечно ожидает установки флага EVENT_SIGNALED в конкретном событии, принадлежащем

        Wait infinitely until flag EVENT_SIGNALED is set in the event owned by

        вызывающему WaitEvent потоку. Сигнализирующий поток устанавливат этот флаг через

        the caller thread. This flag is set by signaling thread via RaiseEvent.

        RaiseEvent. Ожидающий поток замораживается путем перевода TASKDATA.state<=TSTATE_WAITING=5.

        If flag MANUAL_RESET is NOT set in the event then:

        Перед заморозкой устанавливается флаг EVENT_WATCHED в событии.

                EVENT_SIGNALED and EVENT_WATCHED are reset when the event is

        Если в полученном событии НЕ установлен MANUAL_RESET, то:

                received.

                {EVENT_SIGNALED и EVENT_WATCHED по получении события сбрасываются.

                When MANUAL_DESTROY is

                 При неактивном  MANUAL_DESTROY - событие уничтожается штатно (DestroyEvent),

                        inactive: the event is destroyed by DestroyEvent,

                 а при активном - перемещается в список ObjList текущего слота.}

                        active: the event is moved to ObjList of current thread.

        Принимает:

        Gets:

                eax     - указатель на событие;

                eax     -- pointer to event

        Возвращает: ?

        Returns: ?

        Портит: eax,ebx,edx,ecx,esi,edi .

        Destroys: eax,ebx,edx,ecx,esi,edi

---------------------------------------------------------------------------------------------                

--------------------------------------------------------------------------------

WaitEventTimeout:

WaitEventTimeout:

        Ожидает с таймаутом установки флага EVENT_SIGNALED в конкретном событии, принадлежащем

        Wait with a timeout until flag EVENT_SIGNALED is set in the event owned

        вызывающему WaitEventTimeout потоку. Сигнализирующий поток устанавливат этот флаг через

        by caller thread. This flag is set by signaling thread via RaiseEvent.

        RaiseEvent. Ожидающий поток замораживается путем перевода TASKDATA.state<=TSTATE_WAITING=5.

        If flag MANUAL_RESET is NOT set in the event then:

        Перед заморозкой устанавливается флаг EVENT_WATCHED в событии.

                EVENT_SIGNALED and EVENT_WATCHED are reset when the event is

        Если в полученном событии НЕ установлен MANUAL_RESET, то:

                received.

                {EVENT_SIGNALED и EVENT_WATCHED по получении события сбрасываются.

                When MANUAL_DESTROY is

                 При неактивном  MANUAL_DESTROY - событие уничтожается штатно (DestroyEvent),

                        inactive: the event is destroyed by DestroyEvent,

                 а при активном - перемещается в список ObjList текущего слота.}

                        active: the event is moved to ObjList of current thread.

        Принимает:

        Gets:

                eax     - указатель на событие;

                eax     -- pointer to event

                ebx     - id, уникальный идентификатор события.

                ebx     -- event id

                ecx     - время ожидания в тиках системного таймера.

                ecx     -- timeout, in ticks of system timer

        Возвращает:

        Returns:

                          не 0, если было активировано.

                           not 0 if activated

        Портит: eax,ebx,edx,ecx,esi,edi .

        Destroys: eax,ebx,edx,ecx,esi,edi

---------------------------------------------------------------------------------------------        

--------------------------------------------------------------------------------

GetEvent:

        Waits infinitely for any event in the queue of current thread. Thread is

        Бесконечно ожидает любое событие в очереди событий текущего потока. Поток замораживается

        frozen by setting TASKDATA.state <= TSTATE_WAITING = 5. Event data

        путем перевода TASKDATA.state<=TSTATE_WAITING=5. Данные события (EVENT.code+5*dword)

        If flag MANUAL_RESET is NOT set in the event then:

        по получении копируются в указанный буфер. Сбрасывает байт приоритета (см. выше) в буфере.

                EVENT_SIGNALED and EVENT_WATCHED are reset when the event is

        Если в полученном событии НЕ установлен MANUAL_RESET, то:

                received.

                {EVENT_SIGNALED и EVENT_WATCHED по получении события сбрасываются.

                When MANUAL_DESTROY is

                 При неактивном  MANUAL_DESTROY - событие уничтожается штатно (DestroyEvent),

                        inactive: the event is destroyed by DestroyEvent,

                 а при активном - перемещается в список ObjList текущего слота.}

                        active: the event is moved to ObjList of current thread.

        Принимает:

        Gets:

                edi     - указатель на буфер, куда копировать данные.

                edi     -- pointer to buffer to copy data

        Возвращает:

        Returns:

                буфер, содержащий следующую информацию:

                buffer with following data:

                +0: (EVENT.code) dword: идентификатор последующих данных сигнала

                +0: (EVENT.code) dword: id of following signal data

                +4: (EVENT.data, поле формально не определено) данные принятого 

                +4: (EVENT.data) 5*dword: signal data, format depends on

                сигнала (5*dword), формат которых определяется первым dword-ом.     

                    EVENT.code

        Портит: eax,ebx,edx,ecx,esi,edi .

        Destroys: eax,ebx,edx,ecx,esi,edi

--------------------------------------------------------------------------------------------

--------------------------------------------------------------------------------

Ф 68.14 для приложений:         ;это тот же GetEvent, но с обёрткой.

        Waits infinitely for any event in the queue of current thread. Thread is

        Бесконечно ожидает любое событие в очереди событий текущего потока. Ожидающий поток

        frozen by setting TASKDATA.state <= TSTATE_WAITING = 5. Event data

        замораживается путем перевода TASKDATA.state<=TSTATE_WAITING=5. Данные события (EVENT.code+5*dword)

        (EVENT.code + 5*dword) are copied to specified buffer when received.

        копируются в указанный буфер. Сбрасывает байт приоритета (см. выше) в буфере.

        Reset priority byte (see above) in the buffer.

        Принимает:

        Gets:

                eax     - 68 - номер функции

                eax     -- 68: function number

                ebx     - 14 - номер подфункции

                ebx     -- 14: subfunction number

                ecx     - указатель на буфер для информации (размер 6*dword)

                ecx     -- pointer to data buffer (size is 6*dword)

        Возвращает:

        Returns:

                буфер, на который указывает ecx, содержит следующую информацию:

                ecx = buffer with following data:

                +0: (EVENT.code) dword: идентификатор последующих данных сигнала

                +0: (EVENT.code) dword: id of following signal data