X-HYP for ARM hypercalls

Introduction

X-Hyp for ARM defines 54 hypercalls allowing a domain to ask for X-Hyp services.

List of hypercalls

_HYP_syscall

This hypercall is used in a domain having at least two internal functional modes, like we usualy have in GPOS and some RTOS, when the unpriviledge code inside the domain wants to ask services to the priviledged code of the same domain.

Typically, a system call from an intra domain application.

The priviledged code of the domain must have define an entry to be called on system calls using the _HYP_syscall_requesthypercall.

#define _HYP_syscall		0

_HYP_console

This hypercall is used when a domain requests debug information to be print immediatly by the hypervisor.

This hypercall is redirected to the standard console hypercall, see _HYP_io_write, if the hypervisor is not in debug mode.

#define _HYP_console		1

Registers specification on call

Register	Usage
R0	a character or a pointer to a string. or a caracter in low byte if R1 is 0.
R1	if 0 R0 holds a caracter, else it is the string length

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_yield

Using this hypercall, a domain can relinquish the processor. Depending of the hypervisor scheduler in use it may induce a domain switch or lead to a CPU idle state until next domain is to be scheduled.

#define _HYP_yield		2

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_getpage, _HYP_freepage

These hypercalls are not available in the current version. They are reserved for a later version of Xhyp with extended memory management capabilities.

#define _HYP_getpage		3
#define _HYP_freepage		4

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_irq_request

The _HYP_irq_request hypercall allows a domain to define an entry to receive interrupts.

#define _HYP_irq_request	5

Registers specification on call

Register	Usage
R0	a pointer to the interrupt routine
R1	a pointer to the stack for interrupt

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

_HYP_irq_enable

Enable IRQ for the domain.

In the shared page, both v_irq_enabled or v_cpsr may be modified.

#define _HYP_irq_enable		6

Registers specification on call

Register	Usage
R0	IRQ mask. If 0 enable virtual CPU IRQ

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

_HYP_irq_disable

Disable IRQ for the domain.

In the shared page, both v_irq_enabled or v_cpsr may be modified.

#define _HYP_irq_disable	7

Registers specification on call

Register	Usage
R0	IRQ mask. If 0 disable virtual CPU IRQ

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

_HYP_irq_return

This hypercall must be used by the domain to return from interrupt.

It is called when the guest finished his IRQ handler set the context back from the shared page where the domain could have changed it for context switch purpose for exemple.

#define _HYP_irq_return		8

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
-	The call does not return.

_HYP_exit

This hypercall is used to terminate the domain. The domain state will be DSTATE_ZOMBIE and depending on XHYP configuration an event will be sent to the controlling domain signaling the death.

The DSTATE_ZOMBIE will lead to DSTATE_DEAD if a controlling domain retrieves the domain status, see _HYP_hyp.

#define _HYP_exit		9

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
-	The call does not return.

_HYP_cpuctrl

This hypercall is processor dependant and is used to bring back to the domain processor specific informations like processor version or type.

#define _HYP_cpuctrl		10

Registers specification on call

Register	Usage
R0	The Virtual Coprocessor register to query 0: Coprocessor register 0 (mrc p15, 0, r0, c0, c0, 0) 1: Coprocessor register 1 (mrc p15, 0, r0, c1, c0, 0)

Registers specification on return

Register	Usage
R0	The value of the coprocessor register

_HYP_syscall_request

Just like for interrupt management the _HYP_syscall_request hypercall allows a domain to define an entry point for system calls.

#define _HYP_syscall_request	11

Registers specification on call

Register	Usage
R0	a pointer to the syscall routine
R1	a pointer to the stack for syscall

_HYP_syscall_return

Just like for interrupt management the _HYP_syscall_return hypercall allows a domain to signal the hypervisor he finished a syscall.

#define _HYP_syscall_return	12

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
-	The call does not return.

_HYP_pgfault_request

This hypercall is used to define an entry point for handling page faults.

#define _HYP_pgfault_request	13

Registers specification on call

Register	Usage
R0	a pointer to the pagefault routine
R1	a pointer to the stack for pagefault

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

_HYP_undef_request

This hypercalls is used to define an entry point for handling undefined instructions.

#define _HYP_undef_request	14

Registers specification on call

Register	Usage
R0	a pointer to the undefined instruction routine
R1	a pointer to the stack for undefined instruction

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

_HYP_enable_mmu

The _HYP_enable_mmu hypercall allows a domain to change the virtual MMU mode

#define _HYP_enable_mmu		15

Registers specification on call

