From dc7df1cd0f0bb2ecd4f5a15b7b4737ea5686ae78 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Fri, 26 Oct 2018 16:40:48 -0700 Subject: [PATCH] doc: update HLD Virtual Interrupt transcode, edit, and upload HLD 0.7 section 3.7 (Virtual Interrupt) Add target references in other docs as needed. Tracked-on: #1623 Signed-off-by: David B. Kinder --- doc/developer-guides/hld/hld-hypervisor.rst | 1 + doc/developer-guides/hld/hv-cpu-virt.rst | 2 + doc/developer-guides/hld/hv-interrupt.rst | 2 + .../hld/hv-virt-interrupt.rst | 259 ++++++++++++++++++ .../hld/images/virtint-image64.png | Bin 0 -> 35491 bytes 5 files changed, 264 insertions(+) create mode 100644 doc/developer-guides/hld/hv-virt-interrupt.rst create mode 100644 doc/developer-guides/hld/images/virtint-image64.png diff --git a/doc/developer-guides/hld/hld-hypervisor.rst b/doc/developer-guides/hld/hld-hypervisor.rst index 5001bdbfc..17fd4f4f9 100644 --- a/doc/developer-guides/hld/hld-hypervisor.rst +++ b/doc/developer-guides/hld/hld-hypervisor.rst @@ -13,3 +13,4 @@ Hypervisor high-level design I/O Emulation Physical Interrupt Timer + Virtual Interrupt diff --git a/doc/developer-guides/hld/hv-cpu-virt.rst b/doc/developer-guides/hld/hv-cpu-virt.rst index 291446546..c6be41871 100644 --- a/doc/developer-guides/hld/hv-cpu-virt.rst +++ b/doc/developer-guides/hld/hv-cpu-virt.rst @@ -514,6 +514,8 @@ that will trigger an error message and return without handling: Details of each vm exit reason handler are described in other sections. +.. _pending-request-handlers: + Pending Request Handlers ======================== diff --git a/doc/developer-guides/hld/hv-interrupt.rst b/doc/developer-guides/hld/hv-interrupt.rst index 995912204..0a8c41a1a 100644 --- a/doc/developer-guides/hld/hv-interrupt.rst +++ b/doc/developer-guides/hld/hv-interrupt.rst @@ -348,6 +348,8 @@ conditions: Request IRQ for different conditions +.. _ipi-management: + IPI Management ************** diff --git a/doc/developer-guides/hld/hv-virt-interrupt.rst b/doc/developer-guides/hld/hv-virt-interrupt.rst new file mode 100644 index 000000000..cd0997a7e --- /dev/null +++ b/doc/developer-guides/hld/hv-virt-interrupt.rst @@ -0,0 +1,259 @@ +.. _virtual-interrupt-hld: + +Virtual Interrupt +################# + +This section introduces ACRN guest virtual interrupt +management, which includes: + +- VCPU request for virtual interrupt kick off, +- vPIC/vIOAPIC/vLAPIC for virtual interrupt injection interfaces, +- physical-to-virtual interrupt mapping for a pass-thru device, and +- the process of VMX interrupt/exception injection. + +A guest VM never owns any physical interrupts. All interrupts received by +Guest OS come from a virtual interrupt injected by vLAPIC, vIOAPIC or +vPIC. Such virtual interrupts are triggered either from a pass-through +device or from I/O mediators in SOS via hypercalls. Section 3.8.6 +introduces how the hypervisor manages the mapping between physical and +virtual interrupts for pass-through devices. + +Emulation for devices is inside SOS user space device model, i.e., +acrn-dm. However for performance consideration: vLAPIC, vIOAPIC, and vPIC +are emulated inside HV directly. + +From guest OS point of view, vPIC is Virtual Wire Mode via vIOAPIC. The +symmetric I/O Mode is shown in :numref:`pending-virt-interrupt` later in +this section. + +The following command line +options to guest Linux affects whether it uses PIC or IOAPIC: + +- **Kernel boot param with vPIC**: add "maxcpu=0" Guest OS will use PIC +- **Kernel boot param with vIOAPIC**: add "maxcpu=1" (as long as not "0") + Guest OS will use IOAPIC. And Keep IOAPIC pin2 as source of PIC. + +vCPU Request for Interrupt Injection +************************************ + +The vCPU request mechanism (described in :ref:`pending-request-handlers`) is leveraged +to inject interrupts to a certain vCPU. As mentioned in +:ref:`ipi-management`, +physical vector 0xF0 is used to kick VCPU out of its VMX non-root mode, +used to make a request for virtual interrupt injection or other +requests such as flush EPT. + +The eventid supported for virtual interrupt injection includes: + +.. code-block:: c + + #define ACRN_REQUEST_EXCP 0 /* request for exception injection */ + #define ACRN_REQUEST_EVENT 1 /* vLAPIC event */ + #define ACRN_REQUEST_EXTINT 2 /* external interrupt from vPIC */ + #define ACRN_REQUEST_NMI 3 /* non-maskable interrupt */ + + +The *vcpu_make_request* is necessary for a virtual interrupt +injection. If the target vCPU is running under VMX non-root mode, it +will send an IPI to kick it out, which leads to an external-interrupt +VM-Exit. For some cases there is no need to send IPI when making a request, +because the CPU making the request itself is the target VCPU. For +example, the #GP exception request always happens on the current CPU when it +finds an invalid emulation has happened. An external interrupt for a pass-thru +device always happens on the VCPUs this device belonging to, so after it +triggers an external-interrupt VM-Exit, the current CPU is also the +target VCPU. + +Virtual LAPIC +************* + +LAPIC is virtualized for all Guest types: SOS and UOS. Given support by +the +physical processor, APICv Virtual Interrupt Delivery (VID) is enabled +and will support Posted-Interrupt feature. Otherwise, it will fall back to legacy +virtual interrupt injection mode. + +vLAPIC provides the same features as the native LAPIC: + +- Vector mask/unmask +- Virtual vector injections (Level or Edge trigger mode) to vCPU +- vIOAPIC notification of EOI processing +- TSC Timer service +- vLAPIC support CR8 to update TPR +- INIT/STARTUP handling + +vLAPIC APIs +=========== + +APIs are provided when an interrupt source from vLAPIC needs to inject +an interrupt, for example: + +- from LVT like LAPIC timer +- from vIOAPIC for a pass-thru device interrupt +- from an emulated device for a MSI + +These APIs will finish by making a request for *ACRN_REQUEST_EVENT.* + +lapic_intr_level + used by HV to issue a level triggered vector to vLAPIC. This vector + will update into IRR registers + +lapic_intr_edge + used by HV to issue an edge triggered vector to vLAPIC. This vector + will update into IRR registers + +lapic_intr_msi + Used by HV to issue a MSI to vLAPIC. This vector will update into IRR + registers + +vlapic_set_local_intr + Triggers the LAPIC local interrupt (LVT) 'vector' on 'cpu'. 'cpu' can + be set to -1 to trigger the interrupt on all CPUs. + +vlapic_pending_intr + Check if vLAPIC has pending vector and return the vector with highest + priority if there is pending virtual interrupts. + +vlapic_intr_accepted + Used in case of no APICv support. If a vector triggers the vLAPIC, + this vector is then moved from IRR registers to ISR registers. It + indicates the vector is accepted by Guest and Guest is processing it. + +EOI processing +============== + +EOI virtualization is enabled if APICv virtual interrupt delivery is +supported. Except for level triggered interrupts, VM will not exit in +case of EOI. + +In case of no APICv virtual interrupt delivery support, vLAPIC requires +EOI from Guest OS whenever a vector was acknowledged and processed by +guest. vLAPIC behavior is the same as HW LAPIC. Once an EOI is received, +it clears the highest priority vector in ISR and TMR, and updates PPR +status. vLAPIC will then notify vIOAPIC if the corresponding vector +comes from vIOAPIC. This only occurs for the level triggered interrupts. + +Virtual IOAPIC +************** + +vIOAPIC is emulated by HV when Guest accesses MMIO GPA range: +0xFEC00000-0xFEC01000. vIOAPIC for SOS should match to the native HW +IOAPIC Pin numbers. vIOAPIC for UOS provides 48 Pins. As the vIOAPIC is +always associated with vLAPIC, the virtual interrupt injection from +vIOAPIC will finally trigger a request for vLAPIC event by calling +vLAPIC APIs. + +**Supported APIs:** + +vioapic_assert_irq + assert a PIN according to active low or active high. + +vioapic_deassert_irq + de-assert a PIN according to assigned device or emulated device + status. + +vioapic_pulse_irq + trigger an edge interrupt. + +Virtual PIC +*********** + +vPIC is required for TSC calculation. Normally UOS will boot with +vIOAPIC and vPIC as the source of external interrupts to Guest. On every +VM Exit, HV will check if there are any pending external PIC interrupts. +vPIC APIs usage are similar to vIOAPIC. + +ACRN hypervisor emulates a vPIC for each VM based on IO range 0x20~0x21, +0xa0~0xa1 and 0x4d0~0x4d1. + +If an interrupt source from vPIC need to inject an interrupt, the +following APIs need be called, which will finally make a request for +*ACRN_REQUEST_EXTINT or ACRN_REQUEST_EVENT*: + +.. code-block:: c + + int vpic_assert_irq(struct vm *vm, uint32_t irq); + int vpic_deassert_irq(struct vm *vm, uint32_t irq); + int vpic_pulse_irq(struct vm *vm, uint32_t irq); + +The following APIs are used to query the vector needed to be injected and ACK +the service (means move the interrupt from request service - IRR to in +service - ISR): + +.. code-block:: c + + void vpic_pending_intr(struct vm *vm, uint32_t *vecptr); + void vpic_intr_accepted(struct vm *vm, uint32_t vector); + +Virtual Exception +***************** + +When doing emulation, an exception may need to be triggered in +hypervisor, for example: + +- if guest accesses an invalid vMSR register, +- hypervisor needs to inject a #GP, or +- during instruction emulation, an instruction fetch may access + a non-exist page from rip_gva, at that time a #PF need be injected. + +ACRN hypervisor implements virtual exception injection using these APIs: + +.. code-block:: c + + int vcpu_queue_exception(struct vcpu *vcpu, uint32_t vector, uint32_t err_code); + int vcpu_inject_gp(struct vcpu *vcpu, uint32_t err_code); + int vcpu_inject_pf(struct vcpu *vcpu, uint64_t addr, uint32_t err_code); + +ACRN hypervisor uses the *vcpu_inject_gp/vcpu_inject_pf* functions +to queue exception request, and follows SDM vol3 - 6.15, Table 6-5 to +generate double fault if the condition is met. + +Virtual Interrupt Injection +*************************** + +The source of virtual interrupts comes from either DM or assigned +devices. + +- **For SOS assigned devices**: as all devices are assigned to SOS + directly. Whenever there is a device's physical interrupt, the + corresponding virtual interrupts are injected to SOS via + vLAPIC/vIOAPIC. SOS does not use vPIC and does not have emulated + devices. See section 3.8.5 Device assignment. + +- **For UOS assigned devices**: only PCI devices could be assigned to + UOS. Virtual interrupt injection follows the same way as SOS. A + virtual interrupt injection operation is triggered when a + device's physical interrupt occurs. + +- **For UOS emulated devices**: DM (acrn-dm) is responsible for UOS + emulated devices' interrupt lifecycle management. DM knows when + an emulated device needs to assert a virtual IOPAIC/PIC Pin or + needs to send a virtual MSI vector to Guest. These logic is + entirely handled by DM. + +.. figure:: images/virtint-image64.png + :align: center + :name: pending-virt-interrupt + + Handle pending virtual interrupt + +Before APICv virtual interrupt delivery, a virtual interrupt can be +injected only if guest interrupt is allowed. There are many cases +that Guest ``RFLAGS.IF`` gets cleared and it would not accept any further +interrupts. HV will check for the available Guest IRQ windows before +injection. + +NMI is unmasked interrupt and its injection is always allowed +regardless of the guest IRQ window status. If current IRQ +windows is not present, HV would enable +``MSR_IA32_VMX_PROCBASED_CTLS_IRQ_WIN (PROCBASED_CTRL.bit[2])`` and +VM Enter directly. The injection will be done on next VM Exit once Guest +issues ``STI (GuestRFLAG.IF=1)``. + +Data structures and interfaces +****************************** + +There is no data structure exported to the other components in the +hypervisor for virtual interrupts. The APIs listed in the previous +sections are meant to be called whenever a virtual interrupt should be +injected or acknowledged. diff --git a/doc/developer-guides/hld/images/virtint-image64.png b/doc/developer-guides/hld/images/virtint-image64.png new file mode 100644 index 0000000000000000000000000000000000000000..3c2186073a31104ce784642258cc1802f4dee7cc GIT binary patch literal 35491 zcmaI8c|4SF`#wIBr6j2kV!YcEX+tH;RH!7fOH4)frLvD@qMf9bqL4L_vBcPhC{&W& z*oN%uSjRTZ%=a8KdOy$edHsHW^y*b^_kG>hb#BLT9_Rf?_kt$>TCueV1cLwUnbUd* z1m^?-v1)>M75q=}xiw_?i^Ek<^CTke_tqi!$7&mtHVT2r2<2P4$_4*kbK{JuD+006 zjroV8!y4&@Km;83<`5#kUUEU?R$KNI}gJ5r{K;10~OV66gHX$e$v1d``u;V|t7hAE|CV zIOm@~5<};19gp_ZN8CQLZ7{$Mqo5N1d_;WgR@-;!>$I?*eco>+5qghfcpLH@fd4*&q+Rp=Rlm1fLkX?3@E@&dla5Jg=&n$vpvNTw;TR}o3*-)>YQ+q>`2l~ zY3D^eJ-%A`>4nu>PcA7V)Pe*lYR3g{@J`Ml5PLOhIEPMu`R7|FCnA0eN+5m{$Ab-6 z0mRd5|N9F<2mgHh`0>)EOYP-6m0_=XJ0z~DZ#eZPxQ^d8OnS=>9Qw~y$^OM4jcEh7=f?mFJjLkDYI%tAB<*5 zVWQ-^c%#<9jt+~+xx+@$5kwAh_aVPGI4k70)&$YEkxflV)Dmq2*0feF^7uaU%aIB- z=RTpctV7Io-BxuaEWK(yr=MOqEz;nbQRd;^dOh-*Y8-=uyv;+YIiBPes~tiM?a{Fi zsWogXbHWuLugzSVQdO(rWNoDEox5$=MeX&1U%_UG3MN7U5mkPt#WwN{Fs|g*>U1v2wBW&bReWt zsbaq$e$%D`3;xoXE|Y;ct}e3Fr7Nn>JQk4JmP!i~^AVHA_IJGhbIXmwie9U8B7Zi; zTy+RS+xhwhsXl3P_%n3rvjZl5xIo9OGg&2&+&ZmfUi82w_A7OIbK7RKKe%ltl=psc zLYMnnbWSIoNciJ>0$Y-NILhPh4O%{RwUemwDA7Po&LWApLAs(EpnzpK!H!5Q|$Cv^Fk$eh*$B`xb^!%$r0(Ct95B5@U)N1{2y4%gaI7!OszTq0E~zub5$8F-xl!z^Qt5!TX-s9w@06L0bq9Ks&3t zio>G?nU996)P@Bq2))56QZ3w^+UoUZR+Zs3Qh&;mB7gLFmj@@}>9*C%w>M+t4<o2A-e#&=vF2Wr};Eu=T>5DhEP#E;5bNL*I_)T!nce^?XofH?6(KO>$DzR$SasUtN zZ<(*@dSb5h+o>I*d$i=IpZ&&Tqf|JW^~GXtifg5Zi)SBSs&V*}2zQ3`P@{e>E)9((Js3M*p-j=pEsv?;dt zEp3154X2NJ^19g$x*G;t8+s`*axYKQBm{iu&sV?NT5WXuSAg2cofr#IT3f;Cxy(U=x#mRG>PP^up1 zTw0K_CvYPd!SJQr?%Kx*k*}T>=O1|Wiy}Jn;z{DU>F}vLqSFpTdRr;6k;aNK&d2fZ zbj%jXgBm%Vm%JQCgmW@zmz?xQoKguMExNgS;o0a9)=Mr%#Mq3!>>`J7RgQv~qP7^R zcOf1v@0ZpD)A}B&BC$6Zn%DT2n$u3Y30)Fhf6~K>f7Hq?fy+j|Cm|>}hUd0{^pf1x zbl#n7F_jYN3$Yp1GKMdaiw09i;wmv7ds23iGgsB0_a}Es{*zO6?W|{wIB7JWl(t?Vp3IMxD|+0RsSu~VZ%FixfBF6OSZ%uA@rUKticLQ?nB1AjFRee^g;C0F?tE_4 zDzqTq_2ce?seLp8Z|(UK_p|egb`Pe)<;8T04Q@hUdwLGL=&~l=cIR4Z^YwoQ%XYiG z&YKP2a6hwomF#{@jYBy1@ra_4KlJmZBWrc4v+l3=9OCs*&rjv1^U|$KZz$$yiBN1( zIH?%}pJj*+~G>kfneE!>|b;ERmOZr($D3b#hQ|3 zKUl3X9zJ^2rY(Nl8rjm?z(GqmlD;*3f^x!alo)J1I`1*%@jF)D!~D_}&gu&tjQH3$ zH|n2^hiMemCi^1Cq;Ew!qHs5jLrEEPWa*bV`XI?Fryxr(l>vfn()ws6( zJLwm>ZX0YHytvw+^l_a8r6oR5j(0AX6<=!Nc;WQ~DMOo7dXd{#;sz`OvdG!5%zB$? z{omi2GbX%4+tfN(9s9j<_T1wQDhR zcOyUUiQ?yy`$vb96R}wW6&fpwId~&RdCst>RVUQw`YbyW@94_#hM@dsXD>6>#%>>c zwz0U~KPPe4*iV8$ZO{&|In{Ni_XPhsh`Fnk^-iJ~18DAc?o}tmrF%9{KEgmOj~V2} z#IHuF^7tqiK)MRt%{%$(9uD4>TwM6BqJJ4Sz|TWfztv|j19Q#xoxGT(_ww1r`GSB@ zPO|>}50sxz&%q-CV=9nP`To7||LX_8`XL(*SD!+!#fV=X^&gw%Kx|MAl-!G|u~bmC zz@)wuD4y4ce7gn}`ci7}VB|oL3*+XvHhS7&u6^s)cQ+tCKSZ*A_Fw{qp17R)X8 zQv(*)X+vpu&~GnISKSMhBRMo!;MXH=+p@0ax{u~>>iqD@*<{9P+D1Ykf|>G_=v3nn zoU&twUk0Xf@|CK2C(SCg6JWR0$>o(jxR~mx;+*0{%E|LDt99s979$LJ{5riCH)!01 z?VQTnsQTC+fw+cRe)Go!$zz@)HO3(ht~Nw`hw|iN+f95=XyLoJxo)`0NIoR?roDDg z71Dhx9%`>G8<;Pl(gWpU5!4ZW=%0KRi<-{J!l{{ls?cJqy|e1jjVuIWhxqa~XARBa zdp>#U^a6zT9MR2?G(}>kyG!3~mrqh{^|v;6)gdU5)&mUydG*`|is`g1r2`i1l!m_8 zmj7w`W@M!7$F!1Jwb@jjFfWn3dCk<=3o!=sCVyN%Dwa+mfmK*N;^3?5{X( z(v#=j3My{HL}X6XWy17;4#4q&cl$XIXO|C}+MsWu=r;Drz$BdUWHkaYy?kQS&3w_+ zDe&3IPaAwbRzu0_iB28!Z7)|cUxko08&1WXN5Zkt?Ttyy+x}4&_69*~Z!q z?NWT`s6U2OwM(z_MmV#ix$g+Sy%fZ`*;8@>t@N0CUzPL*=bQ^laNy59j=Z@@VKd`FDj=_NO)l zBJL=LTmZFK`;%`I0(DTyG&VN2SnUt5kGHL}K9Vk4%#CxIQ{_ z29Cb?Xm&ps0y>}g`lq5NQK0d!`DRn;E%Q&?E?%6KB47v2-!5 zf4Mp0cKos@`jv(hd)Kz>19Hias7IRTy7u;c`_T4G^hX|7X$&qUWm>0r?*ZXPZd`$%nkXY%rpoMru|dn&-New{=#x} z<~w-dkiQTIBId+$aEsmw<}~8cV5FEz%~{BbCsb(F-5sBP5uv!ifp{sp{CfM+HjkGU z$s9)d$43~~gKv2kx_lKteAv9af5tVtlXZHtXDI5DdiNWKq9;`<< znJO+iDDySnbW9EY<+1DfhH;+02;iUo#RAGpdm5H=C#e(sje8;$`<8tvev{@B-w}i7oi}SkA@G_YB z!Uqh3u77@uj;BNexznFf7`f`{!DWk)OX}==0zu#zfX0;a>;Y$qhylwVSzH9%>;&0J zrb+&L-z|kr7Dll1mDuxohK8>sP@UOC?2+fHsc4*KYrIfl)kpz4k#H^8eIm&BXWe|H z2&AgyW3<}Y!y^$s!`VX~JF2rL|7o;R@5tbZ%CzwO1eDnKUCa9wUJ+O8qlxpw=lQEU zjpTsA^I?uQiDZdz`)wH%n>U|r(Wp;3e%YmfLc&d=aKVdb<@2LI?-N2&x^ehFe>@(% z*URT_o4ZWa!!Lk|{aD(w|D6d0SbV_GTEYk?*;jbWQ+3vR?!D&&4&V~0n&NC?h>i2O z8M;dPnb1$??Z}ZVF29ofYqHvG3A19AZhmtW#4FTz)rWx=Yj>%07FdXn1hzIzIwfXC zg$TT(&OG?E+jx9w;RR&nO*0DNaCpA+g%wUQx7@Hwo*slY#M7OuCknb-0ceYLi{F{q z_By#Wsr5uPF{fOCH>+(>m+NpDKSs7W{pu<6QWe?kJ#(o+&cHuTHZ0tor+ipsTtpnY zw;Y7jMO5nJ_JkHohY#>lMeDtXP`Lg0fWdhWp@pdEV}oC*#OwzZ=QsO|)w5!l#h`0+ z(36Mf*ZYg8DJ*A{A`^=XkHZGDU%T=UxIWwHm=Uko4{Z#zIFfEjebW+X@#0dyVs_CV z>F3rraToR<-*)KOyg56sQ4{z&Wiu9s+!f9C1IC(orcB$JE+iPGS9)(8*}7R*z^0=AUX%aLsK+x5*y^$1Mxvy`bbh&8&3MN2 zO*1e82pmr=7RPD_mGN;_55M>R@#L`DwCsC*^V#o+pGNeV=02~29f2zbsa5r;2x=Dk$Q$~xO#lBA3_suxYwjI1ZvWqKm~q6ITK>es zk7|Ey_`=EBJO1yj*G-Dv>2O*iY>PU(XB{;Y=v>Eb%tC`;QqxAHq>lSz{J>2ih4SEh zNzva0wyK|1_U&-ZwIsqpI+)?z`Ev?d%IZ{aQV%aC(eN*4qL;#joIU>W)krB6Dr(*A z-#L zdE8`ddbIw~t65}s2eK+Uo!g&)&N;dkL(^C)<`JIjd%`6p3C4TUdlKnCNTt-glflw@ zIwH9kSLw5*cWQ~2RmwAM)u}1q-9QP!(dI|4dvk=|uYQp(DKkhO!7iw#&1;Sf=uFzn zr>@G;HJZP~Z+5Wl%Ru(*C618-_hOr1zQI8KfUW5%^=VYe0=ARt;tL6kBzte8K3@A?*Jqx`FA|d%n-eXutv4pHbJ)XLOVk0R zOWvvKQ0Hy?9OX0k9rZf>i1!7)1UF`J>uYh=+nf#-ndBujXScaO@(=C0d8Dc1=`KH9 z@b4D?nXY)`164;akutP;?iE2Gzap*Y!=-MYY0-C<>5C36&i;`>+@4gheplDoX=x#2 zHDpx2t_*$hlDz)Vq1NLr<;`pF{EEKK-E`xTUTRVUgSH(QBdE2xHAQBV`doe;xGJAK z?xFASr{}0u!AV%j1O8L(XwqX50qiFavcKtkrBH~w6@C(>LR^DE2p#@fyqe>*G|@}- z{DN*tTk8qY5l^L`AEeTQzVrAcY(5fQYbrG7U%8RLSS+>pq8TZDxUIiBjGm|{Oo95? z;3wACDkRdJH@fy}=_L&_y+su2kG)@si!W7d@4U~n!|3<-fx#nqyJDrqnT3F)8LndI zvV7Il{m$gHaeAQsvFPY^q5Z}iDTuI#(BJ5(>h)2Kc&BG!n3T#W>YF}PJm-tLVmB)O zeRl*^<3+4!8*uXBjfXzfT10*p6?c#-3OkbSjoni<-?Ml<>Ro7UV(d9it$j#~oJwvD zzRyG_-)4u=;dYI_LF3Co_=MtSTDz)raqh#0s_Tk4f0W8qvchNaPV1#{<59e|Pspr& zxj&Jr-YeHNnBLVHDcqcGd*yIPLx4&R?iW%s(!-ZAXT5s^J-PXs`On`a)elv5J`q=C zECj|q+TX1sUnnme5W|z1JkjZZ$oxa@Jv~2^?ws?@x8mW>;6M$T`=65&Ya^B}?S3q7 zey&q?yfnD2w;^chi?!SNPQ!?d3~u^7T}s2USSzV(pEjpNJ@V)8tI}2UqK51*Ja24q zM#4)neTuV~_!G#j1(b&}G3W=RhK$$r-52*lhejLz*wMD*1uPaY?9BbqYIE+@88P=r z9ekj4=0`re^4$gVN{IS9Dl(49k=8zA;T^gCB=_D0VIp)x0-fwr$Ma*jyOJ*mP;a;_ z%jO=Dx~AL-V0)s182v~zF*LC?Z@<7sd0ee-PCxS+Mk>0M~s z&xJbPe+FONfx~(f!!zOee{yp0yh8Y_Ek0w_?EBP!VN=eXnX>8TO)cftZpnf28j-En zeVjCmuU3|35?6_ftR~ooe-ioBV8QPgF5Gt2$(p)mzOpq@xS6V_pX+(TmRSZuTA5L_ ze}LxCm*`Wk+0BCzfOI5qg?r83vY}F|>O-V)`@wdzphfdwwSRxQfA;bdNKa!$Cg${k zTjw=v9#lVuGOVJ?h>4!>zCBy6EIQKZZ~d;#L?%%3AyCkNLJfx-!zP%ydLX+p_{QMy z?|O3{61Q{`L@#<}8>##nwEP|ePtCWX2zhPX<(;!|LPIpxp%xM*u%|ScWUTEMWr_2R$FO6$NQmSuru`dnk0k?xC zDPieWBR?947ojqC=IOr*b-GAWldo%6kJg;nzD3EG-;c6(EatnU%J{MN3Q;;=9$X%dwPDg@&;y8z-~b^ z27EBzCAYH5`ZW!?jwA(!{DV=VR=0t*^L+W3LPhxnkK^x-(BB4;s*p%T{IUq=Aqy`Q?==P%u0+KDS?b(c}Sum+#B^*Kn%wYM5;oh2t zOSk_Y5WZgO7JK=zJ7wRwE5^NdbvZO{jnL9$S>LyksP@dh`JW__lzmgZVH1zk1fu71 zO{L7)4|@HQ(U&B*TVuOl^8R#Q_N`u)Dn1;geX6e#HpEU?N04-I1*TGs?B94uc)KM# z^oDfzfMUW-PulGTDVE8_&W+Km{;Q5uEV!XlPQ~UIwM8Xj$yX1LqaLk;UOm%3^{)Mo zeMVrPI3%#GbKeMQy_668aR%Q1$>OkK@H0=!u)g9?aUbP6ujvZ83!fJHODn?19L_?+Jj+kOE<$U^sUZH(pn?uNS9^Kn4JNv%j8rN%a#$yE2*R6On zR{aXWYTRbNc$(t^{SGK`yA-1OEn418~WC?nP|J9#w#s8f5CA)hkhi}IlteX zKv9u$${tx|8@LJcF(Uk*MSmmKux-{V5c`yloa^vap*K~nn)hK_rBU-8N|~RRsl6=5T@ zfwz3#PJqXdgjv#mU=QzHcnk}ofIvp*M3{ipYW8t$9PiMf+LRMJKbTVv_e6&Xv}BQs zo#>;jU#%sY$Y*joIy&G~h6cuzoT9kF}OHiv`M0bJ_0;sLuByeYe_PIN!=}IlT7H0%dDCX&*Z~yUFVUki(bL z=;?C&3^2KSUCkcMZDY!T#F4j@Hhz_ipA#UY^pi`xEN|jCv_o6ihEO{wKGur$_SqOk z1G$Z5dB1#KgJ|n8biiAFbNZVJd@<-e$t)5iBW!Y1v-w-zg!WY#Biins+Z5dJaX-hGy zzOm%$cjjm)7ommG<6@C3F?psWG+kGb`%;Ryk-XbjWA#{~u5f+{P{WEHOBeB2$mGr* zc5IV9y#;gd53&OY)_!YCYsL$d>c!KH7gq(LdQ0B5c)y@sLAncC%(MidzMB}9Nyd~e zZK@HX2w_)YYLhcYuOm9~zEQp595NAOX@fj&;ve3Exk%W`m9`19cj47l7eRek;c0^U z`A36E1#Y;50WJ+$ZvQegpkb(2J?Ct>QsLav_nue02~eC=WqpV6s>pv92(&TWpxKZ} zB>={AoeYnM4N0286W&+ZzW-)E)HGW}ch`iaQRS|s^tLBF+7}s}k77^n2!ejVA!z#P z-fF_Jsr|O`Xq~w%hkl*88wS()58^UaXGR2^6%g7Ck&K5OzlgcCEJw2sEldtZ&$nds%`0U6jD=>@$7+3pH#*m_j-RsbHRQ0R3J z{v{)lm$oJ_y%%XaYOU1|lr(VjL*;*YTc`QHNL9w614pTzjJcR?C^YyRn4>~s?YQj| z0+-tdFlhWU{ME1A5+yp|gjKdNmi8Ux7Dtmao>)%{p=vnasMm0sJjcJ-#Oe{?SWE)s zyc{MAB$AyZ~_pU<&q8yI31)Xu?2DA)cZ zjTAs&&0DV(t* zoshq&V+6w7+C%7Op#{Ar#&ijz>K$729#()(eBb$!mOZa3z`ryd_u05}#-UN&v3yXs z3jj3kJHvZE*tT4F(V?Mm7oTu*T9Aou4dd408~;0u&kQ3}lS5qy;v1l@18DGm=syAl zbP>`B`UC$`=fe#gcZWd**XZj@aT(}jt(G$PgljKix%@*0&wV8bC8ZK^r;1;; z=^Sr2c(f3Me~JHbmxn-}S`u@iK4$EzE2O=%)rh2rY9AImPrKP0KIBsp7-T|aq%8oU zM3N9AevuGVgH{4!S{`sh15VXZIS(^X9qk5`c3snNd1X z|LNXQkYZkn^A0{x`$hA;VGOx0bHaAb8VqR^QWdkk0DUg-QKbZRbh0!5Dixs$(Sf&70uPQ4WRTQ&Ln8xcjf6|5(Nv~Yp{PLr>JmIH> zA39bbWJ=rGvh0Onc&IG7F(W z8e7Enen+)^<`R1u?L5p$&I8mF)}3e(8?>6%UaA^(-n3@C``X;}P_(oZ`ytPpzm}ur z(?~a+dlGy?)_6A`m2k7n=~Q)L9A@IRjkM~gJI@)^w7uKUMQHo|I(BJ4J27qZn)9D3 zS4&aOD4=VQLGX*`44!iI{ce$#4jr>(bXxl9HNJOMAapE;k1~o?Dq}Ev9QwR@5EP)A zcNU&*S~MGAH@wVA3(TIP_JKf^V=KR+_!oFm42L~abwWTocgu!|1-TrwMe{jGj@^Qk zAMDV$=RGt(0Vgn_0b$nsk&3d}~>W zg0FFA8lGP5299ul&B=zChI)zqWjVr5Ha7a%3m6-qA*95|W2QURlcEX9izdgTp1b{} z8#J*Omn8~XAdY21iI-+>xJ8**fQU=M_g$F1-h<*Rf`xq}5D@7ff~Hax*h%|Pxkc!= zso#&a!pHD4j>T9DdGD^@g7}a_dfya5v_S4;iWV-3v9Ep(Rq==ZP4t$tT33;UGhk~& z^go|~P~d5G1!Y`!$}cpq&23OV38HUaV6A7z$-jNBlkRn(aI>}yD~jedWiNNfL+pt~ zXkBVjy=Ea0(iz8&bSxe8V^ni6b%V?o+VLb}9tu^Ta&PDvm_*$iLkq=3=+IJDJvCw{ z`CHIF_sq34p6c9`IEVjD3&-0``}sTtLDe!)s%t68A-<*W@$~SE?Z~E)d%uCr(cjH5 zL7IfxXSQY8&Q}}KhNxrPiau3ro3AdS74^BQEDGC!R*AWa)7FD!x63Hd{{T{}-7#-o zNeHTW;}#_$wY}`p@gh?} z)nMZXsPG_HF>8tyR^;glwIFuHZH$DuHItU84dF$kPn3N8dq_YNAdOd3Kyq1nkDR~q zi2VXDy;y)3igTlu=&|FugF0>yr!hdC;KYa!yARe0;8zK=;oq4^`m;7THl}`Mj@f-x z5?}(~{CrpF%)$=N(VK>>17z4-Pn{jq-FapYidcPSe5a~v1t%F$g~tio)`jWaP`Ic- ztrYBUi#)@@G8RyWjxa+atM$JU5>I6N0NdX<3Gq$2I*o(9^z&XvFykP%|I47%F4HF- zPLcq(8Q-1oyx&i-?|O;}w}(}Xpl)PT7n4;$7*YA?BA!zXgsaPRiMj#bf$j8K#4=pm z_L1wgAj6i0u>~7f{d$N!vW&4aAKG(Re^V7(#@ME(vk`~8k^IXTTPF6>ZPCe4?q$;v zz9{?U@w_JIGUf{YAbdq*DUM_LG5_dPbTo&5EDI&6Ai&Om4N$wkH1fuO=G;8sR{m4l65jPhRU?y)N*|cm_VG3E)R`$t^JBn81QLW8K9oyaGEd2LHj$!H7 z)f)9&W2>Dw=T}IBFv!G7{>rrCCFHv{u_F7iWCl%EppFv@s$iy>T9tvKDLQSuKQQpMlRyi-(u!(zFN&d7hrj&vs z9_kjR4RpuF;9xol<5Y1fWmpp27&x{z2|86y{t1kS^M!#6NQTa z$;i4p7B6;z+T?r$unL8+lRz@PE%Uk%P1&7s07cimE~x6V`O$}=(3BLP(i5e0@ma{ty?c}p>K^sc z+ovm)8YS|38%(toxBP(N4?k&l6s4}g@Ly>O> z+bz4}Oy*G0m3_Vi4!1szO~?AIqK&&$MEVSqxo}MR!6=_a@J`>ZRBm|jA8h1q(EPt* z17`(urhFi~anR;Od&USLP>z#E)X9I~K7swJRWD2vD>PA4gos7o*f&D+k+W(k# z$aaukE}DxI;d$zFRtD41fu1Zi-N7bXbya|~Y&)#;d^(T_M|+NdnXerru!Leiz-R!0 zEysl)3nGP0Z|NT%%6S<+EC@$n=WE*4Cs4RM2Jxd6orN_aSs>#l9V)aJ7Gl55%cq1t z?yL|WM3?$ZZ7ZIk1N-Kft}Enwx9B#lI2asbS1-d{Dv})(yZO))t>BKQ<-GXsSeQF= z`h2mFsUI009?ilZ+2lVF_Nn%<049W7r6%vV2Qa*J7ZBN_KXs#s&C2PJ0qVILuApzT`N!>9bu0aTPWsp$9E* zR#$N9%L;4V4a`#9FCDRrt%|J%P6Z(XM=YV*$GGRc$|q<35JkSP9$zpkT8t4GKlu`M zHadMZ6g|rnj>$$w#08%chhre6c}f(fIQQI%UG3*pT_PN=U!oP{-6eAlh68d9ZCqqB^M@I?1UbI^nf6%ODc+xWhe?idj5sJ~;eCJMX7 zFNhp*aFBNB6=9ZswPr*rr=vOZ+$6Fx8?0Q3ZFksb_{Lq8Pz0Sd7zn%IDdDDn<^*Y+ zIV46cBSD)W@%BAdo%aPD{e)19{W>2}O{`7PA$_{PgUMb`#@GQG0Z@|v-gO)#Ie1PJ zDVpV&2BI6PPkj_)=)ICNXMOXCT(Qf-TOxYb(^hk?=n`Y;xYMl1gJ_@lBEz3il2Ay` z>}CmX4rSpCG#;@kmfJDt*DN*BRb252&yfwdVwo&v(UKoJdG7j4c9`R(st?mXxib35 z%p%ve8oHHvrZ0be9Z-h)Wr(|zX!O;=;vy)^nVumv7;eR)=>C;Up09AtRdj5=GJbqq z^?FVq96}UzhR0$e=sBCzN1<24-ZAxN#TS(**S?VV#9iKRLnGDIZOrjEiUO5c*zb)c($y8q@&1wM}<)1|g$Lw3<6Nw?C9*CXnG#FU)ni=euC4xr3x%uyO z95N@QX=^PkJ>Tp9ruLkcM<-3e<+Dkdn3azV0!j0j>Jv8YEL zcLs!WOlR6adDVqJx(E;eBxqtj%H19^O^@MO@nZOcJ~hGpwEa~M2_eB{#r^V7cS9o& z!aa0n4z5_H@oQ{XYEjb6CL5MGHJi|%%@i*Ejpw}7)9E6={Tp*VD)K^re0n)}FY9_@ zbT=Sd;C>5%5iXBZ-A`kjL?o~anm`p4Xm3Y-+l}%?euq`DXckBc4g!%2PmR9;-^YwJ ztNk|e6SnAX5TU{SVw85U6q|pzaLl)2rgdIwFBI}Ohb(%alHT9MXQMUH_id2HgIDrd z2(qKe28tk1#m8%++JL2jq~18w#)ufaG5JZEi3A zGXu2+1cY8L+!>yg{d~3tebfi&-9FeDNT-mkrvr`S*R3qdWI^P&bZVt;qfqg7j+Y!O z|DD^Sk3L5&3_q>h$g>9qUs-2kSA#4(l>HDFp*}N}?sZd^Gp>y{Al&4}q0} zWR1NgYg>|(T3(PuC_@*zrl*)cVn^`Re)bFaxCLmd=Z&23Eg1pDE3C>&c;)dgr(L!b zv(7^J1h%~Rk2~wMY%|(8tTwJ(l?vNZ+5(7&nO*rTm}DMf$|HodO{#6h9&CcKU8Bs} z@&qTQCPxWpFd7sClWQb>rs6es~Tj^SYPM)5D31AFJb{K_Lf| zvW|uSRF|tgXK~E8W2)0&I7~pp-&4FStg;Vs`jJ60*|2@2po$aZrOP#Qpi04JiXxKW zCcg8EK%Gl-I_jp&VQ8a8yzHwCZ+kr3`q*jJE1*FScB}q_Kt-E_3%M80Ze6j=j~7FR)ATNH{;AM1 zCE>ZXmPktdQzDS^Y zB_9~v>Dv@i9yVY82_enQyx*`V5rHak{ebUcA)vEUIV(u#A&(9u?@lUy}!x04(}U_(NK~4ETl*@IUv; zI-!zXPJNAU>9%0R)7aR;<3&BF`hS~ULsEc;>{qry-(j%q3-|-n)U8nNjwKOEqpO(F z-XWz0PyoPLsL`E;nbYVjQ{D?*od?_ep$J@yxlV{Q4+OykyrKISfb#`RF$8m9oRviD zL0iFODS-D$1>#nJ4kSA|8Wo`Bxdz~X3b1d$Y5y~ra$sM61#&Lbx*uQ&0dxxh>PU`1 z0Qij;nGm3l4Qw-$kCb6fVz8D{JA%w3Kwa`aMG2`gepCPYB#S3=YXmt620P-GrS@yZ zGb@Hki$5TS0(5GHaR@F|e*2}WU_Q?$zBlcwU~`;{u~GQE(+z*G-yOj3G`HV_zVv9! z{O#EBc_xlS#Im@LfWbROc)Ta{sj1G9(2U5t{JVVU#ga`P1z5+LsFd&ew{It~Xm&L* z$@iU4lTcb(!QCCZ^b;M@2|4a&GPqN+)4^^5*I3Minpj|m>KRsB!{$ZajZt+2f;q>g4!i-#^R8S&NqOC-uES6phxEqq=(#t94iFOyU64)A6 z*wfoc$^5@9!?YkDQ0e@aSqafxEjFE0g)%Y&y1ejZgULFAhKjTBBlecLar;4!6id|( zm}oh=X7biG11@IBeW!|zO{^|8%NwyNJXk}8;S*}I4vl(>t5Xxn%L;!|?@)4GS&>vy1s(B^t^mRd2wKYfGv?^6nt-lw(u^@)qUuCXK`|hues`mj`)~#WGV0bF_=l$jn(#v z(%V9zztQ5-wAi{lI1Ax}*?a)7cy>gK_vwul+plDHKSB8q3KC``V6<)z4p4k)`mB(O zatZAVA93X9)$XsXNr|v^N6^)@eT#koEXKf!!LpQ zfSHGjf1^vV3royQHjDyy)}l!3?99zBFfpq(X}p@*CS@g3OA8Qny{u`}_u$ibsL=)r zyp=j}A=hcH%-)B863~Jo-)0y=XH_)Urd&$BVw8>R=B}=bmffxpr8GFBT=)>3e6~38 zwwQUr(z(ffUt{pwb+GfrgV1$VYR{GTJ(cwNu))U zg&n@9m$1}vhL2%(?mWE`omez=IdH(npiA1NKEo6DsrKgQW7!6gB$ECeflE{4M#tPI z1xjP8k>weLzGo%XT_@SScYq_$Ss@rk)0tIY_~P%ELuWgr$FcJ~eK~CnSE&8n)++7% zXH?t^?Jcw!P<#&i7#6j0$owsb)Wt9dueh9IlKsmCS!M>k$y0St^W}D_lQ8AQW@sQb zgDbSlr0-d=B9YPA7f*o4hYFYmT?Iumf1@syZ+r?O%A1l{VH(=z`kP5-8Lr68+&8vEo(({v`)dL-?l6|D^KG2> zB0F}y2`uVA9ZlB~T_lD@4|`D**FuA07JG5nr6Fud{^uFNzhJMAj|#)!`610Gfa!)B z@#9x0ri8rmPY9=hltMX!4ihLl{TRCcmWvBwET!4(eFez9)5!^IC}XtV><3kBxgKbq zr84>zelkW>C~qLE!8eCMfE}#J$P#^$mfg3T&32>EzDy*PuYVH@89P!ogkN0Y!|xfAg8c8kTh#rt=U?aN zA8*@Cjwt%2S~GU1VLwUZ2Zi30hx=p=L^@z5_@=|Sb-=ZMBg5Z* zY%RPOOcTnK9X_?WuW4}DapYEZc9m_`AHliwLfRq5T~Q=u;Z*(@{%b22`QUtD46(4; zFuW94TR2fH=qo|LmUm;|%v5yc-R70em&=0>-+=VO0>tA`@@$@S+W+cLSi?1;v;eXm zc5$ldOVh)udH9fqeFu-9*ZJD3Ul+N%uB!93e`p3ND|~Gtmz7#>f$q-b)T5~t=z!k! zZ+id?0GbD&7HMeV3VpIzI@?G1r+OEy0=V;34$o+ScQ9xzD*q;`yjCBG~g8gpa;$4TM$Lrw1tEgOKuf z`ektZ#~mIix=fDq8Vut(SM@_zoK;QsE#QrDPNcARcw_wBC{gF##N4Q6;@^5O=&>*2 zqkmeiilN9GcIPHg<>qlD9^wGAtYY^x9G8Gqe9M|Mf^J7kNPtntqm64;LWIhDrc?_A zg^+cj>&R@ih$k_r;m-qZB7Km0esOZTxHp z9>sLr3op;8tT?Wqu4qcXClp&hP5cGF}8iEYTGwXU%y)D6~^g>)-Qc5d!fE*Q)Ea- zmOv^AnwO(U6TYRt2y`!V5CDFgCC(WtR~uPEULN;t&jCHkzs-J`e}Tc_E-2pniVj2Z zz65iqP}aejwm-3h)X>2ilVnK>C;q{G|I4Pd)Imi8EPiX-<@JOuH?q80qmA~)P}eLo z=~nErl9wu@SFmsJ6A5~|x_#pgDYeV39hf8uzCF4Uz@p8W8ZcIy44Quyxvo}E2D%WU zf3fBW)!)Z2!R40|Vx=7vs4@bWb+o#8iS%NKsY+rwZ?wB6PDS}v-=j7}CcAaG+OKKv z;7p&wZO4_M7VW-TnXO#|#GT*T9}w-L>?*F7vl5kb(g1lwp9La+Yd_H5xANYGggcMU z#QV=ssq}#d#qGNW17Nm-1!rDpq2z|W+GLz-_H{Szr#q0NBBLdSyg}7T<~{@*0Ly!C zCHDhF4wE%&s;i5wIxq-RvT5FvdBwUeyE z(cZv3h|E*A#!PDPMI{fRC}k*El9D;syDu<6J9JQ>*H;PUcnnM*yz(^leNR*q8uv7YTV7{ra0Tx@e`u6_jC z7XTPw5-$>fI59XK0if@t^DK*KC|T_UyPKXo!|32s&WK>W$g?0Juw(%ua z2IpNi4eQvnV$WxM+DfmAQZwMLP;f zfFum=KPu+v*>*jCQQ#+r6t3G;kbEdJ#`v29V z+fbnSUXH)rz|;iTVte3rCQ-$XEuC~y8W*Ul7goFunK1Ew@|VoNH;RtVj<@bjHH7V=1!@trZEF6QssTya65 zN$JwD)$W;|-#TykCS(@vK{^|v0L!@dz<7Tn?L|Bd{miYNpZQ5X=Ot)ZkqjQKEJWus zY5kZ$f$zet5OV$rpTnZ~49Auw^eubOi!vkIsm1(ov@%2cI1V6zdwMlM zHeItk-2vl7-`jpX0-3ARv7#yH0+;XpU|?vtpm^25-l4vnFLteG8~`8u9QLy}A4Ys6 zf0WZy9pxgYkll{|;T<$KgNS@Wdo)nByCg|dWSUs?H;HX3u{e2rPU-81B*SJH@G`~a z%=*ZGSH+A;IvB^aB@%=lXKYiv3bsPyexKq(;pB}vB5L=mjwcgIgLeXBj8of$Xjf~h zJ&=}BZp5-;!KBD@l7TA!fP^9IAK)vCp2LS5n0inUr%W$w*@dLg13a`ApiK2_b8swg z+7h`=Xf-qzEqUI`4o+7@T|2CGH5wE7HndO{b_%5FR}@w&tJN5ngP;XEEW=uyiZhyP zCD#-C9Z}=^+OrlBM!og>d@-N`dvGkUL-IXQOk9Qpgj17WB+yYLk82w!YapS$=4bMa zeNFHg1JHS2ECfl)E&b`lk4C53nt2FSds1Zw<&Rlf>BxKe`>UYjjz<{%mY}qnz2q6H z+BVh;OnUSN(9{A3MWE0s02*Oi-st)7)seeslJZ{Lq|yE+A0~rvO=wI(*A8O$PfL6v`XQ2S zhN4yU`X_{D5xExKn+IZ#zclKVQF$wrT2fb1*FM;*K0^ua%T8U|KFdSv5zj8 zqJSp7U#P@LoQJT?ZBHgC>RbQl7@W*9X>-0d>hk!AHh#0Uvw4=wSKjGRo(|%H?!2dK zj?2|9ZT{J9@x4=bdZcZQ)-!p^B^94jbNr|`*Afj$5=rr)F5nJeM{T7}zsC}-^xCko zOR6LOsV;53IlI)LP#T;hRRz%oL~_}zT`O@QGUL%o3OHM4m5erAc}M{l1+m#jLF4?h z*!Vzf($>3O>D_%l45O8`2BzknO@pb0Fmnw_vp{I@)W4QBbG4PKcp93# zE4NnY?-M?aH`f1bL#G}okM()E*Z!94Gae{lHW zYVYS53p1IPq@H5OlvS5_30zvsbis3sB`*wZ>8dYNBK(3N=2NK<>Ugc3q9+;}M8w9O znA#{PGb8`$>u}{FK;|Bj*2ncy`4U9%i}E+x5`%2jg;Fcx9W>3JnJG+{7j&^Hez#Rl z<|~hIBg*neu>SCn$YWaxn<~;8DZWKq>No9!g%>TWdaHGM^4LiS)CrWdg02t&(JZam zI=!t!cY%Xj9_O$w|GPdk#-6B51y>vSsKa@@pMD&n(MM?DdCA+V%DE)r@g^ljeW%R# z+#~go#^^n0f(u)_De$aK4x7tIJu-7`7g9fw&WG8fw5d*d$RkqMb9>luPEVre2U9-- zO)5=rYf&Sa6T;z-YA$1I`ocrt@4dipz8nsV?j|G6u{uVJQCVueZF-m~8=>8$mEG%-?$|agU4P zX=_gqxhe;FkcLUs=|?Z&Lit6SBwl%onmff6*I(4&P4{gbfiiE9{ScrBVido8X5?uI zUG@OdF(cOi^Uu@+m!QlmL!Fz~)K*xmb`u)BtnkkXQ@NG>1i@Ut#3dUS!qBeQ7AiQ| z?tj>cRmqUhPF-p5dF_!hb`Zx2Rnp@Ev^suclj?FH4gPp8UmVaoA9M{i0pEEkcqf?> zEsLC4Grs0Yq5HQ^T(z)lUwt&C)(59roqRwW&ZdC+^v}Rz=f?X1Fgu1=sr|85fr|3*vej^ZELWo0w`38( zJzvs$%<9Cln42rRl19bIcv#gALgDN?f}Ph0``ZZM(Hegr^4Sf*)Gs5=%NH3N1hFr} z))uDJ@Y%c^9u6UK%ykYRVfBAeMNn_G`1hDZfqV^LaG@=*)I>8+N3g~!FoQ^~T8|P5 z{1_zvL@7Myr_zv5t6S1(Ldz$bxc8js?_I?0M?tL4n}HpdAJf?d7(z^^V36$F5q5C? zdGHelgx`X*LLyh_q%>w^sEC_@!pgCm9Jgll7s~p)+gg@r8y6X5%(w%MfO|9$2%EID zoU7sVo{>(ZwtNtjjomY982i-Xv6zUv*;aLO5WStFbNBoRPbw7@P8cQ%R8dmg}#=HtBO9=d*Wrq}Ilr zaQ}fB^5hYQJV%!+1=9*w`g=|R(!nPh^9NQq2MPMvDggA`NraTmQR}_pNn?yF);#xb zMW)l^8}GiUKSp1Cw6QntjAM0YivV@@20|@zI1lZkduH-Y0DrR57_Hj+tB7d>hFV;$ zfLYeK8As?-zz)It$Y+$~?&I=|EB7kwNytbGfSQ$o-FK_(fk6Y^hC?ijq0`jYM)+?4 zbvK8`uiaBQziTf1_h+{=h;X~dW&jR}BYZ@A&vgclaWnLp%*c$ld0l-Oc>Ta5)8G;W zP##qJUsKLWh{k~X96dWe4YYd@ss_Nxi8*Yy3bm2~dtSvZ)G7!wWXi%ggGSY)VW^?B zalDNq{Dl&B`h5X|uM-z2h#NG!EnvS4_FOsBaOe=@Q-^Axa)L*aVRy@$zDOAICoW(DaJPk;jlXm>Rn<2=ui0vb4 z;9$c=5Lj^S-~dPf>h-ZpRWl(s7?&L*N@RH=gM-ArT63gpW!bmFG48qLmgfh?={&m7 z0|pHwcKrsizM*p}xFM0Gq#k}t>8Ssl;K@#ZYAky5b4*;z=5Yq#alnAG_--rr4*#~) zHc6j~XotY>2Sn(i?%jlE3*hM?iBN?y`xVBzuIFMQOJNeA*=Yr}3^=tqQ@gi!!11vpvAu?39G zAyFF#s@keqL(fr7YT6RDCywQDpv0IKDw>Ff>3Q?r>=$4={hZ~d!-HzE>LY8Vcv$u@ z6(xsUW`y1;lbl=eOviL+hjdy^0Hoy()psD`Vz&IV@v>FBt`0BzdD?;k(KN&j^yWtw zQ7J@oW#4g^0~s+a8+UKR=HC_gbA|}jYbd4x0l}4M-eoldA_e)^yuA-QoXuXH%OHNztk@zaNP<^$8bC<_KbMW6h^G;C6 zU3Y%^V`9%Pf#zQR7WWIN5*do+OgLMM-ZuYO;Bsul=P~BWY(jmTM(X5hD9&+lyZ`zo z**U?hp3P=SI$}e4RcDY4ebT;-4bIBdCn>jI9C%(;}!Elq_ zLuk<1nWb6FvwDOlQx~h|J?|M}lvSIOe|GtVOeI$1u|ih#N7*%7?fIiKC5svY2^V@{ z6Z@v`U7z&&1>{yWd%Sls)a_fk`@4Z3Y5^voT3-%W~JZ5@7c zxIBKHk1ybyw zvIbg<;&<@ESITTOw;2;JH1(cZy;~yIkb8qP_CV56a}l38+g(-V{qZKxfXht5t2x%~ zE$U)Ec#3ApVo@#PO3?21dlR+pkq=(pjh4-8{9#7ICruY*cC5@Tck+X;J*Q%*%IHQ| zc<>~N7mdk3{HFi1OqHO7LNvF-zWPziHy1cr-?pWKbsO1eAo-=qdETO@+*UdK1A9&* z7WjMp1sf8dkj3{V6!vb;7Js%v;`>pKJtr`b{v%W&0$7FF^I@A22HGPoY1Xy_=AMeH z0_r1p!(z242Sxn(Jp{U5J|uQ)e?JcH(tu9#~2)6zHib<*wIfs={_+ux< z&@aps9#3Jqpgumli?V+vcIE|p&iY#dVKUTW&~kI*^ZLr+RuN zRj2BSIrH8KpP*dTP!7}b(p>9!vz3sirda3UOS)Uk_cvJO9LKTelqCh@nO*HpF3(KL zx*sb=lpoC3a@yTIU6y)fvfQf2(Ls`;q+ISSupY)GUTFKHeAhTf4h#Rf&{4#nm1CqX z)s3n%zE&lW=BPj7)}EGe8!y7Y`mBUc%P3R-+qW)u4iSWQVk1IZ(Y3erb(7~2)bXD2 z*A{Yz6e1k2^^D(g%Hk6kU~$+%JRW;SL98iU_2J8GR)me*Q_uaB3Irap-_}J*ai@UG z?gN94u3L-Ftf3W1USN)8pS+EDdjrB#>kkb&R~1HkX>-yQ4a~}VDt|5#R^Q*usLu?4 zgU|yaLX=1U{VM73Q3h?)KPhlk>k@r(L$zmZF7AcrMi@MA(@O10XcI%)x*w7fY71N%6(4COqs&^@gvywUQ5hFY8xBRdEboX zzx3p~-zR4G%J%Ep z-^CPZ{2f%q>7qW&LJ!Z?&kK5priZj>;*GBKn_Lil>b(iyb+OS#F{w9|wJd42(=+7A zq@zE6A#R~3Cw}fk^%2RFu`eI7mX&!Lf7o+R)u>Il;tBM3klyYgwv*&0`;z=g!LZcz z{^K5PUkx)+_d_4(Pe)=EyP`&nmB7g#D9siFUN+61B5b&dBDCI&QyR**=Y5)Dmw!X= zuebTNiQ}pHp*zy|9Cp>47sD6uud=X+)#m;)T8tY6=SZBHtNxa0!FRido8dW zb?R}6yC@A|gWw?mEWj8(iutzdI)0&)wN-PAHYF_JK_|1;P|6)tDg{GLQ*3<^_5isZ`}ExTHD9zx;e}X8(*{nYF}-gOVTqSSgRp zH>aaJ)e~v6?M*fH025zwu;iImsR&dUW*IphkN|Gq|eyKE%3Zm!=gH`=b`(o))AYlSysMtHM0 z(7l(kf^)Rumck$L<+eTTGYLyCq#ozY;fVV;#|(X>f+e+sWobz0;Wrt z3@v=wybH&XQrN{ZdD2f%Lg{npw2nA^{5_-rA(3KcRx0?Q>}3U2h4BK7a4_Oe8tkK5*ia#~5GSzp92J;uCW_WO=ag+(A?`CMhw;MBQWDIneP~`BBOMbs0sOr6^+350O5q z-lND`T2_1cLrYNjPY5M%efst3 zw_5b)@xBA+SM$m~cM1Y-O@HC4wQdbP+MrnbeAB}3I1JR{SdRbGFl(sa_#$!niOQeQ z+YW%G3T`yu>161N)ym@N`pa_Uhk(qM@XE}x`3o7}!e^b{=-w+TJqkp<5E{* z@{n-CODt=NF)7-1R?TCkzU_T(4A;i81Lehe^VZDeEWIIwUe{|}k#^_%>b9O&Wiq7X zw0EY>#EkA#!8Bocve9%|Ae(?ijg^IOWg$x@RzZS?%6Vt{qXAp)Wfu~0^JoFY%nli| zbUswM-}550p*Mb1LJDzlw4(VeT8;@j9#$S z=w}&7=Oc z)lc62MxHkIL=A6^=LFS<4wJUF7Ukom4r$4cMW4w(U+J+?z2B=bqepaqOkqvLFaOK( z=gy5<*CTfZoN(2XechGD^4jPPUYfFPZ>qB+F{L7OkYJqs@yEfs#Ai9@(JaRQnCCgC zbY;JM(%tJ-y%ZG9MG}@d&;hZ?Bu}_vQ?%gK6P^Zs2o*VyxhFnqHn1(1RdORX{%B$?WmBf*yYKa)_VJKO$*Tu|=j%kd|b)oKw=$B}W{rR-$I5#K`xJA3!aX}52F zzM}cKFVx6orha~t+vKTlG2;EQK4yM02l9f+!jv(9&)tcf$44g!12RgfI9FL)`P|!4 zvQOu(EEs1juBcYKVsypnv$ct28{1{Q4r2fC}w4IZ{(&k#386x%R0m4-Mu8-r(3`CKAF^f!lO10tA zlk}+Di~IxXY|T2}dr*N`ZF}}BsNUmAvfUL{z?1ZiR!HqF4VIjaNnHxc3K`-*qEx^- zYVWJ^S_fsJP%3zqopiyuu8w~-(abe#R-v>hVpodYScwDnzdv^SUc%52b;Kx>BDq9a zh@<``)bQN<-?ca_Gyr>-)Y9@+xGC%|t9eqWw`^9^Pj@^Uy34Un(k>8vcafssot`iu z5vAkX53~NM>6z(4wq4Ub>#{T)lzneSFoI8L>~-cGpWyvyIr5XcleXT_N(!}k>?mGO zA>K20Rp7W%DLHs_e!G7xbiSdbL~u2~h>0vo1D$H<#TTNz;wE#WDol~*FCXxUlj8p~ zJ=<>Lvaw6ZS7D(|q3ULxI_n}L@p$WXee(lK5-JA2qmbHubu4g%Xr2cDY|WfIUNb4P z7|tGi5U^4D<`D8#u)`w)Z#Vkgcp}ei-2{gN#dDM1jxqxx)Q0|>fI|7N2`DJ;TOvAu z^9OvepK=e*)05&uIHN^pf5=UzfPI86i+Q*6Z#oh`wv7l>7080gAbuNQwOPELWrg|( z?5#n$|Kz>EoUZ_1EJ&w^6 zaFohSo%HgrIgQH9SOb;<7{Y%~{hhUo;>JO717s;E3oZou|2+ag7_go72g;(KGtdFB zyu69GUhICH$x$?^aNql)qAlnc_KgSjdWXN?seb@k zt^sKcSmrm;kd862Q&u#b!X7w8!yQK$+E!UyzBlZMeGW1GQ9VQ0d@M#78Yj{N}e3`d(R*mB!YRoGDpjn-;^jmJLtVIr?i`a+9g_0 z*9Ny7NZ1P94K{us8D~%=w7H;YI&{!TaL_1Cf55XAxg<0LpJ z(rP{|e+WA=-@#r98t(-dg0pi3x=Gb+#CK7%3DEwOZm=SxJN<#+<}`pvHWr_AJfU|% zbrVIoDY4wgk;Xp71P+r4WoVWHnkyNgGt9^a(I#*{(~ckRM9$EZ0SE+uOGOKSU;&k8 zXrH4`p_&|nE2k?lz6yXS5Y}l7Ug@Ex<`x=N1QLJ(h12z6N8CU@lEJ_Wbp>4J0fKj) z2P#8c?-<20(X02VcG2L6{89$Nk`&2paB@*r~EH6GaNq(#Ihe_98?4UFXkxI>;! zhpt74xSvZ|P>TKubq%1How77#XV~^JBMCIi(M7?dJ`%uYHtq&fx1A&Fdl|M1AWJjQ z9jHG|>nM@hUj7K}@e3pAOp%Q26M3B^W67q1 zFAjx47U288)oE>cJ;}{vr(Eu2gEHWprdvH@XGFqn#BFB@IS&<-UtSj-R^Sxb!WiS< z3Dusd_R6}5VWwe~L1$2|XsmgPB>@S6#^eDKz~y~4fbWm(9Ah5-D?KyQoYt_g6~+2g z!o|tSOMv0|u$%CCEU};f{9T+A3fjp8|JMo9{|l4e%^2{)sFfiR1Tg7=mz_pDjZa&4 zPXEEAGiHiKGXl~1I`b|MeiK#1Xf%7o@bYEVuOZ7e#eXEf|afLNBb zViz;>yGVFpbgK*)!QLw5I}W~7K)NpD00(em4V8UbYX?*aIaQdg-=dc@reu?*3hy$e zoL#SG<*{+FMkBrLX<(aeDNVm|xgoQMhF?1bI%S1gHu`qCA{diS3IjkS_`@2?XJue7 zqaVchXJ`;k zvi#D26d4P8*aobLOaGQYo`OPQ{laBmuzi!$GV1WXeG+|V&|BD31Fb_qQ z;pIf@QU_HZ{YAJ~uAqh)nv7I@_en6K2w5Jh_#nbqJFod*?O4Ae3?lQ(B64S5;03vP zYp^v2_JJNtP-yV0nk04(eE2@H`V8~til=kId2&f$zUs}w{J^lT>_R#zv zz|G_^@okR{OXaMOEb{WON#zT55AOjmBq?^EYzS(|!ay4}UumP$f&N7&QIU+e7xx`3 zBB+kZdyy)ggrpUZJja;Wb^V?SRJ}L8IAnX6C3g;uhGv$Vf91!j*>213+bf%j)JBTI zZ#(LHoOWAk)%xS2Zv&-V-ip8(PRW9{rVe(hk26j7{7aKXi64T<9rUm|#$V#6z$CZG zHvjR0&HZ)#Df#VJZIL~aT7lU;C$Tm2>K?P$92U8`aeP?SSIdy-?0z@>Edt>^`ksMk zanbcyQ#&$D_mpAlyBqFAV2~h;_G1ubay0ydi zpH79=A<`>+t`9()N0!HH-iZy~77g|_x_8xc^DXqsXJQ*Zs@QcW%z*jrxP9ZD|DHMt z98^JG0c=CbNiCU4PQuf+1}`M0q`S9!Uz7Qr0O+oezu2kmTQUyaZRVv>tw29~Y}ujy<6n}* z5tDSm!sDcYJ+ZQASlN1(Y?UCtD#(8;NrITmsv10u4{zoKB`%H z<-3GV?57`2w&{4e(8*$#=*X*E?EFv8HmTz9+m46_2t?ff#$h*Uk1n+EiSN_&pE7<5 z@(&!g0Q_6P*Pawe%64l$dJu2#CD4K6NwD<@3AKukUteV(qqfg@q?-_Ah+CYM$eJRN z8e7Q|)b=+Km|PI4GH%ep-U27|Gy8mlrl!Q(DsO=&sU!VBY-;n!gOzGRH5i|G6USDC z8Vu+t2%1vI3fpb-mp_(q9H*s;WhZB9V}+3xQv&Ot3|)67t&F}gPVDdD$c~|s8iSEY zWSP}kPA;k+1&mcBdGaO)kUnqKv+RbD{mHR)05xHy^X0+R^5tKSh@dE=DdNN_=OwAJ z0+@&UMz=OelI=Jk-A&1|TKTp@X(RUC{*WEwei+FcAZf5#bQs$>a&40XHmWWN5S{cnLw^YF`=~i-(@2}flq0$;OQZLbD%ZzzOO)7^xqc{i z=}1hFOqqQ;J6h}3&N|itp8t)*kh)~f)yJo4sE*eq*uNQhLorGUSmiGl{N>dUzsrBU z-FI~yx1rHAij48sI1N&sNmYewUbFK2DyMUEV}edz&rN<2W>g$aR(pIUr|MBxLI1Q< z2PSt?ikmG)iY2bytFwdOG5X4}H{{Lbk)&e|#1D&;W4m%1Bcp3`PxE{WGTqtT6k?Nh1TjKYgn#cnU^O%Ier{Op^!TQbh#p!Qh7SzdcWvD!h4{fb_ zJqC{0lJmAmBv7T|gHlMR6VJ?URk21cW!QbZ$}>`xfHf3Rs^YrZaI|1&pf>N-25r^S z?g$^=eAXnHHTCJi@;C_I1_#^RCKCimXNU3 zx97d2?jh=d*4W{H$5mZ-05ChZmiE?;qs305`wx7`=(jPm$jR5v-o^DIn8&1MASE^N zl^hZ!;6`*I7{9up7`mFY63&g)A0cll#we*<(JQiicIsAh`~5kCRvmxYt$P(Xv`l0C zpwm<&CBF&=yWH#?lAlwoB6sC;!_{aBRJ7noN9z44Aof+ZrAnJ^G5^}p*Af3+>cmpU zRs7P?)DVl-#8-H>-2Pu?^mX<{#>RNX;UJ!Q8DRX>0zvxT^KTaJ_bPj$k*hdb2Ol1x zRd@Dp(wAwbhRA#~><6%f*COOsX~mqEb=g;yUzl`D08Ht(m;y2USyTZ9Hb*ytR&m~J zDq0SrHWGL6+$vP-1d{*D1eBrdUj%gfP#$DQqD%Ee$$t*wFFjOVeYp#Uj)V<7DIXFr za4a?M0P#}}DUmnR#vM*#RGcqmbiEce7_(Z636HK7(vc}E)wzV_(0hWaDjs;dyEtGqzskLY0Nx0& z7oxp|#7%&G4*TmWAn*e7BGI);Jz zE{o8gE1z$A$+NB(90xX|JB@k+O_t4|KO;`I#6>Dhnw0oJ13C}BwUP&7(Nl^X(DBn} z-2>=klHh}dlZed4W2=KdH(Tdw9u3SseM5iP1^7ghh~Io7jbD5s42s4la{j!r3lDzu zcBVWxISeKL3W&>3Mu%?mxWO&M?f^>f(35c9sF~h1u+k)^37BCt5`WU|*d=a16rs0o zoeaK+B`;=IIOuLMdN(#);f_rneRi&4M2~yztfd-#sD*bMI%TCfr9&X_dPHBgA{fxl zgICKXiowUmI!lkFas^DHcd2O7Y5H*u=U35~Sk2Y@YVK@r>59dqN6^K16=RH|g%cUI z6>GvFvGEnF;pX+yL#G(WfuY&6w;XB`qU2!E`C>q`B~HqVplc}}Z~?FZhS2?sy83HL zOEl^`smNHE&ZYP}N;x|aQb;KO?}bE2i?{09SMc#bvpk}k5uATL7iJIaf_Ht}rd0k7 zVkQfNGkfG23QRecH5^Do*Yp5 zrYbA-T|;goA!WK;uo9i_ZsG&c@7OBOgXIJz2=tww2{iW}VY7|RhFT42YZJ{a%V69_ zXelFBwKd_}8_S3M^iK(3_xxnhz}`m!@^sO0NCiG?Rvv`?#xJA16Z^oX2F^Z{E|n5c zaaD5yjszwoE&o^Z2PZQx;PV1J0}od6XOsb`&DUf6#}{AGn%w{TPJeGeGtEK({23(3 z_(NpP${){?m1vEiX=%p!v|At2zE}d(6v5%!{xXEdU^;YSr4#aiPun(Tp>R{@{Er0| zWJA^vXR8LG7Ou^Oer?(~e%FIM%aIBoDo2F4V>2)^F{K7s#)VzZnI-}H*mQa`jc%w{T}n^k>!3x0A`0?KmD3T5U4 z{UhPb*XSe95NFP}Y_!3K)C7imU?F>yc;FrhdUwMBzYG9V=>4yO%H>7#?CVKH@s(17 zIZ!MVdJ^(Ul1@Hicncx~!9!%yoLPB}PU%xaKqpW`D|d!3$^#3BAVCmOF}g-rU%t`z^ax?u21}_vTtq3P5cE55}0Ng79$|%QV|b0P@)MGlV1~4JM&cAt;IGiOui>j zec$$j_taM)E#MoZ;;X|55x?j~)HK|N-=I6fhAWCK)AfFM zD62Gom3&W-R%Cf5&Wp+i?PT~4sHNg7S8)T$4wp&e;|5wNq{jEt^0RQid;yiKy3aPZ)AQ?32gldx4Z=x_F&M++ z%RXyA-wy0#P|O}&hP>sgfu&XC`sZ7-Ln;hQ>;ixuO$$0Ad7ORYN4UlcY9Ek|g4;Y2TqcGB zEG77r$p>gX4QGp>O}#wJ7dk8_LI7#ccn?k5^N^>32s+e-lgblxrX!caV1DMSo4EsO zWiQHoaB2a~ZcH8YwR#8fVqleqRjZZ3b~;Y6eE2_~$qBA=wxD(M;Vt%V&v8(R(B`3D z#8)l(AnY@`Q{w;KKSj2GFoyq(j9zrKdI5J4XiYcX4blxHOAMlu>i5&<;ORvUmEr=0 zUM|dCpX;)ftUqynH1*jn^$AXb!rGk!gNd)&jBq<-^9GW?@;khE5d%!G+dcYR(ASo6 z+h%&L>w|{=JegBn-8}VUik8MjrQceP;>cZ1R?tiI;n2At157aMb1ngam)Pd3+x-6) zqTiyUm%5bmm4Tx0%xI&mD)XuS>p^Q=s&9l525X2F^(+e>g7x@-%=NRp7`_26_`g%s zDLThuE1|w~p3G8vCGusMYH9E0C?B^Uj&g?(DhT(n01M6T`HwUaN9xu}xwM=^x@fbB z-2O{lIh{DiQKyKZPD-d;Ld+C)#F+Cj0OxL`6>CiN4%*5l<5h#0uJH&Gt~|A#GAnd; z-6Cctl*GRpWscAlT0b*&@XBaegygf4Q?gFs(v(kTPFqlwueUYl9#e8_;}>uomg?B! zniXQTn=LoxD|EZAk<4TmUIDB^0$#KSm8S9%+J(8P3q9uX% zI^H)O{K$A5T08t3P350h$ryF4*%$L+)yNt9mS*&V056N85S5&iJ-fiO-9PAjL%OIZ$ z2L{DzVs+w2Qs1n+w%__e++Xz9+$)W(l^KR;o9!-HI<>dbtn^w-k9@guxy0=Gzz5k@ zyN@idSxV}xx~(n-?sth>^78es8#8eYiLRX>Tc;I@wZFS#?4X&)xm?Z`WP)FikJz5u zpLp}6sV6@|gXO4_5Rt4R7_bONfGXo_V`8KmD3M7lbSGnfgm$#rNGv+2pp;H?(E2oQ5h+Sa zGS=g_%CV7f$ufPC78J5fyl*^F=CcNNceaai-8Nd57K4%p<)FIT{ip||6-B*qMRLg8 z@S^tU(6Dejp{L&GHM=h=ZhezEhaSxdP2$BjSha9jqyx($LZakbRM6|GG;3aOfkhrl zkl!xoW)H>tq*hW`6|VZN1dAZ5)yKjf9h@k%z+kXss|D zPyR;E?@&(Uqk4Q4%J@3V%S5w14L;3mRW`rQ5*!Q4Hm-xK?a?DrOf)l%q}?Cl+(|*3 zXebNQoo!X#-&WW+?i4(1C}2Q}3Gw!$iw!n0ormzR_KLCle;~=&{X>IoSk)pYNX~g> z*4!NJX)RFEf++W+e1MfH8Jg-`V+9UwCJBsg7iiMe(_g%gW~Z+|3rYh|i&9Z0H8YyT zLk=KkwSb>cs-VHMV#~RZ8uo$vqV3|Z9^Fh#OuPSqe%;VP8!8I$=PaZ@@aG`pn(${2 zByCJg!4dG*W@1tUH39q)hP@d4`G0qqBY7#8ib@n=xBc{p