����JFIFXX�����    $.' ",#(7),01444'9=82<.342  2!!22222222222222222222222222222222222222222222222222����"��4�� ���,�PG"Z_�4�˷����kjز�Z�,F+��_z�,�© �����zh6�٨�ic�fu���#ډb���_�N�?��wQ���5-�~�I���8����TK<5o�Iv-�����k�_U_�����~b�M��d����Ӝ�U�Hh��?]��E�w��Q���k�{��_}qFW7HTՑ��Y��F�?_�'ϔ��_�Ջt��=||I ��6�έ"�����D���/[�k�9���Y�8ds|\���Ҿp6�Ҵ���]��.����6�z<�v��@]�i%��$j��~�g��J>��no����pM[me�i$[����s�o�ᘨ�˸ nɜG-�ĨU�ycP�3.DB�li�;��hj���x7Z^�N�h������N3u{�:j�x�힞��#M&��jL P@_���� P��&��o8������9�����@Sz6�t7#O�ߋ �s}Yf�T���lmr����Z)'N��k�۞p����w\�Tȯ?�8`�O��i{wﭹW�[�r�� ��Q4F�׊���3m&L�=��h3����z~��#�\�l :�F,j@�� ʱ�wQT����8�"kJO���6�֚l����}���R�>ډK���]��y����&����p�}b��;N�1�m�r$�|��7�>e�@B�TM*-iH��g�D�)� E�m�|�ؘbҗ�a��Ҿ����t4���o���G��*oCN�rP���Q��@z,|?W[0�����:�n,jWiE��W��$~/�hp\��?��{(�0���+�Y8rΟ�+����>S-S����VN;�}�s?.����� w�9��˟<���Mq4�Wv'��{)0�1mB��V����W[�����8�/<� �%���wT^�5���b��)iM� pg�N�&ݝ��VO~�q���u���9� ����!��J27����$O-���! �:�%H��� ـ����y�ΠM=t{!S�� oK8������t<����è:a������[�����ա�H���~��w��Qz`�po�^ ����Q��n� �,uu�C�$ ^���,������8�#��:�6��e�|~���!�3�3.�\0��q��o�4`.|� ����y�Q�`~;�d�ׯ,��O�Zw�������`73�v�܋�<���Ȏ�� ـ4k��5�K�a�u�=9Yd��$>x�A�&�� j0� ���vF��� Y�|�y��� ~�6�@c��1vOp�Ig����4��l�OD���L����� R���c���j�_�uX6��3?nk��Wy�f;^*B� ��@�~a�`��Eu������+���6�L��.ü>��}y���}_�O�6�͐�:�YrG�X��kG�����l^w���~㒶sy��Iu�!� W ��X��N�7BV��O��!X�2����wvG�R�f�T#�����t�/?���%8�^�W�aT��G�cL�M���I��(J����1~�8�?aT ���]����AS�E��(��*E}� 2��#I/�׍qz��^t�̔���b�Yz4x���t�){ OH��+(E��A&�N�������XT��o��"�XC��'���)}�J�z�p� ��~5�}�^����+�6����w��c��Q�|Lp�d�H��}�(�.|����k��c4^�"�����Z?ȕ ��a<�L�!039C� �Eu�C�F�Ew�ç ;�n?�*o���B�8�bʝ���'#Rqf���M}7����]����s2tcS{�\icTx;�\��7K���P���ʇ Z O-��~��c>"��?�������P��E��O�8��@�8��G��Q�g�a�Վ���󁶠�䧘��_%#r�>�1�z�a��eb��qcPѵ��n���#L��� =��׀t� L�7�`��V���A{�C:�g���e@�w1 Xp3�c3�ġ����p��M"'-�@n4���fG��B3�DJ�8[Jo�ߐ���gK)ƛ��$���� ���8�3�����+���� �����6�ʻ���� ���S�kI�*KZlT _`���?��K����QK�d����B`�s}�>���`��*�>��,*@J�d�oF*����弝��O}�k��s��]��y�ߘ��c1G�V���<=�7��7����6�q�PT��tXԀ�!9*4�4Tހ3XΛex�46���Y��D ����� �BdemDa����\�_l,��G�/���֌7���Y�](�xTt^%�GE�����4�}bT���ڹ�����;Y)���B�Q��u��>J/J �⮶.�XԄ��j�ݳ�+E��d ��r�5�_D�1 ��o�� �B�x�΢�#���<��W�����8���R6�@g�M�.��� dr�D��>(otU��@x=��~v���2� ӣ�d�oBd��3�eO�6�㣷�����ݜ6��6Y��Qz`��S��{���\P�~z m5{J/L��1������<�e�ͅPu�b�]�ϔ���'������f�b� Zpw��c`"��i���BD@:)ִ�:�]��hv�E�w���T�l��P���"Ju�}��وV J��G6��. J/�Qgl߭�e�����@�z�Zev2u�)]կ�����7x���s�M�-<ɯ�c��r�v�����@��$�ޮ}lk���a���'����>x��O\�ZFu>�����ck#��&:��`�$�ai�>2Δ����l���oF[h��lE�ܺ�Πk:)���`�� $[6�����9�����kOw�\|���8}������ބ:��񶐕��I�A1/�=�2[�,�!��.}gN#�u����b��� ~��݊��}34q����d�E��Lc��$��"�[q�U�硬g^��%B �z���r�pJ�ru%v\h1Y�ne`ǥ:g���pQM~�^�Xi� ��`S�:V29.�P���V�?B�k�� AEvw%�_�9C�Q����wKekPؠ�\�;Io d�{ ߞo�c1eP����\� `����E=���@K<�Y���eڼ�J���w����{av�F�'�M�@/J��+9p���|]�����Iw &`��8���&M�hg��[�{��Xj��%��Ӓ�$��(����ʹN���<>�I���RY���K2�NPlL�ɀ)��&e����B+ь����( � �JTx���_?EZ� }@ 6�U���뙢ط�z��dWI�n` D����噥�[��uV��"�G&Ú����2g�}&m��?ċ�"����Om#��������� ��{�ON��"S�X��Ne��ysQ���@Fn��Vg���dX�~nj�]J�<�K]:��FW��b�������62�=��5f����JKw��bf�X�55��~J �%^����:�-�QIE��P��v�nZum� z � ~ə ���� ���ة����;�f��\v���g�8�1��f24;�V���ǔ�)����9���1\��c��v�/'Ƞ�w�������$�4�R-��t���� e�6�/�ġ �̕Ecy�J���u�B���<�W�ַ~�w[B1L۲�-JS΂�{���΃������A��20�c#��@ 0!1@AP"#2Q`$3V�%45a6�FRUq��� ����^7ׅ,$n�������+��F�`��2X'��0vM��p�L=������5��8������u�p~���.�`r�����\���O��,ư�0oS ��_�M�����l���4�kv\JSd���x���SW�<��Ae�IX����������$I���w�:S���y���›R��9�Q[���,�5�;�@]�%���u�@ *ro�lbI �� ��+���%m:�͇ZV�����u�̉����θau<�fc�.����{�4Ա� �Q����*�Sm��8\ujqs]{kN���)qO�y�_*dJ�b�7���yQqI&9�ԌK!�M}�R�;������S�T���1���i[U�ɵz�]��U)V�S6���3$K{�ߊ<�(� E]Զ[ǼENg�����'�\?#)Dkf��J���o��v���'�%ƞ�&K�u�!��b�35LX�Ϸ��63$K�a�;�9>,R��W��3�3� d�JeTYE.Mϧ��-�o�j3+y��y^�c�������VO�9NV\nd�1 ��!͕_)a�v;����թ�M�lWR1��)El��P;��yوÏ�u 3�k�5Pr6<�⒲l�!˞*��u־�n�!�l:����UNW ��%��Chx8vL'��X�@��*��)���̮��ˍ��� ���D-M�+J�U�kvK����+�x8��cY������?�Ԡ��~3mo��|�u@[XeY�C�\Kp�x8�oC�C�&����N�~3-H���� ��MX�s�u<`���~"WL��$8ξ��3���a�)|:@�m�\���^�`�@ҷ)�5p+��6���p�%i)P M���ngc�����#0Aruz���RL+xSS?���ʮ}()#�t��mˇ!��0}}y����<�e� �-ή�Ԩ��X������ MF���ԙ~l L.3���}�V뽺�v�����멬��Nl�)�2����^�Iq��a��M��qG��T�����c3#������3U�Ǎ���}��לS�|qa��ڃ�+���-��2�f����/��bz��ڐ�� �ݼ[2�ç����k�X�2�* �Z�d���J�G����M*9W���s{��w���T��x��y,�in�O�v��]���n����P�$�JB@=4�OTI�n��e�22a\����q�d���%�$��(���:���: /*�K[PR�fr\nڙdN���F�n�$�4�[�� U�zƶ����� �mʋ���,�ao�u 3�z� �x��Kn����\[��VFmbE;�_U��&V�Gg�]L�۪&#n%�$ɯ�dG���D�TI=�%+AB�Ru#��b4�1�»x�cs�YzڙJG��f��Il��d�eF'T� iA��T���uC�$����Y��H?����[!G`}���ͪ� �纤Hv\������j�Ex�K���!���OiƸ�Yj�+u-<���'q����uN�*�r\��+�]���<�wOZ.fp�ێ��,-*)V?j-kÊ#�`�r��dV����(�ݽBk�����G�ƛk�QmUڗe��Z���f}|����8�8��a���i��3'J�����~G_�^���d�8w������ R�`(�~�.��u���l�s+g�bv���W���lGc}��u���afE~1�Ue������Z�0�8�=e�� f@/�jqEKQQ�J��oN��J���W5~M>$6�Lt�;$ʳ{���^��6�{����v6���ķܰg�V�cnn �~z�x�«�,2�u�?cE+Ș�H؎�%�Za�)���X>uW�Tz�Nyo����s���FQƤ��$��*�&�LLXL)�1�" L��eO��ɟ�9=���:t��Z���c��Ž���Y?�ӭV�wv�~,Y��r�ۗ�|�y��GaF�����C�����.�+� ���v1���fήJ�����]�S��T��B��n5sW}y�$��~z�'�c ��8 ��� ,! �p��VN�S��N�N�q��y8z˱�A��4��*��'������2n<�s���^ǧ˭P�Jޮɏ�U�G�L�J�*#��<�V��t7�8����TĜ>��i}K%,���)[��z�21z ?�N�i�n1?T�I�R#��m-�����������������1����lA�`��fT5+��ܐ�c�q՝��ʐ��,���3�f2U�եmab��#ŠdQ�y>\��)�SLY����w#��.���ʑ�f��� ,"+�w�~�N�'�c�O�3F�������N<���)j��&��,-� �љ���֊�_�zS���TǦ����w�>��?�������n��U仆�V���e�����0���$�C�d���rP �m�׈e�Xm�Vu� �L��.�bֹ��� �[Դaզ���*��\y�8�Է:�Ez\�0�Kq�C b��̘��cө���Q��=0Y��s�N��S.���3.���O�o:���#���v7�[#߫ ��5�܎�L���Er4���9n��COWlG�^��0k�%<���ZB���aB_���������'=��{i�v�l�$�uC���mƎҝ{�c㱼�y]���W�i ��ߧc��m�H� m�"�"�����;Y�ߝ�Z�Ǔ�����:S#��|}�y�,/k�Ld� TA�(�AI$+I3��;Y*���Z��}|��ӧO��d�v��..#:n��f>�>���ȶI�TX��� 8��y����"d�R�|�)0���=���n4��6ⲑ�+��r<�O�܂~zh�z����7ܓ�HH�Ga롏���nCo�>������a ���~]���R���̲c?�6(�q�;5%� |�uj�~z8R=X��I�V=�|{v�Gj\gc��q����z�؋%M�ߍ����1y��#��@f^���^�>N�����#x#۹��6�Y~�?�dfPO��{��P�4��V��u1E1J �*|���%���JN��`eWu�zk M6���q t[�� ��g�G���v��WIG��u_ft����5�j�"�Y�:T��ɐ���*�;� e5���4����q$C��2d�}���� _S�L#m�Yp��O�.�C�;��c����Hi#֩%+) �Ӎ��ƲV���SYź��g |���tj��3�8���r|���V��1#;.SQ�A[���S������#���`n�+���$��$I �P\[�@�s��(�ED�z���P��])8�G#��0B��[ى��X�II�q<��9�~[Z멜�Z�⊔IWU&A>�P~�#��dp<�?����7���c��'~���5 ��+$���lx@�M�dm��n<=e�dyX��?{�|Aef ,|n3�<~z�ƃ�uۧ�����P��Y,�ӥQ�*g�#먙R�\���;T��i,��[9Qi歉����c>]9�� ��"�c��P�� �Md?٥��If�ت�u��k��/����F��9�c*9��Ǎ:�ØF���z�n*�@|I�ށ9����N3{'��[�'ͬ�Ҳ4��#}��!�V� Fu��,�,mTIk���v C�7v���B�6k�T9��1�*l� '~��ƞF��lU��'�M ����][ΩũJ_�{�i�I�n��$���L�� j��O�dx�����kza۪��#�E��Cl����x˘�o�����V���ɞ�ljr��)�/,�߬h�L��#��^��L�ф�,íMƁe�̩�NB�L�����iL����q�}��(��q��6IçJ$�W�E$��:������=#����(�K�B����zђ <��K(�N�۫K�w��^O{!����)�H���>x�������lx�?>Պ�+�>�W���,Ly!_�D���Ō�l���Q�!�[ �S����J��1��Ɛ�Y}��b,+�Lo�x�ɓ)����=�y�oh�@�꥟/��I��ѭ=��P�y9��� �ۍYӘ�e+�p�Jnϱ?V\SO%�(�t� ���=?MR�[Ș�����d�/ ��n�l��B�7j� ��!�;ӥ�/�[-���A�>�dN�sLj ��,ɪv��=1c�.SQ�O3�U���ƀ�ܽ�E����������̻��9G�ϷD�7(�}��Ävӌ\�y�_0[w ���<΍>����a_��[0+�L��F.�޺��f�>oN�T����q;���y\��bՃ��y�jH�<|q-eɏ�_?_9+P���Hp$�����[ux�K w�Mw��N�ی'$Y2�=��q���KB��P��~������Yul:�[<����F1�2�O���5=d����]Y�sw:���Ϯ���E��j,_Q��X��z`H1,#II ��d�wr��P˂@�ZJV����y$�\y�{}��^~���[:N����ߌ�U�������O��d�����ؾe��${p>G��3c���Ė�lʌ�� ת��[��`ϱ�-W����dg�I��ig2��� ��}s ��ؤ(%#sS@���~���3�X�nRG�~\jc3�v��ӍL��M[JB�T��s3}��j�Nʖ��W����;7��ç?=X�F=-�=����q�ߚ���#���='�c��7���ڑW�I(O+=:uxq�������������e2�zi+�kuG�R��������0�&e�n���iT^J����~\jy���p'dtG��s����O��3����9* �b#Ɋ�� p������[Bws�T�>d4�ۧs���nv�n���U���_�~,�v����ƜJ1��s�� �QIz��)�(lv8M���U=�;����56��G���s#�K���MP�=��LvyGd��}�VwWBF�'�à �?MH�U�g2�� ����!�p�7Q��j��ڴ����=��j�u��� Jn�A s���uM������e��Ɔ�Ҕ�!)'��8Ϣ�ٔ��ޝ(��Vp���צ֖d=�IC�J�Ǡ{q������kԭ�߸���i��@K����u�|�p=..�*+����x�����z[Aqġ#s2a�Ɗ���RR�)*HRsi�~�a &f��M��P����-K�L@��Z��Xy�'x�{}��Zm+���:�)�) IJ�-i�u���� ���ܒH��'�L(7�y�GӜq���� j��� 6ߌg1�g�o���,kر���tY�?W,���p���e���f�OQS��!K�۟cҒA�|ս�j�>��=⬒��˧L[�� �߿2JaB~R��u�:��Q�] �0H~���]�7��Ƽ�I���(}��cq '�ήET���q�?f�ab���ӥvr� �)o��-Q��_'����ᴎo��K������;��V���o��%���~OK ����*��b�f:���-ťIR��`B�5!RB@���ï�� �u �̯e\�_U�_������� g�ES��3�������QT��a����x����U<~�c?�*�#]�MW,[8O�a�x��]�1bC|踤�P��lw5V%�)�{t�<��d��5���0i�XSU��m:��Z�┵�i�"��1�^B�-��P�hJ��&)O��*�D��c�W��vM��)����}���P��ܗ-q����\mmζZ-l@�}��a��E�6��F�@��&Sg@���ݚ�M����� ȹ 4����#p�\H����dYDo�H���"��\��..R�B�H�z_�/5˘����6��KhJR��P�mƶi�m���3�,#c�co��q�a)*Pt����R�m�k�7x�D�E�\Y�閣_X�<���~�)���c[[�BP����6�Yq���S��0����%_����;��Àv�~�| VS؇ ��'O0��F0��\���U�-�d@�����7�SJ*z��3n��y��P����O���������m�~�P�3|Y��ʉr#�C�<�G~�.,! ���bqx���h~0=��!ǫ�jy����l�O,�[B��~��|9��ٱ����Xly�#�i�B��g%�S��������tˋ���e���ې��\[d�t)��.+u�|1 ������#�~Oj����hS�%��i.�~X���I�H�m��0n���c�1uE�q��cF�RF�o���7� �O�ꮧ� ���ۛ{��ʛi5�rw?׌#Qn�TW��~?y$��m\�\o����%W� ?=>S�N@�� �Ʈ���R����N�)�r"C�:��:����� �����#��qb��Y�. �6[��2K����2u�Ǧ�HYR��Q�MV��� �G�$��Q+.>�����nNH��q�^��� ����q��mM��V��D�+�-�#*�U�̒ ���p욳��u:�������IB���m���PV@O���r[b= �� ��1U�E��_Nm�yKbN�O���U�}�the�`�|6֮P>�\2�P�V���I�D�i�P�O;�9�r�mAHG�W�S]��J*�_�G��+kP�2����Ka�Z���H�'K�x�W�MZ%�O�YD�Rc+o��?�q��Ghm��d�S�oh�\�D�|:W������UA�Qc yT�q������~^�H��/��#p�CZ���T�I�1�ӏT����4��"�ČZ�����}��`w�#�*,ʹ�� ��0�i��課�Om�*�da��^gJ݅{���l�e9uF#T�ֲ��̲�ٞC"�q���ߍ ոޑ�o#�XZTp����@ o�8��(jd��xw�]�,f���`~�|,s��^����f�1���t��|��m�򸄭/ctr��5s��7�9Q�4�H1꠲BB@l9@���C�����+�wp�xu�£Yc�9��?`@#�o�mH�s2��)�=��2�.�l����jg�9$�Y�S�%*L������R�Y������7Z���,*=�䷘$�������arm�o�ϰ���UW.|�r�uf����IGw�t����Zwo��~5 ��YյhO+=8fF�)�W�7�L9lM�̘·Y���֘YLf�큹�pRF���99.A �"wz��=E\Z���'a� 2��Ǚ�#;�'}�G���*��l��^"q��+2FQ� hj��kŦ��${���ޮ-�T�٭cf�|�3#~�RJ����t��$b�(R��(����r���dx� >U b�&9,>���%E\� Ά�e�$��'�q't��*�א���ެ�b��-|d���SB�O�O��$�R+�H�)�܎�K��1m`;�J�2�Y~9��O�g8=vqD`K[�F)k�[���1m޼c��n���]s�k�z$@��)!I �x՝"v��9=�ZA=`Ɠi �:�E��)`7��vI��}d�YI�_ �o�:ob���o ���3Q��&D&�2=�� �Ά��;>�h����y.*ⅥS������Ӭ�+q&����j|UƧ����}���J0��WW< ۋS�)jQR�j���Ư��rN)�Gű�4Ѷ(�S)Ǣ�8��i��W52���No˓� ۍ%�5brOn�L�;�n��\G����=�^U�dI���8$�&���h��'���+�(������cȁ߫k�l��S^���cƗjԌE�ꭔ��gF���Ȓ��@���}O���*;e�v�WV���YJ\�]X'5��ղ�k�F��b 6R�o՜m��i N�i����>J����?��lPm�U��}>_Z&�KK��q�r��I�D�Չ~�q�3fL�:S�e>���E���-G���{L�6p�e,8��������QI��h��a�Xa��U�A'���ʂ���s�+טIjP�-��y�8ۈZ?J$��W�P� ��R�s�]��|�l(�ԓ��sƊi��o(��S0��Y� 8�T97.�����WiL��c�~�dxc�E|�2!�X�K�Ƙਫ਼�$((�6�~|d9u+�qd�^3�89��Y�6L�.I�����?���iI�q���9�)O/뚅����O���X��X�V��ZF[�یgQ�L��K1���RҖr@v�#��X�l��F���Нy�S�8�7�kF!A��sM���^rkp�jP�DyS$N���q��nxҍ!U�f�!eh�i�2�m���`�Y�I�9r�6� �TF���C}/�y�^���Η���5d�'��9A-��J��>{�_l+�`��A���[�'��յ�ϛ#w:݅�%��X�}�&�PSt�Q�"�-��\縵�/����$Ɨh�Xb�*�y��BS����;W�ջ_mc�����vt?2}1�;qS�d�d~u:2k5�2�R�~�z+|HE!)�Ǟl��7`��0�<�,�2*���Hl-��x�^����'_TV�gZA�'j� ^�2Ϊ��N7t�����?w�� �x1��f��Iz�C-Ȗ��K�^q�;���-W�DvT�7��8�Z�������� hK�(P:��Q- �8�n�Z���܃e貾�<�1�YT<�,�����"�6{/ �?�͟��|1�:�#g��W�>$����d��J��d�B��=��jf[��%rE^��il:��B���x���Sּ�1հ��,�=��*�7 fcG��#q� �eh?��2�7�����,�!7x��6�n�LC�4x��},Geǝ�tC.��vS �F�43��zz\��;QYC,6����~;RYS/6���|2���5���v��T��i����������mlv��������&� �nRh^ejR�LG�f���? �ۉҬܦƩ��|��Ȱ����>3����!v��i�ʯ�>�v��オ�X3e���_1z�Kȗ\<������!�8���V��]��?b�k41�Re��T�q��mz��TiOʦ�Z��Xq���L������q"+���2ۨ��8}�&N7XU7Ap�d�X��~�׿��&4e�o�F��� �H����O���č�c�� 懴�6���͉��+)��v;j��ݷ�� �UV�� i��� j���Y9GdÒJ1��詞�����V?h��l����l�cGs�ځ�������y�Ac�����\V3�? �� ܙg�>qH�S,�E�W�[�㺨�uch�⍸�O�}���a��>�q�6�n6����N6�q������N ! 1AQaq�0@����"2BRb�#Pr���3C`��Scst���$4D���%Td�� ?���N����a��3��m���C���w��������xA�m�q�m���m������$����4n淿t'��C"w��zU=D�\R+w�p+Y�T�&�պ@��ƃ��3ޯ?�Aﶂ��aŘ���@-�����Q�=���9D��ռ�ѻ@��M�V��P��܅�G5�f�Y<�u=,EC)�<�Fy'�"�&�չ�X~f��l�KԆV��?�� �W�N����=(� �;���{�r����ٌ�Y���h{�١������jW����P���Tc�����X�K�r��}���w�R��%��?���E��m�� �Y�q|����\lEE4���r���}�lsI�Y������f�$�=�d�yO����p�����yBj8jU�o�/�S��?�U��*������ˍ�0������u�q�m [�?f����a�� )Q�>����6#������� ?����0UQ����,IX���(6ڵ[�DI�MNލ�c&���υ�j\��X�R|,4��� j������T�hA�e��^���d���b<����n�� �즇�=!���3�^�`j�h�ȓr��jẕ�c�,ٞX����-����a�ﶔ���#�$��]w�O��Ӫ�1y%��L�Y<�wg#�ǝ�̗`�x�xa�t�w��»1���o7o5��>�m뭛C���Uƃߜ}�C���y1Xνm�F8�jI���]����H���ۺиE@I�i;r�8ӭ����V�F�Շ| ��&?�3|x�B�MuS�Ge�=Ӕ�#BE5G�����Y!z��_e��q�р/W>|-�Ci߇�t�1ޯќd�R3�u��g�=0 5��[?�#͏��q�cf���H��{ ?u�=?�?ǯ���}Z��z���hmΔ�BFTW�����<�q�(v� ��!��z���iW]*�J�V�z��gX֧A�q�&��/w���u�gYӘa���; �i=����g:��?2�dž6�ى�k�4�>�Pxs����}������G�9��3 ���)gG�R<>r h�$��'nc�h�P��Bj��J�ҧH� -��N1���N��?��~��}-q!=��_2hc�M��l�vY%UE�@|�v����M2�.Y[|y�"Eï��K�ZF,�ɯ?,q�?v�M 80jx�"�;�9vk�����+ ֧�� �ȺU��?�%�vcV��mA�6��Qg^M����A}�3�nl� QRN�l8�kkn�'�����(��M�7m9و�q���%ޟ���*h$Zk"��$�9��: �?U8�Sl��,,|ɒ��xH(ѷ����Gn�/Q�4�P��G�%��Ա8�N��!� �&�7�;���eKM7�4��9R/%����l�c>�x;������>��C�:�����t��h?aKX�bhe�ᜋ^�$�Iհ �hr7%F$�E��Fd���t��5���+�(M6�t����Ü�UU|zW�=a�Ts�Tg������dqP�Q����b'�m���1{|Y����X�N��b �P~��F^F:����k6�"�j!�� �I�r�`��1&�-$�Bevk:y���#yw��I0��x��=D�4��tU���P�ZH��ڠ底taP��6����b>�xa����Q�#� WeF��ŮNj�p�J* mQ�N����*I�-*�ȩ�F�g�3 �5��V�ʊ�ɮ�a��5F���O@{���NX��?����H�]3��1�Ri_u��������ѕ�� ����0��� F��~��:60�p�͈�S��qX#a�5>���`�o&+�<2�D����: �������ڝ�$�nP���*)�N�|y�Ej�F�5ټ�e���ihy�Z �>���k�bH�a�v��h�-#���!�Po=@k̆IEN��@��}Ll?j�O������߭�ʞ���Q|A07x���wt!xf���I2?Z��<ץ�T���cU�j��]��陎Ltl �}5�ϓ��$�,��O�mˊ�;�@O��jE��j(�ا,��LX���LO���Ц�90�O �.����a��nA���7������j4 ��W��_ٓ���zW�jcB������y՗+EM�)d���N�g6�y1_x��p�$Lv:��9�"z��p���ʙ$��^��JԼ*�ϭ����o���=x�Lj�6�J��u82�A�H�3$�ٕ@�=Vv�]�'�qEz�;I˼��)��=��ɯ���x �/�W(V���p�����$ �m�������u�����񶤑Oqˎ�T����r��㠚x�sr�GC��byp�G��1ߠ�w e�8�$⿄����/�M{*}��W�]˷.�CK\�ުx���/$�WPw���r� |i���&�}�{�X� �>��$-��l���?-z���g����lΆ���(F���h�vS*���b���߲ڡn,|)mrH[���a�3�ר�[1��3o_�U�3�TC�$��(�=�)0�kgP���� ��u�^=��4 �WYCҸ:��vQ�ר�X�à��tk�m,�t*��^�,�}D*� �"(�I��9R����>`�`��[~Q]�#af��i6l��8���6�:,s�s�N6�j"�A4���IuQ��6E,�GnH��zS�HO�uk�5$�I�4��ؤ�Q9�@��C����wp�BGv[]�u�Ov���0I4���\��y�����Q�Ѹ��~>Z��8�T��a��q�ޣ;z��a���/��S��I:�ܫ_�|������>=Z����8:�S��U�I�J��"IY���8%b8���H��:�QO�6�;7�I�S��J��ҌAά3��>c���E+&jf$eC+�z�;��V����� �r���ʺ������my�e���aQ�f&��6�ND��.:��NT�vm�<- u���ǝ\MvZY�N�NT��-A�>jr!S��n�O 1�3�Ns�%�3D@���`������ܟ 1�^c<���� �a�ɽ�̲�Xë#�w�|y�cW�=�9I*H8�p�^(4���՗�k��arOcW�tO�\�ƍR��8����'�K���I�Q�����?5�>[�}��yU�ײ -h��=��% q�ThG�2�)���"ו3]�!kB��*p�FDl�A���,�eEi�H�f�Ps�����5�H:�Փ~�H�0Dت�D�I����h�F3�������c��2���E��9�H��5�zԑ�ʚ�i�X�=:m�xg�hd(�v����׊�9iS��O��d@0ڽ���:�p�5�h-��t�&���X�q�ӕ,��ie�|���7A�2���O%P��E��htj��Y1��w�Ѓ!����  ���� ࢽ��My�7�\�a�@�ţ�J �4�Ȼ�F�@o�̒?4�wx��)��]�P��~�����u�����5�����7X ��9��^ܩ�U;Iꭆ 5 �������eK2�7(�{|��Y׎ �V��\"���Z�1� Z�����}��(�Ǝ"�1S���_�vE30>���p;� ΝD��%x�W�?W?v����o�^V�i�d��r[��/&>�~`�9Wh��y�;���R��� ;;ɮT��?����r$�g1�K����A��C��c��K��l:�'��3 c�ﳯ*"t8�~l��)���m��+U,z��`(�>yJ�?����h>��]��v��ЍG*�{`��;y]��I�T� ;c��NU�fo¾h���/$���|NS���1�S�"�H��V���T���4��uhǜ�]�v;���5�͠x��'C\�SBpl���h}�N����� A�Bx���%��ޭ�l��/����T��w�ʽ]D�=����K���ž�r㻠l4�S�O?=�k �M:� ��c�C�a�#ha���)�ѐxc�s���gP�iG��{+���x���Q���I= �� z��ԫ+ �8"�k�ñ�j=|����c ��y��CF��/��*9ж�h{ �?4�o� ��k�m�Q�N�x��;�Y��4膚�a�w?�6�>e]�����Q�r�:����g�,i"�����ԩA�*M�<�G��b�if��l^M��5� �Ҩ�{����6J��ZJ�����P�*�����Y���ݛu�_4�9�I8�7���������,^ToR���m4�H��?�N�S�ѕw��/S��甍�@�9H�S�T��t�ƻ���ʒU��*{Xs�@����f�����֒Li�K{H�w^���������Ϥm�tq���s� ���ք��f:��o~s��g�r��ט� �S�ѱC�e]�x���a��) ���(b-$(�j>�7q�B?ӕ�F��hV25r[7 Y� }L�R��}����*sg+��x�r�2�U=�*'WS��ZDW]�WǞ�<��叓���{�$�9Ou4��y�90-�1�'*D`�c�^o?(�9��u���ݐ��'PI&� f�Jݮ�������:wS����jfP1F:X �H�9dԯ���˝[�_54 �}*;@�ܨ�� ð�yn�T���?�ןd�#���4rG�ͨ��H�1�|-#���Mr�S3��G�3�����)�.᧏3v�z֑��r����$G"�`j �1t��x0<Ɔ�Wh6�y�6��,œ�Ga��gA����y��b��)��h�D��ß�_�m��ü �gG;��e�v��ݝ�nQ� ��C����-�*��o���y�a��M��I�>�<���]obD��"�:���G�A��-\%LT�8���c�)��+y76���o�Q�#*{�(F�⽕�y����=���rW�\p���۩�c���A���^e6��K������ʐ�cVf5$�'->���ՉN"���F�"�UQ@�f��Gb~��#�&�M=��8�ט�JNu9��D��[̤�s�o�~������ G��9T�tW^g5y$b��Y'��س�Ǵ�=��U-2 #�MC�t(�i� �lj�@Q 5�̣i�*�O����s�x�K�f��}\��M{E�V�{�υ��Ƈ�����);�H����I��fe�Lȣr�2��>��W�I�Ȃ6������i��k�� �5�YOxȺ����>��Y�f5'��|��H+��98pj�n�.O�y�������jY��~��i�w'������l�;�s�2��Y��:'lg�ꥴ)o#'Sa�a�K��Z� �m��}�`169�n���"���x��I ��*+� }F<��cГ���F�P�������ֹ*�PqX�x۩��,� ��N�� �4<-����%����:��7����W���u�`����� $�?�I��&����o��o��`v�>��P��"��l���4��5'�Z�gE���8���?��[�X�7(��.Q�-��*���ތL@̲����v��.5���[��=�t\+�CNܛ��,g�SQnH����}*F�G16���&:�t��4ُ"A��̣��$�b �|����#rs��a�����T�� ]�<�j��BS�('$�ɻ� �wP;�/�n��?�ݜ��x�F��yUn�~mL*-�������Xf�wd^�a�}��f�,=t�׵i�.2/wpN�Ep8�OР���•��R�FJ� 55TZ��T �ɭ�<��]��/�0�r�@�f��V��V����Nz�G��^���7hZi����k��3�,kN�e|�vg�1{9]_i��X5y7� 8e]�U����'�-2,���e"����]ot�I��Y_��n�(JҼ��1�O ]bXc���Nu�No��pS���Q_���_�?i�~�x h5d'�(qw52] ��'ޤ�q��o1�R!���`ywy�A4u���h<קy���\[~�4�\ X�Wt/� 6�����n�F�a8��f���z �3$�t(���q��q�x��^�XWeN'p<-v�!�{�(>ӽDP7��ո0�y)�e$ٕv�Ih'Q�EA�m*�H��RI��=:��� ���4牢) �%_iN�ݧ�l]� �Nt���G��H�L��� ɱ�g<���1V�,�J~�ٹ�"K��Q�� 9�HS�9�?@��k����r�;we݁�]I�!{ �@�G�[�"��`���J:�n]�{�cA�E����V��ʆ���#��U9�6����j�#Y�m\��q�e4h�B�7��C�������d<�?J����1g:ٳ���=Y���D�p�ц� ׈ǔ��1�]26؜oS�'��9�V�FVu�P�h�9�xc�oq�X��p�o�5��Ա5$�9W�V(�[Ak�aY錎qf;�'�[�|���b�6�Ck��)��#a#a˙��8���=äh�4��2��C��4tm^ �n'c���]GQ$[Wҿ��i���vN�{Fu ��1�gx��1┷���N�m��{j-,��x�� Ūm�ЧS�[�s���Gna���䑴�� x�p 8<������97�Q���ϴ�v�aϚG��Rt�Һ׈�f^\r��WH�JU�7Z���y)�vg=����n��4�_)y��D'y�6�]�c�5̪�\� �PF�k����&�c;��cq�$~T�7j ���nç]�<�g ":�to�t}�159�<�/�8������m�b�K#g'I'.W�����6��I/��>v��\�MN��g���m�A�yQL�4u�Lj�j9��#44�t��l^�}L����n��R��!��t��±]��r��h6ٍ>�yҏ�N��fU�� ���� Fm@�8}�/u��jb9������he:A�y�ծw��GpΧh�5����l}�3p468��)U��d��c����;Us/�֔�YX�1�O2��uq�s��`hwg�r~�{ R��mhN��؎*q 42�*th��>�#���E����#��Hv�O����q�}�����6�e��\�,Wk�#���X��b>��p}�դ��3���T5��†��6��[��@�P�y*n��|'f�֧>�lư΂�̺����SU�'*�q�p�_S�����M�� '��c�6�����m�� ySʨ;M��r���Ƌ�m�Kxo,���Gm�P��A�G�:��i��w�9�}M(�^�V��$ǒ�ѽ�9���|���� �a����J�SQ�a���r�B;����}���ٻ֢�2�%U���c�#�g���N�a�ݕ�'�v�[�OY'��3L�3�;,p�]@�S��{ls��X�'���c�jw�k'a�.��}�}&�� �dP�*�bK=ɍ!����;3n�gΊU�ߴmt�'*{,=SzfD� A��ko~�G�aoq�_mi}#�m�������P�Xhύ����mxǍ�΂���巿zf��Q���c���|kc�����?���W��Y�$���_Lv����l߶��c���`?����l�j�ݲˏ!V��6����U�Ђ(A���4y)H���p�Z_�x��>���e��R��$�/�`^'3qˏ�-&Q�=?��CFVR �D�fV�9��{�8g�������n�h�(P"��6�[�D���< E�����~0<@�`�G�6����Hг�cc�� �c�K.5��D��d�B���`?�XQ��2��ٿyqo&+�1^� DW�0�ꊩ���G�#��Q�nL3��c���������/��x ��1�1[y�x�პCW��C�c�UĨ80�m�e�4.{�m��u���I=��f�����0QRls9���f���������9���~f�����Ǩ��a�"@�8���ȁ�Q����#c�ic������G��$���G���r/$W�(��W���V�"��m�7�[m�A�m����bo��D� j����۳� l���^�k�h׽����� ��#� iXn�v��eT�k�a�^Y�4�BN��ĕ��0 !01@Q"2AaPq3BR������?���@4�Q�����T3,���㺠�W�[=JK�Ϟ���2�r^7��vc�:�9 �E�ߴ�w�S#d���Ix��u��:��Hp��9E!�� V 2;73|F��9Y���*ʬ�F��D����u&���y؟��^EA��A��(ɩ���^��GV:ݜDy�`��Jr29ܾ�㝉��[���E;Fzx��YG��U�e�Y�C���� ����v-tx����I�sם�Ę�q��Eb�+P\ :>�i�C'�;�����k|z�رn�y]�#ǿb��Q��������w�����(�r|ӹs��[�D��2v-%��@;�8<a���[\o[ϧw��I!��*0�krs)�[�J9^��ʜ��p1)� "��/_>��o��<1����A�E�y^�C��`�x1'ܣn�p��s`l���fQ��):�l����b>�Me�jH^?�kl3(�z:���1ŠK&?Q�~�{�ٺ�h�y���/�[��V�|6��}�KbX����mn[-��7�5q�94�������dm���c^���h� X��5��<�eޘ>G���-�}�دB�ޟ� ��|�rt�M��V+�]�c?�-#ڛ��^ǂ}���Lkr���O��u�>�-D�ry� D?:ޞ�U��ǜ�7�V��?瓮�"�#���r��չģVR;�n���/_� ؉v�ݶe5d�b9��/O��009�G���5n�W����JpA�*�r9�>�1��.[t���s�F���nQ� V 77R�]�ɫ8����_0<՜�IF�u(v��4��F�k�3��E)��N:��yڮe��P�`�1}�$WS��J�SQ�N�j�ٺ��޵�#l���ј(�5=��5�lǏmoW�v-�1����v,W�mn��߀$x�<����v�j(����c]��@#��1������Ǔ���o'��u+����;G�#�޸��v-lη��/(`i⣍Pm^���ԯ̾9Z��F��������n��1��� ��]�[��)�'������:�֪�W��FC����� �B9،!?���]��V��A�Վ�M��b�w��G F>_DȬ0¤�#�QR�[V��kz���m�w�"��9ZG�7'[��=�Q����j8R?�zf�\a�=��O�U����*oB�A�|G���2�54 �p��.w7� �� ��&������ξxGHp� B%��$g�����t�Џ򤵍z���HN�u�Я�-�'4��0��;_��3 !01"@AQa2Pq#3BR������?��ʩca��en��^��8���<�u#��m*08r��y�N"�<�Ѳ0��@\�p��� �����Kv�D��J8�Fҽ� �f�Y��-m�ybX�NP����}�!*8t(�OqѢ��Q�wW�K��ZD��Δ^e��!� ��B�K��p~�����e*l}z#9ң�k���q#�Ft�o��S�R����-�w�!�S���Ӥß|M�l޶V��!eˈ�8Y���c�ЮM2��tk���� ������J�fS����Ö*i/2�����n]�k�\���|4yX�8��U�P.���Ы[���l��@"�t�<������5�lF���vU�����W��W��;�b�cД^6[#7@vU�xgZv��F�6��Q,K�v��� �+Ъ��n��Ǣ��Ft���8��0��c�@�!�Zq s�v�t�;#](B��-�nῃ~���3g������5�J�%���O������n�kB�ĺ�.r��+���#�N$?�q�/�s�6��p��a����a��J/��M�8��6�ܰ"�*������ɗud"\w���aT(����[��F��U՛����RT�b���n�*��6���O��SJ�.�ij<�v�MT��R\c��5l�sZB>F��<7�;EA��{��E���Ö��1U/�#��d1�a�n.1ě����0�ʾR�h��|�R��Ao�3�m3 ��%�� ���28Q� ��y��φ���H�To�7�lW>����#i`�q���c����a��� �m,B�-j����݋�'mR1Ήt�>��V��p���s�0IbI�C.���1R�ea�����]H�6����������4B>��o��](��$B���m�����a�!=��?�B� K�Ǿ+�Ծ"�n���K��*��+��[T#�{E�J�S����Q�����s�5�:�U�\wĐ�f�3����܆&�)����I���Ԇw��E T�lrTf6Q|R�h:��[K�� �z��c֧�G�C��%\��_�a�84��HcO�bi��ؖV��7H �)*ģK~Xhչ0��4?�0��� �E<���}3���#���u�?�� ��|g�S�6ꊤ�|�I#Hڛ� �ա��w�X��9��7���Ŀ%�SL��y6č��|�F�a 8���b��$�sק�h���b9RAu7�˨p�Č�_\*w��묦��F ����4D~�f����|(�"m���NK��i�S�>�$d7SlA��/�²����SL��|6N�}���S�˯���g��]6��; �#�.��<���q'Q�1|KQ$�����񛩶"�$r�b:���N8�w@��8$�� �AjfG|~�9F ���Y��ʺ��Bwؒ������M:I岎�G��`s�YV5����6��A �b:�W���G�q%l�����F��H���7�������Fsv7��k�� 403WebShell
403Webshell
Server IP : 14.139.229.36  /  Your IP : 10.1.1.9
Web Server : Apache
System : Linux gbpuat-tech.ac.in 4.18.0-240.15.1.el8_3.x86_64 #1 SMP Mon Mar 1 17:16:16 UTC 2021 x86_64
User : apache ( 48)
PHP Version : 7.2.24
Disable Function : NONE
MySQL : OFF  |  cURL : ON  |  WGET : ON  |  Perl : ON  |  Python : OFF  |  Sudo : ON  |  Pkexec : ON
Directory :  /usr/share/doc/qemu-kvm/interop/