Register	Usage
R0	1: enable MMU - 0: disable MMU

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

RESERVED

#define _HYP_setmode		16

_HYP_set_domain

This hypercall is used for ARM implementations.

In the case the domain handle two mode of operation, this hypercall is used to change the ARM domain.

In a ARM processor we can define 16 different domains controling the way memory is accessed. In X-Hyp we restrict the number of domains to a maximum of 2 ARM-domains per X-Hyp domain.

#define _HYP_set_domain		17

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_disable_cache

This hypercall allows a domain to disable the cache associated to itself.

#define _HYP_disable_cache      18

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_reset

This hypercalls is a demand to the hypervisor for a hot reset. The hot reset is done by calling the first address available for code in the domain (usually 0x02100000)

#define _HYP_reset              19

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_idle

This hypercall ask the hypervisor to put this domain in idle state. That is it do not process instructions anymore but wait for an interrupt.

#define _HYP_idle               20

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_flush_cache

This hypercalls asks the hypervisor to flush or clean the domain associated cache. See X-hyp cache handling documentation.

#define _HYP_flush_cache                21

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

RESERVED

The following hypercalls are no longer used and are replaced with specific register values in _HYP_flush_cache hypercall.

#define _HYP_flush_icache               22
#define _HYP_flush_user_cache_range     23
#define _HYP_coherent_user_rang         24
#define _HYP_flush_kern_dcache_area     25
#define _HYP_dma_inv_range              26
#define _HYP_dma_clean_range            27
#define _HYP_dma_flush_range            28
#define _HYP_dchache_clean_area         29

_HYP_switch_mm

Use this hypercall to change the page table associated with the domain.

#define _HYP_switch_mm			30

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_set_pte

Use this hypercall to modify a single page table entry inside a known page table.

#define _HYP_set_pte			31

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

RESERVED

The following hypercalls are no longer used and are replaced with specific register values in _HYP_flush_cache hypercall.

#define _HYP_tlb_flush			32
#define _HYP_enable_cache		33

_HYP_probe

Allows to copy data inside the domain memory without to trigger a page fault. In case of error, i.e. the address is not inside the domain R0 will hold the error value or 0 for success.

#define _HYP_probe			34

Registers specification on call

Register	Usage
R0	Destination address
R1	Source address
R2	length

Registers specification on return

Register	Usage
R0	On success: 0 On error: A negative number indicating the cause of error.

RESERVED

The following hypercalls are no longer used.

#define _HYP_switch_task		35
#define _HYP_copy_page			36
#define _HYP_clear_page			37
#define _HYP_new_pgd			38
#define _HYP_set_pmd			39
#define _HYP_set_pte_ext		40
#define _HYP_get_pmdval			41

_HYP_get_timer

returns timer informations in R0.

#define _HYP_get_timer			42

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_io_open

XHYP defines IO operations as event operations on qports. Each domain has 3 pre-defined opened channels: 0 read, 1 write and 2 error. (Like in Unix).

You can use IO channels for inter domain communications. These channels are implemented using qports. See Xhyp Documentation on qports implementation and qport user's guide.

The return value is a positive number indicating the local channel to be used for further IO or a negative value indicating the cause of the error.

#define _HYP_io_open			43

Registers specification on call

Register	Usage
R0	high word holds domain number. Low word is the channel number.
R1	address of the buffer
R2	buffer len

Registers specification on return

Register	Usage
R0	On success: Channel number On error: A negative number indicating the cause of error.

IO routines

XHYP defines read, write, ioctl and close using POSIX syntax.

#define _HYP_io_read			44
#define _HYP_io_write			45
#define _HYP_io_ioctl			46
#define _HYP_io_close			47

_HYP_event_send

A domain can send an event to another domain sampling port.

#define _HYP_event_send			48

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

RESERVED

The following hypercalls are no longer used.

#define _HYP_preempt_disable		49
#define _HYP_preempt_enable		50

_HYP_hyp

XHYP implement tracing facilities. Event's data is logged in a circular buffer on specific events like scheduling events, interrupt, errors and hypercalls.

A controlling domain can usr this hypercall to retrieve the events.

#define _HYP_hyp			51

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_abt_return

This hypercall must be used by the domain to return from abort.

#define _HYP_abt_return			52

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.

_HYP_usr_return

This hypercall must be used by the domain to switch to user mode.

#define _HYP_usr_return			53

Registers specification on call

Register	Usage
-	No register used

Registers specification on return

Register	Usage
R0	On success: the number of bytes successfully copied On error: A negative number indicating the cause of error.