From f9416444d44b81747d9a4dcb7525b0d5900bc10d Mon Sep 17 00:00:00 2001 From: RobertCheng <782307550@qq.com> Date: Wed, 20 Oct 2021 05:30:20 +0000 Subject: [PATCH 1/3] optimized DyscheOS-utils.README_en.md --- .../DyscheOS-utils.README_en.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 translation-projects/README-optimization/optimized-README/DyscheOS-utils.README_en.md diff --git a/translation-projects/README-optimization/optimized-README/DyscheOS-utils.README_en.md b/translation-projects/README-optimization/optimized-README/DyscheOS-utils.README_en.md new file mode 100644 index 0000000..2ecb3fc --- /dev/null +++ b/translation-projects/README-optimization/optimized-README/DyscheOS-utils.README_en.md @@ -0,0 +1,30 @@ +# DyscheOS-utils + +#### Introduction +This repo is about Dysche solutions that are misc tools with regard to userspace part. + +Note, the Master branch may not contain the latest dev kits. See the list of branches +for more details. + +#### Architecture +The overall architecture of Dysche is originated from Linux AMP(Asychronous Multi-Processing) architecture. +In general, there are two parts in Dysche architecture: the Linux kernel part and the Linux userspace part. In this repo, we'll focus on userspace part. + +For Dysche userspace design,it is logically divided into following parts: + +- A tool to load and verify APP-OS images. + +- Interface with the Dysche kernel part, and run the APP-OS. + +- A system service to interfere with Dysche kernel part, maintain/operate APP-OS on the fly, provide devices emulation, etc. + +#### Instructions + +See README.md of each sub-dir for more details please. + +#### Contribution + +1. Fork the repository +2. Create a branch +3. Commit your changes +4. Create Pull Request \ No newline at end of file -- Gitee From 8c7be9de7f08105aaace67453f6882553e4946d0 Mon Sep 17 00:00:00 2001 From: RobertCheng <782307550@qq.com> Date: Wed, 20 Oct 2021 05:31:28 +0000 Subject: [PATCH 2/3] optimized etmem.README_ch.md --- .../optimized-README/etmem.README_ch.md | 494 ++++++++++++++++++ 1 file changed, 494 insertions(+) create mode 100644 translation-projects/README-optimization/optimized-README/etmem.README_ch.md diff --git a/translation-projects/README-optimization/optimized-README/etmem.README_ch.md b/translation-projects/README-optimization/optimized-README/etmem.README_ch.md new file mode 100644 index 0000000..0dff201 --- /dev/null +++ b/translation-projects/README-optimization/optimized-README/etmem.README_ch.md @@ -0,0 +1,494 @@ +# etmem + +## 介绍 + +随着CPU算力的发展，尤其是ARM核成本的降低，内存成本和内存容量成为约束业务成本和性能的核心痛点，因此如何节省内存成本，如何扩大内存容量成为存储迫切要解决的问题。 + +etmem内存分级扩展技术，通过DRAM+内存压缩/高性能存储新介质形成多级内存存储，对内存数据进行分级，将分级后的内存冷数据从内存介质迁移到高性能存储介质中，达到内存容量扩展的目的，从而实现内存成本下降。 + +## 编译教程 + +1. 下载etmem源码 + + $ git clone https://gitee.com/openeuler/etmem.git + +2. 编译和运行依赖 + + etmem的编译和运行依赖于libboundscheck组件 + +3. 编译 + + $ cd etmem + + $ mkdir build + + $ cd build + + $ cmake .. + + $ make + + +## 使用说明 + +### 启动etmemd进程 + +#### 使用方法 + +通过运行etmemd二进制运行服务端进程，例如： + +$ etmemd -l 0 -s etmemd_socket + +#### 帮助信息 + +各参数： + +-l|\-\-log-level Log level + +-s|\-\-socket Socket name to listen to + +-h|\-\-help Show this message + +-m|\-\-mode-systemctl mode used to start(systemctl) + +#### 命令行参数说明 + +| 参数 | 参数含义 | 是否必须 | 是否有参数 | 参数范围 | 示例说明 | +| ---------------------- | ------------------------------------------------------------ | -------- | ---------- | --------------------- | ------------------------------------------------------------ | +| -l或\-\-log-level | etmemd日志级别 | 否 | 是 | 0~3 | 0：debug级别 1：info级别 2：warning级别 3：error级别 只有大于等于配置的级别才会打印到/var/log/message文件中 | +| -s或\-\-socket | etmemd监听的名称，用于与客户端交互 | 是 | 是 | 107个字符之内的字符串 | 指定服务端监听的名称 | +| -h或\-\-help | 帮助信息 | 否 | 否 | NA | 执行时带有此参数会打印后退出 | +| -m或\-\-mode-systemctl | etmemd作为service被拉起时，命令中可以使用此参数来支持fork模式启动 | 否 | 否 | NA | NA | +| ### etmem配置文件 | | | | | | + +在运行etmem进程之前，需要管理员预先规划哪些进程需要做内存扩展，将进程信息配置到etmem配置文件中，并配置内存扫描的周期、扫描次数、内存冷热阈值等信息。 + +配置文件的示例文件在源码包中，放置在源码根目录的conf/example_conf.yaml，建议在使用时放置在/etc/etmem/目录下，示例内容为： + +``` +[project] +name=test +loop=1 +interval=1 +sleep=1 + +#slide引擎示例 +[engine] +name=slide +project=test + +[task] +project=test +engine=slide +name=background_slide +type=name +value=mysql +T=1 +max_threads=1 + +#cslide引擎示例 +[engine] +name=cslide +project=test +node_pair=2,0;3,1 +hot_threshold=1 +node_mig_quota=1024 +node_hot_reserve=1024 + +[task] +project=test +engine=cslide +name=background_cslide +type=pid +name=23456 +vm_flags=ht +anon_only=no +ign_host=no + +#thirdparty引擎示例 +[engine] +name=thirdparty +project=test +eng_name=my_engine +libname=/usr/lib/etmem_fetch/my_engine.so +ops_name=my_engine_ops +engine_private_key=engine_private_value + +[task] +project=test +engine=my_engine +name=backgroud_third +type=pid +value=12345 +task_private_key=task_private_value +``` + +配置文件各字段说明： + +| 配置项 | 配置项含义 | 是否必须 | 是否有参数 | 参数范围 | 示例说明 | +| ------------------ | ------------------------------------------------------------ | ---------------------------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| [project] | project公用配置段起始标识 | 否 | 否 | NA | project参数的开头标识，表示下面的参数直到另外的[xxx]或文件结尾为止的范围内均为project section的参数 | +| name | project的名字 | 是 | 是 | 64个字以内的字符串 | 用来标识project，engine和task在配置时需要指定要挂载到的project | +| loop | 内存扫描的循环次数 | 是 | 是 | 1~10 | loop=3 //扫描3次 | +| interval | 每次内存扫描的时间间隔 | 是 | 是 | 1~1200 | interval=5 //每次扫描之间间隔5s | +| sleep | 每个内存扫描+操作的大周期之间的时间间隔 | 是 | 是 | 1~1200 | sleep=10 //每次大周期之间间隔10s | +| [engine] | engine公用配置段起始标识 | 否 | 否 | NA | engine参数的开头标识，表示下面的参数直到另外的[xxx]或文件结尾为止的范围内均为engine section的参数 | +| project | 声明所在的project | 是 | 是 | 64个字以内的字符串 | 已经存在名字为test的project，则可以写为project=test | +| engine | 声明所在的engine | 是 | 是 | slide/cslide/thridparty | 声明使用的是slide或cslide或thirdparty策略 | +| node_pair | cslide engine的配置项，声明系统中AEP和DRAM的node pair | engine为cslide时必须配置 | 是 | 成对配置AEP和DRAM的node号，AEP和DRAM之间用逗号隔开，每队pair之间用分号隔开 | node_pair=2,0;3,1 | +| hot_threshold | cslide engine的配置项，声明内存冷热水线的阈值 | engine为cslide时必须配置 | 是 | >= 0的整数 | hot_threshold=3 //访问次数小于3的内存会被识别为冷内存 | +| node_mig_quota | cslide engine的配置项，流控，声明每次DRAM和AEP互相迁移时单向最大流量 | engine为cslide时必须配置 | 是 | >= 0的整数 | node_mig_quota=1024 //单位为MB，AEP到DRAM或DRAM到AEP搬迁一次最大1024M | +| node_hot_reserve | cslide engine的配置项，声明DRAM中热内存的预留空间大小 | engine为cslide时必须配置 | 是 | >= 0的整数 | node_hot_reserve=1024 //单位为MB，当所有虚拟机热内存大于此配置值时，热内存也会迁移到AEP中 | +| eng_name | thirdparty engine的配置项，声明engine自己的名字，供task挂载 | engine为thirdparty时必须配置 | 是 | 64个字以内的字符串 | eng_name=my_engine //对此第三方策略engine挂载task时，task中写明engine=my_engine | +| libname | thirdparty engine的配置项，声明第三方策略的动态库的地址，绝对地址 | engine为thirdparty时必须配置 | 是 | 64个字以内的字符串 | libname=/user/lib/etmem_fetch/code_test/my_engine.so | +| ops_name | thirdparty engine的配置项，声明第三方策略的动态库中操作符号的名字 | engine为thirdparty时必须配置 | 是 | 64个字以内的字符串 | ops_name=my_engine_ops //第三方策略实现接口的结构体的名字 | +| engine_private_key | thirdparty engine的配置项，预留给第三方策略自己解析私有参数的配置项，选配 | 否 | 否 | 根据第三方策略私有参数自行限制 | 根据第三方策略私有engine参数自行配置 | +| [task] | task公用配置段起始标识 | 否 | 否 | NA | task参数的开头标识，表示下面的参数直到另外的[xxx]或文件结尾为止的范围内均为task section的参数 | +| project | 声明所挂的project | 是 | 是 | 64个字以内的字符串 | 已经存在名字为test的project，则可以写为project=test | +| engine | 声明所挂的engine | 是 | 是 | 64个字以内的字符串 | 所要挂载的engine的名字 | +| name | task的名字 | 是 | 是 | 64个字以内的字符串 | name=background1 //声明task的名字是backgound1 | +| type | 目标进程识别的方式 | 是 | 是 | pid/name | pid代表通过进程号识别，name代表通过进程名称识别 | +| value | 目标进程识别的具体字段 | 是 | 是 | 实际的进程号/进程名称 | 与type字段配合使用，指定目标进程的进程号或进程名称，由使用者保证配置的正确及唯一性 | +| T | engine为slide的task配置项，声明内存冷热水线的阈值 | engine为slide时必须配置 | 是 | 0~loop * 3 | T=3 //访问次数小于3的内存会被识别为冷内存 | +| max_threads | engine为slide的task配置项，etmemd内部线程池最大线程数，每个线程处理一个进程/子进程的内存扫描+操作任务 | 否 | 是 | 1~2 * core数 + 1，默认为1 | 对外部无表象，控制etmemd服务端内部处理线程个数，当目标进程有多个子进程时，配置越大，并发执行的个数也多，但占用资源也越多 | +| vm_flags | engine为cslide的task配置项，通过指定flag扫描vma，不配置此项时扫描则不会区分 | engine为cslide时必须配置 | 是 | 当前只支持ht | vm_flags=ht //扫描flags为ht（大页）的vma内存 | +| anon_only | engine为cslide的task配置项，标识是否只扫描匿名页 | 否 | 是 | yes/no | anon_only=no //配置为yes时只扫描匿名页，配置为no时非匿名页也会扫描 | +| ign_host | engine为cslide的task配置项，标识是否忽略host上的页表扫描信息 | 否 | 是 | yes/no | ign_host=no //yes为忽略，no为不忽略 | +| task_private_key | engine为thirdparty的task配置项，预留给第三方策略的task解析私有参数的配置项，选配 | 否 | 否 | 根据第三方策略私有参数自行限制 | 根据第三方策略私有task参数自行配置 | + + + +### etmem project/engine/task对象的创建和删除 + +#### 场景描述 + +1）管理员创建etmem的project/engine/task（一个工程可包含多个etmem engine，一个engine可以包含多个任务） + +2）管理员删除已有的etmem project/engine/task（删除工程前，会自动先停止该工程中的所有任务） + +#### 使用方法 + +运行etmem二进制，通过第二个参数指定为obj，来进行创建或删除动作，对project/engine/task则是通过配置文件中配置的内容来进行识别和区分。前提是etmem配置文件已配置正确，etmemd进程已启动。 + +添加对象： + +etmem obj add -f /etc/example_config.yaml -s etmemd_socket + +删除对象： + +etmem obj del -f /etc/example_config.yaml -s etmemd_socket + +打印帮助： + +etmem obj help + +#### 帮助信息 + +使用方法: + +etmem obj add [参数] + +etmem obj del [参数] + +etmem obj help + +各参数: + +-f|\-\-file Add configuration file + +-s|\-\-socket Socket name to connect + +注意: + +1. 一定要给出配置文件。 + +#### 命令行参数说明 + + +| 参数 | 参数含义 | 是否必须 | 是否有参数 | 示例说明 | +| -------------- | ------------------------------------------------------------ | ---------------------- | ---------- | -------------------------------------------------------- | +| -f或\-\-file | 指定对象的配置文件 | add，del子命令必须包含 | 是 | 需要指定路径名称 | +| -s或\-\-socket | 与etmemd服务端通信的socket名称，需要与etmemd启动时指定的保持一致 | add，del子命令必须包含 | 是 | 必须配置，在有多个etmemd时，由管理员选择与哪个etmemd通信 | + +### etmem任务启动/停止/查询 + +#### 场景描述 + +在已经通过etmem obj add添加工程之后，在还未调用etmem obj del删除工程之前，可以对etmem的工程进行启动和停止。 + +1）管理员启动已添加的工程 + +2）管理员停止已启动的工程 + +在管理员调用obj del删除工程时，如果工程已经启动，则会自动停止。 + +#### 使用方法 + +对于已经添加成功的工程，可以通过etmem project的命令来控制工程的启动和停止，命令示例如下： + +启动工程 + +etmem project start -n test -s etmemd_socket + +停止工程 + +etmem project stop -n test -s etmemd_socket + +查询工程 + +etmem project show -n test -s etmemd_socket + +打印帮助 + +etmem project help + +#### 帮助信息 + +使用方法: + +etmem project start [参数] + +etmem project stop [参数] + +etmem project show [参数] + +etmem project help + +各参数: + +-n|\-\-name Add project name + +-s|\-\-socket Socket name to connect + +注意: + +1. 执行add或者del参数时，一定要给出项目名称和socket名称。 + +2. 使用show参数查询时，一定要给出socket名称。 + +#### 命令行参数说明 + +| 参数 | 参数含义 | 是否必须 | 是否有参数 | 示例说明 | +| -------------- | ------------------------------------------------------------ | ------------------------------- | ---------- | -------------------------------------------------------- | +| -n或\-\-name | 指定project名称 | start，stop，show子命令必须包含 | 是 | project名称，与配置文件一一对应 | +| -s或\-\-socket | 与etmemd服务端通信的socket名称，需要与etmemd启动时指定的保持一致 | start，stop，show子命令必须包含 | 是 | 必须配置，在有多个etmemd时，由管理员选择与哪个etmemd通信 | + +### etmem支持随系统自启动 + +#### 场景描述 + +etmemd支持由用户配置systemd配置文件后，以fork模式作为systemd服务被拉起运行 + +#### 使用方法 + +编写service配置文件，来启动etmemd，必须使用-m参数来指定此模式，例如： + +etmemd -l 0 -s etmemd_socket -m + +#### 帮助信息 + +各参数: + +-l|\-\-log-level Log level + +-s|\-\-socket Socket name to listen to + +-m|\-\-mode-systemctl mode used to start(systemctl) + +-h|\-\-help Show this message + +#### 命令行参数说明 +| 参数 | 参数含义 | 是否必须 | 是否有参数 | 参数范围 | 实例说明 | +| ---------------------- | ------------------------------------------------------------ | -------- | ---------- | --------------------- | ------------------------------------------------------------ | +| -l或\-\-log-level | etmemd日志级别 | 否 | 是 | 0~3 | 0：debug级别；1：info级别；2：warning级别；3：error级别；只有大于等于配置的级别才会打印到/var/log/message文件中 | +| -s或\-\-socket | etmemd监听的名称，用于与客户端交互 | 是 | 是 | 107个字符之内的字符串 | 指定服务端监听的名称 | +| -m或\-\-mode-systemctl | etmemd作为service被拉起时，命令中需要指定此参数来支持支持fork模式启动 | 否 | 否 | NA | NA | +| -h或\-\-help | 帮助信息 | 否 | 否 | NA | 执行时带有此参数会打印后退出 | + + + + +### etmem支持第三方内存扩展策略 + +#### 场景描述 + +etmem支持用户注册第三方内存扩展策略，同时提供扫描模块动态库，运行时通过第三方策略淘汰算法淘汰内存。 + +用户使用etmem所提供的扫描模块动态库并实现对接etmem所需要的结构体中的接口 + +#### 使用方法 + +用户使用自己实现的第三方扩展淘汰策略，主要需要按下面步骤进行实现和操作： + +1. 按需调用扫描模块提供的扫描接口， + +2. 按照etmem头文件中提供的函数模板来实现各个接口，最终封装成结构体 + +3. 编译出第三方扩展淘汰策略的动态库 + +4. 在配置文件中按要求声明类型为thirdparty的engine + +5. 将动态库的名称和接口结构体的名称按要求填入配置文件中task对应的字段 + +其他操作步骤与使用etmem的其他engine类似 + +接口结构体模板 + +struct engine_ops { + +/* 针对引擎私有参数的解析，如果有，需要实现，否则置NULL */ + +int (*fill_eng_params)(GKeyFile *config, struct engine *eng); + +/* 针对引擎私有参数的清理，如果有，需要实现，否则置NULL */ + +void (*clear_eng_params)(struct engine *eng); + +/* 针对任务私有参数的解析，如果有，需要实现，否则置NULL */ + +int (*fill_task_params)(GKeyFile *config, struct task *task); + +/* 针对任务私有参数的清理，如果有，需要实现，否则置NULL */ + +void (*clear_task_params)(struct task *tk); + +/* 启动任务的接口 */ + +int (*start_task)(struct engine *eng, struct task *tk); + +/* 停止任务的接口 */ + +void (*stop_task)(struct engine *eng, struct task *tk); + +/* 填充pid相关私有参数 */ + +int (*alloc_pid_params)(struct engine *eng, struct task_pid **tk_pid); + +/* 销毁pid相关私有参数 */ + +void (*free_pid_params)(struct engine *eng, struct task_pid **tk_pid); + +/* 第三方策略自身所需要的私有命令支持，如果没有，置为NULL */ + +int (*eng_mgt_func)(struct engine *eng, struct task *tk, char *cmd, int fd); + +}; + +配置文件示例如下所示，具体含义请参考配置文件说明章节： + +#thirdparty + +[engine] + +name=thirdparty + +project=test + +eng_name=my_engine + +libname=/user/lib/etmem_fetch/code_test/my_engine.so + +ops_name=my_engine_ops + +engine_private_key=engine_private_value + +[task] + +project=test + +engine=my_engine + +name=background1 + +type=pid + +value=1798245 + +task_private_key=task_private_value + + **注意** ： + +用户需使用etmem所提供的扫描模块动态库并实现对接etmem所需要的结构体中的接口 + +eng_mgt_func接口中的fd不能写入0xff和0xfe字 + +支持在一个工程内添加多个不同的第三方策略动态库，以配置文件中的eng_name来区分 + +### etmem支持使用AEP进行内存扩展 + +#### 场景描述 + +使用etmem组件包，使能内存分级扩展至AEP的通路。 + +在节点内对虚拟机的大页进行扫描，并通过cslide引擎进行策略淘汰，将冷内存搬迁至AEP中 + +#### 使用方法 + +使用cslide引擎进行内存扩展，参数示例如下，具体参数含义请参考配置文件说明章节 + +#cslide + +[engine] + +name=cslide + +project=test + +node_pair=2,0;3,1 + +hot_threshold=1 + +node_mig_quota=1024 + +node_hot_reserve=1024 + +[task] + +project=test + +engine=cslide + +name=background1 + +type=pid + +value=1823197 + +vm_flags=ht + +anon_only=no + +ign_host=no + + **注意** ：禁止并发扫描同一个进程 + +同时，此cslide策略支持私有的命令 + + +- showtaskpages +- showhostpages + +针对使用此策略引擎的engine和engine所有的task，可以通过这两个命令分别查看task相关的页面访问情况和虚拟机的host上系统大页的使用情况。 + +示例命令如下： + +etmem engine showtaskpages <-t task_name> -n proj_name -e cslide -s etmemd_socket + +etmem engine showhostpages -n proj_name -e cslide -s etmemd_socket + + **注意** ：showtaskpages和showhostpages仅支持引擎使用cslide的场景 + +#### 命令行参数说明 +| 参数 | 参数含义 | 是否必须 | 是否有参数 | 实例说明 | +| ----------------- | ------------------------------------------------------------ | -------- | ---------- | -------------------------------------------------------- | +| -n或\-\-proj_name | 指定project的名字 | 是 | 是 | 指定已经存在，所需要执行的project的名字 | +| -s或\-\-socket | 与etmemd服务端通信的socket名称，需要与etmemd启动时指定的保持一致 | 是 | 是 | 必须配置，在有多个etmemd时，由管理员选择与哪个etmemd通信 | +| -e或\-\-engine | 指定执行的引擎的名字 | 是 | 是 | 指定已经存在的，所需要执行的引擎的名字 | +| -t或\-\-task_name | 指定执行的任务的名字 | 否 | 是 | 指定已经存在的，所需要执行的任务的名字 | + +## 参与贡献 + +1. Fork本仓库 +2. 新建个人分支 +3. 提交代码 +4. 新建Pull Request \ No newline at end of file -- Gitee From fc88158c837298b0f9c8036d1318c9250b88e0f1 Mon Sep 17 00:00:00 2001 From: RobertCheng <782307550@qq.com> Date: Wed, 20 Oct 2021 05:33:09 +0000 Subject: [PATCH 3/3] translate bishengjdk-riscv.README_ch.md & etmem.README_en.md --- .../bishengjdk-riscv.README_ch.md | 13 + .../translated-README/etmem.README_en.md | 494 ++++++++++++++++++ 2 files changed, 507 insertions(+) create mode 100644 translation-projects/README-optimization/translated-README/bishengjdk-riscv.README_ch.md create mode 100644 translation-projects/README-optimization/translated-README/etmem.README_en.md diff --git a/translation-projects/README-optimization/translated-README/bishengjdk-riscv.README_ch.md b/translation-projects/README-optimization/translated-README/bishengjdk-riscv.README_ch.md new file mode 100644 index 0000000..f9883d2 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/bishengjdk-riscv.README_ch.md @@ -0,0 +1,13 @@ +# 欢迎来到 JDK! + +关于构建的说明，请查阅 +[online documentation](https://openjdk.java.net/groups/build/doc/building.html), +或者查阅以下文件: + +- [doc/building.html](doc/building.html) (html版本) +- [doc/building.md](doc/building.md) (markdown版本) + +点击 获得更多关于 + +OpenJDK 社区和JDK 的信息. + diff --git a/translation-projects/README-optimization/translated-README/etmem.README_en.md b/translation-projects/README-optimization/translated-README/etmem.README_en.md new file mode 100644 index 0000000..33994a9 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/etmem.README_en.md @@ -0,0 +1,494 @@ +# Etmem + +## Introduction + +The development of CPU computing power - particularly lower costs of ARM cores - makes memory cost and capacity the core frustration, limiting business cost and performance. Therefore, the most pressing issue is how to save memory cost and how to expand memory capacity. + +Etmem is a memory vertical expansion technology that can achieve the purpose of memory capacity expansion and memory cost reduction. To do so, it first needs to hierarchize memory data based on hierarchical memory storage generated by DRAM+memory compression/new high-performance storage media, and then moves hierarchized memory cold data from memory media to high-performance storage media. + +## Compiling tutorial + +1. Download etmem source code + + $ git clone https://gitee.com/openeuler/etmem.git + +2. Compile- and run-time dependencies + + the compiling and running of etmem depend on libboundscheck modules + +3. Compiling + + $ cd etmem + + $ mkdir build + + $ cd build + + $ cmake .. + + $ make + + +## Instructions + +### Start etmemd + +#### Usage + +Run the server by executing binary files of etmemd : + +$ etmemd -l 0 -s etmemd_socket + +#### Help information + +options： + +-l|\-\-log-level Log level + +-s|\-\-socket Socket name to listen to + +-h|\-\-help Show this message + +-m|\-\-mode-systemctl mode used to start(systemctl) + +#### Command-line option descriptions + +| Options | Explanation | Required | Parameters | Range | Examples | +| ---------------------- | ------------------------------------------------------------ | -------- | ---------- | --------------------- | ------------------------------------------------------------ | +| -l or \-\-log-level | Etmemd log level | No | Yes | 0~3 | 0：debug level 1：info level 2：warning level 3：error level Only levels more than or equal to the configured level can be printed into /var/log/message | +| -s or \-\-socket | The name monitored by etmemd, used to interface with clients | Yes | Yes | A string less than 107 characters | Assign names monitored by the server | +| -h or \-\-help | Help information | No | No | NA | Execution with this option will print and exit | +| -m or \-\-mode-systemctl | This option can be used to support the starting of fork mode as etmemd is pulled as service | No | No | NA | NA | +| ### etmem configuration files | | | | | | + +Before running etmem, the administer should plan which process's memory needs to be expanded, and prepare the configuration file, including process information like memory scanning cycles, scanning times and the threshold of hot and cold memory. + +The example of the configuration file is contained in source code package which lies in root directory of the source code - conf/example_conf.yaml. We suggest that it should be put under directory - /etc/etmem/. The following is an example： + +``` +[project] +name=test +loop=1 +interval=1 +sleep=1 + +#slide engine example +[engine] +name=slide +project=test + +[task] +project=test +engine=slide +name=background_slide +type=name +value=mysql +T=1 +max_threads=1 + +#cslide engine example +[engine] +name=cslide +project=test +node_pair=2,0;3,1 +hot_threshold=1 +node_mig_quota=1024 +node_hot_reserve=1024 + +[task] +project=test +engine=cslide +name=background_cslide +type=pid +name=23456 +vm_flags=ht +anon_only=no +ign_host=no + +#thirdparty engine example +[engine] +name=thirdparty +project=test +eng_name=my_engine +libname=/usr/lib/etmem_fetch/my_engine.so +ops_name=my_engine_ops +engine_private_key=engine_private_value + +[task] +project=test +engine=my_engine +name=backgroud_third +type=pid +value=12345 +task_private_key=task_private_value +``` + +Descriptions of each field in the configuration file： + +| Configuration items | Explanation | Required | Parameters | Range | Examples | +| ------------------ | :----------------------------------------------------------- | ------------------------------ | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| [project] | The start ID of the project common configuration section | No | No | NA | The start ID of the project, indicating that the following parameters all belong to the project section up to another [XXX] or the end of the file project. | +| name | The project name | Yes | Yes | A string less than 64 characters | It is used to identify the project that mount engine and task during configuration | +| loop | The number of memory scanning cycles | Yes | Yes | 1~10 | loop=3 //Scan 3 times. | +| interval | An interval between each scanning | Yes | Yes | 1~1200 | interval=5 //The interval between each scanning is 5s. | +| sleep | An interval between a longer cycle of memory scanning + operation | Yes | Yes | 1~1200 | sleep=10 //The interval between such longer cycle is 10s. | +| [engine] | the start ID of the engine common configuration section | No | No | NA | The start ID of the engine, indicating that the following parameters all belong to the engine section up to another [XXX] or the end of the file. | +| project | Declare the project | Yes | Yes | A string less than 64 characters | If there is a project named as test, it could be written as project=test | +| engine | Declare the engine | Yes | Yes | slide/cslide/thridparty | Declare the used polices are slid, cslide or thirparty | +| node_pair | A configuration item of the cslide engine declares node pair of AEP and DRAM | Yes, when engine is cslide | Yes | Configure the node of AEP and DRAM in pairs, with AEP and DRAM separated by comma and each pair separated by semicolon | node_pair=2,0;3,1 | +| hot_threshold | A configuration item of the cslide engine declares the threshold of hot and cold memory | Yes, when engine is cslide | Yes | integer >= 0 | hot_threshold=3 //Access times less than 3 will be identified as cold memory | +| node_mig_quota | Traffic control, a configuration item of the cslide engine, declares the maximum one-way traffic each time DRAM and AEP move to each other | Yes, when engine is cslide | Yes | integer >= 0 | node_mig_quota=1024 //With unit being MB, it costs 1024M maximally moving from AEP to DRAM or from DRAM to AEP | +| node_hot_reserve | A configuration item of the cslide engine declares the reserved space of hot memory in DRAM | Yes, when engine is cslide | Yes | integer >= 0 | node_hot_reserve=1024 //The unit is MB. If the hot memory of all VMs exceeds the value, they will be moved to AEP. | +| eng_name | A configuration item of the thirdparty engine declares the name of engine itself for task to mount | Yes, when engine is thirdparty | Yes | A string less than 64 characters | eng_name=my_engine //When the thirdparty engine mounts tasks, engine=my_engine should be written clearly in the task | +| libname | A configuration item of the thirdparty engine declares the address -absolute address-of the thirdparty-policy dynamic library | Yes, when engine is thridparty | Yes | A string less than 64 characters | libname=/user/lib/etmem_fetch/code_test/my_engine.so | +| ops_name | A configuration item of the thirdparty engine declares the name of operation symbols in the thirdparty-policy dynamic library | Yes, when engine is thirdparty | Yes | A string less than 64 characters | ops_name=my_engine_ops //The name of the thirdparty struct that implements the interface | +| engine_private_key | A configuration item of the thirdparty engine is reserved for the thirdparty policies to analyse private keys, optional | No | No | Private keys are restricted according to the thirdparty policies | Private engine parameters are configured according to the thirdparty policies | +| [task] | The start ID of the task common configuration section | No | No | NA | The start ID of the task, indicating that the following parameters all belong to the task section up to another [XXX] or the end of the file. | +| project | Declare the mounted project | Yes | Yes | A string less than 64 characters | If there is a project named as test, it could be written as project=test | +| engine | Declare the mounted engine | Yes | Yes | A string less than 64 characters | the name of the mounted engine | +| name | The task name | Yes | Yes | A string less than 64 characters | name=background1 //Declare that the name of task is backgound1 | +| type | The method identified by the targeted process | Yes | Yes | pid/name | pid means identification based on the process id; name means identification based on the process name | +| value | the specific field identified by the targeted process | Yes | Yes | The real process ID/ process name | It should be used with type to assign process ID and name, and the correctness and uniqueness of its configuration should be ensured by users | +| T | A configuration item of task, when engine is slide, declares the threshold of hot and cold memory | Yes, when engine is slide | Yes | 0~loop * 3 | T=3 //memory with access times less than 3 will be identified as cold memory | +| max_threads | A configuration item of task, when engine is slide, means the maximum threads in etmemd thread pool. And each thread handles memory scanning of one process/subprocess, and operation task | No | Yes | 1~2 * core + 1, with default being 1 | With no external representation, it control the number of thread inside the etmemd server. When there are multiple subprocesses of the targeted process, the larger configuration leads to more concurrent executions, but more resources are occupied. | +| vm_flags | A configuration item of task, when engine is cslide, is used to scan vma by assigning flags. Without this configuration item, the scanning will be indiscriminate | Yes, when engine is cslide | Yes | Only ht is supported at present | vm_flags=ht //The memory of vma whose flages are ht(huge page) will be scanned | +| anon_only | A configuration item of task, when engine is cslide, identifies that only anonymous page needs to be scanned. | No | Yes | yes/no | anon_only=no //If yes is given, only scan anonymous pages. If no, non-anonymous pages are also included | +| ign_host | A configuration item of task, when engine is cslide, identifies whether to ignore the scanning information of page tables on host | No | Yes | yes/no | ign_host=no //If yes, ignore. If no, not | +| task_private_key | A configuration item of task, when engine is thirdparty, is deserved for thirdparty tasks to analyse private keys, optional | No | No | Private keys are restricted according to the thirdparty policies | Task private keys are configured according to the thirdparty policies | + + + +### Create and delete etmem project/engine/task object + +#### Scene description + +1）Administer creates etmem project/engine/task(one project can contains multiple etmem engines, and each engine can contain multiple tasks.) + +2）Administer delete existed etmem project/engine/task(before deleting a project, all tasks in the project will be stopped automatically) + +#### Usage + +By executing etmem's binary files and Assigning the second parameter as obj, users can create and delete actions. Project/engine/task can be identified and distinguished by its configuration file. These above are based on the premise of proper the configuration file and an ongoing process. + +Add objects： + +etmem obj add -f /etc/example_config.yaml -s etmemd_socket + +Delete objects： + +etmem obj del -f /etc/example_config.yaml -s etmemd_socket + +Print help： + +etmem obj help + +#### Help information + +Usage: + +etmem obj add [options] + +etmem obj del [options] + +etmem obj help + +Options: + +-f|\-\-file Add configuration file + +-s|\-\-socket Socket name to connect + +Notes: + +1. The configuration file must be given. + +#### Command-line option descriptions + + +| Options | Explanation | Required | Parameters | Examples | +| ---------------- | ------------------------------------------------------------ | ----------------------------------------- | ---------- | ------------------------------------------------------------ | +| -f or \-\-file | Assign the configuration file of objects | The add，del subcommands must be included | Yes | The name of the path needs to be assigned | +| -s or \-\-socket | The name of socket that communicates with the etmemd server should accord with that assigned at the beginning of etmemd | The add, del subcommands must be included | Yes | It must be given. When there are several etmemds, it is administer that decides which one to communicate. | + +### Start/stop/show etmem tasks + +#### Scene description + +If it is at the period between adding a project by the command: etmem obj add and deleting it by the command: etmem obj del, you can start and stop the etmem project. + +1）The administer starts added projects + +2）The administer stop started projects + +If the project has already been started when obj del is called to delete it by the administer, it would be stopped automatically. + +#### Usage + +A project, which is successfully added, can be started and stopped by commands of etmem project. The followings are examples： + +Start a project + +etmem project start -n test -s etmemd_socket + +Stop a project + +etmem project stop -n test -s etmemd_socket + +Show a project + +etmem project show -n test -s etmemd_socket + +Print help + +etmem project help + +#### Help information + +Usage: + +etmem project start [options] + +etmem project stop [options] + +etmem project show [options] + +etmem project help + +Options: + +-n|\-\-name Add project name + +-s|\-\-socket Socket name to connect + +Notes: + +1. The project name and the socket name must be given when execute add or del option. + +2. The socket name must be given when execute show option. + +#### Command-line option descriptions + +| Options | Explanation | Required | Parameters | Examples | +| ---------------- | ------------------------------------------------------------ | -------------------------------------------------- | ---------- | ------------------------------------------------------------ | +| -n or \-\-name | Assign the project name | The start，stop，show subcommands must be included | Yes | It's an one-to-one correspondence between names of projects and those in the configuration file. | +| -s or \-\-socket | The socket name that communicates with the server should accord with that assigned as etmemd started | The start，stop，show subcommands must be included | Yes | It must be given. When there are several etmemds, administer decides which one to communicate. | + +### Etmem supports automatic restart + +#### Scene description + +Etmemd allows users to fork the systemd configuration file and run it as a systemd service. + +#### Usage + +Compile the configuration file of service to start etmemd, but parameter -m must be assigned to this mode. For example: + +etmemd -l 0 -s etmemd_socket -m + +#### Help information + +options: + +-l|\-\-log-level Log level + +-s|\-\-socket Socket name to listen to + +-m|\-\-mode-systemctl mode used to start(systemctl) + +-h|\-\-help Show this message + +#### Command-line option descriptions +| Options | Explanation | Required | Parameters | Range | Examples | +| ------------------------ | ------------------------------------------------------------ | -------- | ---------- | --------------------------------- | ------------------------------------------------------------ | +| -l or \-\-log-level | etmemd log levels | No | Yes | 0~3 | 0：debug level；1：info level；2：warning level；3：error level；Only Levels more than or equal to the configuration level can be printed into /var/log/message | +| -s or \-\-socket | The name monitored by etmemd, used to interface with clients | Yes | Yes | A string less than 107 characters | Assign names monitored by the server | +| -m or \-\-mode-systemctl | This option can be used to support the starting of fork mode as etmemd is pulled up as service | No | No | NA | NA | +| -h or \-\-help | Help information | No | No | NA | Execution with this option will print and exit | + + + + +### Etmem supports thirdparty memory expansion polices + +#### Scene description + +Etmem supports users to register thirdparty memory expansion policies, and also offers the dynamic library of scanning modules which can evict memory by thirdparty algorithms at run time. + +Users can use the dynamic library of scanning modules provided by Etmem and interface with the struct required by etmem. + +#### Usage + +If users use thirdparty expansion eviction policies implemented by themselves, they need to follow these steps: + +1. Call the scanning interfaces provided by scanning modules as required. + +2. Implement each interface according to function template in etmem header file, and finally encapsulate them to an struct + +3. Compile a dynamic library of thirdparty expansion eviction policies + +4. Declare the thirdparty engine in the configuration file as required + +5. Fill the names of dynamic libraries and the struct into fields corresponding to task in the configuration file + +Other steps are similar to the way of using other etmem engines + +Struct template + +struct engine_ops { + +/* If there is analysis on engine private keys, it needs to be implemented; if not, set NULL. */ + +int (*fill_eng_params)(GKeyFile *config, struct engine *eng); + +/* If there is clearing of engine private keys, it needs to be implemented; if not, set NULL. */ + +void (*clear_eng_params)(struct engine *eng); + +/* If there is analysis on task private keys, it needs to be implemented; if not, set NULL. */ + +int (*fill_task_params)(GKeyFile *config, struct task *task); + +/* If there is clearing of task private keys, it needs to be implemented; if not, set NULL */ + +void (*clear_task_params)(struct task *tk); + +/* Start task interface */ + +int (*start_task)(struct engine *eng, struct task *tk); + +/* Stop task interface */ + +void (*stop_task)(struct engine *eng, struct task *tk); + +/* Fill pid-related private keys */ + +int (*alloc_pid_params)(struct engine *eng, struct task_pid **tk_pid); + +/* Destroy pid-related private keys */ + +void (*free_pid_params)(struct engine *eng, struct task_pid **tk_pid); + +/* Private commands required by thirdparty policies as following, If not, set NULL. */ + +int (*eng_mgt_func)(struct engine *eng, struct task *tk, char *cmd, int fd); + +}; + +The following is an example of the configuration file. See conf file in root directory for more details: + +#thirdparty + +[engine] + +name=thirdparty + +project=test + +eng_name=my_engine + +libname=/user/lib/etmem_fetch/code_test/my_engine.so + +ops_name=my_engine_ops + +engine_private_key=engine_private_value + +[task] + +project=test + +engine=my_engine + +name=background1 + +type=pid + +value=1798245 + +task_private_key=task_private_value + + **Note** ： + +Users can use the dynamic library of scanning modules provided by Etmem and implement the interface of the struct required by etmem. + +0xff and 0xfe cannot be written into the interface - eng_mgt_func + +Different dynamic libraries of thirdparty policies can be added into the same project and distinguished by eng_name in the configuration file. + +### Etmem supports memory expansion by AEP + +#### Scene description + +Using the etmem kit enables memory to expand to AEP path. + +The huge pages of VMs are scanned within the node, and cold memory is moved to AEP via eviction policies of sclide engine. + +#### Usage + +Use cslide engine to expand memory. The following is an example. See conf file in root directory for more details. + +#cslide + +[engine] + +name=cslide + +project=test + +node_pair=2,0;3,1 + +hot_threshold=1 + +node_mig_quota=1024 + +node_hot_reserve=1024 + +[task] + +project=test + +engine=cslide + +name=background1 + +type=pid + +value=1823197 + +vm_flags=ht + +anon_only=no + +ign_host=no + + **Notes** ：Do not concurrently scan the same process + +Meanwhile, this cslide policy supports private commands + + +- showtaskpages +- showhostpages + +For engine used this policy and all tasks of the engine, this two orders can be used to show access history of task pages and the using history of the system pages on the host of the VM. + +The following is an example： + +etmem engine showtaskpages <-t task_name> -n proj_name -e cslide -s etmemd_socket + +etmem engine showhostpages -n proj_name -e cslide -s etmemd_socket + + **Note** ：showtaskpages and showhostpages only support cslide engine + +#### Command-line parameters description +| Options | Explanation | Required | Parameters | Examples | +| ------------------- | ------------------------------------------------------------ | -------- | ---------- | ------------------------------------------------------------ | +| -n or \-\-proj_name | Assign the project name | Yes | Yes | Assign projects that are already existed and need to be executed | +| -s or \-\-socket | The name of socket that communicates with the etmemd server should accord with that assigned as etmemd started | Yes | Yes | It must given. When there are several etmemds, it is administer that decides which one to communicate. | +| -e or \-\-engine | Assign the name of the executing engine | Yes | Yes | Assign the name of the engine that are already existed and need to be executed | +| -t or \-\-task_name | Assign the name of the executing task | No | Yes | Assign the name of the task that is already existed and need to be executed | + +## Contribution + +1. Fork the repository +2. Create a branch +3. Commit your changes +4. Create Pull Request \ No newline at end of file -- Gitee