XtratuM Interface ----------------- NOTE: As can be seen below there exist some functions with two similar versions for example the xm_set_domain_priority function and the __xm_set_domain_priority function. The reason of this is that one of the functions is a simplified version (with less parameters) than the other one but basically both of them carry out the same action. (in the case of the example above, xm_set_domain_priority allows to change the priority of the current domain, whereas __xm_set_domain_priority to determine the domain which the priority is changed. ------------------------------------------------------------------------------ unsigned int xm_min_priority(void); OVERVIEW: xm_min_priority returns the minimum priority which can be allocated to an XtratuM domain. ------------------------------------------------------------------------------ unsigned int xm_max_priority(void); OVERVIEW: xm_max_priority return the maximum priority wich can be allocated to an XtratuM domain. ------------------------------------------------------------------------------ int xm_create_domain(xm_domain_t *domain, char *name, unsigned int priority, int (*main_func) (void)); OVERVIEW: xm_create_domain creates a new domain with the name "name", programmer also has to specify the initial priority and the function which will be executed when the domain starts. The parameter domain is a out parameter which returns a pointer of the new domain. NOTE: This function can be only called from the root_domain, it means that can not be created new domain from non root domains. ------------------------------------------------------------------------------ void xm_destroy_domain (struct xm_domain_struct *domain); OVERVIEW: This functions finish off an existing domain. NOTE: This function can be only called from the root_domain. ------------------------------------------------------------------------------ void xm_suspend_domain(void); void __xm_suspend_domain (xm_domain_t domain); OVERVIEW: xm_suspend_domain suspeds the caller domain till a event which would be intercepted and not masked by the caller domain arrives. The second version of this functions allows to specify which domain is going to be suspended. ------------------------------------------------------------------------------ void xm_set_domain_priority(unsigned int priority); void __xm_set_domain_priority (xm_domain_t domain, unsigned int priority); OVERVIEW: xm_set_domain_priority changes the priority of the caller domain to "priority". The second versions lets the affected domain. ------------------------------------------------------------------------------ int xm_install_event_handler(int event, handler_t handler, int flags); int __xm_install_event_handler (xm_domain_t domain, int event, handler_t handler, int flags); OVERVIEW: xm_install_events_handler installs a handler to catch a event, when a handler is installed the event is set as intercepted and masked. The domain has still to unmasked the event to be able to manage it. The parameter flag can be: xm_PASS_EVENT: The event will be delibered to less priority domains as well. xm_BLOCK_EVENT: The event is blocked by this domain and it won't be delibered to the less priority domains. NOTE1: To uninstall an event handler is enough to call this function but with no handler, that is, passing a NULL as handler parameter. NOTE2: When an event handler is called the behaviour of XtratuM is to masked the called event and to disable the bus for this domain. When process of the event finish, XtratuM automatically enables the bus. However, the mask of the event is not automatically unmasked. So the domain has to unasked the event if it wants to receive this events again. NOTE3: For efficience reasons there exit just 32 (0 ... 31) possible events, in the i386 architecture the 17 (0 ... 16) firsts are reserved to abstract the hardware interrupts. In the i386 architecture possible events are: Reserved hardware interrupts: HW_TIMER_EVENT HW_KEYBOARD_EVENT HW_CTLR2_EVENT HW_SERIAL2_EVENT HW_SERIAL1_EVENT HW_PARALLEL2_EVENT HW_DISKETTE_EVENT HW_PARALLEL1_EVENT HW_RTC_EVENT HW_SOFT_EVENT HW_RESERVED1_EVENT HW_RESERVED2_EVENT HW_RESERVED3_EVENT HW_COPROCESSOR_EVENT HW_FIXED_EVENT HW_RESERVED4_EVENT HW_LOCAL_APIC_TIMER_EVENT Domain defined events: USER_EVENT_0 USER_EVENT_1 USER_EVENT_2 USER_EVENT_3 USER_EVENT_4 USER_EVENT_5 USER_EVENT_6 USER_EVENT_7 USER_EVENT_8 USER_EVENT_9 USER_EVENT_10 USER_EVENT_11 USER_EVENT_12 USER_EVENT_13 USER_EVENT_14 ------------------------------------------------------------------------------ int xm_install_trap_handler(int trap, handler_t handler); int __xm_install_trap_handler (xm_domain_t domain, int trap, handler_t handler); ------------------------------------------------------------------------------ int xm_raise_event_all_domains (int event, int flags); OVERVIEW: This function lets to pend an event in all existing domains. The parameter flags can be: xm_RAISE_EVENT_NOW: The event is marked as pending and processed before the function xm_raise_event_all_domains returns. If there is some process more prioritary which has intercepted this event, the caller domain will be preemted. xm_DEFER_EVENT: The event is marked as pending to be handled in the future. ------------------------------------------------------------------------------ int xm_raise_event (xm_domain_t domain, int event, int flags); OVERVIEW: xm_raise_event has the same behaviour as the function xm_raise_event_all_domains but the affected domain has to be specificated. The parameter flags can be: xm_RAISE_EVENT_NOW: The event is marked as pending and processed before the function xm_raise_event_all_domains returns. If there is some process more prioritary which has intercepted this event, the caller domain will be preemted. xm_DEFER_EVENT: The event is set as pending to be handled in the future. ------------------------------------------------------------------------------ void xm_disable_bus_event (int event); ------------------------------------------------------------------------------ void xm_enable_bus_event (int event); ------------------------------------------------------------------------------ void xm_enable_events(void); void __xm_enable_events (xm_domain_t domain); OVERVIEW: xm_enable_bus_event lets enable events for the caller domain. ------------------------------------------------------------------------------ void xm_disable_events(void); void __xm_disable_events (xm_domain_t domain); OVERVIEW: xm_disable_bus_event lets disable events for the caller domain. No more events will be received by a domain while its bus was disabled. This function only affects to the caller domain. ------------------------------------------------------------------------------ void xm_mask_event(int event); void __xm_mask_event (xm_domain_t domain, int event); ------------------------------------------------------------------------------ void xm_unmask_event(int event); void __xm_unmask_event (xm_domain_t domain, int event); ------------------------------------------------------------------------------ void xm_mask_all_events(void); void __xm_mask_all_events (xm_domain_t domain); ------------------------------------------------------------------------------ void xm_unmask_all_events(void); void __xm_unmask_all_events (xm_domain_t domain); ------------------------------------------------------------------------------ xm_domain_t xm_domain_self(void); OVERVIEW: xm_domain_self returns a pointer of the caller domain. ------------------------------------------------------------------------------