From adb468bade62f77869107d8796bc4d52ef3c569f Mon Sep 17 00:00:00 2001 From: Roman Leonov Date: Thu, 21 Nov 2024 19:48:44 +0800 Subject: [PATCH] docs(ext_port): Maintainers Notes for the External Port Driver --- docs/_static/usb_host/poweron-timings.png | Bin 39711 -> 39353 bytes docs/conf_common.py | 3 +- .../en/api-reference/peripherals/usb_host.rst | 54 +++++++++-- .../usb_host/usb_host_notes_ext_port.rst | 85 ++++++++++++++++++ .../usb_host/usb_host_notes_index.rst | 19 +--- .../api-reference/peripherals/usb_host.rst | 52 ++++++++++- .../usb_host/usb_host_notes_ext_port.rst | 1 + 7 files changed, 186 insertions(+), 28 deletions(-) create mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst create mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst diff --git a/docs/_static/usb_host/poweron-timings.png b/docs/_static/usb_host/poweron-timings.png index 867253da18d734fef4d86af9f0628431169986df..59973ec9cef28b29a8e387e4dccb3622ff80b4b1 100644 GIT binary patch literal 39353 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 Z%_=?Au4!Pv+`$0E5ih@k<(}B9e*^N@YyAKK literal 39711 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

hoK z`tBuQNA~*cBaqDOTHd0E7@C?sdv<0Z#m@fdSR!4U|0=F{xC|jn6G~W=1=%vNE-@Tl zN(y!Dt}^CsW4xJLEBM}NpS$~8+6YXuSwx#bupj@e2u~pvIo5nNe#W4&Gkr=(%*WE+y!Y`avdU1VzpazpRi@X zn|_O4aGpziK2IW^f#3oXNKYSAnAVLal02WDJ64T}>veWT-Xf0mPnprBrGzOdw)O6| z>)#KX(X$@YwG8TPqu)-*}SU7m^RM!zln$evpk$jdh)fY5QqU zg0@sQ*Nw|>DjsT*l3o((_{yR}MJnX3{ZbV5fgP@yo>OGnRe;$!o{uV=xT-UVuNq}- zIZ4__2YQEC97^IDB{uCaJu7ZUGO10J zZg9h#hHV@0S-a2+_FE6&I#xEVs}#`ABa_y`n~7NKux~_GAi@pIe;wg@Bkb3+G@4Tl zHn=XcN7_J7Q4x-{;Yfw0dOkIqpaeQGX#Jq`p@tLDPh4#JbouMTyc(H>bK4GzU9l>xyGb4?;&2P zLN)@+_xMD`G_)H$5iF(}o@@fh<0YDe3VC2fQ(q5YJ$3SL z8TzeFX>YBkC1rvJxU76zfd0bPRaDYk)kw`=st;8)4D>ZHYnTg!M6_ND!(mQW@C1gr zGW^ztOqKD7{akJIKVY)XJhIG?u*gyR)4XlLxM*+omBMt*JehsOgp2dxvD?jj7I5|# z`z;cUk)IvuXRQ0QoKs}i7X2HU=UwdXO6!kTS_mE@I!%m<2DI+LFuI&k&(lWolud6~ zSs~BE?+=B{pbCwEd=IQ|{5Ez)L$1cI2Hy3&-S-Yok>lOaUVZgl$5;>XZwez$rj;RWNgg^7%Hv|%P(aASQeVo-5CEur=^>pZ zv3w4FsHR;7{A4FS{H0id@uf1lb0kzAvScpW{BRA}E2G!X;Uo zs7kBRKvrg&UJIR;EE(7-bH<~$2TOO-<~@E8<}|{@t&PcgRY<~et;gmrcl|V-FFe81 zdWIx-e*UG5uN@Q_YfE_A6x_PaNs-t3msL2SNpJCo=%)ZPxvDHRcsZmq%X0SVU(W7+5 zgF0g6-y)o^ohro_I>D7<5a0|vmxpAbwn?e=!i>LB(pdx8pg|jzo$~gwfTnX}U?^s7 zx;Vo}&`!bWm;QWWanHu{=7z-sO^VPHv;Sem~3i z{1^>mFKt-C@Frh72nL`q#v(mE;G+*COK$jUX#B2%sspUOY)M~W*7=K8cRo)c3&KNmbj%SR*fT@2m^<>_@7 zH1K-zS|u<6z{qWIAs?(Ar>%CHm5bx#Nj@EkNafxi>`3l#$;+d9| zn7Z2jD~wf$MO@HIFOu0np^BNVv?)escvXjxm#;fF?o0H@rcyRbt>w8{ZtZ~q_rt&~ zxPVhLX#*2%RVu={G6LaH*lr3br?fWe)>R`mZ#wC4=6gKzGEoV4p-%CG8SI7~vp7?n zB;9=bCl*{Ck|i{sI;rmcPvrtA!|)fr&RgY5Wyk2^P`A_gCC63>gRs2=4s^A+ddFCB zcK267#z8Hy$GJPrjFMn!ChdJzC41zESH~gJ+Y(~a*yi)pi0!>XBs=bxWzj_3!rQ#s zwd&!6qLAF?hT(=6@cxO2Xa!}CS9UMSy+vdd;PAiJe(5Z<*uQq@gN1KhvPtrgR!E_3 z4Wk8Vsh>y3uqh4o7CA!NoZ%h&ARqmbu-{pZ>;Lnol~F@`ac7w$y-09lS4JroVKxhA z6iVP1%^VL{p-#D1rLlTwa|5}wJW9M|n)B_g@j0V-_TDrwUXA&;Uh{X=I+*q{&J4p} zrVJtlTE51p0>RbvkIiErBxy1TA2#KV#hYGLi}D799kQEeKkck#zi)I=l_q*OxX@3r z$|g2R0L~gDJfJg#6Ki!UkFNi$fOLCMDH??iIaXXV-0$=ifitY%@e#1l_#|E&!W3cm zFYt6Z*GD53{jZZpli>G12mu3&+UU_}NQmG}f%ATi!k6NPh9oefBk$j9Nj(?Cmbxn<;B$Yc^M5PV|2yz}jTk5MFbHP0e>vB*EU z%9EKgU2jS;8~2WQ|8I@gww`pEIBJlx*Z;90&GUWpbPxFtyV63wea3=O#n$A|&kdqc z&<5euZ&QUDW6ZvAk;r`QM`P$xNb@^&!tkuJy>KSnBXuTBHz)tBIDOiqT+A3Y0e4E==(dmQFu7 z3Y&;A;d9V1n7mG;Lprr*KEkcT{D^f2@_Y`m_8whng;SlG+h%I~23m``d?%BDH65+! zX7q&JcnmdsZmQ=|e@MN*kp58aIaP#VADVoCJVuU4(xjI@a(IwL(mm*OyHOV0C~Tj( zDR1SmcL~?c4%K^jR?WePtl}pGTa}FM#O1uE7mS2*u|UbJgeL8*r(j~Et=V^liHTG@ z`ZNw!I?T`a9z38d#gq}H#(TRG!=+YecH759s~E)6miDPC9OSZF89Jw5kriFGNDo0u zIv9N43{^76nzXFpqqOpjFcBQ!CIQuY>RRWW923(TyC;p7%PJHC&sAnoraFfh7by@a z4%peo)zgiz1X054wrneKK^b!z>j)VP5icZA*`L?nH@hp#1qNI8xuPDR+|3948-qXQHLyBZwJNr}$tO zYE%jP1_#pumYS-!vapA&UQ6|_e3u?q}o9@Zjp7x-Fa3g!$xMLG4{S?=|B4!;@mjR9`9 z8uGg(dY%b?)Vc}BDDaF+tGsu9TFVI4AAKTQVZW7wbTf#bZxR3NxFi7H_X!{gmyP&m z##^Aj63_t6d4_=83Os$I*JRL@L2$9UqwBE9UVSE?6O^-fQfWk?V`Kf1GV`QFZ`4d+ zCivGX(RHy>`^pCU!qEd@?8N2R&hMQ{(ZGggL5)@_Q{H9$dDy@x7>%fQE4|uU9Lx7l z;rKr_{Vts?CP7|)qF5{+IIrY(XA<8zAHadV)EycI?#UfZs1I~U)Zo8UFomp}{BPXGPk!UC7kU5|A*1Rd=A zcq19<5q`-2{OC~BzcoCci^cVewgG&tL|gOpe^u@Qp)Rhc=x&-%nM!$WPoA9f=-iz@ z9@P&RKK{9Mc+@GM@D4YW27{&jFnE9_9-G6@#l>l64vZBx>qgKY`j)1L| zZixd_5(3;@!36GQ#5@JZ9nVVQUf)U32r=K=$oh6eEAB#p0YkJ>YKj`qDTMcn(d2bLDd{yTH{ zpndmaV(L85R3%O!0LH#2BC@Ul1XvnVN0&g&s1dnqR)d_gNsa|23MygbIUC_#3ZU8* z+_{VBr|95l#Mh_pJW%Iqj`RZL^wCZjX>+wI4HQTI{gt;bBS=m=b5;1Og|E-5Rj?D> zkFDef+vPw#BH(&L7xuhctq03~OgLL@jDQU#dNF|@wd0#$a2}L{!(T)xINYlR?Wbo6 zU&%b|G>hkS1N}WVXFvn(m|2_kJLg1=*@(OfYJh`YB*mXGn0d$4@T*;sBzm^M7vd7ww8J0Ul5|0^8<2H$1utnHHJ^OO#h(*!crweoZk zLZUWQw(0*0HGq*{tF4Q?Bq+kiIm=Y@be-3KODj$Rf&AF)avB7vf6HFU;fazCHZVD3<1P=-@`9$yRZprfI^gDrH*fRee=USl> z*ChTM3f>uhRFn0%GNv4?HURx6hBwdTPuIv2hvCx1s*b&F6LjAKYG;oU0ICB|S}@LQ z>?#0~UmMvU>Db)7vpY!6^v;k6Pt%Qy7brf2_fGq@==fU zY*5%L{F}o9oNUSg6X4`vPJOc7J_64Gtegs<^F&8e{vQPxz)7kLJ~F*|r+I(fg&?JU z`QP98S0i@$lASK?7i6T{7L0$~dZs%vHTKn^7|V^nN-C$+cOINsUH)LwP%OD%{rIoG z=2V{AGlZzx5ZH7Qa^a+drPHYNT*Suydle?xr9UX)nL+}EB&&-sH<<$Ry9$!oz3AyT7v((4X_}QDQ0A^X(nUg`3HAI2VMo}X~_3-b6N%PnxQvz zNvQhJvKQS3x_l15!{N3w(vILIijW7n9w+$yI+5(S*UO%?rvx?7O13ukw$_y=$G;*_ z_-Krj^yceZJ$V(`!k_#)d@QT)v;xcq6;WY}W1`uheh#n=eui*0r&h7*&S?v(;APrD z#QN(K!7hybIVT%Ss~6UMpjYkMzJ0f#ibh75B@`RP+21`Nc&nN9@yCkWt;zKfB&{WU z5!>JQf1(9@l^?Nlhd zu9((cfDmU(op`M>mt`qOy8d4Oe=k+MGxslcwMRz8A*!wrOA!`GzgG$vGf8y_>B7T~ z^Z6X;`7D_Cc572|2ip!8#zc=b_tsFvz@3AdtW&l(&4+7%O__fQkze`0+V>~J9vKy^ znbL1KYwq4TcikA~-!H@8`wRi^3WD5*VS*#$_whFHpw45?CB=?$cSu);l|nD&$nd`e zNM0=6^l2xT63j4xBpL+;6LU@pkD*$#|&S zTOz-3rrjhf{>g4OmFokpv;7mGgPblyR0Z(;)&Jhohfu%H-wue4xWNL!#nfg5crzDN zT3)LIbMocO$oyDhps>o$n@ERdotQ9~gfydm=K#?%=43vN!^wa1Jwr{404eiKYf!YV8$c%d@rr^=C>3z@t7%R5wn zj7Nqjj6cD%cKPjlUmxlT+niik0^se{WUDKEMrZ>)-Qu6WZT#M>mrme?? zUszQ!);I{=djrFib5iy|jZPSas}6pZV){A}Zu& zOq9ai1wql$)YVTLJ}-ADn~LQ0MIeo zR$vge0a3AoRUKI6;*AiN8~+k?WZI!}8|H9ucw}f8SNX3B7C3*8j^ZSu7#Gpf@2L^N zW{LK0rCL~;y}_6TWG-&pH;dQ$H+u%L(fQ;z6io(m zZeb!9*LHmjrHTKmd90t1bB#&NM~j&P zD4&exX^MTW7x0dpP1+j$&tr}e`7HoQ3V{8Crd8U?o;$GVS?~@7Kwd}{H#+=VQx@|9 z;~)4k8zmrhpJGlwY@;9l+NE7}@6}N>x(>>{@x-6us{{>*5QtcguMiA^ss3`xBtGjQ)p+{&YV7yO~8c1w9lk9B+>3z?*WOwgbD4}U4zPD)j%n_oXMYG7be?k;q&l?|N(Cz5{nKIhCN)d%0uX4X9?b`5@du%6b9 zFDiu`w>(Gm4&j9dwr$HOuV7p!+ACdBq81=pc1X6q4G;OsGBvPMbHmg2c&Sa4IX#z& z%^hq*c43p1A-Kq1z(B~HB=B`ZC}XBlqZ-5z zul8&dJb`(aHU_c#G)9=~Jx5i@q-@8n{zqqMPdtzq)KX!i9ysu+cS9bs0Lvmpq6+>Mh@@B83 z4UA>#tkEFzgDd257M&Iap+2i86j**(D)wgjS>0zjL-Z+qhpnq-b-fp>lHjL+hBifs1F*n?{0-8LQ(ab zoxGHZ8t=)cug(VTVl&*_LL)EA`MJNLRZIAl^^R`Ccmh5otcY!LfDGQdIiXu`zVIWp z(`j78=iDaWNpe+TwF#3=1DM?XLcVCjjbtCNw8+ITC%G_T)mQKOExUzuZ;SA*V!|jS z-Q$;E)KPVAA>Pg2&*Zbn%4=+Qz24K!n;4N|3_6tP>XU+bQj=BAMm5gJnMhfBG zr@2CIveKw-S>JmnL!+{9Gndm4Zp*3j6u{%vH!$HycqZwTfY!lJSv{ZA)GlhcmqDc+ z_fiO?$A7*SJw!rr`YA^C>Y#u}swyY5xlj&yxSGEYMqORypLF$hv8-pTQ!s6dqxW?$ z)(tu|_q3Rt{u+Y2voz>^@T0s*<1&xO%f#A{Swp?v28{Y|kl2V_^8nw?dkGjMyDjL) z?~mnI5E+=-IM1pEnF7RuvdW_M_$6~m7Q<%ZTfBkOwZ{zk{D=wD-KQi=z%B5_e`oO5U z^=ac0$14IPq1Pt-{c%9dnulv|`aByD;JL!75Fz}<<6Rl&(nT8}P1gSv3wCX4-=kwS z)q2a<&CRuz2cGCTOnXMC*X}sbFeiY!x2Y$LQq0GqbrOf&qii&Z3Ddr@WH>b`+(OO@ z>OBoMA#E6z(F6zlX|pgN3+oE{{1g#llkEcWTe}%m%%2_bmiFYSeSXm%;x^a-dfT{F zf13sFub--)%{-YfimDv<`gp=MY#6o%^bJ~^IjFw2bCfL^?y~ab_5O*Mw#=IBpBQ%q zAKjF3SaMxq<|1Zl3LIlb(a}O1GgeFODbKTTd%qOny#H+EMLft>47}tNw-v0ycAFba zrUm4@|2hAoEN_*$y)>=8Ni_ebYqB}5*4MMj1L>%C1ZlKh+k-cK|L=3r?zl+%_!FiTNHW_8!c_Mgubz93b~;Tj$~_M~#%Jt6E>F0G-N~L<+}|tv?3FDe+yk zS&vVTvqF_oy0zwzPtnH8gNh+7iw*XQJw|1&^m2YV8l&H2JjYZ(&sD9tbayf7#-O1w z+1mMZytL8Ipa+y_cFC6srtg9qic^*at9Gs#0ZjbqZ|}C3Cd}`aIpu<(wrQb=ogpH_ zLc3|qh|S?X&-coO(Xt#BZ(I#GNLduaS3Z0@#O67Kk*=FS-C~MCR#GoOK;5BJrBhOI~~VwQpB=D|NNrKi&dqi3E(FYJSahXa>doc5fY=2u9$}j@F89~{&NJFK{U#sxsaY8Mbq1SzkL;9KfBl{+p8o*X zrV#Q@xZEB01o&n5o5sEUYp~nd44`zj5d|BtdakB7Q@|Hmf^Wh*KP z<5me}DayVStz_SKlHJ&c#$H6FaF=~eS+egl3}ZMnP`Kvgu*Xx|?T<4tUbzRTvI*a|bZG$h1GNla@A`0%GL}c@s)tu0Z4Uuh`yDx02 zK+dctNP#wW5+hd3CGCC^1a7kL{^ScoZa6qO-<`Z&_7Z;LXAfvEkWSjfP-fOI!OAY=|s3aW> zCdF~ccVb2syu)>>+bRml6}4q0*iUZ2VRiU<$^G_x*Q5q5PzYKLHH_R~VC=Dys=%qXtHDJZx@n8IWo4pzC$yxp5 z6GYr_D0&$oxN@BioLG9kdfVw*G|t>bp|d+Gjw9f;^zF*%i4lG+143y=GMA@ROAv(c z8{Cw(aXT!It_;ok>%3}uZq2%M70%LZc+gB_=!B?5d?(}e(Nq5AV4S~oOq46o3AK=4 zC5!-Ey0P-@K(hLbo~m|@%Y>L9{RYohxKNZ=KQ~vW{cCP&>}Z)~eBNT`uI*wWk69SQ zt|l>;w02Rf;FM=cA)duuFWT>$qve)?;o}iiya?u2lGdO}sVq@$`!0LiU^cO99Txj8 ziLHB)t}*?p;d-5)q>8rxjFiorr%mG4^gqJOmi7@9QNBLRhvF&bKievwIb!I4%Lymd z@UrW_o%&W1!tSHM=E?7~c#G9W0f0FAkALQouaf9VxdU;4Lty?Vx6ZZjG~sN0ttvm9 zbgg0ejaO*RrG({_zygAbRA~S*M=wis3UH#2(rHmPq%B=if1{P@oA2y?Y*BpOU9@0v z9rstx@i4a885_SrPBmX0V=Z_9v&)>Ab*~1y8_`+BP!E(;a95{?!N#ctwrv?l7 zsL?MOM}Z6)hHC*t<)rzqmL^tmAPbkCoNv*$-$pV-HgWe=| zT=maigm|9H6*Yvu`vOo&WL`}U@-e$h`I$mO=k7*!x->WK!Nh}Eyw#XiT{O|lcD&0O zaPLlac?8VXcxO)hBGv*gMZ@(A(j|a*f7HMf>`%ZyL9C|Mqo#VB%JS~)ZYdrp`~UE_ zC<@qfr&4f15Zbr>2|j9B#C)Suw_T0C_61()nd)}+-#z*RvOSl zNarpxXf=+Qf9toBc(96P<6QD;K2c>~OO9C6SJIdT#A?i0ad-zzfvn#sxEL6mH#$f- zAEMvue>lMt+JOt&)zM00!D`iM5c}aPY9ZmfO5QBi)O}3W(0mU$MWf3q#7a4S5H5n( zP{UM4-4E@cPei4cb}8n1Hao!8Lpr z@U~~P2TjS*S%J0+IPu1gSN3I^+dYTcBktY`>7>Yz4qWx_FL;Lf9|>5XwQzViu+;O3 zwfnuDFjYD2sXo39KD?oJT5r++ObXup?&hm0o7I89>fj@}Zz^>*(Q*nDNX6{<)AtZ((gIss#LKKFH^4& z7O=SYKTYJ0_KdwKgmwK|jo?A%INOAim?#yWYrF6P05P|@NfxRQx&hD!%EGOrH_q<#w$BHc#*Sh-r&-_Xlbkj6dw~xt&9HO8wr$Fspc)daD zylx^#P9+$C0pg@Y!Q`&>;;tGUBtRG>b6yZoIo-q?XRUJE#ak>#ks(XMFvpq|AGW!5 zG7LJ7zMt`tBW~2_wXM7D=;dK}7fU$2VKJ?auaCsoqRX7eOLekmvW$r;XuJ7r!7E22 zPG@!SUS_;c!Z1)ZJC)nz_04r&1Tj zqObFOHC&yG@WPRH4DkN_)UO&n9|GSJpp$-54I%2IksY{Y@-H56u4}WY!d2hoOk8Il zR&)Ei0!F{wVr1aWgoI;yhS(ZALWGzILO+W!2LX?` zF>40>{xFqP*`nhU`n=`V=aFz?iU^a)(No>8Sl#p|N1n21=1!zqVLqe%Qgta-8p0<{ z%-aEydDnWZFN7K;m`Vyim-lfr;x!2-2S#$}eG6w2$u?aX#kn>kae`~&8T5SoG4mH0 z#IvtVTX^IEr*zLoaG(~uQL>ierX0UHHcL`9otjQRb8PnME%Ep+PUwD9z(FVHCdpT8 zv-pX*?6G2f?p}*iF;9bb(dUN?4Xwwl{A)15rp%X0EjkoCEsC!6LhDQrfm?9JQO4^} z^2vPliGWx1yyKsEZflB$;jvdT4}IL`N?6kH=uD^h-XBRm;uw<3_LW=zV*k6I3bTMi^XHV+-6(IxiEqhq zm3<99LFL~fGKt%J6rm ziEH#jWiWtAL1AfK^dbUY)Dq<76}5 zhsaws{W%`f)!*liV|^j3UxhDtXCwA`^GV3Zy&pCZ)_IOBUS)q8V>@zK?|pGEMdO!r5^muOlaWf& z9PzPvu-mI%pOJ?<-9tbCSd+u4#Hd%5Y6#Iak)lW-X`N=O6wWdNH14v`vdL#z{h(V1an^l68+SNU^l zwhSnPq`QlkHLj3vM{&F>RId~~^9@g-e4$A-;LRZfTjj|E#QYp`kxnO!vRTU86Vttd zo)h{FOOhs}pawF*n?2B79-tslDidz>;kl4JAg*m=G?CMye(yH1_+!LQpqq$7N7U$s zmMi#7HBQi;e|^`kJ3I9$gd03oDm>Bkg}?YliCp|6N6RDo^EBOv0DIrlCg2cOAo*w&c%8 zG;D-JW7*If1C{#6`?nK4>c1kbVw!4>9!9aMYu?OD!AvhH2||?4Aw_ERMoH@Y`V9S zOk0C*WY>YCu={aHD~!dWH0i62Su7J8yq<#4VKyg@-D|n1{<+faD0-hr7+?D7pW=cK zV`IPCu_EObHHkXrAg;ClCj|8>_qvC40#o3-#^KfW0E5LI^RG2UejNw?VuHG+rAMTa zu3n$at1C9|DHpuiF4Xjua|79WfZH$hkK50-pG_te1}!U~rX34h_5Th(^O#DM=g0?ByDNjs-_TXyhM@QBJBEV3gVZ+_33> zKW~RsaEd1G?W3kDHfO}{J^JWTFFt%ef9-W&M8Uh0vf=Y=iI5+1HY>`l(g3R=IU#Vu zf_^SRaBQV`otLBQtbgJwi>$8o?zFfR^CNeNSA~8fL-!K{ zQm<;pj`@#`=dcCn@+Szy@HP<(>qTiaew$!gO43Y2PP~od2s8DnVjv|YeU6^7Qc}2H z;x(=m4o7b{y)5ihD-@5>r6^Kv^Ca*;{OlVdm${4dU-W^i(KP;ho7V2d8~m_ysB52) zc81m+QC+L&s!J-48;l3tjXy7*pE7_h>}oyjl`hX;6~Pg$SI=hB5`Jy|GB{{zc}4~V zVm@zcVA?|&vDGR)73;Kh&8hzH+eU_s{&=}Ub=6_F2tQUXr}ylIz&8HsXLy2st@r2> z%=P4VcbwH-^T{Gg>dRMw@G4VEX8eVjyI{)_J-l3(ZyDoL;Ba}rQTV-sr;|p}LCiZW zAOov8jjo^A2|JiJS~WaDv9gu4kfL#=J@gWPP~KawP<7;3NmA9$e~SPojii?Vm}|bI zb>(QszzX@SqF{@}4q#i(^z1Pgit{$s>sNrb3~H(E9>nv`GPrVl=1 zT&G>fDEeilAU0;~vj#Sg#=XfZ(pvPXvg1S@yDrm#;tf;tk$i%`5qkLF95};q25?wJaM)>bbC372SUEiIi?ylx1zf za|0zy)CyjGHGJ`+USz}j&QgIVQ;VkgV~m}Dyq#4(D?JokI&=rqHd{Gy%?YF4oLDwD zB*@oA1hm9Fhm?-1wSOGUq&}g_{zbL3m^HtYadU-kJl3}r?#EeGvlSdsKo{NVzKzQv zcC_N~$U!-$fj9>id~1yRkOtKB8=SZ4Jfe6Yq)V@~+`z8zw2yU-UKuApzW{(IqjUvu zVV~EvKoN};^gx{~szkWt2JWU{jH7-df2^Uj_P|y)8YQdj>mU88#80ehHgnQrTrQ5o zZq3Y8JOGG`I#adT`u>mmg+i!`|A zRLDcf*T-`=7D0tI-W$q9alRVYkH%fM{$hEEia9u#y0n>Ig>IdFqe>}(s4ZN!G|$QA zZG!4@IutsX=#7mb?m3`-X*Pv%BHu12RE&z2bJJ8QKzkI{Cv;3e@P=xH)e$qZ7{)pMi@C4o<%k!4XazSJTV$&e1!mZ@G|P_|`HuwA zlTK)`b4DG1S@ur!Z@ISJ-{&bT&3VvMBJ4t8g%zWAx_hJ(!MC;h7;G$ma6IJ~wyuw= z-EqS9rJ%Ckf5tcNEn%z=fPyUe;kBM9>H<&(gg#Z{tJzMcL5}oUo6Hl{_ja6?vz0Kz| zc$$&AKb^s@#`eQY^0lp4u6ZZq>5U8SGQ2Ump=$t(p$1Wpr&jEX`E6~<^fj3WPGO^( z^h087cY$Ser&~XSurY`|4E?HZBEzbiTV7lGxYgrewzVmXD1~z@HY^S_!}sSR0Z*lC zQ~mqnsBX*=?KYYV6b{OCHxj zSQuI%kpOdnpX!UC2Ie<~HUV8p0P52Q?oUO{c*JMfnY5H+sN4Dzpqti!lPrl!E+PhZ zpQdy__|AGzw3X$wR&U34M5aOIOjds<0rY6ZUxp=_IfSFj#sdec5Ic$5GE+;| z?gVPS*m-7}HC2+*Z?;wp;dWg5H2zkH@{R0zBw?N|couuhtuXNC9r5pog83h?p`?7^ zO$sbj&+9J^D+D{{=CIXAS}7)eezvpVHwHSt za(1=RRD&{Ie!OEj#aRO+Zu=Y^yrV**#h^@xK11B@+dOoIT z|K`c_h#>(dfXrMDD$w2B*b>MK`M|CZFqxk`ys-AXKyzKBk+EkB1OoCSe9{Uo-Y*Ln zOka4cJn`~~AWTcg6*>)h3lOWchx2yg1tmRN0IR56PhaM3X6EmXCY)?Cjjr!|L=VG# z4UkpTO`FwlD((2Ul``&QQ0+MxnSbl>B}uml!DNH3{VlgWA3!TpLZ{BQu5R%TD9GNwN&O51V~zyr8%Cepw|rkKVEtvKhE>xE*Lb4Nuz}nAFNrps zZ#sN2a!U00N3MH5HO7AtE(yHwDiFGUiSkD1@}1q`2nP< zTp*Nem(C9Yl_qu2fjo^OPB&k`GlIgF0cQSmF_S>p&0cn(fGf=iH$9^Y`lo3eht|s0 zvPuvadjK}5R(T>gAT)5hgFj^Nc@u1BnLvn^56&+#&Ziu1`!``4PWH6gnZBt}3g=AL z1~~hksEBw^)iVzon^05^E?qUjcBPwDOHsY%B_?{1sFTKorn4P~mgt z-sC|L6($tF?@3*zU??gC7XF=IxHxa&72ZNXuRrJC1~qS?CoNC$mXQPAWi8+GTK3Pp z>P}pJuPtEDrSo8IJowS_X7R)7SMn?%P~vGIOX^$zb!HVY!CVpSzii@p2r3_(EB-xP?_&LD$;PTk1`rifzo)w|Y+j0A<=@VF#OcuL;mfkrd z_kSl#PW0sa#3B2PYVI(PPh8@?vWpKqx=;eRce~|aS7yQp90daP+5XS#q9UVJ)!Ay` zzuX}hX3!dMV#EWDrAjR{i;t5~xsHT|;xJ)SIlefVCdS3KX!+P+)BL|)s5wh@XJ<64 zYH!T)@~ayahe!h@_a!vwv_>AM*|G@;if$edi6NuRU=I)LA!m7Zez-B_ugZoN^G7FR zBjTHrg@jct$CJFX~#oIJP!;P$a)^lGb}hO0*8(y6-;G+NT(IyRK+8=?^-9 zrcd!wx-LKKFQUXloJrkSPGAL$IB}kxoD7vSTpMD@tZK|kiip=(@^08UxE|xh7gDU> z=kb=d@b2^pB)$co>yMcy7mo>nZO@PthEJRW73&7YKDfg@RRo>5iNw$K5x5bwrJOX! z8xXYp#?QYqEQp`BNW*|49_}92-!%LX>Srr& zU{FW;9(=v--={|5C~c8LRdA?CS!?V7*1;E;1^H8;WDm^s)wAb=R34fHtdN*aXifci zIj6Aj9r2!DmDbVnBVDB!NH;NMuGuc+H}){a%*-;>`sS~m^Iz&fcGp~)e%7eZKZW1_ zGcwOY>!83ph8*qI55Y)I;cz9p?8UR*69hO9C{p(JUsZjS}P8S{OImbaBHlyR1K~}GMBX56mT_uQ0!df3PQwO3#D-JJ}2&>^{xVntDK5rW25_Bu2EOg`PJEQ8g z(^MQprivRVi*uoStN42A>bie%EOoe*N}Ww6F3NVaD@v1gcUPNeYk>+?xjt$Ljv)Yj zqvliOLWGJ4wpmtzbtsBQHP?O9hXr`LPha^j-q+16pO`$T@<;encd&$mP;-@NpEm0W z3Tb~Q)<5x!@Y~PAoy8l#=R$W5$%oYEz`L8Et%(s@M3sqyFGv<#fciezI7-Y}f}KRM zUfw@@ziv{m@5CKlm0NE=D{8`Oop!rwnb7-G@+$vO->ik@qum>^p?f-q9Z25$x@Yg} z&L?dn_^DA*M0{v!6d$L2o259>ok-n0qP|qx;5hQ323AGA zi6;2azXNq2$TgxS4p33j8?oR{DwrUM*0#+2EIewsR0k4Xih7_MpMRYgdbra!J0++j zGPir5y@{7P#m>b+HO^@I+%2NOl`C{jTh8OYsm8b>SH&bk(f&|BB^_E5vi}KHxMdsTqyZg6l*7s!C0<9DFP`%Wq~Z)hg~u&)GL{I_0HR8B z4dWy~#aI~cgfyDvD>vq|{5Vz%q5!0`|X*`mFblJ@W~X>*rTR zV%}vg6IMZjZg?#(2(mtKs)aCu2iMkM1Pep&tz<{ zNj0zhTrrb&P>K1%)>yA4%sY@xi5B|0ICyzu?I5VI18Jb4`b7}xoUyZ$Ng?{sdZ2JM zhXrfhjr1-wzgw&2N|EH!TjhdWA`cc=xmCjyb_&G5f^2fNu+b3GLD08<-v9$3ic3xM7L*nuuuwKEIsF**?u zpTGC=C2;1V0d=E7%-tr;LhXAHuph)DS zL(_Ed5yy7*`+;sfI>`*gc{hVZj@bdQzykR(3hD^f`X&$&U*24x+UY|~We4Gbtn4G$ zc=W4%fo>A-wJ32$Q0c3G5Tfmi`vN$^L006_DUo9~M}Q{)Me*FWib-4 zGW}cUpE(Qy@S^_e{oS?bmLhr9X8}Ogh^LE&YNsHS2C%2!@SWA0oNOFBDa^k#`tuVl zE06YPKo|b}nE%>qbko8gky9*SiZ+@h7^3GBq?c&Ba3L%q; zz+Z1CcMqNvP641dsJTGwKiE*nNUbwi@MRYbZCm5%^+(R@l|llKfihb^{BnA1381)R z&z}+j6J=~!sZM`Yx$TXt`-xGX4|XMD)#ey79Y`^%$F2aZ&ZivJ{00DnAkPyc~+5_O@P!(OR7a)OVNZ*gLNf5UAD)%nbU!_CQ!wCEU@I zjs&F90;U9QP|-kC5@<<7$>J|Ff!c{QBf@ijlNU(snnnZddTIC`6z00U3Lt*nB~MUq z#E~!p5BAun?gJJI$R_TObiB=T!#@7g)&Gt*&il`3|AiI*2LgjEUL37eD^M7|{0PKA z2ONM-T?RV!Jm5bQ0|JH#WJu@#!DB#^c+0oaQY z%P9{fB0 z-t>>RnlCGr{1MW0H*Kt-<{H3hkPc)Z09NWK4Z_dU3O9guiT9LI$@ zQzKA*)&EtSqrvz7+t8Mca6GJPR^udXc(NIS9_Ht-cnU)z<*I>1eR06G@$X8C1S&}Y zV>tegT?5S5nSae6pa?N-0xcwHBj%bphyrlb4Zso)2cG^T5nv*()Bc#B*8waQMj-kq zx=pjrwhzgxu{5EZbR4rtl}&1s6YGUQCoF*d=oQo&Rga_RUF0~*TfsN1xS zw5W_r+PZ6k`AV422)hV>F9blE9z4Ih*+kh-zAu!6Muq2DL}(@D!0R9>-1i8sQs^$I z2^v^jK3;ldt)=6D1H;7K`bJ9E&NHMxre11Xo>)k3#P*igMu z=US!=@t+21U4k*x`TlF{gzOPw4L1RIO$;IgO0WB~f=f+5+cK8Dk?`)f3lHfkeji^~Flv-Van03dJAvMXt*b@GRVZWBjg{6?#XPyLg|P9NrS)5t4h;CwfgJ52ebdM1qpe+*%U5oer-!@%l)RQf?QZh~*L=`* z3ib6BU*r`vh`YYl=7<9UCl7o}cZ%o&0;QvN1QBdJq*d}<*Mibn)awn2pCRifO7C(V zPdC3I=O7!#A#eG?YUh@er+gyWyADvUKgv9oIpWnnc_NY4xaBHSEs9b$H|4{6wZr$= zklL;Slox+}k}cF}+V>Q?%ia{N1*{3j)woPGz>Q(m6moz~lku>60Nd#&<%;)3ukN%} z6kkr-IiwInlh6#Hcj$?eB%OawjIcuH;MBZb!35*Jb7$dQ)MepsU%Lk3xjpOAcBUN? z>o=OL>tUn7g)q%0fc2x3d&k*&cYnSojo%|vw)&k-k$GO+#s+N{2m}05AOm{a-;EnM zk=E7+k6``4FVe&R&+g+5xLQ2l@!o-l!~4#4jZDUDFnSSyKHj395((NOsL~ zYqP*!h4|x`0a`1Lc(p}GIV6AT*GnN`azcfr+CcY zY5*pFbo^souR&}loXg=!)5)aC#$ZZ58DHykAqZ~&PJ=YrAb{i}?`8+Vk~=)ssmcB& z=55FX+(YaRRboAFK|a`N`TMP=7)?&_{8ooMQZeZ3VJp?TZIeLmfVb^1J!jm$%hBQ) zlC8TEuC^5Hj(}Bln?%V`AX$Dq^{~)4R0IjT`3;gJb53u5Ynkw|V9PZ>#igiXU$bwj z8e0*P1{+1Z?^t*4fOgpFDbMRe?A|9v9Mf1*el>KJoCw!!K#o&Wen(_h^;F|)gRC+| zy&8-0;KuiOHz80tfcMI+Khgn%eDd*SCle5vOzSx9!XwO@@KxsQW;K@|*7wXR)OJvZ zn>mpz-UJJR&ucZKb8sDPPJB~8NfNDrTWQ$Id<+N1Pm06+d*kC{lUk_kU@o-%gBu8a zi3GX3_)lLIZZx^0o(5az+A45G5&Sgy28GY;uNGUg5c3M=zP;OR4|#LPxx6>?F9GzB z1Cm_(x9Caw#G&9*^aKa3H>96V%^^QirQM2Jvj%{KdAqTaD4} zjrolU{~b-^>%zJA_(|_jONo2xCTClI!HpmD8HZ>4AuVJM-+Q_YUe1NF{Dcck=-l|F z)r7j?w%ks-9qJaS3>if+{C$%!Rx2v;g=K0)LSU|}qLjX6uJ?oi+eNzryNoC}Y6KFP z;f}|O7h#Aff;%|8IlOxL*Kn*=Nt)F&`zCSICJ6RI(sHE3vn<5iQpgl9$-zG>xDKe_ zRLVuwu3Gtt0WX_%lwtod*YL84zXWQcG}A5!_kWSw9wBI2kJ}*5QqcLeLEUxPQ5JnQoAtSca$3m;8 z!XKPxuMpyhLVIE2oZHvE`-5=<6`6rrE5Vr^%7_ed)#=##ucddF;&i0Yj@8?x@2W?2 zAt(yGp?FRK>-`x8aMN81!|@+PcIzu(`;+x%&I%b402t;Mz!@(-o&6L%u$iS< zi_%F8JTsDGBWx|&(SV%s5OOc-8N}&Khv8y}RZJhrovTc=dLvOkQ!(k>7=Cv$E{`hu z3&vf`m%v$DF5%7a7s{2UQ?*cj$9pa1CED(gQ`Pp z{S>18J}$9_D5L$10*4@71{jy{9;?_MgQuDLeJSrxLyK2!%I5Q^9hqiEe2TX(<7v;nJ4wz`aFU35*IP*^R!R>lm`7a`ClUJC3@^oiUdQ8^W-dZs2*sT(PpVP!%8|I; zn1p2Q5=`WMD3YmkN$RHmH!4#MLmo!tX3xFYO*21b71x2ySX^&KrcU5QV=-rhB(*{k zIU!5!k)2oQ3)gz8^w2tP1i03NUX4%vHgCh4eX

