From 9429467289513fd8e772ccdb5aeafe59211fe14e Mon Sep 17 00:00:00 2001 From: gatieme Date: Tue, 16 Aug 2016 23:08:39 +0800 Subject: [PATCH] ... --- .../04-buddy/01-buddy_system/README.md | 267 +++++- .../04-buddy/04-alloc_page/README.md | 763 ++++++++++++++++++ .../04-buddy/images/__free_pages.png | Bin 0 -> 20224 bytes 3 files changed, 1013 insertions(+), 17 deletions(-) create mode 100644 study/kernel/02-memory/04-buddy/04-alloc_page/README.md create mode 100644 study/kernel/02-memory/04-buddy/images/__free_pages.png diff --git a/study/kernel/02-memory/04-buddy/01-buddy_system/README.md b/study/kernel/02-memory/04-buddy/01-buddy_system/README.md index 0c8cdf4..88dd91f 100644 --- a/study/kernel/02-memory/04-buddy/01-buddy_system/README.md +++ b/study/kernel/02-memory/04-buddy/01-buddy_system/README.md @@ -628,6 +628,8 @@ not_early: 还有一组kmalloc类型的函数, 用于分配小于一整页的内存区. 其实现 将在本章后续的几节分别讨论。 + + ## 释放函数 ------- @@ -1060,13 +1062,16 @@ static inline enum zone_type gfp_zone(gfp_t flags) 与内存域修饰符相反, 这些额外的标志并不限制从哪个物理内存段分配内存, 但确实可以改变分配器的行为. 例如, 它们可以修改查找空闲内存时的积极程度. +##4.3 分配页 +------- -##4.3 内存分配统一到alloc_pages接口 + +###4.3.1 内存分配统一到alloc_pages接口 ------- 通过使用标志、内存域修饰符和各个分配函数，内核提供了一种非常灵活的内存分配体系.尽管如此, 所有接口函数都可以追溯到一个简单的基本函数(alloc_pages_node) -分配单页的函数[`alloc_page`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L483)和[`__get_free_page`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L500), 还有[`__get_dma_pages`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L503)是借助于宏定义的 +分配单页的函数[`alloc_page`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L483)和[`__get_free_page`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L500), 还有[`__get_dma_pages`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L503)是借助于宏定义的. ```cpp // http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L483 @@ -1081,7 +1086,7 @@ static inline enum zone_type gfp_zone(gfp_t flags) __get_free_pages((gfp_mask) | GFP_DMA, (order)) ``` -[`get_zeroed_page`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3900)的实现也没什么困难, 对__get_free_pages使用__GFP_ZERO标志，即可分配填充字节0的页. 再返回与页关联的内存区地址即可. +[`get_zeroed_page`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3900)的实现也没什么困难, 对`__get_free_pages`使用`__GFP_ZERO`标志，即可分配填充字节0的页. 再返回与页关联的内存区地址即可. ```cpp @@ -1094,7 +1099,7 @@ EXPORT_SYMBOL(get_zeroed_page); ``` -[`__get_free_pages`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883)调用alloc_pages完成内存分配, 而alloc_pages又借助于alloc_pages_node +[`__get_free_pages`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883)调用`alloc_pages`完成内存分配, 而alloc_pages又借助于alloc_pages_node [`__get_free_pages`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883)函数的定义在[mm/page_alloc.c?v=4.7, line 3883](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883) @@ -1118,10 +1123,34 @@ unsigned long __get_free_pages(gfp_t gfp_mask, unsigned int order) EXPORT_SYMBOL(__get_free_pages); ``` -在这种情况下， 使用了一个普通函数而不是宏， 因为alloc_pages返回的page实例需要使用辅助 -函数page_address转换为内存地址. 在这里，只要知道该函数可根据page实例计算相关页的线性内存地址即可. 对高端内存页这是有问题的 +在这种情况下， 使用了一个普通函数而不是宏， 因为`alloc_pages`返回的`page`实例需要使用辅助 + +函数`page_address`转换为内存地址. 在这里，只要知道该函数可根据`page`实例计算相关页的线性内存地址即可. 对高端内存页这是有问题的 + + + +这样, 就完成了所有分配内存的API函数到公共的基础函数`alloc_pages`的统一 + + +![伙伴系统中各个分配函数之间的关系](../images/alloc_pages.png) + + +所有体系结构都必须实现的标准函数`clear_page`, 可帮助alloc_pages对页填充字节0, 实现如下表所示 + +| x86 | arm | +|:----:|:-----:| +| [arch/x86/include/asm/page_32.h?v=4.7, line 24](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_32.h?v=4.7#L24) | [arch/arm/include/asm/page.h?v=4.7#L14](http://lxr.free-electrons.com/source/arch/arm/include/asm/page.h?v=4.7#L142)
[arch/arm/include/asm/page-nommu.h](http://lxr.free-electrons.com/source/arch/arm/include/asm/page-nommu.h?v=4.7#L20) | + + +###4.3.2 alloc_pages函数分配页 +------- + + +既然所有的内存分配API函数都可以追溯掉`alloc_page`函数, 从某种意义上说，该函数是伙伴系统主要实现的"发射台". + + +`alloc_pages`函数的定义是依赖于NUMA或者UMA架构的, 定义如下 -alloc_pages_node函数的定义是依赖于NUMA或者UMA架构的, 定义如下 ```cpp #ifdef CONFIG_NUMA @@ -1141,21 +1170,225 @@ alloc_pages(gfp_t gfp_mask, unsigned int order) #endif ``` - -这样, 就完成了所有分配内存的API函数到公共的基础函数alloc_pages的统一 - -![伙伴系统中各个分配函数之间的关系](../images/alloc_pages.png) +UMA结构下的`alloc_pages`是通过`alloc_pages_node`函数实现的, 下面我们看看`alloc_pages_node`函数的定义, 在[include/linux/gfp.h?v=4.7, line 448](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L448) -所有体系结构都必须实现的标准函数clear_page，可帮助alloc_pages对页填充字节0, 实现如下表所示 +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L448 +/* + * Allocate pages, preferring the node given as nid. When nid == NUMA_NO_NODE, + * prefer the current CPU's closest node. Otherwise node must be valid and + * online. + */ +static inline struct page *alloc_pages_node(int nid, gfp_t gfp_mask, + unsigned int order) +{ + if (nid == NUMA_NO_NODE) + nid = numa_mem_id(); -| x86 | arm | -|:----:|:-----:| -| [arch/x86/include/asm/page_32.h?v=4.7, line 24](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_32.h?v=4.7#L24) | [arch/arm/include/asm/page.h?v=4.7#L14](http://lxr.free-electrons.com/source/arch/arm/include/asm/page.h?v=4.7#L142)
[arch/arm/include/asm/page-nommu.h](http://lxr.free-electrons.com/source/arch/arm/include/asm/page-nommu.h?v=4.7#L20) | + return __alloc_pages_node(nid, gfp_mask, order); +} +```` + +它只是执行了一个简单的检查, 如果指定负的结点ID(不存在, 即[NUMA_NO_NODE = -1](http://lxr.free-electrons.com/source/include/linux/numa.h?v=4.7#L13)), 内核自动地使用当前执行CPU对应的结点nid = [numa_mem_id();](http://lxr.free-electrons.com/source/include/linux/topology.h?v=4.7#L137), 然后调用`__alloc_pages_node`函数进行了内存分配 + + + +`__alloc_pages_node`函数定义在[include/linux/gfp.h?v=4.7, line 435)](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L435), 如下所示 + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L435 +/* + * Allocate pages, preferring the node given as nid. The node must be valid and + * online. For more general interface, see alloc_pages_node(). + */ +static inline struct page * +__alloc_pages_node(int nid, gfp_t gfp_mask, unsigned int order) +{ + VM_BUG_ON(nid < 0 || nid >= MAX_NUMNODES); + VM_WARN_ON(!node_online(nid)); + + return __alloc_pages(gfp_mask, order, node_zonelist(nid, gfp_mask)); +} +``` + +内核假定传递给改alloc_pages_node函数的结点nid是被激活, 即online的.但是为了安全它还是检查并警告内存结点不存在的情况. 接下来的工作委托给__alloc_pages, 只需传递一组适当的参数, 其中包括节点nid的备用内存域列表zonelist. + + +现在`__alloc_pages`函数没什么特别的, 它直接将自己的所有信息传递给`__alloc_pages_nodemask`来完成内存的分配 + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L428 +static inline struct page * +__alloc_pages(gfp_t gfp_mask, unsigned int order, + struct zonelist *zonelist) +{ + return __alloc_pages_nodemask(gfp_mask, order, zonelist, NULL); +} +``` + +###4.3.3 伙伴系统的心脏__alloc_pages_nodemask +------- + +内核源代码将`__alloc_pages`称之为"伙伴系统的心脏"(`the 'heart' of the zoned buddy allocator``), 因为它处理的是实质性的内存分配. + +由于"心脏"的重要性, 我将在下文详细介绍该函数. + +`__alloc_pages`函数定义在[include/linux/gfp.h?v=4.7#L428](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L428) + + + +```cpp +// http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3779 +/* + * This is the 'heart' of the zoned buddy allocator. + */ +struct page * +__alloc_pages_nodemask(gfp_t gfp_mask, unsigned int order, + struct zonelist *zonelist, nodemask_t *nodemask) +{ + struct page *page; + unsigned int cpuset_mems_cookie; + unsigned int alloc_flags = ALLOC_WMARK_LOW|ALLOC_FAIR; + gfp_t alloc_mask = gfp_mask; /* The gfp_t that was actually used for allocation */ + struct alloc_context ac = { + .high_zoneidx = gfp_zone(gfp_mask), + .zonelist = zonelist, + .nodemask = nodemask, + .migratetype = gfpflags_to_migratetype(gfp_mask), + }; + + if (cpusets_enabled()) { + alloc_mask |= __GFP_HARDWALL; + alloc_flags |= ALLOC_CPUSET; + if (!ac.nodemask) + ac.nodemask = &cpuset_current_mems_allowed; + } + + gfp_mask &= gfp_allowed_mask; + + lockdep_trace_alloc(gfp_mask); + + might_sleep_if(gfp_mask & __GFP_DIRECT_RECLAIM); + + if (should_fail_alloc_page(gfp_mask, order)) + return NULL; + + /* + * Check the zones suitable for the gfp_mask contain at least one + * valid zone. It's possible to have an empty zonelist as a result + * of __GFP_THISNODE and a memoryless node + */ + if (unlikely(!zonelist->_zonerefs->zone)) + return NULL; + + if (IS_ENABLED(CONFIG_CMA) && ac.migratetype == MIGRATE_MOVABLE) + alloc_flags |= ALLOC_CMA; + +retry_cpuset: + cpuset_mems_cookie = read_mems_allowed_begin(); + + /* Dirty zone balancing only done in the fast path */ + ac.spread_dirty_pages = (gfp_mask & __GFP_WRITE); + + /* + * The preferred zone is used for statistics but crucially it is + * also used as the starting point for the zonelist iterator. It + * may get reset for allocations that ignore memory policies. + */ + ac.preferred_zoneref = first_zones_zonelist(ac.zonelist, + ac.high_zoneidx, ac.nodemask); + if (!ac.preferred_zoneref) { + page = NULL; + goto no_zone; + } + + /* First allocation attempt */ + page = get_page_from_freelist(alloc_mask, order, alloc_flags, &ac); + if (likely(page)) + goto out; + + /* + * Runtime PM, block IO and its error handling path can deadlock + * because I/O on the device might not complete. + */ + alloc_mask = memalloc_noio_flags(gfp_mask); + ac.spread_dirty_pages = false; + + /* + * Restore the original nodemask if it was potentially replaced with + * &cpuset_current_mems_allowed to optimize the fast-path attempt. + */ + if (cpusets_enabled()) + ac.nodemask = nodemask; + page = __alloc_pages_slowpath(alloc_mask, order, &ac); + +no_zone: + /* + * When updating a task's mems_allowed, it is possible to race with + * parallel threads in such a way that an allocation can fail while + * the mask is being updated. If a page allocation is about to fail, + * check if the cpuset changed during allocation and if so, retry. + */ + if (unlikely(!page && read_mems_allowed_retry(cpuset_mems_cookie))) { + alloc_mask = gfp_mask; + goto retry_cpuset; + } + +out: + if (kmemcheck_enabled && page) + kmemcheck_pagealloc_alloc(page, order, gfp_mask); + + trace_mm_page_alloc(page, order, alloc_mask, ac.migratetype); + + return page; +} +EXPORT_SYMBOL(__alloc_pages_nodemask); +``` ##4.4 __free_pages -类似地，内存释放函数也可以归约到一个主要的函数（__free_pages），只是用不同的参数调 -用而已： +类似地，内存释放函数也可以归约到一个主要的函数(\__free_pages), 只是用不同的参数调用而已 + +前面我们讲过内核释放的两个主要函数有\__free_page和free_page, 它们的定义在[include/linux/gfp.h?v=4.7#L519](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L519) + + + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L519 +#define __free_page(page) __free_pages((page), 0) +#define free_page(addr) free_pages((addr), 0) +``` + +而free_pages是通过__free_pages来完成内存释放的, 参见[mm/page_alloc.c?v=4.7#L3918](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3918) + + + +```cpp +void free_pages(unsigned long addr, unsigned int order) +{ + if (addr != 0) { + VM_BUG_ON(!virt_addr_valid((void *)addr)); + __free_pages(virt_to_page((void *)addr), order); + } +} +``` + + +`free_pages`和`__free_pages`之间的关系通过函数而不是宏建立, 因为首先必须将虚拟地址转换为指向`struct page`的指针 + + + +`virt_to_page`将虚拟内存地址转换为指向page实例的指针. 基本上, 这是讲解内存分配函数时介绍的page_address辅助函数的逆过程. + + +下图以图形化方式综述了各个内存释放函数之间的关系 + + +![伙伴系统各个内存释放函数之间的关系](../images/__free_pages.png) + + + + diff --git a/study/kernel/02-memory/04-buddy/04-alloc_page/README.md b/study/kernel/02-memory/04-buddy/04-alloc_page/README.md new file mode 100644 index 0000000..8f89653 --- /dev/null +++ b/study/kernel/02-memory/04-buddy/04-alloc_page/README.md @@ -0,0 +1,763 @@ +服务器体系与共享存储器架构 +======= + +| 日期 | 内核版本 | 架构| 作者 | GitHub| CSDN | +| ------- |:-------:|:-------:|:-------:|:-------:|:-------:| +| 2016-06-14 | [Linux-4.7](http://lxr.free-electrons.com/source/?v=4.7) | X86 & arm | [gatieme](http://blog.csdn.net/gatieme) | [LinuxDeviceDrivers](https://github.com/gatieme/LDD-LinuxDeviceDrivers) | [Linux内存管理](http://blog.csdn.net/gatieme/article/category/6225543) | + + + + +在内核初始化完成之后, 内存管理的责任就由伙伴系统来承担. 伙伴系统基于一种相对简单然而令人吃惊的强大算法. + +Linux内核使用二进制伙伴算法来管理和分配物理内存页面, 该算法由Knowlton设计, 后来Knuth又进行了更深刻的描述. + +伙伴系统是一个结合了2的方幂个分配器和空闲缓冲区合并计技术的内存分配方案, 其基本思想很简单. 内存被分成含有很多页面的大块, 每一块都是2个页面大小的方幂. 如果找不到想要的块, 一个大块会被分成两部分, 这两部分彼此就成为伙伴. 其中一半被用来分配, 而另一半则空闲. 这些块在以后分配的过程中会继续被二分直至产生一个所需大小的块. 当一个块被最终释放时, 其伙伴将被检测出来, 如果伙伴也空闲则合并两者. + +* 内核如何记住哪些内存块是空闲的 + +* 分配空闲页面的方法 + +* 影响分配器行为的众多标识位 + +* 内存碎片的问题和分配器如何处理碎片 + + + +#内存分配API +------- + +##2.1 内存分配器API +------- + + + +就伙伴系统的接口而言, NUMA或UMA体系结构是没有差别的, 二者的调用语法都是相同的. + +所有函数的一个共同点是 : 只能分配2的整数幂个页. + +因此，接口中不像C标准库的malloc函数或bootmem和memblock分配器那样指定了所需内存大小作为参数. 相反, 必须指定的是分配阶, 伙伴系统将在内存中分配$2^order$页. 内核中细粒度的分配只能借助于slab分配器(或者slub、slob分配器), 后者基于伙伴系统 + + +| 内存分配函数 | 功能 | 定义 | +|:-----:|:-----:| +| alloc_pages(mask, order) | 分配$2^order$页并返回一个struct page的实例，表示分配的内存块的起始页 | [NUMA-include/linux/gfp.h, line 466](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L466)
[UMA-include/linux/gfp.h?v=4.7, line 476](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L476) | +| alloc_page(mask) | 是前者在order = 0情况下的简化形式，只分配一页 | [include/linux/gfp.h?v=4.7, line 483](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L483) | +| get_zeroed_page(mask) | 分配一页并返回一个page实例，页对应的内存填充0（所有其他函数，分配之后页的内容是未定义的） | [mm/page_alloc.c?v=4.7, line 3900](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3900)| | +| [__get_free_pages(mask, order)](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883)
[__get_free_page(mask)](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L500) | 工作方式与上述函数相同，但返回分配内存块的虚拟地址，而不是page实例 | +| get_dma_pages(gfp_mask, order) | 用来获得适用于DMA的页. | [include/linux/gfp.h?v=4.7, line 503](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L503) | + + +在空闲内存无法满足请求以至于分配失败的情况下，所有上述函数都返回空指针(比如alloc_pages和alloc_page)或者0(比如get_zeroed_page、__get_free_pages和__get_free_page). + +因此内核在各次分配之后都必须检查返回的结果. 这种惯例与设计得很好的用户层应用程序没什么不同, 但在内核中忽略检查会导致严重得多的故障 + + +内核除了伙伴系统函数之外, 还提供了其他内存管理函数. 它们以伙伴系统为基础, 但并不属于伙伴分配器自身. 这些函数包括vmalloc和vmalloc_32, 使用页表将不连续的内存映射到内核地址空间中, 使之看上去是连续的. + +还有一组kmalloc类型的函数, 用于分配小于一整页的内存区. 其实现将在以后分别讨论。 + + + +##2.2 内存分配API统一到alloc_pages接口 +------- + + +通过使用标志、内存域修饰符和各个分配函数，内核提供了一种非常灵活的内存分配体系.尽管如此, 所有接口函数都可以追溯到一个简单的基本函数(alloc_pages_node) + +分配单页的函数[`alloc_page`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L483)和[`__get_free_page`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L500), 还有[`__get_dma_pages`](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L503)是借助于宏定义的. + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L483 +#define alloc_page(gfp_mask) alloc_pages(gfp_mask, 0) + +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L500 +#define __get_free_page(gfp_mask) \ + __get_free_pages((gfp_mask), 0)` + +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L503 +#define __get_dma_pages(gfp_mask, order) \ + __get_free_pages((gfp_mask) | GFP_DMA, (order)) +``` + +[`get_zeroed_page`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3900)的实现也没什么困难, 对`__get_free_pages`使用`__GFP_ZERO`标志，即可分配填充字节0的页. 再返回与页关联的内存区地址即可. + + +```cpp +// http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3900 +unsigned long get_zeroed_page(gfp_t gfp_mask) +{ + return __get_free_pages(gfp_mask | __GFP_ZERO, 0); +} +EXPORT_SYMBOL(get_zeroed_page); +``` + + +[`__get_free_pages`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883)调用`alloc_pages`完成内存分配, 而alloc_pages又借助于alloc_pages_node + +[`__get_free_pages`](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883)函数的定义在[mm/page_alloc.c?v=4.7, line 3883](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883) + +```cpp +// http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3883 +unsigned long __get_free_pages(gfp_t gfp_mask, unsigned int order) +{ + struct page *page; + + /* + * __get_free_pages() returns a 32-bit address, which cannot represent + * a highmem page + */ + VM_BUG_ON((gfp_mask & __GFP_HIGHMEM) != 0); + + page = alloc_pages(gfp_mask, order); + if (!page) + return 0; + return (unsigned long) page_address(page); +} +EXPORT_SYMBOL(__get_free_pages); +``` + +在这种情况下， 使用了一个普通函数而不是宏， 因为`alloc_pages`返回的`page`实例需要使用辅助 + +函数`page_address`转换为内存地址. 在这里，只要知道该函数可根据`page`实例计算相关页的线性内存地址即可. 对高端内存页这是有问题的 + + + +这样, 就完成了所有分配内存的API函数到公共的基础函数`alloc_pages`的统一 + + +![伙伴系统中各个分配函数之间的关系](../images/alloc_pages.png) + + +另外所有体系结构都必须实现的标准函数`clear_page`, 可帮助alloc_pages对页填充字节0, 实现如下表所示 + +| x86 | arm | +|:----:|:-----:| +| [arch/x86/include/asm/page_32.h?v=4.7, line 24](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_32.h?v=4.7#L24) | [arch/arm/include/asm/page.h?v=4.7#L14](http://lxr.free-electrons.com/source/arch/arm/include/asm/page.h?v=4.7#L142)
[arch/arm/include/asm/page-nommu.h](http://lxr.free-electrons.com/source/arch/arm/include/asm/page-nommu.h?v=4.7#L20) | + + +##2.2 alloc_pages函数分配页 +------- + + +既然所有的内存分配API函数都可以追溯掉`alloc_page`函数, 从某种意义上说，该函数是伙伴系统主要实现的"发射台". + + +`alloc_pages`函数的定义是依赖于NUMA或者UMA架构的, 定义如下 + + +```cpp +#ifdef CONFIG_NUMA + +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L465 +static inline struct page * +alloc_pages(gfp_t gfp_mask, unsigned int order) +{ + return alloc_pages_current(gfp_mask, order); +} + +#else + +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L476 +#define alloc_pages(gfp_mask, order) \ + alloc_pages_node(numa_node_id(), gfp_mask, order) +#endif +``` + + +UMA结构下的`alloc_pages`是通过`alloc_pages_node`函数实现的, 下面我们看看`alloc_pages_node`函数的定义, 在[include/linux/gfp.h?v=4.7, line 448](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L448) + + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L448 +/* + * Allocate pages, preferring the node given as nid. When nid == NUMA_NO_NODE, + * prefer the current CPU's closest node. Otherwise node must be valid and + * online. + */ +static inline struct page *alloc_pages_node(int nid, gfp_t gfp_mask, + unsigned int order) +{ + if (nid == NUMA_NO_NODE) + nid = numa_mem_id(); + + return __alloc_pages_node(nid, gfp_mask, order); +} +```` + +它只是执行了一个简单的检查, 如果指定负的结点ID(不存在, 即[NUMA_NO_NODE = -1](http://lxr.free-electrons.com/source/include/linux/numa.h?v=4.7#L13)), 内核自动地使用当前执行CPU对应的结点nid = [numa_mem_id();](http://lxr.free-electrons.com/source/include/linux/topology.h?v=4.7#L137), 然后调用`__alloc_pages_node`函数进行了内存分配 + + + +`__alloc_pages_node`函数定义在[include/linux/gfp.h?v=4.7, line 435)](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L435), 如下所示 + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L435 +/* + * Allocate pages, preferring the node given as nid. The node must be valid and + * online. For more general interface, see alloc_pages_node(). + */ +static inline struct page * +__alloc_pages_node(int nid, gfp_t gfp_mask, unsigned int order) +{ + VM_BUG_ON(nid < 0 || nid >= MAX_NUMNODES); + VM_WARN_ON(!node_online(nid)); + + return __alloc_pages(gfp_mask, order, node_zonelist(nid, gfp_mask)); +} +``` + +内核假定传递给改alloc_pages_node函数的结点nid是被激活, 即online的.但是为了安全它还是检查并警告内存结点不存在的情况. 接下来的工作委托给__alloc_pages, 只需传递一组适当的参数, 其中包括节点nid的备用内存域列表zonelist. + + +现在`__alloc_pages`函数没什么特别的, 它直接将自己的所有信息传递给`__alloc_pages_nodemask`来完成内存的分配 + +```cpp +// http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L428 +static inline struct page * +__alloc_pages(gfp_t gfp_mask, unsigned int order, + struct zonelist *zonelist) +{ + return __alloc_pages_nodemask(gfp_mask, order, zonelist, NULL); +} +``` + +##2.3 伙伴系统的心脏__alloc_pages_nodemask +------- + +内核源代码将`__alloc_pages`称之为"伙伴系统的心脏"(`the 'heart' of the zoned buddy allocator``), 因为它处理的是实质性的内存分配. + +由于"心脏"的重要性, 我将在下文详细介绍该函数. + + + +`__alloc_pages`函数定义在[include/linux/gfp.h?v=4.7#L428](http://lxr.free-electrons.com/source/include/linux/gfp.h?v=4.7#L428) + + + +```cpp +// http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L3779 +/* + * This is the 'heart' of the zoned buddy allocator. + */ +struct page * +__alloc_pages_nodemask(gfp_t gfp_mask, unsigned int order, + struct zonelist *zonelist, nodemask_t *nodemask) +{ + struct page *page; + unsigned int cpuset_mems_cookie; + unsigned int alloc_flags = ALLOC_WMARK_LOW|ALLOC_FAIR; + gfp_t alloc_mask = gfp_mask; /* The gfp_t that was actually used for allocation */ + struct alloc_context ac = { + .high_zoneidx = gfp_zone(gfp_mask), + .zonelist = zonelist, + .nodemask = nodemask, + .migratetype = gfpflags_to_migratetype(gfp_mask), + }; + + if (cpusets_enabled()) { + alloc_mask |= __GFP_HARDWALL; + alloc_flags |= ALLOC_CPUSET; + if (!ac.nodemask) + ac.nodemask = &cpuset_current_mems_allowed; + } + + gfp_mask &= gfp_allowed_mask; + + lockdep_trace_alloc(gfp_mask); + + might_sleep_if(gfp_mask & __GFP_DIRECT_RECLAIM); + + if (should_fail_alloc_page(gfp_mask, order)) + return NULL; + + /* + * Check the zones suitable for the gfp_mask contain at least one + * valid zone. It's possible to have an empty zonelist as a result + * of __GFP_THISNODE and a memoryless node + */ + if (unlikely(!zonelist->_zonerefs->zone)) + return NULL; + + if (IS_ENABLED(CONFIG_CMA) && ac.migratetype == MIGRATE_MOVABLE) + alloc_flags |= ALLOC_CMA; + +retry_cpuset: + cpuset_mems_cookie = read_mems_allowed_begin(); + + /* Dirty zone balancing only done in the fast path */ + ac.spread_dirty_pages = (gfp_mask & __GFP_WRITE); + + /* + * The preferred zone is used for statistics but crucially it is + * also used as the starting point for the zonelist iterator. It + * may get reset for allocations that ignore memory policies. + */ + ac.preferred_zoneref = first_zones_zonelist(ac.zonelist, + ac.high_zoneidx, ac.nodemask); + if (!ac.preferred_zoneref) { + page = NULL; + goto no_zone; + } + + /* First allocation attempt */ + page = get_page_from_freelist(alloc_mask, order, alloc_flags, &ac); + if (likely(page)) + goto out; + + /* + * Runtime PM, block IO and its error handling path can deadlock + * because I/O on the device might not complete. + */ + alloc_mask = memalloc_noio_flags(gfp_mask); + ac.spread_dirty_pages = false; + + /* + * Restore the original nodemask if it was potentially replaced with + * &cpuset_current_mems_allowed to optimize the fast-path attempt. + */ + if (cpusets_enabled()) + ac.nodemask = nodemask; + page = __alloc_pages_slowpath(alloc_mask, order, &ac); + +no_zone: + /* + * When updating a task's mems_allowed, it is possible to race with + * parallel threads in such a way that an allocation can fail while + * the mask is being updated. If a page allocation is about to fail, + * check if the cpuset changed during allocation and if so, retry. + */ + if (unlikely(!page && read_mems_allowed_retry(cpuset_mems_cookie))) { + alloc_mask = gfp_mask; + goto retry_cpuset; + } + +out: + if (kmemcheck_enabled && page) + kmemcheck_pagealloc_alloc(page, order, gfp_mask); + + trace_mm_page_alloc(page, order, alloc_mask, ac.migratetype); + + return page; +} +EXPORT_SYMBOL(__alloc_pages_nodemask); +``` + +#3 选择页 +------- + +我们先把注意力转向页面选择是如何工作的。 + +##3.1 内存水印标志 +------- + +还记得之前讲过的内存水印么 + +```cpp +enum zone_watermarks { + WMARK_MIN, + WMARK_LOW, + WMARK_HIGH, + NR_WMARK +}; + +#define min_wmark_pages(z) (z->watermark[WMARK_MIN]) +#define low_wmark_pages(z) (z->watermark[WMARK_LOW]) +#define high_wmark_pages(z) (z->watermark[WMARK_HIGH]) +```` + + + +内核需要定义一些函数使用的标志，用于控制到达各个水印指定的临界状态时的行为, 这些标志用宏来定义, 定义在[mm/internal.h?v=4.7, line 453](http://lxr.free-electrons.com/source/mm/internal.h?v=4.7#L453) + +```cpp +/* The ALLOC_WMARK bits are used as an index to zone->watermark */ +#define ALLOC_WMARK_MIN WMARK_MIN /* 1 = 0x01, 使用pages_min水印 */ +#define ALLOC_WMARK_LOW WMARK_LOW /* 2 = 0x02, 使用pages_low水印 */ +#define ALLOC_WMARK_HIGH WMARK_HIGH /* 3 = 0x03, 使用pages_high水印 */ +#define ALLOC_NO_WATERMARKS 0x04 /* don't check watermarks at all 完全不检查水印 */ + +/* Mask to get the watermark bits */ +#define ALLOC_WMARK_MASK (ALLOC_NO_WATERMARKS-1) + +#define ALLOC_HARDER 0x10 /* try to alloc harder, 试图更努力地分配, 即放宽限制 */ +#define ALLOC_HIGH 0x20 /* __GFP_HIGH set, 设置了__GFP_HIGH */ +#define ALLOC_CPUSET 0x40 /* check for correct cpuset, 检查内存结点是否对应着指定的CPU集合 */ +#define ALLOC_CMA 0x80 /* allow allocations from CMA areas */ +#define ALLOC_FAIR 0x100 /* fair zone allocation */ +``` + +前几个标志(`ALLOC_WMARK_MIN`, `ALLOC_WMARK_LOW`, `ALLOC_WMARK_HIGH`, `ALLOC_NO_WATERMARKS`)表示在判断页是否可分配时, 需要考虑哪些水印. 默认情况下(即没有因其他因素带来的压力而需要更多的内存), 只有内存域包含页的数目至少为zone->pages_high时, 才能分配页.这对应于`ALLOC_WMARK_HIGH`标志. 如果要使用较低(zone->pages_low)或最低(zone->pages_min)设置, 则必须相应地设置`ALLOC_WMARK_MIN`或`ALLOC_WMARK_LOW`. 而`ALLOC_NO_WATERMARKS`则通知内核在进行内存分配时不要考虑内存水印. + + +`ALLOC_HARDER`通知伙伴系统在急需内存时放宽分配规则. 在分配高端内存域的内存时, `ALLOC_HIGH`进一步放宽限制. + +`ALLOC_CPUSET`告知内核, 内存只能从当前进程允许运行的CPU相关联的内存结点分配, 当然该选项只对NUMA系统有意义. + +`ALLOC_CMA`通知伙伴系统从CMD区域中分配内存 + +最后, `ALLOC_FAIR`则希望内核公平(均匀)的从内存域zone中进行内存分配 + + + +##3.2 `zone_watermark_ok`函数检查标志 +------- + +设置的标志在`zone_watermark_ok`函数中检查, 该函数根据设置的标志判断是否能从给定的内存域分配内存. 该函数定义在[mm/page_alloc.c?v=4.7, line 2820](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L2820) + +```cpp +// http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L2820 +bool zone_watermark_ok(struct zone *z, unsigned int order, unsigned long mark, + int classzone_idx, unsigned int alloc_flags) +{ + return __zone_watermark_ok(z, order, mark, classzone_idx, alloc_flags, + zone_page_state(z, NR_FREE_PAGES)); +} +``` + +而`__zone_watermark_ok`函数则完成了检查的工作, 该函数定义在[mm/page_alloc.c?v=4.7, line 2752](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L2752) + +```cpp +// http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L2752 +/* + * Return true if free base pages are above 'mark'. For high-order checks it + * will return true of the order-0 watermark is reached and there is at least + * one free page of a suitable size. Checking now avoids taking the zone lock + * to check in the allocation paths if no pages are free. + */ +bool __zone_watermark_ok(struct zone *z, unsigned int order, unsigned long mark, + int classzone_idx, unsigned int alloc_flags, + long free_pages) +{ + long min = mark; + int o; + const bool alloc_harder = (alloc_flags & ALLOC_HARDER); + + /* free_pages may go negative - that's OK + * free_pages可能变为负值, 没有关系 */ + free_pages -= (1 << order) - 1; + + if (alloc_flags & ALLOC_HIGH) + min -= min / 2; + + /* + * If the caller does not have rights to ALLOC_HARDER then subtract + * the high-atomic reserves. This will over-estimate the size of the + * atomic reserve but it avoids a search. + */ + if (likely(!alloc_harder)) + free_pages -= z->nr_reserved_highatomic; + else + min -= min / 4; + +#ifdef CONFIG_CMA + /* If allocation can't use CMA areas don't use free CMA pages */ + if (!(alloc_flags & ALLOC_CMA)) + free_pages -= zone_page_state(z, NR_FREE_CMA_PAGES); +#endif + + /* + * Check watermarks for an order-0 allocation request. If these + * are not met, then a high-order request also cannot go ahead + * even if a suitable page happened to be free. + */ + if (free_pages <= min + z->lowmem_reserve[classzone_idx]) + return false; + + /* If this is an order-0 request then the watermark is fine */ + if (!order) + return true; + + /* For a high-order request, check at least one suitable page is free + * 在下一阶，当前阶的页是不可用的 */ + for (o = order; o < MAX_ORDER; o++) { + struct free_area *area = &z->free_area[o]; + int mt; + + if (!area->nr_free) + continue; + + if (alloc_harder) + return true; + + /* 所需高阶空闲页的数目相对较少 */ + for (mt = 0; mt < MIGRATE_PCPTYPES; mt++) { + if (!list_empty(&area->free_list[mt])) + return true; + } + +#ifdef CONFIG_CMA + if ((alloc_flags & ALLOC_CMA) && + !list_empty(&area->free_list[MIGRATE_CMA])) { + return true; + } +#endif + } + return false; +} +``` + + +我们知道[`zone_per_state`](http://lxr.free-electrons.com/source/include/linux/vmstat.h?v=4.7#L130)用来访问每个内存域的统计量. 在上述代码中, 得到的是空闲页的数目. + +```cpp +free_pages -= zone_page_state(z, NR_FREE_CMA_PAGES); +``` + +在解释了`ALLOC_HIGH`和`ALLOC_HARDER`标志之后(将最小值标记降低到当前值的一半或四分之一，使得分配过程努力或更加努力), +```cpp +if (alloc_flags & ALLOC_HIGH) + min -= min / 2; + +if (likely(!alloc_harder)) + free_pages -= z->nr_reserved_highatomic; +else + min -= min / 4; +``` + + +该函数会检查空闲页的数目`free_pages`是否小于最小值与[`lowmem_reserve`](http://lxr.free-electrons.com/source/include/linux/mmzone.h?v=4.7#L341)中指定的紧急分配值`min`之和. + +```cpp +if (free_pages <= min + z->lowmem_reserve[classzone_idx]) + return false; +``` + +如果不小于, 则代码遍历所有小于当前阶的分配阶, 其中nr_free记载的是当前分配阶的空闲页块数目. + +```cpp +/* For a high-order request, check at least one suitable page is free */ +for (o = order; o < MAX_ORDER; o++) { + struct free_area *area = &z->free_area[o]; + int mt; + + if (!area->nr_free) + continue; + + if (alloc_harder) + return true; + + for (mt = 0; mt < MIGRATE_PCPTYPES; mt++) { + if (!list_empty(&area->free_list[mt])) + return true; + } + +#ifdef CONFIG_CMA + if ((alloc_flags & ALLOC_CMA) && + !list_empty(&area->free_list[MIGRATE_CMA])) { + return true; + } +#endif +} +``` + +如果内核遍历所有的低端内存域之后，发现内存不足, 则不进行内存分配. + + + + +##3.3 get_page_from_freelist函数 +------- + +http://blog.csdn.net/yuzhihui_no1/article/details/50776826 +http://bbs.chinaunix.net/thread-3769001-1-1.html + +`get_page_from_freelist`是伙伴系统使用的另一个重要的辅助函数. 它通过标志集和分配阶来判断是否能进行分配。如果可以，则发起实际的分配操作. 该函数定义在[mm/page_alloc.c?v=4.7, line 2905](http://lxr.free-electrons.com/source/mm/page_alloc.c?v=4.7#L2905) + +这个函数的参数很有意思, 之前的时候这个函数的参数只能用复杂来形容 + + +```cpp +static struct page * +get_page_from_freelist(gfp_t gfp_mask, nodemask_t *nodemask, unsigned int order, + struct zonelist *zonelist, int high_zoneidx, int alloc_flags, + struct zone *preferred_zone, int migratetype) +``` + +但是这仍然不够, 随着内核的不段改进, 所支持的特性也越多, 分配内存时需要参照的标识也越来越多, 那难道看着这个函数的参数不断膨胀么, 这个不是内核黑客们所能容忍的, 于是大家想出了一个解决方案, 把那些相关联的参数封装成一个结构 + +```cpp +static struct page * +get_page_from_freelist(gfp_t gfp_mask, unsigned int order, int alloc_flags, const struct alloc_context *ac) +``` + + +这个封装好的结构就是[`struct alloc_context`](http://lxr.free-electrons.com/source/mm/internal.h?v=4.7#L103), 定义在[mm/internal.h?v=4.7, line 103](http://lxr.free-electrons.com/source/mm/internal.h?v=4.7#L103) + +```cpp +/* + * Structure for holding the mostly immutable allocation parameters passed + * between functions involved in allocations, including the alloc_pages* + * family of functions. + * + * nodemask, migratetype and high_zoneidx are initialized only once in + * __alloc_pages_nodemask() and then never change. + * + * zonelist, preferred_zone and classzone_idx are set first in + * __alloc_pages_nodemask() for the fast path, and might be later changed + * in __alloc_pages_slowpath(). All other functions pass the whole strucure + * by a const pointer. + */ +struct alloc_context { + struct zonelist *zonelist; + nodemask_t *nodemask; + struct zoneref *preferred_zoneref; + int migratetype; + enum zone_type high_zoneidx; + bool spread_dirty_pages; +}; +``` + + + +| 字段 | 描述 | +|:-----:|:-----:| +| zonelist | 当perferred_zone上没有合适的页可以分配时，就要按zonelist中的顺序扫描该zonelist中备用zone列表，一个个的试用 | +| nodemask | 表示节点的mask，就是是否能在该节点上分配内存，这是个bit位数组 | +| preferred_zone | 表示从high_zoneidx后找到的合适的zone，一般会从该zone分配；分配失败的话，就会在zonelist再找一个preferred_zone = 合适的zone | +| migratetype | 迁移类型，在zone->free_area.free_list[XXX] 作为分配下标使用，这个是用来反碎片化的，修改了以前的free_area结构体，在该结构体中再添加了一个数组，该数组以迁移类型为下标，每个数组元素都挂了对应迁移类型的页链表 | +| high_zoneidx | 是表示该分配时，所能分配的最高zone，一般从high-->normal-->dma 内存越来越昂贵，所以一般从high到dma分配依次分配 | + + +```cpp +/* + * get_page_from_freelist goes through the zonelist trying to allocate + * a page. + */ +static struct page * +get_page_from_freelist(gfp_t gfp_mask, unsigned int order, int alloc_flags, const struct alloc_context *ac) +{ + struct zoneref *z = ac->preferred_zoneref; + struct zone *zone; + bool fair_skipped = false; + bool apply_fair = (alloc_flags & ALLOC_FAIR); + +zonelist_scan: + /* + * Scan zonelist, looking for a zone with enough free. + * See also __cpuset_node_allowed() comment in kernel/cpuset.c. + */ + for_next_zone_zonelist_nodemask(zone, z, ac->zonelist, ac->high_zoneidx, + ac->nodemask) { + struct page *page; + unsigned long mark; + + if (cpusets_enabled() && + (alloc_flags & ALLOC_CPUSET) && + !__cpuset_zone_allowed(zone, gfp_mask)) + continue; + /* + * Distribute pages in proportion to the individual + * zone size to ensure fair page aging. The zone a + * page was allocated in should have no effect on the + * time the page has in memory before being reclaimed. + */ + if (apply_fair) { + if (test_bit(ZONE_FAIR_DEPLETED, &zone->flags)) { + fair_skipped = true; + continue; + } + if (!zone_local(ac->preferred_zoneref->zone, zone)) { + if (fair_skipped) + goto reset_fair; + apply_fair = false; + } + } + /* + * When allocating a page cache page for writing, we + * want to get it from a zone that is within its dirty + * limit, such that no single zone holds more than its + * proportional share of globally allowed dirty pages. + * The dirty limits take into account the zone's + * lowmem reserves and high watermark so that kswapd + * should be able to balance it without having to + * write pages from its LRU list. + * + * This may look like it could increase pressure on + * lower zones by failing allocations in higher zones + * before they are full. But the pages that do spill + * over are limited as the lower zones are protected + * by this very same mechanism. It should not become + * a practical burden to them. + * + * XXX: For now, allow allocations to potentially + * exceed the per-zone dirty limit in the slowpath + * (spread_dirty_pages unset) before going into reclaim, + * which is important when on a NUMA setup the allowed + * zones are together not big enough to reach the + * global limit. The proper fix for these situations + * will require awareness of zones in the + * dirty-throttling and the flusher threads. + */ + if (ac->spread_dirty_pages && !zone_dirty_ok(zone)) + continue; + + mark = zone->watermark[alloc_flags & ALLOC_WMARK_MASK]; + if (!zone_watermark_fast(zone, order, mark, + ac_classzone_idx(ac), alloc_flags)) { + int ret; + + /* Checked here to keep the fast path fast */ + BUILD_BUG_ON(ALLOC_NO_WATERMARKS < NR_WMARK); + if (alloc_flags & ALLOC_NO_WATERMARKS) + goto try_this_zone; + + if (zone_reclaim_mode == 0 || + !zone_allows_reclaim(ac->preferred_zoneref->zone, zone)) + continue; + + ret = zone_reclaim(zone, gfp_mask, order); + switch (ret) { + case ZONE_RECLAIM_NOSCAN: + /* did not scan */ + continue; + case ZONE_RECLAIM_FULL: + /* scanned but unreclaimable */ + continue; + default: + /* did we reclaim enough */ + if (zone_watermark_ok(zone, order, mark, + ac_classzone_idx(ac), alloc_flags)) + goto try_this_zone; + + continue; + } + } + +try_this_zone: + page = buffered_rmqueue(ac->preferred_zoneref->zone, zone, order, + gfp_mask, alloc_flags, ac->migratetype); + if (page) { + prep_new_page(page, order, gfp_mask, alloc_flags); + + /* + * If this is a high-order atomic allocation then check + * if the pageblock should be reserved for the future + */ + if (unlikely(order && (alloc_flags & ALLOC_HARDER))) + reserve_highatomic_pageblock(page, zone, order); + + return page; + } + } + + /* + * The first pass makes sure allocations are spread fairly within the + * local node. However, the local node might have free pages left + * after the fairness batches are exhausted, and remote zones haven't + * even been considered yet. Try once more without fairness, and + * include remote zones now, before entering the slowpath and waking + * kswapd: prefer spilling to a remote zone over swapping locally. + */ + if (fair_skipped) { +reset_fair: + apply_fair = false; + fair_skipped = false; + reset_alloc_batches(ac->preferred_zoneref->zone); + z = ac->preferred_zoneref; + goto zonelist_scan; + } + + return NULL; +} +``` \ No newline at end of file diff --git a/study/kernel/02-memory/04-buddy/images/__free_pages.png b/study/kernel/02-memory/04-buddy/images/__free_pages.png new file mode 100644 index 0000000000000000000000000000000000000000..9fa7cec0ef7b0aa9338b5460b93794b26a4ef26a GIT binary patch literal 20224 zcmd?ORY03v*ewWckwUSeK?@XzP~5G!yA+2McL^>nMT-}AcXtR@ytunda3{D;zJJcS zJu??`Hy4rpzT5XBYporoq9l!hMvR7lfPf(@BcXnHNwZqIuf zCIUs&@Q|W_`-wm!GL9-1@HY|f{@)e%I6e@v8ukXh$4y{M7)|5p87Yrohxc==_*X0= zM?54-r^%j$QLDUI!6bt1hIVVqop$@j7!k-p81vA9&B4I|M)3vP|Mj`)sp?^S=eRr{ zVJuT9i7jIa_j>)Cj>b@Oq0|Axo>8-m>b*Mw_uHdK=}%gfWM1B3Vl z%l`CKjxnLt{mc|PqzSOv-`@D5m079SZa|OmEWgbuLOhqr$|BA+eCVv3Hdj$+OW05J z$m6KuAI@bp^^W@F#KbTs06u}~Ja2azB$WzXE>GPI{stUuM=4B8SXFBp$=9zyY7I13 zYZ7kT-j7z0kO6B!|3qegWq%RlzX&uzzjF>gNDj*n^Z0jtRmc)1Q!i3T+&gOVBfEJx z9(9fTO7oGSgdv#^1W6ATp0&{k$yha}2|`0UX9JN=6uGnVVH6nEd(;Sa60oG^fkH5y zA%TJK?sxO86H1#sw;}0nvqK3BTMe2Wp2iV1{`j*cbxnGYH)QdY&u+&HlxX-ss@JmU zj{9<*8Z{X)eE^4`f&GN@L0XmOui&8=zk2&r-Nl8_i3t@m1sZ;SDW$!=y()!4zZ8*j zbB0$8P{gxda}H^oOKJ!fg<8LB-q!b_oK^^gUY-5wR^&Y$9o<5GqiSIrHUU9!em>no zt!G@b-H3?JAoUcE}amD}s~l!fp@IfEPDq^T#~0g;J`shQP)aj$l^n8?6I zKT?jdc&EF+FhOvw=qzb!eLg9q!PEOJUY>Kt3II9=Z*RGqSAQ&|iO(rFHO*D+A5p-} zT*?~D;5RA%C0;qz4g}@jYnP}=c7&<=yRH`N=;-X1Z+Ck0d=dS!kd{Ry1IY3D(DMiV^mmV!mFl#aj1TzZqPKRwI(@n zsa(~IWgZpS8nN>JHa_Zi`9YpJe2`K`=--MouDJQ|iB3*o*MHca=_;}a4Q_NWp$5n; z3>H6N1(>PWI60C2$LFQ1q)Tf(=_hc^t-JWWlKZZ7U0Y{=>rV+%J0z(6hM&EE;iw-B z_YyQ-zZbuu1@xIe-V@nXP!lvC0oQkqxn(b@Q{EosVvdg0f=Y;OKNIjF;3L}TGC=B> z3SLZ!(yCve5COB!r|~AaSw`nr;n@NkU5G8<=6H>IzJSMJP2t6G^=n5oXZg49N|NXG z<(!dT3wa1t--;@wSRQUEcz-M;6Sa8#)cx1wFdr4Z4gkF}VjeQD=X@e2CN7OQ&@NKS zh{!I%JcQVDUjBXqG1qS4G@R^y<4#T0jBe1c)6pxI0Tp(^=v|`yyrc+7}q?V4R zVqlO32GH>}?2f-jI*(oV4fz^`HrV3O0N^lpv~h#C>l4d>M<$MsD=Ja{^GiDOtwU0B zLql5$d<>6F&i(Ly_3%bY8d^H$Zs8Bux3l2^B?9ms^AKK2j@|hGZSh!ykeoaUlZ=0B zt1o;g{+QZ+uxASS2lp$cc27F7o0^&?II!m(z&d#p_P?HdeHwpLZSm6P)!3cv?$B)S5J>e6P^nqaDaXm_sGyO4AmkfGR*x5w!*h4 z;6#Uor6or3MVs}?4EA0kkOJ<1&s+~@WC25lx2LNKl<=mhyv21s@SLI$C3$W(I${i( zmIJ^CDh&I@KdgOxB26z2!65n~3NVE~i`46^^C^-VjfO|6!U!`r9;&ZnlN|j-!@phN zW_#b}Vqr$l!I--DU;24)Qn9#Kdc1+?HMyU4VeAlrm<9Bo#x7|L$R^*RJO?c`*f9OK zpn4~z45<7JMma5`*Z(wJgd5u>jr4%*P>h^X#TI-rP8R~h1F4)1QjU&a6ciP4d|xx! z6X13zoUU$huXTG`s$JH&ZEpeqjePpgl4r#aFtygH?ctrX!=qkem1bReR2om^{|r~# z1GjA(Hny6T%@1&k4*kUspM?2m-r~*ztxA0)c)Ij#h95zH1o^0g29Y`Ea+i_yt@_Ts#z%wy@G{=q6frxST z%0*9d6dJ<#X{{pNJF$mKrN>t2Y*Hs*~qGck{S zxlbGb`oTb7-|-~Nrn=lb?Cvgv*XPbL(N3bc7c{w*<)rjLf{u=Uu=`Kpei!KkTxj;< zduz{G*QiBf%ziB_wBfDNF_`c4An2E#Tq81TwQs~2#cJ5bd%D&hKAP5Kyxe$VIgw4d z=Km_h$CC50c$U0ub9XoMM3|k^K*>_LqXT6Jng;8mlhw=64DvA8c3N|@8uqf|AnGtw>bsHD1aFCZ`I10x#xt%%CJcxGcK&FuQ zM1zespNcXZP~g&;pPITYoNqdN>H0m`F_u_PocmuoTjjde`@s@wZrd?7fMPckp(V7Z+z>DftRNKEm{qNSl3 zd@U8h!EukrW1X6K;dR-KXlp+?M$R+sL%S5#X|XQ&qlUj=`8xQ>mgf82l3!fV_d&u? z7_As~%V9qDXHOveRr~Tx1uHBy5vWJI8e=O3j}P}vWm+YS&wd>DcT@EyJyNa*ONuX< zQCE`Tgu}}}{6hSq{gQTEGbcmZk&2Zv+6{Jj`NGHq+~`3Mn&p<1!f<4gn+J+#NRcHJ z$+*g~ilgOY1O*ojS9}c$-%oddgP-0M4vPe~)s90E(YyP5CeT+U<>8XZxva({+EjlD zi9q(7uS_H)IRB-pl0;>a=R()*>rQ1Y(Qs?jtH*TpvC4yv z9(WXOf1AH3jNHu=5-PenHXGx*+1&_scAy-RoGCHT8*4HDFTOZFM2qZfsTk0sd;#@; zFk`N}A>-e;ulw$~FyY!Fc_rj?7sGxN5FL#bMaqZ9(?oO03)LzvR)fe4Z)>TI?f;w1 zb4+rE9zN)uAnRJkQ|G2XM;uH;ofuE^Nr{A5vLl^kBr+1658bJ$Ctu6_oN*X7=|0pJ zIb>PqZYPzh%sgt7KyBZ?eG4XEPksCcAF{xKjGoS*$-X^e3Wf1P_w3-kzlgtQ8$9dF z$aw|ugRL!|Dt%U_*oqoRgFJ4;~0odkW1jr2YE!p!aVgJ98Rot~>W*K4~O- zVgdx*o^#+VzkaETZB*l2AZSz?o=>F+;kD+5)LN|)k137uA%joC86ySw#%CXib*z6B zw-{J`gS#=4wmbHNw{B&60|d(4;65{OI~O?A>@7YugCi0;-b4$tVf~mj8kE_L^eaIjyK*_HS@}JY08kvXtYVwf2p8Lj{Km>NESF93dTD$XX822dL>mY5(pUEgvA2Xu_7=cDj_7#F_ z3jFp54c)25kl;k=Wh!m$d)^{wzFF?JoHmz|(%#~5y3O%uSKpZffU$O3vW`gEC{;3C zU$xWE*GwS@$gbDcNJS}Zn37vca=cQaUYIK{J`F`?DQay^TOrn2eftf-!J&}B&NuC> zX5#_*p*HRb$CSw#hYBUY>B0uZ!dyiN_O!dX*~t0*UWU`l(>-%vmIe>REL=M=TzK?| zL{CqnQvX{e>&aRk9Xz1N*VqQm-4}U^9M~0|H|9RrDJv_R9V3lC=dofm#5#h(s{I=D z)v7igVBdz+U16%=!eI=4V2S2q022BRH$JTXJscm_`%vc;8dC5B58A2|{G!Px^NW;1 zcll(0rY!yJl|R@&33BzZA?%Dh9^?2k?-JS02S*P)iIw3?Wm0^X*0ZH%J5PY&!A>Xr zsjCy%9nE|!haKt6qJLE8aK;ytT=v2&e(Az7MQ<p z;;O5^@Flf_25y=<&MsC?seN0l?cxQFMD&4X)bht`hHTT5bJ-l@+0^EGg&w1EWUPv6W$cBOH+kN za^>k++)tqXz+e0v#2pa}R;}$Q>Wp+_jjeu0*|vik}v_!p^o?y15At z`cLGwE!>ARo{OXBH-6{$L+=bW5S$1AXs*3y4g!>fdQO&)u716HRXwj`b@e1zdG2n?YcZR zwC)<>QKZ5ne62j#36SDt8I?hF&AKl)jobX-o4K6yl|>E$5LtG~Gx~zEfA0cMC(ghOw!&_)jP~nd6#h~R zx|O#EF9j`G#p0CX*GJ96+Wqx#2}hw@XaeexO2g>7EjgaW(ODyjL~L?@|2W(;gAjgX`%1E;%y8ae%xnRNu?pzWcP%K8 zSAv8;GZos(nERTg8nF}tJ8)1q##=O&Ob$yXX-~>f5#1!;e<7R6iHM6kG`O1)Cl&Jh zx17P&1D_8wNvgrH^V^E~=q4TzYY3c94kJS+O7@d7!wS7_kTG6E!UGiAsC?YLr0INgwZfZG6=+wAE+MiK9li3ml z;PV_ofc;Bb58HN*{US8HCijrUFK)sbA}3S~6DOMx(yH41F}5HNr-#Wui<9_Dw>6t0 ziq=Mp|0P2)65M=VJd+}(qV;$jjNv3Z!2tmBR5fmt0GLMremEbQt6`(@x*&&Ol6|$c zW!9~?jLMY^XJpV(foALe;?I|GBuc}W!H<|^J0|ue zcD#OOjG!tk!p{F5W8VC|+GE%4*VED1O1xOiCf|ZHh{U&$l9Cer$S%Z;8trhG!-)3J zCy5tN{1fHH8a?*s8xcUG12!=TgK0#&E_}7eG*<8hY?+mEm^03B7{UD+`orGLENCOU zlQ)~=CKbNx$M_TW0C-~Sjfm1%Gl#h%fE!3CC|HvWkJp>98f@mZ;4^Kvh7+F!CMmw@ zlsfalpApVyX*>>oM-RXv@~sDW2D^B=PoB)%JUpa=a|A;QILU5DPG#9XDERz%^U%h{ zr(q2eJ&kxuCox>~ge`8AFEtK4) z9LB$Ir(5YVDc9e#RS3qQh?0#Xg_>NG%vI`KI#CkBd#Dl&ce_^>_)yQ`|LG|6 zT0X3pFZUk)^f`wbjWI3K;l3@5dS1Ntu!|7$W_T*>!&$GOrg zJB=Nj$`13IbXL$f><8yGBFro(8$?dDd%LF#x$IVWV`kMn{f6_pS41$D>r8RP_xZPE z(BBNw$NRkBQZ65ulRHHLQ<41fIsJa$%YVIfvt93pn}ZKLa)Vwez3$PufO-5@XlrEr zuJI&U2erMUCk=C5>SaERe7q&FH$`E7O=3N-W-#o%8ZRya;K&Q|54M}L?YXlE=-b6> zQHyB^*H}6q6P7xtb^Zb})%p5DqJ=@s2#OIHQ{DS}U@lH}Uc!RV@P1=pmS{K&zF|7T zqLCx}CuU1R6O+Q!p|ruuKky6@K}-< ztupC-Cfv^PrUjDFMmsdP-sWTg@b+}g%QnbT?p&5b+k%mK8qmCpfEzk|W%tZbAso{(^I%$Q%!_!z=>1;OYk1!M=Ra6MtC;G+uEQk>kR0=| z^a7r2+_HyjKDf~%Z)U@1{Ph|-Go21eXc5K>ExA}4&hB^8Yio;VTeajXo_#zj9V1ZH@*MzEFUZA^>4Qgq)QH|O)DMWbYu-%~5jcDSP>7IrYuHM51mHssZ zChf}ZU6!=#xu31AEdY)AidC0%Zbq%5`w5o=c%}c)!`i1Al-7^|;$sm)Pc)|BWkrPCqSA4iJ-F)0{aq5cOG!{z6mbO)Ff@}97pgs*tlTXM%4KHgh$M06#9@VtoGKGnA;?hRA7^3COoqa zCEK@rlMTJaOIub3LD`1 zYO6aGR=;w%UI?41%iz`}Ph~C0fpJ!@DIFS~ppItwS?o`kI4_+Fd6_>Lj*hO9fsf|m zrY9Qn?p2oHVV9AC2*l3lXAuD%C8eXQ0S#c9DRjb>y5Bb^0{;$Xzlw`X`uMa7wpomm zUueD}0=7TH_52TH+|1KY7>Y?GFgP9`Hq+()x(#Pbn*AC9zkVf9;uBZtOnwEZ=iE z!PyyLxI7_JQL4JgA3Ul)@9-b`33iTXea%2M4;YsjnphY>F?)WI?+>y)+ilub%pR`yFKs~+pl4S4Xk-70Xwf46Hy^aLQsm#mQ&Z)K_KoA64-6Ya zEp}fcH)-MWH(Zq+-nRaQvfKsNgDlY99`vkF{zDMRC?PeM)w+GZ@h3Zc1yETg)sB5U_`)-0RzdSKN$^fLzglF7G;HidRRdYsl$6R z@F48N&8d+0jtQExVk)N?bSMGpq!?Vt5on$Pf$Jp!0l!omO4J4NOw!F&{59!O z)++SoBlJ0+`#%p1{&(#rI7Z|x#9PdfC&|~AoNQ^PAVQKh=d2X-CYtinC8;|8==yfN z1=a9*3os<4UgoLjX(d(_#$WQSc|sC6Rs`RvmNU3_JFD`6ssQl4_@BGg|0mk^eV*fCTaNO3m#ClDTY{IvtcE=7^S8Q0v~d#BDXTpw zX5PtgIXOxZOP&~@KuG6eb?w?3k-I02W zeID3!tERv-2=xN*g#`Y3AfY6d_9F@?NqbY5?qQ|PldV{we35Yr-g$`kb0v`1^T%xM zE5gp>(~CnrK7hUV8WRpE)^?UCqGIFz*z}ckW2fsxXPX-xO}KSoLa~dyO+H({U@t8#a0|>nUvA-R>b5eCIzEK zcV26VDL*rv)<&r)7o&4(LN@-cXJhoQ3SBpf2%xFPlXN9aB7qjC@v z&&~zvqA@GWk!W*f*r+cyqvdZb`=>xzfl~K z+wMWOJOB3jZORL3o@O>KAro(sXe7iRJlOEC(R^Zl?Dq0u7fCUmHUHeH3%`Ll#MJ(d z5mu%llVXj^aDJQ-s=GS2NkYNe>{<~KFvK&Zu*vvrxUsUmFjd94KQCd;IE79ifvAbb zqE;y&On^l(K+XSvNG`ED&=Yd&$n-=|Y1I0&%%4;u+sX!3uJ<0_T5BLAp{zUC6e&50 z{-+wgTrNG@_S-r&`obDR*3Xo#1uTa^AV#zSkVwBNuuYKl^G3jtwxwVd(5H&^uSG#T z4W2UgYw;%qc|5I18{DRv27hVhhjYT?w0Uy#6m!P&<8CS)9yjT4Nhb?zUBrE0mQ-Pe z9G&SVbW(EPU!(FN*-i|j&wqfc@+ZNsA#cBo3~AUHe4sqv={Bu*5G0&b3^v}xw1AcB zYuuljt#*w$ESZ+yS2e??i|At?gQh=*gW?2oRx`(V9|mlFO4oQ&WW;!3L{F1=8Aq0< zdJycjp3ySOyQ38b()A8NS=8$<(@03R#WVN*A~n9=-l@d#tMI_yY&e6zIQiC}c{C40 z%W!d8!$5=yy=Ghsw;iP_MnWsN0Xr*M4jg=nT7A9 zC}F5>uV@&F2|>$46kqZy3Qo<`Lw7t@{O?esb3xd*8{||J{ge+{MD_-+C{2~f#@@zG zt_SyQ%#1p@4M4(DsWI0L*=_O`OIo2tRaC=tvM?4)!#lTITx*i$Xe$bP^llxx4{`txR2 z#FEc6Q3ENSQ42=?A4ywhCit5RKH)-0n4)^Sy1Vg$(9&`PJm2Fn-XRVpK8p@LW%So} z^<1DIYY=8zpE3Ab5aGDvsf(n9?aAk_%v<2Qz7so$;_rPcE;wYm)@@(RY&4Ncd05OO zWncSO|F%lCDLKmcE03HV=BB!lg^!k&cPj%Otl#`xgcrX;?yw_ak_9PNfK0_fhm@B2 zEPP3lowX*EH}C+n412PRtjLc7sqD74QnfKY{LH;3Z?iKOjTu{ib^1FW~)si zotbZF3APd+&wggbg{I-m)}BfvePU%GI)aFO34AbjLf0j`?h8;Jrk}=$aU*;5Ymc}T z64>&WR5JBx7d}sOM%(LT3eOf#I?uPY+7}v87q7{w!aaSiCM)Y~m?GmfT5gfc2kkED z!t6NlUc`N!dsm7*9%g=i+Lkw6Uc#kfmmG*v z$zK=w)IV!Y?{!T^W&S8_@!)+R@8s%?{*zXzdwt`i_@D&!$_<$ zK>0S6?kkm*Ea7+_Rj*LS5jL>RjwPr-K3hh$@ViV4Yo(!g3>fnH`9R$1Y;$_#h%qzl zOBH3V&R}f!<7v2%aWSmf*y;QZe35LUc_@8ll4!Kt6R7PWTgeV``6J zhc4%??y<~+)6h?beT%V3KGg#4T#)owmr;up?)c;f7W#BrC`cH)c9W~q?n(7Y)>n#p^{CdcU@EYa+dg=+%eV0nlK!46Qj-jPsjygT1_T85wQmt^*% z?WWWHPmc!}pdhBnW$?w2O2H;$nqr+$l`j)Stacg-vbp_Traa4$>vEUu=q{3Y!dA5; z(idnJoj^s;VEE2XpDAhz+=~r(ys2RqJGss(15EVA-(`RN3>Y3P=oK_g@$^YdR7== zw>4n8&8a#c8sYT~F0O+VgWl`#)|W8SW#PsK3KY$m6i%;KXKtdlCMLwj#>RJ`i_{aj z`I>L}#0By02$7G1*9_1QB#Na5 z6ws5tM;z)&Gd;geH{eGnVT=y(j$$ty6=Ll`gpoX#8Y3_{?2XoY%W{BPh2WAHmeAeG5Uh4Ep;YZfYE6xC4kO% z`#IO={F!HO64d^-l$sdLZ;ve@I0SK+t&0P>fo0lh(FVz9XxUVb1id0yGRSzX z@$Ha9T~BC?InhcX`%Z0*1zWS<2>}&3Lc!=^c8II~Eqn2d?8diZiYVHG?X_LI=9`Q8 zJ3mnujTnNLi~uB;GY;HM(Tl11sma7@8><%j9~cY=&+q%`$Y>L5rp6~3ybffw!TiG*=k|F!&0 z>e%dzL~p;~m>NyYM_&@vGc747R(_sXAm}##gr3ii*_ORDf}F|&D)E7L@vA#nk@i5Q z!{uY=sD1$Uk<(pQB@H9KCWYCQ`)0^_+-g&@ONa38?tyO1TfX`_pWn_@8SiwN34Y32 z4RKOVb&rRsZ2D2r1?1Z%2-&5p#@ELj(OqLe|K+32y|m9(0_eX({mPq`r$*o z$lkMWAMotNwEYS}wWl`35yngP)wJHl-C7RV8S?8~%~_S|x$>NBULViq=yO!D3*rHm zWQ@0wYV8U0rVF*<=b&T4v?zuafef{L(gjpRJqMf;g;=Xyg3J)qXmW1TeC6i3S_XeT za3!kD+{Ig0ZDE^GqJxq(t?@ns2JKa+Q(2rOV8yrr1zTfc!Tu?^*5>>lHg5Y$vF{v7^~S}9jNPb$}>0;l_`)GbOm$yV;OOm1gA zSqDKTkKxYHR8PBv2qz)O69v6Gr|jeQ5enhD8fPmfRf}Y` zx=>$@AZ7q}JEkSC6vTuL^>2t6_#^HlN!wGh!MSniK)j2su1P>HRENTeXV{C;-{yeo zO`Yw`JDi;ZAh)&tKQq^h({-tZ=UUk(Q#ykYWbZJN@oNVW-zf?dbgYNRi13_R=05(= z6u;Yo>-YfCRW%)RhQnbw@JIyqTC6V9*RFE4-SE29wa&?#yFUx9eFhPgvuX;$ zUfP1Ff9!XoGRIJP0Tg`MJn>QZE|bMst*8^4WU+Xk1^t(3DuolHP~;D2UCm-##Xq0i zg3|i9uQAHn#zVr1H48o&)c$hR@zv1xO;&gEcM~&cN%@k+7)4v`kUuTy{8#^=P|ApF z9(1tV8tG~a!v`X=QALh*d2x3ewsgfcWjr*;mO&t)rc?KmzJ*n&0!=#g4K6rqkTK0~ zrJ(}tD)kAC7HPq|-L+ ztCW!^mXEZ~E5K`xWI%LtvZ=Iq$3vyJbT4HuJ9FNJi{!E`=hd8*?(mQc@-peP+NZ@k zawpr|TtRS@v=C0)w~uUP$o=>*yCJ=F$%OMuy-bVRbW2d7SQk?S8;Zyx$`R6G2P2*>9l-e-rf9Apd<|&cS>Qd0yL< z=pSXV9#7|jHq-fLadh%+8$l;f7`?tdVNg}*m;4UBLHPX=J z3~H4EN35q>XXd38!mpP-X{b6J@7K#&Bkuu{CM7aH=XeGD(cO2>!uzVPOe4a?l!{#G z9v;MHg1>t_6ymh=GKR8N&p0q43mg9Oi%k1#{_m>?8G8Ro$e?Qw zo6N(izvGP(24`)28X9zTdifk6j1eO6`s2cmDLa1FV*lRCh0}UQW?LO=_cqG3XBv^$ z@tS?iBT|ZEbjz8M){viIJ;HS$h|VAMm@at^$%^XjyfrO2(q}%0^{ttuIbI$DY>Cz> zemx8KGro$Z3kVa@lAN5Y7AT(=7_U_Ejzi@@i_c> zNh2%zZ|T61clnKB*TDH>bXHEcfEB8d`$ryi^aGFDK=SeB&|-yYH8R zyne3lqgV$1UR~0VUa$=;oK-jqsI987k;z^-dFWJ;x(eIIQ2(4MroJ0o1DHJf&l>I6 z$K0CeHVTf6jwUF7OYYD^2pW~MU`QOVXv-?AiVXwUk|u8J{Kc0L#+2SzyVhZM;pNwp z`0G6lf~}DLs3R%bK$rjNT~+h?7W44_kEruLkQwb1Eh#oDw{72bNdquTB{}Y)v zmXl1cQ4uC+y4#a?YK3fV%qY9Cl3;z1a^aXfh)qNwJ2K^A3kGETcH4hmgZss4OJdgI z=~F#}CK}j#!9pRe-k78^%#k#0PEA?fK<(Xbq;AePMVGcL;xP1OKZ&fh)8^?FKnS;z zR1>5?Q|xS0c7%e9ByDVMbm=0poSxDBo*dVUM>-PgrON@-*fr$~?5LCl+ehPUT?pxZ zSpC^7T~t%O9P)*&B&^X0v)^*hsM;w`#5DhhaKROL1kgr|C>tDH-+F%4fn+nUYI$kN zV-6JlS**ZAKGg?=wy@ix9t8MYArL4%0CI!|OkIDyO=e%i7hv7jvtXII*+?b{{;(XT z7S~>FW!+j%IR7R{m3}*b7Rl}ECV8`+VvQq>+J5yr?2L^x3jJo|j4t@en7uOVvM;Cf zJ#V{>NC3!rA6usAdtjDe04Quq(Q+6lSxtRg4?qo?v=4bBRb>lag4H zb?S-1h-yVQitcqOg9lL?ImoX$a*c%0)N%Ds>6xNj?&*f-dHOu+0p0DV{P}rHy)x3R z*ADbqa_``MfhLt&>qSAKKlC42yIhuR(`}(Ie-NL+UbB0pg@3-VYDw4_S;};T2w=g? z@b^h=e>9E?2i!l7)`RWO#A+zGLp5FZ%(f8YI;OTGAWQT3<;MS`; zB(l(PM{Bzp^7ruVsQenW{z~)5vb>p=61?6ui~;dwBu6GNT27>S_iAH~^M)nP1?r0( z_35&5e^LtZoeWCu!SFg?*+gC66xpGY_J{iw#O056)sB14yso84(*bHRarUCQxw#k3 z-$Af5RFC>3=Xh%W*=58~nYPddke}4CrFMj!z8v4A+=jnVRPV8;y^dfh0~%h_FYO5i z(lvIRIV?35h$@QDqzyLd-fQ565w~c9JGgxQS6Z{j<{RL5pRYIiUXyB`*x0 zEB8NgpuEj^=H!Q}8Zcx0@uDE)mf>NGO#0L~uKQHu#zx@%X#67m(=pz8lI8LFho<-V zhOS0#)Sq`&B>nG9duAB!ppE$E4sng^7PA=E2y|z|f37EN8tJ04Rxqo2ysJH5l8Qn9 zKrYHalkvmON&hi4W=k;swrz0t^~UwFfa9RVQfCrRw^K673tU8?snDAOGwVAd(t=BS zsPZmUv}h&c`(37-Po77WiJO1nF1u~qMKbX=a3H*I2sZ75@LgW@(4ZAjTACo3q7ekk zPNEgttWs3^2X37yPEU*%3Nu=*Zxqr|z8DfSr@8-$N-*4?Eu-Vt^GA(;Ai_um_w9sL zsMJW2#V`30&mW{d9&^74-XU;DG8f2q03}r#|G;ije>e5k|1dJqqsBMUw%;1GbFhs* z`OQad$4RVsK=~0HGK!D>#Qeo~+tsyzgf-rMrkV`dPv62;DV>Jg zk-dWU7=`3BRoU~7Tv!RBr{w;&Rl{x}9nok(XUaVjPE-l|`@mfG7GclUtS&5=R2nKXi-_eS!-Px zFEQ6D=H9#TjD1~);3ebYI9+oS%e8FZD9Te)Ldk?OdSujaV^(GmMTn-Hzp)F)eBkv{*DxI;>|^qVx|bL zO_R#rc3*bnn8rBb=nX#Z%QeAVuv^4EQ3$BM`gs!lr#6r2_n@ofg$h35Kh733B<_7YAd7BE$Uch*0TB9O z8k<5LVNRU@^b(_75H3cZY0c$Hk)V4c)@cr{+YJEA^=ej`>DY1;i@++P8Bb_UrfYQ< z){97xUtBeq2=l{T^(DxD4d40R{WAl4F{xiO&LjHjYR~XuW^LRAG4VUkGK9ibe@G^k z5Vhfz`eLIM(QZ5C+mdNWe*XHR0fgn?ctpKhdH;+{_{Pn6Et{3iNt{<gpNssF4o@$leU!|E>VVxBr&KW$xxQfz|^zq_J4#92JGHfkNW6I@J=CLWpt;UD= z5A}1+Q|q9P3mbXy5{d7q|A6T7{Q`hA<5^OW1^=AKs+e{?CZBT5A6MTkaAT;Q zZfY*kKHHuyuj_oQ)DIwB9N`rd;CSD`IZx+~?F`}7onfwe)yDeXRw3*@3X9 zReOGmB!r7MmSz-Ru!cCGWmRs&-eZn@Lt@4+!bS^SGZogKAE&IklSwfbbr$;P^7@P{ z-u4QEv`Aqf0H0*Tm-nNl^hkemEy|bL?eDfNDM^3WRzC>rt$)PRetB#q#ci7}rh8xl zrQnN?R#K~|1Jt3Peqe@|_0&q(r5m`SxkF&$W(Iqp9LDNKt>D@GmB);5LhK@g_Bc8B zp7DaT9r-Cq4&4-bPe0sN|Ku=r{_tJ2+%`@5g?jnFgsc47o~xzwMwO&;9go6ti7h|P zU<*UhW%cBGvJ&ld^Aon}f3#v9mhOV3;DMxcE7(P=!a8-OF^G8xGR1)9G zJ&I0>50?H}#2YRJQtnIRRW(c zzJUHY-te5unWAPFbBZx(Yx_>u-mC;?73IvWyE6ft!gO2bGiwl5-tT3|NHkRFeYg3% ze6?N;!X!0TwlkeKOc8)gl9X4SqJ;hlbPnX&)IYSsc*3a%FFnH0zJG-?iU9`oKU7%=lMjQUDSQAxWp4|V|hxAs@t+(-;{Q1?w+!ys1=D2{fH&dhQf5;BKE+zEW zo5;0C(kM4)_?aKXx%`fM?uYU+%vAT{WXd}nDGV5qHZ4u%6)KWkLihmm*#e4Pg^W>- zJm)q46!J+9_o5Ab*=mmyGRibK*FK6%HEHxW2ua_~`GywHqI4=9h5HBFi??tK!C(Q! zX|ngxlVgP}nSPT5WNGt~371gSoSjDKGBx08;*fwsEZ6Bx4D;Z7H-XW2%_9rakg!-EP6{9iw z!qZ*Q%BKdNK}tz>@7r3}-augp`S$Q6RW5vsO%cyA>mkKQrVR7~-H)Nm8K|+%+%Mtp z@%TqBrHp0V8sE<<94``v{u_n^)nvr|nOgEvYb03xJ}QHymPCufYIO${4GCzXRFY`A zFr8iOLYC_u07{V1zjEqZm;^467=9$%Jq~_#pgwmpRdglgSE3Hdy}u`(JEP52YjR)% z?^4+c_~T+ZIE1)#78XDKhJHT)8&u~0G zbOLL8paw<7u4_EmSY35HKof6QlQGA(FM6Wd(}gohBrAKnXs%c{A5GZ4FmsNSMVKO7 zasI}{@Yb63fg{^qzkQ{8&5NDZ&%R^`oEk4VJbB97Fhh{lcpCY$-Fu@>OL4L|3JFbq zvqsl9vftyCDYEDme7l(Gcg7u%Yn|;S3FeBg+*-;lo_s;~5$t4IQt}Es3u%xnNDnZ8 zAu`|P;xN{yL}y2n)_@nAEH!28(sU2ZOI9Vy_12O7m1_HVI-h7N3V>%hhjgox1NL~d z3Zx;Fukyc)rkc)0T9MFc75}>1iTv&ROOVW7kT!LG`F6&B5!J%|v}f(tpaA#%U@&4eeAH~~hn>wz-kQ)WH9MIl_BCS%h zyuKYVa0rUe)R+l5wbPc4|np3I@x-vry zzQENSi&B3DNz)lc_+^}cGXsx5tKc5Npr@G{apZ$v6hGi7B{<$W@cfSD|}Dz7lN z_$i1wF{(~f)bcZDmdWIIwQ|AI#8~@U^2~tcc$YipN!0p$x_4?0-4=_;`BAR~Ml&iX zZy1_%JB5(-Qv!tJaM`RyUC1Kw8YbiLrE4q~K9ky9Zrh;kS7j@$Vk2jiEqVr!tTBB# z+vIU1zZ5wr2S&(|dF9Prdfu_{8uAmnh?o2(-iwGVit2v-J-6PejkVgE)O)~SFll#5 zO!~OTH)8XxZOU$3%s{+jg~(Yohdo`4-?1CZWVW<4`9|^oD&|c5nP410{_uz_N9Ia~ zTp^+y4Kc!s$kjt~G+G*lCc|t|j+{B36mnlMF!s35Ib!B0=NLJ2_3ichCw_m% z=kzNtB~@GEeL$1y~Ag~Q$Xah~W^uIe#?^4OQG24|YF--6O} zv0Y^nQj8I?W`wPQcI;Tz+>(Dly$o1?d6J5nO6+i;KRdT|hbCT$M23WR*P(tMWFDU8 z=nb&Z|I3gD7r%-3{W5>T>xC93A&lEvdcl_UUaoA{D=AUkM7x$}EYF$AFIT1Qp9KT( zD20EHjC+dHz(!#nQ?3>TNDhtXv|Ajf5V4S?>^`-6xpqgz@k>GXkUBPoerpmA`J?yn zu$@}liG~u3%fPS+mu5rtt3)4t2YfxP-~%@(xa18!s0hBJVF)ALXE{Be!5-h%U1*A$ zp9D;TmCOBtFdR_D+Ae|(@z~U z;9MykzFuNdY*CP5V487x>91u+NdD;vp>uOw152GjBrRyqh zUyWw8L?idtR4ACLPw+8mg39X$D!=xPq3cdKz-OKsI}s2PpKoL#v?O9(G{&B2T*!kb|c=p9WL`Qv=MXg_*Sd_ufa|Kp0=x;GcOH=}BIx*w1g<|A^`vb1JRbXwrPT_a?oP zsV&rNUIOziO;E2G@=8@lX=MeGoPNVQ0ZDl_+f(mg+sA!?$pgdJXtCZH2R=vc1;b#vUc*5oTyCJEZuojD4r=+I1F3TwErI5KUH`)bau)clm`< z2DDbngTMp9Jb&T{K9Nd5(7#qA&*KI9YuS#_z>jgmrepvZLS@a++ z2k&^W=1Gn9f}$%cjdk}(4Y`|-Bys0FYLen5Hx^DF&2ygp3X(p%3=xM>F%hK@y+arI)i6$e79%tMdzNEZZ=YNgR0!|r7PZfm)1@q8 z%In5H2|zz-Z`?po-?dgTq$p&-6Hs*k(di!>WQJBm%k2Q?j-Ko)Hw0mP8^w{r zlrzTJbr#gfu9-|L??9Be9+m`0x4h$*8iP0v3lV&NbFMi`vpO13gGIXp`y8(*+Mok~l_?3pH9s9e38Ury4MYC(m!_@cx zUfi)08Mho_-6$N0G(Au~M3jTgXL^XaFlBk&-l~&pBMy@#O(7qf$RHK=CeYxQ^}9B( zxsL_X6%lS~lZI@r*inJ*TqaVC23fmHGuZ_CW=_Pw?P;G2X*05g?=C4bJiXp}(QmZ_ z8yiDq5<02ZM?34|(t@x>v11>`%yyFS<$u0Cs!d=1Dd6t$Gx(m9jw zA|*LvQC3+e2-h`_K{ZGOJSc%IP2Z;&RNZw7-%x__6=(JDAls2BX{&su%#Z$%h}S}z zXg*oL>$szbe7<`%lk=)(H5(A~`eR3+PulV;Y}xr;dnM2@w?Gm&YXTD)wo6?!ZAW@? z1d={7RH2OXRxLQQ0;4E3%I|@nn<2YJE(-+|^l-|6@E&C3KwQ6X~H_yD?i?P5Kx&lCRW8<5rfc^}EU>;_ELhP*H4bW|nt!_LDu}Vwcyr zrZS9&WADVgHHQk6_RkQy=Y+TbroZOGNS<%GxX`RwKobsR2dwo&RR$GDTpw^~`*_p{ zs-5J0Nx~zmER6KSaWJAT5gO#;Z@*{SQ_`V=R39{!}1JA6qh@@A|mKl)$5bgvWe_5=lPqj zV(bJ_D$9$~Vd&P`J-$Wl`{0$L+JSphrI1JXpa8!LRF%Zlt_Eh0i{84FQ?D{E_LD9n zJeFQAd@OVN36oaF1brC4xf!}uiIk72{Uo(NqyF91SS110l19fvzLrm~-l%&e(VYNj zuOTbCtzHMB}Hj^8^4P&c-ak*PnuYiv0$@ageO|o vn9U{(I{s0@{?D57mZ$uGgpREKI^)$QWN~*>32lF>b$^*a&5ei#&Y}MU41_lq literal 0 HcmV?d00001