From 066856d6f9e5fdad2eefdc369c043e76b3032f4f Mon Sep 17 00:00:00 2001 From: dongshen Date: Fri, 12 Nov 2021 07:24:35 -0800 Subject: [PATCH] doc: add vCAT documentation This patch adds user guide and high level design for vCAT Tracked-On: #5917 Signed-off-by: dongshen --- doc/develop.rst | 1 + doc/developer-guides/hld/hld-hypervisor.rst | 1 + doc/developer-guides/hld/hv-vcat.rst | 139 +++++++++++++++++++ doc/developer-guides/hld/images/vcat-hld.png | Bin 0 -> 68359 bytes doc/tutorials/vcat_configuration.rst | 89 ++++++++++++ 5 files changed, 230 insertions(+) create mode 100644 doc/developer-guides/hld/hv-vcat.rst create mode 100644 doc/developer-guides/hld/images/vcat-hld.png create mode 100644 doc/tutorials/vcat_configuration.rst diff --git a/doc/develop.rst b/doc/develop.rst index 6c2f8326a..ee57499ba 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -74,6 +74,7 @@ Advanced Features tutorials/nvmx_virtualization tutorials/vuart_configuration tutorials/rdt_configuration + tutorials/vcat_configuration tutorials/waag-secure-boot tutorials/enable_s5 tutorials/cpu_sharing diff --git a/doc/developer-guides/hld/hld-hypervisor.rst b/doc/developer-guides/hld/hld-hypervisor.rst index 2e0f8fca0..276c4f301 100644 --- a/doc/developer-guides/hld/hld-hypervisor.rst +++ b/doc/developer-guides/hld/hld-hypervisor.rst @@ -25,4 +25,5 @@ Hypervisor High-Level Design Hypercall / HSM upcall Compile-time configuration RDT support + vCAT support Split-locked Access handling diff --git a/doc/developer-guides/hld/hv-vcat.rst b/doc/developer-guides/hld/hv-vcat.rst new file mode 100644 index 000000000..0d707e7f2 --- /dev/null +++ b/doc/developer-guides/hld/hv-vcat.rst @@ -0,0 +1,139 @@ +.. _hv_vcat: + +Enable vCAT +########### + +vCAT refers to the virtualization of Cache Allocation Technology (CAT), one of the +RDT (Resource Director Technology) technologies. + +ACRN vCAT is built on top of ACRN RDT: ACRN RDT provides a number of physical CAT resources +(COS IDs + cache ways), ACRN vCAT exposes some number of virtual CAT resources to VMs +and then transparently map them to the assigned physical CAT resources in the ACRN hypervisor; +VM can take advantage of vCAT to prioritize and partition virtual cache ways for its own tasks. + +In current CAT implementation, one COS ID corresponds to one ``IA32_type_MASK_n`` (type: L2 or L3, +n ranges from 0 to ``MAX_CACHE_CLOS_NUM_ENTRIES`` - 1) MSR and a bit in a capacity bitmask (CBM) +corresponds to one cache way. + +On current generation systems, normally L3 cache is shared by all CPU cores on the same socket and +L2 cache is generally just shared by the hyperthreads on a core. But when dealing with ACRN +vCAT COS IDs assignment, it is currently assumed that all the L2/L3 caches (and therefore all COS IDs) +are system-wide caches shared by all cores in the system, this is done for convenience and to simplify +the vCAT configuration process. If vCAT is enabled for a VM (abbreviated as vCAT VM), there should not +be any COS ID overlap between a vCAT VM and any other VMs. e.g. the vCAT VM has exclusive use of the +assigned COS IDs. +When assigning cache ways, however, the VM can be given exclusive, shared, or mixed access to the cache +ways depending on particular performance needs. For example, use dedicated cache ways for RTVM, and use +shared cache ways between low priority VMs. + +In ACRN, the CAT resources allocated for vCAT VMs are determined in :ref:`vcat_configuration`. + +For further details on the RDT, refer to the ACRN RDT high-level design :ref:`hv_rdt`. + + +High Level ACRN vCAT Design +*************************** + +ACRN CAT virtualization support can be divided into two parts: + +- CAT Capability Exposure to Guest VM + +- CAT resources (COS IDs + cache ways) management + +The figure below shows high-level design of vCAT in ACRN: + + .. figure:: images/vcat-hld.png + :align: center + +CAT Capability Exposure to Guest VM +*********************************** +ACRN exposes CAT capability and resource to a Guest VM via vCPUID and vMSR, as explained +in the following sections. + +vCPUID +====== + +CPUID Leaf 07H +-------------- + +- CPUID.(EAX=07H, ECX=0).EBX.PQE[bit 15]: Supports RDT capability if 1. This bit will be set for a vCAT VM. + +CPUID Leaf 10H +-------------- + +**CAT Resource Type and Capability Enumeration** + +- CPUID.(EAX=10H, ECX=0):EBX[1]: If 1, indicate L3 CAT support for a vCAT VM. +- CPUID.(EAX=10H, ECX=0):EBX[2]: If 1, indicate L2 CAT support for a vCAT VM. +- CPUID.(EAX=10H, ECX=1): CAT capability enumeration sub-leaf for L3. Reports L3 COS_MAX and CBM_LEN to a vCAT VM +- CPUID.(EAX=10H, ECX=2): CAT capability enumeration sub-leaf for L2. Reports L2 COS_MAX and CBM_LEN to a vCAT VM + +vMSR +==== + +The following CAT MSRs will be virtualized for a vCAT VM: + +- IA32_PQR_ASSOC +- IA32_type_MASK_0 ~ IA32_type_MASK_n + +By default, after reset, all CPU cores are assigned to COS 0 and all IA32_type_MASK_n MSRs +are programmed to allow fill into all cache ways. + + +CAT resources (COS IDs + cache ways) management +************************************************ + +All accesses to the CAT MSRs are intercepted by vMSR and control is passed to vCAT, which will perform +the following actions: + +- Intercept IA32_PQR_ASSOC MSR to re-map virtual COS ID to physical COS ID. + Upon writes, store the re-mapped physical COS ID into its vCPU ``msr_store_area`` + data structure guest part. It will be loaded to physical IA32_PQR_ASSOC on each VM-Enter. + + +- Intercept IA32_type_MASK_n MSRs to re-map virtual CBM to physical CBM. Upon writes, + program re-mapped physical CBM into corresponding physical IA32_type_MASK_n MSR + + Several vCAT P2V (physical to virtual) and V2P (virtual to physical) + mappings exist, as illustrated in the following pseudocode: + +.. code-block:: none + + struct acrn_vm_config *vm_config = get_vm_config(vm_id) + + max_pcbm = vm_config->max_type_pcbm (type: l2 or l3) + mask_shift = ffs64(max_pcbm) + + vcosid = vmsr - MSR_IA32_type_MASK_0 + pcosid = vm_config->pclosids[vcosid] + + pmsr = MSR_IA32_type_MASK_0 + pcosid + pcbm = vcbm << mask_shift + vcbm = pcbm >> mask_shift + +Where + ``vm_config->pclosids[]``: array of physical COS IDs, where each corresponds to one ``vcpu_clos`` that + is defined in the scenario file + + ``max_pcbm``: a bitmask that selects all the physical cache ways assigned to the VM, corresponds to + the nth ``CLOS_MASK`` that is defined in scenario file, where n = the first physical COS ID assigned + = ``vm_config->pclosids[0]`` + + ``ffs64(max_pcbm)``: find the first (least significant) bit set in ``max_pcbm`` and return + the index of that bit. + + ``MSR_IA32_type_MASK_0``: 0xD10 for L2, 0xC90 for L3 + + ``vcosid``: virtual COS ID, always starts from 0 + + ``pcosid``: corresponding physical COS ID for a given ``vcosid`` + + ``vmsr``: virtual MSR address, passed to vCAT handlers by the + caller functions ``rdmsr_vmexit_handler()``/``wrmsr_vmexit_handler()`` + + ``pmsr``: physical MSR address + + ``vcbm``: virtual CBM, passed to vCAT handlers by the + caller functions ``rdmsr_vmexit_handler()``/``wrmsr_vmexit_handler()`` + + ``pcbm``: physical CBM diff --git a/doc/developer-guides/hld/images/vcat-hld.png b/doc/developer-guides/hld/images/vcat-hld.png new file mode 100644 index 0000000000000000000000000000000000000000..75da1d7a34a2188bc758235d0d0dba56fe603eb3 GIT binary patch literal 68359 zcmeFZXH-;8_BYxnCGVu4g7b*s> z5Xg-Y;t$F7{*HABgpjGKAgkkLvUYqf(Zt5<;y=tw^$r>_u2Ie z=DP0sT73}Z+{CQ9*EKGh^!Qo5w7$4_f7D&b(Ln`_2Q;Dkw;PE=gFtdtIqd)K=!6jELuJJ* zrpt1KUc^*p`GqDip;{V4H!LWD6S( zS74NoRD6%b&O;XR=ro3FC*A%3aa}a%>9>V0s%U6vEVo8Pc3>cfGid&TNA0lRX)ylG z-g?Vkx1N6Sd0)v=ulbtY&uzsq`GzU$rdyG!%M2lry(0nJ-Pq;q9n+qXw->S=sSxh^ zRl<-s{GtedrYm7_3x*s=^o&b0G%m)$kbYY=_8Uf%D-v02VqC{tEa(B>NR+_(-Ipr< z{NF~((XE)QSBEKlTbsjq$Of^Q(<>|3#S~52r!Qn1Vh2)=$5S#z8n)nAlU^R93ZCO( z(_^S%1I)XE@S8H=LDGw+bK{30(nn@B3!m*v+|6eEFdDR`Fqei=KgV9tuFpc;^?L=* z-I$ui_sWc_gk4R-r-I|U(@pW#$)e8)j%OUdl9B`pbHJIBr|){>z}%5DJLU~5)uM>{ zfy;sK=mj2VOnBBhOugU4Td6jz#M3hxd`8wRet*k7NZ)v*axJlp!hAuhlJywP+iUf^ zyL-n_`V6F~0A(3#JV32{^Zlj}K1sy-5$N$OqgN_BM(g=Z_oU*; zr3u*H9cTxaOxwHVIvfozV zNA;YgzevHiX=&)StF^0kdc=327{wPa3CEa4->(zA6dcU>5h^|Arqy)yO@%SIbKMT=h>Wv`R? z6)1z^uu6~w!Ea$s51QTLAH?F)!;<^N=gKJ($dHDP!_`vpCe47uLD;Y#=*r4(t$fr3 zJDsP9D`0h7ww+fM6^y@YCfBf%Y~)nU?zjChMTg{+3@?!er{_E1(`8?|&T=lM6sb4Z z%}`%at_Zp=>5a@0zJoHXKkjoGceHNU`Ig1?5yM#fBzwIY?|~}Ba%J*Q_SfoCLLlx> z3MWIOn7KH7(r+dv`mB7#=3316WpeTs`(ryzttzR@+(byRt^EG)DI5q$!XYvyo_)&) zl5-CTVmD?kk#M`vzK_CCYIB7+?Ik;ApW7kVr~HtjjWa{%SJy)vaygcN5I$Lj9DVms z2yU!g)PT1~#5}7%_X+}8xy>cg@m+>m*iD&~V}2#P@JxD0Mx+>*se2>4F4iwgBOzwW zW1hGrOb?o94U=ZJ+L==L>i#qlS&*n1k`4wlJiGMn`0Z^dVsq{Fj(rAQEgF>cPWLza zW;ysEH!4~VeM}rLLvJOOPn_2ldfavDT>Iwu9;7G3b7pAgaKrj@06i680KH4s@R$IC zh^ad->LCsO7bQN`=yZSf!}x*6Kl`V^`aa7NmsL0F59VHYb<}Elq*&QQ4LNf{fmy_* zX`Li$lBVt*VG6O$ht;#QNgY#ap}mdN-b9y#g$q-gu) z9T^fJvl%=mU9eo1ju{I*NeP?od?*c?M-p2tu;KEYAGh7I*>$UFM)+#oren(U$)(c| z(cex}c5RXc+Fb$s$C>_`jZ5^rGe7n9i;238FZ`mwk)ydAE*0e>drenF6d_ASPuf(eX8^D>URYlFSn5_ zF1d(q3eK8|%Xx9ymwQEePeXt?(Z_2Y{W|z%rn1reHRu#W=(Mh}1G-Vq`Q>q#sW7N**>)>$#G9gCfYx(MQHZIBZ*$he3 zDvKxfucalPIRL@BQP#q>fyjNI!?^r4R*(MWB}h@V2@W;7khdVL!%+V9upi<73HexT zB`0GW+DlwOZ{eT6Lzt40faDxtzD}X3zsuxBy3gFvgI!Hmgq9VZ@0VKDz&WNA_~zyT zM#C&?aOc06ab2$*KLts}d5l}e@=fSOpN&=y6|n61^4M*~Akxjcf%+y?~Q{pO39x?`HT3$ISd zm1Tt(l;n!uU9x@9pBxERgvbF;YAj~s(g1U$^aO~Sx))9g+arpbx4|M=3ar&>750Tf zzU1_Taz)ytlvj%Z77OA%MFp|Z0Q@NVC;3jMFf{W#{6x_`_8FxXpUdlZ#h**SvsK%? z8qTE|X^^ykOY>b#`{!j;51nnVWUnAW+4sS-Y-+&$fhD$sS@U@dB+GAWHygxFGu^g- zaxUg|Kk-MhzPMA_w6gxo9g@RMoQ8}q4PAs@q59}zK@scorFEIziVhZK>MGdY#zHll zwqr^250>#7&h$*ZwDtV=6;8>Rm+J277k#81ntnJ?KxFK-e;02y;H*}!zh-Rii{&*M zxg4qxk=uPE)I`@Gna(~^P&xg19W#%E$QTpFc?e3^rptRR8isVQ&F`jRQ4V5YITg#j zX)ttIZMTd@_jgi=^LbfTEnD%?FKdIY$(?!$(n}1G)Qv}ydqc3{rxcH!pirmSVcL#i z<}E43v2>bikh;&ncJ{f=B^X}uSUXMI>Fr++n6c2%}ZhoA;TV4H_ z{Zur@Z*fbHj758V8&B|-pvN=L9#6Y|0-dDZ4`K56>I~c^XYVK|>PS;G4aIOBjRqX+ zHK;AOT+!^(gUHAd7w9Stoubj#oW9$JW{Oos)u;O>?D*G0F&luln;ILu5iwMpuOlrQ z{%9R0&?l>`vv4Woqn3Z_Whd`)^PSH+6G@;Q^@)q#XTCMtx{SwdYBnCPI}dIK z5OBK*Ge;bGvhTnfN~tQv(_vnl;u}?Ld2$Ag{(k=aklnNiTJB&>UEk9)Ikz|zMUTTO;9~0dXpq@8d&zAIW(sau)RhQwF9qy z5wnnx&^*H7@|%9PPoY?5gw&x;O7Gb);iuHFN%v9XanY77wxFJNX+Elf7oc9ITWDL~glVO?0yy z&V?>}HsXwH_C|~bpJ+-(&rBEw-RhMlzz)})0}{xDw4+Z!rhu&lIvZ1XyfLRvSD9MAuRm>DPzSd7&iLcj$6Z(z zme#A05Azi;?8_!p}z~pE=i`&SmAM;G6rBx!*uhWlO(K z*wC~U_MTiY258L!3}RF{@XGhjBkYb*Q|z=(8l-6bA8RGw7RivXKk3>l_;T(CpL|3l zBchKrIHO$xq0Ho02BjL%75x=@J}T#k=-`#wed;+=TuIYw1eokvs=~qL_OKOTM!h@X zwP*DAth(aLCX#)#Bsn$I*pv{DZ2MA&CW0ReFx`@i%IOM?XI#JY`V+YX>$gy~$hgh^ zK}ZHH@%kL&eO0jLZi**dUIZVv4PhAAdXk;h46MU4mzL17w4`uEPTf+zT80--Q)tdg z=ri+fRQb5yy7y9LqlPDbMbCgfU(dvwy|L0gQ^iy9*X12qVvm_$w*my~DR5>Hp)fGLtgnJ;eD1N3?3@rM_+8C3O(>heEn1K#jqb_ zV;_Q;b;78ENHob$4YQM)rCxb0<4!J{Y9SwhsTG7x*9oq~Ha=`-^yPs&9~pMTN!39%DuM z=IF?_{ia{vZJ&!vyLQUTPo(@TrbQ^R|72Vp$&~h$RK7d zb~&o0F+N(8xHFAMFX{Tn(ocQyga?o5QrJ0YQ(vZGMqH$iabgs`CplSVO#NFPub);* z^`$6lD^VNXo>llX{w-@Gqm%@%<4s>bH2ymrC&G|szjbM=#>TUJaIDyX>_=J%<7a4K z%TuantJJTx*tZDoKyb+@Quu9D5AAkv+iF?N`c zip)N?7P4OR)gMJ|7F(iqel4L6M#45)*I)|11<9n$EXhoZ#Zz$t1_v%({mRzS%)q1Y zNuQCAa`sy_8h1Y5vY$rjce}9?*Yg1VE@pJbbH)!_e@AkE%))@_$852FyYF6G1b;&u zkP-ba^T!$vTKN|cK(BrKCiMLHa7|>*%=Nihb1=p7AHW9GaL3rTMXpouILd)RO+8X> zYX7={vGieGXQ?E6`c3-w@qnosx1l1l z-s5<0bdej-?RwQLtE;mWuZ)4tWySoW-WvDiAH#WrB=)0L!z}gGG&h??oVqHi{tOMC zkLnxpT90ePG1b~Z#cY2>33?BF5p-DUJL(@Ps0Nn*G2`nspbwYFED+t8$2Hi6gdON; zM=v})D)M2ngeY*Lrrby8^EPk;u?@t4G>ADHQ}eFXI2nuC&Ud)|`YdGNt}=GHV1zX& z3=_r`H8qOVVz<{;#ETet2`&?Ls^rnk8m*F$T zXw{p(DdqO1-|Iw{68-VoZz?5wgT3_&$Z$*hhpgXQ%l403K2|J$&4N`ZCFp#|iv@{DL!{!?fN< z#;1DV)~Oq(`-wKD39np~<(sqFMoN(nOX(->!}oHtvZSixt`-!02|@0r z5E_tn(rXUMW`fg2C*Qbt>jG!6!{iwHf~p1_?RG1Y##J``{PUh4?`@}x%z$Vky$h_` z!w%hZvK@|v;UhX}HgARej}F}0ZdgBGofccoFWnx_B3Y&mR=9n+L-r#0$hQg}KC0Gh zBrT=Ds+drYeCQfN**n6W@cGd3nRgIFzd3iV%m#xn&(zG=Veb4jNKnBx;f_EEnka!s z6xH)za_4tb$TWS;PDa_u_|&y8N@1!Uq_2lw0(}>$>iE_HEAMa}=$GLBjKNL1N^1X> z#K>tA8B|sA>cOprH$mja=1M;aP!5tli}j-6c@hXWsE4$rz%kJBk<;v87LBQLY0#Q7WRQ_CbTPg?a zJ0}Nuv9a0WvBSAjJ|&B*tVz~rZ&A%wCnaGP99$-+Lm{)7-`@;o0E1FA zL&=inhKs4QRiGQk!kaP?wp$xvj#}trbFIT(<##`Vi`$=m;H7DTXqjrz*FK3I(@bB7 zdUL28)HdR3cfV@-am}obIaW@^Jd(oBIrtGXQ;2{g^mt7{#U{05)ke)~Aq-i*EuaZR zo*No2Vr5@ZcyM+gf|enAlLWdQJmc`WSMa#&@c5zM4vTfBs`$+hZ3vVooT2&&ov@b| zUPVn^mrsp*r0zqq@gZ(EqTN{q!RvE3;0tEjWiDjE<>MpoVI1tZP}9@r$j?)Z=eTuM zDq(XEQJZpPTXVS4JLh|PVlB^lF7K1S&(i2N&E39rudVtiyRRieEsc7}lO%9O-Bho{ zebZr`r-IH$$B2mS;?~w}0o-Pa5|f8MUBjq}?NX$8mMoic+kGR4r?tWbMm2&3{)fwD zN3YHfl;Ad#$_NLv0}?MyyrUv9rsqs zfU`e%pXt~J^}t*~g5o-)$KfcTSLV3#Mp-#jKI*!Tl>JCPNc>K=5zLsp=iXyY+H2@v zPrhiTSmt&1RtLFUq0y&%RIwwp?<2OM`A zQ~ad}zF0{~%+E@b1SQG|shNp6&)!~**qQxGkh!aO+Gffgj68bQFe*K}id#&nic%aIya zdZonIam$+7=QjPE>D-sn#w{e_va|PQeid5`F3Dd~ZT6Td$MyuL0oPE8(d!xA2UGQ> zp80RG%^}vvRZ96bcxO|3VT&hE#UfpAeYT5~G>}i-z>9MH@g^)eTsq?*`O-v{07JQt zyU%JkjV)0AhFsz(TtiFiU?g8^n*on=V&@Ye-A&=w-!s}dw5F6s6hd}~bSY$;>b!Rh z@dzYmG%a<^RU}RZ%_N-^wy(EU=Y{M!lfDT|ZCemy8+Xl6BZHjRKBi_-QvTh(EyQm< zOx0Rpb-Z%)eq?|8cdFY$@wy(r$HJ0i_F|r1#EV;ouI_WM7XABICdDRDb~tzUGRZM7 zN=P7{ik2^Uv)Ydl@r_3e(yv)KLyyA~;2*(GCPr!Kko4;K2U*$i{(#Y&xiekeNv zs(U9=?L&^1!4n6#E8@63;#%fjXRLKQB|XvFHuV>+ZJb~2GW{so=#uCTZ`T8%G*nT| zaX`qm*^8sX6|F!IgwUIIO2T&{vGfsVDSHf`?JdY@-*k0Dm-`kN#YQ^T5mxmIAD%@T zeDttO^i;Sf8OA%S?{Z07wd9LSq$~ZRM*w=##OcVu8iBc&L-K5*96Dhp>uD20HVlpR z(5DVel)xgk>or)HstEBD;)z)5(g#_a()ZU((JTeI4_F14R9ACszSGd$R)k#n-ZBu) zpEcFC@o_zb^O|%b-mgb_r+&J2m!W`=$OzkrUFL2)P-xJjM48D7*@loY))|NEL-K#j{gP zS;m%`&3CL#olU?og!*<&K9&JpHnF$CmY_x-hw7(m@m~xi|E;Sn}n6rhNg&7G( z(rgMn2l1&(*@+*@kHZa^@>0Ax?3c@Vnm#V3IQws;j<_g3u?TQScBa-&qvkL8|ehLT#SOlk@wG}VHC78uN3#;?MJho&~4KHZqEVHosUG82k|5) zCsKF)Q=w}o)TgfkrkjgrCN044OfLw+$syo;6^5Xju1L*{8%I=X!WBj$F zKOwee7Djzl{1uChdj-3*n8p;7n&m8qyFR4M{lRuPG(rXI-4g0k-8tNN$_wxd6HDTqebQ9@WS-UD| zi3pY@e&L1&ul#Hh6$x<@S{i0wq;W!|4GfVjSP=%_>qYk7t%roo@h$NkBCGvk%C~N-Y5Y<37II8mN*!0G%(OHt}A0D z@YXqn7TuEj=;f$sq^vQ${0BC?7KP777X?SC2PXSM{VxyI|)DFQ3y!CuFi|+f~ zj?!#jLeEDObEYJoiM4`z-0ER7xxasaPRP>=rqra@E$BdL*T2L}5iJMnUi#`@Dchk} zXRQ{;lDyemuu?sh&Af*86k#>+r|7CTbc@s&T2qT!q`d=!;%RxnldzT}#26#6mkaFd zR!ZbDB)5bL9qWXx0@tdYjC}?>qHPT==!?zdN9?$94MG*<%F}h`io(BO#%OHPTV{r1 zCGRI_{4m@?0)%^(iJ%ir$vqu)DiA!UCJ@LWWoSQ6*eta9M@BT%dE$|x&1K~Ami(0S z_p7|+9gfI!nvr@<0+0BJt9n4n%*0yix%N43NT6M(TvU>W+C<6=IXc%af$>&CPPo^6 zVQtCzs8|5y;q?XP)WUphX~d%An?Q=y(d=O$F=Ls0d3-kpCY+tm$(ef{#5GfDvTFtdz{jTv)=3BYa<{T<(p6(5fG>*A#f_MoI zAZ4KeH>bz;9bmm^eQM1X3~z-CeDUUp*IJ*DeM!-+hV z!@*|*H^K=BQV5E=R04H4A{o1o$BPb9&0ff}0vL`zKXx#4c~;_xamfoB5J)Z`pL2WB zRvg)f?%lB}fxJVnWq`h!7~wUFG1l5#Y6_U7HIm?LLM$SyIT9EihxW137dGtlBn30G zplsk{zMFzDgk;I_Fv#V^bSEX0=NTRkJsF36AXih`s5GT>ZK1Z+N5`3^8mA-vn9T)K zjCVy!(k4QzrQA1o^D%whCjkCXU3Xb4gxq6;Op76Cs2y6LZQt49l04;rsMfvVeMeD zB9cdNSaeDFW!_>)Aj;NGO`cU}EP&t;c<^hzvNxAMX41#r2TR+ik{8S8*zj$-wRP7^ zkk2RIsN|NtF-=xwN_Pk3Ul$^e;$Mh#s?^BINRp*uJBKKrI`}&|MjpZBAcnCclr$*glUirpF1? z7p{Aj955J9XChJPy@Jxg>gv0vLB|cz6E#Pvzx? zc#vhf``)->(~3q$!hStn(RSPqlS%7b#lm}p8ZGIFin~#=@Rk-;fA=ynjF(H%e5AdP z!Q;mUWnK!br270^^--*0$Tx9}kv#KE}k z*X$&{8!;$e|EL$32%>N!vv!u~;<(cT$zHwW;!48!{Ml-4ip$@B2DiDGE2(JGL^Dwb z*@ThFc!FGEDno6|!i%7ss->Sih=vzOUqlx3taePQq)i>SOT9q>x>C}VlSo(Iu+81WRHhx|2m8~3$&1DW{Xig7s7MiBK zrS7M*9|f_bOEZFc}T z5V4zerQR{hv;{>?Id3Q*p|do5gUhTP%QtGcFUZd3&&Kr|u4bkj-74@o+KO3Jp8pZG zh4ytXJm&2Y&lOI;XMuEI9kAC!J_4REMC=S)vh7iiUIGtn z{wu89vgP52msEo$00ZK!?_*=s3YPHBo3kPz%;Fny>rVRhVhObX;JEFiM^R?o3>2vG zO?#k9Sx!YsJhRn&YRDwv<3`u8m~1;Ig?s+JtEM%=Xd(P+uK{K@!WMgsshp%W5A@M_ zbJ4EO-?gVwy0u!Fs$>RLZa{unzQ-cayDW#RN7O0fv4uWbI9J4E@L-x@plT{}t3CoJ zr`gzGV|k6{ma=f9`wO(B1%sG9oCYC8K_BB0f0u>9XDMy@4-om{3n}na_G=JhYJk+D z7l)4@`Xy3M>;(b!{K|UshaOUwF@}*1=w>iQ=NZtE`>3GT+SnTYdQZa<$Uxeg!iwkjsB`jt zX2Z&?em5N@e+qt-7*`>_k|S8QC3JD9b4NR#dP_ct>MYVE3D_YF{jA(q7jK$c1YHvs z-bkr=X({G1oa>O|qXP$VQO(8*FMmO%2w{DJI6pPCAEm>j()BA)c7`wvy@=IAvE3;7 zfqrGCBo58w#PU|IoHHb;+(da}ag<{Wn6a17(b%y+W%k(9{zL zK`bi0RqLV+<9$a|9v&-0f)2AS4gt&&NESn#daL2wd=%R$M3pl%NE1GBnjWKJRDI9h zjAlL0JXyswRP6(~Tx54ho-&P^!rl41&)v~C)6d^}{lOxHLOtZB*R#)6tA*GM_-6fi zDo70xm^xJi+XJXf0@1TD74r31-W*itPVNPcfQOAw&~1SUU{k#mc6vw;g6wxHg7-RO zEWbC$)GaZ{_b7wl%Lt0gLBIN5f%oCE!r3u=Qk;-V^i zyX{LxFYQL~Y4;1HyWsmjuY|T$YdTFvI;~MUI-u!i2pRO4)|*i|kg#8@TqKRLjj=QMQpTC*2wySsPEbd0}si_Pe22KBnyA09(Cz; z6K!l$_x$>_WzL6ULZ&1T9WDR&;%DNVpH}i+psxt>ie(XB15S9-XC;OgGW*jf7I*x8 z&H{ftcI}k^(;xg5W2X0fJq%&Z6yuXoRQEMlNpI8)J~DuI$`l%ex<+iekunqW4f{r= z91J64MC0t*<9E(5LIy`RvN4$aNySVN3j=Uz_N6T7L2xezV$eUv>g6quhOv^4mu~5c zLP!FWiNI`;HBtOG*l=UIkHzGVr0sgEr1B;%1@-)#>vtxc7uks7jch)xJr#tXQhzra z$-T#4qg4ymOpGJOU!Xxm*|X}iMYG_))&JUl81EanqBQ~Qf*(jFjpeMrMSAO%Nqr-zX92v?r^QsCA5 zz@w~ItYj;B%Va_b;J>xngq$)YM~R9IC$hm*>hEVbQ$==yL6MJ>+ynSn(`3i9u&s#k^|@X@J`ETF zSK5JC6Os?fT91?zb_7V2@zH@%61jj-WWZeT!v2%~Gu&MFS-;q9`VQ-bTPQ=e&vNT! z5mPIu=ZZ8Ps_Te_W<}JK2K1VBl&{AyY81xY**|oXJ@-01N?MFKh$TrBof`T zwwvD1b!i@x^`p4$9QREC!?FR$3I3AotfqHJj+{ZgSRVdCor~`PfYPLvckigqin=&K z`izJI2@PT??~%gewp~uxTtXc-s&rteE+KQ1_EfXx5@D_R^YE%M#!bnW zjmIT@8955e(OFr7Zoo4yn)2*@{hoL5hy6|~CRN(d)SVsAlTM)<#1v3vuK2mg$(U|n z3@JxO0Xcm_unY{_I{(T-I18rg676PX72#fyERGMFB8%$itNo%Z30RRZd$s<0vmAWhZA7?(tXx*y2@GkDCodY1in%S;&B~t#W>)K-DB&8yao{vV6`1B#?ATq0RHhD<|jPcceS=W>jUEk_QWF7O>3nrii z_FJwbr1ahO`twT=)+;%<)O<-jgO${F4e538yX?=Zspbwn61yI6ouxdDoA#&-0g*w; zZ9FEs9l!59s4g<~iK%!i8NM@Z*7i>DFiQSu-=-YQ8N~dL!jx~%`jW|*61A}ShPRzZ z18OeNII^QD98X1}uH*RWco1%#c>!;&gs8NR#Y;)cmDYPc$eHP(homAMpEgPnWl7oL zPtL&_J(Hgs5iIj;m>KE3{H5jAty!$Vs>PZrXXbjOIA7jwXc1c^J)&Ls`D9f-jV>um ze-Bsw(J@dR1YDynF>D*V(J0N^uv+L*8M{%<$%}90ABX@|MLwCujr(tDOGeuTEM$C0 zAGq;0A$X17o{~8}F>s|*2=#j9E#XnK?=lD=Z((#+;{k`MPy{m@>g8VBks{?>p2lHm zI2jo4^M3g*QUDk!JFH$DK)tJQ8-QrNDUpdY6bz_k(bEt=fF*)3 z9Bj#(s`K;sa)4yO+|PjBT;>dJfy5&V=L0!0hf(xk(E5JYrlUvGmnS>J9MsQub#o7d!YRh}Upd6Hk1pMppsUC7H4^tIh3- z_qdG&5AR;zfh9J?yO4XpdIKGYg@A0z!o#t=84Za|;+TY&QU_MC&0%3xob?eRe7IJ%!NFFQ?9Cq6%v>tk!g zj_+f-VvwtHLr-Q%5@%Au1AvomtWBYtUG@1>%(vv=Ip?v`_Zwo!7y>XMrncjJSoCIQ zqt}%6V6kugZ|Lv#aG~zgQq9`Fb$BSk`4R9Kbc)Ly!^(RjLx>@qS0JGshb*4;Y*gnb z0GQtOlHy`%qOw(sk_6RIgNy-tdIs)_IxkvwIw$@Bp9?*6(6%O8o9ydE=l6rnGv{2)XGQ1=Ap?QSGTN_K7QkjvuKXM**0OV6>3XDG3T5;I|R-uaiiUjfbCMq) z+5}i3VJjct^uo_ywWPjh14$K14K@yqj%g9VT^Ao9Ms(9SWmRsv9(VFv-&fWJ;r@Lo zqGpFrf{+NkaNX8s3*#ksfDb0_pD8LD7Q)d-OlFG2QFqyM%bkFW7=<9F(HT$g!%-ut zvE1R|LJQ1Ky>8SQ+61)qPGPTJ!p-`{T>x3RTcr4qik3G2ngk{i_o z9B(!8dNhMAvhjFA5Nk>(_r`Tu4>Y9U-B4&Yrk`9&v!d~E`auwE(~M}qO`SyN^JsbP z&IyB3q#Sw5?xqh#F6$_wOH{V8ybNE`sISl_`rqY-eiZ^jq%b!Zg57xuG3slAy@4?3;gDuo8zy^;kwABB{;3qgo?Mxgv=vf#rArL*i}N zYRiAjmY1_+W3PX_R%*MYA(F`{h5flZN!u6~GwoxaXSQSpGOb_MO>rneqKR>A^R|2; z-nzsta+;K8t4I5|IM>DBB~rlRR*Tl|I^E{|!=mQLE3BkpQMb5sKBwD#G5fJUVNG+_ zMH@-&wYvjzd0M{p`2*4nT-BDUS^sPMxV?;BOEi zRwRc7AWi)ChOvwe-nA*-Rt>q82j{3x_lAH>)JbGy?BgS~6Ip!#5+9|)9m4rfIWoZ3q%=hE7FSL0E$;en2*g~r>pFDT8$Rpe8?}D%=D_Wrp?8NPQ1mt zt@kYpx;>jgQ&LFdusxtFxI{T;d)wGEQ;~2yvs{hz7fSFR*dN`&YYDUc<1vvb>s_vB zhOTip;LeL%E?&VjYH~9L)QKkksFa%&fq_!oF;D?ZAKqZLx56V~us3EgE`b0cVT_mq zKrizYd9T|KM!BF%EZXzmKiCfsVN|0RcCaCgy*VR9X)nE$3Q~4law83YZ$Q!>k(m2~ANB7!Ap{lTYIjZY%MAWR+2Y|bfu`H*(xGQ{j2@#d{z)BM_ zHGw4gt1=4$(NPOJ?IN2ocBXQ?1L00{>uNh!VsO~wanhoClIQ#3rir+(QN=&SKt4yVtSLhr5qS#&IggB zg?t#<>B0X;j&|2YRhh{jo%Q#p9FiwxwgCAXwn!Cz{Jd!voK5LD=Cskw-$mS5OKLFJ zoT9x6$5`P@Ov%S*8!BXn6t@gaX2yg8Vu`E=U=e|oCq7dS^!o^i-J$yQmF@Fcum#<^ zd%XVbuyKHXJ_e`^IC#!SRh;LH#Cj2^V7hccOn5s|d>|BXMTS!?FWjKEVt!UYXKJ9W zcNF?0>kAYBe06VnJ_XU}+0$oEtrz87W+6YF4Adorh1|{I4+zd4fRMA&w7Z_2VU3_r zfoaO;GZdGDv@|kP_WD;G_ueaK34s{w$VP>c8oXEN?p<=(|LDSes%EIn4oU~yb~Wli z!HsRE!=dkO3BET|- z8T3wUTIwiJZ%u6FUoMj_-B)IC*8wQKY2VFm@XDs&rtjcnwQK2~UgP0#KCsb28wP;X z!-t^wutDu7;##iL;qEf8tE^RTvSSYsT`WTeKn%p^{-O^`08A3-^bhRn#JXGv1PWd! z{{G*#5$dl)L}d2TlROoItf{9V!r&b2t~LL;P; zk&izM+CFZ0Z5M8~)GFiVSWJ8{SCt)5e;;7oV<>Vrml+-bFx5y5rDla7eUo2c$G$uDz#S-)RyIaBJvk7KR2@mABpoCDMMZY z1i!UC@u^&Sah{5}oQt6mbH&HFMuM-u^UmG%S^Po4YLm7y!|+Q2k$y81ur$evEp+=L z=F8gFEPi<~dl4gS+QPHJPr2^FckIi@va#dm!sq@VR;v!V8R6=}*OU3{X`;GIBe*16 zEWs|$`p!NL$0ZSO?McU0z2*I@nCaj53j2N8K&dP9@5rPLb82p5dDT3!0qP2{Pf`Jq zra71XUf6%<1R3!*IDIVgv0=$`RS@L^q*Ci5vSF9j?UsvVIVI#$C#N4^9}?-Q^ZxH0 zLey-a1sXm+cWO8O+`wVQN|6a38u&fjA236_1@kHw9eKG;U z0Y)}Ff1kLawEik}BXS3rGO>?;a0ju-5A3Wjsvoy$bo933O#p2^-?LOZsVYbn3u2Z@ z5m5MC6Bf@50IzZ9?)@!og#JU?h-nob-R6=b_M3C*Z?W(2%q14i6WhO} z)IVoahp7h=1014}X9@&|amqmp=fD+BiTCBLhni%s(-T=PL7Ij^CzB*oNoeiq+E&t+i zS#ci7lFUT~eg&Zu**2VhIY^Dm|9-+Nc7OW@szxD7sAs<-ZRP~9ZH!D|TdlUl>I^zC zh6+nDb}e=;*^}X%>~@*6ZSQV;1ngGfVDJ~aaRE9I+kcvwGH3tVusIbc8i329Cs7m| z{^~iXYXn}+ohMmy+&P8bI}7DOOjkG`bqRwG#zr&}gn3QBf8!)g14U%SK8rx*SkC2t zV^ul!ucSBPdL%KEV0~%yp1wz>))1ljZi5;kmaCo(J4v=+eE%3b7kD=staTXnT&M3 z0j>&Q(W+-p9kk9$4HEw|JVLa2w}%g29EC;Z=*jfe(^jC~-U7=wKF>&dx)vZ)#s zmn!>@Z*KF^dJB1}TZEM28UwT3PNB~hIR~QqQ0-T3+3oKriCa8~j z{8`f1qv7?6VbL?$&qDUP6_Hrx(WkBp&w7*7?%)qm*%M2u>f=`F}!5@&4q?=vP2 z=zmi_m*P&w^=~ra?-#(4X+K7_Zn!RV{nWd7%XP5_>_?6Gd+esN<=Ce{EXvrQ7y@_y zoRiJD^%wCRfa1wjAnu!2*P~3PuK}Ogk@(Sz5@05`qM419pZ)<%=qj@MdJ`O@K*TkF zoNAJxN?E1(C>8!9ToD05^S7^h~dw2UBHWqyVbAyltXs5%7 z&s6=In6RU2KZd?OfxbGq^9b%lo zpDH*5D$I`eC-`TGI^`KNut(}glI*CU%sLvLdEl9oo?xJ-(VD-$Ax1db*@5CfNk_-0 zJO7wKG!^L>2*$k0IhB@MW9OcEp2#VwbV1DDtd{fX6llny9>3qxF652;)gMv$j5(~I zJin5D`PL~!#sBrjr5-8V8f=({OXgqqmafbbhc=`LCZ3>!~G>5yJ%g> zP~J{t>Sw=B?8CHs3tjOak%uF@%Y&dgQ?k^$w@1&f-8!M5K>B~N_MKr(b`WbrQ-yWNru4Z?%^@xUq{ZfdkXr<^W+T_xpre+6y9zuf4)A^g3u`{ zMV2J&MKvrAlZfTBE8^=4#(boE4YN{G`qQ1p$a|AGRg2lKK5XT!J4hpO1PYq85s*ir zlgvt!Uzd$h8?y6F@Evc@h331D8d_Ci(njn*L`XSyy|ij%QByW1bfcz1Y}bCg00nbf z4U4rdgxQ`eJ!-c2&6mKWg3`)jB%u&+Lg^UUdmFyDQ3z~eMUK}jp>vp-_?I>|*=vFw z42dNhvp90k(k|E0w_@_12Oo`->_hb?>&q4|xt5&^$>#W9)e!!J5Q8iVLtwt~5 zw2|nR#MVe}x@dued5YbL1v!vXgFw~^J; zd7rk$j*IVo-#gRJ+;Z`#qhq;IV5jFEVXN4eBQt=bZ7%rP$`CGgXbsO#3XUYNM8a(h zU!MO|UF+U3z`${I{<11X!wRv}^vY@8klR!MxgFvw-q*ZV$c71H?qjbDmy_8luVFTN z#JfdmT)pBv*NXRI&m$H`?%8+`@TaE5#5 z13GnAJ%T!i?-t>{2Nz)gRNA?yiU8|}vm;0(6`EckS3}C@^kq=>vHyC|_$1rz)0zQf zm+;pR$H~T7e6ia`LEc^C9YBatL?*FW&C;G+LsW7HpJ6s@t&JrGjo7#A^f`@xd2Nb) zjs6r|eq{4$Z&wo48|>O)H}Bnl~}PDDN+k1 zgaCC8OwwTB<5x}WyUPi7nE6$<&MOIQFWwy)@LpsAK2_~r){%8Bav-)aF9HrH3xMLg z%!6|**F#dbZQU&tiSy|n;w16lFgN3@uxvF1z!|oQjp*2`McI%lPd}enOsi(scTbbx zR$zqu(YiVg>gPFgzb>XvW%YJ@rwcYXPbAqCI~}Hf6^S}YtpA+XszbCHDl{WxvL?yv zmNyLS$G5lZ*wQxD%xnYa44+HJA^U2!+u+-EUPC)6pYs4!A4AUP$M+QcYq<>%T%~_} z3YFN>ckjcM#Bb^F%>eIXKUjC#_k)=%qZd7EpyN@82KD*+>ct&bJoglKKXmZ_XnZ0c zlwkQp>m8ij1@b_jxZXUJl80GetOWA(`kb3wO(r_x-k8hv-Exb>W-yrPU;I3dkNFi8 zypiANz;_&wJ#PS?8(eBxZB1){s+A7))T_qYP`*2MowO&grqu#y6g_t1drAge@)lCK zIrai@cYpeQ=BCtp!^EH^S$dE6x?r4o(_*Wgu+Z1S?10@t_W)+FpiO-q*cH0q;|gr+ zaY!w@X{y0#Y*{+F!J<^+qtuL(ONs$~--niTORK&QRP&DH(p=I*bg=XM3Nj?4WoN0D ztWYy>&eD4#=}3{bA*8ij&d#|gyw^E5yM%9R!zs-_VI%K)C&DR?;2|IjEiKHBPwprp zm{lihCPeBcAKMq(TX#BgzmLq@Q8NgY#8q3MHB;p_mE318X}0qMa+AD4jkLQc08fDG z?{Z<|l72KtX5|;-@)9kD{oSqjm=}#J{?3HP(p-l=4Ze zWb6{lECTy6n)G!F97UrjdCiw{rx~KyAE<#kkCDBauI|iaH-ncn^2r!2+Xm6sG;Fmy z)8sag6bOUOfotJW*ec5}buIeg<1hJ3zXl%3{LoG{hhw_u_*0a>rO~0HNq(&2zy&}9 z1mGhpP>tNGW2@vKwP^Vuz0(;S`lMAk5cST5wdS*w_nF%W6b8N`_ zkGJTYr%STW+GAPczU$>xGkl|FBavK-?Axn0U%YbYAe^MWZjod_@7l2oxB)y@KBOmx z<;5NPRC-KjC#yl}&^3p;ru%biCUa}QHqae=J$SIr(Yiq8 zSN~woypyyq2_C6WC;w7jXZ93xa;uiWZ>2+?7;TZoVs}aKP9580(f#enu ze;CPYy2~F>x}Gh;bE5+ROtqNpy|V5or#c6aPe za(YOt!GeEZ<(MDuYOK`sF>dqcatbKyO8IUFAk)Q@Tk*mIwpVJ==gva9=?9=zI(orz zwR#&UgIoFrAHCM~D~?l3Ielr;C%z)Y@RN~{QYj4DgOr@9KJ~@)L^o@(WjhD!@{FoQ z`$~&a;!m$xuZ%uX`N0#+Zzg@8I^J{iPFIB&aJ>l#>S89ZTNJq(1D+;qX_Zbv!)_Cv zeXP`gYONrIOk|=po_n|_dMZjzzB2QN9$40>5JP`G_G((->rGE*Kb+2k?|gEZD0poa z#Wmge5ZN*2+-Sw;ES+@N%vtIQeebDRRyZ4n3B@4-j7+CZhHdt1vBr&smHF(Zg4|rl zFCe>5lRCX-9t<&kQ6z|9OY7yyXt3RHCX?J8?@gcJ*cXvi<7k-JVdjtL9m^V= zAO_)N{gvY#kc&H4iyw_!?hd`_w6$PVmsDpBWo;>v@tnv=4zXj*kb9>?%8r6t&_DH_ z>28morbl(QVq@4y<2wL92NwW@--T;+^#?l2E*twFNyi*JFtKl50q*vw!fNZh-mm*@ zQkUx;C!ZyjZHK!|@|Bh%x=@v%Fv5QF>q^JTOQwtM>hF6t;bo%Y=}u;f{?36+3S`1` zUb;8^^Bl<$}YGW79`^>>8e|RtKyH{F+Ql91ANs^~A(u;0$Vbp>s8lw1ZpI zYC@0X64qJngs?{B0aAhxP~G94RK#RC%}$=4e7!wdk4?2qW@@t9jeSGhMmEhZL8|L` z)?H8FgqruC0*os;@K$?hng3z!i@I)ckK9)9PRa|SLIC<|igyn6da3j?-_X)f5jg&< zL*_PfxK1JP6aA)Qs~prS)4?16CnO5K@&ET;1P$}QE_wg^rbdb2Yc^8i3fMSk623VW zTT4JEK5CK?t@7&QW6H*8P4u37-zoKe`X zD`?TtmMQc2JpRD%i^>ly026A(!98C8z=idhc9kOY_7)yl=y$N4AaFJ32qaukr-E3d zO-m1^LAn`61j*Wfx5ztE{}I6Kq?xr;8=z50m)!gdkkJH6pTVx+@O8!N(HoG0^LcLd z?;_PPG2d>2V7_Cj0&*9eR?275hwng-h6%r>pihck1|XqsJ~Jz~1s`YeT24BN!|yrA z*K!%8FxWH`{d5LD9(CG%wpz3Ao$qDo9hpr;)xi9yxH2OGAq1JixTlW+(Vs$We(kTX zM|uDfQndTn{ySivi=n{oFi%;UeMf1opZ0>V7o(PkrqFWg@g~v8Q3m3v3_iXEKqb4+ z`>tO*5B+V9kDcb)xEvyzg2<>?0fsSYp?=e@!_-lcOj+C-lIr_oPD7Ha!u7MGC%VU;<11ggM3j< z5K+DgX!s1DemS7W<^OzsBYiuYkp=n~0!ny3+p%2T-!m_uZm0SC&0x1PQXZS^fK^*V zXlNgUw#A$Z5>1#7_$WJrI^YaDBtN*Jo7|j~Gwx#-4?d|n{mvUi3_yBsPT}Kwl>2YK z9bn2Wq0q``v9t5YLHyH{KmyFR5(u1KJu>v&N#Kk%WQS%PE(f$dMbP<&<=cUT(GrIJ zJr-^6!g4Oc%BR9rp!kuQi5T>;?F;C)?H|NNFrXlQNbF#$!imTKd?XHi1QEFO)omO& z!en||k^YUeyPTPN0d&gm^Zj*@8D02zWcbU*eL;3)+p$MUADlX!fjXla zEJS_4NsuR3u~gXFEzfKi320NnKUYp_Dm3l&Ym&a9G;)Wh?^BC80h|>5&k_QZ2%!A7 z!5RDX0FYh*Bo90R4F}X$NIKzIiVn1bv1sY3vw-MzN`0Xa_r6I5zx^|IaX zQzqRGjC5h+D#Wi?)h!qU4F*zltDZ2R%GlQZgcd_8Nr9ghQU(#h@Aw`Cx}%{J=Wa; zp`s7C)MAq_zDpCgHg#Adu@BUVs~zq&g8#sXU`r!`P7?)GefNuRC6OjN#WF=bA*QIz zm(YqHyv$A`&GG=GpXva@h5oV24<8@UV&5Ey{|~OW9|+mU^Q(Z^h=s&{(1Ka;A`~dF zP28Ek`!|sJ<0TX`)PE=9U<5(WZYso$6bK6huc)gl?UM}^?6`FikW!lI?+GtMgkK+7|`F4+rI9xHnq`7-s_xCi??rKvvR|OL{LChDe(ch);!dZ15t^h zQig!GiKoQJaD5X6w`LMSF?Kqr;38|~2|z=^fE>NrX~cQNuP=uHLk~zYi9D3X%wI8= zMBx@g^vb(K_%5{4n%@A2!f$S=yMXql6A+IDz&L&1(!jy(e-DEt8uovKqul{z7~x|3 zC%L2ID~eUMQ3 z-(WA=nnpwO`8m)9L2vs+l65jSm8?NV;D8?p_NB8C=M?nvNNQdS59TM?$j{J#MGmVB z(UkIQHad%)WG)FDVAMY<8|(pVu(?P>Sh9e}=ZHT*-u+ZGejp=w`wZaQpyqhFhIL)| zRP-Ma=_}}y37t!2Th9BsizSmbL{RG@Lt-wa)om71>#^EY-+`~u12});mP<<}gT>9C z-;sb14{!8>ise|)fx=-5am6ODFA7jy=1osnYJPmj2HQNr{3Tha9|U^z(O;qP5~EhX z-hbq6VbGfWyGSje9b9ta$2QVzd69tT3EW6P?N%abBYnL(k~9e?T|B~5Q3x?ve;Y(3 zC;OxdChkpfuWPNVQhk(4diYV|n&iGwptWfwY?7+~ol2n=sF=J4XwLmT&eN;bYqyR0 z9}dekx2%V4K8AT{>Td`S&N(<5$qOkW4I2iI^~xHYqU#bCn0Z0Hzi08&e?P~`XLYNz z7TmR_l>-F4SAz(dURdIa`?{8MXdzeRi`ZQAphz#$dSWMtWCF2ok-6~EXyWU$k>`MN z>AoEWV21>!uLz9E$w%G(g_e=K)^&Bz5rF%Hiv}pOA+HIL!}H>JB`SD_Eg7}==}E|G zUgPF|X|H0DYm&o{KOk1htspc>Qu8hanFmjk-lRAR`t?sjB>THr7hbUKnFzNgU;X+L zIwwOraW=X0*K94Vty^@iU_2Ldh8jMP1s;jwPDDDPgY!9tha)k7dPYx3;iw3m`hm5% zA#NHT7vv=>ArtVKxqT-?Ib`P{+r5aD!ZtoMJI>%j#!Z>m7+eq zi(H+?*w|WhX)*N$`fxd)E+bfX?5!pmFB#1j$Ssfx*)L6$JCf?elA1w%Wrm{UVEP?Q zbhm5vrUfiY)sNBJB@GAe270il)87c4vDlkMku0>iG;+u10%}Q%wf2Nz{@T4Y{@1np z`-DJvD|_dn+=1_aaP~dLb@Ab|2tt1g3?j+b?rlAM#Q6BxGe2r}-`8}=@%=*;*`vp8 zKs0t9qCCWV=8k6aJaqlwKISpx2~hx_5QND8;QQWK&UOtUTzija-M2?**;g|P-Uq?S zsGO2-3vs}RH2|WO!V$0nOQ>0KtQA2tKNT#Sp{L!t=xtQx_{LqnaY`IGgAOFch4Ve6 zby_YN0KvjbcjF=t99*_r)%}!lZoUn;yy1Dm#s(R0U>s=Z#19>4bz;dX3oR4vyMjYt zcOPcnPHNCbRzCuY_`Cgc&w#`$pc>n*08(F9_iq07yLPZl$8HBM1fQrqaGvqxvfVT` z6!4rZm%I(+3H%DU0K@Wj6g0D|Afm&5dcS)4wy{7xj_JeipmY;sDp%%Dv*7p^x>9GW z6SXu0A$f**IRw4DATs(?mg&OAopRrlr)}4pKy;V{Oo6!ZW+DnCLU-u2=VS?|pPhOm z*ztYX{-tFJW7GZx2jDHv1FGK+d>pTA5=Tk~4aNTM^fMi~?G4D*z#4dOB(tTSmhT>7 za+W%LJtjE^kS9wT3+V)H;N|O2zcSKHlzZn4jJ?_7*l)r@WeQ7Po=-*4Lf&H&Pxj1K zVY~$;IQz>QpaKDz0bnEAzTMjFeNg0T@p$`L`9lsKrIv|RKl-W#S>;(?;)J{c%!_#b)I5V}gk5DaLhkMqiK>;ZCSfH0wU*5Ty! zy|ILVUui`qY3VIRw_DaVe0G8!&C~nIU0?v~6md^%KIOO9xAB&b!8cML9yOxtnz}c- zHS<(XNKsVL--P2}R_%;Xo)U_TM%^L##%FBRsyGZx=u{-w?Wya9ou+4iaE#o4*}eupkxSJ~r}5{s)WJ zlMev{kkg-cw#?|CYj?NJ>@@G3G4uNxV*pnE<97s(%_zpNZGMb+C??cP@Kx77JTPs?{r0K*@3(!}7 zsM74aCJk;hgNNx|MnU2RxaZPHQ<9W~1X&=z02UWZE5j8_`xVV86Kv_u$XEDS7*r?w zosRPcsSsw1h0pd5!MAVM4790+n)B*hz1t~8P<&YYtGRe-y1}ZiW#(`kyX@=K>m$qW z+~V>r;_^qPZrV2)7VRP?V!6HJS*vEFi|v==Y*F>!ug}+u)bPGNCnP)~5VXEcxNGd- zu`=WDjKW+&4X^Cl+L`-;@$^Q-g6wSN6FyY@UqjxV?EV1blxt8dZb&M@j;{AyefDgd zG*WmXg+^M&k6wid9y3GS>TucR8vrElRacJicuveWp?Y|F{U;U1yAv7&Bu2OaqXarJd)}#D_;W25E3tka4f-|Gf%si1}qxOgB=q>jaW(VBGX#!^D^Sk>W zguo;79*#Vk#S|V6t~t>ZFbUl^ep!P{g3|D#f}Frlvw&ROzV*UJhuo&3ANM1DyVs0A z<^0aH8XLXG_MAJbI_gC(?(wVcUO}+E$1ryyNJC9MM~);a9!VV9AjTGBBVFdY9KPel zgvmd}iw;L@z29imleEuc%qf{6Ei?iD^g%GfxwTw7fRd-QnR1>puI8)lxM!Y<@6;bot1+#|a9$h0h+j zjYK&$H2Gmf47b62p>=^$e_%Wu`$A8Lj~QNP=HyX8Ytc(Z>T3!ex{&Uw7e)V5@#syq z(r>v#A2)KZdaRaf-){9jRDB6y_vrTLLP(5!_`vPH@k_SL_|FIH2(hjDyuU&&-ldi6qP6KB(mU&&lF^jwTs{{h z*kv@*{FO_EAm;0N^1bb`+MOZSd4&OzJ{sdbdzVmcSUG*j*xJKT)Y5<94OdWND_$du zz~*Jw^_6=~%bFJMHnLc^g#I=4gl>kCHG~GqCUr2TA&K8ebN2s{JZf(EtsvI3^)b$ZSSr_Ib!pB z>z!)QWem#ZVG4ZjwKZe~C3qBxG4);8kKwOeiNEvaTm(+uzsqA<4)6;k7R{!}u4xr% z0oPCGinzVI#q$l#@~_F~JpHQi;)Q(!n#U<=HiI|(F2ER1efkb^iX!-{H@c(mbIOF5 z!DS+N;&iRq09P((i8HJnSp4COy1ly4<0&^V>~_?4NA}l?N6&~|Jt8?g{Q1-ymrWt) zZ2Z83rwN_-sZiV+cx?(&9sM$kUyleZxgN>M`LsN~2D?-WK-Gsyob3#jZwd z=kMR3izF$#ZKsi2H|Q8sz1A1KIV!jg0+@*6Gc9BNMiF$KI_(J_6QvY{z=s4{shHIH z53ydKOum1dMP@`;6S0iYt+CD-^|fxEsL81UeEJ!4m+M8xNVNklWfM)TGIKwvG5&&F{18NQr)vmS=TiWaep9BTzvkBfejqPgWk0gHA zsmA{+{W~Db$%iUkVsUc5iLJ#xnS(Qv=Wr#?>uHT=3A#w$2uW&|I-|(S$OSrSJ!@}v zP;(F^=2etLjUXEc;H|J9WUwbkZ%ym5$?s-3$t$+)oi3fs1?-RwwqdlX%3+oYoAHR* zDMYnS?&bOH^E!wYcE$IdC)Zb6e~0b_pxt>-!^~lNSpwgiobxILCpsSrg2S>Qo?cn# zhwAc9_+@P8t1Nde9;wF}ggkFILvOVrrvnNW%VonoXfd-df?fkj6v%Q5Xou6GE$p&w zKmDnuUZS7NAd=2bef*{d+&?~~xzP?VENZpov*~$f@3HQNNIcb#bDoT{TFLW%Pj}Ne z9v;`d_Znv_G+tHYX0U9f|Dn+GX9VW3DKyPFNstY+UqjUNa_3KfvX~mnj&$OJaZyw zB2?#die1+4nB84q3y^)15p8|-$lJ-N2rPwW28A(g2pfMC>Xi7B&I!4 z+ewZNi~u-`c`5r5MYs6(xJ?7mdOgF;r&n0SY@f9boG&eaq)58+?=(GWcU9=dmFhBI zl1Vpsga4M-gN8OJ4gk$SOT=!t7~Ihkl_}8a|Hy`f7VW=t1EIhCouc)>(fj{1trGgx z|MehB3j3>;cc8yX&Ay5!Aj_X{7#$2!ZYfCunfCvJuFwPiPT7JW{_f*P2D_nj!kPB? z7`r3P{B2u7dSqs09p%kX}Ux&q9#^D~NCiDAu9tfs^2ob<&W@ z<)CEA)=4wmzC&*S^~E%F>5|Xc7mnswDg$s{(I$k(@dISk){vULM6HAszqB$XjVXz##k7 zaQ+8Cq|T^xI?xPkQ_+QsRUq=$`t@yaq-^N3WzY;KK1a5^0n~2Si=mUEn8B-DUjO?l z6Mb!JPDhsK-$CcQn4BlPoh$)|BPo(B#ryImBoBFD8WnV>N+Y)}~Ff&R``rJ5_J zk>NNUun?xJaG)6=n3!dci;sX`JY;w7;zQ?`r-zM-2LtOkg&8@)4>!5~o!>_sK%Yxf zty4xHXPxM~K-o)safcL1^+ya*mpLkse8=Xa|NWspE=D@t!9H%FheaB;(BOtE;n z0+1XRy0U)_rI8Oj9G;W}tslt3l!*cf(U99vcb}Sbnn}MPc(+2(A!P}=KYR_nPkl9l zTdiXyDCeCDa0u%9{|v}vJm^{q4PVmX6dJH8+KAzJk?w?y3jxw888-rEo3yDfg9&U1 z{8_HPezdPCVQrf4(;c2SuG;jWR}IRpRr2YC zx(GR>J0*?_Kr|Lq{~Zs^>k72akAq+reM5ircwA&Q zbWzuS%P?^Z#N??jf;FZF+biAo=jkRYR}OK44>gf;T1s=)V~Toy?C|X`bYMtQ=CP{p zuHBXf>#rI3ui(NC`qC(Z9)3T4kMLX4st)(KjVVgh=FrFl-k(Z|xM%H(g!WhZ&ye;T z`khl>rq{X%-r~ms!dBi}&ve%B$h5IsdFb5Wvvte-+(jPcBwx;b43O;AMPK@NJA5($ zQSHoYNXQvE&$qK!sZq15n=w!+`Pa!o!`e9XXP0}msM+a5>zTAJ03R*F<02r)^=1$5 zLi?r+0{njN%AarA2DMNrjT{cA5vqt2(GUh`Q*^(9`Xi^^8c))q!ii$pK92@vP+P-;IVC!ES>B?xdODohCTC_W~Fh(OWE z`kk*3RWySyMLYP0q504>CFdr0=x-Ie8-@WZS9^Ev~|DR(ohDNdBryr4Kye%Lq(4@Z>CJ( ztinqrXqvqmx4~S9YJUdR`#>`|a(}okv$K+n#rmCL=hX)0(l)^>!%no|yqT>3wY+vJ zVA`^MLH&9dK%l>V2OxNxnb8KTy65sTE?hB>1?LRpZ$U*{JRoEXJ2i|RjDw@R(Fx-2 z_NB9L{b+P^%O(PC&o>46a6PnbI2V5Fj_v9>XYiWA{y&ET=E)%wmT^w6?CB$>NIB_l zZ3Qr@lbw>&kq;j7C~({ic$z|E0JL7mAFT(A&$2t91Ujd>KeRIh2rOS`?Oak&p~oe5 zV8<9ap>VP5U)wk5FwMTato2*N0E25$Dz6pjLk(yWe-~j>MsItUKJ*kL8|9>xHfVoZ zt_pMRloZjAkw3xE8FV=O^MiDA8<08b|JN|~Yk{NksS-#XbYB7>PGU|npU$}=8b!@e za1|~2Ym%8fGGR0_Vl3U>V7)E+E_{MS4j@@kO6pMzO(((Eeq;(SGAb~pz65>(Dw9F&E=9}v*eL-$`?Ovn44iJj^zV1p zu$|>f{PibypfF*PtLD2=&^ZUllp&Ae#BMUfLD)y~pS^}zGEpf}pJoTF8tfXHk;Ul} z4uEP!&L$TP%t*#*(cPsYUdGF(`mU`CH4XswBJ5xL{-b1zM{$hM;qHbQQ!E3`v>$@* zBkhcVJ`myI{#@S_gJUOW&#Y@@o|*v4?T-fm^J!;hSF)9t?lwB0MA`J8%6`W`-Rh4% zuE^0F@HGAEFiM`~8gLq3{W-lpB(O4?n)P;F8a(~-T#ElWi`hat?36Pg&yrWuyXAGn z(Y}kL_5L&P5>OWe+BZ?oiOJ&Sec^+kNN0>8`qXo!>kgd0{xqCoCxO1S$%PUqvJ|iE z3;z)xnvyKa4QK~xtOD_X6%JhEpx#uF!3CupT{p5aiv2H4fT-F(T1pYo37nP*G>vWx zu1DK_=6&S1v%qxS`*Z4~OXTX*0STYKBTxmYP<{p?TYUWv2hDGb)ONjm-1mr4-(%jb zyo!a)&1rE6$m_2s@ZMXB?)2&58ceAFz>EG%{fO zGbIDhuzQ{HrPgBq?+5sBT!5SsW$bgb$; zfjfQxMzp11fhHyzv@*Xd7v{c8y%ssdZd?IRog53tg4bxiJmE)1A>8)~=;@6GkZsO5jl8+abB_)jqtC(Wr4w8uC_$qu&X+@?zCUti#bC>9yp;oO`8vP)>L$pt#(<2d> zsne$T>dG(XsGYGikL`#`kh)NJ>;Cbef|PSiu;h%^M_$W;Y;G4#7z|09dBWrsQ8kAq z#7c?Iy0{v`d>t3!?dY6`z@%4K-;cpo7_Pr!!}TJ6rY(<*AnZ{(>mhVyspSLrNFs-I zAJ(qcAzUv`=levdiC%34<%8f&gO#M6#rSU_w+abObf_vq%n>Q-oVn2 zy{D6LE1;%0KU@h&Dy)rtI`25v{egSdbqFAB^y8!fZ>BLqbiQ47-SIU*y@rNz?Kt#A z*qzWRg_g&}))x-3TCBii>X!fh^G0v=ie&_lqq=9IQ0>XPbb--gul1S4l|c+JE!sRv z;5Oysacif=aJV%dRq-JHDEO8(|L;F6RTJtm%@k}(J2u3re4Y8XtFGB1<(a?qG2&b^9=LQirNw{9OaJ^syi^v;HbBqGRFBqm5;M`k@RhE2ccaFG&LQc2juIk0}4pw;)&jz(=Ly;uv zl_DvIs=SjI)bq%2u^GBJ2PDx3V|-A>rI}7P3mMbcV93I<0}Tdh8+Q|J=TGLZ-aZ}g6H+6tHeinjEUrd zBk=-W^Wl15eo`YkpLM=AZ@;AY*n}91!`Zh-4_wBrPGOBkBz~4A^adl&J5H_7x^8)U zZ4r?j!^Urr9oa=@&}1h{${D?9hIH*t1mfC7E*x{N*$p5u!Lc=e>P zGT{fOi?{-W5)ZC9m(NO~N?6`rBI>rNMz0x0E!sXIdKMkkFmL446JGEH`m~BN0BV)| z3Tn?MQWhiu5YMeH14`@#ipY+!RI#WbOWG;Dn`dAA z%$1OQ^O5oKMDnO=Z1N)u687o0&1F|5lN1lv9pMzRT)9B^evZ5S5$ER9kNc(5?r40D z;8m0SRktOECif95yVihoP3patNCz{U$9W<|&Svw&UB@F5yMtp|`gF+9jH^K|f&ES0 z*s$;^?O05Nsj{7)=L|tuuQOH`9`>Ne&o)0dh>`YWQGjIP)Cceewq>0Wn2rS+qnu)dw zkH(K?I*=DFq%dz^jeyjbimo{#xN4mi2!|}}8wQhmC&(Faq`kXZ&%vFTLdRz~8$N~d zw3nR5;p5-iUX)g^qeLtcHp9@49{gwEI69+2$xJH*YGcbe1Dki;Mc__NR(M9sE_T-* zAp*HL2t<3FP&;H9iYMDnop~*%XxMK(xD?ehMnK!&bPsz{gUHAI#f?wF>s1 z9|XOKNSVjpbC07Y7O{f|cS?clT~WYd$Kq<0Q~_@`D3s~|3N#MV$(0s&&VGnlQ_yq& zw)60+)=8YF+m~TiwZ%Jk<7tL$cGEnDYZ15IJNI@puEs=`#AV&~#O&w7Vq_wml`PFh z@&veRR)l&|8^X6)QrookqT3$N8%BG&sW9-a-`(QlR6hi(YvG1$6tA>zDf#J^Lj1)< z@@tG_#H0nBpd=EP7*n+YzlTT8&3>P4&(3o2ezJ&n-u@Abv&oCNbvYom6TUICwH9y) zJ1VjM5u0$2$FxzgHsz~wc%gRcqrH!E8gZd9a`G5`^UqxL@ATNe#bIV0%=8ivQ>tG- zYh%e>A;>ZoDp-CTQ?T(0|fLUtz=$WnZ+3;nejn3ZF{^=rSuT(x) zZSzB1U&74sSEBklMJ7U7_Lp}D~s{42e z8>AJJ9GGfrD|tLRX-`KoYupH5(dl9w6ymk2(ynK`_Ygs7lV>hP@wT*uMcL}U*l4S| z%$0P5*W$C8c-xz}TKIBxk!Mxaa(lX4@|jqz2Rj8RM<1FqN8vu!Opz*7hx22(V6g1t z|A@8UJ!}w%*>lebrl8H~R{rHX>x<3TI~F=Unj4s1lV4_8Fiwf{c<}|-{%V=&bSJfM zttpVF-!5YV$H1~{#e`>)A;pfQ<_PsX~2^$CWm-cUF$8nl3jB!-Q zRFoVTJAr zB5`XhbSP61>$niFjl{~Xuf5fm(N7<^k}6NdEqqoiwiM>=C-8xUM z80^)?RuS{^en5hdWMj*m$rWQinRxo zG$?dRrnBT2C`m_h8iY$Kea(Td?_XZNwebtPct?K#q_dB_HCK^IvlUT_>|I3tNL?xI z$@__br@jH#j0pMP<7$#vS?#g-%6;O4;2JZpMIAX^r>3k@s4vpXCb0{yIFGo&7W?IT z#!X!*eZ!>8(l#CQfnGduJ}ZR9>W(z4^UN-`2eU9XTaB}CA{?E6bp87=cU8mLY87e8 z)Y!&P0`edHR0KB)?bk(LdCjDTn;IH6X4;P#bDJ)78-A16wCY^CLu9F8c6D0v#*fqj z`Mjn?*`=4acH{+??|j=|nykn$9joTm?P4NI8(o3>ir)IJAXUNAeq4esqKFK+vzuOf z*bjSY^9)+Fz1*um7S)W1vpvl**{`u=_fFRBF(tQ1S2xJN#)u=BzN{NP)f9;vDN69N z6p53JFl7&qB)mNY8qC?|_$h}!b)87d9=Vu^f4#ifA1ODmNLtdu_{P$k z?K}suRF?MW`tK;I`C7NqG~Zp19LUx8`cT+GvDVEYg&hlpiWYhBB9?ak0->0lg4E7N z8DeV_d>BZSKDMfgg|C{qdWsQa*+{P-Rm;NHF-zY3I=^XXT)2{0uu?bgq%%Yc@mOsg zb~I(X98eWmcGi`pV{#!}_r=cA-nIgK30wikjZun_V-x<{u?eeNX0H_&d~rc3_)$2` z_J|0vFT2%3%Ik~E+C|dbH2E`Ow`Xj`J*^(S@sB#2jsYIau^2Of=S#?3WKAt<5qtMg z!=%GK4;AsCN1@rBc;tAtUcg)G(RDGi52+T)dKOncZMr*nTZnfoJ+E>&8fSMykySrN zgr!8F!D-=xS(o_5C)Zo>1BlPNeWqR?Rukyjd4{xc`&|RF)O)K{JND{S1BxDo3pQM2 zb(Q`zbZzvk5u#*3w3P@Qc{d5g4qt(y+Z6YHaoB(h!Jv3=V!VE!wt%oCZ)_F38!^x( z9!kurbp!5-#}NMg!>xwQlZ-?u9XLo{wOB7ruPM3f66q(y$sPtHHVGr$w7V@stME-7 zWZPXaJrP$K&hTx;uUyUHVvja}hO^6ia$he)va~Xb#qRTpv11pRXdn_-5W2bd@sNNm zT4pG%1wE*Sj>vxfeR5HXofwHrsdCG+U3@{(o~r!r9*&!7E0QXdPx@@j>+zwYzVC8( zYf2T0!Gfs#xKAl}dLd>%hyaz$Y!uLACj$iATzY zy68F?sQe^cTVSMO%hBhGY9Y+Tu4t|}?eJCyOs?qe@cEHdhZXc^j|C$`_YJP_I{jHvEWFxWpU3Y5;6xY%PM`xKb9tr%q+Dip zhiwk32yW6<;oi8t*So$xuk>}aJ74O?x5kPCuy+QK@u(AC504==ZHcuv*RF2nl}tKD zJLx)*=7X1~kBHb|F_ky_6A2{rXU`q2?2ST`$xEsE%7S~z#v9#RXJJ0g;JyPATLcx( z5%vH)!M0aNw$E!C8gNizFiqcDLpeMgCRckljgT!Wb4iQw_vTj~eFo*w?j-|C*WPv; zu)%y*xqd$ZV5_(d+t4F$V)ItT*2hEe6yS2^k%m!oRxIY5 zhGJ|%CvwNvZEu!Ls4X4+nMD!STM^rs{714P`*dUbbAh5anHD?=yla!^_GQj@fxN@C zIVdO&SN?4GmOMbrqJ1a`(mu@7baLuGm`_w&?I2inrVRTxH3M72d|)4xFG7<7|5Q0C zzdhi&EGZ(Kjzih3!&eYC>)ROI(h9g^X&?Um@v!r5Wn2@^TVWl-nVP_^v~c{-C#9pq-zEujAu+Om%+-~Bcl3!HZ_8fP>dn7viX!9&$ zMlf+Gm8~UTqYqDe$P<&-&xi zvBoQ_U25U%geoY79U-1b*q#h=SOG-j!g(NDe#8dmqpsw8?H=dt(<+eMw+%osD3Mil zmCqS%Tkl+;Hqy?ZBeF|r+)R0=mpy3IrJ(o<2D=Ddh%MiM#8=g9v7s<(MRU20OVSz( z3mM75)?=%|?%9FViclsd#!|Vzbv=>1hYkVfR+T{zya-Bwyr#HgY>HM0XN?`YfA%>y zVfFp2MEd#kDlKy<&iOFT@79{0pG*xml>@TdjsqaON%cfy04L28CE!(n1d4OCGpMB} zY&I`;OYpU1VvkwEjUM)69nOf+UF6lMNLm$gM7M-wq4y2JMzMXc9cZwM0EB@|zd!Y_ zh(SeIt#M)q^{VlD+(35R4V|DcPK_NuQ$zC)sq9G8^RqQhEHLT6)>-$1a#C{JeZ_s8 z#H-c>ePsi)Mul)TbHO&Sv|K;KfQPW!R9a+n9CSGn7ESUHgI%Eg3SkCUAt}mcrLE_t zNn~ZC{Sl*aciJJfQ^9vb&9ggV7*O5Ei7)>fQhvz@#d*O~ahg6wLpEl2b~(7D0apIaPC07(U^DaoD6% zij7x6IWkpMo8duffai+%+B><1R4*kWlp zR*<(=6cbcBdCi1=Y(sL&KGeDyPRz2Ic>@jwf0g%4ByoKoH65`xm*1|!+e zSEF$5;P~rDegR^}S*szYasx=$^v82dPr#uEDvUcI!~hHq+*MzX)N)aUOR*^-B^J~} ztPx&{o~mh_wa~I|AwQ?0zJuOK7;w@XW1V#0oK!l|7!I^yT}!Bsd&d@31ZvT~cNsiM z=}qMIh`f8RrVywm@v-ZM6IVx686E)(75Cv~KA)yXh6qv9A`in7Q3I z-xrmlz;I!nF?^Y$NY+!uk_yI~$oVh62Fu@!8ei4zxe4{tg4{{9>5kmUE?!;lyDk>-#sRpaVa0 zjg12LpXLS)sDL`OyT1czklkD0xI3kJ`}UY4@=t{?ea}uBbJ7Jpa1p>Z_%sNf^eZq0 zhPrMdwO5PZaidG2bRgAOHmtrWnRPP*ohaL4^rioPT!sZAnwz`^vT2rIJW@Nj-KsGWH(Vrx
1v=)$_m8@_b;Ha7C0a==HUE3TU<+>)Q~de6nwS>KOA1T6szW0`Oq zrXTXxAhVf77bS0xwe4JP|9H`&8t}v@(tfm%m^{P4maROb5KcWmAR$@pz$pteng7df z)N!`H329qXoVZ9e#$i!5;3ahrPIL*Nn@hPlddA{?m&lp$?x#C1VRhYqt)h<-SVb=X zk-SczOK4|UpVm=fB&G8>Pdwny{qDUU>|P}cw0(3a7@le63J97GHipk-bUv&FRk6dd zY(N1}jdDtA9E8drYN=`3*xS2AYzMDlE=Y0}DDUIk)nVYQE|LeJk-g~3g(%5fq7RSNfz^%vCCMhKJYV|4dlkvgIc2PA%hJ?tn(DV8E=124=YY7j|D$pa{=KA8oYOhsbBg6zoVUAYC#NFR5=bM?3G45{1dG}d0bpF5 znyXCUH6fVR8rFJy#UE{!B7lW{QgO;~%W(G!Y=fI(eyCtR2g*QnD;^YpR*Hh+pLmc_ zl?k%ZLAi81NQcWiKT93Vc?aTZ-4f0(d=H8=m!*)PzaP4^NDaQz6=HuJ6tB+soxJyM zEQShp8V>mu*VF(BEYcaYpK%D=_U9C9Q4KZNKRNsENw5`ub)sxC*d`cM&orNa`CKnH zbO#Ax8)0$^=1vBHpA{o{w+KIm=v4OMTn!6{DIrY{et&h0g;Ux@byLOOJncJa7l*wh z4c;UGITzAEPeWzDJ%UpIkGb~_YHI!Z#Upa`a8&ew$3|5XiZlfQ>0$vw6;K4JN(o3) z5D)?Z;nDIr)xkJ18!5ETMKfGCgz2!Z>=?>qDUW`1-3dheaN`wu4$ zJ3D(nd#&}X^;w^_7J5KfMm$Pla=}C#nu4*o{*R*ibiCGwt9a-yTv!w*InAO^OUw>z zqL5EXLKpTHdPS)tHD<~j?6>WV9&SPhcH9I9jQ`>DF?aJK0O18>-kmgsp4{*pnEMx+ zlrNaoY~oV^YBA}OgjOs1pnrXo{;=pwH4c#@7I1_ zLT=SH;9edL0>@w`%>3>f3Rf*vxlzLx54GF^aoYF$D|bbeC0neYY>KLf8$5gxSkvgY z#tw+hBQ$5MSdex<-0hVOwM8QDNrSn`{T+_Lw*)%^@L5$JKIt1fMKlg;zD%Fq>SY{e z4JW0IpR<4-MB@&FO0WB}0wF?kx)qn8N8!TtC=`#7)+JP6>Tn zNqGs`wo@G^)CFhIkcwcCskFfWKk1dw#dMA=ZH!J#jOfVDF_vqCR%9IZHFM2$xsg-8 z6{5OJxbztJ+3&o9e`NGj^qI91@&l(2WS@hJAk19#K9#O}uE{dFFUhhh2Sp%t7Q&|p z($ZVfL!3eknTy2EeEYjm16Ff{CkN(EO31an$Y_`d_Iz0wElXv^pKhbPifB_6_^ZFyHYV89RkqEJ+owcn`YMuK5&lMAvPV|EzmNc#0J9G zG5UcF?4*(V>~-hDRH#|l)JtPIh>Cd%4gPP*en;pQhn(lrD+MnnbRczye#Z-8%K2!B zOa6+I#PKfc)NauVs~Sk1Cd@wH1xc2Pazh%Bxu6K2MC^@Ie)loUPG?K4+c}83E{Sxm2E9So`65O=!ZD0bcd4?@LuCstdn}fjwls7dHr6 z+c2z^o>($wZe+dj2vWh6j)l6YKK8|}`*vstsR-p(G6Xa=o!@LJvF^0;T_JMN%!$@*2l%`Je}p#|jVliPJ- zc|mCY@(;B*v=4|-h4P6syCJKwMWk+RvO#|O3})MmV&082NEw)^12uX(xA9pGA_j5v)<4_N(`0hBkIV>MEoVZ&kIV91(;&kh*Hv zLG%Zt#9?NnpGujbQ_Q`UCnEpZJQI9h3GD)6m}}`$DT)Q}L`lmS;(S7LE7a)4ETbm# z_gr__SxCY^a653}V0qKxWuC>?=L<{eTK zpZ_{{8)wyGHSO$fqgO@-P9mZSa5UN(w|W4+jKw{Hr%g80Hv9`tt``DWb*FK^(!0Qx z+K(X|LlDcR$tTFt{VDzZ#ZcpA9!T$l@OhP38NYkUAp77ETM=Nk$Iz$@1_g%d5{N;9fE{VwV5=A&t!LG2fjsxoF{cl#%I9No>`;|2oDEXJIpol%67CX^(cc~Qy;fOx$Xf)@&whbqgG&DP?U ztrALxZY$r(qTyB#*NH$tzm*PLH4dGL%Rh*#a6y$j9;;*o{S8UDDx5v=$q9WBek;?* zY#Gz96c5Ha7mp@9`gc1d`F>_~cgGH90}|lw!AGDZ7Cfco0}RsUCS0YL4ia)RztVlo zLwMX(izCo2XrV|7azB7CHuRAzF^shgJL5*1Ou$wZ%3|`}yj9!>^F;ZX341HFaD#=y zJ3%n+r73jkgB!a%a5Fd`ix^O|xGY2*om#;8ljbJApU5}KGKf#xAyp!Z1-Gw-_rVn- z8vFod>unYI_KrivTOlfze$mi3_KHR^lsRks1c(OwrOKz!WUB;#bEPo^fK(giWS6#X z(589;%(Cnjy#q)0#FV=2y9P>bSo|wpH%Hb@_R$@lgv^h=j`IxEQwIaIeqgTO%H1@7 z0T>Eo=Bs{N7Wlu=7&E9>Qmin(t&2E5aVX3UuhxCJz7bXXS{gg|cquEcl@X{$W!AkH zXJLY_(-%NoGtU!t78{G`(Wc&t$5k^}s#M>@>)TZ6A4A&~J-`RH?^yiSFjcn);3{s| zyFaDsPJ(Os#v86qW;B;d_5O;VQBT?ILf%~W+~_)!%>O0#=?-8lwmr&}l@ExK&E33T zV>A)Ivs}dpsWu@rnRTnk^5u?HRMKP?*||2?X%30;KYW zpvGRONLwH_;he$C4W-(TlT$&p{?wOL)ba;~v(lSeyiNgw;PnwOb=V_AtC$rCWa{YV zz4o~;dDixu2H*RvG=eh@1B^R23%UiOz{nZ+F#8G8b_~$7POczINM^9^N0 zRu}MZPsjwFnyY)C^B+%MOKS<$=&9uh)JoWXC)lNGRH#fkm*o^T)h(5)9dZa8x;xvh zV|>Dbf5Yd$8J%AGTf#s<*nqI{0JUdy&nZQO%apb-a)=zW^PuhA4SJ__kiyY_!u6`w zrJ!2pJ4xrmJSC)wn>uiG$?`sBv}lL-7AL|uKI%+Y@>cMC&PtGM=57)JH=82iZ4t{s`uJXEJST}r8 z{LwAeAfNCly+9sP_lRSa@B#GV8GW+WwdCOOtf9j{F46}c3w6G5JsgN7qzkqwUa?v2 zKv`}l1#;<83@$^vk)*ptg2}J}Fx?4&fI3yIr^YJp`l2G1JdSpbj_u91_L4_fV7|7E zz78yBwN14O?V=uc*qg>jT3LauXs@0abaUUV?&FB;yy2I71^tju={Wi1qryil4O8$Y ziCWlOUdx)A65E^k!Q3X`Pl#8Z?>-B^x4nu7(eeE3Z+}&p0krP-`FE!*6V6$>2uG=G z<;VJzk)Pg|9X0Mv2CF;vWRYEbL@|Ey-@g+E%>epPqWCAIO0#%lH)=)_?KcHN&fi`O z*W1#obnm~w$R8J*(vpOx+9<0*{*&KvN(Xa9ZaPVRZuC*GIP{>*`dm#`9EcR{ZTGlX z^e^S@MQ5CYIPCyPE`V&TlOtF|5yi@-a1Ds#R4(M9gTxMqmqY2a%SQYnkihwcgYJGG zehY(ILWdAo04V3RQ-5yViNQ(lP#*ajKer_T-jF7F{yI(#Ipl(fXn-i>u1HN-fc-xE z#txf=bG^yZuT7O8ZEreA5w=F0frX)WC8<|tO1D9(3<0QfVqfk<T*YgB`pW*-0!?|Wu^UuYxuz9W??sB08V1&&U(E5XrxL+)x1eF1QH z0WktHVJq?P;2DX3AHK|lr!C2G7eI0|CYC+=q~|g!%qpB-9TgeC&dNLo^*h(2U z(B52rw>=_Nbhuu8V|E8%Mz^dzXpTAxRGwwSiXVLfZoufjZUB-YOptg5SR~dR3jU4n zgCDfs3j|Gg{C|^L;56Zp{X4z{AKK0dt-J705JK0&<9NC-tO7^E!{10c`1GH|9r*Bn z<5I`VcS-4VH?^Jm%_RrFVGD@A`4M++3Y{_G@jv;qu$$d35^h+YvHKoG0knc21SO#lB2dC7lL=9dhFrp3NLZ?i5c>Zq4PPy?k_2f6uc&95h= z`D6oXBdMony7eW0$8k@7%WQE^B$8g-$eLp11di9$G-Ge#r@w>-Mz(BD=K=gYT)mf_@15`>$CLpzDbKfTmw`POqH7m0(jV9whaq0&hO)pBZ|M|-|BgV)yXQjQ*1u-6jAiPQ zd+IH=4p+`ii=7PJwBpS#_>=wHfj(+=^ZhQ}SNukQ>b&X1D{fIJo z)H0P(uv`)u3;ar5VF|E7O_mmAdq>zbaP3qi@Li3=%FIX3yWU6svzBK0$ zJ;KbSmh-HneC89MzMM!Z+c-fFY$leYs`kG??HvbVYsfZL zzl2^s8{A-HF*acueC7s&8sZ;mw8Er&9y6F5^I%3Btk0eu{S`a6{Ii@gN?`%SHzM2< zqrs2q9PKWR>%kIh*@(`YQ1TO_l-TzcwS&|@3!|Mypo=_w2w{VF`)vo^Gokuwf0k!Z zZMd6NU)EcRJvLvDbUYB%0InvqZdEuxt;buAKdf^h>+7VOM39f=Z7cCwh z4dY}MH5tDXZs_BJ#6B&Q)?JG$Yl*}xz1@wvu>`tIHoIS5y2Pd?VSH;M(wRR5ZpG51 zgu8J3%iHZ|r#3eqw!MQVwjF@)38(CDjdnVH5@8$KvYye89aEPuv=J-1iiUPfTo=2y zykjn8z0Vv$yd2lzQgXic6`Pmcef$oyuKz5xo{B5I(X|>HOiqGEXP+~LOHArdoNVllnb(xy97t$0I^D?TGxUGH{v#yBH*L4;404Hi8)~(T(Em-UDdU^SxIzOli3$i;Nss6W&JT&Mr0nSwE`} zZnTJiy>2^c@p$&!Sk{YKwe7Dy3l2Z*g`R#iH?6zzzL2A)Hi)U$pBxN+R&-!_6+Nun z(F^|4!h54;X_GbaDJMTNpa!|L-Zc)4jk)sEOy+O|-3k%68=m48HG7p_&CED>rl+^L zp|ok=mG40gO82$(I$Lume^{!!H0CkuggG`BSdg$^V{2(7S{3f4V@k=yu7b^BOi)TX znsVw{z98KT3mRl>@N_<`)C^sHVxe8OFt+VCi9C=3h_q-b(X6N_7)lYHS{%A z34`JIjTE>U=MPI$gQ2n*6R~3k?v1Ll=4_aWcwC+9txLdlUNZH1ZR8g{+o?@jh zHP0%+%iRl3N+#dE8AYbl1l2BuCbu#LPK~0+W<}dUv%S?j#BCCyHVMCk9T-sS6W@%U zNVKTF{RB0fC99;qg<5!#f+oVV-o?C=EI6JIfuFg0;q-BSr*Mzgf#emfIJ6_NOl$nq zSU5%Ikee<32>FiY=__f|&sS0cXW$omFQl3q&DtN$ zS|829%fOuT@K=v3&rVRc%Kl6U5e*7P%OBq+F;JD1t)~^6dGD>BBy#xR550+|mIay1 z@qt4TiHAkvtP`Qjk7(+~%~HVu(=TS?{Vwjj9^(-x`8R9xS@Y{tV#b()gK#sy`cF#u zyoiGpC|EGy1s%X1+_~z8d+0c~lAw6&sF(7fqSf3DhIz!%BX3DfnLWY=ZRsLeVgm|w zde-h|rXQ))_-ouQ|QTSz1_=eQIUmvB`3PrEZ$m3tG}baMZNxJ(}9 zrhF;>5sDu~-<%k7MObFn_^i&s&kXuDq5s^1af(|X1?Hpa@4D9j=gZG>6R%YF)naH~ zdOz7c>tH$kNz0Sgs|tSy>&ZTfc$OODv@)c0KdY=?Y#hV1s3>wTTziE3(38OILRiS3 zO3hukb7LtYxajr-mXaGjvbdfvhjb>;=?hv$d<6<=>0Y6Z6bbeAbAbe06&C$UP&;R$ zax-hhAj+d*bv3*tzH@#uXi16DAjP z(+1!UnksX1dqGv0Sh#NEl?P)WlOC@5@qkZr`ZmshFH{Pf-_~(3HA% zaW%v$6dmhHgavo%KPVkFL8@KStGZJE@T7%CSHZ|(0ow5~Xp&y6y6NV-ZT}JGVB{G4 z1i|=hy?|D`LcJr_SXC$;IyyZc&BIN&H&9a6My$l}^YN=Ft%q+GvZI&Cb~DWy%P6ex zCgbWR*_LFMg3LwTTD4$Ze@RX??L-YK>|+Qz@9;U#Q!7)y2`!DWw#RtiLhpe4Mih)iO&@X z${6r7I)RuoqyHJ!A#d<@!C3tagH?@NMghdzR~9HYEd<(ns!+VV>-8hg8eHb`d~ zthBS@0bNU(oc_wpgky|g4}&hJR@$0DtuL}mA2jbYDzj26{b27W*7JG+ZPCsjV5!rB z3JT}_YyLGYC?uq_c)d%61-$#N9KlIz7rPTxA6!Sqzk^Z4o=D=J9V7e24S%-z0X#F1 zJW@k3M*i&3B;q}Vxf^=58gFFn_4ce6SE@=??_a7c)cP@ur4;g7Y4imhm2Vl$b`)kr zvlyB=<&g5&)mw&Z;Fl$s0>FyQn;yS-+eKB%j9{)UV=Ah0!JS3H$lpANE@%bC zN6x7i(Hhyp-ZCGN2!*Ag6Kq4wMb3z&s9|Ra)TrUcP{I$1DcNI%6vx2|p zc{#1gWwv>xQ!Q?&ca(^Jlq{K5ywf6zTQp`0j#BK>l+Z+RU8L_sZ>XL4ag!-ndJ|hC%ARd=6LZ?d^#czy<(wVK$za^3v z+@lUox2~(1&YSkN7^Kd`u?c1wQn*4k*NTd0$^08`)2= zn>-;fMy6;dajDOwFE0(R4W|h-Xg)*kT-H^5p58*%gqb}izNSoIb#v~3&%~!E^yfJ3 zevo}0gUt-t3G`;ef>(F0x_6w=VLR4#wevFg{OZSewqL%<&pW$=$VroI=5RLD;$=3Y z`gw-zdt;NjTSBA_un*9OGmgCN)Gsz(;%`_=#XjQR#Kx5vIqG8buI3imLzSpHrxwyryXn2J=dB(@d^#Wf z#Df_$zUa}ORRlqu+-F=CZL6fSEe3vGl%RUA)!B0uPdi+qt>R5Ds zRr!_rQc*@{_|l52`fc)nOJCup7r!9=>*xZBUmlnA6!%SwXyinpMDXdpE}^-bBPSy2 zNCQN6x$Wt(UrWKB8I4gUaync6)9?k}{ANmx8nR0f;nz5cw7}OejO!$V*S=7jzFa)r zP@f$aS!!{EBw9eI8rkT&Sv*&~iVT&wfmIanBXgB0%6x0}=#ccd$O{t1`7%Q?u1Cog zEm3-AdpX`~0jV;%q}-TQ)^r1ZT-#WnQ;L!TXjK ztfGv5obP9N8zT(@D@ONqMP`%dej!8s$>~(3!V_I-Y@f9CYE?wOwA&-W*BV+V%gnKs zoY}3UbT4ZOSF2yN!l{iXO7+NUAiUmSDxxgt&`2aE(nSVgxkCCIe(3T?T5n7v=8p(ik!VgwL05@H< z8Y%ggioL`cU)tmG5`^EG%%aeGYTn1fU^iyB%nGkADHllJ_%r-4>L=hC9gP~l;Qjoy%-`?A8TSr^yv`3w%jYNqq!ddNS% zGGwELZ_vHN`=F*?cXL5?qu&nY?R^w=5@$Oo!4V=oAty_Xcf^smb2hh+)nD9BcI;Iu zz2qQKr9P4_@7WvqM6|rGPT$u&L@;*IGc)r*<4l!g`BqbdjZbe~Mf+zx{?cvP+|1{! zCp(6L(!dMQ1o!P?lD9g;ri=(xjlKA(jc1;kR|Az<8m5gbTcaxXvRF)0)fM_}6P6yU zRyCfc%8!>mp;C9n$_w9)ocx8urExHt#?h1(KOdKvq(+x`SY0-G5NHLaSTK(4Y)`({ zOx#`=cd;^w6&2i4Div(NL3xNU9={YAAvWz?(Z^Op9>r4iRE&J_np)ReL4n;&@3BS# z-Gi{H==+pEXZfXuuYRLo!m0DPFJFWFB#0LQiNnxB19=^Dxg6sRs{&WK(6v7{m+}?U z9VUP2*)oacseiL$zEn+)%8wLC_-k}I6nKV)C;92Aa#v1ZTbx|tnYz!YDef-qN65t} z{)gUFy(+0-V<&Vg4EN@HhqkPcR5o!=E6H7niWGB>Y&Sn2?AiJ{QE~ znMig5cw|utfQu=9cG0Q0MV6it<-JBY+Rdrwe6pAYyE`<;Dr-5*0R=ftU^D>rrFCiydL1MTtgr^HMA8_R-;Fp zKc6^+yPD?HUI*b>UMTD-MBAL_u1dsG>htHdeUtG$lTASl?>ixC<*{~f`Mo0~yxkBv zS=xLJ#>Q(fH^TBdepQTn;z|D`C9VM)F-wCVEL4t3=iG!fx5Yyv^$y$@(o2i$F@=LA-+yAMA<0e~@$2wW|*A{y3ejfVfA6V{{HKrX`I!oKrD6C;_v-ta__Z zMu8>Idd4WVP;NxU7lvLVjPDN-bT{)+_asg;R!UPNdDhAghfE*-T03=-a_d;wx(Z8+ zOhu8aRqfDwA~cH&b#AUrF&Nie@I5x0n8|D!0fqU#a^g|U&^Z!r-^|^ zz!;w#{LZf}GMiDjC^fziHORhh9F_lkra^A175yOqfxJlgh>0;dpdH;Z3axv&cNQ-t z5OLSbZOCTL4Fn%HtrJDhwmDX-XPtb0GqwQP0n?)Sh1OMwW?vhwy5r$u!nB@JMTmF_ zEDteT*Q-UBCE8^6{=9O1)llr-E(hI#-h;gYV9GBeslo2Xu+$lz3{%fH*RoChPV<#~ z(I33=9hWHG6$q=HT7_&>pmQh1bJCz=qrbTpA@K2|oPwTxCW@ptXmaH^kZF=yW_vz2Gw9;gj94^b>C zaM9+lO>3bV_+XCg{xE}%tY?guAwUenE2#FN6>pTt3s*>eE*w6$cgPZdSggU6L|Jt+ z;g3+7TwT@8-4iv9&aYLlYfbvk#5ZiKNd4G01Spx67u+4Ze`BA>K^}YkO+57phO!H> zQ~htW{KhR|s(Jjg{O3=h-6tJb^AFRfXdh!cFAX9%+};;6mo|x>USWY2do&S#yB)BG zv}J+DuAMK;dSBFR8mlO+FqfL_<4ZNpi$q4G)!M!gf&{7oebwUP_|Ybx=xCTYC*MbZLs zcI2=WY5ir$0HbK~+zC}vx`Fqz`n}{-`|e{8FA))wuV*!#&XYE@n9hvce-8{+jqEcr zD)h^0n9WG2U^fep*vMjKS8o$9mNKaSZClg6(-Q}CF4T&c4(HAfrHw-bB0lG3_Sl@h zo+dibIsGEZ+`jififD_OpgZDBh4I;j!u4uYA$6QpwNE zC2@&}#ivd-F&IcIr=C(BXQ zaDiZX-R)JYRF4zG#F8*n9qjDY+K_pnS4Z|%#a25aqFKSzzW0+&!fks+%#=gzMCp&S8I-YR$}SqFo)$jE^Qnlj>7hDEo0!?hw`#J0_q}5#-?8=m zIQmj>-wT5w9{0`Bv(zF zg6((nZJU)x_4><2Dl;QuwoZz1nXBof(ucvlK+rrvtAtOU>(>@=CA#Ccy>)X0W7Pr9 zdk6)8gb6s*sNydJTbg6d1w&Dd1BI`3FJK8hRuG^FayLKxJ&)sb{r$O;AFg`;BWel^ z&nTASV7Ho)_L#VCvK#ri2Pcv{ z9~$2*r8ZV4sHVyy=e|5CL(6wvtpMuY5$TY^TFrl+IvsIDfndSctnI5vgxiVDz%qT6N_)wZnyro5Jc&)V_`}T*Z~WXr@9w1tQIuh7PW+u zB#x+@mw6SE3z1vg+(q1p7CleXEs0&AmmR{hmo^J%+nD@6?jinIGFSD!HOT#mS>d2VVl-`_w+pFYr>7FvI-9^NlS2t> z@<+B4nJIV@6*i7>r56_IK5a;gi&WQpzqx;N^+cS;`OYp5pI>+IZ{jR;?hOC)2IY+QY&hQaaN;bxnP@;t$TkKR7RbV$&@OUhPzw(>LsodXE`SrkQ*|?R*TOVYc(36 zP9)pG6_%El;MrScvi$iht&Lkhwh=?=8y~`hiRHxZ2y}3^s6#*LFj3BOk2d;G7dRiO zeD)vW!+YI96;`pnQr4O!&@cOr2qecr9whjtGC#70FEC=JO%;p2_I5^xrAZq|%oz(g zS^HbQf_@``f=z6%*2a$0>9_bm3H>Nx)!0kZk2|2+U~pW8t5>9m$Lc8GA8LH zr&JuhD{!c3Zr_1dHC7Myik-^}Gv&BUi+Rj*o<+UhqVA^(J%RO_D3c3yIimP5?c_hU zp$Ri1ny_r%i`0-o+~EjZ&bVd(?F<`b%qa3rEQx4qRzIQhsC#FHQ~05b5c$|J)BDn4?T;+ns`l=%Ik3EAP2mmpbl95Q0K=x9 z3LJu;^edPb)ZR0L{M#f4!|)0#(Lvh0(xN-`!IkarS*L%6S!$Mv5A*m1vl5=LhnLa* z@I6%n6GPV~wV279(#7{-5ts3$hLPQ+>bjQ{R{%@B0{3!+8@^uAWt~MjFUTFK-Rp#s z#8>;~y0&jfDMvfiGsYz{nF2zdfV+j{dK?8_&(47@PxO@tdkp4Cbz1t{v;*D6X3d6@ zdOt5j!9T~PiQcUhrBE;?wO&&_5?mPaDl0f=wXk-z z72$4K!O&lbYMkP154oujp3V=~iIa8YRa;!R*?O#RK-`KvzVN=PU^ABg87upZ%@eBE(8;OxCU-^IOe*>6v8TIP8Z{MG;MW z_QuRIDuX;0_SPULaFb6!s3B2>_bPaAo3_LPy>eUMRLs`so0y$H`Mf*IKNI2{w{5x3kG?}tFjZL~ zIKkjmvBnTa99N1!{e4U(^guSdtRd>WNGs9z+LVK$RRSXr)moHi{%+b7V}H02ad3ZB?xKVGTVJhiD5rv z)!D&xzQp#9pk#V*PE^`z23xsK44<&5PsPV0a+O#Hvyw~~kB-nCjhx-qXJGsT z4mN)SlkYgXKlj%)V@xHq?>JKWm#5#n#(VU=k8U9Rwa2Qeyye=@H!YNcgwL;Bia}>n z#h~wMB&z!=-Cv6Kh@9#X46jnZlkN>q`Dh?m>mKQe2z%Q7mvU-l2AX4?ex&0r+PVW- z^1&@dd5K=WmNow(z9D1a07rX2L2fx0)_7&mv`6&HKF9HA>V)(*7nzcosK%e~a5z&S z7B!-2!(fxf>?ewtbFbpxVQpKqI%daFTbAs%GcPB`ZYQl( zYHgYqUsUtU@i3IOkReRWWe zx4B6~MJ4nA-X?SMjJrd%v3Mpqi$m8COP_yL^?vT`2p7MLYlZ19-Kf?eCyX=Z?2{Lp zwJkw{O}=! zHsj5PM$;ERgKp#Sa@)N<{}|RH)s_Qm3S*j;ZV+y5( zh|Kc3I(K7}993MJkpOrZ&99nYukx!8(NcXQuU&&+uIK)hAzAr+IEhA9uXRVh>#tD;44M$i}!%-P+ zPBO_ax@ynGak+Kd=z5Z|6%xiAWbZ%6dl#uJ-9n-$h0szQgk9o{P*C*%hcOEx#pxch zk@3&(0;5QE1TNzG{;v+QT`pU_w42p#9M zc9JV!ik_Wt6Sz9dWh}k!$9h*c6biHAa9c zvHxhn7kcyR2C{dZ(*OKUpZ;;z-bd~aEg{X&hf{x9@(ftF8PvE)ug0{sUqr1_01ir= zP7=8%hQWS%6MQ`QJ&ks=T0D%2T!^cVts#1@zMY}E{57xoU_lF(-AZN?uRi8rX(MHQ zDrE(KUsU|DI5MrDYe2JO>ts@U5QmoY2j4cXaz(Nu>IKq-e?vCfbN&9`mz4T(7BKv=O4z+5|hXmUH_DhxsoOVTN{i#SEl@?U#wrsZyWv{ z&uHPrX~E^Wrl0NN);nI7G3pDL9Xgmk0EW_byaa*h>Ko28+*AcT$eOpc0)6x*?W0y{ z%qTglZ1PfHnU3Y6K1-Ls?BF}glpy4R`x8%iwO`H`SVefkum;7o?PX^zBk%i~NO zC3dRKD?Sk}mQ(5%OHY2CNqx}N{n>4n;E9x~uh|=M;~4x|V`8LO0%se&?_A^s#zVt; zC@hAOS-thL*h!=L06Uh{=Pu2`xAS>%V^YVv<`>tZt55#H&hoXMUjIi#8wB(xtmF$twW~0USquUiEXUV)8e&fI$N+a6LWj6zKZXdlVk~$*0 zE!e!#gmJd>>rSgfJ?3$kD75{|iQ_>A3v}^Cqh;3qw20h!|IcAl{7wez-}g#lebq2V zlrd6lW9ki6V+)#MQbjd2YWAwpJk#}bqjkxJ4{Kc%OlwUc)%m9RZO;)|gNs+*rwp#5 zx>_^YMzovknC|(iiRDZ{fRgQ_H^0JsA3pIydPgUsH%5hK9{Ns$d?(D1GGV#;&alC_ zU~hzkp3OQx?w%^|Ijhe0R>{AY;2r~PN7o;0r)pb?ntw%=s7V>ND&34E^Cc6&))7c@PL}DqeYCzo77vMHQp9< z%Ri@}ZR>6{H`B}Adqw$3PeP05P(Tg^L%13h+in_s5buB~XG~X8?V;HyGKEANd;JT; zont_YI!D&hQTqjnO<(v%(|pU07xR%MSE;>SVXsW_095uQWO`QgthMsjiI+wEn``3W zQGwS5zGa=uiuD{xdM<&ew%Xtu+ZN`Y)s@N<6_`*Pf0vx28;R~@sM zvsuBf#tZi03&};nFRB>Nc&{T@Uf=Kj3!`z%C^c;7bKcDO#-Ag-n(v?T!hQLqZ$xr% z`q;ydbA%n~Uf~|$!y5*2Vm}n$+G7BODl+ejgnK@~=Vy6G5AdVLTBD_o@oiGVmCKz% z3%{@rs71nx~r}HRtnVM%|3^;J|TN_RmFSw@)-}p;qCYpT`5sYQF3s$Am z`+SKWKNI)gD&B~%g$?J3nvaCw*TwE-5fZhmKuA9n(0TD6u~)EPju;qA1M!Wjy-5%! zh~rU9`ou0rj5b0ILB|rX;rk+6`|)nYLEDK_&2%cw-p6HDYeCXbt#&_=RXn~wrjVw> zxGMA2v)x#h*ma?@At_eZrEHO?u!5V%qpI&#O^8NIs;0J}EKhQB0*RAaFfZ47LOY^$ zeX)zL;M>W{iX&$3?TX3}ypAI4GE_U)x&x_v_ZYVU(4m<;71R79YRv7CH#v5> zhHcSEjH!2lKD=0XdJlYf=d8IyZEEcO)vA#Nd`mQG4ViqElrUMeT&lB7fV~C^sG)w zIKvYv+-6T(CBgxrFOc@j_7WvQ*cWe>@Q&qItpXP*p^}zNUYQnIK#sGH-gy_+agZ-I z%M9h{tKwUau#THHF1CmkTkcVQOF@~IhytR?QPX-ujjqqeq#YJhanpYlO&L@opwK;7 zY5+EFDGX{6(eI+D6E%*%g=kQ$!!nQITL>5ue_iYYM;#e5-RPU|r^n)8Cp)Wx3FYSo zKWW6hiVGP(%Dz;9r7BT6*4}(ezN^j2A6L*JZMY%Q75Bsl>Cb|^_NI13Cn9@8wv*Sm z+HB$VN?e@xqL9YMFL@&rrAGzpi*_k3g@}U^W74l|U>%xsul-=B(KnpG#uU`X91QD- zGGT=WdrV2Q(RK4!$bU2$dPQWzDjo7LNOuI=#p@3#9^^XI6ToajXW3Ol&ablZ(6GF& zB|OC^UPi%`Gd|%I%~mz{8NrL+51x4ZQmDHeOk(#&KPVjMXb)We+rKFp^{<8nMFnaOa{TOc`HLd9Vv&2rWMS=SFE90o(}0p9@y0T(SyXRv z-Cj~YovctN89g6k)?tZm^NI7jIb@X>EB20w{u;KRvZY}hFIPH!I?+rlA#2*#O$08M zz}*4$m0>n3-28c2thhJRTRcL#Cx1oba|Fc?J8_@ zciC86CCo(>X19ZOz8#DssXgJHYbvbcwU;rZ%d0ITW=lp{(@ZVwyk22+>)X}mN%IjM z<)(Olf6bSg^v%AVm8744@nyIHdyPyJ7UY3OSDTxF8dzLFdiD!%trE;qPZe zzhc3h2$y;kKL*&Z0!nr;NwkbW$~tJ3&T&c!XA-dU*RrdqEg|U$GxkrV;ZuvjWabJf8ys6d zo`%!%eUQ?`2cR-@WQDVo`^0n2f-3};=vJ(@`td8`RblO6)2~gg>%_79rpm%S zOfET13{_}-1Ie(L!N;MgjWcKCjpH_zbljuu30)bf*BOen>1|g+CkFE6R;&B~-yF18 zb6@;6l~O3avAyfLgtP}?Nj5lbc8JnV-+Hugrk)aC6fhJ-4QgO{4an~X7 zrg+s1gFB@*jHbHAUt4Rh>-2u1$=AOA6*#R+n@6&_NcGzOZQ2@}7o~R6mx*0D?y^z0 zX-6k&q)<)Fuwat6>tAYxhY^2JneN*fKe zlUYG{w3y>EbQSOJV{nY&OYmEYr)!=ck#*3Vy4UZ~w;)IC^S;WDLtGyb??-J|Z8kP* z`%Yj@bdV+tKrS>2e!0_#84LQ~c~l1Q?)Pjek-{Arlngenj9}~hGp1l%R=0Md#fiP~ zk8hzYln<|`a>I$hI{vTf&NQm2Y}@w{J*XvWi5^i=ViQ0VL21Meq9r1s6_h3-0TqG@ z1d&eKpq5gI^nG6?1QpTHD1C?u(gy@02qDCh&d?SF2qYxjxv4YGt8>S@_shBCjr-Q8 zFv3XoUOQ{ewdR`t-@mTn>eiyx*IUk(EM>ZhBj^HEM);C2vSgmn6Ii};G`BUw%X%(3 zUG9$>?>TE>dccV7ILCjzO-O3c{96WHp4{!T%LJVnQt3T5^OZwN+#@MEsysA*#LlNL zfH6~WL`|6IvlMnRXfB;NT(|28uawc$HR*m%=Pc1$KKc?GTO{X3pAKV$Pihy7luv4p z`Sb`wL?%Q|w-WsY+ppfa*K^LUxIbuX1$t~cPR1C$uV|9t_2i0*)8d#J)G=ht$W|Nr zxU4_kq^{YtxmTb3b6U2=eT!&&^Ohmw-Re#y38>rBGL*dY_b>Bs_jOIy9K5%f=GZO! zqrvU6%Aor^&XSnVn!1MBmY^QI`AXyThLc%UrNB{Q6%83ay$(PR7wWzh8BCYfV>7sw0mjEd+{ZXv?1T*wyDq5ptlPjWF!^6cx=ocN$RD%Md{$jm3k8Rg^6ie zFUUaHc7i4WgXcjESdj7!UsY5n#SwIt^x&lzObUYvU1;qt$6FaZKmW*?*xA%U)gq}z z;m~Z637t=ye0zo))RZBV9%!0NiaAVUIo@wu`^}M60am{yYrYTiNWG;6qQ2?M@#54I z=ha%9?!f7Tx~gtfq@D2X3+a2JVs_BTcb}h>JgiS4dWDINViL-22E?cswUgL`%4CalBupzs6jZ?XH64^UbuYYnrPqUR0*jkSjT-PZ~8!X-CJC33H z4{DEKev-4&+CFJf{BdU_PZZy!I$E%kK7BHc-a0Fr+-etrkIpvIKABVeh4ZSpQwerd zy9Vb=nJSQj@DUVp$k()Xu&?#ImdqBEmgjKv!p$xNve47`hk*! zxHZaaqcEXXwJ6c6suA=acl$0Hr6A$5!024ep{8imz0U?<(G+Uc zSdp!3obqmE-ldyc?HX^oj@Q(vM4o&qOX(dlT2c+BT;P}KAKw`qe_%Z$>=i!az}nx< zr=6V@ZGyW&K9_X&cV5h z_61Yo)L*zQ&0V@q8=su|wRn}(JA>Hk9dmSz&&?X4tXIiNUj{>4GgTgXu@YOIsVfpL zr>LH9Y(533XXiT9L7eUD$!FMfZhQf=-6tFKv-&y*=PH?eN`dKp%;C&;eml0&W?#9v zB2b$N)r;*(i;k-Pcwy3+_hRWNI(Vb?boqaJAjhn-jP6>5VvkGd4Ix z-W!$B!$A9XG`mEFU}-c-Yuw26r4sV^BI%9S*cVL#ohQiD(8?6ndQ0Uq&81&9ODZYu z0;(2Ji%tClS*|7PpM)QJSo4En|18*=y{VA-V%gdIcD>EKlfvmEBdnI$v{eg+d%y9? zOZ-$I3gwl-bj0oxk66)r7P*;XuIG>9K~=IZFQKH8va3t&>{HB|I~NS>vEh%W=jZ3^ zuzi)h^hp<4`Ex`yOqAU~Aexs{rvVx`+X`h$kUb%*(uX#NGl?5>ljDWiEk51F&&B#n zU3S79iyJU4Y@p8=(wPzJv6!{L>bL*?Q8mb&mmi{?M-xGB|GEH`<1Fs*poblBddEu> z@MxT$E?z6ztB4aM)I^kX9`nD4Xd%)&mXOz-@yE}KM%an%t#|c25ZWcDVHOy~3V|c5 zE^b(Kq^Wd1A9ape8F7pP_~wO;vT2?GJ7@ii6coh0RIOK;$q(;v1^wX9u~nA*U@+eW z7o}C@{zkpU0Hq^1bV~^vKTr#}!zDl|HGCr~=t>zJW8$LpKYXp^wWOLTFh{z=5FoDW z-W*HC4UhXAsj*s_;+bcuir9sQ@zQ$b&}Pz$bU=$U_Jr(gXQ!AeUW&P0e@7-cd|HM) zCBxu8%dGl13h9-nc0WDk7dh-AK5G26=3G@|%)qudD7l0oJOCDm<9g}{;gh71Wyj4k4fwVh;;oYdv(P1(-KM%idf^Fq<~*6nzLnA%IN`y* zkxv#pBkxE;;mj$R(`wGyb`luS6KQY8>2Lv(1npht;UnQ~A;;&xKBzELw~h3S;=|f= zCF}{>tv`BX3VXrwVwJ#fnv(ep(q&K#{Mjmd|72{J{xyXWzDkRZaEzoO)I9I?_1
9hoTAq{7NKZ5BIww2)U(6o0T#bB3Fy-(j^)u#=lxPRrcc1d&1_?{Z{+$$34egTL z(mW*W9~x#&Kg~Ed^-wk7H@G@Pk~O4c>TBTRoEvZ{x@r$)%1?Be*8X5$plKngy)~Pl zMR6CHmqLICm_QXtq(e)j1lTR#&ge-5%h!b9J_zUc^fd8M-RP{GeoKVQ@|UUTpR` zhatUFpr~}CUOe$qLz;@V@(ab_+o@YRN5MOUTXR7!mN>5T!h)J=N)~jCa}s}I`^!^p z=&kup$ZuR5?CPK;v{);iG2f6o^IczJ0LF^*%8}|Fsj8MY&E>q%kq-qlj*v#uu#i5e zZew6R>_g`JutpIgN_kszf1{J?+L+7I@)RlSgat&3&9ZSg5@UF0ZVQ2aD9doka^SKrtrKSMV=~@Wz2&{w=X3v&5 z7mYJOsBPy{vXz<9;TjZ+~}vhi!;NaONGj z#OczqxS!7xfbxScA=&!d`h&>0m(UeCYW2gx7!9Shp>d4H^7<1Eie*900gY&jgjJ|}(&9}*>+~#6vloOn#xZcL9ABowo ze_HJ7=5NFQg%aJj&+Gm^nwE64>GZy}A(c)$-gJp{9&xQ&a#hF{GZj>hN7#uy(UM%e zB3=uBo?@q;LQ$nOOLpg9t)3Z62w08N9SnrytOFbi>BC4|6CMj5EFOKY>Nck{H#S5f z`?~vg^WVy*Xh#xyIACK=?41naJ2#ykUUK$mxXWkzOp1R%y{#ZM{5QjKX2ko33THjCSrngPgyQ zmV^S^Tex_uh>xbab&i!9`uq0}X1W{=9A3xprh9UTbt1WrEBqm`r76mKHTk*2K>GW`Aq7) zJLccwk)a+a{q1cRfwlN`HTK2?LdFMRv{ni{#fov!!G;cqpF@e{g+$hr7JY$H-17mb zJBHHQsYhLJwIC~Wa0ngPhdw?!P|YG$yb2tDnD+paa7SVQko>)UE&h~^PMzHS2+v{e zy8elfRlKX`b zZcrgFWZ4T1jDu?sl)~JJrYc^)*!HBHg=qfdYq6ykg!0pSaZj4#lBpPVKc{vVawOP2 ziRb(pwlhc}i)6+IzHf~uDB-vBdTlend#j-k^BR06y!aKIKp;2q7+NKP2kA2uRZTPm z6)Oh`Oc0Dv&n#kJkp&QiB`~DQsoJ^n?}s*}uhO$^xT-U)Bfml#x~up49DQ7Xn;rnT zR;o#`E}no&S_Lqiyj!esZ64OY#7^8mdNa)ykGDeI!BVVWtKFnt)(bQlzzY>^E(9j; zK1f;amJKeJm?$1lbKWceS}(dT9=|o&xR6_s_@U8->Sw`U1tS zC0*5UO}+sJcI>-D&Mf?~<=mVhPzd|_ zyu2v~dlm1jviNQ}B~uHgax$`BDme5$0~SN1kjioh_qD2-UEz|fg|+IA zb)<^(|(Zwsr2_pL!CB22&hI7VI2+0%3Wo{85QSVs00TA&wBi#__lH`=4ODvXh z4j`ybUJ(J68}^_H4z;@30hj!4Lao$83q>=@g{eq#FRU&0Z1mOF+A#sp`tP1k9hn&i zSZ?${A-;V;TO0pK-U)Tc!mK~v&088ZdxQgCPLx~w00*zqwQ5WrtCY`m6 zup~I9E_VGwtJ}2Xc;o4As#Qj8ogRT&X-RO3lu7ID!#-|KN>T}Z+pjY2yk7m~mQK^E z&%M6m%}Wj&3%NqOTU4Il=3Z=~hMDSQ!PKbCo33i4z}Y)1nK=0%+tZ5uQWvKT>}l1z z@7MJhvaL_`-yzcxEocqomQ)r;|>J>-R;vxH)y|mQgEP z0tEg{`7Avpyanjkr5#le$S#ZtyM=f=u3mM#gAp+rI0?}X4S$ol^683a+c^MO9Y#EO z?SseX(iYII7_FG^U%bW*d+=-IKcR6yz6n&9^U_D=UGx|1b&yQ946%Iq#oO;9_bfa? zFC?Fo`#cU=N+`P9KXWnh!w&f~n`T{N)8)#GW!GB*m|wEtin{SNp}!8|ahR^fU~ki; z89dgkF#g-$!QUnycs)S=!aW9vQn7K|%u!K`(UZ7fKOn2K6f`Aqu~YR%p_p|U@LM-c zjCfpW!hRm80@JF|@%FL|EBHE!>3Ih|J=`0IZr+Y+%vw<6vM)NQ;1Z;q+czv5IR;xe z^$*HuXpsl#ZxiEO4jd)SMRSE7N;IVyRQKq|C1B=7H)rcdKE9%+;+Pdv{{`f5!!DSN z7&FTDyTsE*bQ8^vt6NG4Q2cBhpSL3??n7f?PJv*5;fBT&JtV5Xl<11r&6g)%%em&@ z*hxVhK2@K>B`f-!th}?j*KPqEn(&(p{R?5_=hL-=V!y4r(z`bX{qf*g?3(1ks5|D^ z`S%-pMpNCY%4paa=C*`2O4BL6wC2Wo=eVxzln}k>?OP~r=VLZjgKrWgzY5YAK3Qdh z>RV^?l7mM0z-wrNCEbNs@Pz%0yRAbzaHni^?!{7QxG{EdWJXlB#ecC+wrAC8%%0n# z3IY>CB*?}CI8)>D{jz3OQpP*^v{II+zd^%yfXrlDHhqiFwj^q{kr-@wqqrV7mMFg#>9m@X%a#4e&a>? z73PR68Zo9xMbtnG2q=O8;F|7n(K+co9`UsX?R#;N8Y^0nJAE6e=Z=)eW&IAseWg5% z@eofgnR3M7!A!3m@hv9Vfw&qW%1fZmI(VN=E`VM^uo!PcLkJ-MO(kJ6rma1iB^$;f zuZF)nZ=t9p8DEndDlN$UJ?xT0W0DVvIya%-?MEC|NE)Aw7K<`P zENS`gD~0^mq=)-9bHtXo*7$A( z(T?m%APyCi!w|_lm^|6GmPZ)a?0& zub6WN4)Lo#=Dd`d!`7FGNBt|zmL$1I5gw$}o+y7D+Y0c=o9nis+eecXfIHC}_yuLJiQvx=1Z9y5%J6Ch z&1uKwz6Cch^?N{}>YHJGoGW0-gv{^2WC0`2a@|f>84(o4XTry@Fos=j19NWVDq5cc z$!0M*4Qx)#wIn#D?$=?;POu?y^*pqs?GF5Tgrw~uFDLjE0)wg{W?@I?Zd$L2#BL{4Z2jEWDyTq~F>%DaRqBPINBFmhOk3D= z5<`U8D%thLfMno=6BW|{j7#y$(IYxA)ip=Vt-T5zs@iwcn(w@j&2}1UK$Zp(MN)=l z-`1fNl7TEHRdh4Q7KbnuL5{?A=_`1 ziQ84MJU9OC4SPTm)1{+t+pKbAduEo(LwKIoi1%w+$zmQ!qhk$i;>=SS0PP~|xkshT zRhivIKT38_koa6!77lw^`DD5FLr=e!WyICw8eV1lwFyXX4s*4UkVLA(jhz3wO@cP@jO#ox0pgD zi$>uNF`ee|9}bMvPQpAKxHzq9I-71tkM;{(ff50E?%j{F^qDrmT%GJ4jxK66nl*?D z3K5=qTA{hrej&^YK?%jKM7Wja*4*KOEw~5ab~;p9W6iUzCqgUT`pA%2=oLO|x-0*_ zplNd^Cqmdg&ILGGP8p)e*$0&4IJJvYU+Q#K}B`JTH(?AYwLrO#TMVpi45(fM8Ads`+t zX?MfP#KjpD*-D}L!{{_M+aH|w6ln-<#%{HJDvt}}n%jiw8!#D6pTHh;>#cIa*xXo` zkz!JeM%ltXw_9}pjpVwn5tr6!zpl_^-CHepO#9$on)(QSGYf2gTbmadg$djD;3AYQ zs1fL;yF;8fij2O_q&Wr;gA3?|!N+?8`Wm26ed92Je`8MEKl|req;8!FNp<@qQcX_| z!x)oJ2(!H_U$MR0u<(SscYic*G2nJVasd~5%I8EuAryPcov*suDPRvvTsQ zHB7bt!rim_ZQ_aU+jaCnYMD5F>1y}=8GL8Vh5haM0ZNI_NKta!&4o!_tsZWI;iVJK zWuvn;F^2BI;`!1WFdo;UphH?I$CQMKVPh+ke_TdDZoeK>rnGeU^l z{(Mwiw~0~Pq|>f&;+AhXMj~c^*#xs%Qeo9m(fl-5*TC)RH6^y??0CJ9@obAFzKYoK zwf5;kfD-@j7+()Ii}1-uG_>GLALY#MT?+_O)Xnd<%>K*7;{l8P zXtyfh;T5k9?#mhG#=3vDu+oIR`oyPI`pJi)YieGVY!H{!Ukm7$)unlg+}Srg!@}wB?;J+__@Mo-WI_fX-xWC1R-|%x0}RyV ztL*p_!q|WMe*k59_(+6~;5%Ms`I9ZRa6kTM#N%=@`2WHSJ^XB)N~!%{L6etDNbJAR zJ^vl9>4zG?F|H%pE?*VGl}y@(5SafDb96av^>6V)mp}S{0jl-C<8l6HZ0ozUqu|Ok zD)B$`5y0C=y?`!mV=GWEYC*S<@8T|Scgj}0u+i_JH|?;yt?G+q#EHl=j(gduG|zbsLuC) zHCXCklSFm#5D@^>-YqkHP#8dm{}1B?57Ot?TlXO^X#ae1OsqQjaf*S&sveU6sD#-5tQK6C##SOqf`T3qQ|q z{KLH@Mu%6rv~ho)chJh(NDj(g>6kbYT}KXXSawl`E;WLOi~Bp+9YWg-ptJ@O?q8A}`Q2k)(U=-qS~=|0>!6W!N8+28*U#6q)P literal 0 HcmV?d00001 diff --git a/doc/tutorials/vcat_configuration.rst b/doc/tutorials/vcat_configuration.rst new file mode 100644 index 000000000..1e333be54 --- /dev/null +++ b/doc/tutorials/vcat_configuration.rst @@ -0,0 +1,89 @@ +.. _vcat_configuration: + +Enable vCAT Configuration +######################### + +vCAT is built on top of RDT, so to use vCAT we must first enable RDT. +For details on enabling RDT configuration on ACRN, see :ref:`rdt_configuration`. +For details on ACRN vCAT high-level design, see :ref:`hv_vcat`. + +The vCAT feature is disabled by default in ACRN. You can enable vCAT via the UI, +the steps listed below serve as an FYI to show how those settings are translated +into XML in the scenario file: + +#. Configure system level features: + + - Edit :option:`hv.FEATURES.RDT.RDT_ENABLED` to `y` to enable RDT + + - Edit :option:`hv.FEATURES.RDT.CDP_ENABLED` to `n` to disable CDP. + Currently vCAT requires CDP to be disabled. + + - Edit :option:`hv.FEATURES.RDT.VCAT_ENABLED` to `y` to enable vCAT + + .. code-block:: xml + :emphasize-lines: 3,4,5 + + + + y + n + y + + + + +#. In each Guest VM configuration: + + - Edit :option:`vm.guest_flags.guest_flag` and add ``GUEST_FLAG_VCAT_ENABLED`` + to enable the vCAT feature on the VM. + + - Edit :option:`vm.clos.vcpu_clos` to assign COS IDs to the VM. + + If ``GUEST_FLAG_VCAT_ENABLED`` is not specified for a VM (abbreviated as RDT VM): + ``vcpu_clos`` is per CPU in a VM and it configures each CPU in a VM to a desired COS ID. + So the number of vcpu_closes is equal to the number of vCPUs assigned. + + If ``GUEST_FLAG_VCAT_ENABLED`` is specified for a VM (abbreviated as vCAT VM): + ``vcpu_clos`` is not per CPU anymore; instead, it specifies a list of physical COS IDs (minimum 2) + that are assigned to a vCAT VM. The number of vcpu_closes is not necessarily equal to + the number of vCPUs assigned, but may be not only greater than the number of vCPUs assigned but + less than this number. Each vcpu_clos will be mapped to a virtual COS ID, the first vcpu_clos + is mapped to virtual COS ID 0 and the second is mapped to virtual COS ID 1, etc. + + .. code-block:: xml + :emphasize-lines: 3,10,11,12,13 + + + + GUEST_FLAG_VCAT_ENABLED + + + 1 + 2 + + + 2 + 4 + 5 + 7 + + + + .. note:: + CLOS_MASK defined in scenario file is a capacity bitmask (CBM) starting + at bit position low (the lowest assigned physical cache way) and ending at position + high (the highest assigned physical cache way, inclusive). As CBM only allows + contiguous '1' combinations, so CLOS_MASK essentially is the maximum CBM that covers + all the physical cache ways assigned to a vCAT VM. + + The config tool imposes oversight to prevent any problems with invalid configuration data for vCAT VMs: + + * For a vCAT VM, its vcpu_closes cannot be set to 0, COS ID 0 is reserved to be used only by hypervisor + + * There should not be any COS ID overlap between a vCAT VM and any other VMs. e.g. the vCAT VM has exclusive use of the assigned COS IDs + + * For a vCAT VM, each vcpu_clos must be less than L2/L3 COS_MAX + + * For a vCAT VM, its vcpu_closes cannot contain duplicate values + +#. Follow instructions in :ref:`gsg` and build with this XML configuration.