Re: [PATCH] Add HSM hart suspend function


atishp@...
 

On Tue, 2021-01-19 at 12:09 +0530, Anup Patel wrote:
We extend SBI HSM extenstion by adding hart suspend function. This
hart
hart suspend function provide a standard interface for platform
specific
suspend (or low power) states and it can be used by supervisor
software
for CPU idle power managment.

Signed-off-by: Anup Patel <anup.patel@...>
---
 riscv-sbi-hsm.ditaa |  40 +++++---
 riscv-sbi-hsm.png   | Bin 16836 -> 31183 bytes
 riscv-sbi.adoc      | 236 +++++++++++++++++++++++++++++++++---------
--
 3 files changed, 204 insertions(+), 72 deletions(-)

diff --git a/riscv-sbi-hsm.ditaa b/riscv-sbi-hsm.ditaa
index 72b6312..320f1ea 100644
--- a/riscv-sbi-hsm.ditaa
+++ b/riscv-sbi-hsm.ditaa
@@ -1,19 +1,31 @@
-                              +-----------------+
-                              |                 |
-                  /---------->|cF78 STOPPED     |-----------\
-                  |           |                 |           |
-                  |           +-----------------+          
|sbi_hart_start()
-SBI implementation|                                         |called
by some
+                             +-------------------+
+                             |                   |
+                  /--------->|cF78  STOPPED      |----------\
+                  |          |                   |         
|sbi_hart_start()
+SBI implementation|          +-------------------+          |called
by some
      stopping hart|                                         |other
hart
                   |                                         v
-      +-----------------------+                  +------------------
-----+
-      |cCCC STOP_PENDING      |                  |cCCC
START_PENDING     |
-      +-----------------------+                  +------------------
-----+
+     +-------------------------+                +-------------------
------+
+     |cCCC  STOP_PENDING       |                |cCCC 
START_PENDING      |
+     +-------------------------+                +-------------------
------+
                   ^                                         |
    sbi_hart_stop()|                                         |SBI
implementation
          called by|                                        
