From ada1c9c5b8b5a5f5eda9469fc3275ffae22b90ad Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Thu, 6 Jan 2022 15:15:32 +0800 Subject: [PATCH] usb: Add USB Host Library documentation This commit adds the USB Host Library documentation and fixes some nitpicks in the Host Stack types. Closes https://github.com/espressif/esp-idf/issues/6408 --- components/usb/include/usb/usb_types_ch9.h | 2 +- components/usb/include/usb/usb_types_stack.h | 2 +- docs/_static/usb_host_lib_entities.png | Bin 0 -> 65445 bytes docs/_static/usb_host_lib_lifecycle.png | Bin 0 -> 24787 bytes .../en/api-reference/peripherals/usb_host.rst | 373 +++++++++++++++++- 5 files changed, 374 insertions(+), 3 deletions(-) create mode 100644 docs/_static/usb_host_lib_entities.png create mode 100644 docs/_static/usb_host_lib_lifecycle.png diff --git a/components/usb/include/usb/usb_types_ch9.h b/components/usb/include/usb/usb_types_ch9.h index 3cd853b9f6..b11305900f 100644 --- a/components/usb/include/usb/usb_types_ch9.h +++ b/components/usb/include/usb/usb_types_ch9.h @@ -474,7 +474,7 @@ typedef union { struct { uint8_t bLength; /**< Size of the descriptor in bytes */ uint8_t bDescriptorType; /**< STRING Descriptor Type */ - uint16_t wData[0]; /**< UTF-16LE encoded */ + uint16_t wData[]; /**< UTF-16LE encoded */ } USB_DESC_ATTR; uint8_t val[USB_STR_DESC_SIZE]; } usb_str_desc_t; diff --git a/components/usb/include/usb/usb_types_stack.h b/components/usb/include/usb/usb_types_stack.h index b7a525b20d..c438c54a7f 100644 --- a/components/usb/include/usb/usb_types_stack.h +++ b/components/usb/include/usb/usb_types_stack.h @@ -138,7 +138,7 @@ struct usb_transfer_s{ usb_transfer_cb_t callback; /**< Transfer callback */ void *context; /**< Context variable for transfer to associate transfer with something */ const int num_isoc_packets; /**< Only relevant to Isochronous. Number of service periods (i.e., intervals) to transfer data buffer over. */ - usb_isoc_packet_desc_t isoc_packet_desc[0]; /**< Descriptors for each Isochronous packet */ + usb_isoc_packet_desc_t isoc_packet_desc[]; /**< Descriptors for each Isochronous packet */ }; /** diff --git a/docs/_static/usb_host_lib_entities.png b/docs/_static/usb_host_lib_entities.png new file mode 100644 index 0000000000000000000000000000000000000000..c22186dae42dc7023aa043c80d9847d980405934 GIT binary patch literal 65445 zcmeFZ1zeTO);}%?0;19_4Fb|B-Khvjr?h}{gEZ1zqDV?(#eb<@^R*;iAf0ppfeG@xQj zb=f(OrU$JpZER*@dNeWz?0pUN4b4sLtR1b6hNEUNJQkUsn*Ed~S( zI$LQG*`p8oc1F(ncE->-A1wE876dAIzpMk>0aF=6*@^`$qqC`*gRzp0z9E!o&Oio1 znW=-N1$bfwAMG9Ntj&$ZzLO3{Fm_QVV><^kz~>?sW+qmkwt=;SgS91S0(6AMu?7-c z(0`!(kUwm|RAC%-#AMK(j9~%~tp(Ev#@3d`4tB0!`bXb#9P%K`kuG3^k`DTI&c8?& z7nF|BGSg#H#maqDsDC8QCf~aTRgYu;DO)J)xr8u+MsLt_lU>!1NDAOJXTnhUl9*R<-bEb zR?ees3H+U#HtIno1cFnNYf z89EAV*MxO(IIE*pzlb!_CV8NTq+kl_pzD97n!d};Kf&Dx%zD5>FlL3a&@a6DbI$#jGVy9Je0~HrV4a$Bh+6$m6y@%z}cM zOn=F5J5mNGM8V(sZP%6lpZ42e+WEWJ{qObLj?~P5iYoudRI->D6bb`^_`BkE-2LJ{ ztaZZ5_c!L_k+t}p^f0-F$>Rz6S>J&im{ofu_dm5#|B6Atd4x{>r*P3P*5!YMPxY60 z@7JFH(E^_^L;hLIlI=%^J#j`l61;zek$ypmfT8{;P@;ccC;ekE($RAMikJRFycBkr zvil=S={K4a0Of}&`l$6k={j>9j`Yv+!5h3z0P zWBac-zpN}ro5Kl_QpU>R*1t*YeqX#`QMi82aZFqD`W56=M%bpoVs;6_>=MnYxegD_cP=3 z2e{nW$_U^J2PqXtT>UHFJ(k#U$nCI94mKvJSN=asfP%h*gRvbn9|{OA3&<<@eGB4W zdJ{*<4nNutFfZVk{Q#?ST%Eznezu%H&sSiD^?XD)c2*uHsHyw?=TJApI{cmVh2J!`5xCfferOH@GQ*GImUvpqT?(G+lXNt^Op=* z826kI5hWDVf2)N5J9gARLPnSpK2Anh+214MQGUlslJUP~NB!;|{%`E4Z2vG8Aot&d z1+c@Me;6fU&&M?BcWNJ(!SB}a-x5N$|6(xUBsaw0WZ}Vfzhh*CY0cwQJdq6%79Ke< zP5S>d81S1Y&cBsZ|34aVLLlm2l{lCb{ynw%Gc@4;wp00=jR@xZ9n)Yi5AwJMgO&Yk zJ%8?1a>5MwKj!}ZQLmB{7L@yA-JYOV$@Vjd;jf=``#J`+{wZL|3)SHr-CBC8>u`2RE`6t2>&GgV9oxX;GJwzwS)rb@5hMbe@VRLuhJ1F zn}3UrTqhe@7S}hnw1%F$SJt_14rY(=85B7LWdH!Q38h&5)jLe+Cs{iWn$Vp#>@T;2{zMo_HPU)Xrh5%wWzna(& zuG617zVgTD4-U479{dBe)<3$Szz`%|gM;=bLVTF)9TETg{Q}3R|I>>IVD0{%%$}_6 z`kjU>A__8pRA#|-BR0^}+u#(UgPFdCBDgw5-^%1bw*G|x!}6>S4x!r}-FyNSd<)}S z&~xO_j|X=S92_zJiBJP}aWJzo5j!9!^jtC{%RylFS3%t0XOolId4HXU$qI9dk5T{N zIuR(JAGe%fC!GEk^J?^D*kP!_btIr~b*>&EKj2 zpSfS3*xe&Po(uU2%~)Z&`8dsByZYag*x%o;507>JxvP=>TWH1s({x9I_V1=51(sg)OYv`#ijG~@@~=-{{mWFLW4Z^nOvl+6R`z$VUHSFC_v3cG8@-1%Jt<3E#%FtrC$aetADKX!AHRQzrD<DDE`NkQf4>;g4P~wN)G4x4GU6i2E;r|Okm8gjdTOtA@KE~Z7$G7=Gu)7& zpv6QGiO!_B!A6^o5Ka5Y2mvL8EJj5*iYg`pza=JPqJ3|=Y;<0Tfsb$Z7R_3snn#E8 z#!zm*jz@mgb{z!bi4hHcq9~A&;eEZy$PWMLnIlm6^?n@iOs|0zLBBZ*NA5U={7W@5 zWIs4~QAlG$&^tsCVRUo^1h|7gW8#p-n{{C&&i0S*8qz>$gIR2#q^mvF-3!GP91gD`tm} zm)5~fAQHS76sGLQwB6v-(p%@zz``wHM-}0?6w%`L%{vI$Xz|017M+H!_z=XynSlv5 z6e62OSIrnPeRVy1HqN|)N`FTwuSb2jfe7%P;DqL4D#WQI5_T{S?4whMdsP_`; zNa8uYrxQ|wE}g{9%66+gNQ%@0TOt%!V)M)7jSR{2%S&>MY=TL*H<7k2Asby3j+nVv zQn(0>L_Xm}R}6+KY#*>1p1G`?<9+qs8WLI6|=Z z_O`7pK0ZSf+TUSUEztCD3Ma~NoO@4uBi+yNQS{1Zd?j<|-rkio35a&>ISo0TND@e~ z-$bw3b|UgwcunMs+%~6{>i6qH+Dk15af|Brc-f5GGS{CV^Pu_kWXq4gVXl8Q)19F* zQK(z**^6!=Q^{9VB`NiP5{9PrpjDk(j8o8^!f|n8ao!K5Whhsv!F#fl zjzF_CCSMjlpjdfc9D&zqJ}2FN$d2)5O$8Qtl;Ad;&)dW+`335d3jwRDek^osf{m}D z$QLDPo1~JYb%Iu6rU0=UkPt@PSFb1WIbYEA+U1O)k{J^_|0RfQc^?@p>gn@DT;f}6 zv#e(Cs0PI-$6tQE#F2OU1qrFX7^EXbAYbmbPMtdeonmGX+vQcE$MUHWlW*?l*L&>m ze!Gk|0hR(%pX#|~c8~N+3uPp2!gPw;g`>Z+8?k=KjfJ8i1@Oz z+G+SY1P5a6yfh-Qv$2xlIqjRk>j?4YdH>w3XL+%DX{?}pr16o+UHJDA$`?J6S>SD# zKZ$T&$V7(U6MrO^%zK-p)c%!RQ=pK5D8x>ROnv<2jm*X6&o3dSdyztWIV~6Ei&#=k zhpQYv6zkumaI_qF{-VxfJC0Evz7qf%s7bC(BhjFOiJB4$Y>#%%&f9%HFSH_^Q`^WF34WUU3~m@pRb)w%dH~ zBY2$H1VtyfFPL#1%p)SYw0zW)$ZK!YB#sDUCYDB?Lak66EsFPS^cw4zrq^9c!E%r? ztKpETw}}}FX`VIPL@Ed1Mu8`@IMY6L|V3f3iM@yJ(k{?Sb& z0(bP5KfSojw)q-QmtR4bJ5}4hMLVtUdde8R!lP5~3w7vu95jQ1qnMFd0&{@CZ0vp; zwRF6!+7!tAKHlUB1$x-ZXIjPPf{(t4sOb)~?@Zr6NqFe4_*j;}`2I{ZFDCiTG8wk7 zji}6~u~jO|{lNxWRj^5`O+>c`S_FDu*&WnwRVa)L{xF*D+my)*q@^K+xW zN(5>!sSI&&ZuZs_-p4J2XmDF+7f7Ed71lI7FuTC#G%pNRWO=@%^Rkfp{L|)Qk8P*P z`obU=vMvYtEWO=}s6Y!f18w8?M5CnX162>#-o`lEGBqRmWRJX%3bUG6-~|l z2_8qs(W}Y5rD0v5KuC{#66>@-S5&V&5UO*vxViatD4t4#-bjt>?UAW6&K@%t!er{} z4>{Vt`h0oK=e$Tu>YzjQmbJ|>di8GhHWGo+r;P{Pwg$rOZ4Kgq7l?~*y(P@jvak;- z+D>iHM#L&vc z-)GWML!gZAt$QRW7!w-Lc5u`SFALmlAhY+ z-$#fEZvObp_+^97>6JG6q8y1oRF6% z&hYe*7!RgxOjSIiRvw;+@a~Ff!zJAZo~60l^tks==gendQy&60@F5>+o`eUm<<;rkN4dV%qf&Zi{1f z+)v56c0Z4^wN}C8F@3jG~0` zgU>~%w%jOt8N4;>wO_jw)#!(U)tmY4C7KYw9y=!g$kSJrGIB9<{YCZ6*%9JF)|I0k z-;xO(Qm)EoModJ-vZLaK12vVWEf|lA$CSgU9wW_*L$i&`sF^c5w4a!2Mv*%{(T;qP z#;UHnGL~2FoO}K_d_$v8^9Zy+yo=mLJjfkT%3jQY;J zsP=J7kemKQ71#`K!`Vjj*6~OCwWkW{hGR{Iuwe>&MbPbfGqa}bEsm(Jlnh+$Y@ zzBJh|Dy7YHxa~Io=<#@F^HTGE)%|BIY%lPnnJi>c$+_A+sBYLtGJQcsvqK@H{L*Dfh_>ZQLE_!;yD4%@ za*&PqW(n`RWOvf)w1a5JZ>IO-$(qEM`G%gN(UtVCP)8WQhB37GDAHcPHG$nEEZK3? zbMieB8u<#la+o;lvzPw4z#3wGjM`hIt4kl=fR#Irda;>u8s*y>LfOKACpEc&+=t#= zrF(nsp(ebiGa|z>Z7;GvY@kI&!O`843@6MAqG;Ay<5%fmZ4aJA#q}EZz51-_{&mTD z9h&IM3L6XdXHx^7lU}QnQLFgQI76+()4pF92J?H`pW<|QyfXYc|53zVP*R|>tA|u} zPt~Hh8R@*RK_{Nuz=#sywHQJ9T)rLnbGvy!kk6XLD8-mcZW(MOExu$|^lGEHb-sufJe8BJej6y9* zmPf{ZY{IX({I(U!?w2>r-=cXhY(!H^<)I{oQqXwnN)s2!>c>T(;wOh)XfM!UI+a4< zsLjzbWzvz9i+ifBz*g~=`ap88t?#E(69y7eOYaL3x40;S3;1#kwNfCc@s!v2UPyVz zGSW;xpy>1I3K;h@inw7VPh&AGLyXc1wx5hbas%l6t zfPjyBg*0)7O%gM{r40sK-P%e677BTJwmNsfW@B>>VKZs-Em>~+8{;k$R`8*ry|zQo zim0M$*n%+}B|mTM>tsgkzw;dR+-CILUbr&x=Ds}RSke`48uz`;>Dwg11;s`Dua`9a zPV0Yr0GSA7Txe~{&ZYh^ewRC{Vi}RXY%XVr(lJHRxx&iUa=fNPx`5uYp=Wg1@>4K& zB{Gi3J?1Nmf(t21QuWlqEZj^9m{K6eYHcLSMTvAOl0HJyW`3aR-@WJPDmHw3}sLs+#op@D;`g-YL;6q~&Wx<45-?{G6cawn(0z@#{R6Ay(k z! z9kQ~6HQID=XP?$`Ut2?PR%|v!(ml7C-hz@kn569|Gh$Fxk0ejL!dt%Ap*9x zZlS3;Ta4+@i_AjKz+|LY{Pl-X5^SmTq!NjWH&h0@ibsB{uRmxDE zR_Se(F89vcVrlrK?QbT`w5EDl-_2ci=OGiJyam>~z!RvHMUTmA*sBscT8|1x`FDr0 z=nNG6%ml+8N_;Z|6T5$L3%{Iub~Vi9%cL)#?8PhHsJkBosOh$r!sM{f)b98IEx(z| zI@wz}S9I5&Rz~L$)Lj~$Bywi;e5>J5`0yh{{ark1**vyp{2T8$nZ5nc^8;w1kH|jR zAZQ1#wOgN6{Tz>8&R$XbN@<88%*ku@?UmavJ`q)h_O9qo4OA2^kZF*w7;^AFc7Tf! zNapaJ$&7dvKov_B5-l2&`~m2i2{N-WRm|0;2hK04Y$VqzAKB)|@rc#%#bDHeukq-u zA|-&HZ)`*6U0su&aGAsiE(q<#pkcCVU!Y9c;lpz^c%@V`v^A#6h8E8f?$_TGg>3h9 zlA<+-AGKV!QliQ9Dhq0Pw@XM&W!vL;g)p>%q|NA|DU;i13!O=dDejYRPA?HU0#iWP zZ0zN^OmYbW`r5a5Sy`hqT!Gu zav-195XP7n``OODio(I*@LpR_gUpA6MGPZT=v(DSo99Q|W~^qU6*Q>$F9-KVx1U$P zgDG}DS#-w*qe8ICw4qpfz=>#aBvkp;QXN-3p;nk@fhbO6T~= zPmZl=f$H0WS_-!bc4#j8PykiJ_{3F;m&o#K4scfEGnp6_*@`xBV=`(f@L3o5C)+TI za>tjnKWtnKj?1r*tGA<%MJlPFW#7Uh$~D}s5sDZrUPPjpht8blk87}WnJVsHT*Ilec(vy2Oe9`E9bVVSulV>(Ws5FY zNXHd9fjR}7x&C!Cxw><#TXGcg$rS=`UIvZ;{#Tu+$>=M@9K4vGAvCuVz;0Zj)2^)! z9UPt$fD62M2}E@}*c5QDB7+(lsy=qt***5wXSI86=8)=q?i&T=3&XR-`N);1_#YH) zKadMk2rH6PKSz$rVQXuaVEW+iS{C-$<_+_Q*ADyaI`w*k^vVk>)Dg@!h4j~bvyiM` z=_yAK_NLMLEDJFz;w85aSFMgxL<_pYClRZ1e^Sp}dVYGkXz!b9BCUvDRJAuH(|JEs zc%KIxjfjbQU+-=@w6hz%qIfVm?5HEyj$qfX6aQkqe0I;I%Jao@71}`qPX;tNyXu7d z=t%i2yLXudUI=bNAi88b@}a%8{7yo+i#0)m&Tn1Eb$~a@A?DhbI#P+9l?Uk9ubt#R~*ZU;a?;}ko_jqvu+=i&;2YPEYh`1Cf>@}o}!2~ zvDxS0=*X`!^)nVj^T;I|4%QbvQT`zs3p}WpDxJ(%nOHoBz?!i(9gYA3Jbt#d68 zO$`B_)y$7x^&Rs*rC!y3LSgDYBL(L}KVh;RX1UA`DjRV;01&#M`v}Vt`j(JA3iUo% z&noWFBmoR$zkQV4l5FOn_rBh^&`CZg#3dK`!c7zfM8TvID{2M;nWTc|?>&>Hc@p~`3qiL>={mvI7cedyH+KLKAA ziuY_4ZvnKgJ6DOuVQFO8#q0my2$T>KHd~A)}1cFNQtiY&Ztr(6m26f zH4H6OI54ducU(+b2cI|5K?dE1{L`ECQj3ply#-oo5;NfSsP%X+`mBsM=LZefxUMRI zJ?)z5#+X+;VNgaf^H%Fd5ao>i*9tRe7Y}$II7p$}NHsvxUn7fG+D)=}Y&igvU8(^a z0UI9plL8Mp%zQb`->Zjw&{(h6dugd6L_qqYEJ|R2-3+`>NnmGCysx)BvbxUm2YmhM z5~#sln|@9%La%~ey$Z%sDNMF{3h}C1-@4Y3=gB6x0TWKHb(egOgTO$p zXWZQuM~4;9tjiQg!9YIGpnoY)EmsjSTR!zYqylHZC$FnhRCO(O<+I81%VJ)vrogBw z76*pe7_v{I!p_}e0$S|1+8fd(LJ{~y$W#%4-wy?A&4&%M=e*K=PicM8G)$cQ!F2BdTY&-sZKWWs5ed=O~Z^aQ0<3*N{w3vNUn|gN@Q) zfT+1Flo#&17SIaAR{^3_jGkf>Z>C8Z9mW`?j2yn2-b zo!vysiZ@S2EH9HoO=ox~SS>W1%gPGb5?EBy-cVE$)qT?$Qx4L|Y+oS-k-qv7Pmq-P zCO_5?jU=&4iQsmFS1pdt{;I0{BhUUm`KG`yG#%1&>wpQf&FP}C5G;ZKMYHJft|Ci6 zVA8Jerc-+CqD%?g=NR$yGSA&R5}I>;`GHVmf>BHI%f{rnm^#De2)gvwT!lK-XCylf zLK`J$907KsoGn^z@iD!HvZx+F(}BF|Q8e-->u-kur}z%4KG|O=AB~`J9O~Gah?OtC zvwk}xxD?ez$E*7u>OI|ANH#rQo@cQR0co1}{$82mu7q00)lR=&4Uua`h;WJIkNC`H z+Wenwho!F|P*9p5pf{b9ZxitV-mDY}KzVhE4gl!pN)y+kf7(J&t#X*frlZ_^b`^r3 zTMY&S4;lb+rU5X15I|h@f!=bNyr&i==&?n+p1TAf@UBXGlP8*`XFryhpi#dXu$51FhC$HAg3DL*{*f(_r{N*Qe%vE-(aX5-5h>X!V2o?d}iEvY3?sRHXvQWgNPBc>#3vf%DrM3Ti?+ zJVN;l}^TaF0P7ROaNaM8&IfCTiuCFB&70s=*m=MeQ83N(~4MaFn#4k*>-Mbdes|Lp965Lr9yT@0q z_X0kP*&Z>$tr>ZwC7MzU<*CzP)m}P%_Hc13qT_ncz15OC@p-W;`Y46oXAhPR$JqZj z)Z;f&$W^2ss&YilkPH{y+u7_>rIW8KvmPZ`s@t{-1AtsE2<_aizK6jo+3F(g+kel6 z!jXXemNHeSS`L+b3V)N8RA;VX;musdtX@?}1TkN)ekcGz^Q~ttknpQx$lnZXTzC&C zn9tX#J@`88y}-&VEJ&d+Nij?944|iW&Q^YYD)i3_Cu4U%%-!w5_v?5%JoExsKTs30 z$ZirIUBqKQ^=bZN2{hb=6Feqhz>p$We*vFGcsRdFngESaHichfveFfBb%e)a<#e&* zoGQ>O;>34?Zl=fblDskOX zhH%hG`1YLwRVXhMoe%M*MDIFypGUwt@r`de3(qAc?EJ3lUWvvxiQ!Y^kD$y0r`Tg& zTD3LX=4z>caM8#6fN$Wg|C(=--c~U~&LG1b$Y<2UoB7b0b(r6!_=J2gY{ywsQOJ`= z)X#jq-=cRVb2v;|y!W_qMHu;DnZ0}0Gz$tntL$zPVZ%w09So}~{KFcXlq`l;!HEj@ z>pD!rXFl$~eZWQokC3_H4~8v)e;CC}ZyNlBOphJGf#$ppPokr4?|F21DBt0can`Cr zX_?f2Mxp`ZVAv#_t{)V}$0ytAR^A6|Qh6$Owp3GR*I}}TixxgY_+Z#4-j^~v&T3N7 zBY!vtH!LHj)^TeX&+)Y1!I~gSUoYx|0L3(2DuQ8ya4@V1BFFzDq`*Vf+=;p(v{MU| zV-k;j)7e4_^HcCZ*2Fv;0b!N#5UQCyK1fzy%`sS(sZmhnw$R#RNU59Se+V;o@kX2PItC$VIZ;l zPjoxXvZu>delhKNx3!gapixhuD^9}|a9IxMEew>-^yXsasTD60QuBGk01kauuDh!;vof-VQuYO_=FC!VN}I7U z35MZXqL->gk{{ddu{w>3FYrRQ7rAPEA=Cr%Di%rPbE!YQ&DeHj-cQsxkJ9mshR}{h zmA9Jn$~?;a&2sGgdXj)PoHm0oV7eT<+Y<*>X`OSX(Oo(>4S3UfUO$@j%_OM{aSq;s}9s>;;V_F66owtT2{E62Gg@%{`l_GM+{ zyGUqdHGM{R3tg3OKm}cCd_38?xLOL0?~6J#r$G55Td@5Os#y zZm6(B`U=Ad&3e*Z6WAhNbkPwf*H{t91LJ`Q71w3q8FbFBmMl<1X|}DePz%j0HOGgI zxor!BEY|<7pj2nSUrwZ%{!TTs4&*S8eiq|yTlWm!9 zJJi<;9hNOiK9YF2`q~AZq3ed)=i8ss^P8f}rSeUyT!AX8)d4+k1P8DgT}vg$s_Ohe z&f@_0OpP|*IAZuwlfUialW#}VTho%(;dl-Y_YCK5kcA$G%|j2zZF3o`p^64VncHXt z@E8SJlx%G8%(vrrBr*hx&YzKP7~R$L80T_pW)>cfzI{4Ocy0`%32GLLLg4w&wddV* z#=LUPe6+NCp@^D?+_8@6)iRBL?`sP(dZ^j{S&js0-LLmGT#bT29-oU?R_b%2D+o!q zbcgpeV}O%*g@$9p4BFQ@r_QMSOPNd)mx>F$7sqbZ-g0e3_@$zWFFlet(!ro(>iUYg zQM^Qiiq5tr`u*a@r{qeCth^XoQF2iSpHgMYN$Y&zEhps#3J#6zO!e8}*Nh+T$hhr^ zG?;zuJDlX6t>kHQ3`LsE4&ibRNosP(rU#}(isFsc9w@3p&c#xkRtr2^(gqTNx*k=9CKl%V+=YiPAoC=!QWHHT|yq&9!+)8*-oWHCr@Zs|G!s{sPkB?-o&xh;gH_Ck2@ zO5xV#wkwnfp+3Egqt$qpz$>bY6sjvibrjsci1TGiBCzeA2V~&>T>tp`yDUrLTq!oYW3`J5KoUz9QZZPak2%#zz{{W3{w6r8odHp75QUgqs< zJ!z+%yq4kQZdUmPU|o78BQMYWG@1QA^LQzplFeEpV&6>*u)_N?!?o4U%kSAySWR1n zq!VY;a?Yr>U-S_wf6_Q8R{!lqwRbJieadTv?%(=aL-I&oxZ*;D;{{( zZ286fFdF|-EE_KAnA)}YPW%AQ(eUOs+;lT(;9*Dn~@TkKn9nN-`+ zEq@*oa(~~0CD;6Qp|ML9r^~!aHM8@f()y=&m9aBg_2>hUdl)>ccy5o>L?H}>0|>Um zuivWa$Us1R@9w4R4?h80HH55od$D?^EA2F}yT{B+$z2!I0!bRdzM}BVNG5dvPjMQ{ zBA(>ky2&*=5emnojS{DYkl0ku+rhobAj5?~F|(l~L#kAIc-ZY5y3kGjqKc8wF!7oo z*kEXJhES3(L9x^YBcTn9!E>9{k3^*(|ELK=cmTmj14DsnxR^I zB4R;ZC(_(%_dO29%vNvYa8|-t&lH>V`4}0}@g+-h>|jHJ{skPPjszsfkwsENHUHjC zHZlJVf?<)x{D+H~9V*RvD)|ces*D$fJTC%swh`)r0OVt+&VvX|Xosb43qn895-k?I zy0l{r(WtaDK1alL4w~Kr)_rBAnbZ&jnt@kMD*XV&sxv9{K?2IFcUjk<@XY)`>9y!K zc9RY=;A7|2;oWqBgC=T#eJYN`{QZ*`Kmb^7_tLVkP3MZ!IHs%#I?SLyZ|}Nsa{2D8(E^m=E>OW4+Ld;7jdSaj!h`+!@FKWfPz^#VGhArctjrM^ok4|y zmF|_y>jH2b+qn+n8Xil+_e-OZ)zQ(kt1}r7K0K$pnaqu`>O3#(^F-t6a~-}3=|rxx z0>je7^yAGLUt{IR1{t-Yxb;QDtluHvtWLcyo_r(XQAW(;`%s?WClX{2CD-k$mP&n5 zC6_1367zLgiOTbETgy>Bf7fdZ<@&XFWj{-Y49TnaQTq$Y-TDi;*-X1UGUvA!232&? z)|MiTf-xm#ucy0C?6^uiCl1aan9whfTi;)Gw;>6-U7&vuuvQS1xCo0%=00 zO*)}_+l)pnFT``jUn;3^s3tfTk2%kjY&}|fc=vQy%qUV+uf#}oAfn-DbNuA!Wkh=% zcfum4eeGyw$^Q55S1x>892SGDX>{#m6vYks+LDr8Z<^2P-&4XaSW{GPej*OJUGtI1 zd@8*8t-0Frkoi*D)p0rQFU_j53;h>Ak}~?CW=E#2R^0ng>_QkX3n`LTt71T-Cw_OU zBQ4!B%!PQP8+Ps>$<%PKCfieHAj6T%~MO_Vm(pc`Pyu2319JG|6WAbg0t%O zRdDyDoW&_~*&3r7Od0(Vk zgscfnP=%)k63@;1FA%U93HKN3^zAoAk`|RY$b5ogH_Ca+C?Eky6r{WKIa#L)dUWO7 zpzM>JeV6srYu_`8-&L{nI)!?HCZ{_9mO=mySS}aZn=Irtk}+aASSA7Rm#%7OYn)_v z5G#UuxFCg0BAT~MjH20;n(~1UgHM??nd7%CE9gG3>eFlc=4n?TX}bK|ho)<5Js<3M zxUYJBLHP>u#8kX?{cZEr#R9G8j28m}~tk_jm3>Qau6;?;_DRUa@?6rhTXaL+H7=b7}-t5S6>qL(WyxvIo+{ zGRB>*tHpI%S8yiBzp~2EuDt2W#nQabT-34*)<$CSX046>hK+W$;~Pr3!lwSkL7Gga zGuPC=Y@dp$x-R4qPMUo|@_w*+6s-)K>|&3&BiL?7z%+o-Sj#h)HEKgHGrLOLqc#FL%xlAk%C0k*C4$zn$7rXA3`umYbVIf@&oCDl-46P zGtis^%ayU$_-sbV2QbqxbN!AlNY9hBoCR60OIIVJpTZ-aedM$-5K;m1v}72y8M3b4 z69qb81;8zN(gZSiZveKfg0KWKCN(o7L{rvoaoB)lFMNI%mJmGV!Y?Qq+R;_{YDIaT z>kEVZYU-t_sLwr0aZq9&L9IGhGRHo_?Rg(YaVz=@cV?+^qUpbMOI2{#P3&)v(4;TFDq@M7;;VkA<&FVRwI%sY{tTKvr3B&+#Z1o4eEuN&JA#C(@AAF|0{ zk~<1U&|LE*l~TOVW+^EyzO&CI)T%L(O`n@o)w)z45J;lkynzxQ!1lMBx}`&Gy~1B&Gmo~^u^)gbJl2yMV{N6bDcIWOSm;FpOuR; z<<@t@6)W67pWAx7dwOMzW;y466fY@~CM{_X@kAX2Un?_0E4y8uvT}2!dH?GMvv$R! zGQIoEx`kzuS1dj}N_SuwYBTb)UY&Xi(BM(9wfYQJF4cZZ*|Ns9DrYm0diNfLUABWX z-#+BTi8iVZ>#`+^^T*)$wjYsOzc^SlM7W&!4P-}RZvq4Bl3c1_fwWn31TjwT_VPFn59AhYtR=GiY+r7(}s`W0m5)TbRg=ZxpH+Obcw+CeR7OOvuWTSZwl_1rV zaC;N%uku)-I4AJoxydIfpmwF%Pj{6WNURm!5R0b!I=3R55VyFC%hWj6eDCM2F~j}Vl0=cZH9@m)6Wus8WHSrj&vbvV`E*K=O6JQbe!VkVf>KuFREoeo zk}w9g1JKkgh8n;}j(R)tBQc}R(Y@;_PgN{&s@fj9Vqve4dL>XEf!a}8?d$6 zwUoI0+RbsLH6~+Yy30zJb`mwi>COMKtV5!ms9uPm{Gqd7^%sYss&CHcbDkqgGI7$D$PKOy0m77JvT~fn8qB1SXh%eG!Kw z7k#sOhj}Fbp^U`V7wmlWKB1|XZ%N+4t@B=ZJ>ZH((vrJvzIs_=#DJG^UT*A36fa2^ z{_;Rip7oIDZpDhy46hj@+jKioMh|lC>OTHCmvE?QBmuIf&_tKl=*v|ICJjagp=TN5 zB8&oWRH@x`MFjckH!yfH(>!;#au-ysI@z2f0;z6#?K&1n>i`!Phi<+v|9+LI@%GmR zNHHRs>P3**Etko}Rhv-XEQTMpGYrlX$P28;@t%7IcA=cRn5U60D8IV5Z*O^iJH*za z6LFxxPYEI1(D-a$6+Y?LI{v%auO0mQ-p~ z&3O9kFCQyB9`1MzrZX`(P&!iSj+R-4-w(lk9X9IuvVqi7ArMirNZXY(*KkoYcc`+v z^0vx6_Z?+o!5rNu4+aFoD<=P9@-~Dq z5N$j>R|(`)7}sb$H3-YJdJ#c9Q|`j5>IBIwQ)w>JxGTOgo^P(hA6*qjr*!94YgX(; z?`!@LhE0!CGQ(5GB`YuEd}erEi7_u-^<5DlB%7n$ypbb&euu-dxb52bXr-gf$1+OX z&*N&Ld6pl2v+{?R+(-%)(iGN`cqPxc27R7ixf?>|xw9*%UF)(as3_IAwp}DNmi!sj zcHtdj*xX*oz}Cc9GY7WUTrLmvryiAK2#JWQ=*s#BioW+0x-q#rN%xh3DMcU+S*MXo zru)|N5PlJdzQ-;hf7%6gqdOb6IB$oFH|RO$zkED>r($jrg$D9E$fyqUUPcQCn)WjK zS(%%%b5T)M6;C9|@2EOQZRe$I3pj?wv)&I2B$9Slce#A8(t_WmVc~jAGB~tBJJvkJ zA^GyLTrvnsO|`}%fhenFnZ?KFV4F13$<_t-c4($d>=;O~m*~q=A^l)gTD41ME^KjX0sP7Ic$co2KmIb9Lc|KM6?ySRjMIVwICMdaFAd4tV^-@R zPR!4cr1O3029eXL^1C&($EYAY*~uE}pjdJX;$Z2Z*c@AaJzMrhw(Lha;;Gi_$suOe zHE>qs)l!fTBg>O-`iLE}1I~%$?OWcHEbs11ywdHq=U!UcE@-zMpZQcHSMh3Z&ul*& z$QKtQE(d2?QrZ((E6tRQuEjP{=8ii(p-FO)x|tD-)dz?DUdp#6sg~Gd>(z`RNdFjW zO=VVlSdr=(E>1TJfjtQ15(wc4X%xud$Uz6d#W2JHd}#6B?R zdOVH_X+S`;j*|8qsl3ou^FezSOF*&tYc+o=&g9M8lPkB;)7!BM^QYV+N~F+o+#pxq zyPq%B^z=qR!E&w1?r_|?H&`>oWck4nn}lAGOI2|ig=QrB+nb@MGdz}t$|S@K4L!xw z=A06*w=79*&H&i4P@LRd&e;|=Je zkW;j>nG~(?G*Sg86pI{#7}PjTmQ(AdjpOZmxY8zt09;a2=?Iq;o|IYMI-89R^{(t$ za>uh8`P&;hJywdvDsT>3kM-OgWe7FD-!Z8V~aBna>~8y=DidHRC@e z$OM4UHBKn3f!hn3C;W)`nm!nuuM4Fj;ZU zKg?kmEPA$kIRm6fK%vc8@-YH%_K<7s0{F%85b<8}A%Yt#os1Y+az7`E7oTAgD(jh*w$?s$*YZ7kEVqDvF8N(I7Rb+7ek8)}v6$4)v^`iG zUjA84QDj}F5arB{R8m74x!&7C=$=`9#i{=A-I2Hj1A0r{p{8G>pOAWTskP)K4rF6| z5sD+kYMv_~^;xDL?m*35^~Me!2H7ysv?%4Gn>u#$4gzgtJX2kaI#t-*#fP;ZDpwo znB!jtv5@OCq5^^-6fuT$cxC}WI zJ@SH^nPqgn8~A*<`TYei6IQ27Q?W$Y(OVuc5x3o^yE|n$piW2%&WIpTj=FuFUm3sv z2`8F2puw0`NB6K~7J|9=PntIEpLrs*_`&6K>1>73Di!h%Jbzy1>30X381~?r^lM+? z8H_HS=iuC8066&h2prK&QyV}(UuZoTP%AGKzLUsBZq}V1V2X2x6Tm}}z+u-1xc<$1 z-RnX{IEd21Y9KcYjZkkedd}re!%YiF0;vS493dI%$D)D545n3rZguo7Nss_#5NFjC zMxg%OG}>wSGgAel@ztSfJH!>mOyTY~_g~gl5A5cvgOO= zz)~%Hu?g;tV$uy-zr08EEs8?MU7JLMO5xHoo!T@KQc;M-G+TNx*`r8daM-gqEfs_< z-8_PvIhb_ohTh>m>Az}uxq)_gNnQXa%fqKYi&_)OTkD!io^p59+zLP&AU5y7iQBMs zcmmS8gn%1W*<1T0>&x$NB2sCZw1AwQ=|uTAO1|EV=pYFraNx4r#^=CV2%l*e88o48 z)O|Hv?V}Bzjl`_>Zk*|`mo$fI*D2^RUw}i@RyBY_7rpU&;B@Y|3YRiGo1nYc2u_y0 z0An|=JxCDa9d*}C!9=j|5%xce)0Hhxs$8h8acvZn`syRlMMOtIC`pz*-1M3$vAzE# zxuhU4&)b{tKw{8xw-l*9Ff%m2q@l;G=o7Ec+~8F^FBkbffemn)#y2xpQS{>T@Zcz- za{tP*sAY1aw9c_yyXolS*kF>ZSX1IN%m05?d+Vm-niMs($Z(9ZJRvW_?LjA9@osBhO(j_>>&-PP#{ zQ({W=nxfb`WsnDGDU_#LKnO)4-CKJp#$P@(=9idFx>&$&3C-o3>Y-pn{%{sf?HTWC zq6@lcIg3Fv;%2lIiAd4S+Kcus22$}174{Hp%v)~)Xd;PU#s?u|hlaiCnEz_<%Y$0)8MZ*1#(W5IDGU`y1z)K1@YtN z+K>@{KH}SA`#P$2PVQp83sHj7rG{2={{ofUN@hwR!HqYOH!g<}d4^(nD$$w(z)=HQ z#f$4-mJukO+Dr3ws=2PlGX#U=F>^0hQ8g*0N$t!I<=vfJJnKdw;8Sy1eDFp@#myPw zk(_b3AR*p=SE~q|lcfQnn+bWG(~9@Q&_?w^Li(tAac8U(0pQ^Iai#QJvQJp>+DRbw z3rTX$ow24lLaQS2ignZHmw~qH5Eb40nCWv8p66DxV7UNfu3sivK!O#(vMyL9Lx#kr zbLqq0y-i@3sy+AMrjh#tD{}U=k~e^bO#lb|M|iTkJKV-!?XJYgt>vG*k?e z#MNhROfHA+7oWg-8mtUKT){Gbc~0{Puo?{?Lbds%V)FqT1_`FjK8a`Hx7WAKVPRCZ z+2}h+#cuo}NIyF>Mx?mqzrvi)9`I{iEc2jqETj;#-y185eK2K9g}z}VcEwZ`Ls>8Y>^aGyJ7&gAE~yi#Is2FJDPQzU zAN3@NIZs|H4<~ZKWkPS7uf_Jo;SOO=7D>}MdOR#`+;tQ~k(fEE5U_I$Q`yh&qM!4Dvl ze2@#cl6x0P3a3P1JA)rB(B53_R#W0s=$u|cNqGPu6EsE@c1`^Vt<+^+p#Diw}6@xNQZFTxY4OpJR0TU47D7*>j_`zIqOM|-ot>6@NPF%Z7+3|-(W zsSqddP)YJ|Ap>1g6y7rg43-k?v{U|BmY+P|Y;WF}Ok`Of>1;`@w4Zd z8hDH(&u?LAM4}RH-I-jn?<;MSVq?FIW?{tS;fXKeE8T|q{Ys)^ovNP zQp%xjkiv&QiIBMU5GIMhh&m9%LZq_5)oww+heYdZ@aIv5ThQEjd5jkq%%niT0&B-Q z)e!UNs{;t=1imb^&lE^36s~}I(4+rf9@No<>kYPIf7+jjHvEO5F@=tGf|LSH8KzeW zQdPdV$eZ2lA0t{wf`fx^TUuu7lf6Fn2;8OydXQk3?d8{FSO>olKhz`ObSFiI+LWvns-`0KVNG>{pXl-E238?YA6)* zYt3EvR*hSu7^ad8P-}1aK`mes3awr4lqpBiL*1mCPFKkB!F-xNb}`hC%As#*4M$kw z9SoiuBx06Bd*e6)U*3IZNFRgm0gW9exgA57!oY9b#QwJ`2!1*$q8lUm9$>;A7G%0XuS5cN&Z;(G%SQbWz23%-SuFbKuwQvH0=h%Dp> zEYtZKKeFpO*hO`_)Z%Wd-llAE?CNrm7JN3-8bZn9;&-w`0p$MxjPwKe()*xDpjGW` zBQyo9i)HKROI*E9P_ADpKkgb)wc-?|1J zTMfM6+^2oV2U~f;hOe+M-!N~+&eTjZi4lqwr>+D6l*d!`QjjtaH7tAd^2Zi|2P7>y z^*)h_ei45B?KVjv*rl18wR+vIl1NF9P0o)Lb+wya+#rr2^yx106;%H{{PscC{ctfS z-azfJ0k{*kV{>tu(j+=L0+}utlTUEtgpoP3PlWj3dm_6!H7Fk70v9#Bgj92^2!rx@ zQav3lWdpKY=0|TFB6{pj`VeN87vO~H@|UrKXI#(%xdGI0K@K9N$EbdEU`$sIUCTr^ zJ|z$FY?$`A$^>Y31Y@f0LwyeyIpWK{22)j9i~Wk{G1NJ6Jvnq?z4Hd~v}m&+A#Mp0 zs&DLodGKtmi=13h!uME|-tX9Phkq(O5pQqIp#jPH!RuGjjSyxhvwaNP`z|W#>Jz|s z3JjGFMGv4dwvy|u60^%G&2;teem`FEGIl^JMo++lwXOd}+iLvk9i|pv0$XjZ%6U=e z?v=}?)QL{*Z-*fW$Thx_0M>IRfWky;tg0kNJh9TdEWHl~Ox-)+N>(`FSD~xaI0(;!bh66R_}^Xe zco^<@Oyj~FFoyK8zYD3vRmI$j#b;N0r=^GiHCq{64&2A5;g<0%i;VVql`>f@?o)QMHs@`)n-1jiPv}b3osd%9+rPYwh1-8Atyo2TyVyHD8I(~osJtT_Gf(K+{MZp`@=PUu!$$# zLr5z*4H%{hRqz>n_kSHVj@7sob)~ZyT9yy#RbA}%C+}$oew&-$Am*G3lNc5k0?$bH z`Xj3PXPa439+kDRApr+9wVto})02ZNs=vR!PG9Sr36ew*m4TRuo0kGGriRraW3ef8oKafc#M$^8*HQ8GpAypx%)SOVcS}6yspT##q>z0Lvr2 zYb<5SjadX4zTRPf8tP5X**@xT*5x+dq)4qJGAROkOZ3F1(-&iJ`ya{50J_yD$uWKH zqJzhL1y7|`7N~4B`oUkXY7%2hV(hl$8m>6z@bl1Mq)zmI5l-Y}2fyJl3Kssugn4Mv zYs;e{9$W<)*+w30XO>a9(^n5gLjG^FF2*T~TgCWgm2ak@wi0p5C;AO1d6g*dUO_V) zcy)bbwS|GD8ttloND?)zPH-n`Lo5o2zj!3)PX(@17G9Q}^4+PvAM%g*S0E!}jJP~L zlPzV)3-B#(hJn$yW2U|g;$TdeLA4Tp42=0ZIvzQ6Pg%%gR&WyFN11)Z^1;+fn0b;c z!wjDNV+=@#QN9AN;os(GbH|EiZ^pKl>Xq)AJ4CGduUen>hPeC?kB;V7te)A1ohLX{uqy?jbw zd|6XkLT%uGsf7JudUks30fEp(sLr}1Ln8*pE6Wmrpu0Tr@&eAcl84G$(WDr6^?$U| ziZ5ef+ykiYBQL=dN6scZ0gvd0MJsMnBb)7&|5jwRx!2)M{rkm7ERD1^5C&XKLn$gK zm;sjgD1+ta|J4o)wu$?%ivYKlzRl(O-(SAE9gbPO?f;|o2BTrb2QPu*lF}QfF#O-1 zFlK6a|Iaw#>o0HI23L}jQoH)UW(>1DHvVfqh_Rc`fopGWrm*;VQC+9yaa&sdgObw zKN|(rEt=CHGPRAI;=Y%Ed#)?~^H|0-H}Ki`>-Vuhf(WDMMgOgnL-9A$-?#k{HnYY9 zIfy!5y?Q~2q>=KxwK`cB27Uyi<4h}h7FFl9rv&0hWR5JzJd-+cu6y~xUVE$N&@v_D z8)4A}U|%L3ABnmhUER@vP-JcZnxbmvDsVs%@m%Ckgp;d?{!t0cT#wIqJ4{XSe+B){ zLCC}5iG^;pe}!~#?ORTbDzknv^)5>0~21k@)1 zzc7|=sRx=to~yyTs}%YmSMgh9$~)t* z1%c7<3kTHWA>htG%58MXs2)160_=I^LW01Uo`3C$ALTm zG*JL(u8LawHC|AC#{fiI2H@ho7jZZ}SHgmP7)f8LHi0*0O&0w+xb-Q>2x-gQtZoY) zcj}kIiTwuZVcevK6?TS-?-8XlchHFH@iEJWs-YSv@`7?O2F4Q0UkNu@USlNUm{W2z zQgnip+&{d|jI7%DfQ!fC4cVDSaE=RbmmmfmV!C=Aj)-X2W5K|Jm`lF@SXN;R`D)6Rs}^(i zKa2pI=TXN3rF&31oy$qNH3EI~++IjWP=-)D?fuvT^d*;9*Fu5LfHLtRYt(>((hkD@ zrd1c2B07+e?vn;VS@gG!8<$zaFb4W)t${&MLbV0@NGy&y(+It642hqSVTI?%e7Nze z0UWZ>T%HG2T61k1*xW>N<+ek2NI2|OHXEo?sBf6P2uSSx0E3w*Io40(;Iib24_4mLJeiF%3h8wg77y3#Kb~h z_&~G}+9;6Imx3ao6(xov0)yw0BUh#xWMKd0Fgv1}Qc&7B_VQ=YXLK=+CXOlzz$^0@ zFU3RnEg)D-@|cpn&|5L*Vt$izYMtY~U#|7KliYD8fu+)zs_hOW&{4zOEJmw)C~axj z`{+K=*yII$FL#g-NfjSi)c?~Z;1D@h1yQ8-7pGd8sD?OiX$bAj6k-%2wL#!+7n%DI zfXk1?mR>%G+aA+gq)OCChBYM1;!G2c(#boS_GV9yYGJUWokm@Pe$gv8VpUQQllu-3 z6Unm=W~=Lt6tJo$@K_2b1cF8+qcd0xJi6WQrGHJ0ulx%f-YTD7e@Y!NHI0ezN2lzG ztP#wsQNn#t3&5BV6s=Wi7o#_*Zru0OX(O)b#Q2&^tP_`As| zFq`~y-Sz|c^1tS*85d*UEY%h~HwgE_th*aE`me|kcIEq|#*&*skm4gve+x`G*G&_n_3SpVxxeFICd zqiu`XY5y}QTr5ZV4*)8lmjq>_P}(ctmdt==!NQM{hvS}1nt1=^DomSUL$VAzI~&9^wp1#x5#O*V7z$hn4Gp~HjMGdd3cMi#jy*NT$oLJ<>1{I zlqF+;Jq%2V4}T1#Qa}k{1ap-VFMxkr8uXY2UUwj7x7_d#7FWW2;B>-Zd$b=Tpv8BA zaJCNeFdx2q4Ikq2;g^pR<;yW|Xb^)HzE@OWh{Jq{6~Z8a1OrOY=Wq;a=g3YHfG-Ch zWWT~M%kr6iVwRO7EZ>`btRJIgF&{c8p$~$AfBWz^uE2QVe=y6J)=2BB*op1`bp2)A z!6s8TgCAvfd@c*_yO+@9&E@Iua)=beUE-&hjlqh&I?=KbL@!s7q5RT)L+!hoGYNJ$ zICm)|kAijn>x+!o_G>=_ZbDU1I52u&2V9}bOw48ePn!^Dlr1y|%{`l1Bf)H6e_RDV&P4JcPD?1o7yF42GXDxMcryB9uqMb=vY* zGh!R1ix9C2P5&8s|JCis7~ht9T(wTE#Cbo(d21g@viW^(|CPgCe zOa)%o%QMVdO5nh}TKd1Q_BG}CSdrMO1?)b>ZNw(41%(BR%GOuRm8$tzgG zKR1R#gM%AEKf`}CvmArHzH0Qx9j^%*^V*&M!{0FdRa55I@a{_RTVdYs`1JYA&I5Rz zlWm2@j(g1)S-EtuRWK^F+;?v`V_p1BFR{U|{5NPVlSoBPOxB+?bb4<+8Xs+7*n_I9 zP`4>PBmTd~+ZZWxc zua6(@=oj^eVmA3c&dXqh5Mq8GPgeJBZB{Om2X&TgJUXp1@nhxJ+GDFF{7#XpY1Jp~ z42Z*-FvNrETcp3cgZ2{z&y$b{3t5j3U3)MSnT|3e!d^B0^2+_X&JTG*hxHWGdzEXw#X;H5aHjzg=q`!NYR%{N8iPx!KMk}FP*BFYESX3q=$hn`TTd8I)Ptsk# z|9NvXv1LWJiEW&R>%>tIOaE(B`<$$Qv}-dqEAqi;rxs%BLhx;biZTAl^Xe&yNYsY< zuG$V-a6pj;|CQ=FYboS?Vq6leLWsc4Eg)jfZuQSX8f+^?L-}(mv~R?sp;i^jO)k;zuTAQ8 zw&dFkE5TKVCyvD)C(dzLmw}l0a<~&Slj0V=KWgp2 zy3a1cS@q72Za|$lSOTjyXsrt*h-JK7$GPLEvCoTOtFgOiY(vkgb=yLjT4vgU)7ZlB z?}%VyQ#j(tGS-q*d2O=x4d;jS7*)J>Q_gY&?u@0*{NH{_#BfuT(n~HZcr92^Z@g0d zHZNICNY=ncaS2yo`9Q95A6|q+rVle#k7ZA z?*IN*=ZJpVoj|6~gOp=WU?|bz4~+%fL&bU*{e$w$S#jS1tmEWlM?(0XjOsb5bwlZ@Lh4 z#&^X2j(sJvNxKhzKzlcf90Ll$*sX|aY+GVYbTC$Q}zvk>SyE4@gRglalV{432TBoi7q`3VN6`d z&CHC|F28OSbX(K*sBf~V-*2ihA)~VC%x`nk_(8oR(Moqt>o>i({=vncvxTGhBWDVP zjl2+$>6LA~hZ#lumv9|nW-LSuCl)`Mn(cOa@Vnc1+tm(l($68FHujpB`zqn3qT2AG zBZrUonpipGxdpCRY6LGMXIVU$>Gy?eM0*!|E0m_o%WBdt5mH&BXmcIuxf-tM)%2}j zo8FF>=y=2Ya;1ibvq6NMlF7xfyys9}WaG~W#rnNOvd8*-inLGgdS^A94!?b%{dupY zNmD-T!-)}5tEk(-(3q9Z^aNv{U%KtcsmXLLJ$Cb&x{@}+m^Q!V_?2~gveMMNF0#1X zI1H9!q3fpJ+OrK^(oQf?Q~_yD(cr^X_qKIuRrOXnw7lkOa95VrJp5vfCclw+{>5;(y#bo zHMn)ZvMcNh`VSYN^>U94K8cYCG~#&U3oio!h0JHR{Y%$Z*8ZKjONlynOJ2NaIGL0i zWFjHgp}_fJp9GpkxMwB@ zV{7WlYA{PYtx;4AYe~F>Lhm+mVT$lk{yBM{-QhoAs`subJl6B0-UULo& zB6I@qdWyBG)cD|Sh`t+7hzbl#`$_8U|7Q2!X)*R!yZ*`Gb|cJ7`eJl&AOZ3SasvWS zf8Kgf^-T8s0Y*6ms$9`$ZmZ*lCsAKhhQ4fF@XNus%IKDuTPrxXeKJKMogD7pt=ZhW z$~k0%}elj0`ydBks-D#xaga;COr&9VPJ<>>Lx!#~nzK7cA1)OiZ+FQPyj>d5M}j14*V#fjrl zUvda!T4(C^Cgnkc_Tlyy?%A)uHb2NBhVm$4D<6}%9Q+vyx$21Y^ZUmrRu1ouI5wCx zeIS23kavfxoHLQOu+wTLFmD0K1l9U?LWZ+?&py3wa2&X#h3)_91>FgRf?4RN@mFKt z{2&2GJ?Q-zIMQ>$2mO(!Jkqq{*vnP*2Tqv&(A<24Ps*VY4z&=iXt5a3BeQIJb^CZf z81bHL4>FRq=8jrl`M`T zf}~#6j}${&|Cl<=I6ROO@y?oiM_gQ!21y878WDR12pn4*1sE|YPN6e^VZW1XrA?d| zCW}_#wpP^tS~a#TsanO+_j<9#FsSn`dq%Z{4O#YmK=s0%DVmk*3kh?Mv(BE66I1(V6_|O9=xsQ^NJMtVTv++{b^?r>4ju`3z{9;UHf$6T*>N z{5p*nLFcrv|7Wt^$4hbtrJEp*Fn1fKe+!Q@->X!TQ2O^N1S~|@Wan#+7QZ;nV^o-4 zSXc&iiJcKp31ZWUJ3re#ws!NY@GlC8i*z-e>H|JI#Eb^QA-o7hqO zbMQjq2?ugZ=njQ$d1Pjvy>|7xk1nT;Z5*>5^5^9nrK-)XWe6y53nLBwG@RkHo!VUu z5>in2D>@2v?#`pGU~~cetqD-K<+KGdGTcv69Pf*v(Cv);;fDT6V^!!@BfsZzm-0I^H|GcLfK!+#e7Y`K!3z@l-Wc z^2=_MfKjx#pD3l_Q3IVgV{b5t^xSvFk(Uk;boFNxEa=PkL@G zrgJ1$8!S6X!>NV3{2E2`+5dC)xxA}+t?qWRvX_4DEBe^_77~10NyzK1ZqQf1J7-d2 zaq*Gw4uS7j)%p1|DH>;*Ox3va{cku!^i7|fn@nY>d**0CY6()%k7A|;@%KN> zDtZ#N8?;$!;r0bl_w^5@0U3AOva0;3g5CdFdf~4G#XqXfn+{ziw+sq&yXtace`|7|8O5Jy zSUWU&d0+EQi+4(XruO&=uv{D2>FvUdg9dhz`xZhQzkitdietN;F=vl=4!TF7eTnuUSrau{p_I=LFQrpzT(UFYm@6-2~ zKM*tC&GNska9iLtd&-%FKfiqfZ&{6l+m!vIT#D?)O7B*h}boj^bd3 z$rT$xD@Ff)<<^QC^VMexDPn=gS$Q9wd#@pqf6o;aR>^l9x!E(Jm$j3B)LpC5@4cP) zeT_-4>kVN9zf4X`OUQvr%D&EV@99v!F^zS9it<1xfmUS;W2V;ks_Z`sF2bepe^lY@95DyT(Gb^pls3>gd=P-6EPq0(CZ)2j=hvNGq{=gUfU)|qy7{)rzWipcSnNoZSYuJA?IUI0xT|3Oa zbi%RQht>U8oY$|lFlDV;glvgMtNzy!-WNY|QEAJj{U4o6+uD47{iw44T&ZxwyQbU^$QRcZMNKRG z&PP14FxEgZPv&ngDm9)G4#l6lsMHt^cqeaAWGVuijdP>dN@~uta5Uu}e4KWzW z!kc_HEm5_5SkUg0ZBZ8RnsGf&voSY78;_#Iexl++`V&46_(kMEiM5@%+wq7ObvfOF>mf07hLHQPSo=t+iv5#I#Yv6^$D^v?Moy5$+_M%2^<`KiF%O8BM z2pVhmjIoDbHGW^$9yoa+Iw02`d)e%6jwkzbimxuYtU~n|9`W}a%{6SS`h#GZQJD-h zgOLALO9ww*spm8=Z;p3YgIG{K%c=VC>2;m?aRbq9G8NuggDXh~i+>SWQP z<8tgD1s@jF`#7F9U(^&@d?xYb`FvCHXMOy)ou22=I%n~axX#eGDM4AnNaOAzCs~BRjY&FBacT}{6aPQz2b3ze4wK4xb9R;&uX^7T7clXdYx|LyU_WIiU-;3gZAYPqo#ZVk ztNTT&vN_p|!VK*XYC^}pt5v~|F7k&fRI81)N>w_Tw0vL>Sf3k7isn75ah(q?psD3e z8(?AMd%4uya%y?D98(=fVkA)Fq!;F7dB64Qy62Diq39bMc~}Ebq{gWHOAvQi>LOL? zZ_}2q3LaK^?b$n)-)r_;DYBV^WZ3y4r&`i8uL^76=3%m@ z7+&OB?beK>bgGPq->J8x_dYR*CAET=-8P@LOb#-mUDn+VQXaebAu>ljA05VkOw;wJ zi>+`lr=&KP@%*M`Pw+qlb^866SfY?cWj4A>MH_Cn_&vm{aH2j!&i|76;9Jv~2|Iqf zk7aFRn~N)dk0G2+Q-pC&0G?xCmxg96*Wl6~gOnV?U352DA}F}tr|Dw4l~SZa3bSJI z>b_$oFk?D%D!+H5Y=v~PjOQDO)(ip;I_6YfDfRy%hSn-$?{sq3ChuI{LnXf{8}4eY%qXlrfbUY2sj}2eN@0 z`Mq#!DvyvsspeqI(RD$~QZ12G63cRLwCq)D$*ojrW8wz$ou#q1{z-yAD@jvp_6L?H zN%<$bnSGPNOV3gkaS{t91`RwkJB(s zDSlPjv%5U`#o0n_;>$e#HUTsN)v7WFy2RTUQBuJZ=SgW>z(R5za;?>i#bsA!DWtXN!1Gc}S( z+X4yOqCw}S=&^RRfxzQ|EFCt-I~R!hqVO+=M68a!SK2*J%E;7k_&aiX%J-;)_SGVa zCwInW(e@y+vn}O0tzkf^!|D-J{qT36whl*`b~BYuPLB6!v~PR_%0}tov%%)a+jEb} z4nJh?FQN~wzWerti?rcAHl31hl-rfA0{`+#?dAbQip1|YDpSLZ>(IS{c{NlD#Yw85AJ%lJ`> z$-7pFl*RXA>e@+fxdOxrjKYLmvSVs%h!{RjebSQ~s7!jjKB0oHy`C2SeJp8wwVICx zIXK*7^ZW*Rw{x5r((~}Q0O3>PK(>qq;*q$VV}2_EwBK6TXL+A7LFiOk64}BVbXXtU{@P$9Y@X*DPpuIJVp*OxWiaAFjV-JH+DVcrF zy~)F7K-K|{iF-+Q->q2Cq?Ia3jno#;exQyglhantLv$_SAfY6m-d(lGN+qS@kw#n` z(tuAykV7vjO}edAK4`rymTkt9`l{UVX|A@#%07}wJ{qwp@eLMM5@sgIkXwyv-?(+G z?|h17*Wjri760tvwDHTLKvW)W>DthxfF5T{vvdD>LEfh1vZ0POzfMjJmwj%>n~ZbR zZZr%>6ZeE`-F9e~P0#3J+5PB7@#2+wD^4=2?Hu;<>@xd|H#@UUv&5H_MLNZuOx=<3 zP?R~0N{p>%2B5PEXuZemv@r^c6C-ys=E~ zb*e6`GtYOhz3ULj?s8gwq{^-{zwlmMwQCt4StfGb-8c|68aqY)9SO(V_DGD^HnYnx zg25`Jo+RKG@05IzVU6OUP`Tn|?A}TL@X<|i=1*;2Fv~T+;V{@FK8!mV^hb>{`%u4H z4M&Z#xKtGC);Ia%%mSI0cxj>BxKuDsq&`~wNoEw~hC(46#%*@a(ekm_%*Fo$j`ql>xmCl*sAk#?P4H1U(M znHw=5**aCD8DHk-+OxP6c5tYoE#3USK*Cgd8E==rKCU{=@6^z{#vRhzi0!ojy3$YC z2s$k(9(;yB-9aDFLl^DL$0|a|cvVvKb~TA~=0m+p|8WaAB+4FCX$qg%t|V6*OL@(t zDM!uZBX3d!88u$8?!}V%+9GsWvY&4)$zkU4*{LgAWu-(g`491&J~-OB>Lwzq7capY zSxgpRwJ(?yMSwd5xmU1t5JTt5}wR6>XC*j{? zP91GkdEbx8Ww;NyB<4gxFLlh(_g>sd%N_e${`BoXqD?|b$^O+|JC6ask`tC^mfQWq zVlJS2-wFi)m~OsZ14aw>+D)l>KH#jp`aR06G~zY7otJgf;7d)sLc~1EFzj{jk2;#E z<(~n;z9$wV15#e650(R;>Sg0s-z~JeD(7|D3vH%GYYsPbqF=%*ky$w{rGV8^GT|{X zDW~IB!K+)D|GgVE7wNSOH2~#{h?HI7JEA&oC064dKiTOI=YEk_azHI=?)IBx_R;Ly zKJ7xMRa)Mvo*ZLwnQT^nGGcn1l#e-7#lBz8@H^52hbgCm*`@DcI|mpl$%D4J1M=xbr(QkLq)tJ#iJU!ptTV4!(-2OJbb5NH z=FA2N)=?!QMp~JDf`@QCks+OY1Hna(I-mRjTC1@y(TVZ<1x*-z#_aohmh*aJ%6+ z&zqA~UU?Kx&T!;NAlyS2$(<9$==j~TLwnx`b>>Z3`ujTj&xr8~TAKL?g@%hbvmF8s zS~Qj&v8vu)PCFtOT0hVCr#U`rIx`TDFuq=I`lO&kTrWdHBnPLX4d)~geH zx13n)^Zq1B%1apd7mxJt!VC8bGfm_DE?^v#zh-)HmEW4h<Z@&xvNRAGjW$`t+ zNt9Gi7a={hs+_%iuo7E+e?`tBCS~yKYHfTOv2FPxOF%`qu9ae`lKLlYhN{lA<+QRG zaVMSm!UOZAo9e7~pz2Q+gacPU?Z*O1&jJXo29@@7&*%G|zD321+rav+r0uwSVr zP(8V%f_~#yR!CCnX$FfK!Ex-emnVjN0%D|c%`J}4*Ud8TB&b2%ij>aV8b817-23Dy zTz7*r9O*#lP2lX9g*jxG*(DTZn414bBhT)((Q8eDrs+A3nB~uR>6u(kXnrdVX?lK; z%g}IqeQfWpeC#Bmq(Hi&h?bPa9JQUIcTB6=VFa+njkj8^Au%eb7&Uv~2DfP^efYqL zQI5n^05iJ`=12%-z442SLUsOZaF<6jYuGE!hv=Cvz8DI&(QI5w3(}LHd0lj6PA!@9 z@|Af`|H+rS(QNX38)M@HEX9w<;MS}|%AqMd1+B8qYfCpr?4<^aGN^^H+_q}pbH?lo zr_wL#8`b#xHn`v=yZc2jL^)sAX{q;A^7%Cq?nvak*5%oQ;Vs;Ua5uclSP-zGz*K_ss zqc%-_@l{`3DQgm;ttBG*iFVXFF|Al7&eo9<;|xj|KV^z=&}&)Y6PeA%(1?pxf#uCx zg{aY0&IJ{;lCT}8wCe-2Z;Z>!0~Z{!)fPA3iyP7H&!P3mXvE2)a@4&RD|DeZ-=>?~ z1)sjhJi9v3G+ZH@_Tr6&S*!(tha5WDUW0Q&E)`$*&;h15ZWU8zulOB*e>&nT5zwT5 z#T-I9Mf7st^Am@4j-wn3q*MEGu_78&ydq$W&1}wf^AoHCCawjFpOD-Ep~4hI%BDl% z7>RtG_~>dU51H#5RLP3OoveEweT*8<;BP__T)-!jR1@1f7if*C*UW3}3&wEIkwb z-SAnj_DkFHDChC+nB#CiQpn}3=`lSrV{j%rgie)Xc7Jkb-}#3Hv?MX$_tAO?pR(+L zS|>Z=$k9#-{b&b|Y=qFkG{mJWklAwJm#Fv+iOh?WeR`sOhhlC8$he6UD>u2rQ35!$ z;T3!K6B%V<=%1Vqs%}KmONDMP4z>@_Dxsmki>I)_w1NIAyV^OCyYCX9K9m-&#E2^M z)hIw75ixCTbF09tBoMs8gh{KW$2>9h@4Q4dw4=871(pdt)$*dExP1e;+Gs*K_>5&D zG-mV6T5_jWs&U<-#eItk7owRcwQ>lnDtc3DOz|Lp;X2p#E00Jfd~l>M?AotBe;k8v z6}-D3QT9HL{TJ|TOQz;$d)wsY2lDO<-Qw5d+BJli7*}nrnP!GC(?%UQpZljR91-5| z=jT_}&9~03Iq5blvPjHAIQdw@@;qPak0=%6Cl=!gG$m7Mb5iNOVHx-HOgQy2JnVAD z715T1F|Hh$X%o|Y5Z0UwCZQI^WR{F)A2el3XI$jTv>9z z{4tYG38Z^M>!P%!NgE)&*m|0cNb%9hIUeg)x-)!A^&YkO<*3`cH~Erbgif!(haFms zS1;vt_RCn!aENHWD78^!qB3J;q4cpnH>DL`-H*0|_FmP;!kNLrGo#$Aj4pOgTSX18 zTG2%{Za{#7V>n;Jmo~g3Kov z(og}OZ>^Z!n6TPZ9Zk+9qOVITaa=mqvfBBIX!oU}BVjxXm%U+AK8(FEjaoD0V1BOd z6_{=?cgcNopUKzch*!9mCZK+cC0g1^L(*>-Up|RKKGlso-M(Gcf_Jf^&HP8*bMZ?> zq5+wmruvzEsZ7t-s{w|pQ%RZJY8h4v0r2#Sg|KA@G3t{Z9ub3dE0l}2lCXz=+vp&r z*OkNC0|X;1rBt%n5>!wbbhc2>X_uYIW6}qvX z``!Gw#+8K186TrL&E@WPq|mf1jVL!&PKFNE=Po>U1~m{P&D7Sd`F?F-eLl6v;|8=I z7WeOFuFBl9ixHm`%JPy*jyN7D$c$V$-W*iQPofLWEmMxUVb1)U&*c104Su_km`QR= z8>tV=71egy*WlV!Q~Zjw;-zCPG+b;(2b3jJjB6> zIbbfkhJpkI&|q&w7=yI%!<~5uDsCeX!HkaOei(H^(Mti!sqe0V%pehgQD&su^|M`u zd!>N<$B1jv2pQ2_SK>dwLh5D$Wj`YO>_1$9YJcpmBqE+BBCkj0wv`30DX+L=#B1W0 zp2>S338xZ9w;`M3ozU9}Z8|>av7*%5hG)XZou^`|=xyblIqH=xQz<6@0%1Tcjh8jC8=bhkZ#k4L$J@HD>aUDjR!JWtbI9-z<>cql@5jR=7Rt>bmoN0kVNOwch?R z4ARS1j|m292U0#&-rj^W7m>1cKNJ4-31XPjFEY~T}=!qiGY8VYz1&wVbGi~5$LqPs*amgE3TzR(r}W6f!&d<8a`JfT^QX& zHPyZPO8-}84!vO_FXvdPOLnh(uTLDsd`aR@e;(ynI&-!9n7P5hE8BWrp?W1Z`$=kV zDxG=W(I0#(X)*ISJ8RQT{xdh7mAFTWOqBt4&-xQoX~|)aL13j%ivBwD|JcXpgwK6a zKWZmIG3rm>^_SA*XoKz_y-6jU%vi>s?h0fBJpN&1b1qQCw%}5a(x~TC7g{QxPd{tT zc$kHG<>J|m*I&xc8IcUD+Im|>yqE6qXt?HA>Q{i%BV2wO!5~Ag=0;PXmLyC7q}%xS z43n`bThCqd?oD&>MBMvoKl)1XXzwTh6IwuTBAuHdd~o2RQJJ8Cn%LO$5lV4XH(LpZ zlib#*@6}rc5mHU&>e>Ii*z2jjoBiI<&Pyqc-2!K6;$70?;U}?7a}wn)iKzXq)l$GdyY%B|B#MjODg=8qFN_#yrIOvL?dgz`Z{1kl3*c<5sffVzRtK`a2 zl3s_X;>`#f{l0IrO9iq!96Hv&4`fefbL!pih75E;UWk~O*lgiIR!Z-*SFAVvY-p_E z-@{m}W5=V*JEJwU15umAOEalLv3CJ|SpKLcfqP(JI*sW0?_$r4f!}e)h(oAgcnDO8 zkET%FBQ&sj!37ts4i(F3pRHF$8|K-ke2pFV zZ``r$4P92+aR3p&iF`wXSwGBr7o`3t+{`f*$~t3Vzx1H}n#)o`a5%5+-VEYR7$_;z zHZ{$hl>zCM51%IcXzln=;XRaKOczuVKghdAYH;q|X2e*jBC$+H2S?sE)Y4x#D>nFP zkk0#hbsz(0zrFm2*Kn%#VDh~l(~;u2nvz!r0?$YIoMYU#i>COQMW-*u_|C2@Q(p6x z-J3et3Hg0}aJqo@qE_D18`0BqB)j$ANJa4#~n>n{w6uWM9 zSPILi?W_UqWm;VLCz0>!6VO4IQwI$n9zxnjOrvn$K-y}<){R-Hc4h_ybO91^%biyM zC`u)80^@x=_W2!U_`!%DtM42+&vv<=Y7EvzL90^q6eq*TsBvVZ(hT4eD$P#@X%slLVd@AVhskK?> z4V*WLlk?0{7D)%ot(}!n=^Cgvq$REhG*<~IRD^P-M1v4az;&GXoe`Zvf3gQkP_PZ zpM}gW3CevCd;sinFnWEdCk2yhxt_M^(D#sY>3?!c`*#k94$`9w|V8?Zd}25KvX@IpUKa!HaL=|tf14~7MRiOw&Zd2&;SEH@LYGKt#_Ww%SR=o^h)2niHppy`k`VszUfu9`-_&)h7-``xvT)<+|$Qa-OPB)!Gtw=ToY)o+KT714I`Q?&#N)g_My!X8F|!VaVBFaQiw>E}hN zC%q(2sQ-f`9YEZlp@5E5QcT~05;@&WT-P)yyj0cp{u=M-n;cgNsb4P~?P-g9xz?uM zx_*yADs&ubK9<`V!j9_n$dGXyF51?S7ONkIIduvN`{+j_-Zh*Or}1|iZePH+eL%do zroiHr{vGlD*oF4QQAp6TGa{;iI*fU4$^D6Y)(EPTTByiHVLlLEt{4q+>$P-^9NPC} zN8d5~0dU(evhWWYeCc3907>B?PA6Rs21#$a5Zz#B2G|NvKUU4Dv7B^ znfe4=y@12)^!`@qZaeSZbsY{(bYZH@%k-CR->hctlO2D!L}+L7icXcC<#C^hg1u3s zluS=(1ji(|Tj6mr~C}+wwd-j||1+K^fT|5@e<{$j z%G~CTuV2p94!(?cb%s7HRBi$;9kFS}RYWJFF0vFLGp^DORq!;swgpcrq(}u`pFmr* z{#2FLL?_eIr}?N2CmuN+4qZK5=0eU^8p2V+yS@CoGw$)wC-VK?djL?}-0AVZwlRS* zaDUfDrl|_r_H_Ug6yFKVs+|=897x5K5mQ~vZ)=7+ zApe5?!q{qv1>xcy9ZqT%x1SAgRZ`FRO%9iTTJHSxn!gsQr1|azsxz+JRb}MJ+i=lg zq9H1uiAmIFH^1=Rf}!E6qz6g$AHmp$)cgImSxbTwoaT3CykDXw8l3Q$T*_va6DeW{ zjTBw?-qv{@uT=B@kWoZ4)-R%?7DsBoIL&TCO;QR^qJH*0?~Q+t<6Ne}qH)Fh0-E$h z<-5{kNJEwJ$V$rlZwV;Ra3 zasa_#cmrzsD zNLpU#9*r>NH;+4*6PY;8;+k;J(5N?1{0B}@pRzK_+jwJV7YT;%aNsj;+(R#B6{laX}lDRgADgi zyzhd3{Fcq-F$rIM$#Tc11iGJ-9Phb)uMu-ar621cfgDj^k9>>TW;to=ceMO(718Qc zBzL$QEm^6PHm116MzWvC)*fp;; zq-0cX zq+eW6@`J6aMnKkPwc8u8lMW&;q|DhO@}c=KhURC-3xgNxg6Z}OBOaYp;IVK7y;Y?u_-an z0!b(ff4+uvATM;Vi9n%MqnO)Gl>Xe1-2ls5DN$Adg3)ro1)d61`kukE2g}(}w=nbXiMR_WDzBS8pdx(~){01g*o1few}I!S zp`K)y&EL?isFA};$LFUkS8>VVQJDItBLt+1j#{t&G2(rGf$X2>W#fd_;A=V~=;x`9 z4=W9w;36HYRsXa_CoWA`SCV_uL_GFKI^wa5HqC2@pVU8DQnZc2nqMuWo`0SAnU~y5 zp`W*6po{o5H!qJHF;AcI_28$reO}c|ICv@#kK4fhacRe+eMgkJ3L{w&@}G?yE>0;} z<)0uPWS*i8JkUTDho7dKhRi~K*~IZC5R+#+b)tD(=RiwZIVy~JHqOMeNkPB}O+VIE z7jWhW5chYZ5Zs%SnKy5wBF)w!mS;H`n}-X-UR6jQa89-&%pd(T`p^H4UeW099aU*a zpJ0<4b;e)8K)1Qch{2d#gXP0Dm1Z*~6AHQ5umWS>@{k;**Gt)bXwCKa3? z7zSlkfW#EP*~yw&m7i}68!(d9K7c8xmAZV%1c-24TLKIlrFhk|_(aW?2;n+V>z z{?RXw-AV(3BPYR26TaD*I%T1?=eGd=5f45Qdhe-8O@;6`r&^pr*Vg0YO zE(Fg5;D87{ghmM=3IXcSH&;ve{ISCj-dhD$$2@xR>V@_~mz~L@!$`m*+5*2!E^s4{ z$4^ASFpH5qm3p)*+q?2dez+V39e^+o+2E9o+XTsPtEqmit;p^Ew%Hdk2h4X^D(F$z zqn?+zD##a{W6z7_A1$64z7fh)ZrDPM{K8353jxv=OyK1$i}5K&GJJ&oo3K7%`WgU| zP}`LQ$$(f72BlHz0FT!s7lp3n@0Iev6Vn7fQd168Luf;w;rK!ypWkc4Y&2lySE1`Z z)~T_fp=pd*8To00h^uX4jf{w};Ftph6zRScgAaUETkr;d0hWgMTL-gZoBD9* zV9@0-X?>==Gs6%B@P$0US($FXiJYMWh(uCvAUDX%wh|cQy4?9a~-5w zw1TV40mfnW<}y*)p4m_Q;Is2pO-)VrKy!xbe-`^o?(F-Sb9AX@KA6cJM4OKTxrTxZuK+b7y@gb4N3D2aQu>Ln;O2hpvgr8!72of9# zQsC5fc`^486@h>9yUae`v)l?=*7NE+JbwImK<%o3@5|EQau05u>+lG!0E>e1p1#t| zBp#=bA6S0ic${TvPU*W&X zS9^4L51>L?34G{ENIVK+63g*L!1)V@2J@B%Kj*m3K4XdCKqxCl7~AtMu#4M}OhDU; z9A_{@kHw+Zu#aC?Pwy0{x{8iYy#xLM!h@DwR*$Y71Pz+Xw^pV!9D1@it&+6mfdj+E zzG|=e*dgJMc>JedsAuIdXH8n)`h#8xIj^}E?{fjNj>CoM+0TAL#Ag^c&=+D2xv~+R zo0pw0fXw652X~URzN&655^~De(+5hV^!~_rj4~4Gqwl>ILnz7JYYGz!Bs!WUdWUc& zmx^lan_{0aV;U;D-Qj-cGie!kgC z{!qcpK|%fT69txV!BtDMgs+HhnR%{QfNr?h%RV?M6{C*L8XmtPc&QSQyH+Yz)&AbS z`1C}$eg6#We_`WDz><(D?=w15xHu z7C|E(gWMueng3p;fF1-L^xF%GR|T3T%P4>j@%`B}q?GJ*uEQsxq+fO9+Ss`mP>`$@pZ<&yHC4$MB;QbnMTsT1 zJAD}(HK076SQfkSt+Lkq-75e%zrsEJBf!{|}*PR{q`*^lClXbP%Ur#``H$PETtb2bY7)u`Mvjl;=LS{ z2~B)1A=$?HVfGbJclp#CF&tx#i+4eS+1oRx5xMh&U4W8fcvj;47zi_$Tnm4gY%H6I zE;>DfwJvYAH}S74{9wMwwb$D4CyWUE*$z#V^Q^E5M#U89G94hk$CCKPv)`R|>s#WU zQ-^r+58+c)Tb5sy$I5#YOj*vFD$6kX$ zcE6=xE1TEvVSKA&_0H@wzT)Cb`>J6=wp@k{`s}B6*a^;&wCjq^Fgs^-q_dwsLR`Tg zxDDh@eL3j0^dD966oq{F(+Tr8yQiYUa30wwQcCad3S-}F_CNyXaD~7YOiKE@dwQ+{ z^w@U#wjenVYI8y4?&w_*XYbLE& zsq?MJw-)2ALw}mcoFi9^CmBZjXpqs@UG#yIgGJ87?kS zW`ZxTj0#J0!vl}XR3!jjAIePUU!WpYQU4C4P&x1Ehue2hDpa2D2dczWJ=zbwO|_ux zI{9Gz5viGEizT^#kq~Xy+ydo(#;Yti4V_FpLfXNlKNoQ{!)(L#vHrTkKKYaK!-ppY zBuiTxIQ)*0;M!5!r$p6?7&RkU$r=Y^BIe7fP zHjNn&;w1hUBiY|}t19pJlN5p`b0;6wEw!$j$5;8o@*&yhIB`6$npjCis|+w0b*Y+o2>i1 z*+*!e1nWF@WPzMwLLy732e@hz7Gk`+H~- zAo5Qk*_#-W)wA(?d~8AX6}!(=3mhp%B3G2Y2ke#R1!QY@YFFmP;hVw(Wng>DJ?w!z zM|03~(X^+q%uqoe0nPS@H|r1A^PmUH8CENIhPwT=*zF5`otH~wLo!}-2d$6-*Gi0Q zvfP6mxT+*W&qS_C67j$4v|ms9D*gPkHF1v?GEW+iuw2GwAlHTqEm?@xG&D)GSr!k~ z?o^Drjo|Jq4?2cizZr7T;&tI3Y!V54Jg&)*y~3=){HjwiFmWe1S#L1wMhpN~jG7pt z(u|78qKP1P1>-u;sFFI{Rn7%sFn217v%6r&6>F`%oDX2UYtDdW!~Gib5~Z7rZ7IBkJHXHnb^)?6ZPF z*b45`@%G##+oodQxo$AJ8331t%%ByBxeTrlGHY(q!uCC`uL1Pwp2O1-6&;Qr(DX#izBbztl<9q6ZsX68K}j?$?MIe2LA zP?xQAkN>3v2)ZyCr2CW_Ojv@xavwLn2igRtUMx#WU<_&=a^5y2$Vueu`rH7xo7$=Q zqyy50RVncO_A>-)qSGSL9cq#@W)bARL51a3q1mj1p9A;t4J++*M`%()I?Hsj zl#{`2Fui17ItZJzN>o6}=r(=5-LBX4J~*dD_;Vw;Pt9_r)|OgO1HPz;JFE3{CYjf- zX%DKknGa;n2Te`Mbf469NV9L<4c(qPc^yMU*5bfvdC>}7$VON@v}%5%{Dx-BDwTb> z)@X0+%KZiHPa=FV@6Tk|2bF9Co1nScs?>qqC$wu*Q>&+0y9^s3bpsM{QMEBVlO zP3lss$_LMJdKWwpo2mHJ`PBF{)6$sJWIfV(v}w5%=?IR~Ambr~p^B#Y`O~u8Ww-O` zJ3G!e=fp4x&Spl5J=gS*v+Yx50GXsr6FP$R^7xMZGn8L4ZYKUmV+l_P%0F&kRiT~9 zv@@>BNSU4}bJu*ogP91btl}vFKa?4J-FNMF6as-z=VGS!#6O9a%H;g(?EPKnhJTne z6AY@vhy|5tgE&HHoSEx_E?VqbC?t06fBv}oCA#R^JG7#G*UmHijb)qyy>a4=#Z#^K zbF)zs7C2tNqHcz}i3;c;d1j7c=z+If!pm5JJ1i_-b!)0YSM1o(QrPClfZf!l8Zf0s zssr9#%~w;heV?w&0Hs~-U2eX?4x_%1nzGAETJinecW32z;)plagvFUUit^8sz+eE~ zjYyZB-Lsv*)&%HWY)a9q&C8#L7=_7Po&B$}to8&2s@8ex$$6cEL;*uA6!gY?(7`v% z$ECJ7Y(zec^!grmOQPzgH6{Ub0^$&VnLu21Gk6#n(Yf)N6jc4Ir?lihEwx^Wr)pXX+jMRvb3^H$u>6 za^+U0PLBslf@>+9ceSj_qHPUuWmK;t@1H{*&-dh%|d z_&JV!+11~3jW_caBBA76HGFdJ$yxssA7@uP4a5UEZWiF{EhFjlD-;G^k|)^21TC2-T=2>4-09+tG=5O zr_!|XCwoJGTK_fQ%y^fnXVdUDx3)-WHsj6_MTy1@sDh-Z?$tIi0iLTj|s_Ngy%aTy4Pb-P-UO#k)M87@Y6 zmxZ@G9PNl$Ap+4uiv7AX21r!Rm_!2m<^vZIfYOAdxz4=wM_23Va1JX->JxA($~|qV zJK>?0xuS}SR&-}KAB3_7+ujq2n~;!9JFCmw7m9W|)6Bz zq3+X!)5JD4un~}F?3Aq7bC~E2(Z%!6&jk0vn@SgDu>Wj9r6~IcpHHHKf_Bld{y32w zH!DNTkM2NBOxhjP<=KVv_qtcs;%IV(mhr-ezNU zf^-6p35$MfY=t+@N;>+i8LAVAtaK)E`yBJA>AGlntEqEzN4wj zdt?%34U*Z_F%d$-EICqqO{;e2E(`1Zq4!$fcmpe}_q4xcN87xZ-!p%gTvpTasReG%Z_NIN?6q>+aMVraIV#Gjapo3m%YjfEyfNMFIJw$FDws{CpuDxRR6$dkxdf;3R!RL;8M7bc4Hnli`n{QkR^Zg3)7#7vnY||v^DV<^?th$JafEQ zyu@&rx0-DB5BWg7XWqkSk@r!>aTR?f;x8N9TkbhqUAqu3>nI>^oBKHTY3|_dE#Y6! z8F(nCeJ#A73`h)iC?mW&>Kg>l*GHPA#+TE5InM0#Tb)IRsmwv$XZk({$om+w?lH` zXQn77N4~VP5)Q#4V5{8AZF?FdnTzdNSH^PBDGU$cdVPvaxjR!RZxtDR*baY=bKk_F zBD9aEvD{lry1MSDiA)|{j|*HKVXS3@F6Uo7bJDHjU+>6=7Ie97j!FA;`sHU_$+$7V zPVYBL(Qy|fz)D=gaSEO>FMmr`>6W(cakxYVe~=L)M8<_nmg93v2kGRON>p1I#DR`Jm} zoAQSVi8&+LVH8OU>n%?4l-RuKBjOwT$i5&j@87rx#069pA>dKvFW#0P`yWw)Z51+W oq~9TJ;o^(`2q;jI_VBHQ>a|*i4d(SLlQtr>gjP^N5EM`v6_FrOC5i|rlB48Hj`xyt5CKsUFl&QI5(JSTIfI~p zfh;+TB01+cbqFeOd(HdJ=k(01e)-W$PS|JfUAyXe>ZxM&4H+r1okUbbI5;>vFNllC z;o#tQ;oxi|Blr!jc;KFTjDvI3+2*{8jk$w?v6(&&1IM}5e=%^JhkxrCqYSN3<_zp? z#(E4KA`I;8I)!8)J)&7j-dcw7#y*h6hnrRv7z@j~QUh*4DT-m<23j!%N5od0mv*)~m|K zdNxL@&vLS@O%HimT;JHxXzj}!>}xl4P`ajuRv26K+UFS9IYd`}R+nXtS|4idd21t- z9>#uk^p#61yK05Oz`*BM40cZ64B6TBU0Z!m^e^syU!9dcdTna|$qQ@qutS;It}T6a zrq(u&>wBS();o)ADa=yW3}tO?tjoY5Y-D3@1{Y4kKdo)7FsAzFFlHF5m4$Gyt^B~9 z)uAjBrJ&b2m0qo4MB{hF1&8Op}kZllpqYqmH1 zKHT@iDuXeGePL%?JEkYs?YVYJ*-x!~Ykdf7jIEWf{@Pn`e82Derh$04*IxXqfoxD# zhWa*J27(d6gVyJ{vJESjR*a7Q0GwRg!hfj6)*Wqaqv5Qr9!@X6$){c z)sf)TtPZyN(CQa|@?jf&2ju0SycT68N>^>#sf44jf}E7BP^i+`L6!DKO#?U z4F+p>IX3y&`tLu*igo|}IaaKnnDrC#b68k+=>OE|)^P9_*-%8^&RAC;tO&mR&#~Wn z&|dSnlj~Ujll|7i=r6Y)*Dv+K@Ad;o_{Z9hXU!e|4)gK+QuCcNGe+pqKivIJ|Bd!L z_1|N^f3o|XTo0#zga55V=mz+M&1d_GVf>UOVBk4`d~4uPHtU(g+O?ku$X}-oD=&%~ zL*Bz7f-nvk`lsJkj}jIp@xLXhSO>B7TwpV`{8y6-?sYcvR|EYzj>`UP@$nbX8Z&(Z zgs}eaXQd}Mn|s}AKl$al|NLrN!_NIn|nf?dN#)-{r|3<;Je0`H5w%NZ=YXuCepFElqc zo$lZ6{TJrm?1t={%)Le^*Uj{=+M9EoEU(4)lk3!JeV|`xZ)}?0zwM3P-W;3!@YJs{ zH}@uUub-;_25bM?3ECL$Un|(cA^7K* zZ9NA5Ph>d1R;PtS@Q*RuW}^DHdfQqGv>{Ph-TD7Yg&7XPKgMjE3CQ1Rwsisj7nuzX z!9T}re_xP<)_@=FSSx)3KXtsVkY%{I-b=Us`}aP(zCC7W92`2F3nFI~95e@8cidM{ zth?4JSx$iKd3e{wyT`;y@eYXWmQB(leRlyLPel9viJM>OJpb4xTX;pAj!@_Dt-IE{ z?&4jOwc7J|sovf|ad{`FTx;d?*v?kdGM$0=7tZ~e*|B-feJ%2%h46Dr7-t(EsnFVg zhH*y;y4uPb>2L|?uHdZxN9qcj6#e(#2m$O8LMI4Gi**T~mL2|aQHV02ljfA`Tnd-Tr_v*r9&5+QKlks98y)%a zAxmW7BC%Ne;kK!A-eHybslma;>Gl9DPkD;<4>TrEJ<4BrTOQ17cw_I;vT z9SdJR&hHBpQr|;&tE8i<`g(?FQN@$fx)<*L@rv8Lso~1D?bx2ItjeRHd<-c~9( zs(jyekBmQH?H&=6CA97;O)19ACr*5nls;|ScfZwnIG5#dzdhB#ira_I{ciTBkH~j( zT}SLdc}lhD+RkKHVYZ^e8M^_acXt_*?;VwH5~Fq13qE6;q?zlK86y8<2kp~wP<+?? zmme@GpE!FJZ>WmAIDl3Vec|2_zp%K`#2*h@%3fg`>WpTPe%j(TKgdJzp7Hy9x8dR9 zdRda>-adSuh}Ul5G2{K8J^*Kde@f{6ea2RbrDI!fyikZ480jpEl94*}v*o87wu80P z&iU;6Q~0#^+Q~yEgKE(wX|b;0x9cd_CV%Yt_mhf8N_We7z=PAcx*^YX{!-YJpUyE% z{MC*L^C!;JLtNfgL_Z(Gj1rm*u!#BeP%D-x^j1eE2lLtoZk@t2uy-1!9ZmF=?EA^V zflUbD2fO^%oMjukbrTA-mc}TWlk|yEEfJ@KzR&OTRiT_j_{m6&uymy5F!*Q`#BI** zcl+l(WMhXFz^M^vPDFVcdu>_VQ2w%;S~@xy%Pq3v`gjdfszY10>e8R=jeWJTl3TZm z#-U@ITBcRx)+GpafBbXsTZlXN)@^hcdA(y$YkBU`*0&1ava(v5*`Hf)2|YY<*$mDo zmdz*OpSZm^QbdC7mf%97>vXFH36}{7(Vyv5xzm#R$_lZ$etiL7G+HQ7C zUjp1OWr%iEYIgivxdky$k* zkzUMS1svOaW~5UoT;xXVl$wWIp%-CYhNZ5=W45q)4G69+_02n|Z z-ue$%?tZGsUz}2-D6SpBCn8IP;CDIIr1quz^3sq!@xBv@!rnxg-St6nZAP(5aV8KS zQs3Oz+nz|w864#_*#{0Tz!P`marN~;sUu`az`IV3>ttSKdQGZfJD0&n${>E{G~Uc8 z2tpn`M91oTCPmKj$q;>U%B}jO(l@k+pqFi_K{wzs1ed{y-WrzsJKAs%L@}<3N+qUX zX@GB;mp?f@w9~3Akc;KWerNcvofcSSfu#gR++ESAlMr6CIkM=b3r}Kj0T( zJ1W=C$f?PfHLu5Q->BzXQ$f9)s^P1%vmyLbgDu^IZRLY*IlPU>x&0#&x{BfOAM1(!bjqb83L{I3@d1O#MA{z zZarS!pMg%uj0iN|!PWam3`1PIyK@0IAaYFbBvg$8=zp5%Re60CzqJDgLD7~MII%G; zFFJy)mv0kxdDs?nImPuJz~s$F5x?^wdKndd2k=;~@%nE1LRJ@<+vWEe?@{j`u6bUe zh*FQGHEYSJ(g=PTb38Eppd}Z%q;A!5rY5w{u7m15{wje-0ZsrA* zRz_VV0jnYFJIyEr!ch5$*x1s&?%34za>Vsl=!C~9x`OI!G`r;P96sNY?zQndE9iZ5 zAF~M((Xb%r!f1*4m(n{}(CqC^^5ot0qK`MA*$M|DW7TZAwv*am}jS zSUAwd`^Qk8zwN{_hhvwMp6#S$D_Dtg>+Bzopo_*i6b{4`Ajd{TU6}*l?3a5}ZO+3R z(QxI~!XU;y8HgAb>U5t)qiJrUR~O67Kgmm9PSDK7GIM|#U4EwtHY~db#~=>450>4l z;2Xb{J6WfO<(B@3hpF)z*;uB>H$RYEmuYQ?g;J z9s3&RIzNSF4hT>o6lCk3cX(51CPL1!(e8i2VyG{~D<^2C1biy+*lrFah8x|IVI(N} zhF9uO_P45OX2yGuTuP+kG7;%L$)pgiosc*8V&gQu)G0BwFCOGhR7=>6eYv2P26en|*!%VCY`BH!+23XQ8+2 z;BU>D68L0qCIioyd^%QRx=rfh0@&9$6g+bR)|xrof>L21)ktfCZW}|H<(Q`(@H;mC*mPmxO2@i z75!cuGP=dLUIE}XFU*dwO?e_K&P|?_ySx3NWmqygKI?^1Rrrt_aJalURL;c*$LmszE_0v4MZ= zD57d*i;uzGNzH9jqkRm|g|G)BOu^1XihofakCR;h*ppWFYr7%2HP#UqlqR;4NiRs# zZ6qGvJMgXil8l}@_#ZgkvM>Y*N4Br00%#z1)&*Q7mLQ!B8G5kA^We2k`|-3TiuzGC zCZdX3Y$#eaDPHw{12UGXTjHNd>`SIj_K7~W=h`TRmP-{Cr%^}uupGe*StVhdXbG+B zge;PylAlni3~qtTq#1TxQd#`=_>Xc>T{J;tQte_R+g{g+!vP= zK4{X&tP$#H&X{6)eqZo0qk}fBN=LUtMESi>1wvwLUwr}wL76;!8)k2Toz)kGvyA>+ z%ey@)cN5%Tqd9ZnWb)BK&-lH>8<52V5gN|18sX(i1)l+Fqs|O>T{S>t7E2N_i4V+u z?y`$XbR^luN7h-uHas0fCE2D$QN?(D2X9GB5z8yW?=p!8DWXxFA_xo*_vPU_^RwWw za;FDhBPWKdm`nKQJ3^Eog+L%m1{cWoJ@vEbf}pdI=`H1#Dx)uKYxvPmC4WdLUeP!; z3Va71BT1>ILnnR>!3GtD9szbpnUwNe9H*I|Y}PPF#y+ru0Pyt^{g=(RLfMuEk}Cp5 zOE=FX6jgL>>LW+RM$B3v1Dv4WAppJ=@hc(hF==F_Yy_kg#pvD<$pK*IoEz){l(2-x zs3|4p!HLV&TX8cKvi~WdKiKAgX={P>9}8cq3_nlIq?!_qWeyM@;~*`?g57bdsYxX? z&L6SN0USjsR0x|mrL5`rcI;cl%9;EjtgUdizSsoSwj4(+VvMHqAlHXr-gGR}1D$B# zju_2JEL+r^7WcLEP7#*rX=K}hxWSEu-qdTkx6-)Hps?IRqy>-%HZmW&a<5S!`Im>= za?Ka#CLi)SS|PTa9Byw<0v!WDJ{f370|13tM}bG0c{4XP4_ZCNe+cM=IWRz_e7D8^ zp?v)h`=-75n|$VnvMYZ3ol+YT!Cg+g2hZ3f?x1z4+_-|zB9tK(A- z4Htg*YtJ3ckV+QOGZ0wRj)5W)!IXo%b}Epaw_dm-Wp)g4Vvh!L zL~?O#2A{LNu{H z*ZfM(B9sMkQk$^pM_O){<8kz{)ROXy3emTnWo51-njp1ed$xT7wT5Cr{dEL&%|V}L zxy7oM_7QUH-lz-_Zgv{WW+tVViJ+`y%g(}DcG#Bk+V<%|E(p$i+`$9%!!}?w-BK@c z*F}`F5JAD29iJbrctyG*9dMGXo$YIU-+&fWSY!oI+xle8rnmYskSxiwT8O?7s}OUSxbC%=CBBpQ3<&e8z`8t@ z+yHf$&t3Z+92=kY_9;spUZ^rK02f)1qF~jusqxfw8GSnvqA}lD9=DWEGowUHpG5Km zJ*`{(hC6(`CBix+TJ_Bv?xF6ITT;Vsyp(OGJlkfM>nj`5t`E!rMH$YjujtU4%w)i| ze=bydZ4_j^EXE_e_Cq!lrlLxB{BD^_S&n{w%WU2KvD3avw>Kh1J<}?a%@vf6>1@d$ zZtvykvcin3*|;5*Vdq*oA4MyCD-UkHaYgtvd5#cxPV4!s-2svQ!QCVM^l}e0XXxuv zmk)k4ci|H?Gox1sagH8RR__gN?kurh9Iy8aTFm`SQL)qMBsvD8(uFn^(oQCRJ=;w^#fFXFSq}8ir zDDonCe|t57t-OV-syamQP~(nrpZ;~-?ilTG?@s-3t`qLOB9%2I& zpxEd@->njW(cn0Q5G={J5o0kP;T|j?Xf$Z;dch0JNXDYB<|CTG*Vx?ASP_f{wb$isHM)eKk=!@kY2gheyQ2n*&zl;#Bw-U?_1*~59Jh80h- z6lolWbEgMDL&XBc06j>B3ri}Wv%EBKw=iRgWqJ@tnqkYa&;d5>0vzl`tO9_B!JeuJ zEOP)+B?(eWEE>u0G<*%a4xZ85x({r6rKG$T9apgI19-hTWGPragcSF{Td*wlcUplK zyWuu-EFaQ&L(rUQ{T$1O0AaP8(=k{?F3QtZ&&*r1YB%C9LODBVmuGy;+j1JW-qQXQ zEt_W9C5mOkNdy-v>k_oEa340O2_rb-2eDVhWZJ6MI7Vx!)!3JJaS)*D^4;A(Jmt?O z&Vb5rBH(-D&(a5fFw}OM;jF~DEzaF(a|h;G2W}n2hPv8ppkVUx@yRrUGAba%^noe%NBHU(!R|1ckif^G_&6E#qg!VeTrUQG~+*==>) z1Q&9a6o~tmJ#g_`2ruWk%$gP7+Ar%&iuME1R-HbyUf*@vGm7^~)*&36{X39e0FsBt z72iK((J%q+E6r}OX?JPwK0MNq;}B+Zv|nGX3q89X1gS2?V~9`!#5c?0Kx65Q|3TiD zP`PxeUX*UYlvUc}Z&ayhM$q<14bziz2+c&xk3v?PEw9mq=~PrHkC?Gz_& z0^1DmepM)wz{I&!^L5@5AzPS(l+6Y|zx7oPe$!KP1M>M1{EM$StR$dTB7(s95ZC3^ zn#gbiR6Y#=;IHtkk&G0iSj(EfpmQ0%O!h^zMuCX@_!rSrfjk&AlXARGMBhrm)&}3j zF9S*rZBddzP#8(l|6m4HNc2q!J^C&Wzem7jRZ;3kNdy-s?iv4ajYyLYYVTIR&R*fnQ1DX!yTBC#4hzB(x$$ioH z^3TLkpayd18oxNaMBP|{n@%`2l|FCxDtA$a^9Iwr2rJ$+k6m`K%Y@j{!tDP2`POYL z4o3*y7$dt0LDN?LlHE{CFH7C6mxrnM*K^(lqo~0~6%B`%RObl!MVp8$biDQ)vJdn< zFf;skR~MCQJz~HDV%8jlbK8Z8;$5V8?Kb=MQ53N=lHJi|;qnA>#P?dxDLg>Vz6+t3 z870LP(G)~Rg!)g;dk_ycum&}aFZLi4_5V(P4HJS=XG%2k&k`+->A+9HErXi9p&u2O zRcv(6VHJ&>c@Xu2q7KW#fhdS0P|ps$2m%D*=XBint{|PM;vPC!Ou?+Gr}#qQ6}a(b z@TQi%pWYu)y(%MrDWye2kHTUfi+V$wL)Xq&we)!4>K`=@CJ@_lE-#4EcWJqddN=z= z-NO?&oU6o{WnD~8=RVW9BmKl-a;|ML~2^2W2p*%ou?zqcu}Ew&AdQffT~K|6>iK2?|e^OBjKI#YrX1G&bh zy^o9coKhf~4&uSs(T@`D`NJaMwBwjwO_KBLPtPvg8vtyxj>!4}t~j{cJZ_V8*%yY* zftqR#bP!9pr#fGMpL%P0H}mD5bjx|4t)YIT_jyPYXnk1nNYGPsK+DB~t&h*xzHpta zRmSrDnkY$*INkWI)s(rr;h>pe!Mla=kmVF8u6=a1KDN0u1EIHQLU8MH9-p?3q9#|S z+uWkCO;Wb%ZP3^B zuZ(dO1rJbb!imdt|hGE-GNKcV!9u{yMYRTjVtr!b90>U+x-l4~0 zweE@#487Q7&8bRO&nWoIy2Rbi38CU%b{v_oerMttpV1)SwrfWAI?vQBK<~ATVPJu z1=3&=fNi4$Yc3f}7HIa)eKF4mAnUJ^1GG#+q*YM++*=pvo1danOlptELa*2$6x6Tn zI%onqNs?t(@p;qvla|k+o#M6AL=S4C!4FZdw8;RM@S7mELX#DfcaSfE3Qns)xjgK? zY&zOiLh^z*UOiI>Je!~|jVG%rKyb+j%CQ{YV=}P_Uts;C33P$4<-yHoYTG4-kcoGf@x*-CVU27lxYyVrz6E)H+#hQG#T>Y}ZTEIpFkh0T2bB^Bi5rQ!AUY-&dJ_jxNgTxosI@)16KF>= zbn7(jmFDZ5dJY7L+hIhTLID~;zV7m%p@+f+OXv>ytOO}sWd1-LyZmpcZ;x~}hawQK zY}lGvI)?Vr(a!L9rvs-EREv1;QGNeTLCS9LMxRkQ1!sFLDyab;N0_ zKNG(*Voc9rSf2BhEj}SQM9@92IVx{bPM$R-B(ON#l~FS%W4;wC1>!^|w_C&5Kk5gk6CQ9jD%=@sb-Dr&@GfqJQ1dF=Fp7+ z&)tjbon9W<${nJ!9s7F%(*9ih zPN5{NV^5e5BE50zzbBiY&R-rZG(j39?Yt}{X$j5bBgTOK+SW*t6)#UFxMym|RZlzs zi6o1W^NdI3+vju2sD;dLPpzj3Kh;PJn(w6Iw3v@`tu1vi-mTkMX{boMkul zMKMp;vnyqAI!?UO9c}?d%s!)nYLe&ayFy&2{wxdPso;+V==rm7285au0O_3-Hb9cm z@lzl&8N>O={CdYS?ps`mobg01gjIySQ5189sLLCWrA#Jt`6s$>8m91ZKS^Z7>%7(0R8lJ3FWd7=4v7|J6uxA+`l;HJ zC=Usw8kI4``?e;mduk^hKnGAGu<`+6D^MfVEpqL$L=vrwxu(@3T8PTBNKb+& zgjT)uhAqAd6O3a-%k^B{I*UureQMxxbFOoGbHa6$I)!83D5vCkkEI0nMbk>Li|O^z z`NEFTwW-Pyrh=Ic9H0F6%zLi1FkaExHs&EX3=ZN%MI|}ZnEX7*Hx4J3_&2V4)f%xB zs}e{_ySw#GiLRsVfug71y{V*fgYw#>3Q-qP%I+MoMe@I2Crzglo-dy}9xO`*GW^Wm5y?6M=z_-mq zji}3>S{J15);_j`oUx1dpJsJGN;j@4)|j~Pqo4pPMSu>8(S41GuXD=%55yuT7z<(( z@~9$x1tP{~T7GJDMH8{H)4Z{)ar%tpL^aBsiVQCzPmc%Qjo3gV3Q9rBSIKosHNJ^W z+n5!JlL_DO!b&A%ZcjLbx-71;&Cnqv!3>4(hOL;Q4f+6D(t0aGH9(naUXC8ijSS0( z+61k3EMoy5QUZNyD}--zH8ljd!GhpvW{o%^eMp{3}MwyvFh&NKmIBC}W{a18up@NLvGzIRN)p0k8rw zpsevbp(Ulj`|J%rZ@mxteVEU%AJ&AXw3nM2Qtu%BDIZw#8<2>ywI_9(_bBLlkGB?= zv_TC~%Ca%WG8xFnnxTTasd)$~s#rjaFcb8(VBsxLG8nvZ^eGlvb;_paHgq&#qg7BJ zNew^mi$!}mAmGwKM8RUV(Y03Q0B-C&@Tz2ky)roPegnw>0wbavo}VXtyVCYBm7A$6 zg9|BDDnRE3@@8R3@CRsv2>pOeCnbM*akz@;E7Ed30_3E5b4{rr_z)X3jrCVY`YuA) zPld+2%Mkb@4!kGqqH*ek{;`KV7|jiPIds4Sgq231c|%WSAcb3bmZ!%X>6ol|%0K)> zs`JkuJ^v27#qS@xqZqH=2%^7Z&EW20%tf1io|(b)cBCNnYI)(CVEU3aAMW?wXrWR9 zhzjgJpNo0J16Zt}9rWkDf(eJ7?gH{&ZwNamH*z86m(@Ni zI(!vL2Jz^IJVc!y==7o8(2CqqPD;sXbUPKutf~anZ+MS6hQcVIDc2Yz1}tT=Q_xb+ zKhxnEB|}5eH}>@d+V3M&f3m((BFs-Ndl7_Z6-0UG2^5&?iQu*yP(h>w@j=~V!yln# zq4na~tk4WlTgq7h)x&Z=9LmJByD#THV3aS0rre9m_>NwP1`4WqDkvjf?dM{5BKgtp zW4m>h3=ob4_}2)I{xyoi4b%ap42#ak?IQ;hy?hqcFLX59jxs%UyDXHZr>k{%NoGLvI@wwe?zx!jQ5C|46}h zWPLA8YG1HC%N;N09U@`5UpNzX&Zi}C5SnrknFnc6H3w{+0t*)7H>tFj0KvN)BNvIJ zt;u|jV;R0uN(q|gz7(wfldirJyrEZQa~v$~g`;K4-)UQjNhchg!{v0H7LHZ|dKd@2 z)^+h3yio3Y;_O;Qc!Jz^TP{n#t5^NEjsa*aQl4Ils{aC7IZ_5Q2St5|>j;?%lo5xT z-%PrNxd(BX8UQa!abM`74NG*kbOKS0W>-7#+W}}qfs)c>(zgW4?^H5$R~q_k?Nf3w>|`-__~giA_vogHErC z7OEt#(GLGMsBp#s7f3U$kM9`jm{kH+@+yCE5EE533OS&2+gxz!X;*3#Gy+`$1jM_S zm05r!005Xbp%C(}Rb^RV{3FMq@xfLoTw8_clm+wF4{B*!_~-{=+{`d`#Dz0uUg)A> za3<50O4wM2LKtOn!eoDYetw)*ew)DJL`{YW^`7|`#_~w>IP!-UqW%Z=@0ll~u+u5= zKd2NTx)Z6u1?34*k}O5{et{MilObmcGETB;Xx1QSuX!f0ykN~k71PTI1x}lYdsLH9 zIJO^=zN>a-8$Qqev8Dqq=Xz?a7tMR_Y3;lYO}g~}PJ7s|&3Qpd-5AcutNcqZx zTybRP=zHdbz0j{MK5;qe4a91)M@G7?T2S8m5>JTq z5E}0i7(eYP_y<*t)BIq1tIInOyml9RKDU0Y(^DBX)nuBGSy=_nH4hyI<{)OvI^2Jp z9V2Q90hvDpx@>#-WM97`=s_{EMNyd** zkP?sX*{dMQQNu|dEZ*M~hcrq?1+>|>yB>NKU}<|44vl{c5OIwL*<%3`TMw<#numzBI=h7S0O9Do>+w8v5U_MoI?N zk-hJd^ERQZ7e}X~TU*3JpZJNzMNH@HYGFARrfdBJ@9y%j+stm$RF`Pi$Cb;TDT*hvwb>Ak^Txov={DOh&5cn`21!Zf&vsKInZ26$+2N8`8i19yv6jZRPvFm@>NR*HYJH$Deou4u zzHjN$l+zXjTyyu1D;}3WMlx9~uGP_{Gljqnu)yiZt_#mD!aQSII~s}{-`RN$4gYA);jRWBq(*+F>-U_0tzOOqt->s z((~AgesDK&Jjc>;tEsBWWfYi&k2@|!s&jj5`ViDP{b&W-;_9ABw|%I5R-~9mNX{ zG7C}WN06{e?^ + #include "usb/usb_host.h" + + #define CLASS_DRIVER_ACTION_OPEN_DEV 0x01 + #define CLASS_DRIVER_ACTION_TRANSFER 0x02 + #define CLASS_DRIVER_ACTION_CLOSE_DEV 0x03 + + struct class_driver_control { + uint32_t actions; + uint8_t dev_addr; + usb_host_client_handle_t client_hdl; + usb_device_handle_t dev_hdl; + }; + + static void client_event_cb(const usb_host_client_event_msg_t *event_msg, void *arg) + { + //This is function is called from within usb_host_client_handle_events(). Don't block and try to keep it short + struct class_driver_control *class_driver_obj = (struct class_driver_control *)arg; + switch (event_msg->event) { + case USB_HOST_CLIENT_EVENT_NEW_DEV: + class_driver_obj->actions |= CLASS_DRIVER_ACTION_OPEN_DEV; + class_driver_obj->dev_addr = event_msg->new_dev.address; //Store the address of the new device + break; + case USB_HOST_CLIENT_EVENT_DEV_GONE: + class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; + break; + default: + break; + } + } + + static void transfer_cb(usb_transfer_t *transfer) + { + //This is function is called from within usb_host_client_handle_events(). Don't block and try to keep it short + struct class_driver_control *class_driver_obj = (struct class_driver_control *)transfer->context; + printf("Transfer status %d, actual number of bytes transferred %d\n", transfer->status, transfer->actual_num_bytes); + class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; + } + + void client_task(void *arg) + { + ... //Wait until Host Library is installed + //Initialize class driver objects + struct class_driver_control class_driver_obj = {0}; + //Register the client + usb_host_client_config_t client_config = { + .is_synchronous = false, + .max_num_event_msg = 5, + .async = { + .client_event_callback = client_event_cb, + .callback_arg = &class_driver_obj, + } + }; + usb_host_client_register(&client_config, &class_driver_obj.client_hdl); + //Allocate a USB transfer + usb_transfer_t *transfer; + usb_host_transfer_alloc(1024, 0, &transfer); + + //Event handling loop + bool exit = false; + while (!exit) { + //Call the client event handler function + usb_host_client_handle_events(class_driver_obj.client_hdl, portMAX_DELAY); + //Execute pending class driver actions + if (class_driver_obj.actions & CLASS_DRIVER_ACTION_OPEN_DEV) { + //Open the device and claim interface 1 + usb_host_device_open(class_driver_obj.client_hdl, class_driver_obj.dev_addr, &class_driver_obj.dev_hdl); + usb_host_interface_claim(class_driver_obj.client_hdl, class_driver_obj.dev_hdl, 1, 0); + } + if (class_driver_obj.actions & CLASS_DRIVER_ACTION_TRANSFER) { + //Send an OUT transfer to EP1 + memset(transfer->data_buffer, 0xAA, 1024); + transfer->num_bytes = 1024; + transfer->device_handle = class_driver_obj.dev_hdl; + transfer->bEndpointAddress = 0x01; + transfer->callback = transfer_cb; + transfer->context = (void *)&class_driver_obj; + usb_host_transfer_submit(transfer); + } + if (class_driver_obj.actions & CLASS_DRIVER_ACTION_CLOSE_DEV) { + //Release the interface and close the device + usb_host_interface_release(class_driver_obj.client_hdl, class_driver_obj.dev_hdl, 1); + usb_host_device_close(class_driver_obj.client_hdl, class_driver_obj.dev_hdl); + exit = true; + } + ... //Handle any other actions required by the class driver + } + + //Cleanup class driver + usb_host_transfer_free(transfer); + usb_host_client_deregister(class_driver_obj.client_hdl); + ... //Delete the task and any other signal Daemon Task if required + } + +.. note:: + An actual host class driver will likely supported many more features, thus will have a much more complex state machine. A host class driver will likely also need to: + + - Be able to open multiple devices + - Parse an opened device's descriptors to identify if the device is of the target class + - Communicate with multiple endpoints of an interface in a particular order + - Claim multiple interfaces of a device + - Handle various errors + +Lifecycle +""""""""" + +The typical life cycle of a client task and class driver will go through the following stages: + +#. Wait for some signal regarding the Host Library being installed. +#. Register the client via :cpp:func:`usb_host_client_register` and allocate any other class driver resources (e.g., allocating transfers using :cpp:func:`usb_host_transfer_alloc`). +#. For each new device that the class driver needs to communicate with: + + a. Check if the device is already connected via :cpp:func:`usb_host_device_addr_list_fill`. + b. If the device is not already connected, wait for a :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` event from the client event callback. + c. Open the device via :cpp:func:`usb_host_device_open`. + d. Parse the device and configuration descriptors via :cpp:func:`usb_host_get_device_descriptor` and :cpp:func:`usb_host_get_active_config_descriptor` respectively. + e. Claim the necessary interfaces of the device via :cpp:func:`usb_host_interface_claim`. + +#. Submit transfers to the device via :cpp:func:`usb_host_transfer_submit` or :cpp:func:`usb_host_transfer_submit_control`. +#. Once an opened device is no longer needed by the class driver, or has disconnected (as indicated by a :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_GONE` event): + + a. Stop any previously submitted transfers to the device's endpoints by calling :cpp:func:`usb_host_endpoint_halt` and :cpp:func:`usb_host_endpoint_flush` on those endpoints. + b. Release all previously claimed interfaces via :cpp:func:`usb_host_interface_release`. + c. Close the device via :cpp:func:`usb_host_device_close`. + +#. Deregister the client via :cpp:func:`usb_host_client_deregister` and free any other class driver resources. +#. Delete the client task. Signal the Daemon Task if necessary. + + +.. ---------------------------------------------------- Examples ------------------------------------------------------- + +Examples +-------- + +Host Library Examples +^^^^^^^^^^^^^^^^^^^^^ + +The :example:`peripherals/usb/host/usb_host_lib` demonstrates basic usage of the USB Host Library's API to implement a pseudo class driver. + +Class Driver Examples +^^^^^^^^^^^^^^^^^^^^^ + +The USB Host Stack provides a number examples that implement host class drivers using the Host Library's API. + +CDC-ACM +""""""" + +* A host class driver for the Communication Device Class (Abstract Control Model) is currently implemented as an example component (found via :example:`peripherals/usb/host/cdc/common/cdc_acm_host`). +* The :example:`peripherals/usb/host/cdc/cdc_acm_host` example uses the CDC-ACM host driver component to communicate with CDC-ACM devices +* The :example:`peripherals/usb/host/cdc/cdc_acm_bg96` example uses the CDC-ACM host driver component to communicate with non-compliant CDC-ACM devices (i.e., vendor-specific classes that support a subset of CDC-ACM features) such as the Quectel BG96 modem. + +MSC +""" + +* A host class driver for the Mass Storage Class (Bulk-Only Transport) is current implemented as an example found via :example:`peripherals/usb/host/msc`. + + +.. -------------------------------------------------- API Reference ---------------------------------------------------- API Reference -------------