Upload File :
current_dir [ Writeable ] document_root [ Writeable ]

 

Command :

[ Back ]     

Current File : /usr/share/doc/qemu-kvm/interop/vhost-user.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Vhost-user Protocol &#8212; QEMU 4.2.0 (qemu-kvm-4.2.0-34.module_el8.3.0+713+8ddc4ca0.4) documentation</title>
    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Vhost-user-gpu Protocol" href="vhost-user-gpu.html" />
    <link rel="prev" title="QEMU Guest Agent" href="qemu-ga.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="vhost-user-protocol">
<h1><a class="toc-backref" href="#id2">Vhost-user Protocol</a><a class="headerlink" href="#vhost-user-protocol" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Copyright:</th><td class="field-body">2014 Virtual Open Systems Sarl.</td>
</tr>
<tr class="field-even field"><th class="field-name">Licence:</th><td class="field-body">This work is licensed under the terms of the GNU GPL,
version 2 or later. See the COPYING file in the top-level
directory.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#vhost-user-protocol" id="id2">Vhost-user Protocol</a><ul>
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
<li><a class="reference internal" href="#message-specification" id="id4">Message Specification</a><ul>
<li><a class="reference internal" href="#header" id="id5">Header</a></li>
<li><a class="reference internal" href="#payload" id="id6">Payload</a><ul>
<li><a class="reference internal" href="#a-single-64-bit-integer" id="id7">A single 64-bit integer</a></li>
<li><a class="reference internal" href="#a-vring-state-description" id="id8">A vring state description</a></li>
<li><a class="reference internal" href="#a-vring-address-description" id="id9">A vring address description</a></li>
<li><a class="reference internal" href="#memory-regions-description" id="id10">Memory regions description</a></li>
<li><a class="reference internal" href="#log-description" id="id11">Log description</a></li>
<li><a class="reference internal" href="#an-iotlb-message" id="id12">An IOTLB message</a></li>
<li><a class="reference internal" href="#virtio-device-config-space" id="id13">Virtio device config space</a></li>
<li><a class="reference internal" href="#vring-area-description" id="id14">Vring area description</a></li>
<li><a class="reference internal" href="#inflight-description" id="id15">Inflight description</a></li>
</ul>
</li>
<li><a class="reference internal" href="#c-structure" id="id16">C structure</a></li>
</ul>
</li>
<li><a class="reference internal" href="#communication" id="id17">Communication</a><ul>
<li><a class="reference internal" href="#starting-and-stopping-rings" id="id18">Starting and stopping rings</a></li>
<li><a class="reference internal" href="#multiple-queue-support" id="id19">Multiple queue support</a></li>
<li><a class="reference internal" href="#migration" id="id20">Migration</a></li>
<li><a class="reference internal" href="#memory-access" id="id21">Memory access</a></li>
<li><a class="reference internal" href="#iommu-support" id="id22">IOMMU support</a></li>
<li><a class="reference internal" href="#slave-communication" id="id23">Slave communication</a></li>
<li><a class="reference internal" href="#inflight-i-o-tracking" id="id24">Inflight I/O tracking</a></li>
<li><a class="reference internal" href="#protocol-features" id="id25">Protocol features</a></li>
<li><a class="reference internal" href="#master-message-types" id="id26">Master message types</a></li>
<li><a class="reference internal" href="#slave-message-types" id="id27">Slave message types</a></li>
<li><a class="reference internal" href="#vhost-user-protocol-f-reply-ack" id="id28">VHOST_USER_PROTOCOL_F_REPLY_ACK</a></li>
</ul>
</li>
<li><a class="reference internal" href="#backend-program-conventions" id="id29">Backend program conventions</a><ul>
<li><a class="reference internal" href="#vhost-user-input" id="id30">vhost-user-input</a></li>
<li><a class="reference internal" href="#vhost-user-gpu" id="id31">vhost-user-gpu</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>This protocol is aiming to complement the <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> interface used to
control the vhost implementation in the Linux kernel. It implements
the control plane needed to establish virtqueue sharing with a user
space process on the same host. It uses communication over a Unix
domain socket to share file descriptors in the ancillary data of the
message.</p>
<p>The protocol defines 2 sides of the communication, <em>master</em> and
<em>slave</em>. <em>Master</em> is the application that shares its virtqueues, in
our case QEMU. <em>Slave</em> is the consumer of the virtqueues.</p>
<p>In the current implementation QEMU is the <em>master</em>, and the <em>slave</em> is
the external process consuming the virtio queues, for example a
software Ethernet switch running in user space, such as Snabbswitch,
or a block device backend processing read &amp; write to a virtual
disk. In order to facilitate interoperability between various backend
implementations, it is recommended to follow the <a class="reference internal" href="#backend-conventions"><span class="std std-ref">Backend program
conventions</span></a>.</p>
<p><em>Master</em> and <em>slave</em> can be either a client (i.e. connecting) or
server (listening) in the socket communication.</p>
</div>
<div class="section" id="message-specification">
<h2><a class="toc-backref" href="#id4">Message Specification</a><a class="headerlink" href="#message-specification" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">All numbers are in the machine native byte order.</p>
</div>
<p>A vhost-user message consists of 3 header fields and a payload.</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="23%" />
<col width="19%" />
<col width="29%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>request</td>
<td>flags</td>
<td>size</td>
<td>payload</td>
</tr>
</tbody>
</table>
<div class="section" id="header">
<h3><a class="toc-backref" href="#id5">Header</a><a class="headerlink" href="#header" title="Permalink to this headline">¶</a></h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">request:</th><td class="field-body">32-bit type of the request</td>
</tr>
<tr class="field-even field"><th class="field-name">flags:</th><td class="field-body">32-bit bit field</td>
</tr>
</tbody>
</table>
<ul class="simple">
<li>Lower 2 bits are the version (currently 0x01)</li>
<li>Bit 2 is the reply flag - needs to be sent on each reply from the slave</li>
<li>Bit 3 is the need_reply flag - see <a class="reference internal" href="#reply-ack"><span class="std std-ref">REPLY_ACK</span></a> for
details.</li>
</ul>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">size:</th><td class="field-body">32-bit size of the payload</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="payload">
<h3><a class="toc-backref" href="#id6">Payload</a><a class="headerlink" href="#payload" title="Permalink to this headline">¶</a></h3>
<p>Depending on the request type, <strong>payload</strong> can be:</p>
<div class="section" id="a-single-64-bit-integer">
<h4><a class="toc-backref" href="#id7">A single 64-bit integer</a><a class="headerlink" href="#a-single-64-bit-integer" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="100%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>u64</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">u64:</th><td class="field-body">a 64-bit unsigned integer</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="a-vring-state-description">
<h4><a class="toc-backref" href="#id8">A vring state description</a><a class="headerlink" href="#a-vring-state-description" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="58%" />
<col width="42%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>index</td>
<td>num</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">index:</th><td class="field-body">a 32-bit index</td>
</tr>
<tr class="field-even field"><th class="field-name">num:</th><td class="field-body">a 32-bit number</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="a-vring-address-description">
<h4><a class="toc-backref" href="#id9">A vring address description</a><a class="headerlink" href="#a-vring-address-description" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="13%" />
<col width="11%" />
<col width="22%" />
<col width="11%" />
<col width="20%" />
<col width="9%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>index</td>
<td>flags</td>
<td>size</td>
<td>descriptor</td>
<td>used</td>
<td>available</td>
<td>log</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">index:</th><td class="field-body">a 32-bit vring index</td>
</tr>
<tr class="field-even field"><th class="field-name">flags:</th><td class="field-body">a 32-bit vring flags</td>
</tr>
<tr class="field-odd field"><th class="field-name">descriptor:</th><td class="field-body">a 64-bit ring address of the vring descriptor table</td>
</tr>
<tr class="field-even field"><th class="field-name">used:</th><td class="field-body">a 64-bit ring address of the vring used ring</td>
</tr>
<tr class="field-odd field"><th class="field-name">available:</th><td class="field-body">a 64-bit ring address of the vring available ring</td>
</tr>
<tr class="field-even field"><th class="field-name">log:</th><td class="field-body">a 64-bit guest address for logging</td>
</tr>
</tbody>
</table>
<p>Note that a ring address is an IOVA if <code class="docutils literal notranslate"><span class="pre">VIRTIO_F_IOMMU_PLATFORM</span></code> has
been negotiated. Otherwise it is a user address.</p>
</div>
<div class="section" id="memory-regions-description">
<h4><a class="toc-backref" href="#id10">Memory regions description</a><a class="headerlink" href="#memory-regions-description" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="20%" />
<col width="20%" />
<col width="11%" />
<col width="20%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>num regions</td>
<td>padding</td>
<td>region0</td>
<td>…</td>
<td>region7</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">num regions:</th><td class="field-body">a 32-bit number of regions</td>
</tr>
<tr class="field-even field"><th class="field-name">padding:</th><td class="field-body">32-bit</td>
</tr>
</tbody>
</table>
<p>A region is:</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="13%" />
<col width="29%" />
<col width="27%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>guest address</td>
<td>size</td>
<td>user address</td>
<td>mmap offset</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">guest address:</th><td class="field-body">a 64-bit guest address of the region</td>
</tr>
<tr class="field-even field"><th class="field-name">size:</th><td class="field-body">a 64-bit size</td>
</tr>
<tr class="field-odd field"><th class="field-name">user address:</th><td class="field-body">a 64-bit user address</td>
</tr>
<tr class="field-even field"><th class="field-name">mmap offset:</th><td class="field-body">64-bit offset where region starts in the mapped memory</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="log-description">
<h4><a class="toc-backref" href="#id11">Log description</a><a class="headerlink" href="#log-description" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="45%" />
<col width="55%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>log size</td>
<td>log offset</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">log size:</th><td class="field-body">size of area used for logging</td>
</tr>
<tr class="field-even field"><th class="field-name">log offset:</th><td class="field-body">offset from start of supplied file descriptor where
logging starts (i.e. where guest address 0 would be
logged)</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="an-iotlb-message">
<h4><a class="toc-backref" href="#id12">An IOTLB message</a><a class="headerlink" href="#an-iotlb-message" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="12%" />
<col width="27%" />
<col width="37%" />
<col width="12%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>iova</td>
<td>size</td>
<td>user address</td>
<td>permissions flags</td>
<td>type</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">iova:</th><td class="field-body">a 64-bit I/O virtual address programmed by the guest</td>
</tr>
<tr class="field-even field"><th class="field-name">size:</th><td class="field-body">a 64-bit size</td>
</tr>
<tr class="field-odd field"><th class="field-name">user address:</th><td class="field-body">a 64-bit user address</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">permissions flags:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">an 8-bit value:
- 0: No access
- 1: Read access
- 2: Write access
- 3: Read/Write access</td>
</tr>
<tr class="field-odd field"><th class="field-name">type:</th><td class="field-body">an 8-bit IOTLB message type:
- 1: IOTLB miss
- 2: IOTLB update
- 3: IOTLB invalidate
- 4: IOTLB access fail</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="virtio-device-config-space">
<h4><a class="toc-backref" href="#id13">Virtio device config space</a><a class="headerlink" href="#virtio-device-config-space" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="20%" />
<col width="23%" />
<col width="30%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>offset</td>
<td>size</td>
<td>flags</td>
<td>payload</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">offset:</th><td class="field-body">a 32-bit offset of virtio device’s configuration space</td>
</tr>
<tr class="field-even field"><th class="field-name">size:</th><td class="field-body">a 32-bit configuration space access size in bytes</td>
</tr>
<tr class="field-odd field"><th class="field-name">flags:</th><td class="field-body">a 32-bit value:
- 0: Vhost master messages used for writeable fields
- 1: Vhost master messages used for live migration</td>
</tr>
<tr class="field-even field"><th class="field-name">payload:</th><td class="field-body">Size bytes array holding the contents of the virtio
device’s configuration space</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="vring-area-description">
<h4><a class="toc-backref" href="#id14">Vring area description</a><a class="headerlink" href="#vring-area-description" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="32%" />
<col width="42%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>u64</td>
<td>size</td>
<td>offset</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">u64:</th><td class="field-body">a 64-bit integer contains vring index and flags</td>
</tr>
<tr class="field-even field"><th class="field-name">size:</th><td class="field-body">a 64-bit size of this area</td>
</tr>
<tr class="field-odd field"><th class="field-name">offset:</th><td class="field-body">a 64-bit offset of this area from the start of the
supplied file descriptor</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="inflight-description">
<h4><a class="toc-backref" href="#id15">Inflight description</a><a class="headerlink" href="#inflight-description" title="Permalink to this headline">¶</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="27%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>mmap size</td>
<td>mmap offset</td>
<td>num queues</td>
<td>queue size</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">mmap size:</th><td class="field-body">a 64-bit size of area to track inflight I/O</td>
</tr>
<tr class="field-even field"><th class="field-name">mmap offset:</th><td class="field-body">a 64-bit offset of this area from the start
of the supplied file descriptor</td>
</tr>
<tr class="field-odd field"><th class="field-name">num queues:</th><td class="field-body">a 16-bit number of virtqueues</td>
</tr>
<tr class="field-even field"><th class="field-name">queue size:</th><td class="field-body">a 16-bit size of virtqueues</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="c-structure">
<h3><a class="toc-backref" href="#id16">C structure</a><a class="headerlink" href="#c-structure" title="Permalink to this headline">¶</a></h3>
<p>In QEMU the vhost-user message is implemented with the following struct:</p>
<div class="code c highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">typedef</span> <span class="n">struct</span> <span class="n">VhostUserMsg</span> <span class="p">{</span>
    <span class="n">VhostUserRequest</span> <span class="n">request</span><span class="p">;</span>
    <span class="n">uint32_t</span> <span class="n">flags</span><span class="p">;</span>
    <span class="n">uint32_t</span> <span class="n">size</span><span class="p">;</span>
    <span class="n">union</span> <span class="p">{</span>
        <span class="n">uint64_t</span> <span class="n">u64</span><span class="p">;</span>
        <span class="n">struct</span> <span class="n">vhost_vring_state</span> <span class="n">state</span><span class="p">;</span>
        <span class="n">struct</span> <span class="n">vhost_vring_addr</span> <span class="n">addr</span><span class="p">;</span>
        <span class="n">VhostUserMemory</span> <span class="n">memory</span><span class="p">;</span>
        <span class="n">VhostUserLog</span> <span class="n">log</span><span class="p">;</span>
        <span class="n">struct</span> <span class="n">vhost_iotlb_msg</span> <span class="n">iotlb</span><span class="p">;</span>
        <span class="n">VhostUserConfig</span> <span class="n">config</span><span class="p">;</span>
        <span class="n">VhostUserVringArea</span> <span class="n">area</span><span class="p">;</span>
        <span class="n">VhostUserInflight</span> <span class="n">inflight</span><span class="p">;</span>
    <span class="p">};</span>
<span class="p">}</span> <span class="n">QEMU_PACKED</span> <span class="n">VhostUserMsg</span><span class="p">;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="communication">
<h2><a class="toc-backref" href="#id17">Communication</a><a class="headerlink" href="#communication" title="Permalink to this headline">¶</a></h2>
<p>The protocol for vhost-user is based on the existing implementation of
vhost for the Linux Kernel. Most messages that can be sent via the
Unix domain socket implementing vhost-user have an equivalent ioctl to
the kernel implementation.</p>
<p>The communication consists of <em>master</em> sending message requests and
<em>slave</em> sending message replies. Most of the requests don’t require
replies. Here is a list of the ones that do:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_FEATURES</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_VRING_BASE</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_BASE</span></code> (if <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_LOG_SHMFD</span></code>)</li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_INFLIGHT_FD</span></code> (if <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD</span></code>)</li>
</ul>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="#reply-ack"><span class="std std-ref">REPLY_ACK</span></a></dt>
<dd>The section on <code class="docutils literal notranslate"><span class="pre">REPLY_ACK</span></code> protocol extension.</dd>
</dl>
</div>
<p>There are several messages that the master sends with file descriptors passed
in the ancillary data:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_MEM_TABLE</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_BASE</span></code> (if <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_LOG_SHMFD</span></code>)</li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_FD</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_KICK</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_CALL</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ERR</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_SLAVE_REQ_FD</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_INFLIGHT_FD</span></code> (if <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD</span></code>)</li>
</ul>
<p>If <em>master</em> is unable to send the full message or receives a wrong
reply it will close the connection. An optional reconnection mechanism
can be implemented.</p>
<p>Any protocol extensions are gated by protocol feature bits, which
allows full backwards compatibility on both master and slave.  As
older slaves don’t support negotiating protocol features, a feature
bit was dedicated for this purpose:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#define VHOST_USER_F_PROTOCOL_FEATURES 30</span>
</pre></div>
</div>
<div class="section" id="starting-and-stopping-rings">
<h3><a class="toc-backref" href="#id18">Starting and stopping rings</a><a class="headerlink" href="#starting-and-stopping-rings" title="Permalink to this headline">¶</a></h3>
<p>Client must only process each ring when it is started.</p>
<p>Client must only pass data between the ring and the backend, when the
ring is enabled.</p>
<p>If ring is started but disabled, client must process the ring without
talking to the backend.</p>
<p>For example, for a networking device, in the disabled state client
must not supply any new RX packets, but must process and discard any
TX packets.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> has not been negotiated, the
ring is initialized in an enabled state.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> has been negotiated, the ring is
initialized in a disabled state. Client must not pass data to/from the
backend until ring is enabled by <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ENABLE</span></code> with
parameter 1, or after it has been disabled by
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ENABLE</span></code> with parameter 0.</p>
<p>Each ring is initialized in a stopped state, client must not process
it until ring is started, or after it has been stopped.</p>
<p>Client must start ring upon receiving a kick (that is, detecting that
file descriptor is readable) on the descriptor specified by
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_KICK</span></code>, and stop ring upon receiving
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_VRING_BASE</span></code>.</p>
<p>While processing the rings (whether they are enabled or not), client
must support changing some configuration aspects on the fly.</p>
</div>
<div class="section" id="multiple-queue-support">
<h3><a class="toc-backref" href="#id19">Multiple queue support</a><a class="headerlink" href="#multiple-queue-support" title="Permalink to this headline">¶</a></h3>
<p>Many devices have a fixed number of virtqueues.  In this case the master
already knows the number of available virtqueues without communicating with the
slave.</p>
<p>Some devices do not have a fixed number of virtqueues.  Instead the maximum
number of virtqueues is chosen by the slave.  The number can depend on host
resource availability or slave implementation details.  Such devices are called
multiple queue devices.</p>
<p>Multiple queue support allows the slave to advertise the maximum number of
queues.  This is treated as a protocol extension, hence the slave has to
implement protocol features first. The multiple queues feature is supported
only when the protocol feature <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_MQ</span></code> (bit 0) is set.</p>
<p>The max number of queues the slave supports can be queried with message
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_QUEUE_NUM</span></code>. Master should stop when the number of requested
queues is bigger than that.</p>
<p>As all queues share one connection, the master uses a unique index for each
queue in the sent message to identify a specified queue.</p>
<p>The master enables queues by sending message <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ENABLE</span></code>.
vhost-user-net has historically automatically enabled the first queue pair.</p>
<p>Slaves should always implement the <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_MQ</span></code> protocol
feature, even for devices with a fixed number of virtqueues, since it is simple
to implement and offers a degree of introspection.</p>
<p>Masters must not rely on the <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_MQ</span></code> protocol feature for
devices with a fixed number of virtqueues.  Only true multiqueue devices
require this protocol feature.</p>
</div>
<div class="section" id="migration">
<h3><a class="toc-backref" href="#id20">Migration</a><a class="headerlink" href="#migration" title="Permalink to this headline">¶</a></h3>
<p>During live migration, the master may need to track the modifications
the slave makes to the memory mapped regions. The client should mark
the dirty pages in a log. Once it complies to this logging, it may
declare the <code class="docutils literal notranslate"><span class="pre">VHOST_F_LOG_ALL</span></code> vhost feature.</p>
<p>To start/stop logging of data/used ring writes, server may send
messages <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_FEATURES</span></code> with <code class="docutils literal notranslate"><span class="pre">VHOST_F_LOG_ALL</span></code> and
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ADDR</span></code> with <code class="docutils literal notranslate"><span class="pre">VHOST_VRING_F_LOG</span></code> in ring’s
flags set to 1/0, respectively.</p>
<p>All the modifications to memory pointed by vring “descriptor” should
be marked. Modifications to “used” vring should be marked if
<code class="docutils literal notranslate"><span class="pre">VHOST_VRING_F_LOG</span></code> is part of ring’s flags.</p>
<p>Dirty pages are of size:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#define VHOST_LOG_PAGE 0x1000</span>
</pre></div>
</div>
<p>The log memory fd is provided in the ancillary data of
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_BASE</span></code> message when the slave has
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_LOG_SHMFD</span></code> protocol feature.</p>
<p>The size of the log is supplied as part of <code class="docutils literal notranslate"><span class="pre">VhostUserMsg</span></code> which
should be large enough to cover all known guest addresses. Log starts
at the supplied offset in the supplied file descriptor.  The log
covers from address 0 to the maximum of guest regions. In pseudo-code,
to mark page at <code class="docutils literal notranslate"><span class="pre">addr</span></code> as dirty:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">page</span> <span class="o">=</span> <span class="n">addr</span> <span class="o">/</span> <span class="n">VHOST_LOG_PAGE</span>
<span class="n">log</span><span class="p">[</span><span class="n">page</span> <span class="o">/</span> <span class="mi">8</span><span class="p">]</span> <span class="o">|=</span> <span class="mi">1</span> <span class="o">&lt;&lt;</span> <span class="n">page</span> <span class="o">%</span> <span class="mi">8</span>
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">addr</span></code> is the guest physical address.</p>
<p>Use atomic operations, as the log may be concurrently manipulated.</p>
<p>Note that when logging modifications to the used ring (when
<code class="docutils literal notranslate"><span class="pre">VHOST_VRING_F_LOG</span></code> is set for this ring), <code class="docutils literal notranslate"><span class="pre">log_guest_addr</span></code> should
be used to calculate the log offset: the write to first byte of the
used ring is logged at this offset from log start. Also note that this
value might be outside the legal guest physical address range
(i.e. does not have to be covered by the <code class="docutils literal notranslate"><span class="pre">VhostUserMemory</span></code> table), but
the bit offset of the last byte of the ring must fall within the size
supplied by <code class="docutils literal notranslate"><span class="pre">VhostUserLog</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_FD</span></code> is an optional message with an eventfd in
ancillary data, it may be used to inform the master that the log has
been modified.</p>
<p>Once the source has finished migration, rings will be stopped by the
source. No further update must be done before rings are restarted.</p>
<p>In postcopy migration the slave is started before all the memory has
been received from the source host, and care must be taken to avoid
accessing pages that have yet to be received.  The slave opens a
‘userfault’-fd and registers the memory with it; this fd is then
passed back over to the master.  The master services requests on the
userfaultfd for pages that are accessed and when the page is available
it performs WAKE ioctl’s on the userfaultfd to wake the stalled
slave.  The client indicates support for this via the
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_PAGEFAULT</span></code> feature.</p>
</div>
<div class="section" id="memory-access">
<h3><a class="toc-backref" href="#id21">Memory access</a><a class="headerlink" href="#memory-access" title="Permalink to this headline">¶</a></h3>
<p>The master sends a list of vhost memory regions to the slave using the
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_MEM_TABLE</span></code> message.  Each region has two base
addresses: a guest address and a user address.</p>
<p>Messages contain guest addresses and/or user addresses to reference locations
within the shared memory.  The mapping of these addresses works as follows.</p>
<p>User addresses map to the vhost memory region containing that user address.</p>
<p>When the <code class="docutils literal notranslate"><span class="pre">VIRTIO_F_IOMMU_PLATFORM</span></code> feature has not been negotiated:</p>
<ul class="simple">
<li>Guest addresses map to the vhost memory region containing that guest
address.</li>
</ul>
<p>When the <code class="docutils literal notranslate"><span class="pre">VIRTIO_F_IOMMU_PLATFORM</span></code> feature has been negotiated:</p>
<ul class="simple">
<li>Guest addresses are also called I/O virtual addresses (IOVAs).  They are
translated to user addresses via the IOTLB.</li>
<li>The vhost memory region guest address is not used.</li>
</ul>
</div>
<div class="section" id="iommu-support">
<h3><a class="toc-backref" href="#id22">IOMMU support</a><a class="headerlink" href="#iommu-support" title="Permalink to this headline">¶</a></h3>
<p>When the <code class="docutils literal notranslate"><span class="pre">VIRTIO_F_IOMMU_PLATFORM</span></code> feature has been negotiated, the
master sends IOTLB entries update &amp; invalidation by sending
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_IOTLB_MSG</span></code> requests to the slave with a <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">vhost_iotlb_msg</span></code> as payload. For update events, the <code class="docutils literal notranslate"><span class="pre">iotlb</span></code> payload
has to be filled with the update message type (2), the I/O virtual
address, the size, the user virtual address, and the permissions
flags. Addresses and size must be within vhost memory regions set via
the <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_MEM_TABLE</span></code> request. For invalidation events, the
<code class="docutils literal notranslate"><span class="pre">iotlb</span></code> payload has to be filled with the invalidation message type
(3), the I/O virtual address and the size. On success, the slave is
expected to reply with a zero payload, non-zero otherwise.</p>
<p>The slave relies on the slave communcation channel (see <a class="reference internal" href="#slave-communication"><span class="std std-ref">Slave
communication</span></a> section below) to send IOTLB miss
and access failure events, by sending <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SLAVE_IOTLB_MSG</span></code>
requests to the master with a <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vhost_iotlb_msg</span></code> as
payload. For miss events, the iotlb payload has to be filled with the
miss message type (1), the I/O virtual address and the permissions
flags. For access failure event, the iotlb payload has to be filled
with the access failure message type (4), the I/O virtual address and
the permissions flags.  For synchronization purpose, the slave may
rely on the reply-ack feature, so the master may send a reply when
operation is completed if the reply-ack feature is negotiated and
slaves requests a reply. For miss events, completed operation means
either master sent an update message containing the IOTLB entry
containing requested address and permission, or master sent nothing if
the IOTLB miss message is invalid (invalid IOVA or permission).</p>
<p>The master isn’t expected to take the initiative to send IOTLB update
messages, as the slave sends IOTLB miss messages for the guest virtual
memory areas it needs to access.</p>
</div>
<div class="section" id="slave-communication">
<span id="id1"></span><h3><a class="toc-backref" href="#id23">Slave communication</a><a class="headerlink" href="#slave-communication" title="Permalink to this headline">¶</a></h3>
<p>An optional communication channel is provided if the slave declares
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_SLAVE_REQ</span></code> protocol feature, to allow the
slave to make requests to the master.</p>
<p>The fd is provided via <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_SLAVE_REQ_FD</span></code> ancillary data.</p>
<p>A slave may then send <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SLAVE_*</span></code> messages to the master
using this fd communication channel.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD</span></code> protocol feature is
negotiated, slave can send file descriptors (at most 8 descriptors in
each message) to master via ancillary data using this fd communication
channel.</p>
</div>
<div class="section" id="inflight-i-o-tracking">
<h3><a class="toc-backref" href="#id24">Inflight I/O tracking</a><a class="headerlink" href="#inflight-i-o-tracking" title="Permalink to this headline">¶</a></h3>
<p>To support reconnecting after restart or crash, slave may need to
resubmit inflight I/Os. If virtqueue is processed in order, we can
easily achieve that by getting the inflight descriptors from
descriptor table (split virtqueue) or descriptor ring (packed
virtqueue). However, it can’t work when we process descriptors
out-of-order because some entries which store the information of
inflight descriptors in available ring (split virtqueue) or descriptor
ring (packed virtqueue) might be overrided by new entries. To solve
this problem, slave need to allocate an extra buffer to store this
information of inflight descriptors and share it with master for
persistent. <code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_INFLIGHT_FD</span></code> and
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_INFLIGHT_FD</span></code> are used to transfer this buffer
between master and slave. And the format of this buffer is described
below:</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="30%" />
<col width="10%" />
<col width="30%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>queue0 region</td>
<td>queue1 region</td>
<td>…</td>
<td>queueN region</td>
</tr>
</tbody>
</table>
<p>N is the number of available virtqueues. Slave could get it from num
queues field of <code class="docutils literal notranslate"><span class="pre">VhostUserInflight</span></code>.</p>
<p>For split virtqueue, queue region can be implemented as:</p>
<div class="code c highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">typedef</span> <span class="n">struct</span> <span class="n">DescStateSplit</span> <span class="p">{</span>
    <span class="o">/*</span> <span class="n">Indicate</span> <span class="n">whether</span> <span class="n">this</span> <span class="n">descriptor</span> <span class="ow">is</span> <span class="n">inflight</span> <span class="ow">or</span> <span class="ow">not</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">head</span><span class="o">-</span><span class="n">descriptor</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">inflight</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Padding</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">padding</span><span class="p">[</span><span class="mi">5</span><span class="p">];</span>

    <span class="o">/*</span> <span class="n">Maintain</span> <span class="n">a</span> <span class="nb">list</span> <span class="k">for</span> <span class="n">the</span> <span class="n">last</span> <span class="n">batch</span> <span class="n">of</span> <span class="n">used</span> <span class="n">descriptors</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="n">when</span> <span class="n">batching</span> <span class="ow">is</span> <span class="n">used</span> <span class="k">for</span> <span class="n">submitting</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="nb">next</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Used</span> <span class="n">to</span> <span class="n">preserve</span> <span class="n">the</span> <span class="n">order</span> <span class="n">of</span> <span class="n">fetching</span> <span class="n">available</span> <span class="n">descriptors</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">head</span><span class="o">-</span><span class="n">descriptor</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint64_t</span> <span class="n">counter</span><span class="p">;</span>
<span class="p">}</span> <span class="n">DescStateSplit</span><span class="p">;</span>

<span class="n">typedef</span> <span class="n">struct</span> <span class="n">QueueRegionSplit</span> <span class="p">{</span>
    <span class="o">/*</span> <span class="n">The</span> <span class="n">feature</span> <span class="n">flags</span> <span class="n">of</span> <span class="n">this</span> <span class="n">region</span><span class="o">.</span> <span class="n">Now</span> <span class="n">it</span><span class="s1">&#39;s initialized to 0. */</span>
    <span class="n">uint64_t</span> <span class="n">features</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">version</span> <span class="n">of</span> <span class="n">this</span> <span class="n">region</span><span class="o">.</span> <span class="n">It</span><span class="s1">&#39;s 1 currently.</span>
     <span class="o">*</span> <span class="n">Zero</span> <span class="n">value</span> <span class="n">indicates</span> <span class="n">an</span> <span class="n">uninitialized</span> <span class="n">buffer</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">version</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">size</span> <span class="n">of</span> <span class="n">DescStateSplit</span> <span class="n">array</span><span class="o">.</span> <span class="n">It</span><span class="s1">&#39;s equal to the virtqueue</span>
     <span class="o">*</span> <span class="n">size</span><span class="o">.</span> <span class="n">Slave</span> <span class="n">could</span> <span class="n">get</span> <span class="n">it</span> <span class="kn">from</span> <span class="nn">queue</span> <span class="n">size</span> <span class="n">field</span> <span class="n">of</span> <span class="n">VhostUserInflight</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">desc_num</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">head</span> <span class="n">of</span> <span class="nb">list</span> <span class="n">that</span> <span class="n">track</span> <span class="n">the</span> <span class="n">last</span> <span class="n">batch</span> <span class="n">of</span> <span class="n">used</span> <span class="n">descriptors</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">last_batch_head</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Store</span> <span class="n">the</span> <span class="n">idx</span> <span class="n">value</span> <span class="n">of</span> <span class="n">used</span> <span class="n">ring</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">used_idx</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Used</span> <span class="n">to</span> <span class="n">track</span> <span class="n">the</span> <span class="n">state</span> <span class="n">of</span> <span class="n">each</span> <span class="n">descriptor</span> <span class="ow">in</span> <span class="n">descriptor</span> <span class="n">table</span> <span class="o">*/</span>
    <span class="n">DescStateSplit</span> <span class="n">desc</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="p">}</span> <span class="n">QueueRegionSplit</span><span class="p">;</span>
