# A definitive guide to using XEN Grant Tables and Event Channels

A document to save all the interesting stuff we can find about EVT channels and Grant Tables, which according to our supervisors should be step one when portin Zephyr.

The document will serve as a library with all interesting information about the subject, aswell as links to wikis and source code files.

## [Grant Table Xen Wiki](https://wiki.xenproject.org/wiki/Grant_Table)

According to Xen's wiki, Their grant tables is a mechanism used to share memory between domains.

> This shared memory interface underpins the split device drivers for block and network IO.

asd

> Each domain has its own grant table. This is a data structure that is shared with Xen; it allows the domain to tell Xen what kind of permissions other domains have on its pages. Entries in the grant table are identified by grant references. A grant reference is an integer, which indexes into the grant table. It acts as a capability which the grantee can use to perform operations on the granter’s memory.

asd

> This capability-based system allows shared-memory communications between unprivileged domains. A grant reference also encapsulates the details of a shared page, removing the need for a domain to know the real machine address of a page it is sharing. This makes it possible to share memory correctly with domains running in fully virtualised memory.

They then refer to two places for reference implementation

[linux grant table](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/xen/grant-table.c?id=HEAD) which is where linux holds their implementation of the grant-table,

aswell as **include/public/grant_table.h** for the most updated version.

### grant_table.h

This header includes alot of unions and struct aswell as flags used for setting up grant tables. The only reference i have so far is FreeRTOS which has implemented two files **gnttab.h** aswell as **gnttab.c** that uses some of the structs found in **grant_table.h**

## FreeRTOS Grant Tables Implementation "gnttab"

FreeRTOS is a good reference, as they have successfully set up granttables for xen using their own RTOS. this section will try to cover how they did it.

First well take a look at the header file **gnttab.h**


they start off with 3 defines:

**NR_RESERVED_ENTRIES 8**
**NR_GRANT_FRAMES 4**
**NR_GRANT_ENTRIES (NR_GRANT_FRAMES * PAGE_SIZE / sizeof(grant_entry_t))**

where PAGE_SIZE is defined in freertos/arch_mm.h as

**PAGE_SIZE (1 << PAGE_SHIFT)**
**PAGE_SHIFT 12**

they then declare the functions

- void init_gnttab(void);
- grant_ref_t gnttab_grant_access(domid_t domid, unisged long frame, int readonly);
- int gnttab_map_ref(domid_t domid, grant_ref_t ref, unsigned long mfn);
- grant_ref_t gnttab_grant_transfer(domid_t domid, unsigned long pfn);
- unsigned long gnttab_end_transfer(grant_ref_t gref);
- int gnttab_end_access(grant_ref_t ref);
- const char *gnttabop_error(int16_t status);
- void fini_gnttab(void);

**grant_entry_t**, **grant_ref_t**, **domid_t** are all data types defined in **xen/grant_table.h** and holds the following information:


> typedef uint16_t domid_t;

> typedef uint32_t grant_ref_t;

Lets try to break the functions down individually starting with the **init_gnttab** which is called within **xen_setup** that we will look at later.

### void init_gnttab(void)


The first thing they do is creating a **gnttab_setup_table** object called **setup** which is a struct defined in **grant_table.h** that holds information about the grant table.


They also initialize a semaphore, aswell as printing the address of the granttable **gnttab_table** which is a global variable of type **grant_entry_t**.

at row 222 they make a call to **put_free_entry** which does the following:

> fyll på här

at row 226 - 228 they intiatie the **gnttab_setup_table setup**

using a macro **set_xen_guest_handle(setup.frame_list, frames);** which is defined **xen/include/public/arch_arm.h** as


they then make the hypercall **HYPERVISOR_grant_table_op(GNTTABOP_setup_table, &setup, 1)** which returns a 0 upon succeeding.

**GNTTABOP_setup_table** is an enum defined in **xen/include/public/grant_table.h**


They also make sure to check the **setup.status** against the enum **GNTST_okay** defined in **grant_table.h**


If the previous Asserts are okay we can map the grant table. this is done by calling the function **map_frames** typecasting the result into a **grant_entry_t** pointer and assigning it to our table **gnttab_table**.

**map_frames** is defined in the {freertos.dir}/Source/portable/GCC/ARM7_CA15_Xen/mmu.c


which in turn calls **map_frame** for every frame in the list.

Here we need to check how zephyr handles MMU, probably different from freeRTOS, hence this section needs to be rewrited for our code. anyways, **map_frame** also defined in mmu.c as:

### void map_grant_table(void *device_tree)

In **xen_setup.c** before calling init_gnttab();, a function called map_grant_table(device_tree) is called


Xen setup declares some globals, aswell as some externs
for example **gnttab_table** which is declared in **gnttab.c**.


the


**map_grant_table** takes in a **device_tree** as argument. Im not exactly sure how this works but the device tree must be defined somewhere. We will first look at