From aaf635c81ef1480c82edf1826cdeb2c987cd4697 Mon Sep 17 00:00:00 2001 From: Manuel Fehlhammer Date: Mon, 15 Dec 2025 14:37:37 +0100 Subject: [PATCH] Draft someip-network-daemon architecture --- .../assets/basic_arch_overview.png | Bin 0 -> 76129 bytes .../assets/basic_arch_overview.svg | 1 + .../provide_service_to_network_sequence.puml | 56 ++++++ .../someip_network_daemon_design.md | 183 ++++++++++++++++++ 4 files changed, 240 insertions(+) create mode 100755 docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.png create mode 100755 docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.svg create mode 100644 docs/features/communication/some_ip_gateway/architecture/assets/provide_service_to_network_sequence.puml create mode 100644 docs/features/communication/some_ip_gateway/architecture/someip_network_daemon_design.md diff --git a/docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.png b/docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.png new file mode 100755 index 0000000000000000000000000000000000000000..afce4913faab82a79f5f033ba9d100244c39e531 GIT binary patch literal 76129 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
g^We)`Kmf5;qyDf@W`TVmhvpL5#sPxAabmOi z@Osg^b}@lK#|-R$?dW3DXcj;!(a86pYX2%*=MR@2-z=SF{>69Cj6`Y8k@Cxh7G=7} zdoI@@E-GzqR^h!d747!fu=~7ULRr*he^Vxr^GF{#YJt=9o(g%kA$i3I?;hxD;Ivca z70Ht6YwchFgsZC8aMI+EH?g^F+s!MUDMIhf@;8%Ny6;rz;rH};qVHvX(w(y|nX9Rn zxqj1LQ2Rw}OGn+gf)SK|hEl6#W-OkrvUGf?f#szaXS;h|9PlA6JiPKzV4`60HunP@ zBmOsPA2U1wZi18ky_?v9uAL5r|HY(yIgOkHPZ~P4P6mzO`!!0!U2Uu8_WRH3^F{_IjJ=w|Wp}49t_*U0 zgL;gSThS-{+vA*NOzf*J@@vkPmfXAj*CfMzk8Ex^-2}_K8l>Ay452WwSR#lg;9^am zmb=BJQrm<6G&v7#9bnr>V?=7Jw_T6vZBcPQOz+GoGGr%PmxtBkvwGSqbbP;p@Q;|W zaXWj+8qt%uN4FaVX zIc`6B)C~I`70tw>Tbb7Vj{28ME+4H;xO&*nqIYo?zvsuwg<{SEV{!seU9qd}s#$!1 z8Bi=g>R)fSALxGJkT+3R`(M~jeeS|oPpYFidRuWF#5eJ6DBTWieCmZhVXx!4eUekBvTe@oD1 zg13a+(;4s4pD^-@ZE*gy<2#FtaI=WKgN5IevU(q?q^s~#0zFIfN>FX@g56?lUsGwz zSI%oywJ{Fe3rB7Jocpqm1ywb-vR!!BilKA-@UIg46d}D!@Llj=Q@n|Z#-6J&x4pnz z3CDtmO}%69ab=~K?E8FCOgq%k!@rE<;&?)ZLpL(CKYy_Om7dR?>Mo$3*1EY9-rI*A zM?yd-b$2kTeDgED%1!#ivYoRgH`?rGX#d?BvJY16?VY3jKJ}<{9$f1!@fL3|^KoCy zuLYHUX7QG)UcIk|78erRgRW+ax(&3oVr#nFO{$y}DpK3hKpu2SzO!^HazW%)j@V|o zzVFd2SM43MZ7hfPu`A)6|LWgW8C&07K6KUcUE&bJ)@2^q#9C*NQ;_$)Qf|14X`;!z z&$ALnAIRcbnO>i@Og-urciFulPFwU?({eQ&V0so9BB7QTHR(*(BYacatp*S6w6(vj zI;_0N;_&Wo1im%DE$;1zEwUk@dCcz)e%8f1pe(;-stV1%!s@hda<0wPTcTX}Y0L%@ zJIHX7#ggr$E@jPxM&$M``u#z>c2Wk0x7ZFopyoNWg_F|OYcYs?^V=+XZ$rgL_%>Uw zCLR0N4YdHagF#Nh{y~>F6e<`*4k<-w9g^8lr@GDdl>a|quGP=}L(Tul=4v_Z|Mx1y zTbIptaElI0uJ$qJ0b>S{dt&r$PoC3F@4L zD3u34QHgiho+>(F1ddKu1hyvrA6kz|78Pup9Y`YFO8v*4kEss$S(77Ip(_*eIc8^W$@b-M*fD1RYgcfji--&9j9k7zHj9Lwjn^KH;FT3aqN0 zUW?J}999F#QRz2?0%Oi=hkq6Vp>f9*N+N!lyB)ZofqYPn;}DN6lIvGC3t#R_!SE8& zo{g7*r2@ANY?x5%G$$OxE_LNQQhTV5H^PuM(P^Cq%A2rMmJx-O3>zVtc$=Z2GaI&5 z&vL=iY00z>ySRl=@N8TF6w&fS>O_bOA9BgoEVt$p$Nh$CC!#S_t!0`VMM~+^geU_) z=Du&^Wde8XVf&lsBzN2lBCZ%P55)Ql7wy)NKaB6zfZ6p#ST(^`DpJ^#aY?RQis;MD zusUiRI2Q|yl763aX*he|Ra?mzk^_2WfiI;T21{dO0z?xC-u-QTPr zw_(;V{he2<2@dDY0$BZ=FebwOKBrF~3?vrQfrKkD9Q1zNErz?y`pWfRJMgxd%PFUw zWSOTehoQGvX4+prPAU081|=0vZ6e{el`v<&&9i!Xl&t;P+ds=UlY>AkT=>~>bi@`d z=$wIDycHRZJ}@xM^U;~d_VEfnHtZdPy>v@W&Ud1d;Fb~cvXqQFhTGxV>&%s5%&(Fz zu+Y`r*2~NAur}|lmw^FW(?!oLx0wYKqRt6dc{6hX6PK_LdQ8f*)(Q1934kw6?7)+)=NT^q83pMuqg+rxC8c494iidu* ztRDU@p8+CAt|CCdk z{PY~}rDp^o4Jn_zsEB22#`#b0Uct?c4$j6>D?P>Ens+Tr3Qe{B^g`S#@P0z-HtrF- z8s-iOmc{o{U%$sa4U}iN+10O^`%W!$r0hVh$tdzr#%*)zmv^zP>GeDJ6?4TJzf|hq ziZC5Z`7T&CrEhc<@ICu*^NIZ|VU5EFnd_08w!?Uym;C`-ur*KffLLI%K*qvDk3G2Q zH%Ye~_LR;r#lN-5ZT?n+N0!?z;}x{Uy%WuSafP?` zr|(n9S93@Us!S04we55NqpC{PXyl6|J{5^%`W5xjDW}N+0ewRP#>U1YRtlvJk0OGtuFi7uTtF$L3Ppkb&pi zRq7Mn-*A#$F+CN70`i}G@>46}`;P`wn&#UFZo_4cb6=}JF>?5B=o_92cyU0+Pd@EC zQqDBX4a~0-hk17J899CvX<~JJ;gZ5y@OU(Lq`Bt94jN@0C*j&+3x^#05_CVCk9~fr z1dVYDDE()G+iRh1*Jo+zq$jR zrlUQ%=yVRT7~>{CKfEJoqbrN(+K(@DFNxcEioeU1&R{k@PH#?G&Ls?u+LJE%xlmBi zPWeSbYJAtB{?@!==SPnDUTHEKSPS~Vd9T*PvoW4?Tb>@vYZG>9DHBYzN~TTU>=q2h zR=M1HMDc_^_5P!Q8|a`~Cuk%dr9Pc{Sft6J=Sa%F&DXW|J#OaFbPdSm{N;FHRDU*} zXWRMwyd9?o3`3-xYL&O`o@L6>4G!MkEW7kscVowLT|SjK`7hbiV zj;NbnO>-YBO@pSkln0B;Rj6gYRIXoS9xM0|WKrH4;7gw zT}uD7{qw^hW5LDVE*kt7B_rm^Twe34n(tyYNar%%EXf@Df)xkE;Tp~gmBPiCM;>l@ z-@8J!%@x!~ko}+X_Df5*JqffE;x*zMyAkcCVUP6uVyZ19Q=3B{Pdn{5vAv)hrRJ2+ z{*pcCgTTrHFm1!kFDb(qj?O*5@UG4yg`-@Td}>46_-2Bl1Z^1Zxk~it+dUGIQaYE# z&HQ!x&9UQN`(p0#x!@6I%Pf`1$NcWqvk~abEBV+qNd+&TP4*+sW7Wneg$h0v_xzxl z=~BLT`U!NFnF=u+6j5gRp)q^!vHopiH<|Lj0Uvd{m_0@g{w`qOCv8+}q$JYH*S_O? zMS4-5_dSK)_8V1nB^jp-?6<1*sNSKYyZmShXm`udY2lG5)45}%M>-rZt%oD*c7`il zPEckpH?xDSq;%K8rL3hcUty+&aMYpYnfY(QNr4DvS$`lBafRx%zjHln8e7}itOX)cW7X&1 zd`Os|_VxM)DqAb#YWar0J-Q;J)n!ucAawdCb&@m2*M}*V*}h|L`!dgv&*Gt?YF&Pn z@!6C=Rasu-+RsPiPNSU0v*=irxgqPP<$E-CKY6k& z7vSqT;H6|{iDXv7Nzwc{s?&Fsf(OqKDpHxxUTbs7q+6X+81xHaQ8f4_XOy8h8(Ych zSk<|Ix?USw0n0$jS7@=!GilLz`R}Gkmu{PkOFFw0VA4z93hhh7v2|Uya)}ZwA3*IJ zDma-`=Eg&Bx5UVNB|v}0%`#_aft6P|f{)K?6@8ygYHR}WJik?1(RbUtocYWToA7j) ze#vfhEjay%=1)yHdc=Oh-NNHT-UUTuGFwO&TjzDF?`%d{u9umOZ>AuY77KCJe0z;8 zOsBM8>J1x(%SHYUx7jsh7lJ%L1PLiimbuk<;fPZio(|fb zs-bAF8tO_0)7;|`k(EnB2Z33G^nA=#wxQ-;p@X|Bz-|A@0`{Sw*EIj6qUC0I_0rPu z&=5urj~607b@xuPDz5VP$rlgzsnX+(0~V~-LIZc&UQ7K@;E7gS(VlBh*6R9&Ku;*Z7S(qvGu4HX?#9n{oc`)!J*7Vc>UQ1s4+WTcU~20}ER|tZIA1 z`fp~7xub97#3ihncjmINh=#p_bmiwgoOC*7o?niIL!8R#DLoPPaF~CJ&r?gP-M-<9 zyUEjR0q(RZe-`)b9S{ZQn#*hn#5srZhukJJ>wc(@pbp_f&kGq9uq!OBwEu&IH>Y>z zxP3%7cemyT7ASmTHCfz`xL7Bex=pR?sD7GA>gY7e%iw=P}7=a=st=d~ME+S;5WHS90_HZArL0^z7RA zzuNoGu%@%EUlFA!RV*M)0l`9V0YVW_(V;oxC>9_f2r4Cn03i^Xbft)>)DRVgu>zvh z5UK>EONl^8fKUx21Of?!zzrjFjvUW@?uYx{d!P5*@k1VY{z=x_YpwlTZSR%qm`Am@ z67Lradw1*qv`Y|D$E((ftMf6MUw9K#XK?S7)$1%kTsIt;w+3D%2R25pB(V!|t&-gm^82$c& zh<>oUZ?zxAX4FsZ85s>$sjEC8Iie7JLFp$vp6?<~R>R@>I0Hm~F#cvzeg^Pp*HK$X zPo+K)_hSkL-L0e39l^?QD3Ig|st$iED3H`;+z6qB0Y2L#^JS|b3chAimnTP8!xS_ zxq~kKQ2&?21x)5kPVjo={l)t1~^P28^a505=#T-y9&Ommyb4CZ7b&Ll6}GAc$iJ}oA18|Yc6&4I}!hpB{KrRvO< zguC#o9iXkygRb?{@@+Vkq^&WlYt$LZq^puegmsNfRGL9s|Kv%@fnjo^CRha1EdqkI zS_fok;mq>@R1KH)>c&Dhuz#}tr|x~9o$c%zcil-m96IEDd9uG|3Cycgwt|wyL(+3& z*Njse*CroTS30ymVeCC;&E;X|yq_%R0H}JG8+mbIPa_>lPrb)ydtE-$fa@nH zNwGY}m%zMRy34#i?WmHLRGf~&7vylxg&Y7?KNt5DN03yvd=pcTYL}RZ2C=QRM3J(Y zxRy)j5b0I1SMv#1pCyK392AqC<;XcZgj2f2+>xx%Wg)#hR4&S);iKs8kseMS{V$R9 z+2*HvYqQ9AKcdLbRUcq#MeJfOo0|>M9+&n6FJwx%)1U{~LU=W1@?B|`^q|-z=6PF| zKi>Iedj4$HePdTfr!MV%EJJvBB*3BgJ(D?YY^XO`B13-}L<`EEc{4f1DL3UbWWD@1 z!1=(u6Cv$kwXV0iZnb`@^u`)&jIA#*_F2T^>>FTtuRVWloWrZt0y z7tO`Fg9j>}hcv&l{(7rJpEZ7;U>*`*e-$5%xLFyxWOCj`k|K3IG%m^=FUfdfH=nvQ zy$iN~WVXKT+(YhAmmf-fPnB66HJ+;iek-H!2^=jY*yfkUy*OdPHL-O6uyHr(xA=~J zmdV?Z(_IC`cOF`NWvio;t~q?7T_<^15@&x*yW$KR)>S}JgfRLokG$1@M?4ZU?uUL% zAP&tR;>D+M-^Cq@WD7k1F=;v_!>P{uo}?XgEks59xN+|^MN0Wt2px6gI6AHSKW086 z@cZ19CazB&_iICWe*3YACMRrr1c^RisPn)ijCcO3;v!xxlPc6~ax&rmF_hhr5{nfoTNj+RLzufyv0MH<>G2~~3^m@p1^@PoVPoN= zIzN9eul{h7)OqxOiM%#DuUkq)n|<5XAB*CDwNw9D_uOcrL>~R2EV$7$5&85(ZH&|E z75cFgu+eKV-TMQnjo!+SEtHKG4ezf%(A{Xs9J>2Mm1Om!_+|t72g3hR4VBHV_YZ6S zkMAM*T#)N+Bu5j9(B` znS%;39oFd=40lM3-P*E%TfrabV0Ej#~L zDVx(+@uB1{?)Xso9KGQVS*7Ah^7nUs-TKZf+3dSW8ZZoCPK>Y+I{Syq3Ho7m4*$Yi z`M>RQF>I~J#bjSdwe2Y?aG0*bxw&zKvrL06%e*bNa;iR*Z#5JZ$LYh>V+mCE@6z~} zx4D=sic}oJm`}0hM0us|(!Dxc4@DZ1fA9iAcm8O5%S{jp;LKSqUzk9NEgdg7DkA}h zlZ5r3NI&Fua_+k&`|1=|DVSsVG@ccd6av?l6;qfe2& z!Q)Jxb!>@DJ z{Oi^=njpDf}e13*z@!RPf8eDKq>o@Zy0F~(;?kS7_KtezmK@v^}hR7ekDeJ z1t>}YO2R?RJYVn~h0_TPKjkIC^ydq8aO@aILn>EI4&62US;l9XUgz&fo-&KQYwfdk zl))fga4oFq&>t@3yABLvR6o&JH6zbqq6`{z-BKl$FA1ef{7hTpo5@t!ugnuNAz)3- z+FHdVS%k#;t)15Zz+vLx8xu4NK|3=uKWl}P_6+p{aezazxH;N7&hsa3&hmFuh=!=j zy&p;Mig)4G9l9LnFBRO~%++ys`C2AUIAuT-DE2hb`3mmNGuEDOB7@@6K37G5P1*Ak zPscP=PrJsRcj;UM?zT5px`GmKd^4UNQOh+;d?Zf2-PV#Maywlz8RN+l=V=J3sa}o- zNTyyO%R71BH?8Yh(%dTS;Dm35+y9DI~w z`u*?K!1?{-s!qysK{;^uVXG}G;jnVJy%V;-CIW@Ep-f$zhV1qN$#i&rWhT8Dj82hc z>E@kzLeuB<(>?3DU1AKf)hcZg*2Fj$ddg5fXrjMh+Rnz9{RtVvemKS%tAwVVv__qj z<}e~xzU^x{>7S7DL0z|ZwwoX0*e)|MLnRGd2w$Jy|W_;ZQN!f{5>Z^|!tA*_rba{qa7}rH0-!!k1fN$K#paeQg1VAJGQ%ta2DE%@A;8UR@&NY}T z_f3V&wyb$9nwN07AiUbPbY%G%d#8F?G$XNHj7K*Pf#h}sJm$V@8~GCfwfa(1HLc?J zwl`xtx0y>alOQ#pOcI`L!q9H9$p)%`xNH$Z*_$S4aeJ2hj)N_~!~^UnA93I1 zz)$4;EuK1FqXf2G>!iD6;ov5DTfGpPkeQsADz==nkk>I=CO^@5p<;UUAkD7(P|0Cl z<=vW1rcGOLw>3M@86SE0(ASK_Prp0(_g#tEPR?t*ifQGtRxfb`IQ+Y1x;9p9vwCLY zCJ=Vy`a!vGVd|a&vP$t@WlJ9xD10f2wcBTr{5mu9oc-+8#MSb%!gUOx^PRNfH5WC{OY{0qXtGl1MQk*Y!p5uh2qP95Uvu!gjsS?_6e#JYP_$8(W zw2W;(i>D2Fl4eECkkv3&=9=KW8nyp9;an5#OKl+QFOg%&aVV*E*d5HWmlub_T?Ua- z=keh`Sq{LEp4xm{SG@d&a`4D0m-zz*!25 z>~gl%qS**#or(1WL3{9JiLTOFy?|-AV`<{ew|Et;XL1-lG z5^Mwzx<+Sv#;iVOA7!_w?`FqRm46H89CzNbmHy6k|I^M({+;Xocg}S;uMcc-Bb%2G zwz%5Awfwi1|09ok|83ZR8}{FZ{jc{M{x7?L+uh&Xwrx9h`rIkg-~Ye4X!2i+Jpb!X z)5c|=QyTxw&Hs1XU3`b5MEGmI53dq6<2$@3{QJFjxhN4cg>B!bWSru>>Fl=e6Q<%t z%=l8aeZR50hx1uEuFZj4oX?)xzBx^W^Vzr^n`4pwCh)h2{u~qbw-x=p(Z0{-`x`3$ zM$5LU0ZSooH(iqow_tr2@3}X``lnNTF zC!VbjIv#73S_@Htgw$8B{{9Tm00o4BeITvcy61dG%dMn#+OHJexbi3;#uygukji&C zCC4^qkMjr2%7(Zzu7wOM^U=gN2U7)rc!nslKU>R8d2(u8{{VVvJ@TfBZ4vwicMcCLTCiRbH}fevf=$!7R*s-3OX5{DBODaAtr^eyfR7bml-pQ18utQ z=7ynQnw>(=(_0i~LCXsWpuGa}_GV_>lwjAr&sF6saooo0D)XZkIWsLo-gS%4Md(|; z2R~-Suw!5)7NCc_X#AV*{R~B*aOC*nz04RpH|?aeHH)uo3XXJ1%4N)4aLi?mX9+Rq ztrg!wNMPTSs5GIYM?y{!v5SH199Rhsdbj}>`8~qWyuQ{lR}i-D;m)l0{i0mo@`3$F zoul@eXyt-IM(OmW!)^2nGF_6-;#pHip0b0k9;r<~u*a(JjHeGO;AF|9@W)6@8Hf}v zn^AI*?e`{@1gI+R@{MB3Z8FKzZs)YxJx3lZ;3eiP(OwjVbz(3!mq-+W@P~=h6Q_tU zVeht!xgcAu^4dJH21y1?@s|AK-TF_2D?LxJY-bsPliUmYbHOCviqJuzS z#ns8=N#g1A9S2;Dt8gu2>|-N~#ww9ZUKJ_tv$UU4t8GIrx|Ohla+(Fb?Jebo&D(8m zp7-oz8A=S>)v*!c+8zg*K3Jr&&WshNs!XZ3_l-P%W#-3fGYy{uoV=?8^0ZDddR(k2R>OAXVQ=@wkDDbU2%?Q z%^%J$!yb#(MvH(1Hbcu1y-IrrXb|Yc=CX5i;ohPLyTr>89Ie&kfLt+ zZY%G(@Y+hdawYWr+xkzE*Bb-sy#^E zm%(}gq!Q*=0aA{(f+50_GelOq49PZY|ES8QSqrF1`GmQwYg(+l;Nw!OXVztdFCgrG zTib`WHeym*8tm=;gKlOv3+CXHz3EXU6Km0^;K}f%0-2I{xAMcr-Dj@b8IC1eMwY77 z6NNmO*NuL+VbfptVw2$YvkNF@jYh0eeRmx-ERoDSP|NtW)yqhuJ?L1)hWx*zEj77fqpFO(Hm`|7k9g@3^UOa#hK=v>UHAG{ zi+vp(S_*k(q}?&bV=G<-PYpJ!>_Sd;Rzg#+G)R)#_}bH-8hM3tO@_9Y=$)AR9U1F_ zK~GTaT2hS^g_cT2OlT=Nqhorzld1mimK!|YC(j5EBeH#7bd(BS;@pIzQs6L(&>th; zhHnB0L5ILo5u*XntCtNBi|uDx_KaF?<~SNs)c#1EM=TwezZ^JTjxQ(Vx#TRrc>XG6 zyqY7y6$hE=(=PXnbld)9vj0_1;oIf&(n=XJxGd$&QVqT%MG{&cT7#4ut~4JsN#*VP zWq!ae?Y%6FVpqIN2436e&9p@{053|e)kRwPzwP%aHL@|K*2Aw;=1~+f+XxJE%O|?$ zz=UI%xS#G{D4>(ogY1l0;R&4nqcaV^0`k_8FB_o30J^M0WHAeE~1J zDgpxQrrPe|#g>3bvr6I1QwU7+@}UyYH8gwM4m;h{npRyuJh($k#Cr!|?3MHHu=Q>b z#=A8$;9=%N=t`*0C8?^Nl7lo9^Hc|a9+<`k7|WWJeZ5R=I@vPIYV8ejc{Uj-bt}In z0Q_WibQyywn`HM1xVh>nRt~KSWq?@iy5hsX#1(7~@@ep`@&tSi^*!4XSsIV~gb`Zu zGN4onZzHkBHh8x622bf+2sYB&&^N^b5M%~gD7tu0rck3>dlFjK2R}QmQ?J-BSZ7a* zykn&Iy0z$TBbs8&)>(#Bp73Ko#P;lswU_qsNqwbwH{VF!Rwypm)~OB4(^@Qwsx#7C3O?HYfxq4uS%|(h;L??N#W;To zt_7?=hH;_Me3sUc6GJZb4zyRg=5hl5bI(rF)Tf>g8g!e=R1wont0 zWq|J%Fv8awPiOn#@3sK5f7gAZ76XCuUh0b_DShS5bBku~`iC1n0Go{Ff3P@ejfZ@= z9hj9={!Vf}bTNEgcX3$ZqS~ClvoO!IN!x17+HUhRPvTs%ctb0(d+qC<7$}84%$gP1 zPHDRMm7q~uh$r>yKAyc?XCY=e5mmiY4C@-8Z}Z0pRl4?Anj*G}T$Bho7ho9+PXZ=& zql*icawt9aJoN189a2!tz*-`y+_&5`?i?%ninbU1=9?0JQhr0If3g7>s@^t<*QUeZz~FpMx=% za%Zvwp>**uU%mY^Pfs)^PMj-foJHe5Uz8D^lwB54!eYWY$9XZRuRe zhuCb-QF1u0_8M!2(4*C=XOv1ZChwB!v-d`v%Bu%bLeOXT*FF*fZO+kZPGBt%2o|P{ zw~2=Up;_sP2i$_fHjL6G8)qm!HS$snPzLo2Eik?C`HHrcUVM{{u>LL$uYRHKb`|(Y zXn{-IaQoi7pIWYMKMc;zGtw&=4j425SgO+%Dl=s+w`8;D0*bqNW2EIi*dWj<_6PeS z7)v@B_pdJ^_{$CSa>5yJ_BZKxWL|3ad=vTFy3Gh5(anSGV zxoQds1y1G|pi@G*1oOR5yLP}R4x?FakG*|u@;;XT*^G?LZ^=z- z>-8$Z7Vh(NN6#cFmf_Q7pT7{67Gu1I{K~Z^hH`$Y_?oxxqu$^t4ZHmhW`#I+rKMoi z?dt?gBLgj=PpbraLxX*Un{--`S<(l;flwWz6Z}h}V96+^)F#}^VDD*aO82XUX3coC zebq1C;I4J$?jj%{s`F7vYTaPVR6C3gZ%JCYxIPSL$ToP!~fhyla%XGgN z2G|y=g*j%4pm@J4RG~r3lvUMP5SpdheA&@wBfdx<-{*4hoq&N`f(0duBP^hZ(NLq@kc}L zTQKPI0-6yRN8o?#k00;4a0u606i^eDOzcNuR+Vh6;~1Oq4*b*VuXBcDpfz3O@p2cC z$cCic8N})3;^W#YHQHjPs72n${b$Esb-PU1eDHMJ{o!?SQuOppzdp2@u+W+YWR3e* zy=(r$OZ2ZHb@8OCa^jmjCH*$xRgYZv%;n3XcJg@S>qHr!$6_Y$Zh#1Q95biXgIf4z z*)a-b#N%u2@xe9ANMLYl@RUtXoSt_Cv7TJf82sja zPS#+(cCHllD4!#)G3{y^bp&u1){0oT&z&J@G_0(IU-$pcoSNH!)0Kr#F`)p@hUOPX zu7$YHejOY#G>s|SGfMtTXgsk2B*O{&>IK~ly9RjHo8yAuqz#8P|2UT3Uo}qQUa;Ds zw6;S2M7;|;$u0>0IuR zG{l$3tT!l0CB`gPGNiR+Q-DqQDK2+?+L{{cOMxua1JNO$c0%~^N6$dv;1&lTnS&~V zy>9ujF9`p_;b;FZ{8HdlSfjh%LIEd+{oFW5Spi=Veg}r1vYovCBzYsF15AxCQ0PX#W5rvxnQkQn8JTbn>TrV&fX z=0!5*kfrf0f($Q%`PDhUd>MPsvyf5!}r4rU}fL0bs z8{2ctcU;tH?{SnNpF4~{WE45%9LI5;LYwuINhu4q-gIn_51cncjhN?T!`TL$+r-jA zCGr<*Ir*eu(DJiwB-M8numqx0aNNE?&%o-g^7N1>YYIS{j4!CiR=i2yS;^{&T{Dn< zogb^pk(FM_-4^Mk++y~%==E>aeUEE$io3Z>@0WLRxBFu9xe1SC?%%qQ;eWdiwJ^c2 z*}!p>yqh>7NskQ1Y?E@e3sK6pTK6(Lp9k20iq15`qe|R6Ve9Xjd%c~mCst5_H9!%T z8o6SV7-}7#X6*2}YPD8{pxEsn-!Q#vL;e_AI)Bbq#E28rcR^zaYTTo-5_l$06{2e7*q6aiuY!x7SKyytyYUSe=+@uDwme}$&Q!jKp!wkG#vf+6 zZq#yLodvcH2`{pi3hLn&>2#YT$ro-w`SeStxE0fYK8tsA zW|WmSO#4qTML|yPr_CeS&tL(ZLyDpM{^A8~M_V=~>{9J0UFyAJOsE(MS>5CXkMU=H z{l3pAL$t5hl9Z?1#=WtZBRYx}PNeq0{C3m#(Qi&JHLK@ek(s6#FFwsd1h8E#*hd0;fS)crmdX=nak^H_@tOj{A#9upX zH{mtYRW&yA?ty}aVr!u$6XPmvL*g>pp>s}_Y$b1fcTy0^jl2?{e#YPhbdA zPk1e!yX&>AR8ePaWZ~NPM8KO??OU6X2zoPqUX~ia{+le5ik~Fr$snHPPYT$#(Q9x0 zY0-FMri*1#HQEjATdG0se0v||!t#oFF(dC~vNF^-Z?xC5ufnO1ya9^dh|k~1MvJJj z7fK11?ht!Hx+oBoT-Hp!HT@@M7qGr?+iqBo1B%zE{z@M;#2vQMlzSyAaQ7zg+#?O~ zEym;Oq=rbR%Y%_NL!^U$N`_nCiynOjFvvT}N#iByzG3d|M$X)^S@ipMQ%!HhDx8Sv zzD?5r*@zTd#fmK-pQA&m*EKbB3 zlrIxd{0{syAHSD1xTAUoIppLEL{?QSD>B z8}X0Zxx({Rm##~H3u?5l;vMRf7`ctT(sNE$vs>27V$fHFTH6T!BadW$|3qZ)wd>Al zy70tpmXM^PVl|_A9}p>6X4YrCjx)YZFFA+Rbg+63IaGEfQv|i?#~OTc5RBfrPh^T`E{AKnXJ+4?v5t8({SPeW&ZsU?e zo;cwBsW+}#TB&*-IW$$upsF`|Bj#&|VvX1>_1FW}f;-1T3Lma0Zw= zNbM!MP6nC-`oxTS=%B`GJJEhf4`oAu1jt_cYv!d8#MKuYu?dA=oF0W-R*XtCcKD(_ z?l`zkMM9WCyIRcR0NIK9vdcO|{a$S`2#gb*T=r4@`ZnBSNTa<^rUfGvQ{Pg(pQ;uz zHJ^RwB=+8HXJT>}Y(Pni%L7*Tel5r-3nzchut@{9{ zh8xJcQ;k?|Y^>6~;pT)DZr0B%BE+K6o9Tvlq2OoNw0+GDL)%A^z&IJsQEzs^*z!p~Tk; zJ4N<~tZ_0WU=UX?3ukQP9CTu61Ey_jY;2U~yhjbAr%X&ezdiI7&?h@7;KeQEs&@MD z!fu7!tYTh~UP7-(qz$uu!0AVZh# z253t@VSO(4u->f2L4OTtZen;d1iNw{8td}0s|_nDyZVvc$s?grvSe6lG)3^Hd;uO4 zfZSk)a~tC~ltF>)qbW?ILfw-;T68$X*=~B#Jw@vxQ|)5CTo)G5XB!GpgSKSR_HTM8v$%)oX0>c{ z3u1LBLH>}PUwR(&!68{hK{~sUYda!XmO=#oz;l|-K>5XB+8^=uy zHqIMt982?a;*56Y=RBLP;mo++!+G{4f-?tMf%EJ+_iHiE-<<#bKYU?wFPp4Su5%|0 X3^A7F+Ge(K{+&B*bLyR$)1ChTWdvEL literal 0 HcmV?d00001 diff --git a/docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.svg b/docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.svg new file mode 100755 index 00000000000..27fab09bc31 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/assets/basic_arch_overview.svg @@ -0,0 +1 @@ +SOME/IP Network Daemon(QM)vSomeIPDATA PathCONTROL PathSOME/IP Gateway | S-CORE AppNetwork DeamonAPIvSomeIPAdaption Layer \ No newline at end of file diff --git a/docs/features/communication/some_ip_gateway/architecture/assets/provide_service_to_network_sequence.puml b/docs/features/communication/some_ip_gateway/architecture/assets/provide_service_to_network_sequence.puml new file mode 100644 index 00000000000..8b42f8a591f --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/assets/provide_service_to_network_sequence.puml @@ -0,0 +1,56 @@ +@startuml sequence_provide_someip_service +title "Sequence Provide SOME/IP service" +hide footbox + +participant "UpperLayer" as UpperLayer +participant "NetworkDaemonAPI" as NetworkDaemonAPI +participant "vsomeip_v3::application" as Application + +activate UpperLayer +UpperLayer -> NetworkDaemonAPI : message CreateSomeIPService + +activate Runtime +activate ConfigParser + +opt user wants to specify non-default manifest path + Process -> Runtime : Initialize(int argc, char** argv) + activate Process + deactivate OS + + group config creation + note over Runtime, ConfigParser: sequence see below + end group + + Runtime --> Process : return: void +end opt + +Process -> Runtime : getInstance() + +opt config creation if singleton instance not yet created + Runtime -> Runtime : Initialize() //with default manifest path + Runtime -> ConfigParser : parse(path, const serviceTypeRegistry*) + create Configuration + ConfigParser -> Configuration : create() + + ConfigParser --> Runtime : return: Configuration + deactivate ConfigParser + + create RuntimeInstance + Runtime -> RuntimeInstance : create(configuration) +end opt + +Runtime --> Process : return: singleton instance +deactivate Runtime + +Process -> RuntimeInstance : resolve(InstanceSpecifier) +activate RuntimeInstance +RuntimeInstance -> Configuration : serviceInstances_.find(InstanceSpecifier) +activate Configuration +Configuration --> RuntimeInstance : return: Iter +deactivate Configuration + +RuntimeInstance --> Process : return: InstanceIdentifierContainer +deactivate RuntimeInstance +deactivate Process + +@enduml diff --git a/docs/features/communication/some_ip_gateway/architecture/someip_network_daemon_design.md b/docs/features/communication/some_ip_gateway/architecture/someip_network_daemon_design.md new file mode 100644 index 00000000000..b9d57aef6b3 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/someip_network_daemon_design.md @@ -0,0 +1,183 @@ +# SOME/IP Network Daemon Design Proposal + +## Intro + +Because of safety considerations we have a specific `SOME/IP network daemon`, which is responsible to handle the SOME/IP +related network communication. +It will be based on the open source SOME/IP implementation `vSomeIP`, which is provided [here](https://github.com/COVESA/vsomeip/blob/master/README.md). + +Within S-CORE architecture, there will be different upper layers, which all need to use this network daemon. Currently +under discussion: +- Generic SOME/IP Gateway Daemon +- OEM specific SOME/IP Gateway Daemon +- S-CORE application using `score::mw::com` with a specific SOME/IP binding + +The interfacing with the `SOME/IP network daemon` shall be identical for all upper layers. +In this proposal we define a common architecture, which should end up in re-usable building blocks/libs, which are then +used by all upper layers uniformly. + +## Basic Architecture + +There exist two "channels" between the `SOME/IP network daemon` and an upper layer using/relying on it: + +- a DATA channel +- a CONTROL channel + +we explicitly separate these two channels as we intend to implement them with different technical mechanisms. + +![Channels](./assets/basic_arch_overview.png) + +### DATA channel + +The DATA channel transports the (SOME/IP) service instance related data. This is: + +- Event payloads +- Field payloads +- Method payloads (in-arguments and return values) + +We intend to use shared-memory to implement the DATA channel. Mainly because payloads listed above might be large and +using shared-memory as exchange mechanism might save copies in certain cases, which helps with performance. +Additionally: Since there are already existing building blocks for shared-memory communication either in the more high +level form of the `score::mw::com` SHM/LoLa binding or in its underlying `lib/memory/shared`. + +Initially we plan implement this by DATA channel via creation of corresponding `score::mw::com` skeletons and proxies +with LoLa/SHM binding. This already provides us with the underlying shared-memory storage! +If we later discover, that using high-level proxy/skeleton abstraction isn't flexible enough (gives too many constraints), +we can refactor in a way to use `lib/memory/shared` directly to build a better tailored shared-memory DATA channel + +### CONTROL channel + +The CONTROL channel is used to notify events occurring at one layer to the adjacent layer (upper layer to lower layer +and vice versa). These events may be related to: + +- DATA updates (notification, that event/field/method data has been updated) +- service-discovery activities (initiating find/search, discovery results) +- subscription activities + +The CONTROL channel will be implemented based on `score::message_passing`, which is located [here](https://github.com/eclipse-score/communication/tree/main/score/message_passing). +`score::message_passing` provides: + +- unidirectional messaging from client to server +- unidirectional messaging with asynchronous reply from the server side +- synchronous RPC style communication. +- asynchronous notification back from server to client + +### `vSomeIP` interface + +The main interface being used from `vSomeIP` will be the class `application` +(see [here](https://github.com/COVESA/vsomeip/blob/master/interface/vsomeip/application.hpp)). Thus, the +`Network Daemon API` shown in the picture above, will essentially interface to class `vsomeip_v3::application`! + +For resource reasons, there will be only one instance of `vsomeip_v3::application` running within the +`SOME/IP network daemon`. + +### Usage of generic proxies and skeletons + +As described in [DATA channel](#data-channel), we will use off-the-shelf `score::mw::com` proxies/skeletons to realize +the DATA channel. Since we gain much more flexibility in these gateway biased use cases, when using loosely typed proxies +and skeletons, this proposal relies on `score::mw::com::GenericProxy` (already existing) and +`score::mw::com::GenericSkeleton` (to be developed) instances. + +### Service-Discovery usage + +From a functional perspective, we could do **without** usage of a service-discovery as the proxies/skeletons are solely +used in a one-to-one relation and the existing CONTROL channel implicitly informs about the existence of the +`score::mw::com::GenericSkeleton` providing the DATA channel. + +But since a lot of the proxy side functionality is deeply coupled with service-discovery functionality, bypassing it +seems to generate a lot of effort! Thus, we will use existing `OfferService` (skeleton) and `FindService` (proxy) +functionality. + +## Service instance forwarding to SOME/IP network daemon + +### SOME/IP service instance identification + +When interacting with SOME/IP network daemon (which encapsulates `vsomeip_v3::application`) we introduce the type +`SomeIpServiceInstanceId`, which consists of the tuple of: + +- service_t +- instance_t +- major_version_t +- minor_version_t + +which come from `vsomeip_v3::application`. + +### Steps taken to offer local service instance towards SOME/IP and forward data + +These are the steps, to forward a local service instance to the SOME/IP network daemon so that it gets provided as a +SOME/IP service instance on the network: + +1. The upper layer creates the DATA channel for the service instance by creating a corresponding + `score::mw::com::GenericSkeleton` with LoLa/SHM binding. + It might be sufficient, that each event/field contained in this skeleton has only one sample slot. This would implicitly + mean, that we will see a data-loss, when the upper layer wants to update an event/field, but the `SOME/IP network daemon` + is still busy/accessing the single slot. +2. Then the upper layer sends a message via `score::message_passing` to the `SOME/IP network daemon`, to create the + SOME/IP service instance. Thus, the message contains a tag/message-id `CreateServiceInstance`. Further payload of this + message: + - `SomeIpServiceInstanceId` describing the service instance + - LoLa service type and instance id, which allows the `SOME/IP network daemon` to create the corresponding proxy instance + to the skeleton created in (1). +3. The `SOME/IP network daemon` receives the message in (2) and creates the proxy from the information contained. I.e. it + issues a `score::mw::com::GenericProxy::FindService` and expects to get instantly a handle back, from which it then + creates the proxy instance. + Afterward, it is capable of accessing the event/field slots: The DATA channel is now set up. +4. The upper layer sends a message via `score::message_passing` to the `SOME/IP network daemon`, to offer the service + instance created in (1). Thus, the message contains a tag/message-id `OfferServiceInstance`. Further payload of + this message: + - `SomeIpServiceInstanceId` describing the service instance +5. The `SOME/IP network daemon`receives the message sent in (4) and then calls `vsomeip_v3::application::offer_event()` + for each event/field the underlying proxy created in (3) contains and then finally calls + `vsomeip_v3::application::offer_service()` with the args taken from `SomeIpServiceInstanceId`. +6. After the upper layer sends/updates an event/field on the `score::mw::com` skeleton, it sends a message via + `score::message_passing` to the `SOME/IP network daemon`, to push the update to the SOME/IP service instance. Thus, + the message contains a tag/message-id `UpdateEvent`. Further payload of this message: + - `SomeIpServiceInstanceId` describing the service instance. + - `EventId` describing which event/field to update +7. The `SOME/IP network daemon`receives the message sent in (6) and then calls `vsomeip_v3::application::send()` + for the event/field identified by `EventId`. The payload to hand over will be created by accessing the corresponding + event/field of the `score::mw::com` proxy via `GetNewSamples()`. I.e. only, when `ProxyEvent::GetNewSamples()` + returns a new `SamplePtr`, a `std::shared_ptr` will be created from it and handed over to the call of + `vsomeip_v3::application::send()`. After the call returned, the `SamplePtr` can be disposed. + +### Steps taken to stop-offer service instance + +In case the upper layer only wants to forward a "stop-offer" for its local `score::mw::com` skeleton, it sends a message +via `score::message_passing` to the `SOME/IP network daemon`, to stop the service instance offering. The message +contains a tag/message-id `StopOfferServiceInstance`. Further payload of this message: +- `SomeIpServiceInstanceId` describing the service instance + The implementation in `SOME/IP network daemon`receives the message and calls +- `vsomeip_v3::application::stop_offer_service()` with the args taken from `SomeIpServiceInstanceId`. + +## Service instance reception from SOME/IP network daemon + +### Steps taken to receive a SOME/IP service-instance and provide it locally + +1. The upper layer sends a message via `score::message_passing` to the `SOME/IP network daemon`, to trigger the search/ + discovery for the service instance on the SOME/IP (network) side. Thus, the message contains a tag/message-id + `DiscoverServiceInstance`. Further payload of this message: + - `SomeIpServiceInstanceId` describing the service instance + - detailed meta-info of all events/fields/methods, which is sufficient, that the `SOME/IP network daemon` can create + a `score::mw::com::GenericSkeleton` from it. +2. The `SOME/IP network daemon` receives the message in (1) and then calls + `vsomeip_v3::application::register_availability_handler`. All arguments but one are filled from + `SomeIpServiceInstanceId`. Last argument is the availability handler (`availability_handler_t`), created by the + `SOME/IP network daemon`. +3. As soon as the availability handler fires and indicates, that on SOME/IP the instance identified via + `SomeIpServiceInstanceId` is available, the `SOME/IP network daemon` creates a `score::mw::com::GenericSkeleton` + based on the arguments received in (1) and sends back a notification to the upper layer via `score::message_passing` + (`IServerConnection::Notify()`). Thus, the message contains a tag/message-id `ServiceInstanceAvailable`. Further + payload of this message: + - `SomeIpServiceInstanceId` describing the service instance + - `InstanceIdentifier`. describing the created `score::mw::com::GenericSkeleton` instance +4. Then the `SOME/IP network daemon` calls `vsomeip_v3::application::register_message_handler` for each event/field of + the service instance to register its handler for SOME/IP message reception. +5. When the upper layer receives the notification sent in (3), it calls `score::mw::com::GenericProxy::FindService()` + with the `InstanceIdentifier` taken from the message and then creates `GenericProxy` instance from the returned + handle. It now has a "connected" proxy to the SOME/IP service instance. +6. When an event/field update happens for the network side SOME/IP service instance identified by `SomeIpServiceInstanceId`, + the `SOME/IP network daemon` gets notified via its handler, which it has registered in (4). In its registered handler + the `SOME/IP network daemon` accesses the received message payload containing event/field data update and calls the + corresponding `GenericSkeletonEvent`/`GenericSkeletonField` `Send`/`Update` method. +7. The upper layer can then – via the GenericProxy it has created in (5) – access updated event/field data + with the standard mechanisms: (polling based or event notified) `GetNewSamples()`