</pre></div>
</div>
<p>To track inflight I/O, the queue region should be processed as follows:</p>
<p>When receiving available buffers from the driver:</p>
<ol class="arabic simple">
<li>Get the next available head-descriptor index from available ring, <code class="docutils literal notranslate"><span class="pre">i</span></code></li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[i].counter</span></code> to the value of global counter</li>
<li>Increase global counter by 1</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[i].inflight</span></code> to 1</li>
</ol>
<p>When supplying used buffers to the driver:</p>
<ol class="arabic simple">
<li>Get corresponding used head-descriptor index, i</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[i].next</span></code> to <code class="docutils literal notranslate"><span class="pre">last_batch_head</span></code></li>
<li>Set <code class="docutils literal notranslate"><span class="pre">last_batch_head</span></code> to <code class="docutils literal notranslate"><span class="pre">i</span></code></li>
<li>Steps 1,2,3 may be performed repeatedly if batching is possible</li>
<li>Increase the <code class="docutils literal notranslate"><span class="pre">idx</span></code> value of used ring by the size of the batch</li>
<li>Set the <code class="docutils literal notranslate"><span class="pre">inflight</span></code> field of each <code class="docutils literal notranslate"><span class="pre">DescStateSplit</span></code> entry in the batch to 0</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">used_idx</span></code> to the <code class="docutils literal notranslate"><span class="pre">idx</span></code> value of used ring</li>
</ol>
<p>When reconnecting:</p>
<ol class="arabic simple">
<li>If the value of <code class="docutils literal notranslate"><span class="pre">used_idx</span></code> does not match the <code class="docutils literal notranslate"><span class="pre">idx</span></code> value of
used ring (means the inflight field of <code class="docutils literal notranslate"><span class="pre">DescStateSplit</span></code> entries in
last batch may be incorrect),<ol class="loweralpha">
<li>Subtract the value of <code class="docutils literal notranslate"><span class="pre">used_idx</span></code> from the <code class="docutils literal notranslate"><span class="pre">idx</span></code> value of
used ring to get last batch size of <code class="docutils literal notranslate"><span class="pre">DescStateSplit</span></code> entries</li>
<li>Set the <code class="docutils literal notranslate"><span class="pre">inflight</span></code> field of each <code class="docutils literal notranslate"><span class="pre">DescStateSplit</span></code> entry to 0 in last batch
list which starts from <code class="docutils literal notranslate"><span class="pre">last_batch_head</span></code></li>
<li>Set <code class="docutils literal notranslate"><span class="pre">used_idx</span></code> to the <code class="docutils literal notranslate"><span class="pre">idx</span></code> value of used ring</li>
</ol>
</li>
<li>Resubmit inflight <code class="docutils literal notranslate"><span class="pre">DescStateSplit</span></code> entries in order of their
counter value</li>
</ol>
<p>For packed virtqueue, queue region can be implemented as:</p>
<div class="code c highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">typedef</span> <span class="n">struct</span> <span class="n">DescStatePacked</span> <span class="p">{</span>
    <span class="o">/*</span> <span class="n">Indicate</span> <span class="n">whether</span> <span class="n">this</span> <span class="n">descriptor</span> <span class="ow">is</span> <span class="n">inflight</span> <span class="ow">or</span> <span class="ow">not</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">head</span><span class="o">-</span><span class="n">descriptor</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">inflight</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Padding</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">padding</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Link</span> <span class="n">to</span> <span class="n">the</span> <span class="nb">next</span> <span class="n">free</span> <span class="n">entry</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="nb">next</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Link</span> <span class="n">to</span> <span class="n">the</span> <span class="n">last</span> <span class="n">entry</span> <span class="n">of</span> <span class="n">descriptor</span> <span class="nb">list</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">head</span><span class="o">-</span><span class="n">descriptor</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">last</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">length</span> <span class="n">of</span> <span class="n">descriptor</span> <span class="nb">list</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">head</span><span class="o">-</span><span class="n">descriptor</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">num</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Used</span> <span class="n">to</span> <span class="n">preserve</span> <span class="n">the</span> <span class="n">order</span> <span class="n">of</span> <span class="n">fetching</span> <span class="n">available</span> <span class="n">descriptors</span><span class="o">.</span>
     <span class="o">*</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">head</span><span class="o">-</span><span class="n">descriptor</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint64_t</span> <span class="n">counter</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">buffer</span> <span class="nb">id</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="nb">id</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">descriptor</span> <span class="n">flags</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">flags</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">buffer</span> <span class="n">length</span> <span class="o">*/</span>
    <span class="n">uint32_t</span> <span class="nb">len</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">buffer</span> <span class="n">address</span> <span class="o">*/</span>
    <span class="n">uint64_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="p">}</span> <span class="n">DescStatePacked</span><span class="p">;</span>

<span class="n">typedef</span> <span class="n">struct</span> <span class="n">QueueRegionPacked</span> <span class="p">{</span>
    <span class="o">/*</span> <span class="n">The</span> <span class="n">feature</span> <span class="n">flags</span> <span class="n">of</span> <span class="n">this</span> <span class="n">region</span><span class="o">.</span> <span class="n">Now</span> <span class="n">it</span><span class="s1">&#39;s initialized to 0. */</span>
    <span class="n">uint64_t</span> <span class="n">features</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">version</span> <span class="n">of</span> <span class="n">this</span> <span class="n">region</span><span class="o">.</span> <span class="n">It</span><span class="s1">&#39;s 1 currently.</span>
     <span class="o">*</span> <span class="n">Zero</span> <span class="n">value</span> <span class="n">indicates</span> <span class="n">an</span> <span class="n">uninitialized</span> <span class="n">buffer</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">version</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">size</span> <span class="n">of</span> <span class="n">DescStatePacked</span> <span class="n">array</span><span class="o">.</span> <span class="n">It</span><span class="s1">&#39;s equal to the virtqueue</span>
     <span class="o">*</span> <span class="n">size</span><span class="o">.</span> <span class="n">Slave</span> <span class="n">could</span> <span class="n">get</span> <span class="n">it</span> <span class="kn">from</span> <span class="nn">queue</span> <span class="n">size</span> <span class="n">field</span> <span class="n">of</span> <span class="n">VhostUserInflight</span><span class="o">.</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">desc_num</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">head</span> <span class="n">of</span> <span class="n">free</span> <span class="n">DescStatePacked</span> <span class="n">entry</span> <span class="nb">list</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">free_head</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">old</span> <span class="n">head</span> <span class="n">of</span> <span class="n">free</span> <span class="n">DescStatePacked</span> <span class="n">entry</span> <span class="nb">list</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">old_free_head</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">used</span> <span class="n">index</span> <span class="n">of</span> <span class="n">descriptor</span> <span class="n">ring</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">used_idx</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">old</span> <span class="n">used</span> <span class="n">index</span> <span class="n">of</span> <span class="n">descriptor</span> <span class="n">ring</span> <span class="o">*/</span>
    <span class="n">uint16_t</span> <span class="n">old_used_idx</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Device</span> <span class="n">ring</span> <span class="n">wrap</span> <span class="n">counter</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">used_wrap_counter</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">The</span> <span class="n">old</span> <span class="n">device</span> <span class="n">ring</span> <span class="n">wrap</span> <span class="n">counter</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">old_used_wrap_counter</span><span class="p">;</span>

    <span class="o">/*</span> <span class="n">Padding</span> <span class="o">*/</span>
    <span class="n">uint8_t</span> <span class="n">padding</span><span class="p">[</span><span class="mi">7</span><span class="p">];</span>

    <span class="o">/*</span> <span class="n">Used</span> <span class="n">to</span> <span class="n">track</span> <span class="n">the</span> <span class="n">state</span> <span class="n">of</span> <span class="n">each</span> <span class="n">descriptor</span> <span class="n">fetched</span> <span class="kn">from</span> <span class="nn">descriptor</span> <span class="n">ring</span> <span class="o">*/</span>
    <span class="n">DescStatePacked</span> <span class="n">desc</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="p">}</span> <span class="n">QueueRegionPacked</span><span class="p">;</span>
