--- /dev/null
+%SWAP Porting guide
+
+# Table of Contents
+* [Introduction to SWAP](#introduction-to-swap)
+* [SWAP architecture and components](#swap-architecture-and-components)
+* [SWAP porting procedure](#swap-porting-procedure)
+ * [Kernel with memory protection or without kernel modules support](#kernel-with-memory-protection-or-without-kernel-modules-support)
+ * [Checking and applying SWAP kernel hooks](#applying-swap-kernel-hooks)
+ * [Checking SWAP kernel hooks existance in kernel](#checking-swap-kernel-hooks-existance-in-kernel)
+ * [Applying SWAP kernel hooks by GIT](#applying-swap-kernel-hooks-by-git)
+ * [Applying SWAP kernel hooks manually](#applying-swap-kernel-hooks-manually)
+ * [SWAP modules and kernel sources synchronization](#swap-modules-and-kernel-sources-synchronization)
+ * [Manual synchronization](#manual-synchronization)
+ * [Usign sync script](#using-sync-script)
+* [Testing SWAP](#testing-swap)
+
+# Introduction to SWAP
+
+**SWAP** is a Tizen dynamic binary instrumentation tool, it allows developers
+to trace and profile their applications. The tool supports a number of Tizen
+devices and emulators and is supplied as a part of their firmware. To check if
+your device contains SWAP, you can check whether the **swap-manager** package
+is installed:
+
+``` bash
+$ rpm -q swap-manager
+```
+
+If the output looks like the following then SWAP is installed:
+``` bash
+swap-manager-3.0-7.6.i686
+```
+
+So, if your device or emulator contains SWAP, you can start using it.
+
+
+SWAP is located on the target device, it is responsible for gathering run time
+data about the developer's application. When it works it is connected with a
+host side tool and communicates with it in a format described at SWAP protocol.
+SWAP host side tool controls SWAP execution, provides it with a profiling
+session options and receives gathered data. There are two SWAP host-side tools:
+[Dynamic Analyzer](https://developer.tizen.org/development/tizen-studio/native-tools/debugging-your-app/dynamic-analyzer)
+GUI tool and SWAP Python console tool, which is provided with the
+**swap-manager** (located at git repo: git://git.tizen.org/platform/core/system/swap-manager).
+
+SWAP contains several useful features for developers:
+
+* Function profiling. This feature allows the developer to trace functions of
+interest of his application, it is based on uprobe mechanism. The developer
+specifies which functions in which binary files he wants to trace and when
+control flow reaches one, the event related information is collected: function
+address, timestamp, arguments etc. is generated.
+* Profiling of OpenGL and system APIs related to memory management, file
+operations, network and threading. This feature provides the developer
+information about application's system resources usage.
+* Leak Sanitizer. This feature generates report about memory leaks in the
+application. For more information check Leak Sanitizer documentation.
+* Context switches profiling. This feature adds data about context switching to
+the trace.
+* Sampling. Used for process sampling with the specified period.
+
+# SWAP architecture and components
+
+
+
+SWAP consists of the several components: user-space daemon, kernel modules and
+SWAP library.
+
+* SWAP probe library is loaded at the target process memory area, used for
+profiling system APIs and LSan analytic without using the expensive uprobe
+mechanism.
+* The daemon is used for communication between SWAP and host side. It is also
+responsible for executing and killing applications, transferring data between
+kernel- and user-space, communication with the SWAP library instances at the
+target application's memory areas, and sending gathered data to host side.
+* SWAP kernel modules provides kprobe and uprobe functionality and sampling
+feature.
+
+SWAP probe library (**swap-probe**) and SWAP daemon (**swap-manager**) are
+user-space components of the SWAP tool. They are built as common Tizen packages,
+so they do not need any porting.
+
+SWAP Linux kernel modules (**swap-modules**) are kernel-space components of the
+SWAP tool, and in some cases they require special porting activities.
+
+# SWAP porting procedure
+
+**Kernel sources should be managed by GIT to make the following guide works.**
+
+For **swap-probe** and **swap-manager** projects usually no extra activities are
+needed during supporting new device.
+
+For **swap-modules** there are two possible cases of distribution:
+
+* If kernel supports modules and doesn't have any kernel memory protection,
+then no special porting activity is needed;
+* If kernel doesn't support modules or it has a kernel memory protection, then
+**swap-modules** are distributed as a part of kernel sources. In case the
+developer needs to apply hooks on kernel and synchronize **swap-modules**
+sources with the kernel ones.
+
+Only the last case leads to additional developer activities, it will be
+described further in details.
+
+## Kernel with memory protection or without kernel modules support
+
+In this case the developer should do the following:
+
+* Check and apply SWAP kernel hooks on demand;
+* Synchronize SWAP modules and kernel sources.
+
+### Checking and applying SWAP kernel hooks
+
+SWAP modules need information about some kernel events. Commonly, the modules
+receive this data arming kprobes on the functions of interest, but if the kernel
+memory is protected then the only way to get these events data is kernel hooks
+implementation. Kprobe provides more flexibility for **swap-modules** while
+hooks are faster.
+
+#### Checking SWAP kernel hooks existance in kernel
+
+If SWAP was already ported to the kernel that means that the kernel hooks are
+already exist in kernel sources, and the developer shouldn't apply patches with
+them once again.
+
+To check if the kernel source code already contains SWAP hooks, check that
+directory *\<linux-kernel\>/include/swap* exists and is not empty:
+
+``` bash
+$ ls linux-kernel/include/swap/
+```
+
+If result looks like the following, hooks are already applied:
+
+``` bash
+hook_energy.h hook_file_ops.h hook_signal.h hook_switch_to.h hook_syscall.h
+hook_syscall_priv.h hook_taskdata.h hook_usaux.h
+```
+
+If the directory doesn't exists or empty then the patches should be applied.
+
+#### Applying SWAP kernel hooks by GIT
+
+All the necessary patches are contained at *\<swap-modules\>/kernel_integration/patches/*
+directory. To apply these patches, the developer should execute ```git am```
+from the kernel sources directory passing *\<swap-modules\>/kernel_integration/patches/\*.patch*
+as its argument:
+
+``` bash
+$ cd linux-kernel
+$ git am swap-modules/kernel_integration/patches/*.patch
+```
+
+As far as there is a number of different kernels, the patches will not be
+applied without conflicts for all of them in some cases it is needed to apply
+these patches manually
+
+#### Applying SWAP kernel hooks manually
+
+All the necessary kernel patches are located at *\<swap-modules\>/kernel_integration/patches/*,
+here is their list:
+
+| File | Description |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| 0001-Prepare-kernel-for-swap-modules-integration | Prepares **swap-modules** integration to kernel build system |
+| 0002-Prepare-kernel-for-swap-hooks-integration | Prepares **swap-modules** hooks integration to kernel build |
+| 0003-SWAP-DA-arm64-Add-CONFIG_SWAP_HOOK_SYSCALL | Add syscall hook for ARM64 |
+| 0004-SWAP-DA-add-CONFIG_SWAP_HOOK_TASKDATA | Add hook for Task Data support |
+| 0005-SWAP-DA-arm64-add-CONFIG_SWAP_HOOK_USAUX | Add SWAP auxiliary hooks for ARM64 |
+| 0006-SWAP-DA-add-CONFIG_SWAP_HOOK_SWITCH_TO | Add hook on context switching |
+| 0007-SWAP-DA-add-CONFIG_SWAP_HOOK_ENERGY | Add necessary SWAP energy hooks |
+| 0008-SWAP-DA-add-CONFIG_SWAP_HOOK_FILE_OPS | Add file operations hook |
+| 0009-SWAP-DA-add-CONFIG_SWAP_HOOK_SIGNAL | Add SWAP signal hook |
+
+These patches are git-formatted. The patches may not always be applied without
+conflicts. In that cases, the developer should resolve them manually. Patch
+changes should be applied one by one starting from
+*0001-Prepare-kernel-for-swap-modules-integration.patch*,
+finishing with *0009-SWAP-DA-add-CONFIG_SWAP_HOOK_SIGNAL.patch*.
+All the necessary information, like files that change, code that surrounds
+changes etc. is provided in *.patch files.
+
+## SWAP modules and kernel sources synchronization
+
+### Manual synchronization
+
+**swap-modules** synchronization can be done manually. To do this, the developer
+should do the following:
+
+1. Synchronize **swap-modules**
+ * Remove existent **swap-modules** from kernel, if any:
+``` bash
+$ rm -r <kernel_dir>/kernel/swap/modules/
+OR
+$ rm -r <kernel_dir>/kernel/swap/module/
+```
+
+ * Copy **swap-modules** modules directory to *\<kernel_dir\>/kernel/swap/modules*:
+``` bash
+$ cp -r <swap-modules_dir>/modules/ <kernel_dir>/kernel/swap/modules/
+```
+ * Make *Makefile*s from *Kbuild*
+ * Rename *Kbuild* files with *Makefile*
+ * For core *Makefile* in *modules* directory:
+ * Remove ```EXTRA_CFLAGS```, ```extra_cflags``` and ```ks_manager``` from *Makefile*s
+ * Replace ```obj-m :=``` with ```obj-y +=```
+ * For other *Makefile*s:
+ * Remove ```KBUILD_EXTRA_SYMBOLS```
+ * Replace ```obj-m``` with ```obj-y```
+ * Remove ```$(extra-cflags)```
+ * Remove ```EXTRA_CFLAGS = ```
+ * Replace ```EXTRA_CFLAGS``` with ```ccflags-y```
+ * Add architecture-dependent include paths:
+
+``` bash
+ccflags-y := -I<module_subdirectory>
+
+ifeq (\$(CONFIG_ARM), y)
+ link = arm
+endif
+
+ifeq (\$(CONFIG_ARM64), y)
+ link = arm64
+endif
+
+ifeq (\$(CONFIG_X86), y)
+ link = x86
+endif
+
+ccflags-y += -I<module_subdirectory>/kprobe/arch/\$(link) \
+ -I<module_subdirectory>/uprobe/arch/\$(link)
+```
+
+2. Update hooks
+ * Remove current hooks, if any:
+``` bash
+$ rm -r <kernel_dir>/include/swap/
+$ rm -r <kernel_dir>/kernel/swap/hooks/
+OR
+$ rm -r <kernel_dir>/kernel/swap/hook/
+```
+
+ * Copy new hooks:
+``` bash
+$ cp -r <swap-modules_dir>/kernel_integration/hooks/include/swap/ \
+ <kernel_dir>/include/
+$ cp -r <swap-modules_dir>/kernel_integration/hooks/kernel/swap/hooks/ \
+ <kernel_dir>/kernel/swap/
+```
+ * Copy ```Kconfig``` to *\<kernel_dir\>/kernel/swap/*:
+``` bash
+$ cp <swap-modules_dir>/kernel_integration/hooks/kernel/swap/Kconfig \
+ <kernel_dir>/kernel/swap/
+```
+
+ * Copy ```Makefile``` to *\<kernel_dir\>/kernel/swap/*:
+``` bash
+$ cp <swap-modules_dir>/kernel_integration/hooks/kernel/swap/Makefile \
+ <kernel_dir>/kernel/swap/
+```
+
+3. Make commit
+``` bash
+$ git add <kernel_dir>/kernel/swap/.
+$ git add <kernel_dir>/include/swap/.
+$ git commit
+```
+
+Now **swap-modules** sources are fully synchronized to the kernel.
+
+### Using sync script
+
+There is a special script that synchronizes **swap-modules** sources to the
+kernel sources. It is located at *\<swap-modules\>/kernel_integration/sync_swap_to_kernel.sh*
+and takes SWAP modules directory, kernel sources directory and kernel config
+file as its arguments. You can execute it, for example, as a following:
+
+``` bash
+$ swap-modules/kernel_integration/sync_swap_to_kernel.sh \
+ <kernel_dir> \
+ <swap-modules_dir> \
+ <kernel_dir>/arch/arm/configs/tizen_defconfig
+```
+
+The last argument, kernel config, is optional. It is used to modify kernel
+config to use SWAP and its kernel hooks. If this option is not specified, the
+developer should manually add it to the end of the config file, which is used
+for kernel building, the following:
+
+``` bash
+#
+# SWAP subsystem for Dynamic Analyzer
+#
+CONFIG_SWAP_DA=y
+CONFIG_SWAP_KERNEL_IMMUTABLE=y
+CONFIG_SWAP_HOOK_TASKDATA=y
+CONFIG_SWAP_HOOK_USAUX=y
+CONFIG_SWAP_HOOK_SYSCALL=y
+CONFIG_SWAP_HOOK_SWITCH_TO=y
+CONFIG_SWAP_HOOK_ENERGY=y
+CONFIG_SWAP_HOOK_FILE_OPS=y
+CONFIG_SWAP_HOOK_SIGNAL=y
+```
+
+After the script has finished the kernel will contain SWAP modules sources same
+as the sources in **swap-modules** directory, specified as the first argument.
+These changes will be committed in the last kernel commit with message
+***"SWAP: sync"***.
+
+# Testing SWAP
+
+After porting has been done, SWAP should be tested. To do this, first of all
+necessary binaries should be prepared:
+
+1. Prepare **swap-modules** binaries. There are two possible cases:
+ * if **swap-modules** are provided as a standalone package, build them with a
+ proper build root using GBS;
+ * if **swap-modules** are provided as a part of the kernel, then prepare a
+ firmware using modified kernel with **swap-modules** and flash it to the
+ target.
+
+2. Prepare **swap-manager** and **swap-probe** binaries. Build them with a
+proper build root using GBS;
+3. Push prepared rpm packages to the target and install them;
+4. Execute **SWAP Test System**. To get more information about it, please refer
+to the *SWAP Test documentation*, it is located at ***swap-test*** project
+(git://git.tizen.org/test/swap-test).
projects / platform / kernel / swap-modules.git / commitdiff
