From 0b00bbd65f9d38ab0bc959974cd0bdbbad802ac0 Mon Sep 17 00:00:00 2001 From: Jason Chen CJ Date: Tue, 22 Oct 2019 23:58:31 +0800 Subject: [PATCH] document: update HLD for vm management add VM state transition, and make this chapter into part of hypervisor hld, the user level vm management should be introduced in ACRN tools. Tracked-On: #3882 Signed-off-by: Jason Chen CJ --- doc/developer-guides/hld/hld-hypervisor.rst | 1 + .../hld/hld-vm-management.rst | 161 ------------------ doc/developer-guides/hld/hv-vm-management.rst | 63 +++++++ .../hld/images/hld-image108.png | Bin 0 -> 33425 bytes 4 files changed, 64 insertions(+), 161 deletions(-) delete mode 100644 doc/developer-guides/hld/hld-vm-management.rst create mode 100644 doc/developer-guides/hld/hv-vm-management.rst create mode 100644 doc/developer-guides/hld/images/hld-image108.png diff --git a/doc/developer-guides/hld/hld-hypervisor.rst b/doc/developer-guides/hld/hld-hypervisor.rst index cd4c8e1c3..57b343d21 100644 --- a/doc/developer-guides/hld/hld-hypervisor.rst +++ b/doc/developer-guides/hld/hld-hypervisor.rst @@ -8,6 +8,7 @@ Hypervisor high-level design :maxdepth: 1 hv-startup + hv-vm-management hv-cpu-virt Memory management I/O Emulation diff --git a/doc/developer-guides/hld/hld-vm-management.rst b/doc/developer-guides/hld/hld-vm-management.rst deleted file mode 100644 index 9d5b96ccb..000000000 --- a/doc/developer-guides/hld/hld-vm-management.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. _hld-vm-management: - -VM Management high-level design -############################### - -Management of a Virtual Machine (VM) means to switch a VM to the right -state, according to the requirements of applications or system power -operations. - -VM state -******** - -Generally, a VM is not running at the beginning: it is in a 'stopped' -state. After its UOS is launched successfully, the VM enter a 'running' -state. When the UOS powers off, the VM returns to a 'stopped' state again. -A UOS can sleep when it is running, so there is also a 'paused' state. - -Because VMs are designed to work under an SOS environment, a VM can -only run and change its state when the SOS is running. A VM must be put to -'paused' or 'stopped' state before the SOS can sleep or power-off. -Otherwise the VM may be damaged and user data would be lost. - -Scenarios of VM state change -**************************** - -Button-initiated System Power On -================================ - -When the user presses the power button to power on the system, -everything is started at the beginning. VMs that run user applications -are launched automatically after the SOS is ready. - -Button-initiated VM Power on -============================ - -At SOS boot up, SOS-Life-Cycle-Service and Acrnd are automatically started -as system services. SOS-Life-Cycle-Service notifies Acrnd that SOS is -started, then Acrnd starts an Acrn-DM for launching each UOS, whose state -changes from 'stopped' to 'running'. - -Button-initiated VM Power off -============================= - -When SOS is about to shutdown, IOC powers off all VMs. -SOS-Life-Cycle-Service delays the SOS shutdown operation using heartbeat, -and waits for Acrnd to notify it can shutdown. - -Acrnd keeps query states of all VMs. When all of them are 'stopped', -it notifies SOS-Life-Cycle-Service. SOS-Life-Cycle-Service stops the send delay -shutdown heartbeat, allowing SOS to continue the shutdown process. - -RTC S3/S5 entry -=============== - -UOS asks Acrnd to resume/restart itself later by sending an RTC timer request, -and suspends/powers-off. SOS suspends/powers-off before that RTC -timer expires. Acrnd stores the RTC resume/restart time to a file, and -send the RTC timer request to SOS-Life-Cycle-Service. -SOS-Life-Cycle-Service sets the RTC timer to IOC. Finally, the SOS is -suspended/powered-off. - -RTC S3/S5 exiting -================= - -SOS is resumed/started by IOC RTC timer. SOS-Life-Cycle-Service notifies -Acrnd SOS has become alive again. Acrnd checks that the wakeup reason -was because SOS is resumed/started by IOC RTC. It then reads UOS -resume/restart time from the file, and resumes/restarts the UOS when -time is expired. - -VM State management -******************* - -Overview of VM State Management -=============================== - -Management of VMs on SOS uses the -SOS-Life-Cycle-Service, Acrnd, and Acrn-dm, working together and using -Acrn-Manager-AIP as IPC interface. - -* The Lifecycle-Service get the Wakeup-Reason from IOC controller. It can set - different power cycle method, and RTC timer, by sending a heartbeat to IOC - with proper data. - -* The Acrnd get Wakeup Reason from Lifecycle-Service and forwards it to - Acrn-dm. It coordinates the lifecycle of VMs and SOS and handles IOC-timed - wakeup/poweron. - -* Acrn-Dm is the device model of a VM running on SOS. Virtual IOC - inside Acrn-DM is responsible to control VM power state, usually triggered by Acrnd. - -SOS Life Cycle Service -====================== - -SOS-Life-Cycle-Service (SOS-LCS) is a daemon service running on SOS. - -SOS-LCS listens on ``/dev/cbc-lifecycle`` tty port to receive "wakeup -reason" information from IOC controller. SOS-LCS keeps reading system -status from IOC, to discover which power cycle method IOC is -doing. SOS-LCS should reply a heartbeat to IOC. This heartbeat can tell -IOC to keep doing this power cycle method, or change to another power -cycle method. SOS-LCS heartbeat can also set RTC timer to IOC. - -SOS-LCS handles SHUTDOWN, SUSPEND, and REBOOT acrn-manager messages -request from Acrnd. When these messages are received, SOS-LCS switches IOC -power cycle method to shutdown, suspend, and reboot, respectively. - -SOS-LCS handles WAKEUP_REASON acrn-manager messages request from Acrnd. -When it receives this message, SOS-LCS sends "wakeup reason" to Acrnd. - -SOS-LCS handles RTC_TIMER acrn-manager messages request from Acrnd. -When it receives this message, SOS-LCS setup IOC RTC timer for Acrnd. - -SOS-LCS notifies Acrnd at the moment system becomes alive from other -status. - -Acrnd -===== - -Acrnd is a daemon service running on SOS. - -Acrnd can start/resume VMs and query VM states for SOS-LCS, helping -SOS-LCS to decide which power cycle method is right. It also helps UOS -to be started/resumed by timer, required by S3/S5 feature. - -Acrnd forwards wakeup reason to acrn-dm. Acrnd is responsible to retrieve -wakeup reason from SOS-LCS service and attach the wakeup reason to -acrn-dm parameter for ioc-dm. - -When SOS is about to suspend/shutdown, SOS lifecycle service will send a -request to Acrnd to guarantee all guest VMs are suspended or shutdown -before SOS suspending/shutdown process continue. On receiving the -request, Acrnd starts polling the guest VMs state, and notifies SOS -lifecycle service when all guest VMs are put in proper state gracefully. - -Guest UOS may need to -resume/start in a future time for some tasks. To -setup a timed resume/start, ioc-dm will send a request to acrnd to -maintain a list of timed requests from guest VMs. acrnd selects the -nearest request and sends it to SOS lifecycle service who will setup the -physical IOC. - -Acrn-DM -======= - -Acrn-Dm is the device model of VM running on SOS. Dm-IOC inside Acrn-DM -operates virtual IOC to control VM power state, and collects VM power -state information. Acrn-DM Monitor abstracts these Virtual IOC -functions into monitor-vm-ops, and allows Acrnd to use them via -Acrn-Manager IPC helper functions. - -Acrn-manager IPC helper -======================= - -SOS-LCS, Acrnd, and Acrn-DM use sockets to do IPC. Acrn-Manager IPC helper API -makes socket transparent for them. These are: - -- int mngr_open_un() - create a descriptor for vm management IPC -- void mngr_close() - close descriptor and release the resources -- int mngr_add_handler() - add a handler for message specified by message -- int mngr_send_msg() - send a message and wait for acknowledgement diff --git a/doc/developer-guides/hld/hv-vm-management.rst b/doc/developer-guides/hld/hv-vm-management.rst new file mode 100644 index 000000000..2aa392170 --- /dev/null +++ b/doc/developer-guides/hld/hv-vm-management.rst @@ -0,0 +1,63 @@ +.. _hv-vm-management: + +VM Management +############# + +The ACRN hypervisor maintained a dedicated VM structure instance for each +running VM, and a series VM APIs like create_vm, start_vm, reset_vm, shutdown_vm +etc are used to switch a VM to the right state, according to the requirements of +applications or system power operations. + +VM structure +************ + +The ``acrn_vm`` structure is defined to manage a VM instance, this structure +maintained a VM's HW resources like vcpu, vpic, vioapic, vuart, vpci. And at +the same time ``acrn_vm`` structure also recorded a bunch of SW information +related with corresponding VM, like info for VM indentifier, info for SW +loader, info for memory e820 entries, info for IO/MMIO handlers, info for +platform level cpuid entries, and so on. + +The ``acrn_vm`` structure instance will be created by create_vm API, and then +work as the first parameter for other VM APIs. + +VM state +******** + +Generally, a VM is not running at the beginning: it is in a 'powered off' +state. After it got created successfully, the VM enter a 'created' state. +Then the VM could be kick to run, and enter a 'started' state. When the +VM powers off, the VM returns to a 'powered off' state again. +A VM can be paused to wait some operation when it is running, so there is +also a 'paused' state. + +:numref:`hvvm-state` illustrates the state-machine of a VM state transition, +please refer to :ref:`hv-cpu-virt` for related VCPU state. + +.. figure:: images/hld-image108.png + :align: center + :name: hvvm-state + + Hypervisor VM State Transition + +VM State Management +******************* + +Pre-launched and Service VM +=========================== + +The hypervisor is the owner to control pre-launched and Service VM's state +by calling VM APIs directly, and it follows the design of system power +management. Please refer to ACRN power management design for more details. + + +Post-launched User VMs +====================== + +DM is taking control of post-launched User VMs' state transition after SOS +boot up, and it calls VM APIs through hypercalls. + +SOS user level service like Life-Cycle-Service and tool like Acrnd may work +together with DM to launch or stop a User VM. Please refer to ACRN tool +introduction for more details. + diff --git a/doc/developer-guides/hld/images/hld-image108.png b/doc/developer-guides/hld/images/hld-image108.png new file mode 100644 index 0000000000000000000000000000000000000000..4276aea06442a895f00b6026bffe5c32639640b1 GIT binary patch literal 33425 zcmaI7by$?$7dEOe=+G&mbc=!vA>9l;bc4VU(%l^+H3lsV-Cfes41$Q1ba%H%iPU*` z-}m>O?>c{+Ke&e3v!A`zUVH8R?6vNDA=Omm@Nu5v+`D%VUqK$Kaqr&!{(JW@9)ceL zEhJR-_Q1z|Hw`(ddliFJ+rSr)m87!dy?a&BxL2lFz;|qCd3`satNY#G{RK-}?|b(U zEDBIbEpOxf)`(`B?oS7Pw{=HY(Um<@n}gIt{mIf03cM+bR3@elRGMTkm->j#;C-g- z+A!Bam(4V{K}nCx@`F0<=ch@U5$ES3N;5|3&AWz9x(25~Y*JwQ(7aHD!rjMxtau_R zumUCy3wAdQ2sV9a3~v^k1ZcI9Kr;cYBf`kd;r!g2xH#5h+~la}a)j3GgZ8<~tPVtvIqjw~35vZc&3N6U zDctO5tXCd*)KI>&xG_`Pm$aHhx+jJw8G61xzz2kqw92_)9zE5Cfip^Z!+KPogP1=Q&j1hq3srB zR$Z&m`2dTjphF#PDtdb=c71x=H`#XX;m&IyhJS%~;n3^#a4hY(D%@Xwn8`E*@kCmU z`GMacsZ!!|n{M7U{s*)9FPFLK;FVKwodm5hPlS8*;kMPnfQDd ziN!M%*F6Go6xcyVsUc%*b>%AU@kbq;W~*V_)1$a0;F0BN!rarEgj;5D9b)sGl(dJqETJ_W3)yowQ zB-0V%uMMYE%e*XpoQq7=R|jlG?V{^uHsd{}7GO!&1oK;87^(Z@liYq(I|wB0nH#^= zlOEcl-aKjM=bC?d=Yt>8W7w0~%I$f{wsQO~fj(VD#S28R|VMg;YCxvnm^A)=n{aT3Lwd^W@}+?qV3 zHn?v^q|#29ViE3lCY*@6aEaX#lOfV9SM7Rxkb`DkF3ha%ezBKUz>n%9yN?ohE$$MG*>mfOR2h-^S^WscE={*K!-UVm5a}j4 z78`y$5SNhGck{>OtU<I!cB5jDT248LD zs!M&)rXZQ6lR)XDzu(HCfR#ru(TB63_h>C;U5pgltmJf?;y2^(H@U|uJ=ADuT^TuS z^GhfQ8^^LMWYpzKbpm0dYow?!$S&C#^Wf{^N4F*>yO%+r@a>GW#d`*%pfmY9R2a;+FO zDZ1>CM%{e0D6#t&$+^IVg|oj-x*dg%-H?0n5J7zjzt^jhP5#Le@rrUCPWxib%6)q+ z+5ng_mF{yYW^(IlQDm|h4jksRPF?x-nV0t$7+_E4waVt4F zJ)!@^B5_O4%(cZGiwoFZ_L7ih*|DuL2Xub~T-zh6^b@P__;D27P3EDat)Hv%C*S>u z2dBLu#OGf4Lli_nQRefeY<8uaY$mLA`E?1aw7uCv(6}G4a_JEZj!!78u zJ@?Vi#!*O;vV__JKh@2Je|)X|>^qc&RwPh+(zOy&%&p>)xh)c*#e&ec0<)wLS3l}M zh_yMrUN=5n(a~kfbO!z2W!&FUTMxFSmgfj0+I<)0Vnh;6ijElJHZv6oT>*e2n?YVWGC-T#T4Fp(F>a$`z-$r&lPgaAA z!k~K4`Iabq5b332b4hYWRB}$FA8)0!Sa`pm;=igTa-!|M6cK$<9_$HB;v7!eR+Qnb zb<-hs7uG@V#b`?GdeU|okHQd7T$Ws2AHha@JNq?KP-XFNYPzg&%J#2DtK6YjmKmc% z&a`J@43Uu0?b#mgSr$_Uvijtn7+zu+%IF90;Q-&XTt;#xutS^OmBoUu@N(E_DL+HN zEG4jZ;fV^F{bB7-wzJ(duS5iQ%LfQIpGJ7tkUFHFwvrk@M^gT?R`I3q&b$-Tq>(O* zbar#f=^ipXHlLJq1C8X!cRp9p2kN|74=$I|>X(qoomR%AQ0a=r!xl^IAzpDb?-0i& z@@MjXOntAIrww)ZvBhsZhpz#tw75jB;Nok?^$QfOXmXiq4{+w$H~iHqB>&N)qg}k8 zacu3Tsa`#_Gm(AzTT(JrAvv~1@VtLe$%6P4YK>m`$LYV6A(Tvp7Pf|0Uybg z5}wg#bl+QrF3ykU`Ax?CkwkwGkbDe#ZNlA`PxgpaNvG~bVo`#TZ4H*&@r9#Dp6yRv z$goP|N$_mJpWz$J@ez|NnzFii(!W>FhU2{No^}=_>)$d=0J$CUHF)jD?nrKyIMtl{ zwyX4fQSdXWlC0E!tu*_Bdjug^c9kGZb+ILIJla8G(JD8;kU8^K^XY<_-U;zz;h0KsN~! zliR5eNm4lkz}RXK8%ciRe#&xbU%f~U6d`-5TH&r6rK&y{l7=-ILC?xWqXuClz=|h# zCq>WsE;u|s;lZOse~!uuv7N@ZYHndB@%W!OB)qNV+OtJh{IW0n>AWWeli1W`*}}~H z7DsH6G%#y2n88o{i=#~?zCZ8sC=^lP#3&UBNepud+Lxuj66MFTfdddzr9 zZL1R9qPwCaQ68O6Hx4)}c$Yfa;={Cn1Tatme8Q8!7JW57dwIfs&TBxlcYAq~K%V|E zab9bY#z9xtP>%Y3%7DNhUp4^)(W1(9$?4VmSUhV>yM6=PgQ4{^RoaC@V@VOS<0Y#D z1`wNCy6M}CgYdtZP8FpNkAe}-AAZ(a6=wY7IT z>Qwf#9>}qdubr@eBnOw;)9TzVf8w6+0J&uo!=P6_z5yQ_pm+Agkgro?cnd#hn`r+T zj?F3~uO<-)ZDSW+e!w9CKYqcHn@!a36=<(5C=@ryBp53v|N5E2DuY^{&^Q4aHQ1La;fYD2F_DubQpx z(uHP;`sIbd;}LdUc+dY?#(PvafnVAU)vM?dAnpV0(_EgDpGk07ut@?DNIuwyMt?i6 z_`yDw7LKKS0W_>>^YJi5IM3XfbYMY6VNlHk2>N5 z46|jyfRYLr3jI5hs`Zp7eDBLx?t>oO)Joxq!tuoxnwD{+Rp3|x?&~pJyj-O{#jT(7 zRn7yIv9RJn>GmK^>x0a( z?%e9ksL_tbvAl}uu48TVwk09e@w}*ViIv4SL+KUZJp=uo#G8|qr=$iV#V{4}ASu)*4ap z>BGi^cmCi4g?vqn*MTk4qHP7X%Z)8nrRoliKXa8b@mu4u-{zac)*HVO*WK7B{oR#q zz@(mep*lw3V;CbKjmE=nt~}eOJq$@r7QDy;Zx~cY!ZtfDjUfVNcSrzu~h+_0_+(fFTr+d*vZxBS1L~&GQFczD~cyp{x1EV-KAwK z)iR;A@lq_J;*)X&*+Pn8N`>}v zsz;Ftub?AOsbsfP$PnT}Fxr1gB;wcVb7hZ33Qtda5euJ5EWv4sQG+PxWx*ey${)`K z?=-r{6UG7ajgF+a;inc4&gBndCN8LXTq9{9hQ%}OF}x z94+i>5X>LzmJRdVlWb847F0n^&u#r`eK#HPwm?ApDkd>m4R6Xjt;sNtf{srbko$ul z9e^NxjS$E3p5%89yck)g%-7f{@ON$vrB+ztn}>2jD&n!$7fAW%d-al}?RGEg;EGQx z&~3Wxnh@+>D&VmY9zSaz8RL!VW72+P@d!a%c+F$0gNLB|yUJYMiv{v|t0ywN{rgND zseHo3w8u?r-t}KT89+iryW<)#-qL$%2VbeJkg86+bBR-OkeivWF@Drg zk$7N}lIZz3jS~lb{%W_=Sutz+Rb+4SLsrZ2uKt!37tlWn5aC!N1&zeZO0Rz$kG+^6 zWP4*~++o_o_Ub&U)P&uj_y;G`K{sF|$(zgd744FGJD5jwf6=l+!!?P+K`4kA#}XT@ z7Ts=NG<;-+i`_P{{I-DFD%4hADJ>{-5>t^HMCm(l?KW|G0Wz`r<{ z<~-kSS=?WfS?fL87Bp&Fb0#6tdWK@gaQiLE-eB_Ff0L2}HF&$l@m^zNi%BuLro`<# zv2u^ivQp-FO&$eZCVji;s(+azyYPcT?aW7?gMAecI9N5%mg-z%!>V9HDea^LZsM+c z^M7U^6plrts&3aaxp%-1^)7b(`#CHA!H(LvRkgo0=RWjq!+5P9gZw6pzF4kKxM zz0hXq8%eQF0j0Ilo}>c}enUB}c+F~iN|e?-W6`^GLkh)}E#~ex&{G`CSR3G#WrjTK z)3_G|>Itp%!Q&au+4f(T=2e&Rth145Z9GH$9h&6daefndgnZ8Xl!H{de`T?yMfQ5g zFm;?#C9r7>lC|Tt}Gywt*(SB-AE%?0+M) zBu(>R7^*<(kh0|-!Wo#rw>-8qXFx5Dq!?5wi!H$C3H0~LoA)yEA0U?NVXDmfmebuU zZe0q6V`$wH3i#mp;QJ8x5K<4<>S=H&fV1G_u}SrlrITKKzDoI61USsf0xyV_{g0wy zUpkQ*_o%35l7H^g=Bt9)sAwGwu3e1k{%+_sA2xZ$ zU^+e%ZD{HrR-UXyjdb1Yfj3e{)7y5fy`GA7Wqpj1qo6kpL+Hbw`p%m&8FGfQ(gh3f z5i9TSS$k1{-1fI$E_&3?dN%WJKczPf2l|Q4EaqUANqft?|3vr{^cgaQcHPIZye~Mr zq%!YO>-$rQUOfb%Ab$l+BIa?!L~(;BzmF1=B9Pxj(vtOKRPB}sf5^*W^!_R@fAGJ? zU{i`9J?;E9!I^{nm?B9u6H}lX1h*p*cfQFTNjJ)r@?S@hw_sL6j!LyRtV%qT*lYwq z3V8)MgoiqiIqpb-GNz{g^+Ui%iTX~hw&iny@FfO_+WHy$qP>bD`ks4qxRTtx&bolt zSw_cP>@y?BW{M0VZzjM0HU8OgPW3fY{**!U9!d+mypP@@k{|B)vbb-%o{x)hhC!+S z*C@u}G=6_V!5>IklZZb<3A)w;3}IT3iXF%kTy3YAZgQ;k7w{-7a)%YSy+=%|}e zH);~m`MTY_^58%HLI}?V^ZUx#jlL28H$1a;`f8K=g(mat%T@4yz2fdNIqi-XLsMUX z4ELRtYO<=lG?HGP8*hH;`#)_$a1K;GQq$Qtg$WuvL6ndn6`xv7KSnM7Q=i|uw#__x{4v?AuB7yD?_ONOiyY6!= zSw`w}h5=do*IDoaY?iPr&AbQTtDlk2K`xynh|%?zoz_ zH$cI6;Xf}bC0#eVqC^W=5Wr4&Elo!`e+T^5XMTB2XQzbK7A9r3*-@4?jMBy3yH$ER z@mAH-*hK#8BC^9}-T&Tf3QJGS{;!5cQF9gzJ-at{P1 z>5}iLW^+F~lL#e8F~g`#LP;f-;y#HD9Ge;LahhR&X3xQPewjxsg}}t(!6(8vq!q98 zRbs-E-yQ&&S-eZrk0X04kMu@fU>E3f*ESqWhd#c14@sT0F2K|*!lp+DBa#vEKqTOf zMCK@X%j-g}p}p+$$+J@k8(Q%vu8wZv$4-FJ(GfsDelPx#$v|r$#?=d+LScZQwV=pP zCWhH;AO6g$Law7SaT25kN(_PS%Lqg=D7o`JDKvsKGF~g`-8~?N?{|RTo9(S;LlN=k z^>Y1cw|_`V4+GWn%fteE>`NA$Wx4dLgOKGj!17XPm_+8|2TqsyG@M~EYba*T(LD_g zdZsir2x+i)6;VHZIGQn(Xhi}I>mao&8T0CyX=Ro=01;;ry^JLyp?!uDyV4TOQc5}% zB?Xq;tMlTYEeoSHo>s41m>pf?Aa>>dcgKyc*zOj+G|F(GIMV<(QvT~;HdVDPGC=qQ zczV}=`^M%cpFqA+l3&HS4_oLT>3=;IUnlcGi!e#Mq&L|I@S>o9_gz8HRk`8L@TX6< zr^PCO{$2liC@h+B{B4s^eYV$#5Ydd7UPApCZ=| zpr7D>{q9E{##Sr7;_>SHzZ+f5@6O*uumb+wt|InBi>M3dm73c%J>gHxBmA!o+CQb+ z?sV6S@NRmH69~500D`%_bB+JErSa%>gD>FwDR2wgIQl!8a%EV@#UA53hAJe=)c|@W ze-&8{&nTvy7_WLny$V=$`yV58=|IG17R!uhj1M`8ke3{@7kYz##qqoHAx?s3FG^Z4(;D<3uoUx4u)&6M<9_duC*8{qzV>Zt%}Z z+Fu|ElkOBZ&HB)wMHEc0&g6;E_pH_wZ7ld<$iO68Z{%Kj6t6GSg973krgvQ`5cq-0D3kj^o}soAJOw6E{1Q& zPk#`EcQQ7bCvxjIF)@jCNkJl5EbH86eex%j=)+bf07oFddHl8dST4cd{s+gK9QW-8 zv8R^pa+|bLW-9C;x7&|_9H@E5QDYo7P=$bR_!~|KxCOUs{egRgkRkt8^UJ*lE-lB@ z3w%;5Fm})};3+%lw5cu3ajLIF+|##Pj#Y1eh5oglWjmdnP}YpjqT4&wb8OF+P>hSlEicv;F9iH zdxs#BbA5eCBor|SO-n{-vVBTLs{&i#v{N=PxWnyB@Zjjip**1kDjw^e1_;m68f~!duAVUNmU|Pf`r| znDuJBY1sqvbwxpj)w0S%gEe^yW-@tLZhc{n)bm#4?bdNTBaT?C7pH@6WPKE~qACi< zN73z*#I-TBzi?M8KS0yvaW|A^cgG9Y%NIy`AKBDUWuVjnJ7blan%i$tgf7(1M(J7) zkBM5h5_@Z6aFb3Flr=DG0PVs&8^~xuXouF%n^pr8} znkZ`_*mdY^zO|6u|{;2lWGGBo4^JaRi!I(rI%C!t@efsN4>q?+lPN) zbrYU@YyaLYWfy*SQ*W9|81!YMnSiC|sF`N&eZYJpMajnP;pPwb(TBeuV#Py~<#AXn zW4+(Vy={QH-p^MOki;8EMkP-Y2ORj>MOPlfCZS7LT^Lef9t;ImwtnPkqIj1xms6ea zN>xiDnaIq>b_yUB0A0H7CzEbJg+!*>WAb3pSmL4@2Zug?^w*mTw~8Hf`IYvj`8CY9 zkKp4_336Mo;g}Fg%1X~<233KmbDVTkr}_>`#Zfx@LO#^Ig?pYfQwI`JP7L`J*gZ2v z0!av{qEFmQ1Y3?}5*&zd}tg3eKV<_2X9hPRI%e8BI+=KYzS!TuAHRH7f z5@ZtFyW}#`_)}NWFOH2SJfe@KjU_UycW8!3Gw3t7T#^T|pQSL_0`iA=@pgBn!WR@c z!z|u=mJNzK2XFlxp5QM?XT)&76dZ!}li@4G+sf9gvE?9cWyq9cKkaBF$RCNrCi1z# zxqCIcX73OAAchdr4G)DBsu#&by*(HehBtglVFl}kknXj>-|9c0cfz-xP8_8?#&{yY z+93!=lEjksS4PzqTk((kDh=o6n7?*t{h5o&oyGcVrQE}|_ssVc-DY_@U*&oFb=_Ed zR&?1RopQxleP9D;!+HUvS;9O(k{g*ZU2lUEpAcoy3Z?-0utCSSw>iISR9UhFlX2`PiVDBe`vAY&dpo zf~TgT^O_zKq*);vJ3U?OR%?)J6YWb(rXdMpMXQmr( z&(LhAr?H*^Fi^f~VTn#!2G~-GW)@;v0Kd@g>9j}JD%mi6o(8kPx};|$V;`t@U96=Q zz|E#x95p{&jlkkZssf@%`0Q}?s{Ir<1K+g1Caf?Vd{eM#24sa;85mI>^9OTDo0K(9 zHMkgCDYr9&vH_f|w#VYpn*jJQe}i1TT`km^2fSzH1cw;~Ayz~gQRCKNk+O7Rk{&6@ zNnGJwO0&N)870AHfra+4ze%}F3AZE7K5v$L@)VP&)F*yEzHyLm`kPZa$|!DV0!X&0 zKxH8fCOhf?;Pf-U2BPUXQXbx_zvMZU`TXI@>+GOuwcLu@55C1-2v$Kp(S{{3EH z0|O8DZH$X@_Nmi{^HuZA|0qs@G!?^;{WJ%XeS`nZS_;C+7j4~RycnN(|1y6G9!3di z({lK{nRYDpTBkT7C(Vw^m`G{LytL#Qiq|9;9w$JIjeZ@_1l-%|XAE&zDPAB|1oHC+ zFP8p{HraaIa_c@*Zl2)#_FR9)=$|=}AdnivcQ|1FuVEhUT$ye8)2t+or;ss_`74L2 zPzSL^Wpv*Bo4bXV;zR}HR!qSO`aff2cZo^}C}FY8%8r+^#TA%RW5ruiV#RkMf8uVa ztJ*iobqedB0En6UC;MWFhqNc$^)e&%r5ta`U^CSJ$UQ+|SNUXzn#B`l7?_mnWbB*@4_y1*eI1ZakbIU!>zr@Zd}^ch1SNr2|S*Yz8F}lL%$o9Uc$f=M0?!)J`^6STv#ZynkgKPc}$1mH~jk;M0(3F)IM-L zDED~g8<)?$k}Kk`6t5^kLqDnEvQP=8{rTg*;$0-!GprOqc!k>*6%bO$!% zXk1TTn8desZN+R7HQO#*Nf-==2_t%A13J*&HJQ$ zdy$E!(qEFle(*Y_FUpG@??p&16NrwJPBjbPtubECK9(0>yCyU=`6mub3HXSyY>VPt zqq8q=|J3)Uk1j+-Jo4``a6r?rzN=@$VX5N6B6UdGs&mB6pQ@p>8$VC-)816`jtGwR zCN)6Mxwjb#A3ytiY8L(S&7eSzmMx3rhW0deL*B2!43_a_0sdOx!;2=RATuQ?VpzDPz(3B-<`=I`(Om07AKJ$K=F zhAmIYf)&rysS1fT*`rq&5hlmL&gR8@!|oA!qBS3r(yslNP*y6ASP`92^7Rv83aAKzdH=zt0`3}|Q@m&|CT7ki22k!ih!Ve7(1EPx5l=I-yDD9~o z5(CZkySITI&!BZ_@H4ZI+pra+-8R+Gq!(g zXsk9wzka(YxVOu7NZix0h-4pjdrsC(0*mkC$i*E3g^L8{@HO28gCc%nZ@6qmgwQIm zu^PU7K*Se%{k4@rmUU%g!d-Q%UWJkjdPIL;uKL2i;qUA@KJMU}_U7U5clY(dgBk1Vu!wAkUIqui5sPABdtNDC8LbLagwAn2^#7VMtyh{cuT`3{xHofc zya}dIjGLk{pBIX7dtXFCh9;BbQ9^d8LgGHjVi`j2pP}2NxIm;EUNrVf=>88o6)w~% zgv;DVu%A8zw3DH0@xU}+2tUPmEL%bGL3v<%nHN0L_T$1@Vn{~-+~qCv=-}cT@p#*3Vd#Y8zSbot9Lt-I zSEko6M=`lZl?AyWoEP)PkE=bPCJZ0Hmnd1+{>YV86!?#hFdE#Nm8a z0LO59GOGc>#Y8+q@s!X>NRe5JFm%&vA)br}V@WbwBW!RUc6F2U603t1xb3Tce?9yo z0sTQfWdS(9K!*L>TQ*c!evrNF!_Xk#R^bZLz;);G^lW41V;tXoq}>Lybd6N{@*Ao1Dab)W@}|!v(CqB2yWwNAgO}fGpsd*+H=DE%t!pF7 zWB0%x;ffsy4b_lGtR&bQU0T~|NbtK%)O})JL+Iz$$h1to=}3y?e3*g~^LIV~3$(Y& zWc-dmwh(!u$slJ>M2FU?{eg?F7Zn2(80s4{Tr%b}7OC5lo2xMH@e$3YjBo~;!0~*9 zmQ#vlqU4=#Zfqa51wy?Ou5o<=LLf9I&43?vg_+#Q^uVvTAxqBMwACx1ti4ES^N_c_# z&Z$leTh7t!yy{@HkrGh<4aFv-1v43k%0g&O_W8cWubAR&d|*Y<+6!gVTv|sM(|Yyu z^+0ug?2MRwUTePI33ECtZR65~#H!{zLt(Hq$B}&70h#Bcqj~NB!YqcBta1`5szUKMKUYy=7;a+4eyoJ=yvRxV8koi3isIi%7m8 z(M>#T%(@wxP4$Qgf(|^%%$U5ekc3db7y3$C;~SnOr`xoAP6VcpXFHMq0uF;Sc(QXd z21e$6>DV@9uoLm?501{p90*w5dHi0d;Pk5NIm_#7N4zLCIvDQh*> zW2mxwG%D-?V5P*Q+6{XiqGX>pRPSZ@+!we=<`WH*C~uUFA{f zqqJI%9%T)t{b(XG;z89uLv7{9rM6#Hfbm9;;hy(3o-W~%Z@27ljS zpm8jvR=Gf~>&tOlkk;*Gx$=&gbh|BWnocVtPg4rbvD#q&Ku@(0-=l|)XQl0q?&cFK zUui`h6a=ta;EM7sZXfZGx{B^>qZd6#@0$_?_aa$JR%RalgLoF3yfn@?zOtnC8%=$uZmf4ol-6|7x5;YJOFnReH(Hi7Zq%1B+@)Cm+wMi-G z{$LlLv>(TqgG6r=DZ8IY6iK-kR@&2Q2mP@qq;W;Kq<|friwle*hNXiKil%!mQ-MgU zwQaZ4J`#U+Lb$AA+^d*&NUJm{iTbD11#OT?W!tQm%=tZs?aVPz^UEG9_f$T`r0{oftw@7wME@8R#jI&At(>Dzwucm37Q?e(nC=_KcQ@qVGL z$1Ah=|fez_wWj36t7H_mE7y*Pfo?BTi5v8gjE zT475a5-Ohqo!)Bcvy@|>jVREHKF&Cb4W+{(QW8BFAyvY$+*lH1Fd%{+16)i4sDd*f zwe3rtN`MDb&31zPva`&wrvmA?3t)Fp+z5*zo%Jl#1{6geo<&MDQbe(WG>d6kY=Wc) zst#V-K5J?5P>K)`A?VTBE{dOegB;2FN5RmmO@dEP|H_8H|6S?f3WGLJEiU|xdfE?w&|L_$? zDnbq&B~^Liim(-G=-L*Vrtg{VT$Ua9X@eP$e_4*(oc)fPZ>2?gjOs(~-*KP9B1F={ zXYWlRLhp-^wa0&2bg9vyx6;uDc*_j=tN@l-GMLVrQga_f+3Y~Ng46(0u}g*1=VkC& zJ>lcxdF<==gSa1HDf>@`4X@3A_mff}IV7xm*dX)!EF!MOO+yb7eth&wdxp@l@n?CE zNuE2PC-K;yDsAlr5^V07kd>ewx-{p{L@Ev$qhXTrxp39;N}WoYRPf1b^x zM!((_;A;0UeI>b&Y?F7AwRs_TIj>N*cu}R$;1#z*VvY7Ux5_0jhIKx?s?4l8bsICS zeTK^t<7L$@uHmaPNm#nc-^^vppSJJ1kluhGOOwFe7^Sow1IQKtyn-;V}aK z@3vZPbmT}Gawq|a#S}ud6d)bQ(Qs)0=gX%N2{B6mY%6&$gjr1#*96JJj)%z*#`qb5 z%&7Vfvf8;=ha!L!BnbPYKnB$cz_4QryVu6gd-+2i!C*}|Xp66W*bG2i$_oiU+hugD z%{o8l+kK|Y)DDPH^)-h){ASroCWZK#+MGHz_`?1r9U8OFmEz3(7Dy*5a>a>byg-4a zu9jQ}HGt}&WQ2D+N$T0xfPoKW39P_Rk=zKu$3S_J#lxI@`hz2Bm1WHRG$wxF7XUSL zeMrgxx1>(s6BnK;NmB64V@5S|))oOUv&@fMRoUIS5e;#Za!qAM@krO%r1NxP~L26)rx!BhOoIUl7Vz* ze~+HMnIVr@+Vt+)mQN9&yyDz;Wfvsq5d5st(dH_;;laQ`JS7+P@N?xN*V=1{n;%Kw zFR^{Eog@}IP6l!L8?rr-Ot2emuaiJhp81oYzQcPxu*3-LURKl;M$W~=0gLFgumYh8 znm1@qB5>~a+eBI~1~h2J`Cb|#lATD79)nq83ML7vuJmyX=JiX3qIxi0RgNiE`kj@} zJYs*n6`{LOfgHbx5upqB58jVu#mY({l(rXV@NE@URA#8%a}+`sZ~%zj#PRP z^=}OYZhtIN2D2NK1NzAAL5Dk7zQ-3{fH}SBDZAlg5mY88bjClq8pMuyDRdRHn!L#y zZEEt~=bA}qiCW2+>zH|=?jm+A$wWfP2mgEEhTz_Dau2$GDk8=VK_CHeQ}kp~S+Hjz z-62bI_BfAXXdA9``Kb{CRCgjw(%!){zoh9+RZRPcwd{z$xknr_B917+GjVH{+Lg=4s|-y@Kq zLI^MiJG=?XOP2c3jzy(=mK4yXzw9)6v2+N#yYtTtiiFRV!i~kT#l0K8+d+JW;vO>- zrp$i7Y&gb}XhZYqCE@K^ZSVsWS#FA&i(l_>?ij7qDG74}MhF`rVv59gY!<3u`}giH z;JBBAvT1l}poxoprwmLw<@%cRXg1IKV+Bxs?C$*yE@v7y>iTXMYu-U7y^JU(t1)0LZ(cvw`z+<;7gcdB0qLfGk#Bqtj3sx|%h3Eh-4y&96)@_f1b| z0BYv@`mt@kK><>Ew7;c!xq(mhC;&Nn1GL37>%DZXA*TxMyA1Ltt^-L*pv#;OTah^H z9lc9ouEXLc=(0^x?m^QC_fGz|_YycPEKv&{`ICkWc_(|V3qcX0^(Bfu%e;MG&WT;uTAucaIt`O*!Tq}*kyM~1i#X=QX* z2lmF#uChR4)?Erb6eyygtyj2fm@h%#=u}z$^`9Qqa-l=oig(f04^$w+5e2785=;S7 z2x#>kF3J?;?=yw(Oq3L7xdf`o_L6E37C7%>Kr^Yc#pf%LSc#o0rbNn6dSI}k_-A@f zzDBq)Fj@ckbcb@fSZ&|;diUAw0BQGC%F~)_^62BaQm(pwYsz)Qjj5Vgkc zY6mErpL!JYD1uZVK>*EInlpB#hA!^UtRW3Wva@}h<#b)5>G*>9L37kb3R~iz+1D(? z8@{QtKF2k0%Z(Lz!D#@=eWp-)HFgD_$nY?nb+L&Kl$%;P2YICNX-Y? zz8^6`2OhtPf0O>!ZjW!@NdNF4*HbogwNBcAmp|>JO8+{rHW|ACf9c~p|F0U%#{Zuh zOzwK1?k)HDZpcT!Cr2|6b#mi*no6Q_o&?kz?+xEvc`NgNvwl!NIwT@|O-6Q|e<-qA z>6PxLguz*%`41cmFi&_5B=IhG7rJ-TuIi-%>W<4&+yYnF9b{>>`oun$F_4H_VX~sY zO$6vPbS07uB%&`+ve~{+*#0-@V&=S!AWHT{D1AHqBFDu+@Bx1G)prv=cK}w?y(_X( zsvnP7sC=jbA=GX{2yTm5#09B2M~H4BnUy}(YEb;9{=H}>$7_|2R~!~!@PKU{a3pQA~E7@DZ?@;vz=6K ze9j0q(Nc2a6 zay6e$KBz&C?^6*{5zRy>3N&^*ePXagJO8Sb!)eCR z>i`B?581o7O{vN^S2yIfu8n)Sbjxfvv{-<`S-OOm)Prd8)oW%IK(kLgHH*wQn1CwB(} zDSU%PlyY!a20Dj0#TS#5j3^3Q#4gkDn@Q~k+cT-r$RrYfV4suJJ~p9a@&d|12dz3UT;-s& zq0PsDTt2p8Fp|Dx}1WFdU#Z29yi3_%3S{erY!-)j!)YHaytTCUCG zfo!CMHO5om?06yc8g0M#egl-(4H|s#%8;o4?1pQ;3Zu&Ono6e%e?03Ca>|UZla*Q3 zjnfto8$<|#mSsZh@;X4zr#FAe$nj_E8R^1;ILp+_)K z_t~8pY7BG~g+?A&C;oz=$>_N!m5{w6#w-Z7PRw|>KMqNXkadAC1d**&qc6J^nqKF! z*?XS43n6TthN?{fw0Ts*3MtZo4ex^FqGp)5-$f1pvP-c>8&yageyDifkqXDQw0`wi z0&fhvRw6}kKGYQxm_M~784RV>_fB4cZJ2#O8DWzcMfZ{cCO}Z%z4#eGvU+M~Y1UtF zc=mSnwGp7e05{#0VD_r3R1Lw_gP#MR@QU7&+_!d<+Xq*~LsJiyw|^#Z0|(JF{gvhH zJcTl0BDZ;8XrVDZU{`QSXQQ29zZ$`?~u+qj;?WXy(|1aSx7fYT{#OWCz~=0 zcTMecn=i7j8|L0-dOwna3~2bq%s^xyy8s>D4FijZ=H$bd{C?$4gwYSYG&tZ_I}g2b z_@0tRC6au3O5C5=HrxRqiXdrd&w;-=E(?sRZI5+3F0le`CQPMU&tGb#KEvCf%w()V zZKo6QuD3P0GxQBAjda)I7FH5cLk#mz`0jQlY{K>tp`eq#qeY0-lJG(v0E5*{gTX7urrKIm|ZI_QttXvt&9v^M{S{3R8T< zu;a#e%VP9<$s(C%Pq5;H$5q&l(d&;?jPWtb$Z&`u!G=!}G4n4`7(DwVsUV6+*xNp@V$X;B-oiXu1 z+tWmZG#!>3K#DyDXdMe0yb`~H0bJm(`BFS4#~nS-Ha4E^jywqDFLMeTr@eB;D^au;Nknty8&5$)uy`6iz^89{^DjFI(<~pC$YVod{v8+tZ6^qn)DF(Jkhuu6k{- zkkba#mbM9u6#zwrMH!2)n?DcSMXCI9v)XUu9EYQx{Wol_U?6GRFQ5uHi3AUW4W-*E z$VJa*`oJhphN(f&1Qr>eiibBPItnS%N!wCWt*jirY^$$Pr!J;BssD}#R3Negw&bf6 zZX=|YcnhV&s_9Mry)Nq~@O5=L;s(Iv0|6E0FJTrg_7pb!st)uswvg5oiOFe>E??TTEzk)V=7XU*RPDWwZ}Ce zHl|zvo)-%#7Op(;Wy@!cL2O^CoV=ZJ6MemW1bMP!!Z)@hFT*eV+eAog9bkJIvX=O1 zN}}_^x}TxC2;F1wMu@%w*JS_=@yIgA`5OYq9kMUcrj`yXmzr`Z)_uQGD$Z*is{)PI zoOy&U+ou{M*w%GA9IcrhwU*>wQ(7BJEypB-Rd*~uZ}@-Odh4*LzVO{!VCZlN>5d^J z20^+Rq(MRjBt}34q`MmdkwzH0Lr_9WLSO(1r4i{yI;26uck%t5bKdI>{^Xk3YwbOI zX0P=;_x-uCHrl=55)SM><$L_bPZiA`Ak|oJ^huiGU7r{@(m$!6#keOC7!bA~ zvEM=)aJ&DF23 zckKLS!2m!ds*2OS`Y*5Rp*Qnz$VK;HcmCb+-mq>{(KSAp6fqgsdkY*2z1zZ3IB+Y0 zIk96o*Dm!y`74t_JxP#{QUQ(qel6e`+!04uMT+$r+51EB$9*^L`9OagHZTD2hpOV( z4llmm_EnoH;TR5STu-0LqE-|Q!7FC!JTY-3OhI-`(SMn$?5UP%{d-k*AsrhS$kve%KzAK$Z03XuVm4T>d0MfPcP5i2z+Jt@#vfnOKa$!2!SczCqwz!mz zu$){EO&h{rY$B7Uvy1b+x7vDL-%!c0p5Qu-l(ZA*tzWC_J9;p5H&Hs;c;5H*KL|J< zh)@c%Y}RXD`>q^Nwt7$L*^8s*B46k~d{2Xj4<9p9toG2dw9+GQ(Oug15lO~+S8XfS(5=-?DkkuL| zF8gj}tp-7W)wMaAKZJyO-1&y>rmYqcwrc7MrWNUghhbnxQU$q7JC>D&MYM z?Ek~@rmv*B<+pa zvZRt^G(>dqDmXp7I`0nz6^st$d6ccT#6}C`aWk(RVAi``NvU#?%^E!2%b>c-u z(h6Q5WQnUieO7bzFk0nXEIMR-^ z!~D(KwT@-kcb}tiOw)w^5 z_oj-)+N%Q}5TPd9{8RS9_KEzc56KWy_`glD8)i*r+tAIHKb?>61e=F?i{=>U6@jNu zp@-S-*a&>MZ~gIm$vLXl0kGJZvEgvtFfZ<`4cE#n+Z-N4d#nZw()4J!`NQgSdmpCv zd~P7MOHjd`>Je_+Mi_lw&rpH?p6Y!#HQ_)2YhU<0FGW(7BLt6oMNo0gdv*Hlnpv~I zB?7^0mQOr3J0#rSEhHnoZm+rA`?to#b9F`+>V>|#ajC30CF0r03<_E=DisMBznJd$ zDY`*SSaJxIgbyEh&wQ}Fk1AflR#8vU`Su~ol@j;0k%ZRR-6J0aM8j@92hYyJEXlYM znf;@SGRjSbo%d7_KogMsGZXwnYI`Hb^>ImR@L*ofCIMG7@}1NQ+aNRQ&YwDZe3C@wA2LrBNLg#B;;OLH~8R^guW3{ICjT{cPc$E(rkqYz1M>n2*m0@ zgqTo09sbi3DSM4qdq28w8^o+r*E5qHm`--a5%{Bt_*S20O)#A&w8(IDgSHId0@8X!@!Yk$mJfTHSjezsH)EGYYkjxp19Q|95sH?{D$E*62 zW*OC*{h|GI4&rN!pseO@EjcR` zds5;)Zaa42kYyS$#^4%dyQpu;h61(L)gNXppD$unWFuM*zV)7kA-zZsu{u`YzkQ4c zd!w-^uPG^;4|n?DjgW5s@YGDGHKom2Eiwl9KYXTeq+6K-dWp)lJ=A?Xw>T$xK$TDA8$EXvs33Ln zE^>|OgRQ33l>SmTgDe`s&gbWZ^I{pP>r+wJ6cQDiTf_=H?tct6NYjVv(dL*3&C4x2 zS-;XBn|%SJuA&(Iat%JxjabLvNz7VRa2xcyZJ;sBJGz8 zx!kAIY*T;uKgW$)Ly3AkEW0}yOXC|m@nr=b!KuF9slbN9TG_M1NlUKEhrId4Y-I=g z@8~cTN@hRdLA^yc!|_=VPO{7Q1|WlIe@sj?8^;#;Bw9-$4WQm$u%sbPU%Qqs!zb=X z2}HWR!Fyc9t{)O5&ZsVaX89rhz?#}25g)XNC=>Bv9SW@fQWshzo1js5x!_1HQ*Iz2 zQA^Iy#aZCPUjK?ml~%uyq6_EHFv=gc4q!Qdz|e-`x}vM<>`hzY+}-_cq`5k2ZZ#>6 ztRSz6+ir+4vzELxM6Dk-i?}`)^d5A{S*z)i@byK7H3;Rz*qlmJC0d5ygAGSHR#5zT z$kn;an*rSm7?_>4_&Ez(qE@CH-C%*?JEi+YNCj#H-c^;w`?qp0S<^w0rAs|LZ5_Lw ztIv6NvdkshGC$dlPPQtBX5t>w@U*6qZ`}F%*NWGvxW?)f>g;~c0r|N?yc%4mIeCXs zhb*EKc`q5L*va_l zMaj_`b&Scn@Zf8DLM0yb$I}jlr*7wMm-NH9^~#k1FvCk((nv%;gd9WofSf~ez>zM=lJ%voEn4IF=1>!;lGw4o z#Li7nM@m;neQC)@9ub$QZ$QWe4G%g$#Hmspr37>Pw?&F(a09Y~bF0%Vb3$mtHywIc z9t=UW;DBoyJNPYiXJw5-U~DIl2!#tJZ~>5!y&Z553~`f2LB>QHQ!FQ}(l2&)UsK6`^@cSt#LA0<^Jw%XDx4MNVVb=?OdN62T-Y7JQ7`uCFu`P1MU?B?*j@ zYPem=OT8qMt?xr<(ll-rCRHRK3wf!?4IxjHNJ#6z2^LfrpJI-km#RP# zHso+2r7PGNbl^&y@2!LF!Up1W35yqSAG4?^!+$q8NrrcYUz;-Won-drQS{f9G=t*) z3TY%m%xt7nGVwP`4KW)_TQPfbSA^KZev}#ST$ZMIqmYa*eo$mhkX%O% zt+CE{s3Z{*wPg7v`%8CHtdOW=_s_gLVM@eB$nS{!dkiBvhwCd~lRq#QGp}oPeyh0p zi=GkUNVBM)C}KlRGR|;d^~jk9xl*wYuqSYVwfm`9Nh1TKb5@jrrO%S?QXG5(?!QNV zcTU_*)s7d?!!PcibZu&_-8Eou4Fk-H5J5)?s_O$3-j{6qlNxSRRNwX0hvJ(* z-)T=nqc2%vnPRC|)xq8Uyx);YR_6{Y(V9%6ReBDJom>&gq}bnW>L}9*045hY$aK3E z&$hL{=EI}Xg*WaxX`hloMjS=>N`pU+nE}Kx8juJBF zEQ81CwV?j`XVLU%tOaXVochCEiNI6ZkWI_EX2=oPYHpbB_M!p7<~s#)AwwcRqZP+ott1QPZES zXN&8~?$ex-mD?|=Z*V5HMytMNogN>KNoc0L_*_YRn&cY%S@Gdt)cJx;gTMVI)CdhJ zO^k6l(Ws%ayLogu*9jX%-|K%aVFWE!vE88omMyEaGHY`>C_YJV-2b9WjOtCrXbyd_ zSyvy@h70%zoz>p`Tw*s&I?_D5QU5PGhybeavGbq7EAzM1UBn@{PA&RKGx3s04vh+I z81UW(hzIZ}@S!qTWypPBme9!xrItQAhejZ^G=|F22Q()=+MXZQTc=k(aTFf6oDayH z6ebDW0(%y_KBj}ticlO=o0P47{wbUZh^qILWiS3XHJ#&j+dtp2UgOo&UiMrsgO#y^K6?Q{5&JdC#Fn}(w}--=B(dM2-~n5F#ls= z3aGkBt}x$qJ%mjQu)M`T);&6YLtD3{U($dGdCTVq{bact&h2$#upr>X{AbSL66{VNBV{*~HWC|~4zRAeEq;^dth(S{_qDcSe! zFQn_qxloKfwm5aAZmW;&Y4qXm2lk)pd#O+5VUJxfeSN9(ojwb}?fUfDQHS9Y;Vm=+ z#SB_t0Gd(zA2h=~&PfOM}XV6wSmBAB22;rOG0IqadRg;2Su`4U}YgN6ZTIOP*4jksP*qg-_W@9iXSP zGVH2f9Zjvi&-O@N_qbdh z4~G|A_(n{LQ5@}=k>@IV&ZiuOD1^eTd1YkmW_9!z6=GN>+TimArZ#RI-VlDLMy<7k z*%?$*KgPtK_OWAybn(s6NsNRBjk$0B7HEKWLz}5DHUj6TKh8THju*YbkVX)gM@iwL z>FAZ4f49VXO09Ff{9Lb|SK+HbX!YdPF{fFi5Z+{n^Jys!AwdGPUt(Q3l4&@+m{fp+ z*6&N3;nyryIq%|jmb@61RAC0?@G^KUQy$ynnf7Gc%^cmBuSrc!L__yt4pSLezOG(r z7rZp@m4&YsJ?fd&{hjO}tDNmBc_C&V^@2TC4?(OVQ9&yG^}tv5$+Is}5S2}NWV$v9 zi}$!n1X7KyJOyN)ccveiCeg=3^+;AFPEk&0-EkcuR+G2$K5QIETAD9W1t;O~Bb zFSF4V6_?L8UX+71#{M9ram}s7$L>ij?7eBrCsTj_!nx<)nVdAZY&ukOp zaM_?L$uPlI7fc3U`n)bN^=DiricT>aXkoJ)2D=kLZFhqt%j5*IxDGgurN~0at?gD?hER5pD@YJU9c`#F``E|fVOl{(g^gg*$Y)W%czHUO zxGG~q|1!OZUbYcM*33LZE^CAud_)!dF6~HQemkh8Z^i|gvyx~c^d!Y;`EZ*}(%tx& zcABP3A`%le4nV`;H~nLIasQP)!t&b}gRWzkfolr_h^~`O%dVCKvadjA6JB zy6-+QZYscGfY5?_nrx2WrDq`N7*xE^<0fSYUTSPZGv4M(^o(Uh-lr!&!W|lwiTqBb z2Bmu^6mBtqccAR^ZNlS~Y@-A|<87NfCk3}*#cCBo-cr}xSB?A?TtYbQzX%o6;b-v- zZKpl=N4OuJi-oAzdzGX<54qH0<3@3rETeJj401^DxPpASDyjeI;<1DfNsH+*WjRkc zuLH*lpgbbAA5yEL>9d_mt~!L}USO|GI^B%`?y9iKKWC(T(05GxuKOp*iBct9I9hpd zLQUq?UoMfz*bpL$_bd;>R_W>wlp{b3#EnxKqK5w<;hqK_F$5PQw-e9jV)^fge>T)b zG?L-#Z_EgjaE9ZF^Ux#yA6k&W!*{&|u>5PVU{wHh=h@(Y7YfC2iLrJOT7|1~;LK+@ zhzQF73x-}9;;(3dSp=x|0@K#dqm0*Ii=2WD8RMe{mF;4+6%Lj1td3Z|{T|<^``L^^ zRJ*5Kh)ph(D(B`+OeaFg!AaHvol1M`#}G1t$5ya+81#9RJ{VPQ`DEfpLf6ueILyZ3ZdqhHQY$Ri&SxZp2#$FXZlk_j*iuYe^Qe^48ezH zKm`dp5fPlI)C`)x(NNjqSB@V5d&w~>3?K47IIw&l{~7P10Uk`v#>fwozF^o&9IHOX^rD1`I*ce}CdBPycH# zp9>p-hhOZZCO-Mo5n#Vy6A9sda_4ISC^l5xvLO6S=e%@wTOUt*i0QF2U0qrCRdUk! z$Nmd9d+sWciNR^kh9a|dnEB=uHfjXb&@w|P+yNM1tRi|b`&)${AqUeHaaC5~3*VqN z?Bo=7h91E<=f>*5B}Y3>q@-&GLe604x=Q*+v~sSc+j5!hvi*-}#goxh#vS`R73ctw z&kTb(L`O8|?_mkqJ2c7Zw+NhwlxJZcA^#@vVCRQU8GpCCXJk>#p=qlusLcJiFbq-} z=U=S3n3;3d-Gm==@g z$0vmn>(TddJn!OvH<3C+9fK)@~tha9k5l7 zP>LEl&a=UX9GNM6Ts~V zImfqp&~vwkKmP^68*UhITyVF3fCdYl5hfuC#40aZurDX&UyOgy+8yc;dDjI43=4d< zgXQ5z)RvSGA%qTG#jhF|=p@r7QRZR)l-!)&-FiPu*x;BIKPWR4@L@M1Lu_YhchQi^ zyA#%o_s7TkU#^{%C)rltgz?=i;V3*{B$h#}WEoFc@f=h*hKd2OP6Kq4Ps@ z)SbT1c;q*!!axTRAB)7CqOvjzWt!w4sdn1)!-uu|G>RCeMkD_+3~30((NRE!*XpvC zD&F2R=R_?wTkLNA2X_Qg({SW&8ox=?$6XT7Cm*5e=#P7}69NZbyYZ_1_RlVDwUJKsR|zaT~FZ{twA!AsWVV={fXQIlQNA$midp} zf|4YtaUQFcHp3Wp28RAx%W+i~V$9PdE$X$pr7wrK%$ygi3Q3aCR$q2MLDho(;EX+$ zFcTJ%$MKN{glpRG_aMa&#f4QAKQe2`LHclJRD2^EO(A2I5iF1aJ2ur{&xhvC27`rF zsg}AP!kV-cI=U_%J%bCb^Wo!+I$YS}y<%03FaRY;TmL$ev{b%gYD_!|2oa7BnK}%0 zXY)|B-MRnzh3?_8V$)(qPx5OFD+ze>4msJQ!G}!)JTKB7vuqv53|I&L^+CM(kIRBE zR=nEyoMj73Kq|x|KK9!)`-SkC8&JLw{>IO+O1~BWNKB3b3yJ73;wN|2yqR)E6pV35fRW8()#BhwY$UTctIvHG1an5GiZllOEU zU=zTi9*jCy=7bo!fX49fK4#L1a@r&z%pedrQL1)|X|wzNzSEG3d=RT?Vnbm^rYr&!ZE=+q zhbb!6A9m=+SRRo=VEm8a(zKVblhn~xx{t-|>_o{~8;=1L1}sAa<(m(HCHa=kX7TW2 zM2JmQZHtn&3oT@rKa|M3F)bky?_ec5$B2!}hmVLzyT2^8VPc!M@s^125U_rU9cr6H z9YUeW{y<6k6k+Y-+c0 z7&~3|lz#cs?0$zU;XWcrQ{Z|JO!{iiXadCnRRNzz}$lG*bIL`xZ!-cLd&ou+CwUUpC3Py4V)Bvq0n3OLLi+9E4zaEgch zTym9UUqhPX04f}Ei!g0SNG5ydJnd9}%P+&*P$JV_~x+TfDS^<@k7!DLa9xyMZkqgBK!zn0?T0-O+_YQeW& zHU0c){yC4#t}1)0m+c#YESwBbQ1TcN+W7!cNW6%46`BzFpRasn$dcCF=vtx^3; zxsPo!WCKwK_B~!Xd`%K%hbYwvO9>c*daRwfN6@kp;%tzBn-F3cu zRL8%rfm{^`(GhZs?w~R*8GjWt7<-q$^0B~v>5xyrA|Nkopfv^l4&Ca1i@ca4F?~u& zfl5^K-aEDoS*Rjiz+S=ifUS$wygG*nAaey-zhCb8576`UofRfCy9vBmwi_pLcFL>b zdGt%;;*IZs&P%KB9Uc(-#SpNt&pAN8w7Sc&d z&{0HxotX2$_ON4K715lZt=ssf^&b;yp`w-$2EV2^hT&Nt zSA@5n{(W!Q!#Q$OwWTi$;@X0ew4`Ki*#>&w4E=P2;)AI>iDkcuD;@!$ojSBPml~@? z{2LWZLxRm$l4s6Fl?eJzj6ds;k@&ui;RE6Tm667QinuFl+-1hg9^Ei5ct?_j@mUK# zscrP*W^xhu2N4CFA5&MP0BRHwKFI9Pr#B`{Amlqd;}$6Q*6TmOes z%(iDPR^DW;mI`NIQuBS3UmZ&|dQo!OyOQlL1LzzU-5?NQ5+pbaiZaBS?4;@9;nSkt zEuINFwjrz~H4fi-%o_O$KM0W2d2?Utys;j?Tn*MnFI~W`pF-x!0rNa$$gJ`@4hPY z*Cn-PzudkRT)SB9rA+(eDK7}I(!HUtkb9X7YP0BA+JrtakJ?>$TZuR zSWkImYFrX^Aq~ z5c|FL+5nJDlJ@FvkJV4`@ZHKNxY#WW)l%BVqR^w%A{#uss06me9s#q<`H8;K{8wHR zUhC?ulDV9E%BEa})@s_$$IuwoiJ9)7GtC*t(yd1pNhFa9A^6xecXk?ol?VmOU@@^F z=6!ub4#H!$#3o&{4L2u6<0Rsdb`Mc}S{3-&VpbqPmLN{q#rSAdq2~ zkDY|asB5}Jgcvg4+$e_bL6QYLjJHPg{PP-++`)R8p8QMy#pMW!k`4$2ij`Zf8>4x{ ztn+zJ$K#L5v?F*FxdgXKd-UGm5?BSti`Aecg_wi^;&tVok4LiQ|5jaF0M+#ysh}3P zn8+vfv?fiVxUwkxnS^~$W#(hLFfwwp=*OSeU!UK?F@JMP+`<&s?2C^8oIqzG1s;Tv z$&$HD{=Y+apz<12iSCAGj}L@B9NL>;`?~#XCzxz7d=T_tcv^3vKIPBQ>I}WYp6(7@}k0FIJ6L zB3nK9k^wg&ID^QM#)Aumjk8OBj$SR`dD3l>Z(D+Dzd+;XXW4H4O7hXj&RHq^HnC?| zYvkYZyKrwLy^=)k;hcj|*AiGHaL_OMj09p#+u7mlC)3$&rIv!!b<>iwNTe;k2J3A^f1WIOnW|gqhUW}GP6Q$ z{p!8FNVeUV*BOY@rMnZ9r{o|6;86PRj+)-T4v%L3`q?_h%NHgf%*SMVRmMq6Rno0M zG3V~4LEK8lP*;oR*yyLP887tLomM)FQy)3tzdy`tep$wz$?rOFSg%u}$R7^186AASvc^ zx0H|4ZHwpMmVW%Nz@HHnc8>t7w+;4C247#jc4oIzA5skvSE6-FUfuasJ>BN>{A`a1 zsfl<_&XSR)^I!>!HZ#R??`mec2ZUTv(`nES?PYak1(fLrx*_->gv_)?4>tSiNZQZgUdyf~OpBwVrI?&a$#|wrn=H9vl&r(bJC#^_T5RZqZf|j3EY-vKo)>>L*r9Ij)2gO-cVnTgP;&Y#GfZ`nWnS1 z8)LX7Cl(n?s1xKD|17pIQcV9fMkA08;1(=bP z@$?=QcH|+(oupd*OLj7iqgH~EH{Acl^Blf}g+%cfT=DCkyt8M@)O|%y+S#?W@vs#H z!hkY%vypGHx~OO72d1a?gCd)wJDF5R_TS^n1zQXe444E1gHF82H>vBMF{>_Y6!wWktr}%fH+9}oGMf$JJGNy`o@-5$H zCrdf|yX5GmzsdVM&Z`-H&SEmUYLJEpt3X%QrfdI*K$<_wmaVL8+{UV^c%@+PjyQH) z5G@5FykT#~H+l58Hn~9OFo%&}64wV@+sKW~8X#sY^E_?XbPw>1)Q+|=f1YgHCNWz4 z+5t}$0`TOypVq+MZ0m@=b8ShTTJ}82Jv_~rwxS%6QwWIqD`La@Bn&ArLep5Ea-k`L zPn$(ZeO&vC3op_P{kIz!QwBv?b6HUVI3v7>O|q17q?(M(!UoA{I%F9mY*rNg!@X=Zw5toqc$1}HK?ypj#$g2=~+ zi>Np=d~LPlQ5Mx-GrRc)BH!)>&gAo+*<{R$?v0y9tWZddYV(Ig1>c-A;5bZ+zE4|m4ZBI6VJ&X)?4BZ74j(jL`?T|FeIkzW^Y^_A=0~v=N{ZaUUyMz?SjTO`_k&mLE zEL4{z;O9BPVEB=y1M*b+$B~fGTPR?6lpB#7=5=&`LtjD2SHcBP#c0S1>EBexJ~WvM zf8UAA8Im2?vXJ$N5Qk+R;Cmh(&od4+?s!F*HjJxsvg-jtzuelD;(n{KoFptZwDIf^ zI}8Bv)L#aKTomi+`hl&jqnJu0-SnRXGqcM)`8q4orxi07lL(uG>#q)x64X|>Q$Xuo zcg!in=+kBXJVjWw7{nT21{_=0&}8?2GWnexxfY!A&W8(zsf>IN8i-RNQC#}0<{%Aez{x1lOb8V!)z0M(_w|g*h0*1B%0g& zM?jQwfBB;+P>DO#um94_26OGPLnB%&NQEb#H`9&(t=WS>BFUrw>5QslTm2UQz4}Vn zus48OE2J3r*z4Oz*c7vc%!p)ayjva;2XFJ?Wztb##ZM1y-gkoPuimojXIyBysiO;v zEQ*o&6j6TbucEW!#IE81(+0lh0=Uo8I>9?e;OYxf30cLr zEoA?`MV4dXEn9X3=Nj?kGR2U-Tn8fRK&vFl(wU)Q z4+Of9LufS$SSi28ms}BP5}zX#h2#qaMLs7l7EnxRs7Qc$5WETFoz^WWe@B3=7Mq%` zT*sVW)<4u2^}@P6NSYKwuS=ATA)9sXlit^Q=Gee!v@y4FSi>@etL5sndmjEu}~J=JgI@GexiP z`rPUhb%TO-zBsfk5`;~HiNqo}8mA?;K+HqhJy0IbxjZn+q0K}+smltT7XROd0ef^j zCrIS192COi37UG;!Hgn%d4FbckKOb!T=CAd|8TdMpvjl)&|;N*;i&ny=Ub=S9E7;4 zk@&aEiHjK1laCXOvBR$NRQ>ljC5}(X5<%D#G|1WdE^qUPo3scnxd7xW2R*%761ZVE zcrdY(3PbT=-7i@Gk{t3J{+v*rek+1tr;A^goz7{S{J}mAMh!t=DBRO+4VHu1b^@z_ z8ys6Nq;mhPOp>&w?lF1hI_BZY^dK(MYEn zs#KOtq&>LloM+w1&Tax;uZa1aYC8g$3pRnQ3=Le*f7eQ%tA~ig1#v#>tGxTIt3=HT zb`LZPw~A)jQ;Ub5L;Q)3pnA^$WDOV!+^*)W0Q))D>rBw3As?xd>1#pSEt+I4k0#;< zZO`!|OiBp_d~jV9ft8NFl3`Sn2wGY6o6pB(Lm@PeUu=QXC&XPKAznBS`G%qvoqNVo zEXTusd!kc##g9z|tDs_7PwG%N_haTBJc3ahc)Z(9VV4B+#yNW4fx%2+nAcl^R4bLO zWx5D9WZOw&V<(HYf#K0RR*FWC)v!5$l_OBS45 z>b@#f&Awi@V*2D|dt#O>g9{)dh3PH(&0O5+I>`+kmRL9Ck#rGoXN}!`7BROTZ?|l# zpbO4S{Q1|)HH8@0AD;N+vEn0cYG3Y-Ek)OeVnYKn1{t}%AxU?nfa09MmoGwu6z=()Oz2Z&m`Gi@=PJtYzU@3h~Ku-GgLcXIiCg+-4DU~lQE zBr^2Kyb@V7F2;Ks^fxL81SVl$zMU%4NA89G)3ifFRE{o#px{dYi_B{Qs~jJPqutGQ z=psYSIg(!;@BSXPVCumc@WGEK+Ba~LdCgBbp4GKxR)#`Bs@k3N^qcK&+PRw~$3s3; z6uk(28@H6xvD3|m_G-`r`c?w`NDZ=s89Pn(3FOtu7E{RQs0ANcbeD(@nFhI=ljIEi z;|%M_CUFNIi_-HOU@3RgFwoyrP!ar96Qk#mAO#}e@HW!#Dx>xf(k>`9m|0(#OF9E9 zVih(f$|jsbW9K#D)3WXQiHskoUwi8clG9?5f9JH5AxZH-{`wAzdP6w)2Y3-u6D7l; z8Z%LsQ5c9WN;cW59PS5`xHhb`eUJ`qmB1t7o3;3ZX}8W-kv=D!}bYYm^`;g+!vU&FC}=1^D$eYqb#DXss1a(xu83z>c7oV|tM~N!KlE8r4l_P0Z(nAEnBSO2RVGlA z;-%OW=N5%72zF^CUt8<1B$15K4X(lUPk^_P(O?R3)o3zuiSvO ziIorp4k8atiH;rm9+aX(kP;-&73qCno0um39|oDLTKwa++btun@rsi`ItRP%ZSbI4 z_>kSlCzU&;6J}RwE+xppvVT4n1xC*Urc6{LaSyu!+Zy|z8p-@~SBfh7xybH2X>Nai zbf$S?Dqy^DF#SNI3|D4AUm?fvPbQTmTk1yS%cPPFi=TXPUQW1MU+yVN-=KzS_@BWn zI<((UxnsJ3SS5f|FY2aOo}3iQ4>;|A@MPrYioN_Y$zjJ(wn=f>bc8+#P^8Vs)*Bmq z26CAY!~|CF416V;wd6{TLjQjRY|iWdlc*#$A};j_=l>C@gdhSz&F4t7n(V2<500bi zsxiqAI2n}1cEq~Y=ABQXmF_>e2$%G=Ogs;k`t##kxxW1bYKt*#ggm3*nrwGI>~`#a zxl6KQDFt@sWa=>t4(#(bn;z19Bg%1y{}g9)bJnY2Eza2cjNXf(10}~Ato~Z9ayRK| zu1AC{Iv_z<5sJS7oTXbp%W10S^0*@msMU)4SxSbDMEQ#f45O^DS41$?l-N=gi4adb- zBa2tyI^U5ec7E;6-I9Ub7swC;4k^7G%(vfA85=+{>Tg!6p!g44VUGhS*BCCsDF;{1ZHg8Y_Jz%8Jl z@)O(w^crHsBT_5LVtN?Lc#7QQ(kv02#v_Q!CoeA}eXf$Se0uS_ZOoY^^V^u;F=DzZ zkKEK&80~)jwGGHxZzikoJR>|KJ)@jcyc*&J=87EZV@kW{@vrB79~F-ef0+@YTq5U) zgOVw6p%DHpZA!O|!LmKtGhH$)vyF45xoWJeH?`KWU-F~28p}1Ywg&2Ye*Om$Q&aTQ z(O*y+`IC20E*f}jLWQk3i)`uq=l#0Ir_;M6l@8bKQgmKuUUXiv%VlJNx$N}qy6p1(cKOY>`|{Uq&D`#@Ev5uDIL>2np2)G9Nk7;>~gQDam=o-8%7o z{C&cG;{Ch3$zC~Lm0oRLL#!!Y|9WvL)NkWXS4k@BV{KXFnys2t?(z8y=lf`Nx!Qf- z)r|Jg5_?Wvc94(66Np@Q`|98C>5tN!zc)`e&-8|r1&KX>e_mi-s2r(E57uhUa&d-{ z=v!B_t}fPs_`aCVyYZi6!Qxu?>JPQnHLEtf zCQViT&NH4u_|6ugk_q6l$v|uMt4(L?AHzkUqEr>!%E!&k9`1$ynCieep}2+vc#T#aElrvTnAAP7A%>sT9DYzm5DI+ z3h+?T%2ga@=%CRNY#fy+>%>_$#b-GHJK96cFpyZ;5Uv-Js2n^tKb+pcP)(ns#fZv= zl7VF_d!?Kh>BeG!GLrd$_4;k}ByeZ{l(z4L6xZC=Zd&8CGkrVc0u)sIz~>ecG+Drv zc762tR#!vICsB2q_WR63ctfo2Ilo)^%buCKUXf$1ves%EX{<-w!KF+UwE7@EWo+W| ze2d4#2o?qLC$5Lm%rq{_B@_b$06*dmlCem1oZUgJR%>v zp_H%>?Ax5e&db^Cw{ByW0HU~wJu;7Lwg>tuP`nd}RXBY$*jL40W0rAypPu$*Z!u^0{d|NOUq_@6y4rLAir9%H&pzU18 zTLVpypWCrPH@lZOb5GwQ2?QKI>D>aBwiebI@;a;H5U1}fpo(_U*G}|A_t4(Ia&}!1 z{szQw2s29;7zLyPCE|c|89WwtVxW2hiA}U1RtKax34<^h@LwBne}Mmvf}|Qemasw$ o>?9~aKLH~1|M!h*$$$T0YzJny3Z(lY?tnj4B`rjS0y5