$gv`ZJm7}Upl>Tcq8yL22RTG4b78g$=Q3%VpDcrOQ@2&rhH!L?V^aIg zAA{8$`4lw`RPiU;UQ6`R=}l^=36oPZX(jEZNGl8bIp{iyza0- ztux5BzN{MsEjRVFP%WLZk|h>*>2NP&hgn^t@KzNyTpkUJQt@@oc9HEyx34Q% zEzEdDO*fC#H_{{LO;+XT^92ery2ZU3xm_;j%FNl+FW*|6;L1vJf9_n5-E}F?aO~-} zn$cfQPD+bXLEzn_G*xomas3%)w0N%S>cP#@kkQ25CvX_ZsQ12H^JRQ%S-ZGj?h>QXE>u0`vt`Eqj%3w7@ z38Ws_I3QQM2J?1fCIfzM{el8mr5q#NJ z`@>aY&(&l^KapQa+>ToUiOcs=;Cg=3GBdRMy6WrXha@Pr@wff&P8=P?5i9R(r2wfI zNBwx`Ja^*8w*A!BymcbVv@bc2U`Z-u@RYgCRb=OV;12dud|Kx`u~1Qf3VMqEIvUxI zCH!r9kYRo)?eE|baF%;!T5tkd-B^gc2oHJ3bE=tf#Ov#O&$f+%O}0w9Y1An0JlSZHmPh52d|nR_{*-R*M#V_>g{vz$ zuv=B*=O+2j>5m^z+}h`AWys4g+-P_jJOEsk37Q-6(>=84D?Cgyc3ft^SO<9Ql6>{TU%2G}6sXAkrIXtUwB8Ks0vFZG3^zApniq%a;0gWm0 z3p!$sY8CQ zz_iRPdnE*V3(LZP%2vT{tEytl0}(9rX{9+4rp2J$#>}ppK>mIx%}Z-Byk|< zNt!R4DCYKa_jDQ&-0dG%7T(SF2E4!5ZtapsR>ibyjD9gi&k=d3;K8lZE;6snJN!W2 z%NA?-Or-_sHShgezr(P{{Z8#5**h@x6mwb!s36dN`TF7utsA~Wc}{ue-8(Hc?4a(%X^&^^yD1v04Mh-czWib)aZBV@(Tv{55wVw@ z7e6Fo+Wf)vx^yMMFD9=2K2UPZx^?hZ;3k~t%X_tT$9`++mDJ~ur9}irvfH3&+2c-LqdZ=@i?kSTAgUGrR(zJ zIcZFza+D+%5(9?y%w6USkPs=FF*+$wzn9h_HH7SG4nTAjEGxM-SrpAT$4TB26m8^Y z+TIAl_?1g(It7mUb@4Y?27cm$+!nkgHs`H?JvpIZk1XJ-WhILk#i5y^+5ZzD>#Z^sJW5q#;^5)-H@6o)L^{M`f1P2t6Z>IlxhTc0qxSU669Fdu-j8 zGfVa>c~q*|WO92(VBa@&CHfdaz$tpd0z)<>bD;{C59^Df??Q9r(6wsxvPMB?qCD~ z=I}M&4ap49(;KNjgS9+M3#>U`T`qLv}XK>lD8)shcL(*u08VR_DnK(;@^BeZC)@s<0o z?ozFs-huTpP{$q!S;eS1P+>LgH{4hp#J0jPVdR5(Ym zP?`4cwQdI0PA+z8=oXoPQE4xa+StwB=VB5+Qod`N3`QY^Ui7PdQJr6tq$QTM z_MfgIM;0SOfXe}A2x60%Fv(bEXk*Rc?YF^Pxn!sJS##%i6h&RPhl}QKPGcuRrm*6n z5w#_uRbYUW3UOEXhV z{qOlPnJ&FZAW#G-MO>6YFpxNp7;`~bl#vw z={n=G^_S|BG;l$ML_SdTnx*z>y|zwxcy=WN40OTfoSqE_&XA8EZIhRF zRkh%~bOV|tw)w_rLHo;;hW+dr{TU#e^Kr_y?c}x^CM&#NNstcFG6zmQI5q{`VVKJC z89w-6$3m^EhwQtxboqF@>XMddQ<^kf;r-i(3~p-e1stRcW?H3Fk&UPT`nzijjVy8| zQ`;%Dc{F*?TRZV?^Xm1PZt0wNRDAhW!}0!ju(R`XtHTE;3;Z(eQdozZj9}*aV~9Ga zJdt{FqeftsJl0-am+#Uo6zc)p;@o$ZkheRr_56v4MPDBa;e`9`dyv-Fy$dh)y9X!b zzi+5x??TNz_DElkxt8UxHSbtSO!=kqdi!B0A_Nkb-1FkDuLFwY$TFZiprXIOCG_9$ zyp%H$X%ZC?FPHw9gpGV>4^wE-l{TQ7;UJJMn=;f@zNCvfSI?-%FuZ^;$;riDyf^Rc z&18npxYwK%c-K8pe;yXQHN*l_vI`veIvJgm`uAG7q7PI^*3B>QsXHdr@tSZ?>Y*L` z0~L>>k4g#MN?{TSM10G;rqG_JN#bJ>ab-ujd_An`#9VAK8@bOimkl*$^jZ8 z_>4DLM4NQMx4q(^#@xtR;$xp>I@9Gqfw?ii_{n6e;9iAtftd>hY;FZSl#aE5OB!!b5o|EpG) zQ^M&nsYCz=*9xq6M=42LAwNv%C|#VejF!WoH`O{9#t|^9-|3PAA2;gMIw5OGfs*r9 z)oO?u1ZL=c>dzbpe3Xs=W=y$qXX+AO;EL_V7&*P@$L6db4o~zAAbvR`e>~# zdG;!VzEDze3S3`+i8PRS8tg5B%-$Py>V+rH-3)lLol;eNQ&UA)NjRrL#MT$4JP${> zuiiHgC!WSA-wr92%u0d=CFE;o6UoVc8Xq|Ju9Ke>T%Dtkr2%Nw?|P zb?Bn$t3qiEq6<}9scu9qvA0u+P(mfPZgk#SIxV6iDXLPfQbl45S}iJ;R)(lZ!XPPW zY6&8e@IEmg=AU@)Z_o4lJ?GpX?)#kUoO3SDocuTcLi-YBoK%l#Cl0|LrtnSUda20;%W53ri>pWE;Fv#mVu0jEy$g z8qN|<=gQw^?(NT}-Xvod-z(fu3i`nNfY2eTmcj))g1ya=L5I!=8)RmWMu=6`w;$4d+EYPq;jur>Js);yX*qH%115| z$_V~xn0$9X&zI&e!H}KWSJG6jiY$)7`{+cSqq!cK$TfwyR)?-4FFmhgjeVl@lSi?O z4(C2_e7L`0sM1+&pW?swgpA|l|_2VZ%yk&{{()CU_J>)ZUDNmQ^r~`{2Iarm9 ztTbILUhST(6yGKuvM>5OMdh#&bF3&qYnwA+pM971%R&8o#U3O7%2Afe1)r1D)6lzz|Bvtg9jy}J$!+G`A>wknkbWZwP6S%V1BhfIze7Xtmt`u>8>D!iMb-2bjx<}*XdiJ48Dol9|1RHh zW+ft-d0cr0e>2cguWxRc6>BM_WUfPuD?87Y;-gg7)Qi!vW}M zH4e4CXMna01S5*qqNe*h%v?rR{2WczagBo$wcY2_y>%cqEAx*rSZ{6(P>Rc}XeOf9 z6M&b9=E)2G{$V%zjBH_6g!Wrr@@Tf0 z^v-3&L@`1XmoPc;yS+4Zu8;kCtSpAEpFj$wCb3~G>hB#Z82U;<`}W>v3|R9$oVn0G zKBuFWr6=kV45FmuDvw$s(;+Qem^4KZPxKjwdd0hc@8v6uYs?-=( z|4&bpMI+!)t;(QPO#aasZYmZ61#i-Yhowui+r=A)UOEdN+IQTNfO2|PKZ&*pt&u<- z$;4q_iR>SSLhE$58rbrbuS|#b^S;>!7jVZ*BhjLxq|&{+I2~^ev1Kg%Y}Sgf$&vw+ z$zCoErAuNl_6$VJkF_u3b9i`5o}>1f6|<+b^gk?35xXhih45p&IyAV!7h>VH;{rt* z^@c1gs}cVC-oxNqPw!O)hZ=yZEy{LX@AxiIIjb;Sj)FA(*}&RStuC29@)a^{`i9Vv zsBiTqi8g1jg=pC*;&uxDyi=El$X_G-k{{y{XlbtipT@w8qxGm~6dWC;01QY4yai`? zhG^ji>78tR^eMJMMOSqHZIW4*-hm0-?^`u7X}q1(NUH7Dj)Wo+{C|!K(^Z!)KL1#9w(H8K@udeKPBIL^#+shA&WgPKFAuP zjurlX;kO~qBU=2AF{iJ`rDlC(J*s)rVFP$##Uw?83m@IXS~XphLLZJ)c*TeDCIAf( zXC$LQ7%om;zzR8!NMhHSk1l0N==>|w3zkCRn&f8bF1jvI!AW;zL}1$~ZBU^gkhB&? z;=*x#^K+F3NjjO1ENv|KlG+1|-gjHr;uFQat#gS6y1&B+s+WS2*mc^5yr{J7V7o3A zO-2mOv`n&MSIBui@!BMY<(>8CjoDS3xKODhwGy>OA}O(dejHSoIg z;f%_v=YN?K9^tyFK2EhO%YzO8k%e6^+|w%vuAQvVS>+Z@soZqm47Mb6KleUCHk_D; zaIdk-^mBgj-#2xZPrsf2s`uaqT^=wxvOwLpmkDR~5a`cJ;=eb&w*3#idn_F77ks=b zLkPv7UAPtDvV!S|8sYUAAiJ;BIsm@ac}*oJ?dru_F5Q(nUUp=ET9MB!ey6~Tk2nU- zb7`Y&828AcM2rkAf9_VBo1b+(8Ydmz709K-+zxFBL+d}6tNkFq1=-L7?R7jeIZ1x} zFKXhTZb-DYEzbZVC~BHc=JXnrlrQqS6k2iuuI)a241sGx z;k;sl@-5`O%kKVZy!-OFA3+2j5|LeX6$_PfN@>Bi<|W;I``KF$*-UC?Q9e@Cn)icK z$)Uo93U!I+%y76UaOf2UKUo?VsgIw;l%d2wKULtuln3*^KvJasNbHLaZ=?6c2NyjB z6N@@|$vJq9QK*-oS0i5&P&U->7bhLIqjbDYMjNl zX)ZV{fqvIL-QGZ!eAn$O|GJyR4^_+P8@6ogXmI$ZCwK#%jE!0krr$&y*rBCfG(U?x zCtt}OcRTs`Hj$`NTtiP7NVR71oha`vK+Yn`?DVX~&hgX_3G}zc>8auIlB#k`1ft?? zqQTilIm`0y37OPYBh!Ickwg?fzb|x_7V2}q_^_+{&wy0H^!e?F>)o;?XE!I;lS69S zU=<_NwnL2hcMo7$S`O<*t(--A7=`Yn7*{$BJCp6xQnVx5sjjnx zNy$7j8EbQ_y+MeYD?_dMH26akVE$ND!SepP zFPNUL8zKTPjYMlWzi|Kn;NCz^Rb+u%Qs8f;a@VZ`B%m>D09qO=hE6G3wafGRMtQj=RRy`X136X|1 zrqE@+rR=5F^1kBl6Bs?8Gy_yXT^SW^^H_t8r3f^NCi$A4gOJ-ym2=OK%<$gzZ7C%G de<`^O*0ykkdoqtjBiEg~vxEET3cG;Y{{!ZlWkUb} diff --git a/docs/conf_common.py b/docs/conf_common.py index c7c26263d8..9d79a4f6e3 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -129,7 +129,8 @@ USB_DOCS = ['api-reference/peripherals/usb_device.rst', 'api-reference/peripherals/usb_host/usb_host_notes_index.rst', 'api-reference/peripherals/usb_host/usb_host_notes_usbh.rst', 'api-reference/peripherals/usb_host/usb_host_notes_enum.rst', - 'api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst'] + 'api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst', + 'api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst'] I80_LCD_DOCS = ['api-reference/peripherals/lcd/i80_lcd.rst'] RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst'] diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst index 27376a13f5..1012748d85 100644 --- a/docs/en/api-reference/peripherals/usb_host.rst +++ b/docs/en/api-reference/peripherals/usb_host.rst @@ -34,17 +34,23 @@ The Host Library has the following features: - Allows multiple class drivers to run simultaneously, i.e., multiple clients of the Host Library. - A single device can be used by multiple clients simultaneously, e.g., composite devices. - The Host Library itself and the underlying Host Stack does not internally instantiate any OS tasks. The number of tasks is entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is ``(the number of host class drivers running + 1)``. + - Allows single Hub support (If option :ref:`CONFIG_USB_HOST_HUBS_SUPPORTED` is enabled). + - Allows multiple Hubs support (If option :ref:`CONFIG_USB_HOST_HUB_MULTI_LEVEL` is enabled). Currently, the Host Library and the underlying Host Stack has the following limitations: .. list:: - - Only supports a single device, but the Host Library's API is designed for multiple device support. - Only supports Asynchronous transfers. - Only supports using one configuration. Changing to other configurations after enumeration is not supported yet. - Transfer timeouts are not supported yet. :esp32p4: - {IDF_TARGET_NAME} contains two USB-OTG peripherals USB 2.0 OTG High-Speed and USB 2.0 OTG Full-Speed. Only the High-Speed instance is supported now. - :esp32p4: - {IDF_TARGET_NAME} cannot enumerate Low-Speed devices yet. + - The External Hub Driver: Supports only devices with the same speed as upstream port speed (e.g., Low-speed device won't work through Full-speed external Hub). + - The External Hub Driver: Remote Wakeup feature is not supported (External Hubs are active, even if there are no devices inserted). + - The External Hub Driver: Doesn't handle error cases (overcurrent handling, errors during initialization etc. are not implemented yet). + - The External Hub Driver: No Interface selection. The Driver uses the first available Interface with Hub Class code (09h). + - The External Port Driver: No downstream port debounce mechanism (not implemented yet) + :esp32p4: - The External Hub Driver: No Transaction Translator layer (No FS/LS Devices support when a Hub is attached to HS Host). .. -------------------------------------------------- Architecture ----------------------------------------------------- @@ -97,7 +103,7 @@ Therefore, in addition to the client tasks, the Host Library also requires a tas Devices ^^^^^^^ -The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. By default during enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``. If option :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` is enabled, a different ``bConfigurationValue`` can be selected, see `Multiple configuration Support`_ for more details. +The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. By default during enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``. If option :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` is enabled, a different ``bConfigurationValue`` can be selected, see `Multiple Configuration Support`_ for more details. It is possible for two or more clients to simultaneously communicate with the same device as long as they are not communicating to the same interface. However, multiple clients can simultaneously communicate with the same device's default endpoint (i.e., EP0), which will result in their control transfers being serialized. @@ -166,8 +172,8 @@ Lifecycle The graph above illustrates the typical lifecycle of the Host Library with multiple clients and devices. Specifically, the example involves: -- two registered clients (Client 1 and Client 2). -- two connected devices (Device 1 and Device 2), where Client 1 communicates with Device 1 and Client 2 communicates with Device 2. +- Two registered clients (Client 1 and Client 2). +- Two connected devices (Device 1 and Device 2), where Client 1 communicates with Device 1 and Client 2 communicates with Device 2. With reference to the graph above, the typical lifecycle involves the following key stages. @@ -438,6 +444,44 @@ Configurable parameters of the USB host stack can be configured with multiple op * For reset recovery interval, refer to :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS`. * For ``SetAddress()`` recovery interval, refer to :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS`. +Downstream Port Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When external Hubs feature is supported, there are several parameters which could be configured for the external Hubs port. + +Each external Hub has a Hub Descriptor which describes the device characteristics. + +.. note:: + + For detailed information about Hub Descriptor, please refer to `USB 2.0 Specification `_ > Chapter 11.23.2.1 *Hub Descriptor*. + +Configurable parameters of the downstream port can be configured with multiple options via Menuconfig. + +* For custom value to stabilize the power after powering on the port (PwrOn2PwrGood value), refer to :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_MS`. +* For reset recovery interval, refer to :ref:`CONFIG_USB_HOST_EXT_PORT_RESET_RECOVERY_DELAY_MS`. + +.. note:: + + The specification claims, that for a hub with no power switches, PwrOn2PwrGood must be set to zero. Meanwhile, for some devices, this value could be increased to give extra time for device to power-up. To enable this feature, refer to :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_ENABLE`. + +Host Channels +""""""""""""" + +When external Hubs support feature is enabled (:ref:`CONFIG_USB_HOST_HUBS_SUPPORTED`), the amount of Host channels plays important role, as each downstream device requires vacant channel. + +To handle each attached device, different amount of channels are required. This amount does depend on the device class (EPs number). + +Supported amount of channels for {IDF_TARGET_NAME} is {OTG_NUM_HOST_CHAN}. + +.. note:: + + - One free channel is required to enumerate the device. + + - From 1 to N (when N - number of EPs) free channels are required to claim the interface. + + - When there are no more free Host channels available, the device could not be enumerated and its interface cannot be claimed. + + Multiple Configuration Support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst new file mode 100644 index 0000000000..1dc74d90e2 --- /dev/null +++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst @@ -0,0 +1,85 @@ +USB Host External Port Driver (Ext Port) +======================================== + +Introduction +------------ + +The External Port Driver (henceforth referred to as Ext Port Driver) isolates the handling process for downstream facing ports, which are provided by the Ext Hub Driver. + +.. note:: + + For more detailed information, please refer to `USB 2.0 Specification `_ > Chapter 11.5 **Downstream Facing Ports**. + +Requirements +------------ + +Host Stack Requirements +^^^^^^^^^^^^^^^^^^^^^^^ + +The Ext Port Driver takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): + +- The Ext Port Driver must not instantiate any tasks/threads +- The Ext Port Driver must be event driven, providing event callbacks and an event processing function +- The Ext Port Driver must use only API from underlying layer (The Ext Hub Driver) + +Implementation & Usage +---------------------- + +Host Stack Interaction +^^^^^^^^^^^^^^^^^^^^^^ + +The Ext Port Driver is a part of The Ext Hub Driver, so the interaction and hierarchical place in USB Host Stack is the same as for the Ext Hub Driver. The Ext Hub and the Ext Port Drivers were split into two Drivers to achieve the goal of logic distinguishing between external Hubs and Downstream Facing Ports handling. + +Ports handling +^^^^^^^^^^^^^^^ + +The Ext Port Driver can be installed via ``ext_port_install()`` call and uninstalled via ``ext_port_uninstall()`` call. + +After installation, the Ext Port Driver API could be requested via ``ext_port_get_driver()`` call. + +The Ext Port Driver API +----------------------- + +The Ext Port Driver provides an API, which could be split into three groups: object control, device control and general. + +The Ext Port Driver: Object Control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - Create object + - Delete object + +The Ext Port Driver: Port Control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - Reset + - Disable + - Recycle + - Activate + - Get Speed + - Get status + - Set status + - Gone + +The Ext Port Driver: General Purpose +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - Request processing + +Events & Processing +------------------- + +The Ext Port Driver is completely event driven and all event handling is done via the ``ext_port_process()`` function. The ``ext_port_driver_config_t.proc_req_cb`` callback provided on the Ext Port Driver installation will be called when processing is required. Typically, ``ext_port_process()`` will be called from the Hub Driver ``hub_process()`` processing function. + +The Ext Port Driver exposes the following events via ``ext_port_driver_config_t.event_cb``: + +- ``EXT_PORT_CONNECTED`` Downstream facing port has a device connection event +- ``EXT_PORT_RESET_COMPLETED`` Downstream facing port has a device and completed the port reset +- ``EXT_PORT_DISCONNECTED`` Downstream facing port has a device disconnection event + +The Ext Port Driver ports processing is based on the Hub class-specific request ``Get Port Status``. + +After successful completion of the class-specific request ``Get Port Status`` and setting the new port status, the Ext Port Driver continues the port handling while it is required by ports' state and status. + +.. note:: + + For more detailed information, please refer to `USB 2.0 Specification `_ > Chapter 11.24.2.7 **Get Port Status** 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 738ac7a270..cac7338ece 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 @@ -24,6 +24,7 @@ This document is split into the following sections: usb_host_notes_usbh usb_host_notes_enum usb_host_notes_ext_hub + usb_host_notes_ext_port Todo: @@ -40,21 +41,3 @@ Introduction The ESP-IDF USB Host Stack allows the {IDF_TARGET_NAME} to operate as a USB Host. Operating as a USB Host allows the {IDF_TARGET_NAME} to communicate with a wide range of USB devices. However, most USB Host Stack implementations do not run on embedded hardware (i.e., runs on PCs and smartphones), thus have comparatively more resources (i.e., memory and CPU speed). The implementation of the ESP-IDF USB Host Stack (henceforth referred to as the Host Stack) takes into account the embedded nature of the {IDF_TARGET_NAME} which is reflected in various aspects of the Host Stack's design. - -Features & Limitations -^^^^^^^^^^^^^^^^^^^^^^ - -**The Host Stack currently supports the following notable features:** - -.. only:: esp32p4 - - - Supports HS (High Speed) - -- Supports FS (Full Speed) and LS (Low Speed) devices -- Supports all transfer types (Control, Bulk, Isochronous, and Interrupt) -- Automatically enumerates connected devices -- Allows multiple class drivers (i.e., Clients of the USB Host Library) to run simultaneously and share the same device (i.e., composite devices) - -**The Host Stack currently has the following notable limitations:** - -- No Hub support (currently only supports a single device) diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst index 7fb9a74b44..5a36b9bb08 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host.rst @@ -18,7 +18,7 @@ USB 主机库(以下简称主机库)是 USB 主机栈的最底层,提供 然而,由于以下的某些原因(但不仅限于此),有时你可能需要直接使用主机库: - 需要实现自定义主机 Class 驱动程序 -- 需要更低级别的抽象 +- 需要更低级别的 USB 主机 API 特性和限制 ^^^^^^^^^^^^^^^^^^^^^^ @@ -34,17 +34,23 @@ USB 主机库(以下简称主机库)是 USB 主机栈的最底层,提供 - 支持多个 Class 驱动程序同时运行,即主机的多个客户端同时运行。 - 单个设备可以由多个客户端同时使用,如复合设备。 - 主机库及其底层主机栈不会在内部自动创建操作系统任务,任务数量完全由主机库接口的使用方式决定。一般来说,任务数量为 ``(运行中的主机 Class 驱动程序数量 + 1)``。 + - 支持单个 Hub(启用选项 :ref:`CONFIG_USB_HOST_HUBS_SUPPORTED`)。 + - 支持多个 Hub(启用选项 :ref:`CONFIG_USB_HOST_HUB_MULTI_LEVEL`)。 目前,主机库及其底层主机栈存在以下限制: .. list:: - - 仅支持单个设备,而主机库的 API 支持多设备。 - 仅支持异步传输。 - 仅支持使用发现的首个配置,尚不支持变更为其他配置。 - 尚不支持传输超时。 :esp32p4: - {IDF_TARGET_NAME} 包含两个 USB-OTG 外设:USB 2.0 OTG 高速和 USB 2.0 OTG 全速。目前仅支持高速实例。 - :esp32p4: - {IDF_TARGET_NAME} 目前无法枚举低速设备。 + - 外部 Hub 驱动:仅支持与上游端口速率相同的设备。(例如,低速设备无法通过全速外部 Hub 工作。) + - 外部 Hub 驱动:不支持远程唤醒功能(即使没有设备插入,外部 Hub 也处于工作状态)。 + - 外部 Hub 驱动:不处理错误用例(尚未实现过流处理、初始化错误等功能)。 + - 外部 Hub 驱动:不支持接口选择。驱动程序使用具有 Hub 类代码 (09h) 的第一个可用接口。 + - 外部端口驱动:无下游端口去抖动机制(尚未实现)。 + :esp32p4: - 外部 Hub 驱动:无事务转换层(当 Hub 连接到高速主机时,不支持全速/低速设备)。 .. -------------------------------------------------- Architecture ----------------------------------------------------- @@ -97,7 +103,7 @@ USB 主机库(以下简称主机库)是 USB 主机栈的最底层,提供 设备 ^^^^^^^ -主机库隔离了客户端与设备处理的细节,包括连接、内存分配和枚举等,客户端只需提供已连接且已枚举的设备列表供选择。默认情况下,在枚举过程中,每个设备都会自动配置为使用找到的第一个配置,即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备,通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。启用选项 :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 后,可以选择不同的 ``bConfigurationValue``。获取更多详细信息,请参阅 `Multiple configuration Support_`。 +主机库隔离了客户端与设备处理的细节,包括连接、内存分配和枚举等,客户端只需提供已连接且已枚举的设备列表供选择。默认情况下,在枚举过程中,每个设备都会自动配置为使用找到的第一个配置,即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备,通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。启用选项 :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 后,可以选择不同的 ``bConfigurationValue``。获取更多详细信息,请参阅 `多项配置支持`_。 只要不与相同接口通信,两个及以上的客户端可以同时与同一设备通信。然而,多个客户端同时与相同设备的默认端点(即 EP0)通信,将导致它们的控制传输序列化。 @@ -438,6 +444,44 @@ USB 设备可能是热插拔的,因此必须配置电源开关和设备连接 * :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS` 用于配置重置恢复时间。 * :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS` 用于配置 ``SetAddress()`` 恢复时间。 +下游端口配置 +^^^^^^^^^^^^ + +当支持外部 Hub 功能时,可以为外部 Hub 端口配置多个参数。 + +每个外部 Hub 都有一个 Hub 描述符,用于描述设备特性。 + +.. note:: + + 有关 Hub 描述符的详细信息,请参考 `USB 2.0 规范 `_ > 章节 11.23.2.1 *Hub Descriptor*。 + +可以通过 Menuconfig 配置下游端口的可配置参数。 + +* 对于在端口上电后稳定电源的自定义值(PwrOn2PwrGood 值),请参阅 :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_MS`。 +* 对于复位恢复间隔,请参阅 :ref:`CONFIG_USB_HOST_EXT_PORT_RESET_RECOVERY_DELAY_MS`。 + +.. note:: + + 规范规定,对于没有电源开关的 Hub,PwrOn2PwrGood 必须设置为零。同时,对于某些设备,可以增加此值以提供额外的上电时间。如需启用此功能,请参考 :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_ENABLE`。 + +主机通道 +""""""""""""" + +当启用外部 Hub 支持功能(:ref:`CONFIG_USB_HOST_HUBS_SUPPORTED`)时,主机通道的数量非常重要,因为每个下游设备都需要空闲通道。 + +每个连接的设备需要不同数量的通道,而所需通道数则取决于设备类别(EP 数量)。 + +对于 {IDF_TARGET_NAME},支持的通道数量为 {OTG_NUM_HOST_CHAN}。 + +.. note:: + + - 需要一个空闲通道来枚举设备。 + + - 需要 1 到 N(N 为 EP 数量)个空闲通道来占用接口。 + + - 如果所有的主机通道都已经被占用,则设备无法进行枚举,也无法获取接口。 + + 多项配置支持 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst new file mode 100644 index 0000000000..6833910aa4 --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst @@ -0,0 +1 @@ +.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst