From 0de6267eebffc5645fcf886d9a42e381bb1d9bab Mon Sep 17 00:00:00 2001 From: Roman Leonov Date: Thu, 23 May 2024 13:13:13 +0200 Subject: [PATCH] docs(enum): Added description for Enumeration process (Enum Driver) --- docs/_static/usb_host/stack-overview.png | Bin 23571 -> 19318 bytes docs/conf_common.py | 3 +- docs/docs_not_updated/esp32c5.txt | 1 + docs/docs_not_updated/esp32p4.txt | 1 + .../usb_host/usb_host_notes_enum.rst | 119 ++++++++++++++++++ .../usb_host/usb_host_notes_index.rst | 1 + .../usb_host/usb_host_notes_enum.rst | 1 + .../usb_host/usb_host_notes_index.rst | 1 + 8 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst create mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst diff --git a/docs/_static/usb_host/stack-overview.png b/docs/_static/usb_host/stack-overview.png index 0558d8388b1604e91a1098996c4a688eaa56560c..40996041de17cf705c4bad02cf2c4e837235a290 100644 GIT binary patch literal 19318 zcmeAS@N?(olHy`uVBq!ia0y~yV0^*Az?8$m#=yW}Hq#)Ufx+9>)5S5QBJSj;({lEN6mey=iT=x4%SRP}jzoN0!@+mo-n{(IlmGnr{m9j;zQyg{ zb^hk>$|df1muFpFwQB3?S8KPf`ewQRYc#{)0~>hW+}K$4ZKw71Z+p_7&oft0QsVo% zXX@7CqGbncA|frbufJ;C9anvD-pO~(;rsvWyZwF+NXf@%<@d}2>rQZA=exV!=cFO? z=7LR%;bGV1?^VB;CG7v_!%0pCh67t<>&FcURuNP-%+H^dN!#KOU{` zI>@^r7VP$iC7&Ml*FFj{u$J*p7fADBtlf2Smp3EthPzOU7RoJT4*dT;;Cp#rjlTHZ z2QQNQ^XEL^GME}}$-1X6{IBAVJDWo!r(Q3Li!*1^T3>H#8^o1yRWUT)O_^by{%11@ z-PN0Jo!jxR#(0rc&E-YkI&QDe?Xq`Iy1Q=wmA;+6TjtzevaO%ta}y{;+b*{`%Kt?06_%OV!XYy*A!ZNFs51?jVvWX@V~b!Ky*V$7|3 zL3=CbefhbfJNnPf9kSl5av%FTyqSA_Tl{NAXoUEQ^XYznCZfXEDbsd{F;~>!)y88D zT@T+GY>JAzyk(!njE&c$qv|tfZFl{;>a$Ow%_hBLXtt-<;G^$MzQLOk26cu*h=_5{MaMc6*MIcwsF?<9VeT$@?iF{9Hu~ZL?*>f(0-zu;9kR@B@TK1S*>n?q{Bv5wj^W*TXHfvqtYZ-I}F7ygqFi`ur z_HopD|0!_~x@<2B#U`4ZPrvZbDk9VRk8SeGzr{0NKU3s?Ze8&CSCK%u@ApspG&_&{ zE&t16GRG5~1tlg2eVC@P_o*zi6?-1fzf01mD{Hlae;w6W+HmS}(s|Q-_jj?@A)mQZ zKk61q&fi`=(qW)niTM>VcH0ygdDDd;-dEy#`7Gh|k@$BHKXfs^4G6OR7@22N zmMr1fy5!X*S0%p9#~;2Aa+td8=zGcRxwFLU8@)8on8sh;yXKVDlCAtp5t<9R>)v|Z&sh-4_!5aHA_r&|X_XRO#1#Cy&x+iuYvPR{7fowa)){_Iyk0b@A$}OEcB-n!oAiH(%To zwS2qjqx(-podchS#?N_I`gAte!%wT?uYJ?EQ`Wz@bv?scaBOS{?PRoVk-5N7kOnRe z5?4DpFz4ihL;A)lfeQ?`rNN=KO^e0kz_&J#lW0{c;xAj@RX=cq70wSp6^rHnMSsno z-)U@|v%5I=JgDNCBQ3_jkPy~4-(us(?KjUyM_Q{t=i^B^-gkBL)ecZ~b7vm|1A}ql zmyO5GnXJBnTd+x`n~UtoqStflkw?b|D9Iu z7wZ2%U7q~^*Y^0kKcrY5-LU&$UcdXL#F3+ck%fOB+RupD_5al4Q~g(K!|ym-oS!_o zcjdx7(|7Nf!)33}zPn?`FSj?7YQycy58hgs|9Z7R$LDX0?oR)Imo=Nceqpk2{+DNu z1;pKJ_w8G!;mz@)^5bm9JYMe)n{Isi@Wp@L%$gs`^Jm2D_SYEvQex3KV|J(1qIDee& zfX7L*%0M??1`Duv{SQS#G;w&Wm;7>XWN%e%@f1!7A(hr>^yB+xp0} zjJ2IHy(ebhKHXboC9Pk^aE8&g`N{<|9sPf9 zYUAUbH8l)pn)*~_gE!oH@o}b+n!LP$K%KZb$6kYD1tMp-WxcJICF}$zO-F$X2L2ow z0^t0`!6fyJlaUu(sjxXZ9JWzh;0R983LF_T)LBe8z^Rsnk@s^;1Dm6RxsyY)!h*zk z0v8m(Nn3!$}u^Z#j-i^u={-EOA$>+-ew zWtAU~#^=6?FO$o;YNog#ao!oB3%llJNY1T~eQ{^z(tpOj`{wcNY~yo%yHWIZOG92t zhQn)zU7$9}ugg>HB-Ts||L|nL=HAf5EBN!vJ>TxX^{`XkZf9nF`-aflEe&mzMkYF6 z)HT1BFa91|_ICBT&F1^QzLmaQIxlrww!`!6&a3;f<4bdAm~M!@9+oZ4v}>XwU0d#E@xNVv+vR`W)(vx6nWUb1#y1=*xb}0}#ojfCZlyl5+y+v#UrO`Bi8-e; z?tk7|X6@u)eo6d-;hfzad;R8H#5yiFlDl{5&%TGUQ?E0=+3m+~JblGf*{TEOx!X@J z=Gv&f*1GQM!c48@|Fi8|xB1%d4qx!U{O#^n1v7X2U3dNW3hsHgjNd26-Mc-lT9w7* z%;a?pS2sTY>~=hdS9ZPJ((dO;x(h<@IW9M{dcI{{jh{rhUJdW1{l9jW>8;Y6n{M}f z*QseQxH5!qAG^-;@bit|i|e<}|7rC|(CUB8;xgF_c1LSNW?m}2_WHv9sO8g7zg=j> z@q%p^Q&jKUX4UyTszs8u4L_fBUG{#q>5zJgr|go671!tXve$@jeS7Z6w@&ru?dE+t z9ur@GV_jjk=IQP%-tL(dLg}A3>~6k(TjIYwD7CzZICY)*aq_PBe}wj(?7hNd#oy~* zERcEg&mC*2>nn3#tg_B`=be83d7Rp}CAE6L|6DPf?k4|eTZZKSIk(SM+^=n3a$){6 ztJm3`|9W#L-)?HiTcW){)?n9*^Gz=Kjf_ewOkg z9}o1DpVNB1%e%aJ=B2Xh9}Y^M{^fAp%Jlx;=!vh(Zmi1Ty#D^_W4l+yA2}ty8|HcQ zWY|Byd~%xql2o1-_iOLIyKk4D`c`Il^6^(Ucb?G<3p>}9nyM!h7`t)JwW+6dj6Uu; z^JCeT)!*;9YA&daJ1S`N_qFu58a?YLCU>7t`1kco#o2E2lX|N^U%0&WT$H};qt6@k z7d*Cn{W^5cv$xlN?X{ivuC`qId4lN2TQ9S7d1`C*X05C3GUxuNroL_a7w^2CvK%km zb}?DW9oanLu*VDMYv-5VTjRf{B4Fw(1FH)r_t{fzGCnmfGTN9U9{c*t6g`G}{S{0z zVzzI)ocj5!^P7dwg+0|1?j4u7_w(HC(^n#nHPoGDt^Ri_S9!Od3fIkuZR^*DTwndl zZs)p~w22q(uAejA?wMOBzqH|-K`GzgOO`4&y5HB7`n{Ct?eCT;TbdBMGss}-2P^Nd zE{{wPrarEW*`@c?tn|57-yX?$=NjI=>%DjC7MVPH_&Oq2(%HfMlIR6H!C!nUq%3=W zX~=SXJg|nBd3MEuuT$S9&3fBs&U)-^7}t@YyL>3&Co?%FYaGT46DY~F->`mOt4o!DjTtzLGWwHM?X&$kub2Lor> zv&@gLteop^CI9)leXfoCj8Jz(*cnwqd#{2iC1XFIVk;aha6bNc*^ zE7tJ63c9(_Tx#jtbq@u4Z$D(-Ribq5RoUzxOb-|Cw27JjePx>Fg53%WIA2sQsy)Y; zRkNnN_eIIW&#Oh;Hhr^wTx0iZX7M|fjGr=Bv{o0}Ouu@5XHM^}vXn=bukYpGuY6Ov z(f3cCx6HFLcD251KWCY^T#w(~mkLg0yS^AXifhU9Pq@@B;Xk9MsVXkFx@DVkd#T(Z zL#@~8_w=lvq-f=qci!4OJCez2zQxb<;HY@#_#~SS3H{IR8{PF#=y+4*t-<2!SN&8ry`%J5+&djc+3GWgeoynaSYP}i!{L5s?li*% zi8fxx*L5}qXeZY!mU1>=FOgYv_UqBosppQLF}W>fZQ$ItyFJG}re0?1YwP~(+i$)F z$KJbF<1F}E?oy-R*4Ghj;9|$sCgDrs^miM+Fj@yB6+GcLY|FA+@VM&J$rY(yd!O7n zePvg+vtMQOt{2*?eY2-Nb^WHO`R9&a`WaT`zr^icU&pI1 zbE%(y-dXoQHgn%IXa4Nh|0}<&UB7v8ZE*C_r@PiA3o`ARxUWIXPVo`@T7K`uhs+_b zoO{?qUpjwrT(rsR$Jd9u`*z5k{amoE?i%Bg|Jo}`FC3kGJ@JXP%hani)8{^07qKHR zcly8lt#9onN@<&j-(UFFpOb=9m^J%`d5X{nmP1>Yp{c z`1aSi$LCF-F1&BwuD#y<+K;!oKLu4v()msxKb%!xAT1$u!Rg_Q!yyEV3Up3I*%%}-@vS)aMv#hS@i z%9Es-q@H#5Exq+Kv1HD(g05d~){~i|uAGa!|KfP2(tU*|Uytp2>|1#95{E?sbh@&8GY;ezB|1mE(n58{3u(jgNP0$$IQ#K65Z9W}C^M#m!Od zeNFak6R#_NJ}tM({dC6NU-d5?#I#=js%?+q-YsQ8-}CA{$4g+Det zQ!nnzmJbd4{nGk(&$rvR@3S)UeqJIbrdo36Sn|#1?r;Bm`#JS|X8(?#mDw@(_TJm$ z`z!MF3#&lu^xjtmk?WJCK7Bp1YTl)t(l4$1ZS}WzcAPGIJHI10BFp`9xvViuiSlI@ z6CFKJ6CsmHN=%$itwupm)05UsQ-mc8b0D3i$INU_4$VK#O?>ZLwpOk}PhOs3vx7tP zj-PY43trGg?nh1Q=C6MvJegbH_KWCi!;%YvIOD`^ZzIM&r z$^HBiC;DVpr>_>A|Ks80owbRbH!LRV-S}Jm^9REW*4{IFAD%Urv9EjNVs|CM)8f~S z$33UcHc#%YxPH(1`kab)KgElr4+|B%UvBsN|9t!PYvxSt=WU3*(7RvnoYl63p8?Y} zf~V;IywQ+pS(z9Y8C(D3!`k;hx4x^|@j8~TMChgDM7<^I)i(Pl^K&_y$&fKRtx=gqlOcf4Iq{?Ccn9SQe-y|bSsv*S_k z`WMCbDnI_4KWF=<=WM*5O6P7Dm%sftd8#-6KZoPDj#leguS?dK@89t^G%Tk62fy0% zcl$r>u*;6)nQgAlTy_1`ue(`y?!I1c|8L*-yLOH)E;5hKZr_u>xL93(&zA>(zs!5y zdg$k*ulet6E52&`%lut_@=2?>fS};=Pd_%F_v@3ZOey*y`@Y6=rjy5c#=CDyQQSmrwHmR^>%b5 zdw_aV6e-#JW8aT6#*>%Vf3P?I*HJZZdZ^{iug~2>`~O{gePNSc`c~VWcT9Gj+gG(E zHZFbM_Ng+v?8EBi!jApb@^!Yk40c)fdOxAqJ?%B;wsP-1^v*iIK4X!+?<=FgtFc@X zzUNav7rFP_T$210d41*IQ=b>zVqdR*UOJfd-GteS)+P08zIQepTdN21(B2>Clo!1J zd;a^pS<5F}n?Eslul&CU?&`n!VvDopIoaqv|4{ij`rfvW|5r?(xXM1?`|QHTvSm!S ze$QHdU1pd4wZ%*ymo59YQ*oXr=Lkk| z#=52bO=iJIsfi#Svzapr(bWr{I}^^`10QJecwKsW!h>zo}Zh0BL26)^s}D}t5=_&+K|`K z5LZ(=X$#91y&ad^R=nkw|89}`_R;*et1n+;ib@Quo~9@2vT@HgZNA6urgt4*zCHEq z?J2&y@~^AB&o6k~;S%y&n)$-(EBlVse*SZ#?B=E3SUcCYCRFv1tDD>u**WM{&Q{p&zxMDNJ$A1dX@*4;_8`+#u}4 z@t1nmzR}O$zPv3Teap>%@-6f{tBU5$bB^7$FSAecjvXYiyf<0+usf6QMNq%j*Ol*XeOOu|FeOf?_`I+9 zmp%LRcE9R57Po2o)ooQ#E04e1mE6BREUt0!-|!t4HOn$z?>Se=vgMoQ^!~%|<~=Jt zC9{pMZ07wl-~T=Rx5$M zD_4pvId;herC&Q;LMJuYSa(_r~-w(=#UmjWeW=zrhrz#p!m#JlU_>AIXg$u3GrEXUj zzj}4@Dkvbi)V906otduL5HfvvW#oEmeS6>N+m&o3nJX;v_UC);Id`k<*HVkK`gbRs zykzz?kWKQwaff-*y6szd^uQVY%cE%NX=jcp9uN9aB3YfXbo#_yhmPB>jLJxBzoMCJ zP#G29FzwKp%c7@#rW)oJzX|<*HNNP@zZ;j*LuREtwyTWZdoJjGsG^i}+E}!jeUwmgCBqr87JD2gQT5F_c{@Ct)_4S7?$I1FG zt@-2KlR1t|c+17K^4FizrTY|rEG)ehQ1?fx>7 z7wT56$#eLU&sQwzeCGGf>)vm&7O!|+_;+c;v|IdB`|n3j`*>{4YF^t@3#z`%%!rST z`z<4%`Xg=47T=pPAAY(Ciu=ndvy?EieEGDZJGbtn=BmdF#MFK!%@5tXbiMae>4r&s zC-iz?bt~Za^4aSy?W?-~X!G|yzN)sjCdn^;khChf2~^a% z9l4w+bMZuDf43&6@bB$NekI6izxjOp-9tyGf}+Ch$i_4J>d&^HDcqKN$4Q=`gh5f&M|K7Jz4qH@mJ)6j6D6g-h5!D2hgIoM?##`uE?d9wX7l9haU0T$?wz`2X<442U|qIm-deYsM=$Jivl3ifjzrp2J(<|saBe1Z@TTn2 zzwh?4udjQ$Q~qy7u(Gm}lHcM@Pd-@R`+2E#y4)W7=e$0rPo0X~trz)!nN&!*EvTi@ z*U@ofxm)tphr!DH`^y= zwEF+ofBR?tS>Atd>&mzzu3?dde|gRQ_3oA*Eqr?X)xFd273VxZdGgqu%8!k^uk4uq zX8)@nXaD~@$N9*p@~(B>?H!g=#n;4so9z89=HG&SN=7Fpr-tj(y!+~3{yMompQh@|{J!+$_WoabkAi-E(EpeC>E-+S#Gp`M&avLz5VzxZSM{f#lLGS{#h0wN`TW&a zT<1t?$n&PW2>lz?3%>tplrvFT80WmtLs4(Dl<%dT3)d?>D^^=%^vd)}x5y)-)fbm2 zKIbo4pg(c7py`(B`T-rM->JS1-@hjQ+2r%mk3YLRSN~*c-SH-FPuprtrU0DC? z%4x%&hgv!&_d@5kf9^4~s{c~tv(G^BQMq}X+~e?CvjyBedQMH4hb;qzc{azumX<1h)jQsV)#q zpAOC%YrGwl&w(3Fy%EzJ+~&lBJ4+k&7<(;tgQ_Q!q*x}Y!ZJ`zpK)Xti^-!m;NrQX zlr!VVO-OEfEp(w{Gq`kB#&7V%w^A2=eV!5j`*^z9na`W_zTZ`^E6tkq&%WemzHD{k z6*JR?TQ8k#IE|E z`x>tOd2#Dtc6_Oz#4YA^S63GFeO>u4v-p$|(p7#FI-p}jp|F8A^JfR`4t>In#KK%v7l|P><`_G&8|D}F? z{^dWDVoO(DUsIJ7vD$p@>4!D3OB&*?#l>C!rycXvyt~$K@5}G}!rO|cG~}h+WR7ya zxU;5gTEn#McRzOa{^Yu9v;N5htE<9&in7&5xN>qAFI(BZ_J4Ln%x94gzi$3su%Z0s z9=`R*pMKt4?R$CO%GfXK>-2hsj(mOD=KBBohI+m2Q)8bsgjHnD^soQVEp7k${`dRU z&)sV0|GBo@oONbh*w0&4TlPFV`utAetZCtUSH-{nShZJ|E9h+S&&;Y_&fnr+f3jRU zuWXL^cTeYszxHoCdivhZtJFK$6Rg3y9YM0 zf01LQ z6~6voS$A@u)ndN?5!Y_7+;HVYL-qEhyF{1$+xg{EoCi!^4HfIRm!S*zt&w@ z`}tQ=q<`>_th=u^{(7cx{p|+b+~_s;%^3{8+}$@z?zUZC_wwxMCD+zxey-B4y(e^` zSI5aA`}gjWog0~~)}L=&s?dG<%S`7jr*CL~-Lhl-&z~hL^YYW{+}0VCMY69t^&(w2 zn5(3{JZAmt3wtgJ{3t7!$aG8mv)jvZX=p zRRm*f@M+)6$vUkWXM-a1mopW5RBm^ad-m-^*&D&#?`{?Bt-iCdchA0CMz;^Ta=lPI zw(zb5+fuoxxMivfiaCz|N{;Z#^}b$~>iv4HWPX~>+HJC1cggOmoN?Q>etKxb?sqrd zZM*XL-EW_5vsg-$y9F-%s-LcB9_H};t7q$^>Z#7xCcZxNdDFdr636bHyY$PebhY}M z%#Go1HuUP3?96N3=FYX~UGMSI-S0B%esVIyGw~H(d@C$WNOIVF?)#OO#s9oi&A4anV$-Mfe|LVi0o$i(?e>Z-&?N`jZDwr?v zDd3w9qwZtwIK9d3e}8{-eSOW>gC}{q`hxRowhFu~zSS_Tu5C86dfo8~ZPqPLL3?lg zkbU##Q)s6B?^oyIZ(iEJbo;u!H7k3!+SRW;eVOBhYVu5Gt2*%rtrenG|5W8J%6Jw2 zU1k1y-e#Fwuh(2%ncMZ%vo_7rC7m~e_v7(hkM-?4kL4CfWZ(QDefg2uP94VDv|hyp z+-dVGPwd)O|F0&w;3uml>%9H?Z@%6(7QImU|8x1;t!ICpeZ6DdrLvOT`gQxa?74m8 zb@}htZO6=cH@@3fYj4ydL(Z&y1G7eR1pG4{wjG{6o8AUT$A;^3H2mX1Q&;;Pd-w?=C&v)#UW~ zPW05;r;mTFZ3;epV~@}LrB=y%YaQk5#mnbizaAI2&CLGQwjlke+tZqF?%H=r-|VJd z*6;1r4%!S!=QsMZPh>iMxoGaC&t3zy0hNyr3&^p`&zt_3_-vpY?Cm7u)6YF!n}# z_uXIr@2Az=JK%8c?#^w`Cw*NVe@oJ-9=aH}MCfxz^e zph|l0bAFzL=SSJ!?fP=SRDECRn^s?OO;FSH(Cqx0^XtoFt6u!8*_RTxeb@hYSDVB4 zeVUrSZ{JI$)*U^sVs?CcCLMQc>$ZE<{~YACwbS43N%@-?JK;+9g$r@}5)}2irF<{( zu0F>(SNdnk%_Ap`)SZ9L-leee`htafYYsZah?&k>A{{nYxcQvC#DSA-A^DEZLP7e+ zU+{+2o@FV#cy;5t>8koS>%VGS{R`LI`$qctzPz{bFI6`vu6lFs>ev78KD(nS{%Y6O z_n-Tl+>Z8wdFos*uKq1wS*U-v{^#lIe`mi|58wAtx5N8!>HlxJlegdh(sxq+-^Km2 z_q_jGZ?XA(-TU2YR`u(4eDm$_etb2*=Jc_%EB6$i%B)PG4>Mo4q~u(+su2eZGg` z`~O^rbpWY27K_;--7)v7d|UmmPUXqs_22wwKXd*1JS5cbS!Li~-stJCwWUwrTv)%Y zG~?&O-|ag@!R`7&>($BO_2*;6n{4z~O$fG}`CRkQm+**g~| z&V0+A!MgkOlk^+T*DcZ9sJlRPj@%(V+w^yvv==-U*j{zN(vGqBv;w%ex_xsYV;FbF z%IQ07&O5FRxcX(?dh?w%b)IK#t9<<*Bs*`t!1>c|wVy9+ukVNs1oarCwr~E-k+Je& zM(x~FjS`_9WqUhggG)1afBNukLh9yPq|miq-*7H9H2%%OQ;Yj+o`ycPi9NV3brIK> zAA7U@9-4S*lh*Xz;!S0vzWuz(rumrb zG*Dyq*xNPx)s_mJ{k$mlzUMpReZ8{P7oC}+p2q6&l?q?j!2|BS?U;L&^+4kE_K9ob zE)~tJSfefTb+gm%FG}H=KQozc*_PjR5V)`-2dXsmfaRMj-sc*Z&%b;69HVsm`mH(Z zZd<8jD@Jqsv+kbnY<#5mv<4)wV*kF&VV@VG@#@fodiAoG7X62>NBKFf61ZM+^zL0O=~#zRtKunI0%b!at z1DT|@Zw99jy)LPsu=nBOtgMUwT|FOre){67wz<`Zey$F^7!!7Ezxv&+ans*xDetwf zb?k#CVnM+|9&loCaglKb$B&@kad4|2G&ces-W?Dnhkx6B7l&p1hiA9nv$FiZsCN4k z_{vA-@O^Wn#RLTl!}|9Z|%G6J!ph4etcIS!Mkd=9Ix*aHg^}7H^Eq!Kh}QU zKkrW6@89b3e-6x7Qc?;7&6Pdwo$UQR{@#B0{r)X-RnI!Hzv~h3j?FAzMt8Xb63B%f0x&V69eZF=7&hK||ahY@K zdHj!`PfjTJ`>osmG8U;w?w?;(72FINymFD<*Zn=N4!%`D-P}k?>5)#BN!ZOr>pwj^ z)7bdJ`$?7y$Ty$>xw@4(eD9k0wyDMJY>VQ*u5ACkGf_}bF#5{r7#+_W4y7%9TWlxJby0yUhqkC0f_TRO|u_~YTta!G1&Y90k{)O#2wPW9k ze<7>?CHZSsct3r5&pH3bjOAACEVhrzz(bzLTubE`*A|3vRR7z0{qBaq_jBcc{cyW* z?7~^w()IUG-`Fwd&u9OCSC@TN(rbd`tyOCoWe-O#jC%DpYZh~O>ee$8zRK6Wx#4#H z_Up5!5vpPtCD*cUsXEE`eBFmDAGS^Je=W7?pK`xVRaWFV=NJ=kUW*B7XIZj_bxZZJ z+SA^xC43(vuf)jCxsaFE$sw&v}o}X;1%lD#>aD4jqqP@;@)k^lRTW|a2t?y@n?W>`lbY|Z4g(vFZ+sx&kB}-nej_J4^ z3Nhg7LdHn03`^hjVT!Bc%IBDs{9U#GYZ^l#s2}L$@OY7xi9$Bx+lBA7jM$N zUo_{$uVnwZ_chwO)gbZoYC^-5tqpzgTQBARI<^1Q<)cve4`SI7+_0u-~<4xUo&&H;22M07*&M7Zg z+P3g<`O?j^mcRFX{&dejz0kIK#(Jxu-g-6l71PD%avCkAL{E_Wj&B^%wU=gIZLe zrgZw-1EKoQ+gx2-=3E7r7F)&N%$&1*Q<>j6S=c&-e!H@qU}j|{rE`xay35_=crnM) zKy`Q6_4oIRKfDsQuY2{<-g|1&>-?(g-rCviawjU8FK^mZbPZH4U0ty2^~DP= zc?B*mN9;_cR`bm_a=kg}F|85rl`8B%jMpI11Kj@zyITEJLw1Ig`mjzblgZvaRI1?`&m4>7gE5{ zG66hZwAy~@uV(dmcMQ&--W79yetfCr-^5=w`oAvEx3yj&^9YueS2tX_Z!^6z?%LB` zhhh?67hR7lKfLT`VC;gBzG9x~kd~DA-AeW^^XosY_nSJ|UEX@z${y7Pg)<>#$i=zo z4%shmr@s4h;kf_b*{36!q^3tga`N3uwlCM^etkRk=kWG@<&S@EI{o_p&NV71T3^rH z{7ier*Ujf-|E}Q<)YIn7h)IJKT_w*&FKm?iKBM2}(~D#0w@yFGfsjhx@G9c{ChY}( ziy~^Ctx3OB&A&G>x$0%AA(G`17o5*B%Et4Zc8uZ5^LBV_1ZlJ`l4g$j|9+F$g*wYM zCR1Xier;nh(Sx>Xb{RT+-jkyXGIst?6vM7HT$@nF_h{D6c3*@^x1}!pYgLJT?)k^B zq{al;|EvD&pEJ^hg5VZV z;l*6ejQujp)(1V^r22PmM(m6)o0)g{Pj`<|fdtIg%B_?DSH1mJn5$Aj%#*yLTB6Ap&EQfI+jqjfUx%H6WOo+q;J z{n>W%ci#TuqT}p#T^$_}p^+c2N$1a9^KSQ}9iJXQ+B^L|(yo$Qze3f&q?v;nT3?TC zv#yYKzRmJw&X2PK+uKwtB6$P_(*yh6zs?Bh_m+G#Pk7huz~)brB$Sl4t&re<< zed_{7*ES#4wS96n*TrSd@?WYEzfvPWla0SZ=U45R4{DBXblq!nZ2hmChWkfBk#R!) zbOvOZ(UbGOW==F;W7PZObg%t(XaTc&rM=hsPxgOrZl3*2QHk*`4BRT0_`exz?+wR7k5XrpfnzW%q_uVR}K6IS|1_yRBOi*Hbs0dW~= zZQs%QdzjSU`C;`rf7tzPEPuW{Kku%I{;Ho^>Yw+lUH5O#i?X}lBCi&%vtPTayKVW) z^vY$o9qU6JZa*wGl#9N&C&sL9U2MHm*$G3tFF)jhuIupKeIFHFdUN|)t>PyW-Oa!0 zp6`yUzRN2;|2C*@URLShVD9XYzpX@3f92182cB0Zuj+QY-@15--VH9MzmXmNh{}Ataq89Q%jruQPR^fRSGIHAg$uhvo}IV< z89w{jO>6rvAA^s(&0D_9^#0cf)@iT6CHHBbz^_(cHbsTMobx7Y^{k~;Tk_ zSI^??X#~KRoZU)va>Aq$mi$btHXaksJwSS$Y1;QY~7j7XO4$m-#OFW z^-tuFw&mO6-^EsO>=x0AtACSd{UiJ9Es2QO+xd^rCT2!wrFti3wX=P>P&?_D&((Wb z+iT>0-nsb4CV%GDLKjdI1RRMkyJz%VE^XAYeZH0JRYaWl+=_+0$I_$kt;@N$E~7?m zrt|hCdO<I*t!|Ms-XR)3qn$+x;)-!$7oa{S{xuAZypFq&n*|I+hWucu_aUw2-g zz4`Uk=Tf&dr)j<{(D=&M&a$N^QKoZhR{q9Y0qHKH6*1GS@9)FQ|beb18{2bhoRlDl;eD}3+xr?v8z1X@#Uv=-_rJJ^zX}+vVx_PTO@cWlL zhrgE{H`+SeYWwRw%qz-_1C9H>JgF?paHzf;o7(nDdWPa+_0vkA9_`-9_=3_;ul}1R z3sl^^vG}B|w`9Ax?b@(7aWB~ie4M_spB=LG{+T1gbjJ2|g<`++!!{;W^rcjb6s#B{!7|p*76l`+q5sF z@XXy~H}}TR$ds~K+~sSkGk)gW|Fl%$%fF`qQviqcq031hDz6-V`|`2rw$9sn_gs!0(9V6ohL7`7&VA!= z3%?#Ss+{-5Bk*L<+}f|Yi$Oi7FKM+0ueN%r$NI*fc*Oa#J9XuE4ez~^E0U_g3p3BQ zMqg{QYJas&qjjwg>$>lYuPAHf)@Me|iL1I65tVOpPowhIgobZcwoB&q9)7j+UX=9I zH@jzCzqKUgWtz*b@;7gbHXKd9eEHF)r3>Fwem7fu`I_`?z56?+p1ShtE%&dQIJd`! zAzJg{Vc{+QY0|!qW5S!>ABwW>l>PDUVMMG>yUqHwk*_}bF5bTUn%L5}AGb}{t6KVL zX=d!@rS^+2ar7Uczq`$ql zPNr^NoYb%UjqfE+Ps=OX?93EZHdXWM0`LBewrksaR?X#j!N&38EZ^P-$GR)$g}rv< zuRW-`FThmgOcvkXfXLWCNtWAP_pP{nsXHh3wKgaWu9v+0c5?5rJvlkgFFl{N{pxAo zV&~vh+s{|BmdI$Ge|ZcMHTin#R)=HBi^BNb zJ6GQP8u`6;*=g{A^WK~5CL2U?HA);<+C8~B)q~+kV$}DvwzwUO_q~1}?Pgp0J?)dX z%huG`a+!Ny&8F-1EPbo*`+An#^OH9I)3)vYvh!JP@BI50($_An`aS2kamLk$4Hut> zS>3aV|1Da5YGcp$NX4n`N4=jWRbMT!-70-G@^!DdZ0uWGlLg+-Bc{jBH)Y%l?sHac zj#W?GA|mvWX;S@5r#%aP^~H*-`)b#+?PM3ZZu#U;`r}q-@pCne-*(AtyCpZhQ~Z1l zWA|zrm*>o}Hkcr59d zELCGyRb%Ir%*6Df#9UP)gUl3FV;5B;BZ~_2c)wtaQtu)I%Lwy`cn?>LR8=D*RU?DE z#N1Sfnt;UgR9!=mDAE<*3Ti z@^hemgc??mm=3cM;x3RtaB^Y}rf7I(N=XLP0s{l6`#{P)QZv&tU{;&KWO5T>s-a4Y zGZIts%OM7Ug}?zhb-I!MX7mE%kgV4hK77uVooX4 zcdABaIVGybPHFjhC8|aS#U+(cf14GSf}91G&@BeXileHLfuTh~g{rZWsu4_H)yOOz zWPoEqK~83JVo7Fx9?VQtBR7b#5EYQnMc80elwX>ck_w6qLses^@{G)q)Zl`|WRT0s zixLY|jh!+|a&uITT|m-lnK?Pm`8oMT;NUZM1_M=Nr{a>L{OnXD83QnYdI^^}G?^J% zfc*kW*9D1)P=p3-S!z*9Dl{2`g}~93Tj8FXpPO1zRHja!&N`Q?Zd zV{8N!%RovjFm;L0M4Apa+DH`^@2W;_(1ZcCA1#p>TS7vX7P0D_lUQ7=YGmM2lv$Qq zG#arM7SKpUidaKhMJz0Fj7DsJUI~?RtTB3yrEA23OA{jll!yftLP&*UYF>&XsP@n5~vvnW5MM+JV?ME01JVOc`z4R{3DuYCPokkqa+|I zRpg<;PO3%*9{I(f_JEIPQc)tPrh^zha%*%;SRs#;U};vPn;6qHdOb$#aZ6b7j})DT zFfrr;2$sWPMFTkvG!qlrMW;t;(g<#z!E+$A0H$xWn$j>@on1yVsUf_Njg(8_QBL(- zYDUB8bo3dGPD2A&VM>?iq~TbH&uDBK85&^eG0`q_LR;vRHh3|Ht)T5(=lr~qqWqj3 z&=`k-hD*3}ynl$h=4hTZgb!}eAkV5Axgo|r!CfAt5oB=3N7cv;HZ~38!^f?q7M!`v zz@Wh3>Eakt5%)Hhdya4D?>hG)pX8F5QyNqK<1e{N{&nVzjahzCV>`#rUMJ(LEp{yd zArh%v6MyRpwROg5Xs8;XBdh0YXlinXt^WG)(4j+WuCA_A-`G8_?_>~EU`p(6IGSWBDJ#2I+uXc- zRmYm^YC=o@Dw~;=CHnaI1Qit(JzeHI+w1GAtB1=rh0Ng)U{p%zKajuwuiEYH`O|N1 zPJb>cB9ij#`Sb5i(ymPk2Y&qcvE<8_FQ;1iKuQH(ax7W8^l55(y0#Jvr`nODM|Dr1 zI;F(uw(F^-y^;e<4u^`G+Owxmo|JTNids86I4CGeO;uG;PRW6#qajn^#F;ZwdU|?v z1I4;k?Tw8$3l%pk+i0uq#nRExq2NAa%9IkJhXo(+?XBkI5>#MvIZ(p!=l=h{^R;>= zu=u7|`OV-EU{r7rdSV5VyTUPn#W%OkZytvL<0OUaAipnjYf#C^`ds|UrGaAt%TBfq z20;T;CKX5F8UJ5gTs&#U42|dK=1yMfJ>Bc>uF}7DukY=xK7Dg@dg{eRu32m5*;b#b zd_GtG^YioHf8RJLp|3FckwTqggUSo>2iPZM-CDbE|Nj0?eQ==h(?NFm8^69iudtiXV9le&q;hb2&ud{|M5n7ilT#1k52WpS!dtf z-JSa3!NE^oF8h1?`1E{YQumvqu{LU})|&pZ@#(e)`MH%TJfzuT`I_6*_5K z?rpEEtW{I=EOFY4Y2CnPByROVT7`f>N1p-p;3DHr%fa{@mMDx>_ePOJ!Ayu^35nb-Tv z%l);5m^1a__C!p)(Qp4x^xS*3SAAqdBpa!P8*Vo5&=y z6)cCno7zR?<=5N&zW@K9x^2~$fJ7B1dtZmV533wps%DyIPkWGlbyaB5&!^M1g-mXp zljQvO>-GAsITytb#rw0=n&sVzc(?a^oTO#Z5=EgiCr<`mEj;sk<8e7{!#k(-_pi~q z_WIh|$+JwewS@kByPco<`Po_3TdL~n-g$ZJlmZbU<$HZy?9(SFC!e}~$$Nj@-zy(Q zTbftgaB}dd|MRhZ&%a-SRVM1?&L6V@9uerzy!xYaD_hC|$%0Z4Tm5GT9mAER*EZ#lx5RiJ5!MSSLhYeer z+Qr1Ot}EoY`teRp5)rYgC?G%~``Vg~b0hC;Om1K0zCI*Z})qRlCyhLvb=?H$0MdL9tHD?NDHf``or2x8y94)T7RVK(m7GiEcXU4Nvtr1?UzD+r;NPTUIoV|nx^_9uKXhTv&{43 zUUl@C#VvO0o#M{H;GaUBGme7t8|63%M8f@083H=bTZ%_spR|C4!ilLe+fn+a_E2K7W=TB?lpsu8@}P#$I`Dw_Pn_=ESjp%65h1A}yB& zj*318&kMz8Dp&;-m;_rGJPn$9POcPSRC-{^q~dtq@Uf^%1BZ(MlgdF3BemsDEFBHc zIW&Z}MCkmSIdkUJRpIO3Rr2p?0@usSI3BdhdU|@QFJ2S&`q`8zQ>NY0K6bdoE@U=H z`hg%*1>=ax(Y5RWk*|#kcEdYp>qqZo9z{RLv^%2zvPVoH>2+@;m{=ekH7b6fh#rGZ1jSwUAN&<2m3hW*E@pEje%i<#|;oCTxu8TD*9%|C49W{0{%FFn#-yvu(O;Y}V^H ze&UY7Jhwt77$q$cG5Jwzw87hdf~Dj91eu_@FN)<9mqtiv9sVoW=2pCTQ?1{Gs}E0X z-Z*Pw*k7TEUj?m>I{0+|Ru<4;PvnU%o$;KdxuLG1?aDdFr_Y{k)lC8$<_bR%R-Tv|@i%9S@JCly*Nqdcz5k!<`F(i*54O$aw}q9Jg7%cZznAdp z(8j+V4D)(R3b+pRE4#&9zauZ0eyLvVh`5H!hQh5YC$j7{GxEHU&EdSAc~ZiQTgTF8 zO=Q{IHc91$Y0JXfjGhK1xsQ#{dNjp3dkTG#I&|S}gNnqiZ69Z*sW`4*sKQyroA{#4 zL5L^z_75N9NeiwAOk&yFW>8|Sz}dDgw`Q57=Y?zy&!#wMiCwZ4u1)*@eCpPT+Y?dt z?vAE=pG+YCyX$KrgWv6V%=hxj%E=*Xqpq5L4*0Y07O2H=XJ>J)m7A+8r(ECuKc7xN zy%wE6_1s+R=`)(OjlaFQ8GO$Az0FMf`nnU5vsGSf^*rU$bVvUG1G!hfne_uc+&Hnj z?Cqq)!)+&L8mBKwJw2`H>(%hnFE1~Dy7|1_WPbZU0ejoDm6e^>?fK-@>Y_3E!GT8R zrBPe6ir(F^JbC(baPf}^&HN&YcK`o;F8X}deD_^f?`b-M6EeQPyL)#VZwd3H1=l-@ z>s@~Q`!Iv0xTt7J_Vsl_!otcQmStUE7n?No?aj^Za`k@-p9VI{oSLdFeo19V(bH2w z#TF$mCfNLXvA9cQx?Zf-^th^(hv%|9S|6~m>H6+7llg39C#$^R+{Jgh3hbGL7cZl} z-U?DWCHXnUf10MuJfqYuo#<^oaaAu>51tN}JsF+9cj>=7t3tJxPEht2$c43(7OLzy z)-G4&@$cT2SHBj!_iHU;-T3U;Gq0zorYokAt$-BFYYxT3Uvv02}Hd}U))mg}-Ys%#^ zxrqwj-G990@3%e3Cu_B0x>uGxu&NgIU@#ST{T^Ae*X8e|~|FdvU zV#RKb>0ecLBpv0deAp_Ua&C@g(c@n8TW$Y-Jnmmw|Noy+(h-iG@Av&qIo>Dx=|*zD z=VUeCkbi>aO`)s9PHxM+edX(kwN7(-Gg->FC~``?@L(s8lhR63em%F4EVQWMm37HBGadC66-?nk1l7>6sUg#>DxetCQQy4kfxX7-ft z@9uV4IC#9f<>KycedY38^^Wdiz0&I0*Vj!gzh4_J_`ZRWIpzMoTBGc1I+-^%ELc+Bfh1$Jm=2!-c>BVTwHqW1?6}rko z_Oiy0I)#JFT~p57fBg9Vw(C=@FKU9^cP?27=DMWNJ4L5;wOHnu@veVquJ%o(LqPnV z$f`36EFm)$Il4doJqofoaTh@KJBd|+p zJEu^~K91yX9oP}cMA@3-EZtYBu=!5|mh%*Okq ziCZrq_Cd|Uc`P5zD>~$Bzf4q8lG*?B-|zRL6B`0d3@;svb1zp}QJJr>-!%K$iqi|t zIbR)xuo{hKeMz3~WyEpI!xJ-Mv-QGscvDao^-LK3&`|dt$V)6v_&6)~?(m#Ar>2O~1 z_V)JhN;`oTwc~xV!4KEla#|^`ul)SX^Y5>(vVH4cW-RI5{L0`{g9Z1>>z6e+omOty zVj?P}JjYFg=Y8dy8~c^q@3=Tjx?v!3cxsCRXO)-I!+ZA%`~-xb{wwfrTDZ;LM(v=m zy5EYk-8C|O?MIFupC0k#N1T7lhU+oKyr_pA*=tKOPm&P5=2trDKo$ zxqG2&A_6NN6&M(rlGS&}9bp#g>Fy3r=}y*AV6kca^m_gNRf`y%f}T9}n``xS8}Gb7 z1u9aUS^hl>c(pG5{{BAvc!=Jf4^E*+cKrMGI(K^YBTg|fu~i#n=NbItJs+{UWwCS1 zw;h5EtJ&o$90YCuv0d`@_1*fE=OriGTyI+?$9Me6DiU757yGDiI5$t&kmx93q00Yh z*PBhJLteCR4yt;8%ubzS)8UB|^Y{I9tBmAmX6Kh%^C?YZ#{#7u8<{N8@}om4hFY9pCX^w=6!pXyGRNQ$9_O@v}k>2r%)q^B#P%YU1&E3$80~ zYHm;rSa$pw(=u81Pn=9Dj_VUis_ZAQIA1rjyWFGl!gPv?<9bD&yL=u^3$vx?XSxY} zk@A|f;JQFt9=poH3tM~7n<#Tu@v4&22633U;Aqmx^JmViX*qsLV`3{q-0!JVrj%@2 zvEs%2_VvoyU3K$$zqj94t6?KsOQmJ-6Pj;;mzau{} zJ@N0q4YlejJhH;Vlc&s?6C)YF^rTGU4@o&ozCGs)zrDFx$;!&A;vhe3!tcZF32ZC1 z(|XnL4t_{y85qrqQLf%BJ$Uzr#y$i;9X=w6wfdg|1fPl`@$iXItfQcUNg{?sEV6dd1Jr>0T^vs zO{DS5`}_BYtb6mTH#16JJAB=gTU)cIU;5lGUpJxp{oZi7nh%bio}PvFh4xzumM=GZ zv&?sP%8?F1qr^ijnRj<>{Z;(_-rlEgZf*t@JocH#^A0mIPD*H48zLrTQ}<_w&4&Zb zpN`AdYdm6nIJf*><)^pX?{j%@)z^Q$8vb-v_PW5$7dsLk9BAy)P*nGyH>KbHU&OY& zyISG#wOeofczSATu~l{XlSlbNclOusclgh5_v66Q);ljfg?K(N@gIKZ(ZpyL6$$E_ zoBh^azelN8+FWm;;fWQ+&(B@jQ&|jZ*mzA?psb&FXGh_tvbRy7v9miBk9!rpo4lv# zOq^+)-loDi&#pG=LFDw%J$v`9dHl)hIL8DQ<~>HIoSG)9`%k+bUmv?I=cZEF>aA0b zx%bP3>L0jjV;z1^(5djngn9GUbzGjg+9q77rXaQYiVJTw5!?S;_g1((q)cW?kuj>@U>B@(__nK`g;bP z-rcyxs`S+okCd;ku4=Kk*9HGpT0hUWTI&;Yq=Ns?&*$wQ``+l{nXVVR>I9?8-sdaQSGr_-g5f&9Cc!y;QG!HZz^&+m5f-qH~LX zKkC-Ma^r9t?_|B$T`U!)vx+SyB{aN^6BBCLZdCFj;O4g6*)atNSud>!RPOBWpFTTp zm*>;(0V)@}pUE~lm@INW$a?SU6wP1}Nl<&KtwW^t>Z;JyA<-h~Y&;SHiwrI;bY_3b zyZ7TUX|wli_Y`a#d*)A_s`{bf-JZ{WPv3rhd;9ve_l?Z#A}6vn-pn;0Ck5_&oDH*=LH88>_OHL~h=^`RS6k{>^9AFD@v$#_`+#*`Vd%C=(kW z5U}8c@I8wz(^(B7g~}Db-)@(!`pX!%ZkYrqvW%yon468^YG%*C9CT;tuRyG;?9`; zwdjlermI~w|DTo`Ee7BXPabB;>tCAmOj6BS%<_<$0z${nPe)hjoKP? zyxfFSgj4B=>%LHZ?XWcgu4)xk=64F3l^kUPnKWOqE;QM5ICgj0%JYI@&H`eu`zQQiaeDe?Ff-9b0}^^ug53d!RC8+upDz43diMsrny$95Oz^q-3qB3u|l@+$x)&5%Xh;5Ja-i8!|{EFu5 z@%4LuamWeV+>*5}P%HP-v*!1wXs_FGNR@L@v--RW zr>EkM4(H5fFIVAM&(|vbVW(x;-kQOR+F{-MOZXJ!~W%PKZa z?``5aac{Dlu1n)nQUe7zn&Rh@egW8fl>hUSMK zCIqB7MyIDsnF<{-6npzp;_sXd2MR-uN^(AGW7a9uVKtZ7!rXZ~y!@@FfVt|OGZVrN z%t@3^=$29bw0Om&W|pmU7A-D_xGcP@{?kcyE!(E857+$=YEhNG=sby~IVH~KP}}B| z8wM73K})?vOP{b_4V9_hC@!;O+xT z4njOS_hfoGG*|?f9v51QI2WXN{{Lg3$OX5BL6F0c#iL0vO<(paLhGSbiU< zxzzz`ZW%TQ$SOIoFm*F{8f>U2Hc@h5apGZgZGz2j$|Wum05v1eG%?KE=jG*PC7HT4 z%6$2fC0nk<)#r&ZSb&;+XL=dr3eTK4aighxvpRH2wdil^mS@MhH>)$bC>#=i56|vf zpoG#GKE!kOr2wN+fK=m_EnD`ydGqGXpFe-%w&lNM6g+n1h>EJZdU)QgEi0?e3bumA zfdw=<6xesv{w~|&Y_xvC0tZ2bXJMaKpK>`CvG&@PLx&D&xw^W3oA1gcHphK}z=7)T zAO7u|tnP1hmEpbck?U*^o-&CjJ@97H5%VrADf!ZQ=gyr>C8My{v*#_)4@`^K6D%lG zzZPWF$ff!Xmn6YuvR~z?#9Gvef*O0hwq(# zADuaKMq{4agIgRXOxx7mT$V`0S9&Ni9duwgpI7vkmASHyljR2!>$>Iz$__$2yEuK; zGI(CN@{GUtbr~F=}QT@Lf=eNom1w8{?WF|iN`1ttKMs~Rg_Wyo3PZZ?f?|ynaf4``J z_`iRzR#&`_Uah{`q#wR6rt_Q1!Tskl zTOU~-3{ZE>T|3vh-0#z;Pfx%D!FE3!1Rs4qZ?A8Dzh-mvxu{Jkox66HzrS}k_qIo_ zgHVZ6(}!0ZIO8gxie}!~QONoGu=nA++bTal`*es~e~0SU!pFx>-rAa-3LRVEsvUeT$Wvx{D?S8FLI=a+*`l+SU<6a4zxV+q-TWP9;m%%X;Bl}4UgoWnV zRBi&zJZ?%oEw(Xg?a~c4RbN(Ay<8)Bo^PRr)2Ath3{q?oF{ogN>b8c*KtZbhJYUw*UHCG$-VGH2HZH{QdPci}B!(!|nXx z+&8A~h?;SEnQ!pI5352~KiPCzPnq);qon7<4eBa0X3y46KR0J0XrM@M=M$mI=X1+b z9v|!N+ThS~?uabsBdaHC`eiJYW}D>(wXiiE?#`Nc?B%Vkt53-*#ax^Gpi5LcBxP}b z#0Bvns}q_15{6FicE7i~xiPuj=G%?rOG`Y3MFkaoTej}ay=_)%`{}hndNSLj2R%Km zpeWqo%`a;eBKfU}TW^9}uasv^&7M0YmwmPNFW(>h%GO#W$Yhc8I>GWYn!(FfEIK{e z-!5}==e7wSrOP9#9Tn3KG%)J)NJJj3%L*2gu5@Yw4FYM3uhI1l;BeMr5$q64z2SeJ zgELEW252}}^vQ;4-`?I<-<)=K5@>37*Okc%pB{X0*tsyoyJ;#fT3Ae7ur!RXI5|8#Vkc9U!r7vr;NX5W zv3y!`=?z(@f4}bp9=(4tqYC7_c7A!W2~+;Ht?K1G&vkE>vY}JcWHsNQlrPt!^H&OU zDJ)@T=UbsPx6bDGs}Bntn?c>F5X&5n6YoH+=Blr+R+jMj`7~%eTx<8|!(r7cvn`94 z>BQ^^Fw4KE6S^v-&}!L#ov>~5Je#b9-dtGNYy)a0Pdt+3kSZ}xwx|ZwS1fsRBe3<9 zKyIQ^3!A5tK;55Dr}eWO4{mODkJw-LSLkg!ue6$Yd`;m>!+u$7HDPtXCF&8|O5aXi zZ8EzmN!i~+V4>!xb5$3ef<&I>?ReN`G+DtZydsYyHjsglv+01tx~h%pj=J@GD?TQ< zLWg)aibZeDQU%S@D>;NWHSrX+oICcVv#{nyr=~}Mc2PsmgzAmrcP2V!e0cLEvB7wb zV_q{m|2Elr#~p88z3W*OvD|O&5>QLnb)CAenA@3X3Cq$~Q*v!HvU%@G@3F}D2>5)@ zp)UK{n!woR2@{&HT$^t;&z4iE_42OL?5Wx<;T_WE9fJ2{_o;X*J5H$GUG`QcZ=&}4 zJwZz+%;|mU{O^-z_%a2@JGqW61{vLAx?YUmzunH)<`3}x^CVdDEAQ9;-^X~K^{ZEj-jTVf&X?yvr^ zz{ErJ;;~loxD{OzppMa6Zhwyr8#V;I6}0);Qh!_6sH^pZ*hFI&F3#slAI&G|^?l2* zbgpW;C%ol+^?^!tl^XlMUxL4`kP%bu+w;Ijv~TYXZom7=Dh{a<_f%}0Wh`6|NtIjw zmAwxhTW^=gx?QidwnlvEH{8jcDZ%&q&L6q*2r=n}H$GnS)?fMjilfg4+aN^+ z`zKEXA{`1Uq_R0(+5aYHy6A8u&aG_xCB34~$>Mm_<}_c|JrT2SEuI}E?e8IQJ)>2$ zqPBqTP3re|ceDH~ba)SLG-x?7E7-yR!sDmMxX<)BtY|x&wyksKv%FaaH+XW zSI?%zyaOHq^Hn4`!+7pnPGC8Fy-aYirKdrXkK{CAh#B6QlM+&H8sABC28|24F4(7X zki#TP!q*cqxa)pO!$n~N#{=j|cThUNvEjh|*Y8uNT+O;WXVRogLizT~ zK<%)G^j*eAMt#edEekuUoGhXw;KA}Qu0HxhuNG%vVd3dbn>PLXnRLe?>(EA@Zil3# zq&Po6zp9v+7^&;?Gp9RVQ2Y1&*Xw2b!n9DDuo-HG*AHZ7W>((3d2{B^pFj8R_;)7t zcfgFbb$@T}i{|GxR8v#aw6xq=ba|QY)$HXOE(fM_D6nq^HDcZM!Hw7j*X*y)*Poac z-zQM8?ccwjO&9mClSA@zSNiHs3-{0MRUC6$t0o>kx$MJ!c>tUYbD}R=bhH#DvEPI>! z#f2G_1m1B>U^#rZ>B@W#0mk(L3Y=A}^7?8_E(&)96*${=v#zukRA7ozbP)Q&Wf$iI z8r%i7WXrkPJpXS_KkxPUSntx(*VjPfsqIlcQl?&JIX4un%ic`j64knKYmRlfpIP1= zjmXHzq6Y^UH8nIQtO{Ly>S}nr?p&+VNzwUxuU-q2cDHBv<@EdYy4`&FOZ6_=c@z}f zFmP*7kvMjYd)cd0)q|Ip`=74=_gTL3|KIOR{pMN~{eHXMd#YCGlM@q_H)UQ{v#k2E zqU7~8-+2{}I8AMH=VY(n8wP4KeBHiik+53YzDi2b*=DHDq~ch7>+b7F z>s7a`UWcsa%l>)b>gw>*sncWAJlK_0Is|^5vwkm9ld5jx%O&`Mg>ljX^^A?Vn*JLc zo7pZccIR(Dv4CMy{(ZaI>K5hiVrJUa?$SzmP|+=D=+xBCFF&nM*4hiy1(@hAXLw2X zwg96vlZvBWn~`Ed%bYjGP0`zO0*@yb{9!$wFvqj7aO2vHq!bwumwA=XBqh!B=BTKs zOv$v{b7Bw21eUYe)$7ypTIRg*{BUJu@T(i%XJ?r{{dzsVykgz@4I2U~OFp~_cv4`_ zXLr1C_WOOm{Xnf2Lqo&3v)$se`57lI_?h!=vgB@Mb)H8rIwwYMPUEZtEj##B{!87{ zq2Ytb$Gt~5W=or9J(>r;q1clPX5Md!8~eY-5GlAfHIY5eK)dHdDhe%xK?%r0q| z-DZ5tHRgoX>2Nae=ioaXfya$ zps1Ap%#hV#zOtJSE-pDc+x+`^m7A+IK~6bzW{!%W0@FDG1Ur2NsW}7-p9Sju}#nlNPKzd;X*_qmqNr6Djn?%C7Ly z0l&Aw9iVl~X^s!J->*9yea_!4a_zOVnwpxrz571h(P1c@2U-AT##Hgs&CTtYSj}x; zrN)U|><|1*ot>SPmX?-xuY}hfJ$6j5r@!Cd%imvJuxP3PqmsZ! z*plsZ(5miDweJ->43Nvz*|r)k4IBcE9*zu_4tv%YL1)Rj7!1vS>(|R76{J)DCEf6F zZ2k=LQ3*$c&a_7_Uc3l`aV14Br6zT*A8y=rYu!Jtxi4X6Z7 z+iLUNm!+e@sX^sLs{>0%!%9H~&RMtq%&`$vU{Y~h2O47W=>>Q4pFaT=^_)e#hzQ&N zeX@P^w>2htcOs&;=jjTo`4rrExFT>dXsOMnB_ z&96Hr8t$3TS#6-rq~f?a>Yn>&GpB%c;3mnfEt$$sPfwrT)WqaEEp&C5?!vhf4Qotf z%aWZ~Jet%@cIhwAX;~06@d2podS^$WQQ8>^N$avTpp{9NHmCbfTA<&1WM2#@bufM8 zV$Ap4kbi$)llydsw!6DZg}-c1I?6R^L3r51qp)&EH+bKunYQRJ?Yl@EO7rpFX@%GlS%+}fJ0{{2pIe~*miB$X4UVgf84O^l6}MeG+n zE}Y=`di9}k`ZrLN2dYG3BPzY*S?F z1Lc+2iq;0VCg>!h#T)K>_x9EP_Nr)lzvpwG&Ce&3jdE@nlStECLb@=*ut7L9-b7}PblT#B2 zI;#Mxsy8tns;%(%6kwg?E?4RD_shGxw_kn<^f`EOR!y(RK4 zAn3mWXfRRegUmDzfyN6C4Jr~+Wedby8aP-u87C!7Xn4NCrGcY`jY;L;g$>MG6_{KU zJUAw>G_%;Wt1`JLn1Cv>HrW-RRiuti4Jr~U4=i;A6_^$_GI$!8ym8P4%^C|asT@>b zJfGOfAjrYXBElJ^GwsirGiSW6t`6ttT?^LhqQJoMV72U|Nt68G<wT5hO_7{s2EUVc~ji9hHv)CUvsnt6_~gf!RtSF zDuMQgC^Ky<#+w3%ggeN*2rDbn#`LUbaI`?0ym}Rq~gOJJWqs%t(i=U)z ziEX(0yg&`KwwOtoy|~Nm>4xZSOed5e14bT!~BjLqLg3S!z#{Mi} zL(tOV)@M2^LoGllFa33E<2$fcgBeDlJjN^@O^In63WBeLwdQ?ZzHebagQvllT#;*1 zQlOQ}hopG4{DRlA&YbmwT5@jNV`O7c{=P^jSY^#Bx7b!&~P{7>W+nxi_f1DDOCH z+u)XWEIzy6!Oo=OSij(u9VjVFgS?llr3KnTWG|q=`HMO9n&T@#Y@yr>YlP6Bx5K>iwb$7Jdd%uND0k!lWsKRSuhbAH9CDboeH|&`M%GQK( z0Z*-Skh78lOOG;oHYnWM%kuwS7HT&5c=5(0kj(-~=r!>&IopE*#v)f0nOqLobL{xS zGE?{q|BE+ML5^@aV5ffKRYAtB&L}}fr3dbi+W3p|sW-DY1R5u}9w_sh;NR1-rgw#e zpaN5!%Yko4Iyyw&-`#z^-+5y;Xd9P9hSC9Xjh1DxD?|kqm>5Cjjlu#;9#DDH2`X>i zI;{njH=tGP42)+JL2O?ZkEVs0;#saN9S#iw3Y=^l8GNAWlnf<-Ybq7r-b7~J*|Bj; z-rXoQpBWDX9tJLUJK4r74O&DRw9u(_LDa)LJBv3JK6X2K>eM9A4kJg$M$n>$b^Cs0 zftEGjsd~NE@#^`@2OBf9vR3)bwF;eOn!U{6+W-5P|JmgJ|8!cPn{T&X?5>c99a|TO z-;l1~|8Cdo58oaL{m9zobU$wIm2Q_DChM(PSG~HryHih3(+ye|vr}lke#8a_{YN48 z+wT;0|2i{&+tpunuh(wBvdgma(~^*tL9Xj|z0%tGd|vgFb-UkfdRhMFhGFLAWxa|T zhUTlUW?h#5fBY6`WKPxIJ|487ZReX!r2d~0?KTS9K)Q^vkpZ@uLK79V&!sD_+^78uY_k8l|)NE!ksc!nSMIH2N>wFj zk4o|m8xlV~Y?nW^|Nr0o%zJxw?y8()QRvk0IXu2rRiR5f zz9vvBY|V;a2VSp`tN&A2%6ugI`=LmWrnm_H@(i5=b$@^DR6Y3ROUcuX3B^m7ESd5_ zZv#g=zx+C}ub|0Ov(@X5cC5=_e$Os_tm8*F%iWhBpUeCtESew$AnZ*Fh*2epWlyk^+f?*mN`bm_d``#tXE?d|J%`EGDMxw#?H z`6;K?%BI4+%k(KIyu5t%?mHhJAD?==KcM8pgM+GZD%~HLXFvS?et-Crf}^708u_}4ijI{`-^#B+ zSDt#`6i9}2dR?XeDqWU({`Bd|MXueTWyq(3TO=+Pe}8w^>;28m>8q_ROWbyRSzrIx z`|iq(k#k>m8Oqmw37lz|+;)k(rGb|<|I~>aZXTfi9+N-ILa{yK6%rpz9{7f?`*Yp< z%)?NN%ZD$vMeHnEx+_vAa+6Eqt3H;kb`Ln;-`eVZ4b;wxDeBy%*?3@sn3QQ&iZs`* z&{ZLxcUKe@7mHrZXi{GdUbk(bFmKbXYbV_P|9n0_RD$cSz%T2`jLd8r()<5@yUi6} zUFh1>;qXB4Ud7{H&?@bA=Z2h(W`Z9Rax*?16^~yL!W889@XueDWy+2ff}s6^e?A=M zH!67Gu(gv<)@sSSvIvLM({zIs`8b4BnEII)YCoAs%!JQL#wu!R zr=Cua&*K*VvO4qcudhZ`Uo!f|x&v*u`bMsgvvqxPfm!k5Wqg2oeF z-6HN378YtPZ>v0dYazI+YelB-uv+5gEZEBf9~p!mK?(7 zToryhE>1bR&5c7K_rcDCmyhx*@ufGFoazu%zS2L9>%#U@*Cx)5icsOiI&XJ=*xA1W@~p3w8^=l%cx!UcKF-aR=vIrnbX_3XGl z<=Cy+`MX{&6Y9S4;>J6VfWsn+bL}G6=SJlgTVFmb==Pz=k>mUQ`ufff=Q%i){&V&3 z$-cgB+gB!ij)?~z9qqnaAf@;?jYH^&#V;lfCnuYd^-u4fN{TMucHNHMPQgh))FwQ= z$%FMtyJ^SP4E=Q;0>#d=5`KPqTJ&^kxK!xbYkXEpGHuNT2U*1{YHBrN1O!zwSUh@J z3XdON)D*tJTx!qq+j+ZvD}$1c^#s1NpY-m7m0ZOG#;t*Gj%sjbSt{#@h1~Ax2(&e2 zs{C|PeQNmPlkW1hOKk3T3ahX3TCOcr^Je4mCGP!l+p>H6-uAHsZghXq84%&UA{jgl z`qXx#<-+Y|?A5k155JsLpT9z8&EDrpEi8innjH!sA3Dp&B%3(>>}>PZUYdveUiAET zcDSeDH=*0@07u}%QpZzC(aPW4rO)yyNVvcDf9<}S=Ht{~iUAVxl ziKF=2`}^znI9DHJb5s>5chAvM>Dj2L@Wa|eXea+$?iD?g6b`9Zr1WX^o)c>XdAxDm zuf;;Q?r%I<*m6RYbJ3=bWPw={vbSY9n=Br9T2B_!jXE(!GdM>jV}1ML*9qGdo!d@q z$-L|(QwbSV3Olme|AX=sSCNGeTV%xd=sl59RM-s~@_EW1xWmacN`Bt7qubof?VfQI z6_$T)spIhenz%PmsOIg~>mgN6^W%?hJ=b?jK|XqSS#I?As4hl6=N)04%1tb`mg*gM z_&J!QZwPY6)&KpP)tuS1Tal-?#j0+Ce#^o99S_+KKQypWl<7an=9GAJ=7JxKM16Z+ zz2p|!q8_j~dAG7-MHz?w+^5}1$;nsSip<#EEfjfN_X$5?md;3OVJUQGzW8dd#}hHr z_X4fLf26lvD#}(+5K!4;D8e^^+hs=o9?c~>+f2QhW=&6>ziZ=uxypDE^<#aqtM`Oe z7e3`Y^!VsWmOl&Ts-5V4^_}BQ$AvrdST=9otZHc)`Eb?#iBfZuHMSVbawa)0+>t1s zBqAoZYL%)JmyU*e(;Ok2)?KBqwel~nQ19q%`@sLOt?U<<(=G-Eme-(j0lpmCSKq_W z&&n<6S-rUGS2GJZ;R$x_|M_h8(hb|@?^ah?QJFlis!74~$(aYHiI1~Y*kS`>T}374 zY1d8QcALoE^ttuJzlR%}&J@aOeVhd`PT(VNSCsd&0@NXi=}tT6IfD0fjx5cm5R2S>Zq5PSvMX%e27VPgJEl z*{$keui!#C4%yJWzdIebe7>@6o&amn6pO{|e;h9SQj%3-7fE{{y7*N7`srqUyNjD{ z2^-8%|HgXG{S~WAr?hgO+%IXCTN(FOsjrmtey_i7V__rLVlBPLtfJ1sxs|p3vBr+*B;|wI&Q0?7l=<1=Ax34B%O?@RtAN#M+x!r!)?Rc4clgGNpI;!U;GwMId zb8I*uAQ&~cD|ae#^onI-n3_HSGG}@`Qk;! z(~XM_mWlT=EHKWi+ps;(X6ssYX=(SR3;6SVZcTQxnAG&SQz1vjlBp83CUWVs)F~{9 z>LMNq{7;-4_4|Ah&n~E!5qGZWi81VJe#!bXP(V4aVhvw)Ql$J=(@E?_U)~t3YT5Bw z`DCAa^M(}@mauDPu~%#~m@tJc^I-R(V~!^p)Hx>TUvd&wnRby+I^)TSiCrSGoX1?| zaUS7*CAc&9V5y zecpAoTa{DOi_2Fn9c}A2Nal2JUa(=N@$Cm}?EJDv8Qh;g{jkS8r~9~!quaSdLH;?f zUy3;}vMXv{+)4j zy!Vxo{eBl;Q*3JZSKHM0DO7P$8mH-pE!^{}3e`^>&dgs~c-`#6{KX5}WXwKIteKy% z;NtTN7lku|4pXJv7v161TKntxjXPVPKTmaUcvx_Abh_1qY!X2IV3ymj;e0vWULtq;Fj-HkBXO1`Sp+J#1!}mxQu9jOY1#P7e7S zD>XsgswRfGRTC#p+{hXqKNULk@_K##zJ=hGWj+nCnKtvUvUM9bZsdOa`0?aRmoIy^ zs2SKT_h32G=MWVY6<1bPmR46+r+-^~W)lZ|=kDLkGlH{fXBPZ(QP?Elz$ftjEn?&D znGf^xi~nWsLq2C@X?(DB`_ > Chapter 9.1.2 **Bus Enumeration**. + +Host Stack Requirements +^^^^^^^^^^^^^^^^^^^^^^^ + +In addition to the USB 2.0 specification requirements, the Enum Driver also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): + +- Enum Driver must not instantiate any tasks/threads +- Enum Driver must be event driven, providing event callbacks and an event processing function +- Enum Driver must use only API from underlying layer (USBH) + +Implementation & Usage +---------------------- + +Host Stack Interaction +^^^^^^^^^^^^^^^^^^^^^^ + +The Enum Driver takes place between USB Host layer and USBH layer with a possibility to select configuration with ``enum_config_t.enum_event_cb`` callback provided on Enum Driver installation. + +Events & Processing +^^^^^^^^^^^^^^^^^^^ + +The Enum Driver is completely event driven and all event handling is done via the ``enum_process()`` function. The ``enum_config_t.proc_req_cb`` callback provided on Enum Driver installation will be called when processing is required. Typically, ``enum_process()`` will be called from a shared USB Host stack thread/task. + +The Enum Driver exposes the following event callbacks: + +- ``enum_event_cb_t`` used to indicate various events regarding an enumeration process. This callback is called from the context of ``enum_process()`` + +The Enum Driver exposes the following events: + +- ``ENUM_EVENT_STARTED`` Enumeration process has been started +- ``ENUM_EVENT_RESET_REQUIRED`` Enumeration process requires device reset +- ``ENUM_EVENT_COMPLETED`` Enumeration process has been completed +- ``ENUM_EVENT_CANCELED`` Enumeration process has been canceled (due to internal error or via ``enum_cancel()`` function call) + +Device Enumeration +^^^^^^^^^^^^^^^^^^ + +The USB device enumeration process implemented in the Enum Driver is mostly based same process in the `Windows USB stack `__. The Enum Driver's enumeration process involves the following steps: + +#. First device descriptor request (to obtain the MPS of EP0) +#. Second device reset (to workaround some non-compliant devices) +#. Set device address +#. Second device descriptor request (to obtain and store the full device descriptor) +#. Configuration descriptor request (to obtain the full configuration descriptor of selected configuration) +#. Language ID Table request (checks to see if en-US is supported) +#. Manufacturer string descriptor request +#. Product string descriptor request +#. Serial number string descriptor request +#. Set configuration request (sets the device to target configuration number) + +.. note:: + + String descriptors are optional. If a device does not support string descriptors, these stages could be omitted. + +Enumeration Stages +^^^^^^^^^^^^^^^^^^ + +The Enum Driver splits the enumeration process into multiple stages which are executed linearly. Depending on the connected device, some stages (such as fetching the string descriptors) can be skipped. When a stage completes, a call to the ``enum_config_t.proc_req_cb`` callback must be made to trigger a subsequent call of ``enum_process()``.The subsequent call of ``enum_process()`` will then select and execute the next stage of enumeration. Stage completion can trigger the ``enum_config_t.proc_req_cb`` callback in one of the following ways: + +- Inside the control transfer completion callback (for stages that send a control transfer) +- Direct call to ``enum_config_t.proc_req_cb`` (for stages that don't need to wait for any event) +- Inside ``enum_proceed()`` (for stages that require some action to be carried out outside the Enum Driver) + +Any control transfer made during enumeration is split into two stages, where the first stage executes the transfer and the second stage (suffixed with ``_CHECK``) will check the results of the transfers. + +When requesting a variable length descriptors (e.g., configuration or string descriptors), the request is split into two control transfers. The first control transfer is fixed in length which only reads the header of the descriptor. The ``bLength`` field of the descriptor's header indicates the full length of the entire descriptor and is used to set the size of the second transfer which fetches the entire descriptor. As a result, any request for a variable length descriptor is split into four stages: + +- Get short **ANY** descriptor (prefixed with ``GET_SHORT_...``) +- Check short **ANY** descriptor (prefixed with ``CHECK_SHORT_...``) +- Get full **ANY** descriptor (prefixed with ``GET_FULL_...``) +- Check full **ANY** descriptor (prefixed with ``CHECK_FULL_...``) + +.. note:: + + Retrieving the Device Descriptor is an exception here because the second reset is taken place after retrieving short Device Descriptor. + +Cancel Enumeration +^^^^^^^^^^^^^^^^^^ + +In some cases (such as a device disconnection), an ongoing enumeration process may need to be cancelled. An ongoing enumeration can be cancelled (regardless of its current stage) by calling ``enum_cancel()`` which will change the enumeration process's current stage to ``ENUM_STAGE_CANCEL``. + +On the next call to ``enum_process``, the Enum Driver will execute the ``ENUM_STAGE_CANCEL`` which does the following: + +- releases the device's enumeration lock. +- frees all resources related to the current device. +- propagates the ``ENUM_EVENT_CANCELED`` event. diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst index 2d23befb42..6b1c6fa9ac 100644 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst +++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst @@ -22,6 +22,7 @@ This document is split into the following sections: usb_host_notes_arch usb_host_notes_dwc_otg usb_host_notes_usbh + usb_host_notes_enum Todo: diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst new file mode 100644 index 0000000000..3e4a5dd75b --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst @@ -0,0 +1 @@ +.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst index 1ab83954de..c6318a690a 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst @@ -22,6 +22,7 @@ USB 主机维护者注意事项(简介) usb_host_notes_arch usb_host_notes_dwc_otg usb_host_notes_usbh + usb_host_notes_enum 待写章节: