[PATCH v3 2/2] Add HSM hart suspend function


Anup Patel
 

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 -> 31264 bytes
riscv-sbi.adoc | 146 ++++++++++++++++++++++++++++++++++++++++----
3 files changed, 160 insertions(+), 26 deletions(-)

diff --git a/riscv-sbi-hsm.ditaa b/riscv-sbi-hsm.ditaa
index 72b6312..bd73993 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..14aca4f0b54941f3027b7a4d5605f4e2652b9e86 100644
GIT binary patch
literal 31264
zcmd?RcQ}^qA3uIuQAlNlNFkIF8CjvSvJyg8*;Mx4q(!!ny=S(vM`Z6kZ!?+MviZJm
zdg^&T&*%3!zQ^(V>v#P6!*SDfU)On^=Xt%yYg}*d%ZTBhB0q&dAn+x`?>;~vFm53b
zXmdE|@RxfZ@S+h2yJ?BL!V0z;3uOcf3Vj2I4nkEpIA?7;-kib3v7?~4<k^Dz=<p@Q
zQx{eh(Rh-zq?8K1{jhJ+hT$As+jfD9gi1YMKig!`X3VmFRpuD+dqi=zlzc;k=rEB)
zo1@^7Lgu4)Cs~My+1M*~uM-$^J4Ex~HGg=bx8>Zc@v$s=dcdLe!cXU)HV2W~dnPa@
z1mX<s`82enPncKzjE_DDS3jTqj(PME?PLN4>Vr@_V)g{;!x;{t;-kYc@&7s+<Ns%e
zVA8#n>o|e14h#)Vk>NxLxuVUU5W0W6WZ_UF9}lZ$<n~%xQBhH1;?&@$r_Y~1=QbHp
z(5FJgWVu;lP&2q$-dPcewd-kbZ}0E#@9w^f?$aI4yM{nG;lnfv!*qMHo@z;_5%Y<-
zX*RJike4u$sa}%Q%8wAz#6VpKefHIa*X=c<%|)b@l~uwBIR%C4qetBzun{v)sgVer
zd(_DLj&cSXiVq(K*z=ix6Tfrkj)g_uzb~;l>f+KA%#3~d0$k{>ynNt)9s=WWBlt6@
z|1baQc3V!aqsEI=F`eRQdQcPPi26Zf&?hA=jVyO6nY)hBiC;sC)rs#~i48x5zL=h+
zqB>Z}Yy159bJ}92P;u;59PIrwTc{rl*_PU(zEn<I%TG9OU)D(&B5h-0Ddy&5<o)im
zj0XEddx^Z&diz;@cENaqW^;wfLbh;D_cgow7kUmW=rzx1H?CmNTt47ro9%f^@JXN`
zKUu?V;na<)xXX*;Z_Cz7W>uaZILYj;Rh;vsK(BFyoim2oKKExXli*d4o0cBz%>VfD
z!zcomMj>H{MkRixXivA7AoF11y};oL?d&Bw*S1&Bc=o@=UFvvoKzB9C=x3Fr;5OZU
z;!b<0@a?h&b@IbCm(~*Q*I|MUk?rzX4?N~qWnH%Ww%eErSwnP&4_CaKpSG39VPhMz
zq2|f<XtI>a7^EV3KgGrh<KthNwNBQi76`GBtw<>;T(<LLt{Ekl3|8#YJJqz5EO0w`
zd()fqhxz!2!@w|`ny){ru8|@)y7%pLwxjLjH^!)$Pr!ykL+vj&^lKQAUtVBmsh2z?
z=-os<W*RNL5fvq=rND7A_mI=6cl%K7Bj&P%A2V%Uz4`alp=iGckxUIQCZtLnSDLk|
z%WmfVY!tDf++Px;!4<#~xGC<1dLk>~aoKS#E-sFXi~IIXX9U-cGnN@?E$~yY7LSr8
z>Z7*MU6pY)9@ihabeH)fnEIj}6qQqCg88bjXVgCmp0k=(Z09pC+R0O@KgScZW_Bm$
zd~hf8jT`c}n1$TT$#uCJO;#l^Dy^xJt`!5Nb{39~d#h7T^YinHnunrDY&DNP>?E~T
z{*9_7Dtp=|k2wUgg8KP%Nu#j`CKlBTp1de7wW!5=_ok5k((L=C(8DudB9)wP%31d5
zAMPig7_q`Ah=~yW;Jr$r%hQAH>I8eP!hB_-=F**4&ydB6RtV|hjlgKe`l&;w2^D*d
z7nE|j{;=ZPUkYl^3v6eGKd}GNqb^u{h=wt0g`pn1C#urA*7OvkT^@$3X*cQ3t=AHk
z_{a_S;R&h3qMP*?4XG}Bn?>|4>w6p18vCZTF70b!YgzGAh+CI(r@DPf_9YeY4y)Ez
zW%*p5@Y34fuMVs*?W?gDA}Fg8A+R?%@Fn$WO}yg#<dh{tlU$~J2BIG`fnxdE%a<?n
z*-{>kxxW{7DWNqPuQy2|kU398W+%4g+Fi&OU3xgm5?soJ9csk*z(jDXH?%}ci>9i2
z)?}riHp<!D-ztR4j#x)2^eor)%UZV2F1-ERbNHMqbN+<o%!LPkE;Bnj>vFg|s(8)x
z$(X1zgOfTn@|j!ig(=>iQ?AmesXIqO;jq1`+jB~7?B^PTlg7XPpNeX6(P1-2?AKF1
zfUe8aXq85c2!}_{`6bth9!z_zqtKiXuD;IDx6;R;IM4jC>>WLuKuso_6K`vl^Tsvy
zTU%o<s@SdO6mpp~%hfzjaiV6sgOqB95;nUhfhXFm9-%;^RZ`sD$3JxW-_9~xd(W1b
z84nk-Ioj4?l|6m>^rcx_lz`49KD)$zKlD!gEn-!Y>!!CM^dz14Gv?}uS4;K^h?>~P
z;XV3hT3TAY`QiR%ljvpo<Vg}n4sT+IdPvlJp3J!CZ(f2#Ade@`9o}w%{BT3x)5}Z#
z!GjB@#U4ExEVWxpOHUuDiPPDb>(Q=#_twX!wZ2|CPtSWMMUsTlhmn;v`lgwdqod>P
z+qa)QiFK?C`}DNW98bXh;ltjE8m}zP3YJaCZOn{}68G*+n9SzLQP;914kah~YB#O$
zZ*<EmXnub7;e7BV+<}Jl{yQhcxyO{g24HAtp(Z#6buY2g#S(#6{LQLg;VWfn2srQA
z8XC?PnoaiCnA5VdE_J8M<KyE`*7+tU70UQAJskeRHZU;o`ZQ&+<!omFon(rHF9SLW
z^CJZnm4VLA&f(!wt(sG-<;zvL=A(TY4&FP?`x||6Ui7|A%KV(k;bzZxqH?tB$khdz
zb+>NFuU`G>hlZM7C$twMPyRlp(9rYj50#YWD{}Saave5}jUT)WlTVWJFDr;|84E3Q
z*fbC94j;F_lm1kJp4)hsI;(K?!lr=j^5Z@RU#gHCTO%2Q+S!d2JSzTBCQ=qPKku)k
znvTLhx3+9+sMt|kQLD_=Z5k$k;TFS*gmCGZBI7ELlT5eb;^QsM&F|g2*BT|z#PZqe
zsYdSdJt?W6GBq3Qx;JeXByKm9i8nS!3kuTF(Otgm{^QkrEwlOP=g(Zmr@o#2h`Ml|
z*#d7A8perG(SVl=9EDm0WT@>YM?y8j`DgptXFfGBP|kiVY-Ds*@{BtXK}jKF0)^r`
z4GC_WV8gB?vP@apZTz&}-iHI}o1Z?<qh@d5rZpwOh}8>AjDt!`VRwzkzbEX8|9n_@
zcwdI97#bTJ+p{Nf6Z_ani%dB=Ij?B(Z5D?a9X86Pl$AqMk?8xWJT0|3^R`<d30s*I
z5FD73aL=uyqmnK*B)Ghj0)10cQyH2S2j3b3`?54gOYLr85fKq(d(|{<txU>B-(q%7
z%6>k?HQ?YtePjLn!0Olwf(K4hjqjB*)dmVoH1+h77J7Es8yXsP1nt*T=GwFWniKjc
z+bYvT+%EcP#|JsD@%)S{vqD+K+i~I9Ai79|(b;lkT}??<RaHTOL+dNf>uUe7uwv8k
zs@hsn>l|gfO{7g;US51$9Bi|PSsKi|#ewYX_V1qY!2Lz=Se!d|ZYCC%uCcLECu<~x
zk(rs2*D{4K>s^h!MVPmC--?2Q!u?3m8S?&ZV>Ly^_rI2fP2Des^v^b+?%Q^QI^#+8
ztB%x>JbmBm6UL_y{dk=p)c=Y|Smu!~V-BG*k-Un^TU1Fq$tkf%Ay!=98VywvqR;A)
z)>~EDV0u^%!DICGEn#3lzzMwb*A3cZy1TovsceO8@!u{lFBcXT4iBrH>t1z;T_Bdm
zdYZ+(Wvs(GTjMsXZt1nzf9r7tEXSP{VaWT>s%q8fAFwG|cAqxR#`$b|(pXSKsr%-b
z!;VJr{-RAq{NX;U%XSlM#a?b=Vq#|IB6r2Mw6*nT96x$72Z!B;KzjYw2#Mh2Xy-u=
z(YnET{Bnu`Nqe)$_N2%OfzJf}CUA}Wj`vY9Dx0mZA+<j||5-<06&AW*d5AHTzzJks
z!^0nWjbmj~VKL(8dw#B;KWta>9bzuKnXO?ti{)(l#@QWp`!67{40w1K$;h;h&>DG_
zldzm|T`#lr^6^O`lUG(&R#emtyRyz$)9KB7%8QC7-nK~P;X^K?Zid&@W}{A<iV6y)
ztBu!S?{IwgI7xVGci{$|?Qv+lWFjhB8^-yRD9d1R@KbtB3^f-Q7YhrEpkVYXVitXZ
zi+zSX<OGTu8n>W|4#+-v@}wm?Q~|nKLhFx8teI73I`VRJNmw<Q7Q;F}y|(j-c_xD`
z@tT~Nm=i*t(J4}~Vm>M|JE1ZBKhJ1V(PEdZU?iW-qPh)IM8bBVKgZ=@E&65p(B8+s
z$lxK&l@W)fjwlg{@Sm)MH9_U<3+%{Qa|;XnzK>_VP;eX5HqCUzzZCi2{NYATO${R>
z<N96LyWd;FmDJUlOG$R$boHvU=g&IK{+vtCT6OUvyXCm0?JMwEyYBSaO6$ymf`VvX
zE2Eza13Hj4d<@_DOiX=$M|PupZ?$P-zR$t}PORy)L9BU#mz7oa<P}_j%)$o~KYtAA
zvi8k}(p<hQUSeAAu(wi&-*@l+tJP(*46(`be+F+J!%o_cNQ}FID)|O-y1KfOl9Cn{
zYo5f{@cNv@J(QL%s~WhyeEoXO?xxcYhhhrjLrSqn7kq^TueS63{h=*zIdty4mYSM6
z^!a&-<MyiN;f_)OXVp{x=qUxJzKnvm8L9>31uScl%ij|(5?8ZyMP}yb2hDXQ%aVR6
z#bVVg-?Mf(*|_%&nf;`?Ctb<+qM!`2&YPl+W!~wl;XDi3AZ#HTNU}*%AF4L}b*rkX
zMx1w_|2!3s$L!iBc&PTSQnW+ie(5m3^}_icL*s@PnEd+!?CcLt{`_`8%i)&d4E=#|
zl%Pvg*!slV@XP(xb)TrbcNdW*A>oeIeD>Z|(r2l|c=z5w0aF!c<Ih|gP-B;pn#z_>
zv8)33YlqYR^zZjuS8&E})X?H}Ks3*nIji~STC3k0URi#*F;aS06U+L;qGeyEx}>;x
z4F1k=k%dfOM&^mr7sLbRVIQpGxI<=}Q&m?-j*Mg$e%w5poKd1<KzOFpJNA%pUrf_}
zHc|M+i4H+(8k!eB_Sy)aa5yNd3GOXdSEYPqV9+r3yqIF1myywOS$Wv#M`xnstMC%^
zHTsHE9LRxd?gEZ#^BskZBQnXvRU{qihP>(plaYch&iC$}DwBGWHNI1miPK(EPtw`=
z%9^U40kxKu-8lAW(zkClAo_8Bl=vBcer!<WlUF>;_^GvRxO={L2y>SCj^yAgYX!WL
z;UAW50-F(L^UpuqjM%-NqrD@di4~y5Pfn>JBO@ar(J+vwKcHLYd-FMx?oK!&z}Q_n
zoQtf}fot#34}(RmP>AG#ZB<-dJ;R6wM~%YdW*}1nMTU^^T&T}NrlCOCxsR&ru1BfQ
zW^8srF7MN)PeUxZA}Z#NRB<Lw$oAqaEhXugg7&7-SFc_{RBC@31;Kt3EgK_Dk|W+g
zqhld=3ymyWw9P7_hgG9Ar9TomrEdevbKBoIA|HloT{JX%u;T0D@$#iNIcKBYyn6wJ
z%Yx#x_I#D&OzdkYzLc)AL?iQjGTZo(;C}m+Gl>+3d^c{~C`#Qch{z;m&>>^jd6PZE
z#_m}_D&1A!|NgPFO>t>yL^y8}P07<ozDbz#B#-p&2|auE@lwVIh#l5LBB$?<%zR&q
zaeUlpWkd1=br1RZ`5ataQ8&%vGBbS+XjBn@?jepRNrrEX%sx}QBhPG7v}SREMX)4Y
z)r4>_^2U<jb=@S{Xyd|LKkx|%=&`J4JL$&Fv1gqR+#g9v;i;mw(`Pef?u=+>gRafa
zA5jjAb_d(jf(KiZJ3IFFslr)28qV9gJ1%<%n-$ZDsfvv@mxDmT>rNAI={@A$%H1z5
zGg##os0raNcs`Vb-3PFUsAy7R;tyoWX5;&7bv~4;pNtfZjWgMUUQ5q+1U*IuL_|on
z#Ebc!!gXoUf*OEhu-s`^oXiGpx_@HFKGl(GJ(}^2Ptx&itCd)1q^8aSnv&l{#bf>r
zfv^^`c&kU$axF}qqpsT!oBvLmRZueu3eo!d=EqP$;FW`+(Sx5e@xHlDyvNfJ6zxrQ
zAoT?)Bj&i?A@*wC>E;duXtmVzdm0)eI~((|QT%rMI~y(G-13gX!e}M`F(=O<XhIB>
zkdUDLHd}H2;zikehc5_jok80hJ=flyY`8z+#oAeM@9kM>tePRO?<Gs+lGqYr;(2!u
zJ5mfD^oFx(pO7{VlZEZa#KJOC;ZjlZcs{AioI^l4Cnz}hG$pSBR}`O(accw*WT4Zp
zY3S*bKYsi;#B#5aq|diFUhUiTw34FY$&hn~MrW;|n~_virFf3WuYhFsfQlc@m9kwe
zj!b0DQ!ivI?CcC<Qc-4RrZJ>|JFoC!`T6yl&#wex&F?K_F6IwkiOBpI6%{2z_B;KU
z7j&Hkn2VO?_4C1e32Vmg-d+-7V*lHT(*Z}N)a@{ts;4==H$Um?BQ32r*YAWven<1U
zrR2&zrZb2`CqJkH&3`Q^kpX(;X#<vycX4(id0yW`d4IU-duU{;7F#k3q$VWLZnFf%
z$hun2Lp$N{r2!MMj(wY{Prb-|%3q8smVTpG)g<-Sm<=_u7_GBK!;~EjvF~=j(P~ez
z6zZz7?eF1f1nXFS#$|QUX{}<uQ(jLp>hev|5JL6sUTVqovPdn~^7Esl+UQu~1tXJf
zC+FhpR%^0*wI3BC5Y##|BAH!*$;LUPn(vmp*xb+)RF_V=ot*PZek_pm5*LBE{Yv8-
zuYlbgiNi|GR{42C2BBgVGg$PAiHV>fA}A_@gSkvbO6TT`tXCF@-mvU7P0!5Cq@<**
zOxDdSeN-v4-w0*XW`Ovs-4ezru-dq>y1M$7kiNFAj-Hm5h=ioKug_~t5aLL8<cZi=
z1EHd<+XZ(r)JuZ3XYh1%b(u9vm4|<L{>aG4fDQrnnPVFX*Qu{J(dB6n2#@oyphNh#
zC8E>{#5+o?e_Ul?c;oHu?d8?f)|Qo$a)xCwJ;C6mab1BEF5)v{Ru4<l+x|a0GY_Tc
zFvqelrKP3v$ug0*oWic|SUnxMmT6b$v}@f~W-h?Tx7!|jCxk`)QLfHO&e{6|lImY?
ze#Ic*r`}Y|rt(xi%Jp=b4q7#y#INQbLi_T!POYYz2bpjKfxux~SJN*OzS$B$uR5GK
zL&;}-_wHT4Io|Q&Atud_8fw1YyK{_>YV9492|gnp<N6st{QC84JJCnjt|lf*PI`n2
zMNMMT(%!L1=0;?sDE~_1#!=U{L~+G<`<{A=1VM{5uWeD5J3G-Ro-$sd>0~YbYEp8t
zMc^(Kzisx@paw(#oTFV4GtE1XUu77~KQO@}5@-<reZ2a0k=?<bospidZiCYX5wo^H
zxjQoiQ7m!pYX)*FOz)tLZfJmli^t*T$K^Q~N&yQi2D^FSBypBGy~EQiHPWR=fggj)
z8kt|)T^NT+ne$>T5B-%Xv$gpyjaW@5Ip<i}VN&9f!m{DnXXcGiN9Z*KGA};h7<Ey9
zQt66jt|=hWWcsdT#VH31p$e^2Tx{%<FYZ`S2Wj;_s<{2&;gyPuqUm1Y7qV=T65R4x
z8hy-Ve#VPTT}je6)J%Le3r*d^V4LJBEj@j%&!h&RKKo2jtNjbpFgn?%xRTuGl+9g*
zmeS+v>Pa-8p;eMlBl+WsitLcZRveVtT3Q}#OiWTAVj6eH_hOTMZ(W}%HXbLCs-YN*
za(q133Q)^a@wa-@t&wp4rkP}s+A1sr;?j$#`H$Q<$ttVeT_2x);J3>i-|=_5K;6DO
zH^Y`&L;7nHVaxYsX}UmJGvAj5Ps@iSZDC=z<ty~`fm2Y^R#lDOPTa8DSvNdLbvw9$
zH6YpYeCV^?V$Xc>OP8eUP*jqCt&V0a%v&bThpx~L5`)w3PhCB|MvXGo_-GQcE*7|1
zt=~5*(9#$j78X`tUk`cFK0`)jr$0wK{b5F9OG^(8GWO5?e@w~9V7_{loK4H4dR$yu
zTD{QpiMDq9a`18J{ZPI)w8TKVy}hlds906wzf`_!Y;DbDXIS<&8r^QDXFiFf{3Z_m
z?K>U!xDreR8I%dE7Ke*?EWXpy(zbWC!IrspEwId9vvxfnN6H&D#L(}&UPpUx<8GQV
zq^0Ws(tQ1Tx6|}b0x(Qqgf4WYh6M2p!kvq<tnO2jtnKwKS;KyZ#Ue4Q^|R%+K5#Ar
z>OQnlwAt^1A8S5*DiCvAau^*dbFh(=Y?_XCY1Mq?H(EKbx?qnwwEmxmLgxx;LrhGp
zuBJvhjKdHDg3;a4Cw&%}2v=9F^_h-{TC4g*QH(JNs+C#L%pzRx>kQ=Trs<Sm6?GdR
zN)afC1v-4h8BY!l4v*Kb)6-h4@Kw!II}o;LD0~ow0aM={Un05YC+Ce($%g_gP<S)q
zQsa<GMaC)aYU+4$Y*(8j-~@gkZU=dhvhrRytx_Nt_|E78Vg!)hy;G>OczocoNMb^!
zq>3WOI8o!#(bG%20`Y|S*52|Rm0~%0Z$u@EA%TAm2G5^+`}*o5MTw2l&LV74)C&Uf
zm_l%GoB)m#*+6@YeZ+3LK8N1xMIwcw!bODjF$2~w>fqpzhMSgh3$XzA2j9yM6k$=g
zhTwvsz;FExPe^|OhwvK$hy3`G2zN+Ys6V*I0PuwRKy3inBI?6`JtQNLZ>coUL>*m7
zke-cAPMs=d)Kv-xL0JFcOlJn+j-V4dV(S~>Bixpj7G`E<sQUptEU{ZlDt;t1<NoJB
zS|-H#N4S8bL9myWmJa&Npr4wK<-t<#fw=A#aq<$9SGWq@HTIL~w|aj<dYK3ThhTG(
zvIzwxTpV@3lW338c?fS8Te*8+A?`eVa!fe|<;@V&mks~dLt=At15n?8W?*1oZ2a)Q
zon?G~b96LUx5*6yduB=xXs3UVI8;bRxw4O%5WN!9{ECO=JmyJU#1%h6l4Z_6!#<hl
z@yTXs1R$N&#gZi-OaIVN+oiJ2Q(5CDigs_b@dv(t&uKa)^txJ@*eIaG67y7jbF<@0
z4JiQ?KLfhu$C7&BTcE4&{gGo#Hf3*Xdz119G=W!SqxPWi>*ej&;?SGzOoSS+U~*yt
zV3acy6q5Spoe2`=LI&EHrd8<WqAIw;-XS0S`aeG(qO=(n7TuAw8lbaz`{qsId}fJW
zTU6Q8J{IIP8s8Y|*Ow$tpo=2(Z;Kbm1lf^w6Ood3b;asd=(nLd3Eie(Zz_RD`0T3Q
z(S-p>r~(W)Z*2}+98OK>3+|F-*s-75xMDM$Z%D}e*yz^b-dcfJNA{wYJuO}dbfotr
zC5hu7WMyQi7Z@XLDt6V4pa$%^3^(v7j=u`pdeJ%w?Sola7yIq0kg0bUSI?tGWV>da
zeR>IV`3fOBs-S2frlgd1No6Uy%lZI{L`4F@z3ZHe4)tv2$_4fQ;sI{1XDg4k9UJQ%
z*VsF+JG%yQv|rE7c$Si5wehdvkyRY-FExqUb4rMso5{~^eZjtX{{}O&v@*<dDAmd8
zOz12VlarT*3S_zFtn~J_R&-(&;;>DTTKSrL6Ql~!T+hk5cj-kD^h{$<gL;U%Z39mV
zni=MHcPpG@t2o%mnq}>oY9k5K7%DJH)>Bi9$iBXKqEGI!Kke=X8rK__5>)9Mn@<~U
zv3QV?kqK^nAz+w&v$;(Ct%m^?otCDIJ<$7UUnZUQ!-pi??|s(OyuvWBPZN<)&a)(m
zRb|h=B-MzikQLYnde%MP3{TyiU=yc#ReMAqv*_-3?h1*G%@GIR@O?rWSJW2NV)j6c
z=-i&jC>XiCTTrq8JZ;V4vCdhI#J;+VF3<X}BK`i1N=xGv0w`85U*G8(QD|vyt+(G%
zEihKBf}zDcM&Zm&wTC-dhwN&a6=O-A9ho*rA|2AQ{+8C(ByB+P;@QL0^k+mqk6)QG
zLuzr@`zVYSS<rL8RPs4#_YQ%2NIW|EH?I($Be=CiJ)rbaS=eeva>LyneVn-L8-dhC
zr**lrF&<W4=ibr|OvAdPp7)bEJOw7Bx9r^jTCqF`KCu$H<S6!*P2G^Bv&Aw}NkL(K
zy~Nm_bReBt4e(f-VKeLs^x(;j^1TKT1%)6g>bXVH_-XMC0f(Qa^3-)6{Ku<y`&rZ`
zFJVBH*PA!z*>&m<_IFbyTvBC7V)qI|q|D9DA@+pG4dWSmUU*AOhVy4A^f5f#&_z{m
zNUPT97I*R=RtCi?J%%K=Fv}|Sp5@unU_9Z###chw`%Vo3bh&a%yRQZJ+?e7;y*n|!
z70()Ud(EwGT9ENv`NoER^9h<JVcJ@0@`q)?!!^Ny%ovxc0svJ%ep~>&j8iT8hBaAD
z%UIHz*Vp}MF))7ZoJ(BOI$LEcz&~EI?t0(r70qbtZbgclwGc<N?QP<C#}Pda`?{T-
zosQjXV#qq8$e5RWBhKF0xjgRfRH$Da&X@<5qcl#NMca)_%!g1RzJB@A2^z#IajV>f
zgalLb`}Q67MUy^!DWn<XPxkKO=2h}`R$VKR>IxenmFOgVhiLWiGmiA=jA&|Z-UE=J
z)cVJxdy1T#oB%NK3zWpgU8ZZcOze16c6hLhjdy-|E&4Em_4F$6(vQ?Ge7*CrMA?>@
zv`jf+fssNa(kCKn^$vl6j^$>F&3LC64X}J7EiStSE)Kgt3T78NveT8a9%|jDINr*!
z9BmGfCr523@h5u;h;+8@G;@zSt`X*G0O7%A?8Ge-^SY=SMw?!^o_}RdJV2ldXG{ub
zwpW6or3kRy<ix}pfMxIAZO0W(JDd>{JSVtDQmAT}e>&RkJ6WT>Bc)_os78R&T!%of
zdVe}~$+yRiH|-I0q_3;lp7mdEj6!NWfAI5aJR3(9pw)!u&WTrviikk-f{KPkqPjSL
z;;eMmjd5Uv8geaX9}H~0o#)Nhp<klcD|?u!CP6aQX=WeF_mKv+EL?(CLiIZOO;py3
zYnDXpFuS3mo$wV**OT8+V?TM01R+I@3N(LDZ@Rd9<;CvgnCQP|Mmf7&w8fXDoB9mm
z*IxZHfd*%QwZ><^1SdEO<$l=+NRY7WUi>5B{@<i8RM!2!I9(vrd>Dww=Yd>73;+9l
zSciZA{{0w^S{NxS$<1ALLhM}QI5Z?~e-uM3JbzpLDs{rqUH8LXTZcoT3QKja4<sY&
zql4%|E-$|eW}rX9&A)7*o+63m!GX%GXyFhbj4gf)eo9J8%F}P_JbbJ06YYPV7x<@u
zp7o2D0VZoVMRz?o)#CC9E1$$bq`mll$SEAdqe<q1)j)m+{CU0NlCJb&0u24i|2XR(
zozbCL|4Sq29uTf|Q2ZU{)c@@_!H$uUs5$qmX#}VmDhgExe)XZ`+d9{yAm@bo(=s5Z
zWAx5j)faOu<2~n4rIxEcoW`YnaFG1s#kNlGtKACF8zT^7XizU+ble(${c-3#svv}a
z%Lw>3fnI9_qa^pypU&JqE-0U&XxWHgRcP^X6^igU6*QwjcvJ#9wnF8~JkRwCRi46s
zK#99d2IrraisDxxHhv{6%6S^l0xT$tw@@QgB_}7Zs;*WX*E_F68$u4H;Uzb?8AsIj
zm?3${D-JQEifn|CIPh+0(Ww7J;rogW*0`ub8gb?vRNj@SJF9TFJb{=YI4<IQv7EWZ
zKaErkHrbx*l3yV2$~42Q*y+hKsKmbLcwae5Ch}hJR8xqgoO<>q+%NTYwiYXZuR(RB
z_25CLEAWW;<UwI!JCzs&IIPJASNQq)f%V|#wt)g4h|l|4cjdqQgV8xRCRA+oW#>@;
zFKXMc?<SsZAcVv&SAbNj3iaEla{bg>IoY|W;DVS;_L;lLC1<f(&4bktO@If11ORy2
z#Ca`zVd2?X>g1W9KYs?&%dXZmM?3ErcAcmE2UR8MiZR=ZwRGq*;v1vg7i#TYt)Qsb
zVF0S83N7fUF6{<0s}k{PPl8xYs4{N4*q=r$Ag8EEB?ot%2-)9nP`J3u#AN@@WhTAu
zN3g~PW!7R$@_o7DNa!L83vbfV)r^}aBqjo!msMOGroMMk{TQGDp7sVid+$dT8eaR=
z!|$QTAWf$|!0rr8OdqqdNYS9ym^yF24)7Z&jx;Nr)fa~b2Om9n5CAw36&1@nbT%JG
z<SkC83!Tb@SEOR-DUP`y6?3zMlDw5}d08^OigQ!ZK><oRH&*Y!!l%Sd^ESrmBv86(
zY;tjOGHN6bkW~MR$r>brLb%-1(^E;qj*f@tLv2Fy;edWL<Cn#A<?O2<B0F{Jl$N$O
zl(VaAYlh0>=0BIsB7@^s?k|2;_<8DXmhq;F+cP3$36ca!={q{(+xZ--UCTM{XZ@zY
zgaH#D5*+M9!R@2Ir`gcd#0M&eJ9jYl+fs@E{W;=fZ(jKi0O+hpWt@oD)oa&4pf>ZV
z59pox-6~wxdM8bXADnZ$8-1EyEK&R{+AG}=dXw$%Xx-}DHrHpn6k?M?lP)YRK6^*W
z*E_Rg$XFfy0W}v?x8TXdF<MvK1lr2{f$l4UiwFJMzCZeN?qFs|qV!Nfwop+^2SZ~W
zS~~-zMQbSAB(Rfe70v?Oz(j8MC}{#C)M}b&L)WifrT?3*f=%zvF*E5aXk5q<4H&cU
zQvveLPyG*gggD5&oO%s=MLyf+G6QSj0@K2L<;ts8h@+et_%$_$?~x@o7J*m0BiMC4
z7s@D~pQu|vu{-NooN84Szcd0S_V&EoMN3d(l!)4`7alXi)n4-aqhVp>MxE*S#^$9Z
zd2ApeFwy{QCfuF1e5-0^=XAxp*RmkPbSLjpgR)$N(GtL)2=%ww+1JgKgq{Sw_4M4?
zTWhPqc}4`FaZ`(SosV3kMq88gh|^^nn)i=wPDYoh(SH!xsD4dgv9`Cp*4^CLIFW<{
z>yBdNv?R+Mw{ttJB&QG^-Eu!wl2u3tCK^5)nDHOP3f|-1xwt&w`!_s`sia@#5YPDU
zs)S9wBUM80u`1!EhE6upbU#3Raj3VqR@#l<os&ei#gOYX9o8L(a-DBi>Pq-1BAnLa
z>2L>TPhPba<$)-GBf(@&nM(HH1Z&xPXN>R*1|}5$bkFma&Eka$tc~Sr0^Im>@iDeV
zjLsaj(*F6<FOYPOJfVWyiZPUKWxoiuaM;1XqqQ#n=S>tqhQz`pNk~dsCFAB0W<Jno
zN|Bz<<OB5p`}0AL>Wx<B3YDJ0!K)xs=(VQwO8(A4A@(7D&#`9n>dg`4KxK(BWQWtT
z=Ex-JaJ*Ro3IP#$cRE}~{wE#UIz%R{Ven{OXx8$2Ai!-UC1%~1PbGb_m)YKR<JLUK
z{AE@C0g|G{)(PyLcuPVKZtk_|MU+Tl{Lqbl>3qo@Uw>wlPJ)Bp`rkSUxe>DO)AQrl
zNqdqH9Qz<ASn@YmG2yZUAJo98bb3sw3UK+eBm$zMD?j6AS;m{bK%nGO)9jf}@|mq)
z4C{?&{8B73+V^o2wX8gqfzSQt7nz)61n(69d<!IQG{4;{kQU+GCP{%B_wQG-99(R7
zS%img!XXUE)WEU=Y<AQLQH@2<A1JNE^F6>+S0K79i1|_}Qj#C9u**ex=klFRHe{st
zKeQG%l4Q?7uEP`PLt3;6Kta0)J(8NH=IG#{{dm<&i25I@oI$u{fk;+6dw9$VCF)#z
zckiA1#1D}!^{S8;PmPRVGk0}%{#-;#IzZo9_b}tp`|$8|ys0N$_8fG|1v9&08@HYg
zikx27Q6-|3W<I*h!NEb0{hg%|y?Mb0)DJIlNrC9d^*Y2phUTml6o{m+>?_@fGxVgQ
zQEiRnL&XOV4@~=+h=_>XTy_w@=t5@=dZW44Yp4KaTsy8QELKzxaCutVITjyF8?LKY
zuhvVp-Bv#D%q>GDmNb+M`}vY<)I1ao5=9)0jBh&`Q{A?<wixA;9GAafUv`zxd^}d^
zM$4z+xFQljeea#YRTLu$8=7vb(hcK=UbDEA6m1Wu`L}u?4fc08OK?9M^D>Kdy&(1~
z&r(^+OHvPVH7*e8;P|xVcEEsieXZP9e=Hi2tBewG@HlHD4@1yD^PP9zg8=;$6c@q9
zO6;T6mUG>yRaKkUdjv&@l?iYVh*;rv0Bs3x;amW~P1P|c;Q2*ZCv?A<CaZGstx8bA
zZJdaj;5CXcxqoqkB)8xxfo#sq)A6~ppYcG*jwT~(5$VnIkW8$g-<|c<Mos9YlL@K}
z)Uq}vN#!D%xJtg+x^OxiQ~R*_XU#c{H;ZdX9N9jy*5XM}BX6VG6+7J6VBUFDXz#)N
z0+O?9SC^W;w$CTs2;-F+jBTxEKg>?%>@5H?0Yi4^Q@7!{-~-Eku-)cDk_jrb)%+_;
z$11d%vYX##Go|*`ORR~Bh`!d=*4ETa0neqNfJ2IsNa*V5+!Yh^CA*;q3GALGnYA3A
z$OHb3M|pbqB_Nk**f`i-@*4A|;119QFth5iDL07qJ<i!@@>zVBGBYy+`g&>^C{w$&
z?}|!Fd0vDcg)C>een3wd927)LN4Me~WlS)B+b3uqI%Po5-ue2<{#6F(v#!($9^{CH
zyVu<Re1ZQuRwuJ-e}#(+V5&w&a{w8!fcl`X;^2Mn=Vg{h`6;=%C<zUq>_^;)=*5Kq
z`eL=w9Br|?cQG^4;p7~goGU$)HHr40jgdyf#R!@&q>n8N9{0Zw39*^$W;FX$3%n(t
zdS89)4m`#p%RqKE<boz*Xy0Vq*b$b4Ze5KV5OQ|o{_OF&p7c83i^<JA#=|$qIi)L*
zN&7&>`~dbw(`EnDOq?%`YGG7lq;wgJdU3u^!#Sf)x15j%#b(#q2nqO?U2la|+A}0e
zV-rZZS>jS}k+-k%JzoUT(FqY0ks=?pXdZc&qKDw(t>%`s={EU5P?QFm2wu)?tS#6*
z<3!xAYwsHbRZ_=%29%i*d^WAK#n^rD2+S%Hm3<8odpzt7MSZMC)V!9KR=x5s%|ZlK
z3Q1SK%ktQlOt~wQ^(2`~M=}a}7BfP{d$ZjiQ&Y#UP^R4q6C(38>0){HU}obB2FP8}
zamsN`0A`#sMK%~8>}>-(bN1|6{-Tr4fdhu0*^62+uKLw#v4Yy5xPyX~zq%#&Nys^-
zMX9}Ei#D=?5j}_LNShQHc7^r#W`Avu@as>|=^r#U^YHLMw+bZ(v4*w8I91|4bVEg6
z*(G_V>W-!ommmE6sU>g99i;wio|FyMOKs(>ZblyQFiTv2@i41IHcHcIh9}MBg;f&w
zRwdUJAHxU|hEUL4c6PR0yeN-}`g`E+*B|z=6jEG-hzepkP7V$x<!owB&i7rZmyq4V
zhDne3Wp~+&k;Ng;W?x!b=;zFjxiR_~qhWeQ!4^+DoqU6ftJm*gHv~H*Ge%MC#kavB
zAr|s(6}ICb+G~bQgWs22wq6Wj&9k@EwBgs4ywv(YTxpEtJ@w}8+q0tf8|juS{6Csz
zCY3h>nD^XLxA3|H38auJ3%s_EPbH`#gmLvC$kB+t>o0e50FnU(p^9B}3R2(WEPQ`W
zNu$VIceLE;!-o%x!ES0<si|+@y_1rZjQ3BS{2kkyMwnGUpBLEsfQ}7t%(J1-(wP6`
z+@F&E-XZ^DjL@OX_27mK#RM6On53<%{M{`dE7pN3LHQV^ji7IET6aFLUu(iNH#Y}J
zt$<Gb82}}YSnih=)2%HZZqQ%4<hB3{4B{jhXfEwB2ZQ%OAz@t9=YoowS}ACc#sPYl
zmX-DO^lWTxbq1l}d(dLVo%c+z4R|pTlGY5}Lqq+OaIWV8>g<cP*g%imZnJ`3NJK<r
zeIlaM79v5_OI!*HikBg|EAa45(Jt5xhIG`KDRF;Vt`WACj|tg%wZ371H6MFCy%gEr
ziIO4EZQQ$8Y&Q97t^|vO77-(O2K`7emZ)zAI+>Ky?S0S;Iux2uHPZO<-=5zCsPci+
zxl4Yn2t<skJ4c_>KPjNm;D@&!qq!jxD6-KG9#sPjKH|70-P8A;T3R20Xs3a1fIjYD
zOb{jxf*QGl&~)@0{SkUks9+^39`BRcWbM0m@0OQMyH=#VQAF0SW)!=hAsiFwlZt6c
zvBcAO-)7W_o749K&*hiHwVBvh2v?yKMW?q;ix=Fg6dj<QnGF^2E)W6;N#~daMd=zL
zC!sMJH#Ri^O9AqUXg|OEpzG7rWJT}IRBvJf$-}j4PeCC+p-1z~<hL?;*E1WG$^QQ8
z>eYPSkm4CxSU@loi!CiF3AK-gmDQ)2a)?Ck?(X2m0cGUg-kzuDsqp~pS>Egh|4?!?
z1oc;;OpJ1j&J2RbDuI!aPBZPXk|8Y2D!E@x)v@F-nf?{KtuOzB*XB#5y^p?bTV7Q4
z3ZEiVqs$)QZ&2gGMCCjMVGG0}S`OKWn;qTV>syn)6rF88#gr<?oGFGm<uaw8u@l0J
z!YuD>xokxB_zZbZ13b<3;Zaeo(u)p9!4QdaC7C3quI}qszeKP*l$EJ}CZrv#xB9I;
zQ&CYFUa;07`_IYzsvkr9UZ-fShE(%!!eUI9>sNO^fBIx5Pwo5I^IS}wZ0L12?~aa+
z-{DS|bhK7OSWPQDT<bz&>f>>AfvWQt=nqH{{UTagalAc3S=asMUE4sYfpJr$I8Q2^
ztHspmHdK6AMo_K*7n}7-JqB}T1!yT;5+<NibxDP_eAJnc;_{6v?#5!lIi_w@9cIDv
z1+g*xYIyO#-Bj!6RscnsYsQFjQ^R(|PEfrV<3%w5jI-oMQwXaCJh?}tGw7^73}W3A
z^Rm4+Jl~r^V}jBsZG{a&mR85$lM{Uyc8Y|horbqHw|prs##ROIg+>i0)Q6m${;pl4
zW7t&ge>;1X%@t)(m_X<Pg=5Hv4@Z(_b943qUn+q#kfvI8Pp<tZYh8+kg|(3OS8N+9
zv0<g``4inVbaiaR>Xi$Hd}nSp?UZ}DPw1Md2dw}G3aNx{!}`Y{r`30~w!gMrdyV(A
zKU!nZ?}O$|MdbrZ>kJjco!6(Wrmc)9H@1G4yzP?!-+}DSPs7e@3z&}PP&OJiHh+%c
zdVd-(FR#s|(KZ%c9WQOu%aH?Obt=7^>O@4WUQbXsBB;W;DRf<fgGv6304Usq8zm@7
zumsz?#>RUOOvHRH7#<UR`c%t!-+0H4cw1rKJX{b|M-x@sf+eBg*?{?2C0e;pJnx#T
z{&5sIv3Jkbw$K@QvmF<u`+dM4XiN&i*sE6`WQ>snO?@SfL}XJ!)v5$AMUAh%8#hY(
zoB-CN&nBa-N@pKXqK;zdOMQqq0^#1Tudkz+r!?aA3r820ob4SP+yP|#)$7+bQi9^#
zoA-kW3o6l$Ogfs3OiT&h!k^ruFhDOHIH6HYdCSoj>OQ7HYUIaQ3-KbEPw0;cQOt4a
zN-ag6Udw}wnCYVtgh~_u6xFBcf*d!kFUId|L2on<n*T-l?ll6+^BRvV*J}P@51Ks=
z7(HY?uOI={1Bfl{4VP$SP$kwB_t7`7j}XGW7TCm-lanE=ni`s#Sv#(EmJ1Qb`(XAe
z5)`ICP-KLsbc{@+Gr<%`<FlYqhNe`Yn*lOhM+4*m(ud;>mNB2^W~q&@5|(#oc3Dn&
zh9uH=;xpWriEkF&mR8S1^rKjDVTn4?*rgH>aFRGaK6PY?61v}+V=;I14Us@&nLQ~q
zR|K5cH3k!u`1CbW#cYK)aS&+esBfd(h_apzv){kc*`eX!0h4`fFMPn1Nb!Q=30ivr
zB$_ipe=So);XXgY>FB!0-_!@DyZ!Z_V^E)#|J$z~VU~RNjfrH~&Mk6WzWnZsS#1G3
z-;c#Jl$!QwU8}2I>L-XiUX$G+^cFky&grmV?t$rafWym|WEhmS>JqhI&1&bp-Vv&n
z@EhO|0n3g~1wY&ah5{~gG~Suyi|R<DtJNnK-8SL#@IObL&LDS?(<3g+dBVdc=v}u@
z5|u1Q@Lo*3hF`LEUtKqI@q8EP^U8Gjc{A?RN}qpvA>%&Hi{d{+FH}4){76fiH%jh@
zeGiLgYKpyy%IlSqQMM%MnUs$z##Am_tdv&vZ;atwB$<b{h1IL;{G9A5xG<wfemCK_
zS83eK67YW5ioTe9_kn<{V&_B7AqJ<Al8nNsRo-{=56R~>mQskmh1c~xx5TGPKN=RC
zYTCt0d8U42Y>XMi37Gt-A9QK&aDL_<^wp*`%h=t$JMv_2hg2Q?{6KE{$4QG$hfdyb
zg;>3oN1O+FrvSmT>ArYvp%ZB-B|nVSRsWUp>|C}mc%^>X`|c@_oh8?8<DGmT;8Rfd
zrX--a&~j>B@Vm8g@IgYJ1o4E}=+Ze>aWbO|1Ko)wv!TT`RiCB^C`n4^Pau|A{~AqV
zZbts(Kn?z!mO@b1^n200$VgE#_5ewr!}$}FyQA|dtox}uLYHf+w8q0Wmncb4@Wz<t
z(bj_NFVIbEdcUu@elYJ#SvB7h!W)Hj3Gb#8l9S2WFOBDU@+>5DZ<p^~mS9%x#f<Cc
zux&~|Bs;#8A?xanE4j7rl{0HoyRc-<v4Sg)a2-7|+?u6dchBeFG7+7-PQ#lvS!`S#
zz*`<-J=3O+P9(><6Xo;$a6>C3bhNzx32g|~;c%7Dcbf`r&ZKOH`poR>)n^Uy_Crp0
zh_0UPv%)}ZL3ldaS?E|bwdlW0hR2@Vz~8^d+*eSrT$vE*nFGlO#KXUKBs$h0r@Xv8
zu&<fC%}4PRHNaoK&imT0{$)2!_`T`=VK)T=qJ|#jQ*}M^sR{=hgDA-s>`p^NLp?W1
zQPv`;`+seaQ=XRE5Qqlb+hbm#d}Jwq&dCrbecg6>3|i_i%=x2$@YhNIiZbAb@DxQ$
zLOtJE%J&K&-sqa6lQkL!4KP$R(BmV9;06x#*1or_tgJu+&dSPCa@wb`x@hV~ASJi=
z2%<#xt7EHV&=e?WexgX4e}qep*;mnwG3&x^mTTmVCP7pD6{TDV0T{;Cd+rfiZGhR+
zhztF!C|FLrcXDHOww(U&?m`g?mIklR5Yz$x(-#Q7zXjL-;R}Rq_#glOcV8eZ#{in{
zfAs~*o&qZu_yVn%^fy;}HEIJxqb9uAFbJnU9Ly<I#C->)F9Q>(Ch3~MBl<GY1m?{-
zF`5=#u-)Hq-H8;?Td?n-tbx6k8;%JZM>f63mj%0kk-@uoD<TY<hRctCSp#3@5d1%W
zf5eM+NvwUPCe-cio>Y2TT8cB|VjFz3@87=pMFzjpS|UVAtY+!oRuWk1kUNcv2(RR#
zoHJ4Lpc;_}X+=Q5gz3%SZjlz2;L|`EQ{B*$vb3~3Hp1K$Q&BE_q5U6~IKya;9uS8Y
z?)XN%fB(sLWda0zO-^8{f>tFUAYe<?{u$95GpX61sSRIp6Nh{jTTkZvm%@9ZoJ4=J
zY;z<Y%}|*<g6j6IgyblD&pF`12*2Q|)XQkpjL^dluDBeGy&T{p6@Q%Djy;YE5`p!F
zp!7uzSkSpNKi_h=&}>0#*6#=*Nd+tzq_*<%YV>bV=;jOU+`K#j@M?j~hfXs1ejwGq
zi}`O(<1b0Sm1mXxB;VNIna>g-l?9KVv(b|$Pt3FVKU#@Z@ACj8iNa_YZ$u^f3LX@W
zciNe2+URRT-PxUhCR;M*@2&cp!+JqEem*%7&qeRv|F{Ens8h+()6+LJ2l6cY%N)45
zQ*XBbdRRX))S+kEJW}RRBw=4;TK1)vGc6EyhM$s}ozE}Tsu&m@1wR3t!a%}yJg`e0
zqS9tfA5Z|yjceB=7q7L}0^f%}`wWQ44`H-5g$*<m1*Z+6g;1z49Y^QJ(sW$G8i2Zl
z*dhAJL#j+wDS3{NkOzr)Oq2iqcJY9F>{Rhd!Yj)XKL6weSTgMzs=Rs&7p98&Zi+gd
zxOY!{Q6yLUH`wxwTaDY;fA_DR!h1tL&(FA*5`S~rV}eIWl>ZDj0LK8n-l0&jH9S+j
z@XYV!f+hOjhT#AvLke<op9?&<v&gSqyEcmbFPZpEkx%QiI~MK(d3hCvGqh^`HPV-^
zY^ld-i2wFAif^|h{P8ska&Diqp-ukwB!iE9vF)TJcR<3h!dUqtlc(jR|4Y)PVzihz
zCi*daXz@Wi2Tf;6dU|}BHSWKx1J#%N{HZkxj3dYGeFK@9D2JVHGT`FcfUK1c1-N`|
z1i(c%Yb4|(F7Ay_sxg9}>g&ag00wy(zWejX4X2xBG_Q;J==Wmv?d*8CiPvBIG4EmV
z*<1`=WtCV_=SCREqeg)e_!$}TI{ak%kqhNF58{ttpR|R|Y7nih-9r6eMg$?05kZ-E
znRL2FX%(y$R~$?TbY21AP35>OoR+0l6hKS#HW|V?3hoXF3~X>-pONc{eX`QMC20s<
zF5S2|>&eB6L+9;rCSLQ<5(}8!J8{>UnV&C>l&vQK-Tv9ACk@<$MXY^RxMjD_(##9W
z+k&YBZ?odM(`p0#Uu&2f;mVy4F)Tm7{a~=aUp(~(=HKRVhuhip^-NJFG>0iE24CNt
zg=U_U(+U^@%cy~x&T*v8C@7+QJUuUqTy|z+Ed9R)?dRs_adB~HW0y+TTA{HAE<=c_
zJ??0_G0UJU(iYXyx@=eo%rFTl>C$M0=HfN%Yb5qY;Kt%$!j~bq<Z$ik)f5?h3CtUN
z$KK83@F^Eexcmy>gU(ia=+zFsxDfvBW{&+NfUikfZckk_7$l(JYWBM&X9b4NnCLEg
zN#HQ|@XRAa*56xNj1<3~1zF3>mrGC5Ts#MrP?4=u>FAJ?s6%2caUIcb7e9wMHu3c>
zX!<cgiO6AaA8;d-s=jpZP#dHJz~};+EwR_Qr26R4H=}H1ti-=8ffPH*rh|Dzd)F0U
z7}x&L`MX!Yd-@E1!6*4b!t&)u-Ml9`wxjH*WWgvnIiZi50w?EGi00?~{O+EfebBu%
zw6>C<t$s5wF%h&|{RSSghE>4i!)s@h9m>Ag&^So2o|amQQ!TCgi3TVMBImywIJM2j
z#hmUzcTKLI^)9(?>vg&PurZiTH{v8&m#gmp{vWNaof#OI$NhFNF6$*OCbbhQax1JJ
z-W&i*L}@*4^^RmBN$xoY;OgH^OzDB$J4G)3!s$AvO{9{X+)CrMELwW{u25jox1jS2
z8bkT`$ZotU1u5Xu-j8ynaYg@3GmhjB3nRd=mON#^uV81l4Q;nX)fLcTp9Jzgqzt{|
zDWtJyv0`nFjgLxga|&g}`>4M2Xh8<D^s`KnlaqrwIyuP{xcW(de{4`f->(5gZD%$a
z(1$V*elnc&rR4hwTvnc`Re1D9ahG{GHE<CEgLw>wT?Zm1p`A*v)RXws!Ob*YoR@(!
zQfNk_0<RKbW~yuhyP?BIkCI*Ib)alr7INyW7y2)u_qT39`w7)UOO!x36SyzgygTGd
zha=duYk@&4a^AN`*?!j2v&tvZd8VhP7{BPm))6aV4Z~Ya7N&S9Eg(G^h7e{_914IT
z>(x^_hC6m!g}w1+qYDcQfFGzATN;A6t~-LmFkq$?Ew14h(+Xgv%>hq+wUs8(cn_HO
z&KZr5k2_MyMBkDoHafLY>rYZg)9wqeI=W3D(D!4sB3fe;a0la|&p)8XaoL~OoNfuH
zFD2Plk*P69+K2ZSTcwX5ROOvQnN@*WOT7j9!?Vq*%W$;GCiX$%QX++%q9UhmBT@PE
zH9``SpFf98@|4c&8lX9XmrM(j%QMLxjHrO4q&RQPDHhp*aU)GkRP^eX#l@O08kuXH
z@qc3+_|4=o9ggqv$o^sSMKr6YkP-c^{OgNs0s`vF>nyo1m2z(qfYR=jbsmq`<XHv+
z(287o8#TWbd;&#i++WR$@SG~%;QCVFX>L;jwzq#dEGg4b4og;KTLce{FJezZNSyms
zH=cAzh=#pkdyFuLAv-&Je`YgRn84oP#Q5urB%)qqv)!e`M1uFHk_rt94YLb3h5*sU
z<F>*2F6&HeP@JdqYuNIoks~7`t-tJ)t$*1m?`dasY-Cn~K=byaf%aAmvMF&G`Y}-1
zZb7MU)wP7BGOf=O*@!YA7B%qFKfl9w^_BXfb@6nRLu=s%*APnLY84P0$GR+tMvKG*
zc$z(7^V#}<H2`$EepQ6OXl2GL92L<zmyiZn=JIuxIyT3~yEyD4IIj#tR^Jz8B0*aF
zGegE)qb@f#Kq}>=qZIc%>uPl>`|z3wPvn5Qv$aye$Q7d5S_xGYu~8Dac=2#cOj)@f
z9^;4t78%fn*r#8c!9bTQUP)+ZZvK{ZYsereK)2rS(qEoU=~2;#?%T-O)m8Jqn>GzT
zFruLt^n7-3;txD0<q_Jh3~GC^>c-fIRPj*fL^-=+r+G;Ppj1*=XkA>*D}lvi0}ia(
zhd}DXY*#WxrmRDCb@lA~Jy-(|+^y*H5MvNtx2*wHy;66vudlC565qaMWwnX5i)ed)
z$)ydg@!9UQ;9<kX&|52C39Ag)Xd=VFka>`lytVorSiSYJzx*Wmu<anrPyKe3D85?F
zK6aZzrcJejO#5U!OXVXZVNuXEUu2v#E~!V`yMeXMKO-oA28isc%rMYpeS=k{TLZPc
z&v`a2s2HFgaoHUjr2=iQH7qpBXX?J1*MYLV49&jry|q(sT1Ft|0#N8RD=a4=2=HLy
z*3;Lgr=#=tqvt&H$9c$~h{>^G_^4uQ!iz)x{dts=xy+z^cd-Nlokza-`bBTg?{Hnc
z=1}3l@ZhfB=;0DefAMVo1!;nZOveD^dvCZ}_ziuT+qd1T$Lo*mEc2he&Q+3Pzcu%d
zj@DFEq*J?>kSfxzNC*V$h5uLPLbOA0m@-%9gwDs1j_IHyb}(W?=7U+(@5x?;mywj?
z(#=4N^EU(FnI<cge&L(H*o;IOSOn7upouRq2HO;AgcL%^g*wQb(uLThKl_PE`F7GA
zh7($Xs_7UF*6bg9Aj$|f+|O4`DSvW?Ys4ZbmdkiJ)ZZWab>qIRN_6ppvC7(wE0h1@
z3yWX~G6Lu6-BW1g=$#pw+LP=g%D#r<=m=Lo;Wn$@q8yub%jT$B)fhb8$@&;oYNT=X
zjVvgb!1M@rHSD1S1t5URu-$=|2A>fzF>zeee|@RTRL9)}<MCg4GG!Oiq!>-b@w*KG
z!~c~grFPBBN=qG~sDREL45N^3H#RmdZ~40HX^V=Uz-Na=heX=sL|ja1bkx>~g&wta
zT4n{;K3_}r@&*wbShyixzKWW^d2Q#$C~wQp(`XdT)@;dBKj{fNtsbw@pmCwkT2n+>
zK>sudwt@14ou^!j{W<W40QZN3U~Pm)Wy`2?!kyc(Xbzu(OAQou@TL#gQ<Jscgz+#Y
zGj-)}JS{Ci;5$NX0v+Wv>YWA^J9Ft)^SyEctgLPMtbOouj@g^6fAQ4***5Ty3~vT`
zq2740nEqIRD94~94r~@6fd%0y@wJENGgUv;JH79sTZluE7spF*&{iPBEaY3zU-Pk`
z!dUDCFg`!H_}5N@U4+80H(+IXyn2}5<$#}acH;~;nBY<*vg8JbhD<iio>-P`@~f`D
zbzbOaOX~{r4+nK*jJ=Ldf}!RwihA_ASyLbMarg6*l3s;dJ~P+E(q$;0%07S3&G)K+
zKxFu^5|4US=6Ng<7Kol?>uS@7j`Q6>8hNQV+waa>>!1L3)P~5&kmg$5cOv$<f})^R
z8JNK3n~?AgsQ!h3YLA-sE5(JMFLBqzho5M&S`p>V;2uaHHV@5vv3ymTVB<H-^HRe$
zC-O`*jfMO_uUc2s5xw1;iZ!!BQWCoHvrd}LrxWuQ7R*D^4c}=N=BqWW;Ntp4I`5LJ
zFV(X=q!eyaB&+C?u1Qq3zl0oC0iBdy;Ybduq2z?-ANroY!B*uX18uuSWE6$27wc+<
zJZ}3WY?S#QSwsGAORknB-m}f&N0vaXR4pYi4t-}$srmXfn~t45AZ$W39Tqe%Y9@-C
zI7AC&G;~<~V>G;K`ghLf7sF+r*=3RRY(=CTcoF7_4b&vc1L;$lEL4oFwfx@G-R*}1
zVpAHnyS!lU`epdjHThTjv<XfM>y-jbRCJNdf!CXWUZmi!fkZP(g>k&qkhI&nfn`Hd
z?*0>u>a%YH*PEN0gZ`nBVv#C=D)$X!A_4tI63uU_$-Q#N`%Dl;1mQTMB@8_uZYll4
z)LdEl9c$Y%f73euP%@>LmzRSM@Y1F6R=%a?wzk8u7X%;ai>F~BRJSImp-cs{d44C}
z4^<oV`PgH9(*^re>kHt;fM?+!Z>mX!mIS5InpKheymfh$_mhu(X${Nw{NaNje`X)F
z{?iGnZ`Nj$qdUz}C4_?5MYm7*zh%ZG?*C~he0WA_V%7phHt(Yyb3?cNK$Qv&82Fum
zVuiOpJ@3yJ_MYKG9doGxw9MOg?oj@RDUe77-XC>!z*v}tlN`Z{dJ7loEqDlz%Rm}J
z9hzojp*|L<X2gNeIKnCbSw!H-ZI#rV(ovX1ET2ZPNT9BUd0&MxGQFzhdVNYQ+8D5@
zzl@4!rl3AK{rXPt^KRPT7DIq=5jao&h`v$Az~yV8RY*GtQ}hyiQTKz5QKIo>ayT~v
zQAzbkRTU5ua3j79Gr~k@z$@qA&;9?Wx-Soh@_pMUMWtvF6<M;jpk3LsMMOkdhZvQm
zk!5U?p(siA>{}r*wk%o3mSjuT42?{beeB!V`CU(+?KnQ~_jr%@`2F?1{ZldXEcbKY
z*L_{*b)M%_%j&tL7=b~E=-)u+2tP98lyV+78&x?#V)8lyWgh&f@E-!Z)E`Q~adZgt
zpN?hlduIoP{Qg1c|4%;%oIyllIC7<Z0%piSY#3c@i<*XpZY0x)#BXJtozVD|_J9p7
zuq2gT_UTk`baVu^27tjZ;V?hS(zDt35dZw3j}ybI-pe+x;SX#;(AI2cA3TYD@7203
zdJmnDD+sVS>DE~cnGs+D3RQ69ICi(~gyw(vM5)VEHoz!x$~hND2mjG3mVvr#w-=r%
z>k0H1KO4+H&xcb1SKCCC*Xg&2;RlEq809OyJ3p>YRaSyv4i-ymV^eCX(7#U-*mq6;
z0}hcLJeC020e$P#_8&gm%9#GTQX?;ORS=Z-V7p8};qc?VP2}W(cQycLXvr=Q0MKw`
z^yul+2zgBJ>49sM`UN210A13bj*xG%<HnvDKtUkG`CCeuhTE10Ri;5v-5IGq@K%C!
ziG}lmE$Ejk*C*_<yhT+kAb6}y*m+8ciD7`g3*+Z>M)+Ec0Mk|}l~$pXeKMbISs#>X
z+)Hq}yA~Iz@e}nTG3W|w;lY3%kEE@(-Us<3^Yu@XudzmYdI%f##$0LddiF08@EC+R
zM3+E?rF-+Hm{FlELSVD$*1q5nA0_KS-2STWfOEOOaQzHq_etBdnn3D{T0H*FKLu@N
zm2R#}h13EN%6>(J?ymf<=3ar9n@=4#?nPi&?b_GGjd{p;8%Jfgo_c)YHvQDzd>N7H
zGq2r#P+Hs?*xa_t@dR<(o;Iu>P~*RcsPDXv=IlpO(~gubiBwcHZ1tfCwSiFm#OeyU
zegUCXdeGXg@Pr^312d^1$=7c$QP~fPS!vM`5qGHJx4VG*+y3?I;>34h&IQS{V2zY_
zox6>p7<0N?96!TM(2Bhf5c~T1-hv&>u0eUIEnMRJ4TFfQXT_tF=4XdzMylA8pJ*hU
zdyGg;wu#J2^2u&2SyZ1Lt(6e@QeO{}K>YNW>89bs+RstWF9VD>8?^8Wo`^m!?@P>i
zf2!R2sMf-%(+Wi*GxNs-5P9Iah0p&}W#C_z6*Y1BQRI%SE0p!<NDXcG<vG`RGygUP
zA+5ug5n;_1wp>jR<r%2&$k|c~;skac9`P3;At9_X^R1m(M&Y+D(fnPD<7BXvRrLT%
zwK~&1eE!_24{%Dm1wYJ_QXY>dg#`mA?@Aunvsj)hX>L7XTYasfpICE`#n+n(W+Vft
z)1OcCdHo(Ftp`o$|9*_Fnn4``pd#9?i@OL6)OwBV%FlbO%#V!R3tVe<sQ|mAz&z~^
zPg;JW_LKY{`7N?zVqX*omLQfV;C;Q11DgU-2V!3aT#f(98VLqz^K{xS5{CuPRKGDU
zITmc8K*xU%6q5<BVjF%46lh6LP7ar$pZ7Gj)L9%J#}ouNgsHUN0ZA;Ka^@olI>3O$
zO_g^&DEH2C&3Zk05oCeSQ{rkOfJ|gP3E<qP>%cCbeHJ_0FC-|a9lxPt;(QFN)#v&Y
zl^eiyNoR9Vw~ITzJ{t(gkE!YrCqn|<dl5Z1`p|i6kS%syyONC3jjW7otp9t6rke*)
z0_P5uOXb+qA~SokW@*{AXIpF_`x&?P?cES_*k6g*cnz_auYg6?#immf8~Vx<vcS{F
zfFr>TN6^C`?W<;$J7;V+YJY<p3~x3|eh!^a9A^5UUuWcM$#JaS?qNUYuYOh;FOW>|
zH>!)5r!duHzqX}ukmly*l!@qps68LHcSC>@PP^-%wLj)@JH_1uz8YyI)V6vYuBklo
z#gkjk3zPr8t`Qrv&o7Um4RXz&q~8jTj$ZEP*>r_W{bh=^wY93NHd<SIFK%;_HYs!Q
z`IzRst2)>ZsPc~P+_#HQb<0$Fg??1<7_YGz=Y{dw+M3WPHay#>*q$cLM&Hen<GK!H
zwD*z7YKuAF^s8Sm^g?Dgg1?P3GP55Q;kQNY*jw9oP2`a7qi4R#I~sZCTE{msEspTS
z<L{}&a9^{jNR(7waMQF&UG0*yih{HOZ%A-xN7`UIi6b{X!*1F6ZCrR@nSa78>TTZ)
zefiDEwbZDvFpCS+`^)wNZ$S%GIX*xC+J!QRnkX{iX<TZLtSA6Yq}vutG875=7D>&1
zwjUIFmB&;kE##RKxF4dJ<_%3IRg;R=e}xL$7^utVkVyXPGhCU)w^k?Q{lYZS{Cw#~
zPaP5&pfeP~zVJqg(3SL*;<>pFP@eel<Iu_C1m_Q1q^$1bnP!JhCPI$~9vr}`gQnyN
zc8ZOd<>^vc4_(E@pOmevBNbnSzlb@$^Wj{i^E;WVKc1hso+(f)gD0hsZL(79cLJ4L
z1bhGisl9ypvYT6p^h76zu1d^)ve%P}{6N~St~xJvX^O{WtZq)t_!%Z)&PeH!$n)ta
zf3hWurn6^{chiqYhlS(oRTOk2c*m3^%wA7D^YPk8QB|cfqT@#xPtG3+*>gRKbB7uw
z_$oCBJZJW-#Qr{d|I2X~=V#++R)wXw|H;?AGWS#9qWJf1x#|R?#2JiD;(XWYqNE`2
zhY=9KGURDGF|e-$s%{r)3-C$7$anf-VC?tqpcf>DobuNx0;)WdS3kJZsGR%zBBPYk
zW5HnIKJ+Uf8-Oj*+Q!C|J};bW(}BIdg!isb90x7^F?|3WbZ>wUIh+Wa(Rm38bqCN8
z^5%4k@ftPEh~Iq_$Lyd|?{+)!_`z1>=G#=GOwzx@UJQT{<g>y#VQBIdFI&O7%D8O~
zV)cjkhM#y4%;b?fQR2Vt{00MMSa5+MimxFjHYP@sfqXU4^AhubaqwA%X69AhDlZj*
ztuLRcd>p?@!Sq&$<^-TSXOF&z76jdY^GV35js|q>9(61WqX6=`Plft)-k`ey0~*C0
z{8+^pXp+8|5a4tMj;`vibk24(Bo<WWOv~y?kRST-!6zQh#rEo^$J%}ajUw;q6pX4b
zV7sBA`@)G0Pjx3C6X&Hzeu!w|j@#Wxu?~V$?%>5LN&-W#SA&B5z>6LYmZ8r3gO8?Q
zwo`zZW}X`rO;po6JYi3F>bmNy{8%qGIMoR7B5j85KR?&qPiOY(fhuLsVI2vd-!;sB
ziMkLK92ea#HkNcw1x4!92Y`YO4h?nt#rCTvJCT#=&E)_3!r1a~Vo`pfSi5BqqZfS@
z9QYm_DjTF`-!;iZ)kvAcbc|blJ9fW@-x%&~rb9EBANi<A9a3Mntj8?aX&Lw4QoS0(
zqd9}S-l9Tx&`jEb0z|sIU!t_ZG7-Efp<x>UfH`Dbr1Imo$ARltQ&R(Aw+Dc}-~eM4
z(59#Uz|PdC$bo0Uysqa)kLaPmj;6?7o6)X>;)<N$m*?c-el5OA2%tOlq1b}bf~TFe
zT5Ai!J1x%+!qbGVFQhYXNhFfH*P#nil9C7(zhF7kyWH#|U01wqk*4f=Vo_V%`HM^q
zCG@8%<>7L91b)JAY;|XJ%hcU@+pS*owMWLl1TZD{{d<yiSI_PIk`nT0*;GEpK1eNS
z!@Y+auFL(j;MZW{@+=OUMFZAvMuh&!3o!X1Q$@t!L-p{Gp~?I*GIDrmh^lfe$3n-X
zQz_STa|4oP4ghmFIKcD_iqY!01*lgL^nCNnU0HtI>=W^aKi_wuZcKDCEQ>k-y|*4b
zPzy&xz(ycE0x*TGTDmCk?t_{R(yq@-5FwY=o&Fq*c%Lg)z^<Q!<pPT)^GETCn{}l+
z647Z!Jr)`_a|oF3g3;{K$<VQn&^i~u$jyB@3zljT=cnM|g3(^x;gfAf=Ed_@rF+4O
zfRvF@73rPAEx}zJV|Z0e17ch-8+40w6Fz{lIRDnyeD^Xjn>)z~z^4@>tC2~-sRf8t
zUC$*w1iu<~Aq7*B+0~xo0qu5J?+_klOFKXjm@<azT}`+IT;*^`8B4Ka5edJF@`f(i
z!^#2Gy+d)FtcRiID)@Y~k4iV`PJx_skQXVYK=6XtEhF8lAQ@UziD8g`8My!EtwWZa
z5%TM`FL!7J_<L;CVuPY1g246bu2jR*<yS(#Ct*+SBuFFm9%&=Wd~VM*`yE+-P7kD$
z0=92g8=;pB^TVK=APKV&wgfwJp0eI>OCredrz*h-GfxH-WH#>#>idB=ntlp(>(*Tw
zVWO|`5qDf)KVwen5aRAYng*o>d^wT|xYdFaP`tvu#vFQVo|BLI8A1ohoqNDRh*O6|
zjy-(no!sbUST^Mf`0=)QsKAbyz`P(3RJdi_3syyf`fGn((hjt>lE$wU6F??-nJ~NR
zLuigUuTEGIzb`cRa|=75&7Xt$6bINsd*^<|S57n(rg&5DB-8KjH(6A7ookZNTL6*8
zkavtUC%u{1%nK~cjfZ`Ym_X^9ax?{S+cuYN9RWf+K7vRp8+G|Sl~6;~Bf(m1pg~>u
zg+Md}b&Zj?pnC>kXMbMNot$o#3a*i=9kQ5dYwJlME$S@*(dB{UW<)B%-7A}D&^1`x
z#g?x;n7QJX2F*1pfRT3tcYRBo=f%zq;<1zopnn>dxz0c<R-jRPLUUNy`%4JK?IowY
zHq7}LX<>p~p^?DWsB)Q&y|S)*mk(SgfICy@1jM}0wEbGrA@!fy+jY`EU(O`VmOeZD
zitxwN-C`b(J{x*yt&d6W;04>LT^X5~x)V3Q0en}svcCg3@kyNP3K`}L1j2?Ffj~Xs
zKWuj5MPzt*2@{hk%Y5Hf9tqd;dL%m+XD6pLb{Ptx7Dp7TD^HCQ4Lu>1J$(6aQwaTP
z7&lDlH56;U2h14FVN-KJAO%P?nsdHH$N_0Lmg{vzTrY2yCb^SL>rW0@SNTI%Rc#8^
z8QN$gd;(ml(zE;gZc<b6d+j&3&osy9#?qO6P!s4}U+JoJeo;v-u1+;JNKrl`P5H%b
zk>`%ne*e)`o;u`m>Dg-L_^sWjCP<;}S+`gGaba+v1mD*to0L<onC{<kNahO-tRw1N
z0|eVn<JND&!=171f&rBfYzo>Nh4lYNk+&XD+C1L(DGzXLUtZT@EQ3zKtQ~k17o@?(
zoxR)a<XX)}M-<pMrfYcW_Q$PySl?@E_fjmuD~MPlQ;S}pCB@Wprb1XKZuyKS^^r2G
zCfOGk&MgtS7Gum=-u*bG*W$hKG`*W<qsE{kVT#Z3C1-E=l3`6C&Z5wIY&dj}wvu(q
zeg2*mG?`N<Z8eVO9v&We{00EQh*b|OqHR)phfrzV-`GP>2%uqL$bi|=DzsxZ-{*K-
z!$xOp6W=$r5>!C#3Iu>kvxrHn2kQFjIySmj{!*P3x8ZmsN_fJ~3+9)FMMb9IAr3Yo
zuXnA2rYxIL|Mncxu63`TH|kx9z|1peJtuwlhbg{du@grdw`YY}uJ4V@WX!p<+qtMX
z=WSJ&Wy`T4x`or*=G-25YFyTuxBdJ6@W6Tj$tid;)|%&nNrqi_LBsfh(QPnK1Jjb(
zv4B-AX%P5<0Xu~30eKJ;8W!AZgQ$kJQ&g-@4w5}ynb^>*5q+j+s`2t;j*vvvbq>Sj
zTZLF$*;~I^MG#`BHiM0CIdpw1d8+dF(lH)%$&8irtnjIW_LyH-=<b&<UrJAZV1NyR
z#Gw1FW1z@hO{xND(&{_SVK4PZZcWJ!0<>bon;xFSBoc(IVR(A3eXxXY`meelerQ6A
zGv9sPltrgCJv9|^aw9e#9wmn|LSm9J&-05e7$4$~T@QWy%0-nDeA9=Kj?C+j8`vSL
z@L&F`Bb44Rn_e}_MhkpGyhw+B_K0KbONOHAt>>pAc3U*zuTUe-s2$-^+pYQboy*CN
z8hT#EU1j=rQAZSrIzG9!2W@ClIz<~HxlA{{NwHJm%zTWfOy*VU9@b&LkNWw&Fb~0Z
zG85JP_jWsqGftzy4%rlSIvM;|fCL6kYe3+ka4h+_J%rt|JO*`pb7LLAA2ComiHT*W
zrz37glRErBpNu?dpo2nXPmb<wO%pa0wZ=h-2WBXTB%SVAS`O9*aAt+XV2aXMH5=#u
z*xts(%luZyLywsm&>cJlyNZ_Q%2&|5*S<K!-xULNGdbEf3%jzJr&I@D<NP;uet15a
zgb$WAQ<8$PYYQ4&j|i_B<ojacV8@g>=Wn|9(e8+PkotmaIjxM>+C4svAM1~FHXx6I
zR_pusSP%zl4(~pv8|j`4s{n`w&Y)~WTpX~_82NpR==qCnT$!LjmjG|(z%H;l2H{wm
zoq308Msh7MestK&fT;e!LQ^xa`+{%uchI7N+VRCkdkv8&*;19z(RF}u06geVa8Bl&
zC~$6IE4xUyYuBXy+eyheklmxeI}(~i{Y30o#ZrwpK}`4*hDpn5P0{^m<bleu4zM;p
zvMFxpVz-)=JeiY5yWRse{gAQxw9d@d?5@cStq;}89O*_9@YG&*6(=Pr=#kX%(|woq
z^dv;v7Gv|H>aGOsZ>oA8XVUJlwq&nY{@~|h-NB-rdV2k!w^$k7x~VdE;R8WgE~1-O
zO7c7ZEesnL3?8#}*swh|ks4M03?Dx91!AFh)V@^9X*a^T%UaW{hb3WT$#-5!>;%5+
z7}oQ6<#$eE(Ryb{d<en#n64gvr(<@F;Z@2CWh!ROt=!qvV+*$!F;50t3N%JQiR<8D
zR>q`p=#LaF>*{UF+|-Qq^8PSRwNJtw!7`)#Wux^LU}_ApRn~g#c~!X3MCtH*ZFkCc
zHw{gRxs}Bm00z=VrRbd~F2BY@sMLh}yidN|^Qw4YoU4hi(bLLPLX6VI4e|!Sw3*Pj
z<Hh%?{YP%ecZ!?;9#UNZ?D`E27Kuf;qCi2{bR}dMgGxSng-oP>2mkrF=E`Ce(MgQ}
z{s%*i<M;-OsG-h&3PZ;wA>UMTT1g$#xtPsrjb?hssP4|YAu9`M;_0!5mz`01xH#?}
z|4$8P4Q9V@CSBJt8Ys4gv<z(I@ash5ZFapC_j%k@Ur2RAZQ#+**?UmRIrDj#=HlXs
zEx(+nmFf-zXLX3qG(IPrzcIG9q>L3!U`CaxLtUZc3zEe$?J$18o^p7RYz=b1D&NPY
z%IenUFze3CuVdXoVtyxi2-TW%T29XN@Pf<~7}%m&ZhXgkngrn{qH5f$b+gQBLbR@w
zZe2WT4@HWg&(XSYft`Q2-GzQA*?jtF>$XplYJrGx$RSXIr5Qf%FC0opd%FB&9xZ<2
zj{gd)vtQ+HLLo(zy8FgD_r0TbQ7i8SaOF4M%hHs!3*TZu;StJ#h4tgmTu(l8`=d{v
zVihGx@Vq@hsX8*S8)4ERXUTT~y_UnX#^yLlEEQU4@E3uK6(8wJ+i<K#+NGB&fSEX1
zGRzI*dvkM6cQdgQP}z~u$s_q`LC2y_6w9TydZ<WLm8-@nQdM@muD8cR+ZEPjqLhnf
zUJ*1kzhB|r*B^+5mG~We@nF3y0#;fMZ}>T51_r!@6BjW|8oJeM3hsH42lADZh^R{;
zLC4bWyZEm}Jr;PJhueYIsLBx}kG*g2R~CH^<1Xd7u?FcYkZde+zrouSB<^>!JrpT6
zDo7E^hHarEP5Wj)klsLr0zzsbVStuN5VKf#WHX69%qxfz3Mz(M_$1hspelj)&5*cK
z3*nUvrY0sP*RS)wE!Zds`Bh@UzA(tUEq;Ix{0q`c9}Cw?F@3u>a=^DEV4s4$<facl
z*&A&K4-DoMEyVW|)MfxMzK8cJfb^|l@D3C^i07Jg^<Ou*MZsMs@<4{N7!%~Zd6_50
zSZ~u-?&Av6#F?}K>lrEDut;Pt)6MI$5e)G+96;l!5%*Wtrzd)^@ThX>NL<~n9GC$<
zD-Az1f2-*_y1T7m{%W|Jn^gMFqs!N6-}9=Ws(DL!gbpTJM&jjKRu|it_Q5v~!Z*P*
z#S(h#(8AC*WxVsx7nL3ko-hqDWdwlohsUDHLhn?j-0q_WDH!sb-j=xykNHPFaKkEm
zSoQGvPeeTHs2_9`!GE?1<eVV3LR?26Y<BYp3+PC&s>Sb0@CKw61^TVn*s;mO)6$81
zL|-wh*{f1S_}F|qM3tXmx3i|l`t}V}|GKo~n7A7Eb@{Srh76~xET5q~N9eC$qPBtv
zOS;kXJ!5;g;gD4gzBP{T?pj1_-yky(gW(v+@T*dEeDr;%(N@&dc7Lb|A)l}W;bM4r
zIB;PK+_6~T>=Ojp{jY)Z3HbS}TsT57VZQgm#pCT$Y2(Y6t3V9A;PQI(7{nBSQsHed
zMU&&XV3A%rNmS?d0ACm=z+8u-?;^alv3hGDSO%g#-T&9N8d5?q@vsVBmI<KdkIdR`
z)q3GF5&9(_XqUibgqOWQxC7~H6Y5$^yEJDT^Y2v-_xEOdF3ZmbY6n<JTfy+PnOf*0
zwH37r2&u3OLV$v|s+j=p`PGe|g<`XtW~1AS&fuPbE_mM04WaK)9B{+s0i^C8VVwvY
z4eXDgMoS_96B;nTMUsnkqon&g%RdUtP_y)<)qyZANt47eH(-0CSAnM0>CNLl!e?cW
zf9KltC)X}9Q2#d~(oHO23Yx=RqSQAXbSCe&I`JL*_eD2N4e`-8)ByzWCIfc2B3Bk?
z3B$!8LQam0@nVpq`~1k;{VxzM-=8H_ci7t6L!0NR6$z`5@e&Y?WID`W?Lye9!AEaT
zLrce^<mbvfWZg|vK_OR~GG(2FvE}fu(bZ#Z)l>iXoJh#jq-1jbq8ia+8tOoq1{D_K
z-mQkwE&aMKTQ$_@r81U1LEZaCTaV<rII%^q6m4}!kM#yg>x#=;jI?cA@9lNap{ip^
z1iid+hrz34Jn(t<MW+!~MEe5+Sx8ApX=k|Q-%~A^=%KMbT7MP`JfOg@%Pgb7s7mSn
z@dHCM^kz7m)p1QGNkEN2<(?vQ8^2H6rJ<u$njA*V>G@YhG|6<$I_JL}9F3($K%oJ;
zx4;kwHM|Awd0ZUV;xX$0zf!0%g6@^yUKt$`yNP>1N~$R6UOV|XJvli!FHeUtP3kkS
zNY(tQI}=9m*E4G7cC`JcgA0vz01mTI#|H7%0;+g;@C~$os+4O{r>e#eAkYXEc51A8
zPk7U(QrT29*`!sAokOlIv_8U{iV9gdIZxOtm{_@A#>-);FVR-;m`Mx?9^gtdcg<*d
zv1B+w{Xx>|<t+9VVI^je8`bb(lYOpp=@hZ?b@E9Y#1rA|Hx)#pp#z87jW0%o=#u*7
zxnYiz`qvE&5Bt}EH))yGSE2k{nSaLcWIer(NN+YL5So%p9N$jPa!p}avx#cc@t|ym
z2$NzC_wLUwD*15f-DEh=eIO)i4sTk7-M2usDlK{&iY9118zMhL0n+zR@X@;Y7UO*4
zW8K$;<0+Vzr*@_r5&noYDF?K01c*K#MPOr8$W(Mil6^qyR_6AMFe5=!u&QGMI1tPn
zVg*KR%1Lp{M|9+^Ev=|eH*|D$Q{=M!D|q2{wfCt}Ky+Ulc%;#;l3w7mT4uh{BLuEA
zgwh7uHJ<N`LZp8m?jqL4&dw7d);c=6^&gE=x-^$6C2t)<<jWcYavKL@>466S>(mS8
zi#2PPm>sWvjxVdaRNct9-XcCC7ET}K-4wwseEia~BBRHK_|A==<WO&kp7I!S_@d{X
zaIOHH?1(V($|dt{CH!@}vX?VH4sxmoI=RXgMD+E15fAjFI>XaMV9vGlfd0LddPkAm
zX3RDnpN`#D@4;6QUig*ad?IvMNf^ty_Mx}_2g~ZPC#QX%VH;6G@O7KXafVY&v7$RP
zxi)y3mOU4ubS;9`<y>;~bR!S0P|hc0j85!bl@s|fU%Gasf-n7BA8ym(Q*0N-TZV%*
zDt5VM<|;)}QWCsw4*1t}u%?lj1c|CI!}RYKZ8@eueOf>Ss0T<Q;DCGIg;(vk@-wA|
zLl=x`&P&a6lW_A(?*(M-KP9N^G>NXhxSNCf)fZFQd`yIEquXlHb+PAL@+PmSV#3NM
zp25l9#lZ1w<;Cm{<P8bn+^Q=VQzI+VruHjV>5?DTnF&FeRf|CUS`JJjVYy{B@V%z^
z`dpGFD>6p(v?WHCHyuJnY)&V=-dxJ5b}?=J^UnRWxN=vM!ZfHC*5qOwRn~&asH0Sh
zhGQ8HGt(K?epISo;)9{I8D@y%Esk0UqGvGcNlR>Ok`>8M_;k+Cc3-c+XR?PpHJJFC
z2caDq7hk8GVa5w-M48FiGu8>?>Obhri?1@R*Sys7e7C0m^K7hcr1c+TK98&JFu%rC
zNIg#$(a&o)Z0fmb`RS1jkHqd~t%vrNCDEpFXdMZCfmAhg*wUTEZ27ApMEZ~cc$7CR
zT_+Ns;-~Ijs(F()3^OB51zUC2*TcA_LG3}(>`Wb7EyZAZu|=Qf#wm``Lj0{;;~{U+
zn3=*Gcao7CbBX)0Ny_>T6NtqwYRjRZj@{1$kZYaRS<BdbDbsT7@M}Uz;t^re-coS_
zb(+G#m8et~lcvM8_>LRbl)ZQLyTepk{i><yIZleBh3R_X*Rjp9P7fHRx^QC6a@3aK
z+o}{V)jS;^4KcUP)gK=RD-Ui=O@)^&X#ad}`Z-~Eb8rjk{6PAYy54N;UYt?Nr=iVw
zUEj5dJZ@n^N7cH%49(C)dF+RS15<Q>`)a?IA4ZlPH*hSSHncw#g-irgdMwy3(H(k>
zTzdFXrKDX6rzI8xpU1tfjw`DwNv^G}pe^##P|GQc(^-!<SGBxrDWkiZBWGt;6Fe7_
zL-~tvamf8xM3=Ky`YBc{2TjuRcuE*;1owovsQ%Jh(&7x=KuILRL*Ux%5N*CSyCwP&
za;|u>>mtWaR>A25-g#{(QyG=^LEir&RF%p;Oq-LhJc?yF>WAc7YNxOatwG2z97O^O
z{Nu}&zdo%14Ki71nuS74yUhmwm_wed5+vTq!9@D#-_HYyE>Ajk*FS`QmO#iK5lw!G
z|F6UIVHwWwq;u|3`y>8w1~30#I8_SLiBo<5@gveQtcIJ`24A!8jt(a%Hh|6mZ{(=h
zlJb~K-9f3rUhqmJmj&%M)2qtgpX==G?CE(3u0c<qGM02sZqd0MD0nGppg1&HJ@EAE
zJBHR?7=Sb)AWlFKDsdbhIF5sZ^2;Bu&lR}xlIxa(Q^V;yJkE40oG@y70N>uTu?ZWq
zfv|n!##bxe0|WY@{8s}{Tp|t}%x9INTZabPGXhYa8^agCg3Q4W3WWRg|LLSix6Qi)
zm`uE9R4M;^{{!0<Tpao$@|RaVFUW-Hp1s&)G%y=)?dA6_gx}GrDQhZaE0{h0e?|by
A>;M1&

literal 16836
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
Bm-zqy

diff --git a/riscv-sbi.adoc b/riscv-sbi.adoc
index a4c3be3..977569e 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

@@ -691,6 +692,18 @@ along with a unique **HSM state id** for each state:
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
@@ -701,12 +714,33 @@ the state machine shown below in the <<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 no impact on hart level state transition latency
-due to implicit cluster level state transitions.
+A platform can have multiple harts grouped into a hierarchical topology
+groups (namely cores, clusters, nodes, etc) with separate platform specific
+low-power states for each hierarchical group. These platform specific
+low-power states of hierarchial topology groups can be represented as
+platform specific suspend states of a hart. A SBI implementation can
+utilize the suspend states of higher topology groups using one of the
+following approaches:
+
+. *Platform-coordinated:* In this approach, when a hart becomes idle the
+ supervisor-mode power-managment software will request deepest suspend
+ state for the hart and higher topology groups above it. A SBI
+ implementation should choose a suspend state at higher topology
+ group which is:
+.. Not deeper than the specified suspend state
+.. Wake-up latency is not higher than the wake-up latency of the
+ specified suspend state
+. *OS-inititated:* In this approach, the supervisor-mode power-managment
+ software will directly request a suspend state for higher topology group
+ after the last hart in that group becomes idle. When a hart becomes idle,
+ the supervisor-mode power-managment software will always select suspend
+ state for the hart itself but it will select a suspend state for a higher
+ topology group only the hart is the last running hart in the group becomes
+ idle. A SBI implementation should:
+.. Never choose a suspend state for higher topology group different from
+ the specified suspend state
+.. Always prefer most recent suspend state requested for higher topology
+ group

=== Function: HART start (FID #0)

@@ -738,8 +772,8 @@ 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.
+machine-mode (M-mode) then it MUST configure PMP and other M-mode state
+before executing in supervisor-mode.

The `hartid` parameter specifies the target hart which is to be started.

@@ -804,7 +838,8 @@ struct sbiret sbi_hart_get_status(unsigned long hartid)
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 `hartid` parameter specifies the target hart for which status is
+required.

The possible status (or HSM state id) values returned in `sbiret.value`
are described in <<table_hsm_states>>.
@@ -821,9 +856,95 @@ The possible error codes returned in `sbiret.error` are shown in the
|===

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. The
+hart will automatically come out of suspended state and resume normal
+execution when it recieves an interrupt or platform specific hardware event.
+
+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
+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

@@ -835,6 +956,7 @@ return value verification.
| 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")
--
2.25.1