</pre></div>
</div>
<p>To track inflight I/O, the queue region should be processed as follows:</p>
<p>When receiving available buffers from the driver:</p>
<ol class="arabic simple">
<li>Get the next available descriptor entry from descriptor ring, <code class="docutils literal notranslate"><span class="pre">d</span></code></li>
<li>If <code class="docutils literal notranslate"><span class="pre">d</span></code> is head descriptor,<ol class="loweralpha">
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[old_free_head].num</span></code> to 0</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[old_free_head].counter</span></code> to the value of global counter</li>
<li>Increase global counter by 1</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[old_free_head].inflight</span></code> to 1</li>
</ol>
</li>
<li>If <code class="docutils literal notranslate"><span class="pre">d</span></code> is last descriptor, set <code class="docutils literal notranslate"><span class="pre">desc[old_free_head].last</span></code> to
<code class="docutils literal notranslate"><span class="pre">free_head</span></code></li>
<li>Increase <code class="docutils literal notranslate"><span class="pre">desc[old_free_head].num</span></code> by 1</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[free_head].addr</span></code>, <code class="docutils literal notranslate"><span class="pre">desc[free_head].len</span></code>,
<code class="docutils literal notranslate"><span class="pre">desc[free_head].flags</span></code>, <code class="docutils literal notranslate"><span class="pre">desc[free_head].id</span></code> to <code class="docutils literal notranslate"><span class="pre">d.addr</span></code>,
<code class="docutils literal notranslate"><span class="pre">d.len</span></code>, <code class="docutils literal notranslate"><span class="pre">d.flags</span></code>, <code class="docutils literal notranslate"><span class="pre">d.id</span></code></li>
<li>Set <code class="docutils literal notranslate"><span class="pre">free_head</span></code> to <code class="docutils literal notranslate"><span class="pre">desc[free_head].next</span></code></li>
<li>If <code class="docutils literal notranslate"><span class="pre">d</span></code> is last descriptor, set <code class="docutils literal notranslate"><span class="pre">old_free_head</span></code> to <code class="docutils literal notranslate"><span class="pre">free_head</span></code></li>
</ol>
<p>When supplying used buffers to the driver:</p>
<ol class="arabic simple">
<li>Get corresponding used head-descriptor entry from descriptor ring,
<code class="docutils literal notranslate"><span class="pre">d</span></code></li>
<li>Get corresponding <code class="docutils literal notranslate"><span class="pre">DescStatePacked</span></code> entry, <code class="docutils literal notranslate"><span class="pre">e</span></code></li>
<li>Set <code class="docutils literal notranslate"><span class="pre">desc[e.last].next</span></code> to <code class="docutils literal notranslate"><span class="pre">free_head</span></code></li>
<li>Set <code class="docutils literal notranslate"><span class="pre">free_head</span></code> to the index of <code class="docutils literal notranslate"><span class="pre">e</span></code></li>
<li>Steps 1,2,3,4 may be performed repeatedly if batching is possible</li>
<li>Increase <code class="docutils literal notranslate"><span class="pre">used_idx</span></code> by the size of the batch and update
<code class="docutils literal notranslate"><span class="pre">used_wrap_counter</span></code> if needed</li>
<li>Update <code class="docutils literal notranslate"><span class="pre">d.flags</span></code></li>
<li>Set the <code class="docutils literal notranslate"><span class="pre">inflight</span></code> field of each head <code class="docutils literal notranslate"><span class="pre">DescStatePacked</span></code> entry
in the batch to 0</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">old_free_head</span></code>,  <code class="docutils literal notranslate"><span class="pre">old_used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">old_used_wrap_counter</span></code>
to <code class="docutils literal notranslate"><span class="pre">free_head</span></code>, <code class="docutils literal notranslate"><span class="pre">used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">used_wrap_counter</span></code></li>
</ol>
<p>When reconnecting:</p>
<ol class="arabic simple">
<li>If <code class="docutils literal notranslate"><span class="pre">used_idx</span></code> does not match <code class="docutils literal notranslate"><span class="pre">old_used_idx</span></code> (means the
<code class="docutils literal notranslate"><span class="pre">inflight</span></code> field of <code class="docutils literal notranslate"><span class="pre">DescStatePacked</span></code> entries in last batch may
be incorrect),<ol class="loweralpha">
<li>Get the next descriptor ring entry through <code class="docutils literal notranslate"><span class="pre">old_used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">d</span></code></li>
<li>Use <code class="docutils literal notranslate"><span class="pre">old_used_wrap_counter</span></code> to calculate the available flags</li>
<li>If <code class="docutils literal notranslate"><span class="pre">d.flags</span></code> is not equal to the calculated flags value (means
slave has submitted the buffer to guest driver before crash, so
it has to commit the in-progres update), set <code class="docutils literal notranslate"><span class="pre">old_free_head</span></code>,
<code class="docutils literal notranslate"><span class="pre">old_used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">old_used_wrap_counter</span></code> to <code class="docutils literal notranslate"><span class="pre">free_head</span></code>,
<code class="docutils literal notranslate"><span class="pre">used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">used_wrap_counter</span></code></li>
</ol>
</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">free_head</span></code>, <code class="docutils literal notranslate"><span class="pre">used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">used_wrap_counter</span></code> to
<code class="docutils literal notranslate"><span class="pre">old_free_head</span></code>, <code class="docutils literal notranslate"><span class="pre">old_used_idx</span></code>, <code class="docutils literal notranslate"><span class="pre">old_used_wrap_counter</span></code>
(roll back any in-progress update)</li>
<li>Set the <code class="docutils literal notranslate"><span class="pre">inflight</span></code> field of each <code class="docutils literal notranslate"><span class="pre">DescStatePacked</span></code> entry in
free list to 0</li>
<li>Resubmit inflight <code class="docutils literal notranslate"><span class="pre">DescStatePacked</span></code> entries in order of their
counter value</li>
</ol>
</div>
<div class="section" id="protocol-features">
<h3><a class="toc-backref" href="#id25">Protocol features</a><a class="headerlink" href="#protocol-features" title="Permalink to this headline">¶</a></h3>
<div class="code c highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#define VHOST_USER_PROTOCOL_F_MQ             0</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_LOG_SHMFD      1</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_RARP           2</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_REPLY_ACK      3</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_MTU            4</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_SLAVE_REQ      5</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_CROSS_ENDIAN   6</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_PAGEFAULT      8</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_CONFIG         9</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD  10</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER  11</span>
<span class="c1">#define VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD 12</span>
</pre></div>
</div>
</div>
<div class="section" id="master-message-types">
<h3><a class="toc-backref" href="#id26">Master message types</a><a class="headerlink" href="#master-message-types" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_FEATURES</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">1</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_GET_FEATURES</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p class="last">Get from the underlying vhost implementation the features bitmask.
Feature bit <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> signals slave support
for <code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code> and
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_PROTOCOL_FEATURES</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_FEATURES</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">2</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_FEATURES</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p class="last">Enable features in the underlying vhost implementation using a
bitmask.  Feature bit <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> signals
slave support for <code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code> and
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_PROTOCOL_FEATURES</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">15</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_GET_FEATURES</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p class="last">Get the protocol feature bitmask from the underlying vhost
implementation.  Only legal if feature bit
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> is present in
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_FEATURES</span></code>.</p>
</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Slave that reported <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> must
support this message even before <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_FEATURES</span></code> was
called.</p>
</div>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_PROTOCOL_FEATURES</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">16</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_FEATURES</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Enable protocol features in the underlying vhost implementation.</p>
<p class="last">Only legal if feature bit <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> is present in
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_FEATURES</span></code>.</p>
</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Slave that reported <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> must support
this message even before <code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_FEATURES</span></code> was called.</p>
</div>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_OWNER</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">3</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_OWNER</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">Issued when a new connection is established. It sets the current
<em>master</em> as an owner of the session. This can be used on the <em>slave</em>
as a “session start” flag.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_RESET_OWNER</span></code></dt>
<dd><table class="first last docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">4</td>
</tr>
<tr class="field-even field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
</dd>
</dl>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p class="last">This is no longer used. Used to be sent to request disabling all
rings, but some clients interpreted it to also discard connection
state (this interpretation would lead to bugs).  It is recommended
that clients either ignore this message, or use it to disable all
rings.</p>
</div>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_MEM_TABLE</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">5</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_MEM_TABLE</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">memory regions description</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">(postcopy only) memory regions description</td>
</tr>
</tbody>
</table>
<p>Sets the memory map regions on the slave so it can translate the
vring addresses. In the ancillary data there is an array of file
descriptors for each memory mapped region. The size and ordering of
the fds matches the number and ordering of memory regions.</p>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_POSTCOPY_LISTEN</span></code> has been received,
<code class="docutils literal notranslate"><span class="pre">SET_MEM_TABLE</span></code> replies with the bases of the memory mapped
regions to the master.  The slave must have mmap’d the regions but
not yet accessed them and should not yet generate a userfault
event.</p>
</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal notranslate"><span class="pre">NEED_REPLY_MASK</span></code> is not set in this case.  QEMU will then
reply back to the list of mappings with an empty
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_MEM_TABLE</span></code> as an acknowledgement; only upon
reception of this message may the guest start accessing the memory
and generating faults.</p>
</div>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_BASE</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">6</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_LOG_BASE</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">u64</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p>Sets logging shared memory space.</p>
<p class="last">When slave has <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_LOG_SHMFD</span></code> protocol feature,
the log memory fd is provided in the ancillary data of
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_BASE</span></code> message, the size and offset of shared
memory area provided in the message.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_LOG_FD</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">7</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_LOG_FD</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">Sets the logging file descriptor, which is passed as ancillary data.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_NUM</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">8</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_NUM</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">vring state description</td>
</tr>
</tbody>
</table>
<p class="last">Set the size of the queue.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ADDR</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">9</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_ADDR</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">vring address description</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">Sets the addresses of the different aspects of the vring.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_BASE</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">10</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_BASE</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">vring state description</td>
</tr>
</tbody>
</table>
<p class="last">Sets the base offset in the available vring.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_VRING_BASE</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">11</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_VRING_BASE</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">vring state description</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">vring state description</td>
</tr>
</tbody>
</table>
<p class="last">Get the available vring base offset.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_KICK</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">12</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_KICK</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Set the event file descriptor for adding buffers to the vring. It is
passed in the ancillary data.</p>
<p class="last">Bits (0-7) of the payload contain the vring index. Bit 8 is the
invalid FD flag. This flag is set when there is no file descriptor
in the ancillary data. This signals that polling should be used
instead of waiting for a kick.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_CALL</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">13</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_CALL</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Set the event file descriptor to signal when buffers are used. It is
passed in the ancillary data.</p>
<p class="last">Bits (0-7) of the payload contain the vring index. Bit 8 is the
invalid FD flag. This flag is set when there is no file descriptor
in the ancillary data. This signals that polling will be used
instead of waiting for the call.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ERR</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">14</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_ERR</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Set the event file descriptor to signal when error occurs. It is
passed in the ancillary data.</p>
<p class="last">Bits (0-7) of the payload contain the vring index. Bit 8 is the
invalid FD flag. This flag is set when there is no file descriptor
in the ancillary data.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_QUEUE_NUM</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">17</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">u64</td>
</tr>
</tbody>
</table>
<p>Query how many queues the backend supports.</p>
<p class="last">This request should be sent only when <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_MQ</span></code>
is set in queried protocol features by
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ENABLE</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">18</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">vring state description</td>
</tr>
</tbody>
</table>
<p>Signal slave to enable or disable corresponding vring.</p>
<p class="last">This request should be sent only when
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> has been negotiated.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SEND_RARP</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">19</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Ask vhost user backend to broadcast a fake RARP to notify the migration
is terminated for guest that does not support GUEST_ANNOUNCE.</p>
<p class="last">Only legal if feature bit <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> is
present in <code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_FEATURES</span></code> and protocol feature bit
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_RARP</span></code> is present in
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code>.  The first 6 bytes of the
payload contain the mac address of the guest to allow the vhost user
backend to construct and broadcast the fake RARP.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_NET_SET_MTU</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">20</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Set host MTU value exposed to the guest.</p>
<p>This request should be sent only when <code class="docutils literal notranslate"><span class="pre">VIRTIO_NET_F_MTU</span></code> feature
has been successfully negotiated, <code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code>
is present in <code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_FEATURES</span></code> and protocol feature bit
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_NET_MTU</span></code> is present in
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code>.</p>
<p class="last">If <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_REPLY_ACK</span></code> is negotiated, slave must
respond with zero in case the specified MTU is valid, or non-zero
otherwise.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_SLAVE_REQ_FD</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">21</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p>Set the socket file descriptor for slave initiated requests. It is passed
in the ancillary data.</p>
<p class="last">This request should be sent only when
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_F_PROTOCOL_FEATURES</span></code> has been negotiated, and protocol
feature bit <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_SLAVE_REQ</span></code> bit is present in
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_PROTOCOL_FEATURES</span></code>.  If
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_REPLY_ACK</span></code> is negotiated, slave must
respond with zero for success, non-zero otherwise.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_IOTLB_MSG</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">22</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A (equivalent to <code class="docutils literal notranslate"><span class="pre">VHOST_IOTLB_MSG</span></code> message type)</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vhost_iotlb_msg</span></code></td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Send IOTLB messages with <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vhost_iotlb_msg</span></code> as payload.</p>
<p>Master sends such requests to update and invalidate entries in the
device IOTLB. The slave has to acknowledge the request with sending
zero as <code class="docutils literal notranslate"><span class="pre">u64</span></code> payload for success, non-zero otherwise.</p>
<p class="last">This request should be send only when <code class="docutils literal notranslate"><span class="pre">VIRTIO_F_IOMMU_PLATFORM</span></code>
feature has been successfully negotiated.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_VRING_ENDIAN</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">23</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body"><code class="docutils literal notranslate"><span class="pre">VHOST_SET_VRING_ENDIAN</span></code></td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">vring state description</td>
</tr>
</tbody>
</table>
<p>Set the endianness of a VQ for legacy devices. Little-endian is
indicated with state.num set to 0 and big-endian is indicated with
state.num set to 1. Other values are invalid.</p>
<p class="last">This request should be sent only when
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_CROSS_ENDIAN</span></code> has been negotiated.
Backends that negotiated this feature should handle both
endiannesses and expect this message once (per VQ) during device
configuration (ie. before the master starts the VQ).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_CONFIG</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">24</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">virtio device config space</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">virtio device config space</td>
</tr>
</tbody>
</table>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_CONFIG</span></code> is negotiated, this message is
submitted by the vhost-user master to fetch the contents of the
virtio device configuration space, vhost-user slave’s payload size
MUST match master’s request, vhost-user slave uses zero length of
payload to indicate an error to vhost-user master. The vhost-user
master may cache the contents to avoid repeated
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_CONFIG</span></code> calls.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_CONFIG</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">25</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">virtio device config space</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_CONFIG</span></code> is negotiated, this message is
submitted by the vhost-user master when the Guest changes the virtio
device configuration space and also can be used for live migration
on the destination host. The vhost-user slave must check the flags
field, and slaves MUST NOT accept SET_CONFIG for read-only
configuration space fields unless the live migration bit is set.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_CREATE_CRYPTO_SESSION</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">26</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">crypto session description</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body">crypto session description</td>
</tr>
</tbody>
</table>
<p class="last">Create a session for crypto operation. The server side must return
the session id, 0 or positive for success, negative for failure.
This request should be sent only when
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_CRYPTO_SESSION</span></code> feature has been
successfully negotiated.  It’s a required feature for crypto
devices.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_CLOSE_CRYPTO_SESSION</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">27</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Close a session for crypto operation which was previously
created by <code class="docutils literal notranslate"><span class="pre">VHOST_USER_CREATE_CRYPTO_SESSION</span></code>.</p>
<p class="last">This request should be sent only when
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_CRYPTO_SESSION</span></code> feature has been
successfully negotiated.  It’s a required feature for crypto
devices.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_POSTCOPY_ADVISE</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">28</td>
</tr>
<tr class="field-even field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">slave payload:</th><td class="field-body">userfault fd</td>
</tr>
</tbody>
</table>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_PAGEFAULT</span></code> is supported, the master
advises slave that a migration with postcopy enabled is underway,
the slave must open a userfaultfd for later use.  Note that at this
stage the migration is still in precopy mode.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_POSTCOPY_LISTEN</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">29</td>
</tr>
<tr class="field-even field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p>Master advises slave that a transition to postcopy mode has
happened.  The slave must ensure that shared memory is registered
with userfaultfd to cause faulting of non-present pages.</p>
<p class="last">This is always sent sometime after a <code class="docutils literal notranslate"><span class="pre">VHOST_USER_POSTCOPY_ADVISE</span></code>,
and thus only when <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_PAGEFAULT</span></code> is supported.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_POSTCOPY_END</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">30</td>
</tr>
<tr class="field-even field"><th class="field-name">slave payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">u64</span></code></td>
</tr>
</tbody>
</table>
<p>Master advises that postcopy migration has now completed.  The slave
must disable the userfaultfd. The response is an acknowledgement
only.</p>
<p>When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_PAGEFAULT</span></code> is supported, this message
is sent at the end of the migration, after
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_POSTCOPY_LISTEN</span></code> was previously sent.</p>
<p class="last">The value returned is an error indication; 0 is success.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_INFLIGHT_FD</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">31</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">inflight description</td>
</tr>
</tbody>
</table>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD</span></code> protocol feature has
been successfully negotiated, this message is submitted by master to
get a shared buffer from slave. The shared buffer will be used to
track inflight I/O by slave. QEMU should retrieve a new one when vm
reset.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SET_INFLIGHT_FD</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">32</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">inflight description</td>
</tr>
</tbody>
</table>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD</span></code> protocol feature has
been successfully negotiated, this message is submitted by master to
send the shared inflight buffer back to slave so that slave could
get inflight I/O after a crash or restart.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_GPU_SET_SOCKET</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">33</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">Sets the GPU protocol socket file descriptor, which is passed as
ancillary data. The GPU protocol is used to inform the master of
rendering state and updates. See vhost-user-gpu.rst for details.</p>
</dd>
</dl>
</div>
<div class="section" id="slave-message-types">
<h3><a class="toc-backref" href="#id27">Slave message types</a><a class="headerlink" href="#slave-message-types" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SLAVE_IOTLB_MSG</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">1</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A (equivalent to <code class="docutils literal notranslate"><span class="pre">VHOST_IOTLB_MSG</span></code> message type)</td>
</tr>
<tr class="field-odd field"><th class="field-name">slave payload:</th><td class="field-body"><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vhost_iotlb_msg</span></code></td>
</tr>
<tr class="field-even field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">Send IOTLB messages with <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vhost_iotlb_msg</span></code> as payload.
Slave sends such requests to notify of an IOTLB miss, or an IOTLB
access failure. If <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_REPLY_ACK</span></code> is
negotiated, and slave set the <code class="docutils literal notranslate"><span class="pre">VHOST_USER_NEED_REPLY</span></code> flag, master
must respond with zero when operation is successfully completed, or
non-zero otherwise.  This request should be send only when
<code class="docutils literal notranslate"><span class="pre">VIRTIO_F_IOMMU_PLATFORM</span></code> feature has been successfully
negotiated.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SLAVE_CONFIG_CHANGE_MSG</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">2</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">slave payload:</th><td class="field-body">N/A</td>
</tr>
<tr class="field-even field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p class="last">When <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_CONFIG</span></code> is negotiated, vhost-user
slave sends such messages to notify that the virtio device’s
configuration space has changed, for those host devices which can
support such feature, host driver can send <code class="docutils literal notranslate"><span class="pre">VHOST_USER_GET_CONFIG</span></code>
message to slave to get the latest content. If
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_REPLY_ACK</span></code> is negotiated, and slave set the
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_NEED_REPLY</span></code> flag, master must respond with zero when
operation is successfully completed, or non-zero otherwise.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VHOST_USER_SLAVE_VRING_HOST_NOTIFIER_MSG</span></code></dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">id:</th><td class="field-body">3</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">equivalent ioctl:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">N/A</td>
</tr>
<tr class="field-odd field"><th class="field-name">slave payload:</th><td class="field-body">vring area description</td>
</tr>
<tr class="field-even field"><th class="field-name">master payload:</th><td class="field-body">N/A</td>
</tr>
</tbody>
</table>
<p>Sets host notifier for a specified queue. The queue index is
contained in the <code class="docutils literal notranslate"><span class="pre">u64</span></code> field of the vring area description. The
host notifier is described by the file descriptor (typically it’s a
VFIO device fd) which is passed as ancillary data and the size
(which is mmap size and should be the same as host page size) and
offset (which is mmap offset) carried in the vring area
description. QEMU can mmap the file descriptor based on the size and
offset to get a memory range. Registering a host notifier means
mapping this memory range to the VM as the specified queue’s notify
MMIO region. Slave sends this request to tell QEMU to de-register
the existing notifier if any and register the new notifier if the
request is sent with a file descriptor.</p>
<p class="last">This request should be sent only when
<code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_HOST_NOTIFIER</span></code> protocol feature has been
successfully negotiated.</p>
</dd>
</dl>
</div>
<div class="section" id="vhost-user-protocol-f-reply-ack">
<span id="reply-ack"></span><h3><a class="toc-backref" href="#id28">VHOST_USER_PROTOCOL_F_REPLY_ACK</a><a class="headerlink" href="#vhost-user-protocol-f-reply-ack" title="Permalink to this headline">¶</a></h3>
<p>The original vhost-user specification only demands replies for certain
commands. This differs from the vhost protocol implementation where
commands are sent over an <code class="docutils literal notranslate"><span class="pre">ioctl()</span></code> call and block until the client
has completed.</p>
<p>With this protocol extension negotiated, the sender (QEMU) can set the
<code class="docutils literal notranslate"><span class="pre">need_reply</span></code> [Bit 3] flag to any command. This indicates that the
client MUST respond with a Payload <code class="docutils literal notranslate"><span class="pre">VhostUserMsg</span></code> indicating success
or failure. The payload should be set to zero on success or non-zero
on failure, unless the message already has an explicit reply body.</p>
<p>The response payload gives QEMU a deterministic indication of the result
of the command. Today, QEMU is expected to terminate the main vhost-user
loop upon receiving such errors. In future, qemu could be taught to be more
resilient for selective requests.</p>
<p>For the message types that already solicit a reply from the client,
the presence of <code class="docutils literal notranslate"><span class="pre">VHOST_USER_PROTOCOL_F_REPLY_ACK</span></code> or need_reply bit
being set brings no behavioural change. (See the <a class="reference internal" href="#communication">Communication</a>
section for details.)</p>
</div>
</div>
<div class="section" id="backend-program-conventions">
<span id="backend-conventions"></span><h2><a class="toc-backref" href="#id29">Backend program conventions</a><a class="headerlink" href="#backend-program-conventions" title="Permalink to this headline">¶</a></h2>
<p>vhost-user backends can provide various devices &amp; services and may
need to be configured manually depending on the use case. However, it
is a good idea to follow the conventions listed here when
possible. Users, QEMU or libvirt, can then rely on some common
behaviour to avoid heterogenous configuration and management of the
backend programs and facilitate interoperability.</p>
<p>Each backend installed on a host system should come with at least one
JSON file that conforms to the vhost-user.json schema. Each file
informs the management applications about the backend type, and binary
location. In addition, it defines rules for management apps for
picking the highest priority backend when multiple match the search
criteria (see <code class="docutils literal notranslate"><span class="pre">&#64;VhostUserBackend</span></code> documentation in the schema file).</p>
<p>If the backend is not capable of enabling a requested feature on the
host (such as 3D acceleration with virgl), or the initialization
failed, the backend should fail to start early and exit with a status
!= 0. It may also print a message to stderr for further details.</p>
<p>The backend program must not daemonize itself, but it may be
daemonized by the management layer. It may also have a restricted
access to the system.</p>
<p>File descriptors 0, 1 and 2 will exist, and have regular
stdin/stdout/stderr usage (they may have been redirected to /dev/null
by the management layer, or to a log handler).</p>
<p>The backend program must end (as quickly and cleanly as possible) when
the SIGTERM signal is received. Eventually, it may receive SIGKILL by
the management layer after a few seconds.</p>
<p>The following command line options have an expected behaviour. They
are mandatory, unless explicitly said differently:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--socket-path=<var>PATH</var></span></kbd></td>
</tr>
<tr><td>&#160;</td><td>This option specify the location of the vhost-user Unix domain socket.
It is incompatible with –fd.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--fd=<var>FDNUM</var></span></kbd></td>
<td>When this argument is given, the backend program is started with the
vhost-user socket as file descriptor FDNUM. It is incompatible with
–socket-path.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--print-capabilities</span></kbd></td>
</tr>
<tr><td>&#160;</td><td>Output to stdout the backend capabilities in JSON format, and then
exit successfully. Other options and arguments should be ignored, and
the backend program should not perform its normal function.  The
capabilities can be reported dynamically depending on the host
capabilities.</td></tr>
</tbody>
</table>
<p>The JSON output is described in the <code class="docutils literal notranslate"><span class="pre">vhost-user.json</span></code> schema, by
<code class="docutils literal notranslate"><span class="pre">`&#64;VHostUserBackendCapabilities</span></code>.  Example:</p>
<div class="code json highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;foo&quot;</span><span class="p">,</span>
  <span class="s2">&quot;features&quot;</span><span class="p">:</span> <span class="p">[</span>
    <span class="s2">&quot;feature-a&quot;</span><span class="p">,</span>
    <span class="s2">&quot;feature-b&quot;</span>
  <span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="section" id="vhost-user-input">
<h3><a class="toc-backref" href="#id30">vhost-user-input</a><a class="headerlink" href="#vhost-user-input" title="Permalink to this headline">¶</a></h3>
<p>Command line options:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--evdev-path=<var>PATH</var></span></kbd></td>
</tr>
<tr><td>&#160;</td><td><p class="first">Specify the linux input device.</p>
<p class="last">(optional)</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--no-grab</span></kbd></td>
<td><p class="first">Do no request exclusive access to the input device.</p>
<p class="last">(optional)</p>
</td></tr>
</tbody>
</table>
</div>
<div class="section" id="vhost-user-gpu">
<h3><a class="toc-backref" href="#id31">vhost-user-gpu</a><a class="headerlink" href="#vhost-user-gpu" title="Permalink to this headline">¶</a></h3>
<p>Command line options:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--render-node=<var>PATH</var></span></kbd></td>
</tr>
<tr><td>&#160;</td><td><p class="first">Specify the GPU DRM render node.</p>
<p class="last">(optional)</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--virgl</span></kbd></td>
<td><p class="first">Enable virgl rendering support.</p>
<p class="last">(optional)</p>
</td></tr>
</tbody>
</table>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">QEMU</a></h1>



<p class="blurb">System Emulation Management and Interoperability Guide</p>






<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="bitmaps.html">Dirty Bitmaps and Incremental Backup</a></li>
<li class="toctree-l1"><a class="reference internal" href="live-block-operations.html">Live Block Device Operations</a></li>
<li class="toctree-l1"><a class="reference internal" href="pr-helper.html">Persistent reservation helper protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="qemu-ga.html">QEMU Guest Agent</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Vhost-user Protocol</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#message-specification">Message Specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="#communication">Communication</a></li>
<li class="toctree-l2"><a class="reference internal" href="#backend-program-conventions">Backend program conventions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="vhost-user-gpu.html">Vhost-user-gpu Protocol</a></li>
</ul>


<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2019, The QEMU Project Developers.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.6</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.9</a>
      
    </div>

    

    
  </body>
</html>

Youez - 2016 - github.com/yon3zu
LinuXploit