|starting hart
-       hart itself|           +-----------------+           |
-                  |           |                 |           |
-                  \-----------|c0DB STARTED     |<----------/
-                              |                 |
-                              +-----------------+
+       hart itself|          +-------------------+          |
+                  \----------|                   |<---------/
+                             |c0DB  STARTED      |
+                  /--------->|                   |----------\
+                  |          +-------------------+         
|sbi_hart_suspend()
+SBI implementation|                                         |called
by
+     resuming hart|                                         |hart
itself
+                  |                                         v
+     +-------------------------+                +-------------------
------+
+     |cCCC RESUME_PENDING      |                |cCCC
SUSPEND_PENDING     |
+     +-------------------------+                +-------------------
------+
+                  ^                                         |
+     Hart recieved|                                         |SBI
implementation
+   an interrupt or|          +-------------------+         
|suspending hart
+    platform event|          |                   |          |
+                  \----------|c1CF SUSPENDED     |<---------/
+                             |                   |
+                             +-------------------+
diff --git a/riscv-sbi-hsm.png b/riscv-sbi-hsm.png
index
033a0b785af2aba03cdcc8e814fd8f883eccc4fb..bd80ad87207861b2c1baa3f3082
7446b708ed777 100644
GIT binary patch
literal 31183
zcmdqJWmr{R_b<FDK@brskyMlp2|-Fi2}K&EK}sn>x>G@=5hSIN5T!)v5T&KNr8}kb
zj1AWP+|U1<_dVD3etGu?VzXImt~JLTbBtfC7jiNZxY*~h5eNkCEy<e-2n5=71OjCi
z3l-kE9eFAafp7@BbyGyiUTeM-SLtqd;byTgDyk^@>GSxyC>K(5@JA&STXu-d-nrnB
ziYHNiyCpyTphVhIp^w&ITFacncr-1lXCojuxwGs-b>fP5N8j`BooSfzd$(Dt4b48L
zX?#3KKu*u7t6#pUBV@rBX|+)0UAplgtMQO$^8UANf#%mv3stY1_m;9g`W@oJm=FkZ
z&xG?wKL}@|&YVF0^!=Qf6c5SKdsw%r2akRrM@uF{{@||XZjFZg;qj>;Gvs$f07~1@
zfhyRAi%^hnTstAjgZz%DLHs)2|8EZBPIJpAfE|$?ot%8h<}C`s^Aubw`N@UcL#Gi1
zLP95;#*E3y$*{06lkUuqA3qM3I4H(AAl!#ez&(;co$($G6#elwAt50rCnr7q1v+^;
zkIf_s!jbIgD9L0#LfDNNG!g-?uUU-F_kKto%G4}QX%avPo1@K~aHsLGzOf>a;PBCD
zbFrw1Pr=;Z-=BqrW%e5yVvQSS<JwtC9zr+5DCJkLUL_9&kn^^+w6qKiy!+Py)`y&y
z9`)u<RCu7#$-Fi+Hdc5@iHOhlutuv07A{KIN`jd@vj<<kOHvQY?a9ORVY$MW$CrZ4
z=nv@OROmu~&Ie=nr22CK5GSAU;7b5{8*UX9MjNjCcg){c4-qE3{O4NWjMQ8IU!K<e
zenMK>^k|ju+fKB9j2#^(&m`r|n@7WCnl=$A$cgziG~w*~1t;<F+%|e2s;jHtwR`xF
zTYyEZQp653B;dT2ef|PIN87@Whr~pK(IMmnP7?Oz$<q<7cDM$`&fNMv{mbKQlY=~t
zweHtuUvW^!&K?ejusvs=*gC++Ka2|9n|=DMFIK%xGfUXki&Uo--!8d&aJ$rR{^}uj
z@&2~<iyB-HUF1ZpA-^zNpT+UUCn8$knaj%0&(E+h^OFlU3)BycpIQx%6e`&HpuDkH
z6O#Na6mgv_cVaCB2eazbR`_(!TU8v^{qgX%@YyGNm{{wyc1C;6hrF9Z8pa3u-?kPV
zUtQD)ciU+wZ*qEY;G!p4y-zh<TeLCH<d}WK7X@ak1!hY)yP{rLr#_Sc7Z=yq5bIVx
zf6`9774PPnZ;>xf9A>Y=-uqU4RbCtK>^;|68vRJSVZ(M-lGtsbbO&Wq4ZIS|R!!N#
zIEk>sNFFgfTSInaJUJr25UY?*pCZ5Zc%kp3V|LjRUyk!w6S^botycC+wFljKkyD3O
z!DlPzL_P(5yVww!YUU<-+a@>p)N`JN)oo7SQ_Z8_`j|)tZPv;U{g~GX*X}<fMuT{Z
zhj?2<wXv}g6BA=#U??F$H4#-WT5z0q^E)q~B+#4Yif`a$HIDey5cYieaju5j;$58t
zKGj96rBu6|1IdmMWs#-YiP>hY3sU;!SyVjeJ~|A8xw*OH?WlzGsqzn!_Gsg{5T<Yz
z^r*&Y9=c1HnAJbMD=X7lUw_o$QXyUIcE5h&n<CrZVuHlk-I|skxBZJ1ZC4zESYn54
z$T;HL`5)dneE!_&Y>4)D<~AO_fWyQy0x>(6onbfQ@0vW1aq5jid+E#N!xUW*J($U4
zSo9=pTI5`YEnV-`?_#zjt5a=9dTJaD)5X4-x_X6CjeE5>h(&0ti#~~e*hcYoU}@2u
z#HP^w@5N^EoT0<?4GwM&j}S#T$OD;|tW<xC<h;xD_)ER}3_l5`1NG&Fz(ek-@xa*f
zgMkdHJBN6VS|1K=lF2LRZhm^b(^~2FB49#0LhE3ryZj0TA!qzZowog~u3&t))<`0z
zAlFh2j(9)<t*Z{UHGPA8rs8`<4?6NpUS3{#>}mJDd%qIVF1}<wvTXj~)E)9Oqz<r3
z^0xTnN)Gu+q_o1&?tCOn&!=)W>Cnuvz#kb|%imH@k`*d!DU!-B!Oms+hBZfp&(6gf
zd$WJ`kQ=Al293}9G(&g#J%lML-2YHNKfm(B{iU}=1?-P$m_vtHgUmh&s|Hxc7-Lk>
zQV$9Xzwq@fcHYi4#xQ%l>kz8N_Md-;rM|gV>eRyWbD5iZ<dRSDbz-|q3m18~i;_Jt
zMiqoJAv0McYtgH@EtAl<>%?7J)zJ})y4?}36jRFOJ4B>Z&dVY?ksJots$neZv|?W8
zgUqPor*ZJsPC-Og;Z?a?e|TXw!KWyHF?)k!=&LnJarN5pH6F8pb9{MYo<p!#R2DpJ
zrpyhBDN!($goTId!-8|J068c{*khun?`5`&-LhM8L8mzS&%1Z;>K7g!>>AJnNB3L!
z5=K?~2<pSuj8YYbaY_T3>KINWM@vr^F2ZzIRaK>@r_0OB&&<qNO*OsG%zQxN`?51b
zIq>{dMp{~0PEM=FsH=%dtg6=6Qc6mkE1#Z(*NYb~U=mj;Ou8~P8`#&TdwY9*iCKzV
z_lpMdVZ5*d^72NOzo`-TI9C(O8W(jvfTiX~hoY>!%S_uFT@`O;eYz}NJW}K&;7gs}
zdXCJp&mg1qK8>BDm3b{$jZ4O@QR=w9wKDeR%^SU%00WYS;F6LO#Z;NATwH!+JONRo
zd?L9jE9f=j<KyIf*3)foq<l%(QfLJeu~Z5k>lhdqNJ&XqS^Zd@XsFw*#9^y-(RNz6
zI=kDcto?#@NPtyur9*?VI%mROJdpB{^+8_fNb{Y#jGh}%pq!Cg!#L&W{r8x3_4Mjg
zG&SEJ*2jv~Ee;kJ-Xb!Vi4{=Y7z*HiqPMX)*dVQ7?!AlqzDZu&YOES})rYCsV)zLr
zo^8PDtOcoW>g1~KYf7qS*j4K+M=CLTC7lnpr}SkdCFSNXK>374--UC|KJf2TRtHiw
zkJ7*l@bKg(Cy&FHKd)O{FnJj#3+`@jgN^KCzpZb<mqG`8lfRWX{7_I-q`7#p$E?77
z;Ns>Z6O*wNVam_v;lvzdHJM{G-C1!)msD$Io-l0$K~aWIXfWbIsfXOq6V3&haVJa_
zd3$?r|CmaB^Ck!Vg5*lJZ?tHUeARTY^$-0>KAX2A2RC01#~VL-^s3ZR+oU+4O3^CP
zU$1)wauVDytUDx^rcq8nkwWEzGV_3dxG=M@&|$F1hVTp-SpzZg<ubSXvvp@lNFGYI
zJ)UZc$yHuzc<SX9*~iin7u8@&UL5eu?Uv6{kw_8Bp>7ei2;LQBaLXZsyTwXVOKWIn
zeNHx3z+r!99g?b|u!smsvC2CLgT=L(_R)vf{huC%l;&e{+z1S2!Mnai-KqRe#bToV
zmCNo11VWuwDO<?Pm!ca<5`k||<NmrQ4x=yVPBoWbaapaSBXX*Rf)v$f#uHtz!W~Mf
z8?X_XiZ<IoFvCvq#T(bx$LF?`lzR4k5j{N`IC;sBCVpOC-qzMuSU4HVS;Q2Aw@66^
z#Xr5~w=>(A?}Zhz)>2ql2<Jy$ZD?57X-a{f5asI8^ulk|Idk@mjEreAG}fp0b_NUH
zzGbYU<Ul5s|G0YLOdQ0cM~`lJpGr_Hg&d&sb&wE|O`6PEj2xtdhxG@X@uG@~%_}h+
z20q!#f_K(s<!_ushHy~R{O{BhH0OSZg+24hVyyZk0qrF^y3M(6^9pwqBO@a`fo1pQ
z^Jhm!Mpjl<^s4<Xh_IBC)N8dWWpC_w9*S=SQ<6sviREtvETC<u!h8@45u&v<(wcs=
zxkzLsCb94x#rHl=`1g%58*zWMgVfD8{Y$Q!{5!*ktKsE)qrPlvYHG8yv#vj)hhd#Q
zM>tsK<>$u<I9OKuk?K3_%%n=|S-&eS`(7UGl8lL&V%N%2rnl?vg50W)6XQuTtC-h5
zF1H$pU05`zv1VLmxSh8iN3l0HHohGr-U&4}HRa;dek2=s@>J=1fo9tiv^kM*$}{fI
zrfDFq>0RlOnXV^dZhU-RD)G~_$q1^5<dRf=M8vr$cF16mDpQO^;}n<&(~`2M**Sc|
zqhZ2m#QmQ8_!KRb?ZPB!IZV6?4JABpwYRkr=em=Aw#0FLRz68QnCCb(`Y3bRE%e=$
zlRHB~LPA9q7Z)e{1v@+=I&dzR-2WLP8(Z8J9n@PrU%%eu^H^VB&sC;&e6Lv?#_}s^
zp0$&n8TcX~A;+EiB>9GaKma9=8TnN&Um8J*KtBQMWsE=fqFrONjxG+8_Ecu^V&WwM
z$F*sp!|mqEP6OAjIo5_pp7xuAc1F#K$<n(d3%a+pNo^w+tzlBx2R?|Rn-3HOGedPs
zNF2%eu!)d_BsC?ajo_B7Y#aovjm^hpwRsv=b-TKj6qv+}tg`w;mIu=<34wweJpmN_
zHxd1XLqkKZvmNQGA07l7K!m5T^TF+EPnA7{dG5;6Zf+#yeBiu25$;SnT~Z=&If8ku
zVD$Ej{(STBQjJu-falMt7b>?GS8Awu2AD)h>l<o5Qu^;s{v&-)etiMe&gnDK4@N4z
zpjCku24=b;oQ-E-^8&tBsjq1Q1~DaN)6@toe5HgG6&rFR3jx&qG~wpIQ^w%I{_d@;
zWT@f$KP|ux;I==feX9#AOUyM)F-IeRi1w4&pz%P_H@45w;jT)jitpGJwY4d{m5t_>
zM*l%vV%nSAzkiwjM~EFPeB~@HLD#)&HdOq!%*F3E@x$L2>l?Q3w)v;MeH$g<z%eWl
zb`l3i{i89Flb5_VamB+p7h3WANrsH{T4t2|wtll*`QwxRWISn<q@?NSPF8MbqlA@&
zoVTv<G{*_aN;|H6mByc+7*h+ZcG*PkBV{8LrQ#zgSZAauT)+DHoziJ7t|iv08x`p2
z=s4GhyTu$J5ifu~&Hg9bI%bZkW7RI@If&LZzrMd-w9d_L)OP7c(RWgFt;8%;<kdmT
zd6|~B?S#wX0B`v2J>~t~O}aXp$#0|%=pv@3%<Hi2o0*#{Yjo{CZ|KtG$UBKWQ{8g-
z;vk8wbgj)D1#OxtC^E9n_F(G8l_){xOe)tc9UUcILP9p4Dm<ma-mb0(_{?S>ZD-mp
zfBB;6u^pm~5w$o^^jYhA=DOhkp?PXMwvO*~CYR=7|4LId58KtNue4IKyB{CwDx*(p
z>f;z0+~CL452axVkhpJ*F6d5sAx<A*`gB86l1KeYo<@!8;998K)I+mbo4H4xYhekO
zAKl<*^wx~EEt-mTYARUg?(a7*m$rGC0GE4<oznj_+n-G{cSu6x)8fkn=`*)@KBq`W
zpPCUQJ8-K-Az{^^#$gc9Y1PvwG{=k5eY>)Ii@44I9yO269f^&OJWA=4T`Z0j9qEd=
zoBYex8)?0LeSHQby@|}c*YVi%%ghW1m2)y^TNI}!%x~QI5=<j8eO1=LV8RK}gVK08
zN}emr&{lQN{gg`56kpRUROw3dnVG8}Qek=$Bza`|kTWB&V12k%BUD*gDeiY}q{!xT
ze_LCdy5?QOzHf0tLM$x)HC)M?oyeg3WTC?IKF-yUz^~2!Fh*5XbwKGroplq3F!$7X
zE=iTObEH-MPf}+3Yj0mE=Z77$Nt&WPSn%q52}MsE92U;Y)U2#cL0#XPV)%>aFJjW0
zTmNv7yMAS&h|V_~c@2=J&y$hKzP=`}tSoUD%<|VYw2~{PQY@bq?9Q3)EwD(^wX=B@
zC)oKu|Kvea<Puc`M|+Ai=Rn+s_p@gqsKwSZFCRO2S_`>}uyAvSu|POU^<R4z-6boO
z2dUe(S#VR}aPJ3|%bL84i(qL-d^b5;`5wo<kn7>@u$BAj@XnObVI5V(^_8y#m1$q;
z>4zw}wxeT58=_%{Z+~K9Y<!W1roFu#7K#&W?@$-M*C@377QtRGr^S7Atx~sdV_yxV
z6l7%HyXs5Cbg#v5cVmIZV8DQc_rCA$+?!R07Pk~?z9_Y)npZtyEupzgNlE$eu(^%Z
zX}mTV?Y~{OJjc>-`C+!smrv%yGErORZoB<Sf!FI<=l15)%}S-^T)B(3IWc7UDON_F
zQJr7h9GPBv&1;pM$>`wVFxQ<W<ghxvKG)4-K6GaV0|R3o8IOI{I)izxI|<UT6+zO3
ztr0fmkf78<T~Sd~hW*W9H*NG~Hz{GoxRiBYwlc{>#>?VdM945*D*17m;u6J$#<Tkp
zNr|^q&3D#jxC)J~<5FEODJZZ%JlK!*d>_r)(7JZNN<mGH&wlxSul?dcVef~BbhNbM
zVqy~jLA`oq(<^qeXY@ecE-!j-Zx70k5rvD=ER~s2!m>stCP}#N8{O5_;`LAH5ZP!^
zQd~)fTCMYEwK-7-tGK#5J3FBxFlmVw34JEvfBv#-?)?~u2+gqmrwuWkoE#kVdhG{d
z#Sv}F$Q8;rI@uVlKb|ce&0WXp1xqL~@uEW7ng#?qF|&$r`z?Ex4gBzp`FGKonX#@|
zkXTu2Tc@y>F<##xOVGc~Kljn3d&?75`d>2>(9&Qd6~>%E_v-a)=3%e1YuG_%nuwVP
zY}X<Y?q$NyCyJPqGX+*_Y1Wd59Oqa%F;Pz^tCK*Bfg?kUh-W)<yD*^Khey9Qh-cVY
zaouAG(e{1{U7>S(CTEZR-FgHuD*}N<>KHV)HlD6NUqv;xt9K_JG1Fy*$}6(JrgCtu
z%kd5l0HIG$3D(*;u6D3&j0Udkv(w7CThH-cxFWK@LinyG?=cEOxVGhqMk<}`pf20N
zxnU|jR18TTrl!}tiW(ZPqoU3e5xt6yy>7QSFgt5(yE0GsoOQ2ZDk36cdU_hlwHf7i
zs?Y|d$tTfMAD0`0tM%)vtE<R54qmjh#Kgp1-QB+5g$`B%J7P{GBp3=8W{HO1K-L&~
z)2H+wK4eqNlN?y^S$O~c{pHJ->+0&9n~Axxzg|OCq=Dg|ODW83z!kj}tC26+T5P+(
zNKgOV*Vi{Nu(`Q8D=qB|>taT-p%-gSz6%cG6Wm@5ZGXq#yQ003(M(T{o|kf5lym9l
z<Nhq>x=R$}j*Uq#Q>H_K%dYKGsihzt-Be4$jc`^?wGw;wt21)FQkq|{eMQ3)px(Tj
zP3d#ouwB-6(%oL2@ZP=0VmaKc<>bHPy56ar=v(!rP#~ETW`liA<6)^t!MB%m>H=@3
zDfn$~-n<z!%QsTi&#e7UOC!*Kca}k|+R-_j>J#EVPLSEXuhrFUgzt{GHkStkN`(y)
z($fA3gDmy!G2$gF_3Ncho0cI<WVB}6w>8sl;WbM0*%xMcau5!mQaSbJF|v<)ps)Wp
zWS3IFKHDm^&L}wNXhP$s_~vjc4Z;L^M;XLI43j2DzC0^*IM{PAe(>;NgUdQ0i=JSa
zCyP2F8#&j8@+-`KFJ9C&HnK1<@H%b0Tb_lX<g>D&aae|o5oKA@IhkZ>kSwW%ybCR@
zXL;s8J_0vo_D8c&9FMt{u`y$5wjTe5A)Bcb*Bl!Mbc*AsbIklOM6L0lE`%jkfos@J
zGeNuD)lyqftl_a=>dJl&20|TRg~WseorAq?sPlEZ)XGH_?$MT0iD&pmlV{lr-r`Zr
z(&}ar3^I#lMz+-h=7HJ;k3FIwOrT*gdGwH31A#chF<sc?_~dcqWmyv(DW0<`mhQq!
z8A&y@#BQc26~xqoC5gw49v6k4o}L#wGxMFu`1;+Ey@b>_<o04Vf_JBi?E8@OulDc7
zgP-l+bgEc&B?ba<;YsY=J07fX)zyyncczhCMlVMWf<4HoTXtus*>kI?e%?d~c_=a6
zR>$igrJ4_wM5gG8h<GfgBqs+=Ot&UgRt}54S$Ei3Gdf83IN-$Sm1>02&ta)^uE@(R
z<%-4V&GTOy;u!36mx=QJ)f*<o5tFvVazCT{`(gzf>%*d=qH1ev*Ve2Z-^-}(K$t^5
zA?JMHM>%s6+Pp2j<Mkj0?U}rMD{K#miHXNat)-`jz64+kX#ek}upMsj_es0Dy57C}
z>aoQ*|58avNXQK>HS^I_VJ*k?qI55|)1psW<nmtP&h+D9cio8j(?70RSy?sI*Xw5u
zg|iE?{9dn3x<?Zt7|a-khI#r<+;u?)h8J7|%OhW4;chMso1ZuGp`=mYI}QRI@-D^R
zzJ9&y+v5c1H)5R@<ta*^3dO?OM<=Vbsc;i6!Z>YW@nB(rc=+&O({5>Ku&r&i_hH;h
z_=RzvWk-_YqmOd_^P@yWMBCfj?Ck8&H4@Ot3}ov(Ip6BkvrdkJpiVo-Yk4Wvg2FPr
z6|sdtVjEDZBB%*fi>%Wbd(A{xubxLx9l=pZy6EXe0FI&kd~0l_{UuDpm<w_Js1pa6
z3xOrSRa}LwuQY~O#zpqDNJ2&Ud9HCM<J|(%6QrHj5YEsXp+iTCi#U_00l9^d@pjjv
zj!Q}BG2P9P?KG0L!qR#0E#iU{kMUc4#MUX~c%XcGdlG>V^#ZIwILxd=i3YJu3dcqu
zDk#;|)d|j?Rmqq4iZVt=TnB_3-tMW!bKANRW~L+$s4L15+jXCe-**1~j5tvzraJ|o
z@bIZmtwTexlirMP@eusSOxV1B0@*QKi2S>)Wsm<c^a#HIx%PiUo3%Vk?vJq>s^g(U
zi4P134NYdnYk4S4i|%e=Mmv9_&Hq4_3Jr1nAfihYVn<4<0d`N=bIpcI(ld$A6j2kP
zR$SvD5G_J!nTr1i3=o8BPe;d1BVWs~A~oS@&pTL%v4J~S0PDv+>8ga9RtD&%jd|62
z)iobQO%`fvk>gW6wML6?7BSI*LJY9<&=1o@bfp7I$~ah>K_^k}zm7h6VGuEG)uNX6
z?p^Y0v8-!k=g&t)M|XCjijwGyBF;@c5QW>lL!L(rY*Q(V`X|8o-L=fPuU<{hz<A19
z`xJ4dsqrb$NNc>WqqE(Y{vP*Zvr5#mC%*<dDGA`)?s$mokjv&^u-VI(FBeNUwMMQA
zP}{jpMn25_@L_jziHe9wjL7(9t2H`yZGFAtN)-tnr2svu^}FI)EsyyqUaQH495d1h
zM|=Bg6bnHYZqQ0ct@RHdbn*4*ay_Vfd3pF?BY$jcY<GPQT6~FzmZM)^SPC2JUE|h4
z8J6$zOj=<lI12@8@mK(Vt)yEzYw<WMK0dzPpiTEX)ep7{eQ%r$#_<WquUx9TU-8(K
z_NleiC4gPmtPOjYdOxJ*=2`+M3Z1#qlW+INY8Lf*j63Mn{GnDJa4X#IZFUtmiS-jL
zt)t+1)OQmnBC1*FaBo4L>s@gK<;gFZ+1c69x>luin3$M!zgOQZU2+MG;(YKe8|%|K
z|1kQ%<sQAjR*SX>x1IJlE!S-W-mzx_-g*SY%M>}pq6lq{3qQuF4kI*RDFY3ZE46mf
z1~8HJ<u7=OA-T`UX`b1<Ab)X*^whZk<a`9^FMt2MW^Fs)lfcJElO_I{vsvIqwcFvQ
zTe$z4@k_t)(Ui6oC|^?_I64+(PpjCm3!e4XL_2W`5@}Dqd7Np-+_wUYv0Bmen|R-g
zstn7ws@T%5+srDNZAhQ0p=JKgUvF&5Ri<AVI2gqY?a$3`S#J9#J5n~=A28l@Z!Gku
zlTuN!G5e){wh5KIRHs$*^KLqmRDS#RjcV^ZW~lX7r!DMNV?uocgWzDT$hvA+0WaD4
z`J<z6OE`9lH3Bk#;~QW@(oUn(vktg$%W!I}<8AI)o5_XzVcLfLvUL_g_c`Ju7l5pi
zcZ!$F8XC)9jPyLkaF%%Ib*3Wxj%3Mtm%9GpMm{v0u6TaTl^JV0(@BA+)ZdW3)X##T
zfaS&e@{LqD6llx3G|;e6IZh|MSI=kEfnmvAA<f9hFc@>&?{*_y%+h|WIAhpdY=)id
zt2GZ$NK4M6fdY9_=}gYGi~Y+%s|9B4=LIF+E)5ihL{~D^JUyPe7`dpaGJVm}&zMw~
zb^+c<mvKwil9Qt@Netifn1SYm5j8ZMRsLe|B`1n6Igw}D8q??d^8>Z0Wum$L%ioAN
zZx#>V)xDz}<z>yOIR&|Va6dD8NNj@<OWDC;o5F73bC&yreJPupB|Zhkd(7uWsjbtz
z3NFpDf&+xL>=y!$ZU^1hNrynr3k)UCpFbCQa$;e)JT3}CNFTpG(5WstIT_#z>+@A#
zzNgd%OTPT<KGFkeWzycTsWFnX=CND*J&VXpt|g%>2Gc}6uyYmf;wZks>F3|vI^Vng
zl|WX`Wo5J~SAJ>tnb4jGGXQceXyZjQh8@1MtD9D&ytL!&<jBPEbXH)=j22kSJ=sr8
z)7slmys$7a6>knX;cia(#fYz5DPS1AaOzUs_v3|!gRxb*;(><AXxsj(>j@MDPi#nV
zvgQ*BxBbnXZ#bhSVqSr+P2XYWP52t3(2Vc=dZMGNYgyvWiHINwHpn~#l|Ke{??^Vd
z0XC+iqXS4t!WD%WX5dg>lZR^MX)P9vot_oT5I-l>Rmq$kkhfgV+MbuPDfV*h#PL)F
zLuBql)2~%*%kt(e6d6--Zn3eN^76rF9~8A2z8`Ws+y|U{ce~lG2{<^Qnps#+k6!N5
zWG?aX)nZoI2=z~tk&uzyPIyMiQM5By{CFk_9}vCdNxQNiF?TcWwe}|I0BH68>r?Kd
zg^r9C!KSA`?|ECyVPbRaU6_nEFWb&h&8iEbBg-!%qigvhphICaa#zDqjlkwoote(h
zAifns`zAHDrm9Np=FJuyk++A_5<+K%eh}NM8ReahbC@KpcXXzZdK;njQhB!ZYL{kD
z26gfH{rYQ;h|A$=X=xX3c*||fuNsHsDwFyr;M3lT2#Sc1Jj>0;$H&X-0PS}DRmL0V
zzT}+5*$T)dCYKK690_Gmtj*Q0JKMXJv&)yKPq$R_p!D856%pczHVelHx_30aN2j=S
zOZ^J@&rRkU4`kuLx22H*Sge?lXAsqe5c;^*c&^%-BDkoZ{g1*H6Q^r9ZM)U~Jh~_1
zXhLw^uRpUw=EJ`?rY32X3cJ6zvj5Xr{!a(l4YCGkf&+o@#wR12Yxy(6Y`j}MP(v3c
zB#hJs(-hk+WxjjojOSj4-RP!<kw<JO)>0%Fj*Vr691MBX$=xt(6Da3RO)pt!BB7f1
zEQqzch6nA8@gIemJiEM#l!PUZHpiAbJ^9J~ko+LRnqmc|4(SwnF%i=lEqkeVg-tx}
zp})tmNp}xAfxJ%%k=f?A@;`mze%ZN3b<t(8rR6c||84}u4nJu3%_UXah0<Z<C;xXJ
zJ=Ozp0pt0Y+%`!KSq6Q-iu{e)`mf)FffYzCOz@dSe%##-DmO%qUd`z;_p5i6sF1Z%
z39`<6PIa*S43PT79pqczDc~??@;-fnJezHugnhLW3;DJ^lxJAzK)IsKaeE_6ICzyH
z;J-ZqXsK=UKYHuwnd1^L8p<@+DUg5w|Cwu@M2jpb5m-d@t?9H!9P$=&J=GQYUx0!V
zfk^O#qI3_6*=7C^T4@EZXq_N=e>8-<+-KxrV1!%YK%y-#KR&8X>)wc?A%rFGLv2`&
z{J#cZDDQUK;vman#F?|ePE<gNigL(dIWBoOchD1A`XZj9BM(o8B#5bFP!Kz)$7Q#T
z=P<6q`~2VZaGnYI=PcKCrt{0N1rUZYD5eA%^yV5UDACOe!u4Xw+_4(0_9vr*75Dn}
zK$dnn3fc)k!v&Ws&?*}kqJY;93=E`#Dgnj>yg<U&=P8~ayGizVas$`CSFEuXU9R=8
zo_o4}*xc7(PtdM8f4)7_;#@uLjc2Fdpg^JFWdVDE{)OV#Ci<oV$P=oqX~3ScAK+KM
zH^ElEHR=m8r=p^w;k`*7AjvKY%d{>mEYQiuj{8Om?XR^1b<m}yy*yld9SEED;^{DI
z%(nLgWrv5(R3bH*><j0grN4cf*t%GL=voyU9WAv1B_h3Tbv1;Cd%Re)&6j6*bb3}+
zA9P8k8H#dpS|1N@s;aC-RJ5oE_FopfmQ87Wl6xo7n%`>jj)jGVv9Ym|l9Hq2&Oo6R
zY`(o!hpqqSw|NfD0~n6Un)mr%zkUTwc4x;CKihUeEg(Unxv5Dj&#)D6yos{kI0|$v
zmGo!EBHAVt+iNcPUv=HHcgzJsaID%t<T8nbBOjTp;CiUe29x~3Ed~c7ei|X<3^O`r
zCNbX@@57(AF;`R!8MTRg#Qrb(DPDS{Y<DpuEzN%7m9m0@g5jO|y(98zo?(QEW~uLE
zMtnR#x~$i)Ul$UJ^Cn_d=Ar5~;60BwVI*acCA>Ck8Antr-dfu5sI`3s-LH&(5Xq{i
zy8b6}1NY+9Z(6<O&@bwUtpO(WiJqmU<!K5&YbZ^td`T2TDCN<aH43sp>hk7|mzEQY
zcG>F^wvuJffz6NIT1jQvF6*zRM;pgDh-DiMxKB4qo_)UOEE{)Sn#kD4sD353sT#U;
z|E9Pwj=f0ay%?JyfLtJvG*zUm?eZ#wk<)s*rH0bUv?hS!qWgk|xw(1jSALT&=G<?w
zg8f|L5-XNgfOKj*uT%jQT*wQg768YVz%YCBmoj~hJ$v1$P^N|)A77+z0w|<p5h}Mm
zi!blDLla7zHRf6ivZ})BQ4;G^=0C80V9l+He$+Z@k9tEp)C|OS)|n6#Mvv%O53=Tm
zN~5Ed5+=v%LJXD`3^}hoSQ;uFNOpTaLVOUDR5l4~YP_+w_B-vSAONdV^jVbQIrhe^
zA1v%Ge5TYD6>ms8e*7#QuxZVG;xxHrBMu4cW5wm|sW`Hj;gRr_)fW)HN$ict3OiI3
zx`~?JS6DbW1a=sN;*o&&HDBMo<5wZxsw7u3AYeOxu5)I+WMF)dj)Ozt<VNT+aQ-h<
z|1d|5^Yf-=KKI$Ex*fR|nLc#@Nk$fvuLRr~g+ZK6q)jl(kf|?m4Z%5B2uX)1ar*!&
z4h#%HhXinUuJ6KH^LN_6v;_9%VMr~3e&ey0U`FgjKkg>mi}5nRH=ydHQ9%kO9*oH;
zT*;e~5;wCfN&WD-S3*b)R4K9Xx(`E<OEc)}#qQv!3kJ(=Qf#>AuDDlnaB}u$CQpN|
zWJO&LPiQau3L`r<kcOiYdIN;F`nh@(E5n~4*`hxD9wyJyqp6xPk|IJ$oS8NL&x<fI
zG>i~(a|Na%&f*3^$EaJiXP@<=qbP9xNBGs!z-si}U+7i$@w|lc);B9VXL*hZ#^9FB
zK`S4-OxyjaFRw0W=tHX_*JYL5ph^N_L2>bwjrbXck%rIApXfWS6l<*YWu@m@L+=kJ
zVyZ0tikaZKSZ0)Xw%a@+R#u#Di<C%d!vU53kANJywR62k>IN&_|DtY~h|zH^({jCE
zUw)~|4kWX}HPIS1xztQdzR|BOClIce1q@rLfALVUXUoV1fWG^(f7iuqHX>j?-AFL%
z>^t=}mqy2<JAziyOI)~EcNPKj+R)ITUhcXNbsXgQGKU`z_-2q4!{{N({*+AIb(XT!
z!bknwy-rTloG`-G?@#a)T&jGClruGY^UbN=tMq1U8bEfbbzPg5?@Z7+n&IV5_KB$s
zH>&pbUi-fl68w5Q=z#8gZLu1J&h*FLk7l>ERtaFV;g$oJW)H+K!~ACXp&;htdZLxX
zy(yt>G{xJWe$hCBmz{YFQc`F+I5-3aU0_+|g#&_Xiez!B{p7t@bN{-`s|yz~?LV;i
z1f+x^T1eig|5u2umi2(@j|hV+a!tGOc?yH0pD8bZ>7bS&ARw4Y_yeFZu&_`7ic6Q}
z2htUXbI;r`C>Cgigv#H(y<Kpvt-TlORcbat937pl!D|lWk*sl`%6^J)%#3E&J2BBV
zKCXW|HTlHZvu9~#WA_ermwXX2g`Ut$hRoXooN&vNo;@)=-rlKYEp++S_dlqdQul9E
zZi%6%XeO6j8t)$SPT7Of<|tcv)S>}mvG$ImsYKJ#6{P9!>+?QEDvIK?F^?}kAPpH(
z<McP1u9H;gL{Ki!XlCk{J)40V`Ki~E&RaJh#%#(n0Ar!mOcb#aT*soM9(0%3%X#^T
z3f}cRQ!~NmcFFlW9rd6is;mXY)h3~|Ku4V3{=#SZDr+Af+u*35KtZ@urxq7BRg-7<
zC8?W!ruwp@_bmv$jfF5MwU|wDI5EpBL%oLs3M+Kp!A2YINfiU~L0udmKdAJ)LGYX4
zE->g4xr5YZ3|5ATAQ05GGiI3|*lYSYWWu+`JoeZhNTSXVYdC|%#%l6g;ap}hproL<
z+6SIbwE!s|Ymd@67LT3X9EFo|tpA6YLR((`g2q?q!=oc3NeKuzjXTm{^Ja1}=n-Ql
zytUF{0$kMmdCmu?3IR$I#4oWJ6VLS{=T%TakFCap+6**251U>yu(HZXOTQtH{lm3b
zcoIEl)lAv%>gs}=2oqe^+P-jMpf=dD^gm>75aaWg51?hUHBrnyS0DBSGX+3Xd;pdL
z0|I2EqyYNqpJ)g_-03cF>mwfW!XdeL@7|}pJT4v{Htn*3$HUW4G*@qi&jDZvy>h&b
z4d6$x63U8_3Y3~bx9P7=a{tm6s$VSesbavnWn%a)XLcc}lkna1yh?H0kD{<*ubL1e
z)q}Rhhb#jAcu<S}TPPRG3!5iXNy<!qL*8MZNfvD0)1c!xtGQ;OkJD{sX_?jys01;a
z)*WfSD;o;8dCVppMm;boTO<fn@FsF+zI!kPnTeolqp7*3HWGmRFuoS#2WIu{nwh|H
z?EL09+A^rjRu?3`-tFD8r8?3VECmCRdeyPC6S5HG`oe+D@3X_@LZv>5;SsA?z(+vd
z2n8V*C=HP4M}L1mQFsGRr*6~+;BY;>_4?$!l|Q+dub0gdZ!^S1UA=mBAo)h81Ofex
zl}CM5a@c~`?eAkJtDpI7H}VKX=@g6ny&wexCBfB;7d`2CKAUqCf4fK9?I4WNrZRuI
z)IgHQam?$Xy$bidf@f9Ci#Vr6-m$KJQ}gnD?#^4@K4l!g!(*%_aO&pmNZ#L)fyxF}
zhJlQ{;jS)PJA7MN;!IyW)>}90hbT?4W4&|de%>dh_n<d?dpg_%Br)E*gOjk?%YFFx
z@owyB?5qGa%LOw=`ixL**B52jFaj^@-5Q|-d}3m5-LF{P?=x1RJ|3FwJ1IK`Jp%pT
z>N^X*tI5$(#ov^CH;uH#^VK(B9#b^76arT;+E||7Z~Xuv-Z^3k2qI~lPhX)`YN`Qs
z_cl%I>Z+v~<1z`G^I=73Bm~XKL0-6)vY3QKdlU&P>G7F#g69B-1)NX<1uCCP$t>4b
ztV5|Tq%P!hTDe|ASBT;~9DjJE)A?#*;@$DE#<^(td2MOfttVRt3PW=vqiujiHvsL*
z^({Y<uUq8<ln5Y8Y)niI?HoaKFd4zY!JvoZ;;?}Nrl<ZDQ;i?#mm#R$&kgQHqGI~S
zF_`v$l16vl8hPfu>vC;}|6vn(x(VIykp36VgNluf{gmhOWiMulKuRLwrS>wv>j5@w
zy_G_W@yhF=<E49%p1()S3R1HNkPi%7;vt=bM(af!^B*~$elsv|OiVxWPK92!_+H^L
z)1DfVcoCP!d24xebQBaZIB<bR;^N}g*48pIO~BM7t-aDAsgk=?6+%u}u4Dix`YrL(
z{dq<q^DkGpz`OJGtYc;dAWn>oi6m2@)$K==_7VFN>W_&>$xNqnJl@nJmZvfrwX}mL
zIZJ{`1<#=SGnyi#>qpG0xlg;)EiG3;A*3|Sl1+_*aPc@(YZK?ZdQ#BWX|Yhk=Exz^
z^W_zjGNr>fzS@*|>3Y~~2$qL6lrx&6EgGBqOKxre#Di8U&SittO<ir<9RnRK4HYN0
zOmIOu=<uVF=dSic@~9>RB3}I(SNB~drSYk$8t8IrYC!X00bPMHIu<Hy6ew=aLBkUf
zw}r!3hLTQw1O^&#Rp@BjSET)s1Q~TV$|1^37fug-G`eO$I=VIKl3=}@-LMPK)j)FI
zi(UiOnV1*|_xmRbPjBH#=4(}m_g<P_j2QIK7Y49M|CqWw?rGOina%1O8jw9Iydol0
z;H9n2hI*tZhJO6#uE0a4;{+Y&ty{M&EjfmjpZcS+2l&m;k{^6r`K?}Fi~lWNCLa86
z`^PGE3??`4*<-@{_vuak(c+LTW>EXM|2uih++5s+Y$`vTRkm~6dgan9^xN)~%{<Dm
zCcYrsNGc&M&{^2dtJp5|<bVX%^XcRZ0y;olD4_+pvC}IbPSc=L09&KJa3<OTTHAY)
z`xZ22+?AUzKvFtOzJ3)lEw#D0_z9lErO!_=`6X;FL};kFQ&N$UNrgc`Z*181$^;qG
zbpKAkKr&l>Xb3hqCTM?6Np=B#oX1P0mlI6@C|(DO6ad)g&#^uc?0rs~?(gcVmi7?v
zWPq^?L7&Q9{q^fOC_zF)Ukf^gX*!cRVOYF)WaeWLn&Rn&V~wMCzhp}rai0Wk`>Yb0
zU?mJ40FL)0-w9{xH~_EzvVU?0ZWU4!#ptwN)@AE)Hok_3i|eOsNfZ4AuWgPsjWk0I
zP7%2(5WPiWHL97z-k!Qv?0&ypP_0s5qj}8Va^l%zT2d@i1(}t)vzqBkX=spl!p8Zn
z5vb65(C!it6F)E}p{HOOWw6Ln&krbp)MYwiVjLbGZg+a`yn+6k^!p>IgNb9zbGxkA
zK7mzNrtfM19j&NHaPrzduIu;9zoxvXAehDZp(p5qKsIDBT;>8W5K^5BaCOi=G^ijc
zy)7YlosG>L5LkdKN?iAMK)zC^E+<!!`HK$*N5E#A{GZ}gCyOIDl}4XgBVOJ5wSmj9
zn8->_0b9L2?DEiQy>tXoMHJr;ce`H`H9h*bNEjmh-zwqmH#Qw(5cLot-neAqfze@M
zpYDG~b(~-s#UsCV#bsv=G~jKI0R~}XWgRMa6Dkf3W(oN0W&MDP;-TuWoxGegvv<xf
zD_AHB$h$fsF-y>nR^=aYFk96XMkc0Pr4+oD$zVJyEL4qgsNhGcg#pk)!I=5Rij-k1
zoEj_L9O}<CXaL}Ri!T5?WkVhsn0rU=6Tm=rY{rD~kaA?H6`3N<68oIAG|7*i>T+QO
z%GRhAwm*#)1VXVGWeAY@hmU$$_m{cwYl}(RxWlKCG*Z=2vX3;&&>I{aY?f!-YjHU`
zG4mUB6O*|Q&DY5&DTmnisRspasLBkWVj}v%7l!gCJ3EN`L??C;ILdsqeICx(ZY_@h
zWtnUE#QKAG(}h1yjn!&0^KYQI`RKWbh8%$|?O<PjzqZ@{dRiL2YQ9L3>OX8Dh4w3>
z@gh$^Bl?z4m<MUBlWI*?2aO+8-h{2yX(49|686NAMv_^?k&z_6x5U9pRJ0Oq(d^vZ
zU8?1%fEdN&S%`Vl|MqSMpaE(0+#Y-ky8@x@^dID1lbBO?5ZQQ=JS{jKot?nItTYz5
z(*d~BK|t4vpRiO+Pk%jZQIaQKnAe|!Y=Xz85cNJ2(pL8}z+d$E$XgYJM{XvBL|cy4
z>`~y0g_yDK-9d4uMiSyjmO|vEp3@*lcc(@=F^}IGRV^xfd`k=AiT2Bwr|t8`S`RET
z2uG4XZ;`Y$di6J>wPXNDdF=I5C<!q`xNCuT@8^+_wm75*?AU!Mg>>vqA364(Mp^UA
znGwoxpIzd*c+t;er8+;i?30tIwew7R77LruppmeMeFXcpI{V~`o=vw5Rt#CzLS>bR
zR-yU=rrwAvUG^>s7P=;>n7AH)&QZw1Aetn=l{rTGUc=N`O(*p5(~WZsD7ijoC#cl@
z{kW2}?Ir5&%o)zEaNV!N<D12BFt&5KGniO>ecN|sM7=smkzapctF^in`)XS&(tC*X
zf*~YE<#n#*eXX(;Na|aEt4XLRzrNUZdTg`I<POEKyy}N<0td_5e6wq3V7pUi);L^w
z{A^;T&^S2>JW~jfBQxX8SNJk)=}-7$TPy7Ks&7<hxjvY8)5dLiMexeA<n&k(QFT!_
zKO@HW<cba1;FFs4!F6^UU$42tZEXr-K1;!#!asvatj9_XUoYnt*LPtFd|u1%r+t{H
zh@eroeP!b;<0!k+E&W#R!-Mzd4~@K5#%lOy1Bq;B&G=FnVm*!YM+2~IR3wly=t+s3
z#utn<qDk|r4@(r<RyNLAC|lBnXTCnDd40O!Wt{V1GWJT6+Y%w0B!ww?Z%2CZOhi#t
z<;Mv;3SuNqg2jB~;k+yURH64?-^%<brZop+{mh5kG$Tz}{v7(3!pRT2ajVPS%9F~*
zQ)kg$oWt?;GFdFQQCZdmjmG_>C`jX|oVmQI?N3yG<zOz5qH?Y=oG*6JExLz6SY9S;
zza)v*)jBm|Z<pUMODL<F>iw0MCu~b1Q=PqJNZUJ(rY&d2uKL}Q4c7{eB0{+0=%DsW
z=T5WWxz<RM>3+Rwr_udL(z0f=?eu=3qWi_S;zRANd*xd5gg^R8`2EJ)#^TglTK9(R
z-d7V6WAqXcKe#D&{>kB+8+pObUu^)1K{<*5OLc|#_#TyC&ch=ot1I+E2y_rfA<%Ka
z0D_e7zNb7&a=)USS|whSlZE9G=u6*zK{_MK34h&sPp{KgADn~K2#B7kiAl!nBFIjB
zw6T9h%x6?7o(I5xJ;S5AM|0^Y)%`j-7P0<}_)Rgf(u18jfXt0wgZ=mKBV&jau`8zB
zF)}oiyKw=Mv(le`By6QUckS`_zK<r-p6f0o7*#dD){dhGVDZp+gN;Ef2?2Gd9I7(p
z)_eEDICwoyO>otlh7OO1oN!+N;zjs_!;i_QPoEkzgmrdzXOxxs7vU9r#!R6{VF_!)
zRk?ATkLoQ!<g$z0B_@D9d2#}`ugE5277=CrrI}F9F+sR!`_u$az2%U$7Mc4Z3<I^E
z%)Eph;P_7Lf!ZQm5=@bq7}S{un4uH&fBbrtm7;y;l)!$Nh#NjGHq(gw!2izBhcxWj
z{v&h$)6h5cufPAp(5FB>IPd=74Sj52=%WQgA79vqDSH#PG3h&YD>V_HU##A7ThGvz
z|M3sjrLwIUDK%=7I4gpfuI1V(^Yt9n17{A>(`OQ_zhF@EVutnL9Ot#*xEZMOy-!oz
zZtUw*!_WTd>8tGV{U85-SnTBz&GeSux9>MyQvfzrDhFR5|FZ&1E2}ygsT(<)AbO>a
zUkko@2EoVSU$&GOzXfrOG%o!HJ^aDA^vmRNwOEDkomQ!1N18kcJ|ZI{O}gIUQyA!s
zoczgsh{8)(S64?T!MP?1$V1Chf{wPf8;N4RncC&7n*hXthVhn+%%u5Djy!cW`<sST
zTFizpR(?l5y02hJhi(mesnM~qA3uIDF)}{&-Bo+-5A8wtiDVt4$BtOrL9vdr3~$*q
zi<Hng^)K){5IJQX$-Pu4D<uBo3P4wOX$;DrOc*eDZ$MiIoM5i+n;YN<OIJ)ifBrnc
z@e<M&G1MDFl(nY<K-tO*EW$60!|^75_T!Pt`uck4wV~t$geGLui$p7Ew``-&q+|04
z8YywmsNP8jBT(Jv)$A?`+~z5L08v1^ll;v-?E1mhn78^=or_?MKj=3ULQV)QcuR1b
zQMCPo%lMzK0P0kIke_zB88o*crBVaQ*jJ&dWOg!_i2lqD<=F)74AGbU6Y5iGS%ns3
zCmgC?O%)tB0S@a0e(Q>$b&S)+|DtBcB@jn&_E866{%c;h1A(g_K75!c8#UD^bM6gl
zs!qNYl6FhMFIphiVlD_tJgomF9zp~!ToCygCC?{NoG*b=upJk{Evn9t9L;i0Et5>h
zRUmHsKd6DxsBq>IL;nV?OeashuMgvspN?x?;)g;w90bew_@8aRxQr1Onyagm@nEcC
zb*Ttl#hH09*t+a2Lm!K#{}s&wuw%(PcewI`y~0nhe``7c#zQ)}zlM?eoA6$Ho0FTn
zDu|eOpFG=0AEnGyY#5N<e%k(7?A)|-)3FJ{3st1jOLKrw*K_#ttjBLd;?vOKJAVv`
z>xv<477~`XDZ7f2Mz&vPThrXCm&RC}t4oyRp;WbB$s|KC)?1>MwLl#8^dO6KcuYc{
zNj~B}CRezjcxy>wub9=H7~2YdW=o2bqc(G0q>G!^dMn#Lw?BK5o4x!L6qOL!r*6HQ
zA1GAZn01NF&c32pjIpEW>*tp|3Eg=?q51Ij_Gj(<mJz8|l~j&l;o(+_B5qi{mD<@q
z);t&vUlI=6pnc~?jsodw|34ZJCMG7{YnLAY8P%PoJzV0zi9tw6nC<%p&CNo~`LY|p
zj=7r~!Vf?uI{^tPdB=x{Nm4Y}9wPoFm^5htG?@p`<SxZ|Vp;$4&`%(%I2*9`@;ji{
z;Z#kDG|wFP=m4>~gnewNkdmGKqj4Pw2jQ$%-1Fe|I0gYQV|Y(#M}UAd#HUmlne@d}
zWhzKOR|tKDq1z)<)8r0YR0Mx~;Z07TNuoy9eKMg6sWlB{ct(Pf5|?RDHlQ(id3hK(
z#4QdFNTi<G4LQ)ki;pjg@Wob6^0LqWL)<<iD~pYpIr&)`crPKr47(k=I0*X&kWbFM
zKC{N52LvJXtH~qYcvM;%8YOOru7z3T?^LGK4fOR}vbnAaKAnG`mKM(!a~c2Ja<K)Z
z)4wkViS8V`4KNS??KU_)&PUZcp?p8yNJzi-%#EF!onFNZ?$>3qn8kqpzEW#*y-mHX
z(PoY^1$JkA;<9Jy2MosMNU!#7a~9-BE+IeS+s3j5)~f%}h`D+g_?w$Q^+J2wMQZLa
z=O4s;m7VD^x(~ic$tsOjd4Btfi#?T>3-;|}<j33(!DX|7B;uis`tMA9Ecr1L{~CA=
z)mYaZqxN$YCRuD-=K54KpFL(Yt$mkzu2Tcxe}Q|FkC$loWf;qjT7mGHw%xWz&|h)s
zF|+Qa$)<xlB<aVim49&VGbkwbKov~efIHOEa^teRI?xOr)XAG~$g~LxL8$ol?c2Kf
z6sDa}-5GHTFR{R2`H}%<CMGg=-J42E9U$OTmX}|tX99zBa!UljvWIK!vah}$bM-zY
z$J>=WD9*vn=IQBKP*AY7wY9hBeEwd6#-OuC_=KT=66n{So+Oa01mASq$#+><;iagp
zCa~B{e{uN11+tP;l#{%=4Ph+SLDp%<e0@^NV~ga}vEX1#bl?oY<bpH>|70xaPlBIl
zr`he`!(*Gsxb>n2%V=s)n`-ubpf~z$bV=bKj9}M0wHfnBY#FwtI;5&Y2L<Jqmomhg
z6wr9RK*3KSYr(Iu&4lN4#PQh}cfC{9j}&zJWaJkxIxz{JMx=HER0dX7V35^z-M*~d
z$jinidy*DMFtdR1J18Ix*t%yT0A`Xbe*JiOYw7=$o6`Bh3)lt87Izb|vWCPy1<B#y
z;Z6N`466CJa*Am@0eRObJzSLl=X0DcGy^NqS`iNvxR7VU*|ZPlv=9007Bxmb);3!*
zhRt>Le+B9Sx0xjN?)~r?8D%xK+v`T{DKG91d4?l-3Lz}!Qntb8$SDt@`yr?e=`tI{
zG&#!W3=C16LDi;<&h3-p30DofdYbF{?A<~KFkHNq5Ep0s9J^TcSu69$)g(Ns>)#rG
zOf@TpXbD&-qC0IDbR}5~AK5m{KZ|E|7BHaRRD4FoPD67;WsNo0OF8!%9^^D{+Yh|H
zWBBxVz@S}t5j(dPc4C$PQLNnRhu1z6V8HvF@3U%MOoxH=$989GO5M4WjEhu<ux?Uh
z>})Q{vJE!B=A{Wlpx%;`<nit}B^@5F<!A(sX)dE9O8Xmkl;B?9DEPgI#eGR<+DZlp
zh2$nu3JeR3vJ2Mxp#(XFXNNH<>q=x;^g;ROuoX*Uz(LzY+^T5=Pf2Ks`DyOBt(Voh
zomt^X(krUg+tP$aIw1)|k2rtKwNgB^X<x!noqEU{QxE1x(ZV`Dy8qGq$c7~#a%m7f
zn)?w)@}}upuPr=j;4gxkftIU0PXEH7A%^8Y816eUe4UTW(PSS6BF!I~w!thu)?+`Y
ze>of>dGW4+2Xh}PeV@V3yRI8b;GiX(slKJY26LYpvq*KgC846y^BkW>BcD}9T}{m~
zgJ~MWQ@&^=xvsu`H064~VaiJbFpO0u*3=?BebU3?_dK@;XONV|UmUk#Bm)ZQb-eR9
zfWqws%bxIdMQHPrRS$-4K~*s9A<a|?Q+&jNWISen+?4F#?)VabcPA3Uk91Mi>C2Zd
zGq3hw4xZwm#}0*?Z4Ov9gPG>ARe}mSnszB%$HtY_2DWy>Z2-=jQR+>1|1upKveRfr
z<zq@8q@-@GP6DyF_Wf_%Ppi;!;?FM05gLB15&!~Gv=N>zfQ{qU2&@PZS6`XSt|X~l
zuh{ADaSXLnB8QQl(}u?Qww<6yy8yKfeI)oa{tK<rz$fJNR^6N+G|u1b;LhiE8Hs;V
zC2(6EwTl`f*lA$@ghy;V6-f7Z`V?JZXQ}+K4C_0?<@j{j_MIvc?c~U}NKx15g2)fB
z3nV;Arb!k{JTz3|I>ryJqXzO`|Jf&HKX*w(`gF|J{YjIX3j8L~lM)l5+W;F%(R?EM
za+OHpAaDoDckiAIKWp^+ij0sNn&_)0U4Wa><H4gtZtv-TMqW!XbN<P2{)~tE`f}AN
z`@Xj9Z?aAyZLeQ}ysN9#flz&^Nxi&QW{qRXJjpkWa%|q4o+!F371k1RTSg{qN%W*6
zhGae~*qKOP-$4j#Q-8G_{7Hs5Djbm^Xwb*M$ANYZgN^_M16Xe~YP74!IP_~l=bFAF
zY>t?jJhhihz5mD82TrmWGAHqHJw_DGYNtSs4#?S@oSYCk3+Jg+ke@fzFz5Ko<Og=E
zCV#=C2KHC(tYf7Tq_c~~ODU6pHYT6>&PF}B!^O?2=kd!m`19y?HS=aA81-`80jG-4
z+ZMP5et@|IRG=?ILaL-C!58rNLj#aJcM<qTQwj>MK?Z{d4}eSpjGN%LTs6F?kpK9@
zyLYBvpW}DzgD@;9So`Ry1ffv40}kW{4^l{RDb&)^x~@|Rz5CNY`n5fv9oacKLr#!h
zHSU=0%$O*{);#_3NYqC2?MT!XT+mO{|Ej$T9@T<0UnAVl+-SCWO@tO{uKB>}nY%x6
zaYTdVZV2X#K=yVpg3QCZ7`M3)?0E~|=mXUk5t-e54>U|7ObZ~ql9rZszIxx{Gg+C&
z`hT`=KCPgsD_~__eLeYKcDjioo4K^u@bHIy;d3Avw0`~DEhyPj3|#o4Q+?xq7zY15
z;RSc|z1nzL{mfZgcyPr}i(XO1lzKREe2x0NZdbo{I1L&QSGHua4nWL>`g57o*>5fD
zn8gaY#YU|;K97c0ts}Xc9%`ff-2!&LVW(J@otr{P5tdP7Z6o9xIYADNwmi0OXyd@6
zZyr%FF$aZtx~ih$7im83W7nW1xCSdEUIhn#mR`(w&8nm9hx*H`hvQskV}#;ZQpNh9
zbl--T1Ic#ek3@C@$4s_;P=+lU;!h<M%R(3y9j&gQU<sBR+d7>}T|)v*jsBqM(N^gv
z6GiqkF<sH~cg=Xe^@`XNy?eF;8l0)4rtCIbNsr9)=HSBgf1Y)0;9RZqTpQ||y|3ms
z$KA1%a}q|V<*0BU+9PYM!iit$K7=-UvN<j;EUenazsXLYBqJbx;;rBCSjwmZGr(Uz
zy@5+T|J@rX)9eo(z3r|y7}F~dDC-;D6SYW7*<iKxq;wQl-D9^Lr5q*@Li`}<fM@9R
zo+Tx{C2f(^2@hsbm9<`q_L0h2#!ML%bTGeuWnCZO8_r8a1y)lsNMRC0%bf*3FC0*~
zoDl4u;Z^*!MKfHK7eKtSgS?3hG)&Upm8l2K^!R>&!c+1oNYz8mU8DfsIS0~104b+;
z>AxJ<gE-jOJypYJRdV%DvQz;ow!2h5?3m~@tfb-d(<tc3GBMFiD4@E9-N$tAT|Avk
z8z&Q!6tdw1_$-%7&{4^zfPDefK^MGZ=hj{`sP6@vYpO{I4(XD77&-_I7Noeaj0uyw
z!u8|yZ>}cl>t9@r@h@VB7|g#%%#J6N)3&fVkq{F@;X33n6$9=%WJ+JZxmlK8V2z_q
zehF0bbac<|MJ2e*$=nz0D72b-&>Sl*>k+GIW@e_U8ady&%W-Tv+!()l6%~wfuvH2&
z)f2motA}^V2j=%wX@vF1apYF9Bl!~?3#1`XO$K(yz}e}`*`I)TMj7Y(E<`;j8nong
zxC>HrGa&ruKQwPOV2|DwC_UXq3chLgBj!gPO92cEadA|jvZA6AvKaje4{S=qFU5q<
zP+uYi1E8B>+KvBo`bmYe-o4z<QVYuH@4!z}$AbtO%5C7DE(i!{+<ml&<NQ*}|3n2Q
zk~2a+2@Y`q+bv(k!_Sx;QHJcL;Ne0@SKz((YHzT4zEJ<R`5~W$hY$?~K?XS7L9ZS4
z$1`|zly82doPeuJ!)=KJ{1)Xh%qX&&NJHwUe~Q9?S^aJR?*=aXIc}(l{Sg)Lh(8cG
zBl@>S@Z8{&f0_GC;qe0$$8z*+B$Wd0L2jUx+6Uys)=}<52*5k;F-JOgB)x_FyUgig
z`QwM6!EgVU&&%8ivMz@HcYE>@V$A{ykB$kHol`#@b1srat%oyuh>9Ajb~QtY3nQaK
z$o1;#{jlBs7xx`3et7IdbW{}mBl#wUf7|!2S&r8NnT_-h@cL?5y!}seo*@e;W{Wd3
z11yP4N0Y;&XN^%3a5yd?{H!=H0NCwv`hQjT<?&Fq@7p|zQX-MczJ+8-WXrx&l#G2T
zg+e3CNFy^ILZ!wU%2o(7w(J_lRw6C36N9ogB)crb@0@y`=lgwszwhUL-#_2?FUx1<
zzOVbbuKT*q^Ei*=xNP@;i3?30=%%Bi1BC7WATk62U?qUfz?u8>?gP-GQ02j&cK)N@
z_&@0?1j!*BIzmE1U%?RvObLKIQ0-R~>;TvrErSCGA1I;$C;)<>BDwsl6#c@8urL5s
z9Cw^c{cfBTa<?~zrrU+Wn<G$*L9k2tM-cdapVH~m03vJwg92p99pL+5H+?a(JqaR{
z+ZzMJxTvTffXhI!I`uvDQ7gUaZ-G$e`xSxa<~tK-Zyv3`^_F9{X~)liCEEAcTH?Yl
zL%-NX3-#<S7=X+uf*+IgWO!p}m7~bi+xx`Js}28)9+1Pa6IT*5{krU0r!JjZ;fra9
z8ZF##*|h^w0q*Kxqd~O#(?LWOY|c0{&5Iy#uSD|lQ(&ea50TQ(-1%Pk^h)1lzZCh2
z^sS|wL??`m>8c>euxLuQ_x=VWm$esb1A`Z1B^GwktMjS#IhRGh{ilIN2b`g<0Xw2%
zw&P=9CB%8aTqnGGc+H@{Wf`oD&_OGZ{KSsSVAu9^zs-oax1Xqc4}?pr_{V8!NXny2
zy<i#x<y=Tu#kiMMP9g`DO3v}MGk~7$vkYc_55X)|<x%pp`@frGBcp|j+Ff8rW_X-<
z<~(}m!mkd~K5BO4m+DaKevRqfDE0N0IaA_13p2!N*tt;tO`zKyOfQzp=5-P7#V*99
ze;PL64~jodlR~YVVb?FHoq6y{6xJ={OjpQd&ywV3&|kv1rhZ&7Qxk<YEv^iB#f{qy
zuP5-;qaxdD*FJceQ^_}n$6a%se<?fnmy-AYO!`FZR*Qyld~PKWWx!f-Nb1T$)-NsF
z!K}L|A#iiFH4fnHD+iuD#Nn5~a`5)lvj|%0c(0@|_sd$hwlpZ!Q>u|<m93CnHcPT$
z1H$g&^w~v6Ij?Y~-bqQ}QHh13z_HA?sBp(i+<XhXy;Ay6_Rm-ctCp7%H9lu{UHsJ=
z@18R&C!V450tH~mjEgk+qWC;d*tU!r{Sq-r8OB)s0Ul>G7q~#x)v6DWe}L;n0i;At
zuV3F7yIHs4;Q!bkq+?s9>C^|uQkK(#U<bbBDAa6aVd1x`%3}fIhdL0j=4N_YQ1)W0
zc>Y%YiN_p9j<=ruljp!6hj27m6pvzDkkM8CK(ZQbe!sK|j%t?g>%1x$C&tnYy533w
zz5G7`8-#ZXUhUo+b)f|T1<$@I0n_V#R!UO>u!-DfhwGePpCjMcUbvgQFnUx>>_Y06
zxr4t1%4;Mb+_4zUOzgMEEhhP#gsam6zV0T-IM!I7q6BTvMQB93KoE=$wpZkRh(7PI
z<s&WJe24D0pmp-&7@vszVUlW*$G={^(>s%K2jy;c{8EbUF^^Z!^o?|+?&Vd9cTJit
z4<6>^SGpmfc){E}_vNKmjQeRD!lBv9r7DT2&BgTX!MV97Z5s?1^GBs>N+LPN6l>>M
z=I0~$>c_^%W5%B+I(GamON0$u$U*L3!?ko~7O8#V9MP`G0|bV0A4JejqB4&&R%46j
zS_{*7qjD~Gw*T7<uVn;c@tFjGXOhu7ft5nD^PnLUMuhC_@H<?35GoX}f-3*{QK`=w
z)Nf{+kw}bLng%<y&*w_N%YN7UsG2Y<?{>*1K&AV|DNBA+HX2Kxbo8w>&|K0%Wl>(#
z<D;s>YafA(FtwxO1sK*@I;Y@%y?)I$C)c*Uehh_X5@&ZrIqiO?&(3aWs}*wokjS5I
zZz98X+i*4RthjW)zpu)gJ+3h-Bp^2R{TOS-F~qZ2m)PC@_WPnf@Mj+@zPU%1J~`yU
z2hSH51w!N+Clmx551rmE8hVUv{)PCZ!&mqy<aAX2Xr?beC1Jf{oluvqqDNkw$(s$t
zu8Jv;ZwAv#1)%3{@qY3^y%fGTv=V8OmhU1(PqMVqSZVfs@zwGBaD;J+pAh$MBeGol
z29I^Me?eKUjHo&3pu!9c8xYx?0X=}~5OA(tHsEP-Tfvpqkg<b@lL3zBadNWcc56l1
zl%uaiWdHJ7<`FdO577Y4A1>;b{U3*l4puQ4Ub)xg?6monOSIwpV&2gYjvfknmPra8
zmNqv1K=*>`7UX4P*D7nD%5|i)FdpBVf+};XqGv1{`8Ml2oQ0NhO;lFuuNr$x$~RiJ
zeJ|~Mqhw>0&vRv8x6(J=Q|z%sdK)n!{T>Dbksa|<`r77-0@J#R7cY(6y%Wq%HZ-J!
zTbN@lD*HlZ`+i-WCui(wsm>L}K(@xo|C_HfUP+yTM)Ab3oy(y0QgHqOa&Xw6!t8$-
z`w0u;xua1T+%IHr=xS@;LyCx?7)nh27!ESx40nmQKfGfTPkfY^s7l9^1EiRYe;V0%
z+?cEz7#Ij%0s!OzUl&Mv+ee}c#(pN2YJS|QEId~8!i;n8HQGh5io7rED#*;t1R8AY
zH0<TK%KaJojd57zJ!AIKC$&HB*|2Dc)`y3`tKT?dOhyh?wfFS+gK^5ORFQY;%vU6p
zx5kf0`)YmMr7SaZVW-X!coLx_yGtceAUVv=>Rw<r!hk)64`Yj^&*nQDfyt1R{XUL;
zIn3emLV{0q<=I`WDE^Zld2d}8DNW$QlSm|%|IH_XKgo723u%~sfIMSKM;9$?u9(%f
zfb^H7qcc2&=kCY?Ors>(vo8q9dne#?agep(WnLt(R09E9B)p5|+CqU>kjZmo$)#0b
z(!Y)-3i7I`s=|hhpd95kFE@Y?ZwKw47_gtqt2rA(P=mBVB)E&^8&oE>Pom;z{|Ju;
znQi}B&HM04KhW(yY;ty`97S9!Yo@P1C-~<_<R9jDx>%kCg1+JdTth#Qhi)(DK0LR!
z4ki4P+Ru?t|F08D9ap0mf}b@CqI9krlGzHO;yE~Iuj=i~b1hyvP@Zn@?!UfpgEZH;
z$G@jXhd9$tCo7_qh1|u0=Way(Agz9uuw(sJV!%)zJpwI}hv$`SJRIz)nXeOINWP7)
z+uL8T_5B|APi7;d#a9v-R!aXaI-Lh@`2&F8g3STE7?ALvf`Ad~PmonPtrA|~e^U&>
zp@a&B*DBO>f`Y!4R0D}&|4=JKR}`<WnRn$CC38h5Own_vz^{z8+U6abH|`IIqEG!%
z&o+uf(fk3j=EXGD-a<wP2@pVWn61Th$eJniu6;8U$~s6|x)L8_L43H(GkS1PmF-Kx
zX-#V1iB*o9CgH-U#qm|!^>Q)fh~yRZy7cza{dD1nZszCV@iA|JSDEMF8}Xs1$1-Q5
zwvE`Nc2tdV+Is`qHQgM4Mu#%-?nig|=St813|r^oK1lY#IA$LF7n6ilRaF7wwuB5Q
zIXRD8frK+c*&JvBcHG3rR6Bcndyv#vSye(B>)Qjug$<CFkM42$88Y)0JTb==hXQoU
z?O4YuTcF?}Ml%&FG(Z9=+7`U&4xT;_xQ-PeFK^GDJuaI7N>MQ?ZTfVFoCk|d8#Cph
zAc}=u0m|@}UW1%@qiXo%GhI@%CywS>A;4hlHh4y~plD{??3F+T?g#qr+b7`gSq~er
z8%x5J)CqgEXqp$upD5kkBk#1#qqte^&q|4MWrL@q5i<}%j+$MBD7`=Ln@x~oqC)9;
zGr-y_XR>D8wX_<5Zu^{2-DOxuHR6Ub>+$&3TYGzLVSRlahugR2;NDF@bSy($R?qVi
z95SJN1N=%mvw1t4#gr<q;aaeSRJI4-E8!e!r<ulgzjRl^Dkz?Pq7jys;HbL_wgu~C
zFb@Use^TD^%NFoG6CZ&8<sOls@t&{QR3aVbbc=yBfo~PW6efEnvAQpK?g$oq!#fSG
zHp-lb9#zj0r(uBNKM|OcE|uoxO@j<5N@J_4?6_@Ni|>Qv?mWVtgU73U##?D_*(k7>
z1o{3KAOaj4pgCqRnna#PnwUf~kAfwQYtiR@wLDV|yVa3%?(WFz*9+`fiX5sde8!FO
zkPq3JSuyw_c2`L^ld_YfVspV(jWDSt?N%a)NG0K8=r`i{vXHf1l4H$$<nM5|4yZOh
zC%BKn%Yu$tP(mJ0J22jo@CG;zxfIY>K0j7xmP?`8#u2tVT;=$sFUG(YjXQKg+f;B(
zO=gHXkmhNkl8ZcbME1mxZ{3~BVT>ID7UQexxo>|>>Ne|2sES4Kp|1ij`Iz>72rPrF
zG|5+E1!!ueX-<pGLfd>tgj&#gnI||!k@E?82rxEKu+FF?5M-qTJyr<cN8bI(mohTS
zSd=}%r{ZUb&{&@m&e`y~Mj$Xv5t303xWKa~>?}SK(jx$_z^j9pc%mhkYQzeYVb-db
zi~*@Apzb&zM3?Y%&-!8IT6lm<^r20R`@3c4Ti=ZJ%hh_?!Tkf1{9i)3Vw~uo6J0+X
z=?8X4xu?c**M)m$pcWWM;CW3rRu`E|Pxw8$M+JI}P6<D5h{7yo0^HjA0({cCkzq7#
zWv+%6n3G;6w#$?qvn(P|SizCAwj^L*MPtCNTQ37|%#CZZn$CHLT3tX;{oSmr65ZQ7
z3*2jprhNuI?)MA5EEz@fWwrAhexdPAi}toJ%MJjXHtDx5x&o#e=HF*#<O2`bG{jBP
zp>Ds^x>hbpu%d>&cP>0wW2mDOx@7uTPOoCzsUP^abrj~btIv@XuKlY~Y(It$SMR0^
zPtkQIdtny2n|~%hRP}6qq-QJgs`J;oTFH-)e87~2#3Y7RwY6fpN4oPHW)H3gkNj?!
zGhFDF_{`dm@CM(`@U9Pu!_${4z<5UWjmPnOxc=!%ZBtX6TlIwUd6L96%!B$RFl#aS
z0UoV0xS_nAGD3BlEkCewBM_X%V!<&nOAocv3|QV3ueh`6J_*NI=X8X?j)NztdKzmB
zOM&{X{jXMa>ki4X)bhLzvRuhyEOKS>udFJ{Y3LoV>gDhaUJl2j`SKOdbXPc;9Em2b
zEd;8)_g~g{4;l9c6e0Q5Z(D!VEba9QgGI+^1Nb>JIKH$4+}zwysE30j0;WC*-l_t#
zSd$Qipmo1)$%o+SktBOb8*l*wgJv4w1XeH8gm?B*0Wkq>*epbyKg}wVs21=QRtH}7
zY&tr%!Qxqf-DwozZP1}q0EwiulxFZv3zl8_AQv@JsAo>b!Vb~RolP_CL1j8!MdS}*
zED(o!`7iWU-z=idiuxmiZVCYk9xtk!g49@Qr2|b*Fy%%`B(;TZTxLdRxc&2dD=^7m
z=>QX>;|C+prmCP|HoF!LGXpIL++g#ayausf+cOQgj$5B|bd+X7pFR5_R@4Lz*T@J2
zOohh(U!$J!cl}&;4db+rz2@$wE~V~MYh6jfz-Z9fcz!?tjD2b$Rf2u<Cv{iaLps^l
zRhP+)VS7YRTUuBcro?+bEh}3BpO4QK*OU34HfA5KduZ}`{uTe$Ide9T2k=J2qlu#5
znYQv7OOJ1T$}MDc+IQM&CGQP`l`m_B?O<=`$aKjhhez<bPjm>F{Gx!1-r>+=*p?tK
zfYPyjzRkuIycB7l&mGUPg9`CPnUFkP3u8<qDhs(^`@jF0AZNt8YQ$oi^Wx_5t|oc`
zoxLP$H%DG=qWPU-&qE&jRLm>mjVM12-EXLbkuE=z-bZ)Xd8$cek;2yTNa%sfD{J3R
zF+>*J1GS{aq2hB~Ou>6kEIB*$Sw#dWvF?BKBox;rRqOKZ;Bv<s=VF?o)w)=FcvQO_
zwvHeulLNE~&dg8>_Cg|ON%d~;M}-42DBVlUO#66}z%mUYf53Sh9LSJ2qY{sRdgLY8
z_};(Ij53P~)>mtHKR*B{e#)uqw&2==LM_8?n;-K8S((df`fdr>1Yn9xk*T@2F%v6s
z(T47j9LzNU5jtT!!H8X^_X$8eG*{AJ^(LPP`_kua_b`HLY4t8mKU74)Bbw9ZT*9NK
zal!WvK3+`ui+N7eRxe(Ybd%*<q?H;0cXVp5Fe(yM4K=m3wGbhbNI|e)ny#|QTO^{3
z0dfQ#2?lry5a$@9z+9Qc_4C24D@)4lJoz+%6>tD>y?|_#m6zkaoV%RzGT#(Al57vw
zKxO2{WmpeBpNe=)+r*T>UvR6VDLkC9ts$+emy^H={UOFZTO?WL|CXahiEb~;taZ+;
z$|9T<0{Z|p3cEQ9iu$^RM@6~PVzNjkGrvt8v``{v-E>!)S|HE1jO|UYje^YCqTH2p
zgMjc%*qh9m&+jPgoy{|=f2GHTx09(vl4E<p!`v9rZGwUK9Dz`jYF|w*O=>nsKk%X9
zeu_f}SZ3`;kOJm2EXFID5s1+!Ue%Sg9ozbgr|JoM8VR3Qs=Mzg^u?j#qG4-kM#Zst
zB%W!AWT^i%f}@?((ebm#&g&cZUU$=rgZt8^enu?mN=ssTB~aL7bpzbQN@`C`Y7D_%
z!UBO|_AP9(H6}wS@nrfI$=@mH4?byPi5d#5X*<B}q8SFW?ny3}^;G4W1!7yx(lj|Z
zw0?%-n-R#1+T$3h{ur?gM7If!x;MdWPb-!`kh|_Z^OE&sS-C=fVpSmUkU+?`tG>eQ
z$aC-AVMJltb%C(=SA+k&VP9;DX+oHl=+c%xX}gM<&9z0syWI~48V>MUY4*rC|LRf;
z!0AVAZB~hu8<jZG0K6`(8>3z}M#p@|4}kDKWwx%$vG%qNAvHC1;@u49Em_Le`~aDu
zOZjL-c7N{6W+wS3+po@ir1wqw+~XFrzI;^xpKPn;?}*q);Tw#6{r05I`j71>ZKLZk
zqXfu)GBd%8g4>6)#&;4IG$wdr*18wW{XTeMN=r)2n~ZW+H#q6NRRc0cnOiI=2|rz$
zJd4ex%S&dL2mC9SAbR#NT0!#;@?GmsBXZI<p!4N`hmPnpkTXOTPKb#$A9=c^LV_t+
zdfr!Nsy8V;UFP9>+D)J}pNha=ud6F;Ci%a2CS4*}zWCZQnduM`7^4)?^^jdVX4IHH
z41~8}Ib$?3h<&9Q@`rP(NHZv`2z$kk9W$3|@V4_cvv{?sjV?*#EY+hjRlgpVMGVXy
zgl!1JDj%bGhH4v2a+C~m?8*=yxKIfeZY_~SfV!34#%Lyz=5x<RknOQglmK|dr>UTf
zE9Fm}YVB7As(|uq7dOzxQ^BL)Y`VI`GLdV^!(#j8mmCc$o@W>enBbwFu6*Wt-u5lR
zw%PO$DR9|u6=&1c%<-OckpIGzT4v&iqsT`=ROX#?V^u2P?o0DiPuGy?9{?b4Mws=U
zcQX;ZW<1Hn<xnsfq<PcbUOanP7RWQ*oII5bM+ui;<>-G0A;@`$qLh|qj;@Moy`VE%
z>{|V#9U9pqy|FXPw%-;r4(dU_JHTNU?HPKo_7z)ug47fQQ~T6825IvG&}XPnTIbCJ
z9TnnQaT%G!xPt6#nqwWn9p@cpcT$feCnry~rORlvgB%jXWI$+e-FIPt`;=!c=oZDr
zqc7NEKO4>uo{0RlLoBfU+8`PZjFK5<jxI&&Q1o{{QzBy<V`j8UDq+AN(%)#&fox<J
zSOqpU0rNn%8uPheW3%@DWLwM0d}7F`f4#24ae*u`lufbin9n%`LiAnh*9A7%H!IxW
zE^OtvF&u7MW93?diD)3nlKo|_o@qr6vfuR+>u^KR(zDlp^(+C%TQlDw?E+mRlx0_9
zB3@^S^{}7~&1gxLr0Q)LrvY9=M!cQ>;ibjfH~53ZY2Q3QR)zjv-s}HkC<sgqmR&CX
z+ZSKMaV&^6m#6SrfJvRzHud9rr$DS8CBcD_dYXUGfZy1VEPjc@ywbwRET4NRI_)kf
z(0V|hbMPQ2<-mz#W4YI<(m=o{3&|I&a`-gUkG|qepphyn_L3FGZmA2}YI4PXjV7Mg
z7T<@ryU#Yw#%Hd`+VD1_$#*WXc1bj6Bh=P1@YLLG?XqBLk)~e{%41&1A=o2$8ZH?U
z#~L|#vF*+A{hOsseu5H^vy0w=%RS#!yzk4~j;^!Mx&Fr%=IB5!afx&X*eXuU%(2)x
ztoCe#d+#4dM%9M#f~;2O&dCDlp6YNFZS3YY3Hl^R)ALmWJ%?)6AZLm(NSAYIg$?5G
zWKpH$Go*?+T;8fTM(TkN1%9HySAcnQrO@5V>Btp~S?2n2;%RP}AZpbjzHT3$Ab<jD
zX?Y5}wK*~2T58o<D&MBR6#9GKWFaNA0X-;DL4k?F8*rdr?mcu$UOtJ0o`axmdU{$_
zMFk3GRt2`>e#3WlR&7J6N4gdJ2?jtuN%5?zd+WbU>4pWnE@-17?fGX2vu=Q01Te7)
z6o`>DHs^GfQ$LsB_&mYP!pYGwO~m@xmO8i#nYK-$p`4@FkD(b<j2Q6U(zS&YjO+A?
zp;8k#(4!;|a%j7kKF>R;s7SPgf~J)ey@TQX|K8}u>RX1I3*OT`Qr{p_>ySzdB|q$;
zW<tS?x0jj;@iy#WnN;BHl>|}OQKf_x5e<#uCmHynNp<h9cL<I(0p|%YC<)*H%H$SK
zE|YKzMV?$79EO2&uLIhozg0iU<sN8qK7r_F@aty(6qW^mOgtO3Bthu4${n%13yRa>
zRqF{P*9Gr?C0DWB-Lp%zW-pYLp0*P`s?oaFED#DqLDibw(l$?Qx?fo=FSe8L+^lv>
zH?1{*vuo~9>iW==7A{nzqbYdZqXYuxT~%J5NqH`T?`dAbf0&Bt=2(@5Gi2BZC;jSl
z&}$1Wcz=KYC#0T{V0}r{g(z{OSOT#*u!6}->KH>@SLf_h_N=6$ODjiz0@fuEsx1V`
zfQ${TxX*e2<Ki}{MA3!tYu?_)m$U3+hm%M`u#W`Yx4rze5RwaFTdyRHIx(V~&%QiY
zrr?xD<VBc$gu=oEdJ4`5crhIr#1Jtef0z6Ge|m}F;zlYcIOBkNA`D1^Pe|^8fH;(p
zfNKLd0MJ)ofpM2yU=w&yW}zuv5@hz9E+^;HAoh=%+DZyh9x7F<atCv@_ib(IaLnE_
zoro)wU}7X?^BIPDIhc0Xz&A{%<yH_J-g6*j3Ue;6X>oV^AO44oykX@K<cR2!(z}b=
zWoDU!{Jq3J8r19HSWIwtm4;J)!t^2!LOHa_xfo&upd0tkaQ>A^bYDeqE{_ZBB*Vkf
z{6ecwH&+jY<{{Z{|CL+dt^X~z7&m~6Cv{S{`>qTmamlw+pISyv9>}<LDubWLT+w(J
zEG#Dbop~GMy79^6`*ZVUIn1z<JkX{j9D`XE0k~yTXWB8CX|l|CJHqc(Dhq)`7H*y1
z!59Mjv%Zlmsv0mHApCu|T#6QV!$fdI+uA%KUU~uNhD=9II}6Yj%6MJ#N-#WYZ8gSh
zun3$tbxtKSXYB&u6kZn!80LnO?~lb0&o_!U;O$`bS*=|q0V+9Ewd?5lk2T-+McV?#
zm<MMLy$fqV>MaPx6CV!wN??b+rgSiic?EpTUATl@b|F8Pqw{^y-!Z8xDu#XiqVDIr
z5bW*3rB7#X7P<P5Qxlb+H-AlIUGJYtNlCHRnoXL2HN91Fbv(Nx(;<zuKvYR_F>*AW
zm<po_{vZli_t5}dnFSu>{8GC=IRGxTh2><{!)fCQv{kv?h#ao5G<?O&V5<nr8#ITW
zU#}E>*6whOL6#|5YPTuRvRA<xcH@r4WwTAzn?(qVMDfinmA3Asl_>`PN1j^_TbGC9
zEj)ixu_xERbI&%UMKZnru=zFMInu$w0i-stN>iA+W<uH3L|TphX@LU?je;W#!1JY8
zHCp76kZ#7<10K;pRrlVVHxpawHf`C{mC!$2@DmBxhSFX&?*KCPgM|2z<u`{{16Bw7
zMz_VKgwxj2F${j*H*I`R)+qr7|NQwl)MqU<o;0b8x1ar*tgCzv<<Ar?1U+5}e)px2
zR=R0y*Z|f?j<}<&-mk-$FzAgH3`{;rIKAC28n(TJ)&Kr7x7vd7;=WUMv<9?^iaqYS
z-c?sV@nFmBR{6>9>c<ms``GI_S$h6&yn@RE>IdJ;nEvScKAz~rr-m+De>pf4DmQI(
zCa&e^{Mn2YGE)|8XpCAHE_A}Y>Xs@UaqGx3S~=i$<912J-s4T%8}%>hQdZVj6Zj?3
z{-qRimWhj{q7C;jUP-q3_k??E1i5#<v$V^5JV1D$9zgBP{<3yYW)_%5k#T1zjFGS9
z?|HHh&vbGcN<dj9Hf1UcNq9imzVL+=6LZ1*XkePEYmK`F*J<CroaL019b(7QF=s9{
zl6P*;<u9Mu=^NuXz3SJ*7pOmx;Hh!_6mc@aGqCO3wi6ls0Y-2xTq1hjkQ{92Lu;#y
z==K7C$)s{qCPHB~@<5gfbPj^Id@^G+Zp!)qf-=I_<5twKu&!w^>wvh0rE-?Gt0}IO
z|4^cC)geift{887yj@C^1l?h%A>0*_)N2`wT}}TXW4o4jetR{v<EFZV?XpMz;%1#q
z7E%B7q7L2|a}w>89N*Vimq@u=XV*Td`$(mVKd;R(FE4<qYC0=hdfp4WF3~R43>0(W
z?ycL6T^`5@u4Y)PfBLWq=tL9gW3tTe7{-4ootPX#Ji4IN@s>MHwL)%X8GDHIgW^Uq
zKyq!aV);&eLAnLh#+wbVZf>N<^N~7#-|5{<`OmXF^95KR)}Kq&{R;+TxR)mEMH$$k
zq@`8j8f}vQ%t3nB#&Wgn%|dF5eDnKL+vw76Q!)qg&d$Bkv;p~h!BDD9XJX{UbF)DZ
z6)$TXg69s_(xou!vj1M97_X@R{b>&PWibX?t_x9UCOpF9C|Y;H3U?^1i>2i@?MA<r
z7x-mD7{wrTkG6CPq8Q}(|Gqq|d(msOaTB6NhVaXKga03HMXSSU5<nFWPk$H(4^3EE
zS%I1kL=&`=2x@D$6a+ZOtYd|Zagxf!u|uV-s&t_bX`jR4a1f<KJ|eH6@V4AvF`C)u
z_}l%W&5w8-d>-^i@CG;NLkDz2q5`lJEorgpr(JZXxfV`TIb*CUHq!)mV&esaY#(%1
zE)g8X3=AUdoj}L~tnQC=c!B0vp7TETZ`(zilY;u_4|zi0TaaJ+8WiS(jYYJHCsYc#
z|Km-e)^<3HMv02iqR<L&|8M^B1$rE+eXoA~&}GEKxyG7THnILWGoRYZ=kC*3TSj`O
Kx`o;oL;eda&5;WL

literal 16836
zcmd_ScT`ht_bnPLq9WCTNRuWaB2pq<rGtQg^rloH5Nar)S!sd@NN-A$5`xr730M%N
zg&t}Er6&|Ap_lVS-{$*$=Zy2m9rupkxc;NWoxPv^l(puXb1p(}Ybw(mJ$n=afzYU`
zDCj^S2V^0TeK(Kn2cOj8)6YR5H=d~~+_>XyK1ZPS(CfiYZ^hD4tEzA}QXk<h-}h*$
zTkU+H!vQ9y<*Ze<b0LooMbfyC-u2+!G|4LDB@ZS9)9ry;;coplv5Z6Gs<aaq4yGLu
z-KH`*tMEhbXf%~*7!4Pl3Pg2&i$~;=?c@N=hOgf@s(d@3;T$upHPClqwlaW(*)!Q=
z0pr<sFYzS!YZ|RW0DtWtb0gvpLLd*|q1`kP2*;IQpFaMd{lf#gCQa4y2P!3{rL7bD
zIc}>E9?(ULtn8(Uq~CNsWyDfmUXDN@$Yk<VTY8=MVn!tr;^CYHzkVdDN_!{_6_KBx
zPb3nPlFq7*a{G!H&_0-t=%zWssRIo&i7GF49;tmyMaw4Td8-7oxruZqL#Br*PdJar
ze0S1_#RLN{M4?{J7FJbNq0u-~8AugW2g>n8g>V6`h*$FQskC<9TAeEZ4=F4Z``67E
zCzGAg;0|l^1n>w{UY_u87jPmDJbM1;Q2r<U5M<w#lPc}gi9*~UD!B@PIc|@t+V_FO
zZm6cFhK5BvfhOt&nDe7~EOZ{=Kd%@HGB7f-`;12g1syJ}6r{}fpRaj1wu)aq_ynQa
ztEgX|@m2R+Y4DWhmhnAJhXK7%nG#){U<>!c{9flG&2oL2^)6=UiG>j<GbNhoRL;S@
zk;jpP?!+Bm9-bX5Pn?LAv)tZvDXUZYj0Uy-O|?$F${B+|-_aM)T_1-rD>;l1l<xC+
z#DV>kxegM~dt$@G$0xV9y&Mq{VOw`f-$e&g9W=zzyIMEDJKUcxjh(Y#d+GOe`W3v$
z+<p9mgukxup1j(?0Dr0G4ykRt$Z<`b<Yec(`GUy4(>7xv5KRbV70$^lR4Pu^+#77$
z6&?GQ2z~xSbbfE$;l>V^mXws&pe2~6eaghc2Ol@F93T4<S(KlDwfgWyM73mPyy@VW
zoZrX(tgxzVq{d8duzG7VBk!PCU7|~Tcgs6h?|M!?wp}@!wWP8Y%`)QW{*`u(&pOL;
z&%XTo#wnXCGo>CgI(Bwb64kzOMdqpez2Z_ldJH9dh%bcn-TUZ{8-!a}rOr!v5}WN4
z1}Zit4u@B8A=k#i<Qva7CVCZ^r)X^LZE0mG!5@{nV+2oum2}C1zuSLNK;Vr=viRNi
z5X5B#gM%`NLBEl`Gx!DLtx4`R72~Um=Ge#iy|8Eo#_Y+V%(gzU5<xKoo>i9<ivg<L
zg*~I^a+|=+3W~}2mYKsj!X^@{PBJk~L(j3E7uGnRTo2u`I9h)$k7c{Uwl%4xrRC7E
zQ|BZ-zB)dZTE5hA{-97ozT3*{FM<ABW=2?@iKM9<i$Z9gNq+A;84|wEE7=bB(p*)w
z*KR_3r|>Jgf(xui2zMEmL%X+CXCzGuQs>T5wT@Zm)y6p<ung{|sg?9uvL31RAMsx^
zE8RC&`O>lMXzLfIm8Ct|A0ej8vW@)6>?$m>b*)ymh4|H%5Z*bXZ`VZ&uj>Dfh2K~I
zo~%$gU3Z;j`hpI0o%r;$`Ma(8>Q-Zg8xu5Y3AN|OC-?c(?M(U7?u{0^N6Ic&tL~le
z^&`ri=#k1zM)mqFJ(k#e5uGD@54kyFEO&1JTJF{JSPsGRUFP1)LeCh}=`?1!G%=4S
zvrE*v*HmA|7~0|Y3*RIjw$Mnqrme|hE12<WDd>kk&qDo&J<+#X`U`0?MQXEA@vh{@
zQ2*ue**7aE=-v4nhili!_j<Fk`FMDnMmmdV<(5XzEpW0rh)q)tNl{i7tV@L3-eh|u
z=LZ(<6214fUb6I52t9Zuhtc;B12>v2T8tGwd=Gwmq4+`;T=vBUzG58ekmVCFeQH`-
za{ilTM$az%SYCdaz@!6ZSNX>{d3brNu%&Fm3cq5+Z(oh>3Nm_nje`<fb)bQCBs#e)
z_>Ys{TG+GTOqiR*Nm@(R@01lfpR)0|JL0>(3Ss*ON`CuA)dzzoB7whxOR`)DB7_|b
zG|Xj^_E$_<rYb(MC=cd{9=H8RXxin#a|WmoMg=}5%29&#)9zOGddYg)JQhF2Ys*x5
zET0QsRBb#q3|{9%JT5w7xBLIqpjg8Y`o~IF85Z<;l4My=7D$XqwzUQBy64r*RSeE1
zEslLrZ+&#=Sef}f$_q-+O4mPD1T)KjDlb_`l8JPlmq+~XuR`0N9y^W3t{UeJ)%sVP
zRXPod=S3mydp3hWQ1&|+bKuNe37Cz`ARaC&23w|z@XzF;+eVqdQ=x4G<*@9@oMd>X
zfTFf`RCn`vC{Z3@huW~lec_%)V1?pA7~A;BOnS~HV{B}kl$@NLl9H014mQI|SlH2?
ztmx>^&rZ{_h+h&DL$trT;asyAB-5T)axG6*Kp%BR%G1%-)>dC1Umway%PMK@Wmx5r
zN92l^wf_2|(tRpT%1e`du)Y0?@9HeLZGF8$b*F6`qjoj4RYL0)x=o%|hI?>%stxl-
zFH4D--IGg81NK0Z>^PkP2veW44YT02E)7+#V-2bkO|b%PX);@jU)bYgV<XN<=!oTc
zWW9U09-}3jm!E%D23a->?|Xa087r;Lov(H8-nTRvU(HlWG3R0F{#f-gsg^{MHz1{<
z(ddc_&u<@}c5beZMUt%2edi^Zw?3b?=#$T=H2pl5BUahM7(){ATX!j#E65H*w%#$0
z*lgzj8!CnB%J&Zx48ioQyY)2AFg`AhH}>SolOX3P#i*%OzzO-DHu9d%Sh7Br?6#nC
zC!JNwGuNzf7!}7?Hn8e|`1bLTJ?k}>R|9%hBY}H671)fbpHEa2)_PN<l`iX_H3{Ys
znY}(++Lk3NBGUE8d~89KP}X*K1y`ufj9*eGP9A8cCpCmKXU;$B?(WXW$mlP%V+UYI
zEN`>xjaGqKtaqa}3X|^y&5ztk%FMdGc|q02wk077tnJH}S;VJE&Q3Pp-EE(8SeM<8
zN!PBV^R0{pq^?Zm$Pk%qC8CX6rmQICl#RWY-|oia_4V}T1~FP}AL8TV>!?l7lWyog
zMbQ{>mT0zQKQ?q}klb)?OOX%}64J`%xOtVWC(CoLTSFYBnGJ`FG4kGeYiu5MN9(qj
zsOWSdu6UTN$p$Ut@02dCl9eVY5f95LNOREB0<hQ9(?bDN0GKVWNRBcX(Ux4acKUiW
z3SoJfwf>PZD#pX7zr;qrS>#o|5)Y4A;D_!)UKtrer_Lvk#Ad*))o$LrS&yW}CF7aw
z(+thn$*MZT;0ZzNVcyrzvk^%on1jP}Rw-V)X@7w34quKUa}?af2chVU_$E7VT)Jju
z=IXk*G|^1UF6%cxR4E3-s{}_!Gk_xy+mWfvF5y<coA7ayOd{i(85O_JX7&zw4my=!
z?{{Q~*x_b}DobCzy6%j4u6OwO84mK++5(j2oHX26H_OKo;m_thy03YMF^5)m{gpQR
zSr8!g>JKn1y6kRmR8>hzKn)BGnj1$sTtZP)Mkh<et)E^S;d_z*wmxO%lf~z%NN9CU
zO<Z$xvKTCG=vclgk3bQK2>0&YQ&Uq52-yAp`Ptk<cwRWJU%5ykV0*ngPq(zBWIW?p
zSXkU8qYRAXmy0$wHanYScUX_lP+5-3ay@YqWsWtjunDSQHA#;!srD@V=fD=fD@q9T
z_VyM;j`Tv}zan4gal+*FLr{$FGaRQv5V9{04b=q(ZWuTZR<xqWdzl`b;Y!)Jew72i
zA-@wev%WYscb3eOgEP?nM9D7afBhe4K$Rk~!l5U>*y_vV`1s0nN2b@pu#b-qbi}We
zkZ<0n53r@k)vHS3XE>?LcTIC0%DrfY3(e^36036=4O%4Xjk*xR>2#2)*Jm0erI-q6
z_}m{Hi^Q>MR5Zu;#`V)KdQIqJEcP~g-A49i?c}z$m)l50A^<v++;{5KsR7oN&mDbz
z-s?ZUHOBC%x6%f#e+uzWsWGWOA0XnT&4*5K4=K$dS;}%kJmiJL5y%VkYKE(4NF7h$
z(@k&Sps0vDIks5-0>`6gX697BQz2u=9%!1^>}0@)HslNPctm@8AH=})xK%1!N;N~S
zOaoH%HA~e}o{57)J}M!Ukq>QFUBTO_RdOx<r5eHdmD$*ArigLRd^C?b{N1;p@$qpM
z=NeZsu}4d8XXU}Z1J*cUs|LUIZ^24azoPIhV=9`nD-A5pX9`#6CtH)%)zmt>x+qf?
zah9iRKtqGIW{9_~zx&Rw;Ec+8Yh+}!L@Vtv{bJamR9Voh>Q2wsY+B~4)?kOP7Uh(&
z(n~0zOfZ`0EYqHsFJFR<-i#(>A*;;TQ^6!W(W^IH`#{A$<hy|FHFb|T`0d-L;Jw|o
zI!y9FL>q37x2@}m_YS#tB8BIM3C_aplt=^dj&8jOA%va_6*qz{mnt$YS91tD!RpXE
z{a1z&fO5;p1p;6TVy9=p7oRNt9J@xB>ZQCvkv8efdBKSRSP^!ic1s*Sbl>YX*`d0)
zco9VT#H%)8-M2tQw`Awb)SJ^x5}jFYle4Jxs~i9Y%+ko-t`}LX{qyI~N_Kfs&E<9c
zuAhQvkOc#Aq?DI0xhtDL#HAmq+1uSJjN|%{aIvYGoTd>Wc<Itmsa;#1?i(<feAQzO
z5v9QeCsxr{?QkheOKxO6`eUarml+2H*TWGfI$+}v^;@^@>;-cvKmQsuJD{9OoN@Jc
z#K8_hzKw+=sy*kT{dk0goWVJJqm{nfmA=buA3-3}r;~4^oPE=IhXFVxb@px_MJ&0Q
z3n+>yN_WM^#x}09dJWz4(tk4wAhIc2QPfwVLIDG`G{~7>*aI(pQht6eFR7-DOG8*j
zJ!mjii%<`eIwi@FrAk1|`zTOUlVLokmU<4t?!OWx^EkiEi$<wnK*nYCfn)PPr<aiF
zJB~pa-&Ijb<>f8zk_Xnl3&U84wJt5WSTmm=AX?+J&CzR)4znOQcB3~xNcn_kc+P=I
zh^eZ7cz|j^49AI#kc^(&`xGZ=a_I~04<A$ZWLJ6!of^*YO~B3TfjO-af4w5Sa^jTw
z)<+S<QpuOIl&xUq@9(d#AD8kfl3i}Ndr8*-izG+CB!Q#9dAy>mOqAI~TN@n7`=UPS
z%1M^UxZ@ajR29FQT%*k9c#PKSJi%oC!Hvg<^N@(Ceu6bQcYG5kwNNGyA$u6?fdTg0
zdey52Val_Pd))(I6)(kG9MUh^K5JcBpkM9&GM*%pJW!sl8PBEA)AuQYkQ0|amMUze
z1c#%gZ)q3mH}ioPrM%vFQ{31dM=VkcAcALx)DTXvoEP(z{VZO1`Qbn1)z0}Rz3^*x
zJLuHxTFBHh?wRAe(xF_au2qWNBo>qi+ULsPIr0*cG|=YYZD#vRBUz<#{#r8=s2ag>
zp=SAcwv1ioJT3MU2n1P5SEZ{P`jzd<JS}_89f%v;k=+{4ua}dUTx~IC3;p3Z+*!L|
zYDQi|!M69!fm)s{XU`6>X7rv3PT7>pGDlXwUNg)bM(uyl?%E)EvPUaT+P)iFemb2{
zfz@JEBIZ1*kiox78p3%5?vN}P85k(xB}d)D+eBaA(>@mfCWpzEL=br$G}V30TeqY;
z$FI41FCa&@T}aRKlB=YS9X;BOc6Amjm%bjARO`P5c7d#9W;tUueY%pkWP#lq1C-%w
z&(!m{*$Obn9sNdJ!HFH5lzjX=5#-}?DTRf*(jA4nv<=5{90m&;(9i-1het}WCXY;k
ze&JPO^1!n;_~7sxYI0gBy6$fNkn0y#{pJE}XlQ8k!&FH`6WmSL#H3*ORa{(Ljss=)
zKW7YHL$9^cVg%Bw%mR1Fkus}&AS`)Jw{!aBaz;v|A&LBzaskW9Be^FUuw+c#jt2Jb
z=KBM*eX&aHk2?lJ&B&TsTdm2Y-Xbs0;Sw8lfF_rhm%V2DT)|WvpgK{rz0}O56n-Tq
z%&pf~JhQaa_Wgr>CDnm@0o6*_R?ChI#jAt3R4E=2xL3&V4J`J~p4>ILoV&E)hE~1F
zdJsBEoFU(b8iOM9UNbL35Dg0;sCKuf<VM`vWbzxOWUHM(1mKo6Vckx6G?=Jav$Hy=
z-@NRyv^MO!&=Zst_Uu`_kVOE<Ozu;-LZecp&G?rub9on*Rbs~KzhO!K%b(^z3X0*=
zx_s$UOJie{g8BUCmX=$MD<epfVD;lFjAO})jgj19J)@fev;V9a<&_D&=Dr#rw96au
z;AkTTs;j*g(nRf}FTstpKrXv1C`c%W#hchI5J1jINsUM<DJcoq*_?^}63Lz}iEz-@
z*LQPs13MbzrvX+=kK61-O?zR7?%Z-%?|_C<TZot^*60xAHKQ<IPhVd%@oF|;-WY;|
zX;^Fntv^s+8S0b9n`E4^`TpSn9?Rwpb)02`VXA|hR9EP;(?V+5#8q&Zr!|6pp&X5?
zcPa(Jo-DO(%?BvmL<R>|-DC<o*gf1zTMU*R;f^bRgdR<&9&P6EE1vJSOOIuVjfu(J
zJIaGTqJ!~#QT6%M-Ytm5Va{g=5Wp)*=<0DL>`JG)EsLKr5r0Al)A#-7mv0qoVow$Y
z?(GWIu4nWI2|VmBT;6UWe)lk1Ou+kUM)E?AL}=Da+Wqjr*Xv79Mt(`T@}dfnmVQiB
zGyY_xJ$7p4J~(;P3Mlu(T6P+apRIPiTc{7@nM^&s`><h**Sl?|;~?a9N2uY{@ibgg
zU)Y!J#RSH~I#40yNH#%1!PeGR4S?p_+5qH7Dk?s8&?)G$rPWUN)6~$=P*r6HwahXL
z?39qXv}50unJf3(UqOexGvy06SHn&UG(2ZbPE1UUjTLkKUJvND{?x#&!I37HM1`Da
zYI1Rq=NsdnHQ3%mPWhmgRH@$Gasj=OKWnga<Yd8oP=o!7a$w=geIH$U^k!i7NJlc%
z`7%Ghs+LyU*RN;99J+};1#`S&_#+)bo>P$<{1D+A#7RYe7V^Ifu}(PRvIg1zG042>
zeoKu}T*}s;Hn8RSJ-fJ1fIw6j$#*_|>ePIH=@dYv%ag4!W|jH*dO>~5A<53QM(nU3
zX=?wj&GehK%BTNXnn_<qH}a(HyZ-f>Rq7gb2EWdaJ7RE7B*@pQs;bclR%!3IIXO!H
zM%W#HM+cOM0;y)oIqcJ~G4lutYQ)`DR8+LG%IrU7|L|<xQn5|*spdtPHoQ)hL8G7+
zYxU(sc|icQWw+6Q`Fyoohl2sSMizhfR(8PgzO*Kn|ESx}Z<~0qX+Y@C;tZ$!AKedQ
zlGckb35m<n@C3AQfhPcOy8WzItwUt-%o&K`Wfn`fqt|b}sPc(=tXBB(pEX+xn7i9!
z7(~xKj#vi+GSoQ2qGS!;gPF4{<SFbniAX=EzuZ@Ncp*=AYqpeG#CCjgvgv@7p3tlv
zp=W+$d8!Akk^Z4ElNxgK6Emqsi%uiz(VKkNV;#h`UK$zXO8XZ{`7%wiYqA{M8%X`Z
zyySSmX(x)<O-@Yo7vQ((qg}1@r#_8O>s060br9pK6de(8DVStbRb|hugexB$e309q
zAT0qE{3}pGAbSOVe`zf24w08SZurCGInp>Ni0a3f9wcxeo~b!G&6U_RTTA3*XZOca
zQ&TtW7fYix5JEQ09MUbHLum^o3}`)2UVfBkqJczKWgklVql61v9?4jy94$~)E-)(S
zW{u7qFGaQrVumcs{k~pbxa<BL;kMcV`|kQ{KKU<SHm~*D0HCxjRSIL<de-PU4-bzg
z2|(v8+r8Z#&j{q{{B!95L20v#xdhz0;T%gKlX{g$h(n(E+(`a#7N{m~=#te@xEPV8
z?6jb<2S^2}QeLM3kqIhF%5a`tI|#Yi@Ym#uv=GHiDja7($sG_-E3F@Y!5>g-@fHC-
z^&#}QG<b^tN|JZVemcf1xOs*1h^*5<8HhrcB_t#OF2tjZK$YtW1DL!nU?+T{Kz1v&
z)3Q5P8`g_1PrlOzqIKchx3`Tayi4VdGT9WkOIb#2y3tWiHdlY=@Xp;IX+%(3>Auly
zZEA{6wzzYr%({^Q+asYLy6#-8h&uS-Md%rlwC2xkAoAj@*spl6<LOy3?($c_H>gje
zm)M#XTfBCNgBOr-W7wBi6REk!w6ZVki|TffrQeQ*esMbZU_R(4k+vM^<u*we;2hb&
zc>#*U*uY?|Lzz7fDnG3?YGzbi6#;2arT<C#?JjEKYD}c8LH&}c6rrY}(Fy_y6g~t3
zMk||vCJN34@elwJOYh#0YEsMa_0tpz5b!(?t|Z9?)+Uyio!78+eszpOJv{5Cxqe1Z
zPY>{pNk%5kUVUmY{Vdb_DdZ4f{poaw*w2UaM7Q>tQTQ`JV?k~bV-3uO8KKS5YNhP$
zVxYi|RU{tf$kI%cPE1KbO*xea#M;Wef>Ca+1BGyk1G-oS5o1<L)ow$n#&6ts2r}8d
z#p;nAO)Y|T@9aJg<~*Rr6?e3^zer5XTN3Yo@yEpwNPWv%-JXAJRbx>9;rjiQ%Y;i^
z$CQ5ipsTMhq4%bEi#W$AieeX%Eg{%q%%Sw_-`KzY4cY&Ht>hK<^cYwa22>q9@^E(6
z(LMBlHV4D`TOZF-s}hVG{kN4lE?LX;;_-N}#d>?w<pL?Bz+@QJdCtGCqJK-rTarf6
zwF(LV8N%(T+H%!EnvOb(?j8ePMTLkDd+_v16uIVa{me2>`n%|Vy97bPH#Mn+8ZCwB
zvcZ!C*g~GDgj}J9adRVJitleGd_`Us5{ggYiM$4$<^Y4Wo}^W{$*qv^M2sQ2s{H(2
z&Rf<pbsLk(Bz)l@))yl^^ixRt_fV)|?{C)7Q`7U_i+GX+FFay+B<AhmOZ6;&jrXGA
zKG>J%tbkP+HK<*RO%nuqV%=(aQGa3FG5_^Xv~tpbhcw3`fjHD0G^=J)&zvQH<HiR@
zE$PMGt%X6>l$zk_LUHWOeDy-DbZ@qrzm%}BHrfe94(G~=IEx*k!EmaKt!|qCYQMAJ
z7z;BqNX;uMT3YdY<L_L@R!-codn$UDb2ywUJDFt3%><xj9WlQkOJ}#KVmOOdRZXpG
zG6|M*E3w39+19Q=GyTIWFD{kMPe<)3^JIe>fTPRG?x5eETOF)$5)cxiEL!_(`Bu%S
z=M8cd2dnRW3To_FpU#Zjef?Q0V2M#;GP@Huyz-DzOPqUOvejo5X_of+gRe?GEF(AP
z$&)7~C08>$`-TBt2jRDNXU@5Ke!MY8M$)&1m+EcOx7w}w7!tqx?o{CJl&+Rcw(>UJ
z+nZ<K(mAh2F&r@qebN*exNT(*4sL8+Ng=d9le^j&)U>Hy!~E3@GApu3jOUCDb@VRy
z4rR~v7l_jVI*iZ28>C@dd6UhK`@Vpx$X)_x2yM<E$(yZ{)QuMYQHU9iCTwr}RW~&L
zG16hIFYUQ&E>pNvWVX8r1@3gKTyXWgJ;+wNv+_nRb`I1%xrDbRKgZTkjBiEoFzgod
z@HIC#$8b-cu3LY)9qY7He#ojDz-((M7uP4W_7JbvRU`wq|J|pelr44@?+<+wVCMoT
z>yfSDHSX!Ywr?yenH~DKZ*#;heZ5s=3P94G6U<i?=FT3N(2k#7CH6F<U6<Gx7LzXI
z&rn$AI$D{P7v?iV`sV&*y}XUh-n#kOR~0h0TW<n4`T7F@?a>1_G~%Q&41sQ`P(MK{
z++6Hb7gF7U)-KZY>$g2rjUYILBNwo1sDvE&K~;7`&Y!z@R*&TfpuF2!TJBIKPXkmm
zhZ)%g8}KXv439T8yCfsyX3_R1_T9VXH9I%K=&Z=7<QvY>RMk(PK6NAL7aH5N<Twi~
zaSXaq`#20*iC0FHVC}nj%V8Lz|IPPD?ZKHjM7l7o#?6EwcqVs)^8a?lM3EyXC;AFk
zFYFxZ@|~~zGJn?t7T*!WF>^p5E9ymeq28$eI4Eu=_I(Fr#OvW~&RTMzGqeABHhZ=_
zlln0~5Yt)xi;~?#h8^A}>!S=^d-M$Ql;0x*rwqwWifU?MrH`?5;>klw{lgVbpyr<W
zYbf&<raib{9v9;0&jWFV!jYJ52n_02*#$Vfgo6qTWK(;QXU*gE|J+-L;EDs*il8#W
z>NiU{MdXAi8?Oi@TwFTh_+#_~>&}xrVTB$HYloUMa`YjUweN6^57<ewf!kjKRa$AF
zL!+~=oRw2Flo~5`cTE)+829U|960q|@SXAvWv*|L0V`a3&MvhRUVsKxkGr%n&|7O;
zUW4niJr&=`RU-89yvpY1Uq|%hyOVjkZ4qlTU0-q|y|WPCt&Vp5VEf*Y4^<7>CK}W^
z)b0O1`-<uGY4uh>P|f`L)YV+=%<x-x{(5e^@{N_K+b8w_ttHOM`3)?1g#gfL-Q3;v
zT&^fJc6flvY`h?mGutF5S>^L%eg-^1@i+`ud{FhzfuK$r-M;-}jD630rZbx%zrwM9
z37q~$a=N%vQitI8DBdqb4Je@-aQK0HYk>w9Czif)MSA;5sJyHR_AWcCv2<5E<Bhq!
zbF)}{vftJm#$?Wao&a~l@y^$7!TWb6p>-Qg0!3c~wQ|gAyo)>drcp0Iq&0c_{E?>e
z$J6HCAF5XN9ZE&gF9W4y+bT;NGmI=i%wS!`?V!+M85!dUUOU5540ZJ3Kep3b{c(WW
zqSMpU)6&ua{YHDxW{XO0{o#(VbMhb<?KcpdFKKJ}M`k-JY^#|&DQwjQ=juNm&hm;2
z8Jp$!z#}113F<QjnZcb3Rcud!Mieup@QID(;dca-H>jRKpp00^JuWJcweQ%X?Kyse
z=^L(Z03Bsdg1WFrV6SgUrc6huFfd%y0hI1KR(^<-(qxu}wEUh|(3w=~Xl)Q)C}E7b
z;M9?_-_r^u4gN>&(bj1zU}@2O*ZFg1Sc2Vq6Bmo0_EXpX5e{ANbAn_Hf~msIC#r^A
zoOvb!`%iu3MuE{O{g(OupSh?BhpTw-Rz+R?n9V<vWPHz`f{ioCtrHUy&iilh!VL9G
zP<BQ=B^9j`C*Dy|!%b%J>X!?^A2d3yzNVx^XMP58{YB&1xY$c1BmHuelY8ZX%OOvW
z#N1Z8se@_$TRmATww|tj$PpuUNx%qSigGX-oOGiyr2|R&bvQ`U@u_lw<~nYbUOZ6X
zhmbsSFcEdnsIer?Mz485JYH(_5d|jLfb>^A3*d=cotpk-FBc~#CmK5Ik{}zNW@Mb6
zAZ*Zd{=u>HoFBPgg3$Db>1i~b0-7KYIxzqO?KF>-o`OIWfayop-qEoI#>rv}P*}(b
zAc&R#Bt|CVOYT+dgFKi95R(ru!)tm(-oGx{ZvTbpbf7;m9rzx=aN9p9&~L&iY&J;-
z0=dovfMPJv2uOL!ln*!*jvhVQa*=}H=)Cx}(r#&L;&q|@u>fpBo;*D$S$dQrv)2<S
zT<nxn*qx*u2*;&M;1ilWmhba%Ch$L@DY#mZ81#-4A@BDGybVpZQOy=j#O~u@`tu7g
zAPd>zJwyNX>2&*R+opeg3WV<iKWwi5)YHpfr_o%62`$3)GG@B8i<3k^?HI7ToZkF|
zk_gO10=B*LjNaaTh%bofGv5c9PCMUFrB|RI!73%r$M*(M6IkChATd<~TsEhFG9$LW
zzCJuWoSsXmC0%as<I`hG?7qFDgn^Tb$(7F}T|cMDr-%{G<(aSyucdnxFleMd59>)O
zPEwA#?>1N7+w^1*<BSo&I1TcO=@flAYj(T{0`V}x8Lp8m_KYtEu9l|z?`}*1;SW&Y
zb=wm{$BrGFJAn*=J331Ht-sy8y3D@&Bba{cnh(ZPaocu2L(^1viq1|03Wyw~-i5kf
z3b&P5WQpgTapD}1xUUj{+LaYRs6r@V89oU>AcQy(JPn();YAn>7J*C_Q2;8NiD2E9
zWAC-C^)WRwcr|znN#U&OjjK8E{~a^4HVyVEV6@_rk|ci-F`wAZwC)scq6~{IXZwoX
zYJji?Y#fUq9(e|5tH<Zdy3NQ39Z!_<ng<H_N-+%$4Nw?xjg6|eZj}i*txD6E`*x))
zt2`I8Z8=j}%+Jpcf;L|Fa!=P>-D0~utx=RLPrj_q#X==)hJ`5PNvsH7l_^$Dg6r$p
zFfhDjmh*S=D`ms4wxeBFJD3X{yc(l<phGT?Q<&g2iw!*m27rC&I&k>-3kja3K#Fu^
zhk4-KQsc8c866$Hva$k}R6A3tvCLCfmr4lJ=q@f6JIJqBJ}|32muBaL%$BJkbY%>Z
z7hB_n5iC%6$~MUWZR)c++aD>n`woS29RC`XuSyX3#rCM`>BSD&l>nrA7)xGKh{}}(
zAO#2)5(r{9c%-$#<&OC)Ked!4pmX}nmb-krY45+i_=Q~DCbO0jzVrQ=&@5+%Df;_Q
z8JbH#hd}}18+lIRJWB~oNVjKXu1@$jB_7Gs#Ihgqa55axCcPYfG{31F6wSc&<23ZH
zWBwJf#}kk|2Z#A}b5vRZ+r+i%dKJiPS*kIzz#BHv9A7{HXL@gEA<&}2F|mhXI06UX
zXHlN-REeYTNY&@0y>Gj<Z!Oe~I5cjA=VjEGF7$UBM(XAh?=D<qo9fR|kzYx=ulbCv
z_Y1p4LpPxEG<JJ|isj~bMuTYHUxg?bh^6VrlJO=$B*t=S`+Lszz4n|ymm4$eRbY+H
z-nrZ`raEyh*R!W@Z6vVHsVMid!Qwl6ji^a&syF_=7{~te)l2u~=kj;qdl9n!n_uUF
zRM3r{D{Yf49gzK0^lT{za{ZNJI06s`v2+8O%CslV6mQ;qv{UfFGy5_R&qQXVY>D0N
z*j4n0`+C*jNiUpyq>C2vOSJ&m{pY)?mi|KlA^?&w*X$3e<SZ;*2iOpt%4M?iDf*9V
znp2plLQ&{s*|aNIG@Dz5aoO8@JO3oGfaw5PDbkHrs{y4KS-*TviCmnX9LuD}&ST#i
z&MX2j&cuzNe2lTIYF4C7;BF0oh9cg}Ki@g()m;gA(VcuV$}+#sh+G~}i|B5q5hb1+
zI|{je!KYrb(Ux1pd#RDncWqvfaG2(77BPa(e|z1P%+w945_^NQ{>OpRRW2u*<2m<=
zwYb#eeXmr3K>&@L((OXesS84Y$1f*&s+CLiRcp+p+9jW->40TO2qI0{1O1qFF@KR^
zd3*0BRC4FGZt--}_o7+s*s-=BpHKs@0fyL^4~&k0V!>ArHv)5rV$v7GOycUmLc#4F
z!Y+$6=`aMI5sLUj-5ERH!EiVGpVE%tC@EF1gy*&SoTOq(ztb;ap`ri7mh>Q#eTX?@
ztG%{Ub<g@}b3#==sFQn0^Y-@k`AP(;4r!}dpbr%RJ{D6ZRtx|>h38RKQ3)|z_~1kF
zY*<N)py19gfssxtddVCLaS7wa=aszzE`+)K7X@CoBcA|#3j?ukIvlS#TXo0}yZn<#
ztI@OgZ7@FO%d&0aif1#tLMF>{D+msLKfp@=haRyz1E@7{@~Pa~Sb-NJAbs-x;DykA
zZb%s}^Od^~x)(<3MjTy!{MzOVU%H)(mUj}s{-$E{e($#TWCjpV_qzq?ojD*+!bR}E
zOFOTFf`S<NG^NSix}9?Xqec*4-9!`ioCCL#kst0nDm1fS5k6Cx+J`u{j+_!SsaToq
z7XjKb-~`+*OSz1`Zx*VPwyZy5m4CqtYbPQp1xuL{TUd6i=R^jBW4!u4L`-%a1b>jK
z0FWL)^qR#3n^Jr{6oy9;i4Hwk^N)XVa#whG6i>x0>x!(x6>zf1R^Z@zqnVln;OJ?y
zzgakb0Rcb(q?;7re%gpKWe@$6-qXVDH2_XMTMz!!EHl?`Y{kc8ZulVN$UZw%vb0Z0
zeP>F_IqEmjG}gAZ!$?vgP<Z1AH=dfB6q#eW=e)m%@^K#$-t4PBOi|(B`$nc~z^PD;
z;kB`|Q^$*W{}}D;>@=(PtVFC1J1wQO_V?$yruEjemC^^FVI7bW9H^#;{ajc&o`sV>
z0ATFyY^eu34OaBWZYS-Bh#tCv_o4Fh00v-}p7|(Lz$cIG^+nH!O&Z;)f?V+h>U|vN
z_MavV(5z3(0%&xRP1&u5@8ARY1()K>Z2Q<<ZxZp$4xv(sJKsOmbgQr6E4VTygz=eq
z@|IVrAs+6m5eVV%;s$A4QbNd=vc&|Emnwvh*DdDFj5gV<WRfJgd1D~gp}if3r$3#6
zwTz)cL%naYL`ukqb_*U~nHY}EUigoj2`9cWTYUG*yM<XT3r=XJV)t_awYIr?t5{=W
z<ELO+N|bkoQXCJ0F#EGtt-lUcy3dV#Z;!7oUV%Cfo9gI9gVH1_ilS$MtU0Lho!o1|
zE_(mAg9GvHy-z@WaSZRt<DKD>$*v1WjzvK4bOBdG)=VpOr0gHIhQ6Umss~qG8>&DS
z2U_Li<fPj1wtpx)`|!53_Rv|VsAx-?j1(WA@=kl#1i$gL40-OPfPOf@ULqnQ0s^q_
z^`XHhSak}&1L4vsSo0{G?&t9)uJbw=xOFeu44?!cjDgKX@#UrOuJB1z%;6>6Ctt?L
z_X55TkH2jCuH9kdHEmCpkcYqTFI~jV^iN%+I&())1~@9vh?!$&o^I|}!W>W%J9+wa
zAc(E27%||Rd!08S<z~J0Tx$NUlvd(ZMTb+D3|)M-dEm<jt|wfxA^^H8%MEz&?Ap?H
zfNze+?fE&0PI$zbfI*rqkjaOD*{*i|`!U}TcQ&k&6VQ8_aw#-*GE~cRA}mjzdIq0;
zO$c7QVLRn0zL1w>=`lf1pJxKis6Ai|`~$7P;g~fAM8Y0)?GV{Xb>JTv%FJga)3c{7
zvTvj*Ct&^)8|=0QeIQqMZLK+*GkLmW43vBtf^{Fj5(@b+@z4sBnVB#f`#5f;6a#%z
z<D$UDi)UF_B64yrl*EPH+uK<iaUK--D2<F57%sL79?+|+x7iEHf8x<kD6x4q5L-Y@
zX|)BqPYxliseMKuGDL+?MNbx}5fc-$m2Vd6Z%q*9f<mD{CliFfPP2xGd06K=iM_tz
zcB$v$MqKtzd$Qz@OYxtS#F$g(EO-O{?Gn(R5|@KK2^GOdFpDT1(g|$=vJ^mvvYxXE
zg#4tkdF`h=fEyyo&mu8r%bn_6_*Jup2SQ^W4c;lPS_%p2E@aV8!~+P^8kCds%N!t{
ze$DkJ#T~H1Ghb22`%+$I?reDG9hq&4|01TNUz4y4m@8gx?je^?G#c@>u^1F;wzFOQ
z&u#m64s>y_mvb0q;)jLG&XQ8d!<j2dnpwcZ_t%qE+w%1aTELT6Ry@?DGC;r__dGK_
zNaX1NJ2}_vF>*|?*W!xa{JXIe1rt5yKBlqJ(dWO^5VG8p*&!e6x$u;IYEp4aGK(S$
zElu~HVes$km6%#&%kIrReQU1wdZrJ>)u(U3Mjus$;BtGvLhK;{>)YVld-7&xg!H}b
zDZpJRi{)WH2pX471Jw|K>`NCexJVsenfojHTiC`u1klHOV<KKT{LE|P-a->Q#1E^Z
z`K3F;Pl5U~$T}Rb<y0`?b8Q3gOKT4DgDyYE$4vT<oF@q^QGJCJFrBoswKgc$5$vDp
z&bFY9jMz+gB%L46!9MYYX~@A6@pCt?=@=PF*fhNa^eZnPAMnh!?0)_DccvhNwFY#P
ztJLvuc}t)Z#_(!HhpV~0`|y|wI7#OR%A4VW0s<`8T<!vb1Nc_~TV(rJ1j>56%BL6m
zPtjcRk6jK2S-vYrBZg{<p<#Jx37G9E-ZYGw=sZY8Y)>+2w<M>e;e+(B?)b;KF^{CX
zF=ZHKmYO$VJ+aCPS@4iVyL5m3=NORpfYm9%Dc<G!{`IRzZlJbCAJdNOn*yhW?E$nX
zC}kUfa5!H@x-5aSK+f=#YA`->ISiRQdLOlg^QtWcf&gfziIm+`!I}(sKRiU(m&amx
z9b5SNPn8|7fBh3P#6#t}6#-;H<%qMfNl8f{{KALc#R?cC$+XkFs50BP=*?M2kcc=j
zw;Guy+ynL-Kz%P063)2phQvbXuKsj;51yp^RMv=}Pf-f?+){2!APQJ)gw4(arzFYE
z2z8kWQYG@!az1x7<lcZaX*z{<Zs9{hldmmB*Qfd8ziv0S{x>n5HSV%m{w6nAzCS#2
zkrBC@0E7U&Z)$uzcjTmYthg^*>Tq|3FKhz1<<!;H-2ueC37jOr@&(*K_h?6IeB41b
zfkYyelo|jNs9$961f7W~OTG3{ER^CclK)w)o9(+;$p26KnO(Wxu?)gJT#5vsZ9rWN
zdZ2!p&omX-w}#x?8vB4-;UnAkxQqSaCvdyOFDLc?qcF4oLlM8v_EQm`1S$unERwZc
zsuV{NiGNw+tM}h=v)bzm*-U*09Ebn4F7af@;Z>%x+XDuzyu94p`;Ly?q^I0Yon>AN
z=H**6Z_=CQUvSEI!>dI|(n$~w(Vy;pjKFms=ql`0^u?JO9N1OjRt@1pLql0v+<HRY
z$1+#@Kxiv4OO};aPy)9G&c@uPf0YvH#n3*B;zG|kpK!Cs%8Zs@i81#^bRS%nk{UF<
z9CF~9VK87$!0;i6g2XHL9`!68odE@sHRko}8^C!>Mq`*+Q+9yjWQ$8ljE{el^n}|z
zUo{&ZtxMc-n!}-%@83KwHbNDQ*S$a=W&@(pFRiTk@q2Kvk_xDbfAJ`0`*7n*6yO~{
zNAXh=e)AV63%6(1Jt5mP$Em`AUp`-ZBoAx(ISiO+nMGKt4@dIW-(L0~mA2Ep5S*k7
z^-0k;Gc(iG<)Thm=J%^V__L+K^U$>z7Oc|F)ejkp&%kn*0>{szNBe&V%<t;YOwU@F
zn%4MjECDo=F69MpO%m%g*3rpG0_<-m$Qs+*+rVJ{wOsOVpxfinGV4im^7m0-fZrJ)
zfggRvR?%3X4JQBVP5(9wN5{nc7ss%Z+i{Oo&|9-rX5WRbo|mi~s;Q|lDz$AKbF1E)
zCsgxkB)v>c6_gkn{qPu^2d}w-?4<BS8MHj(w-%w+wTH_o8n4eeXc8#uv5^sffAYC8
zu)QaVH!l6&EYfRf1a^Kj7Px@`cbH#Mfj5;2IrMw?i18&70AQvVH~~Dk2P*dWs{Pqb
zVtNcTQT*Ob0^>w1ANswUL=bcq{N7E12Hhm5fA1zK2i+u(e(xqZr31D2*Qh~@%dvkA
zQib66dyC8eYlG6Ww6p{ih|x1cF3_kDH?4yKjxo(-@m7?g2X~VyN(A=s45c{+xP~c}
zKK?u&w2q*8!n&P+Sr$M{Y3FWxh6!$bV)^xOiaZZ|aof!nyOw`k_*n!2yMNz%JW3fj
zwUguN@=WahTRW4bpm*Nj{7HPhNg=ABFpIlDD~L>fghxVG-}A9M6#5W@op{T5cnx<-
z3aiynse71yYZq9jG7q;QHo6ezhAQSNoSHJE8gX)e{qVwk-XIVR0XWVd@o>_3ePCSf
z(qC;$$Zt<iQxuHSQ^j~cJR+^M+P%`>V;K?PlScmL0Q+2&#K@KT*z(RU*$j3!t%s|)
z@^}+$7_k~pZ5LSNQ=Qd!Za$^UXv}eQv<`)_D49=ePicr?hR<0zt<FyJ=n(OJee1wP
z&d0}x8E#Q;dHQtvpIuSFc3c89Eef#ie~{pyadrQl&aR}Q<<$vWtQk}05_zLFc4RkB
z?B1>A29{&z*G9H1S_j?e=WsKq#rvD_QpvD@YlPYU)@NJ@5VX$91^AI@9GguILmt&b
zL){oiEr%(D^C$+iB7masvf<lNKr-60SY~aYNYZv*Q_+J(8<J~{Z+S=HJKKDCG^XW5
zn6{D5kZGl3RQc@2WJI)f)RqC-AyJy}>peSG_O^>A&sI+2aD>V-4T8DPL@c10%7!JW
z-0yvesTU1(WEkOYN_4tD`=aXG(OeWN1)x0OrfFe3lmVpEySpZ0tuiT7v-75LdmpP_
zk1n;6d}7JZ(ko_OO^YSRi`Ho({R2p7$FK8o*|vMM1}1W~bv|3Qp-w@{DI(`FxT~e_
zE;goAB*#C`f=|<h+B5WX*CtYN)9F%rd&Sa~D7Ut#5G+kgBW$lEyyJbN5tGro9qF44
zOWWzioAuMlt;3UdD~1B_wO#|qBd@(FZOF7I1d8?^+%|%mUpcfNG@2cGJz0ugPGNmn
zQj6Nyv|EAe=Ji#x$C@M>3^F&^=<sVG_v8x8YPV7+=j`@cYdESSl_Qk9Rs!K@>Rn$#
z(t5&vI?x?Q84e<q@}^<C9mXrVB-%PB%^GvRl8wzhjH{F6h1GfYz2O=uTkmAqOt=Hu
zZ&$c<Z?{L^Gkub8IULi@?5>1z75D#PftRYQ$nmT8fnG|#qPOlw$3aJFMgF;2;9EJd
zy(4NG_PgeoU5VBO^}*#WaaJZ@uW52?^<FQd)8;lYbW+XUZ8gwCe|a8LHzD@M%&I+^
zfdMt1re7C$Uvq%l|9J0OmDplz&2_pLRr@$SB)+}69sWJBihrB#RC_9DQRSrc><MaT
z!8NwGrQ0L^`lKTp4ygkDyFdG$LGYtFa_#@eKLGYJxfJ@IQ&5o7NDkmGM+%_hz^PmX
z*$80UrKKh4Lv?GJulX;^IRzB(p_LxLI?}I!@>|cqfF0m1prYZrNDuz|RiKxqyZapI
z(!#X^z&=Rxdmq(-SH4_`10QF$H<m$abc2H~H8e#&`|np#lrw#FQBi!CJ4HJCyKCsH
zq;UL+pS|$^Gk#M57wCbd{AvTx#r^ky$M&fFXW!qk%Rf&Ge*XbPRZ&v`ee>?4{{@z}
Bm-zqy

diff --git a/riscv-sbi.adoc b/riscv-sbi.adoc
index d7401fa..5ac9e44 100644
--- a/riscv-sbi.adoc
+++ b/riscv-sbi.adoc
@@ -33,6 +33,7 @@ https://creativecommons.org/licenses/by/4.0/.
 * Added SBI system reset extension
 * Improved SBI introduction secion
 * Improved documentation of SBI hart state managment extension
+* Added suspend function to SBI hart state managment extension
 
 === Version 0.2
 
@@ -668,27 +669,58 @@ The Hart State Management (HSM) Extension
introduces a set hart states and a
 set of functions which allow the supervisor-mode software to request
a hart
 state change.
 
-The possible hart states are as follows:
+The <<table_hsm_states>> shown below describes all possible **HSM
states**
+along with a unique **HSM state id** for each state:
 
-* **STOPPED:** The hart is not executing in supervisor-mode or any
lower
-  privilege mode. It is probably powered-down by the SBI
implementation
-  if the underlying platform has a mechanism to physically power-
down harts.
-* **STARTED:** The hart is physically powered-up and executing
normally.
-* **START_PENDING:** Some other hart has requested to start (or
power-up)
-  the hart from the **STOPPED** state and the SBI implementation is
still
-  working to get the hart in the **STARTED** state.
-* **STOP_PENDING:** The hart has requested to stop (or power-down)
itself
-  from the **STARTED** state and the SBI implementation is still
working
-  to get the hart in the **STOPPED** state.
+[#table_hsm_states]
+.HSM Hart States
+[cols="1,2,4", width=100%, align="center", options="header"]
+|===
+| State ID | State Name      | Description
+| 0        | STARTED         | The hart is physically powered-up and
executing
+                               normally.
+| 1        | STOPPED         | The hart is not executing in
supervisor-mode
+                               or any lower privilege mode. It is
probably
+                               powered-down by the SBI
implementation if the
+                               underlying platform has a mechanism
to
+                               physically power-down harts.
+| 2        | START_PENDING   | Some other hart has requested to
start (or
+                               power-up) the hart from the
**STOPPED** state
+                               and the SBI implementation is still
working to
+                               get the hart in the **STARTED**
state.
+| 3        | STOP_PENDING    | The hart has requested to stop (or
power-down)
+                               itself from the **STARTED** state and
the SBI
+                               implementation is still working to
get the hart
+                               in the **STOPPED** state.
+| 4        | SUSPENDED       | This hart is in a platform specific
suspend (or
+                               low power) state.
+| 5        | SUSPEND_PENDING | The hart has requestd to put itself
in a
+                               platform specific low power state
from the
+                               **STARTED** state and the SBI
implementation
+                               is still working to get the hart in
the
+                               platform specific **SUSPENDED**
state.
+| 6        | RESUME_PENDING  | An interrupt or platform specific
hardware
+                               event has caused the hart to resume
normal
+                               execution from the **SUSPENDED**
state and
+                               the SBI implementation is still
working to
+                               get the hart in the **STARTED**
state.
+|===
 
 At any point in time, a hart should be in one of the above mentioned
hart
 states. The hart state transitions by the SBI implementation should
follow
-the state machine shown below in the figure <<fig_hsm>>.
+the state machine shown below in the <<figure_hsm>>.
 
-[#fig_hsm]
+[#figure_hsm]
 .SBI HSM State Machine
 image::riscv-sbi-hsm.png[]
 
+A platform can have multiple harts grouped into a cluster with
separate power
+and clock. The HSM states are only hart level states and does not
imply any
+thing about the cluster level states. The SBI implementation can
incorporate
+a plaform specific cluster level state transitions but SBI
implementation must
+ensure that there is not impact on hart level state transition
s/not/no

latency due to
+implicit cluster level state transitions.
+
 === Function: HART start (FID #0)
 
 [source, C]
@@ -698,13 +730,29 @@ struct sbiret sbi_hart_start(unsigned long
hartid,
                              unsigned long opaque)
 ----
 
-Request the SBI implementation to start executing the given hart at
specified
-address in supervisor-mode. This call is asynchronous -- more
specifically,
-the `sbi_hart_start()` may return before target hart starts
executing as long
-as the SBI implemenation is capable of ensuring the return code is
accurate.
-It is recommended that if the SBI implementation is a platform
runtime
-firmware executing in machine-mode (M-mode) then it MUST configure
PMP and
-other the M-mode state before executing in supervisor-mode.
+Request the SBI implementation to start executing the target hart in
+supervisor-mode at address specified by `start_addr` parameter with
+specific registers values described in the
<<table_hsm_hart_start_regs>>
+below.
+
+[#table_hsm_hart_start_regs]
I think all the table title should be bottom of the table unless there
is guideline that says otherwise.

+.HSM Hart Start Register State
+[cols=",", width=80%, align="center", options="header"]
+|===
+|Register Name | Register Value
+|satp          | 0
+|sstatus.SIE   | 0
+|a0            | hartid
+|a1            | `opaque` parameter
+2+|All other registers remain in an undefined state.
+|===
+
+This call is asynchronous -- more specifically, the
`sbi_hart_start()` may
+return before target hart starts executing as long as the SBI
implemenation
+is capable of ensuring the return code is accurate. It is
recommended that
+if the SBI implementation is a platform runtime firmware executing
in
+machine-mode (M-mode) then it MUST configure PMP and other the M-
mode
+state before executing in supervisor-mode.
 
These changes can be part of a separate patch as it improves the
current text. We can merge it sooner than the patch that actually adds
the suspend section.

 The `hartid` parameter specifies the target hart which is to be
started.
 
@@ -715,8 +763,10 @@ The `opaque` parameter is a XLEN-bit value which
will be set in the `a1`
 register when the hart starts executing at `start_addr`.
 
 The possible error codes returned in `sbiret.error` are shown in the
-table below:
+<<table_hsm_hart_start_errors>> below.
 
+[#table_hsm_hart_start_errors]
+.HSM Hart Start Errors
 [cols="1,2", width=100%, align="center", options="header"]
 |===
 | Error code                | Description
@@ -733,20 +783,6 @@ table below:
 | SBI_ERR_FAILED            | The start request failed for unknown
reasons.
 |===
 
-The target hart jumps to supervisor-mode at address specified by
`start_addr`
-with following values in specific registers.
-
-[cols=",", width=50%, align="center", options="header"]
-|===
-|Register Name | Register Value
-|satp          | 0
-|sstatus.SIE   | 0
-|a0            | hartid
-|a1            | opaque
-|===
-
-All other registers remain in an undefined state.
-
 === Function: HART stop (FID #1)
 
 [source, C]
@@ -761,8 +797,10 @@ This call is not expected to return under normal
conditions. The
 disabled.
 
 The possible error codes returned in `sbiret.error` are shown in the
-table below:
+<<table_hsm_hart_stop_errors>> below.
 
+[#table_hsm_hart_stop_errors]
+.HSM Hart Stop Errors
 [cols="1,2", width=100%, align="center", options="header"]
 |===
 | Error code     | Description
@@ -776,45 +814,127 @@ table below:
 struct sbiret sbi_hart_get_status(unsigned long hartid)
 ----
 
-Get the current status (or HSM state) of the given hart in
`sbiret.value`,
+Get the current status (or HSM state id) of the given hart in
`sbiret.value`,
 or an error through `sbiret.error`.
 
 The `hartid` parameter specifies the target hart which is to be
started.
 
-The possible status values returned in `sbiret.value` are shown in
the
-table below:
-
-[cols="2,1,2", width=80%, align="center", options="header"]
-|===
-| Name          | Value | Description
-| STARTED       |   0   | Hart Started
-| STOPPED       |   1   | Hart Stopped
-| START_PENDING |   2   | Hart start request pending
-| STOP_PENDING  |   3   | Hart stop request pending
-|===
+The possible status (or HSM state id) values returned in
`sbiret.value`
+are described in <<table_hsm_states>>.
 
 The possible error codes returned in `sbiret.error` are shown in the
-table below:
+<<table_hsm_hart_get_status_errors>> below:
 
+[#table_hsm_hart_get_status_errors]
+.HSM Hart Get Status Errors
 [cols="1,2", width=100%, align="center", options="header"]
 |===
 | Error code            | Description
-| SBI_ERR_INVALID_PARAM | The given `hartid` or `start_addr` is not
valid
+| SBI_ERR_INVALID_PARAM | The given `hartid` is not valid
 |===
 
 The harts may transition HSM states at any time due to any
concurrent
-`sbi_hart_start` or `sbi_hart_stop` calls, the return value from
this
-function may not represent the actual state of the hart at the time
of
-return value verification.
+`sbi_hart_start()` or `sbi_hart_stop()` or `sbi_hart_suspend()`
calls,
+the return value from this function may not represent the actual
state
+of the hart at the time of return value verification.
+
+=== Function: HART suspend (FID #3)
+
+[source, C]
+----
+struct sbiret sbi_hart_suspend(unsigned long suspend_type,
+                               unsigned long resume_addr,
+                               unsigned long opaque)
+----
+
+Request the SBI implementation to put the calling hart in a platform
specfic
+suspend (or low power) state specified by the `suspend_type`
parameter. Upon
+an interrupt or platform specific hardware event, the hart will
automatically
+come out of suspend state and resume normal execution.
+
An additional clarification that says that the suspended hart need to
receive the interrupt or hardware event to come out of the suspend
mode.

+The platform specific suspend states for a hart can be either
retentive
+or non-rententive in nature. A retentive suspend state will preserve
hart
+register and CSR values for all privilege modes whereas a non-
retentive
+suspend state will not preserve hart register and CSR values.
+
+Resuming from a retentive suspend state is straight forward and the
+supervisor-mode software will see SBI suspend call return without
any
+failures.
+
+Resuming from a non-retentive suspend state is relatively more
involved and
+requires software to restore various hart registers and CSRs for all
privilege
More clarification required here about the privilege mode of the
software.

+modes. Upon resuming from non-retentive suspend state, the hart will
jump to
+supervisor-mode at address specified by `resume_addr` with specific
registers
+values described in the <<table_hsm_hart_resume_regs>> below.
+
+[#table_hsm_hart_resume_regs]
+.HSM Hart Resume Register State
+[cols=",", width=80%, align="center", options="header"]
+|===
+|Register Name | Register Value
+|satp          | 0
+|sstatus.SIE   | 0
+|a0            | hartid
+|a1            | `opaque` parameter
+2+|All other registers remain in an undefined state.
+|===
+
+The `suspend_type` parameter is 32 bits wide and the possible values
are
+shown in <<table_hsm_hart_suspend_types>> below.
+
+[#table_hsm_hart_suspend_types]
+.HSM Hart Suspend Types
+[cols="1,2", width=90%, align="center", options="header"]
+|===
+| Value                   | Description
+| 0x00000000              | Default retentive suspend
+| 0x00000001 - 0x0FFFFFFF | Reserved for future use
+| 0x10000000 - 0x7FFFFFFF | Platform specific retentive suspend
+| 0x80000000              | Default non-retentive suspend
+| 0x80000001 - 0x8FFFFFFF | Reserved for future use
+| 0x90000000 - 0xFFFFFFFF | Platform specific non-retentive suspend
+| > 0xFFFFFFFF            | Reserved (and non-existent on RV32)
+|===
+
+The `resume_addr` parameter points to a runtime-specified physical
address,
+where the hart can resume execution in supervisor-mode after a non-
retentive
+suspend.
+
+The `opaque` parameter is a XLEN-bit value which will be set in the
`a1`
+register when the hart resumes exectution at `resume_addr` after a
+non-retentive suspend.
+
+The possible error codes returned in `sbiret.error` are shown in the
+<<table_hsm_hart_suspend_errors>> below.
+
+[#table_hsm_hart_suspend_errors]
+.HSM Hart Suspend Errors
+[cols="1,2", width=100%, align="center", options="header"]
+|===
+| Error code              | Description
+| SBI_SUCCESS             | Hart has suspended and resumed back
successfully
+                            from a retentive suspend state.
+| SBI_ERR_INVALID_PARAM   | `suspend_type` is not valid.
+| SBI_ERR_NOT_SUPPORTED   | `suspend_type` is valid but not
implemented.
+| SBI_ERR_INVALID_ADDRESS | `resume_addr` is not valid possibly due
to
+                            following reasons: +
+                            * It is not a valid physical address. +
+                            * The address is prohibited by PMP to
run in
+                              supervisor mode.
+| SBI_ERR_FAILED          | The suspend request failed for unknown
reasons.
+|===
 
 === Function Listing
 
-[cols="3,1,1", width=70%, align="center", options="header"]
+[#table_hsm_function_listing]
+.HSM Function List
+[cols="3,2,1,2", width=80%, align="center", options="header"]
 |===
-| Function Name       | FID | EID
-| sbi_hart_start      |   0 | 0x48534D
-| sbi_hart_stop       |   1 | 0x48534D
-| sbi_hart_get_status |   2 | 0x48534D
+| Function Name       | SBI Version | FID | EID
+| sbi_hart_start      | 0.2         |  0  | 0x48534D
+| sbi_hart_stop       | 0.2         |  1  | 0x48534D
+| sbi_hart_get_status | 0.2         |  2  | 0x48534D
+| sbi_hart_suspend    | 0.3         |  3  | 0x48534D
 |===
 
 == System Reset Extension (EID #0x53525354 "SRST")
Other than that, the patch looks good to me.

--
Regards,
Atish

Join tech-unixplatformspec@lists.riscv.org to automatically receive all group messages.