पोर्टिंग क्वेक 3 से रस्ट

हमारी टीम इम्युनेंट रस्ट से प्यार करती है और सक्रिय रूप से C2Rust पर काम कर रही है, एक माइग्रेशन फ्रेमवर्क जो रस्ट को प्रवास करने की संपूर्ण दिनचर्या का ख्याल रखता है। हम परिवर्तित रस्ट कोड में सुरक्षा सुधारों को स्वचालित रूप से लागू करने का प्रयास करते हैं और फ्रेमवर्क विफल होने पर प्रोग्रामर को इसे स्वयं करने में मदद करते हैं। हालांकि, सबसे पहले, हमें एक विश्वसनीय अनुवादक बनाने की आवश्यकता है जो उपयोगकर्ताओं को जंग से शुरू करने की अनुमति देता है। छोटे सीएलआई कार्यक्रमों पर परीक्षण धीरे-धीरे अप्रचलित हो रहा है, इसलिए हमने क्वेक 3 को रस्ट में स्थानांतरित करने का फैसला किया। कुछ दिनों के बाद, हम सबसे पहले रस्ट पर क्वेक 3 खेलने की संभावना रखते थे!

तैयारी: क्वेक 3 स्रोत

मूल क्वेक 3 और विभिन्न कांटे के स्रोत कोड का अध्ययन करने के बाद, हम ioquake3 पर आ गए। यह क्वेक 3 का एक समुदाय-निर्मित कांटा है, जो अभी भी आधुनिक प्लेटफार्मों पर समर्थित और निर्मित है।

एक प्रारंभिक बिंदु के रूप में, हमने यह सुनिश्चित करने का निर्णय लिया कि हम परियोजना को उसके मूल रूप में इकट्ठा कर सकते हैं:

$ make release 

Ioquake3 का निर्माण करते समय, कई पुस्तकालय और निष्पादन योग्य फाइलें बनाई जाती हैं:

 $ tree --prune -I missionpack -P "*.so|*x86_64" . └── build └── debug-linux-x86_64 ├── baseq3 │ ├── cgamex86_64.so # client │ ├── qagamex86_64.so # game server │ └── uix86_64.so # ui ├── ioq3ded.x86_64 # dedicated server binary ├── ioquake3.x86_64 # main binary ├── renderer_opengl1_x86_64.so # opengl1 renderer └── renderer_opengl2_x86_64.so # opengl2 renderer 

इन पुस्तकालयों में, यूआई, क्लाइंट और सर्वर लाइब्रेरी को या तो क्विक वीएम असेंबली के रूप में बनाया जा सकता है, या देशी X86 साझा लाइब्रेरी के रूप में। हमारी परियोजना में, हमने देशी संस्करणों का उपयोग करने का निर्णय लिया। VM को Rust में अनुवाद करना और QVM संस्करणों का उपयोग करना अधिक सरल होगा, लेकिन हम C2Rust का पूरी तरह से परीक्षण करना चाहते थे।

हमारे हस्तांतरण प्रोजेक्ट में, हमने UI, गेम, क्लाइंट, OpenGL1 रेंडरर और मुख्य निष्पादन योग्य पर ध्यान केंद्रित किया। हम OpenGL2 रेंडरर का अनुवाद भी कर सकते हैं, लेकिन हमने इसे छोड़ने का फैसला किया क्योंकि यह .glsl shader .glsl की एक महत्वपूर्ण मात्रा का उपयोग करता है, जो कि बिल्ड सिस्टम C स्रोत कोड में स्ट्रिंग शाब्दिक के रूप में एम्बेड करता है। संकलन के बाद, हम एम्बेडिंग के लिए स्क्रिप्ट बनाने के लिए समर्थन जोड़ देंगे। जंग के तारों में GLSL कोड, लेकिन इन स्वचालित रूप से उत्पन्न अस्थायी फ़ाइलों को स्थानांतरित करने के लिए अभी भी कोई अच्छा स्वचालित तरीका नहीं है। इसलिए इसके बजाय, हमने सिर्फ OpenGL1 रेंडर लाइब्रेरी का अनुवाद किया और गेम को डिफॉल्ट रेंडरर के बजाय इसका उपयोग करने के लिए मजबूर किया। इसके अलावा, हमने समर्पित सर्वर और पैकेज्ड मिशन फाइलों को छोड़ने का फैसला किया, क्योंकि उन्हें स्थानांतरित करना मुश्किल नहीं होगा और वे इस प्रदर्शन के लिए आवश्यक नहीं हैं।

संक्रमण ३

क्वेक 3 में प्रयुक्त निर्देशिका संरचना को संरक्षित करने और स्रोत कोड को नहीं बदलने के लिए, हमें मूल असेंबली की तरह ही बाइनरी फाइलें प्राप्त करने की आवश्यकता थी, अर्थात् चार साझा पुस्तकालय और एक निष्पादन योग्य।

चूंकि C2Rust कार्गो असेंबली फ़ाइलों को बनाता है, प्रत्येक बाइनरी को संबंधित Cargo.toml फ़ाइल के साथ अपने स्वयं के जंग क्रेट की आवश्यकता होती है।

C2Rust के लिए प्रति आउटपुट बाइनरी फ़ाइल एक क्रेट बनाने के लिए, उसे संबंधित वस्तु या स्रोत फ़ाइलों के साथ बाइनरी फ़ाइलों की सूची की भी आवश्यकता होगी, साथ ही प्रत्येक बाइनरी फ़ाइल बनाने के लिए इस्तेमाल किया जाने वाला एक लिंकर कॉल (उदाहरण के लिए, लाइब्रेरी निर्भरताएं)।

हालाँकि, हम जल्दी से एक सीमा के कारण आए जिस तरह से C2Rust देशी निर्माण प्रक्रिया को स्वीकार करता है: C2Rust इनपुट पर एक संकलन डेटाबेस फ़ाइल प्राप्त करता है जिसमें संकलन कमांड की एक सूची होती है जो निर्माण के दौरान निष्पादित होती है। हालाँकि, इस डेटाबेस में लिंकर कॉल के बिना केवल संकलन कमांड हैं। इस डेटाबेस को बनाने वाले अधिकांश टूल में यह जानबूझकर सीमा है, उदाहरण के लिए CMAKE_EXPORT_COMPILE_COMMANDS , bear और compiledb साथ CMAKE_EXPORT_COMPILE_COMMANDS । हमारे अनुभव में, एकमात्र उपकरण जिसमें build-logger कमांड शामिल हैं, CodeChecker द्वारा निर्मित build-logger , जिसका हमने उपयोग नहीं किया क्योंकि हमने केवल अपने स्वयं के रैपर लिखने के बाद इसके बारे में सीखा (वे नीचे वर्णित हैं)। इसका मतलब था कि कई बाइनरी फ़ाइलों के साथ सी प्रोग्राम को संकलित करने के लिए, हम किसी भी सामान्य टूल द्वारा बनाई गई compile_commands.json फ़ाइल का उपयोग नहीं कर सकते थे।

इसलिए, हमने अपने स्वयं के संकलक और लिंकर आवरण लिपियों को लिखा है जो कंपाइलर और लिंकर के सभी कॉलों को डेटाबेस में डंप करता है, और फिर इसे विस्तारित compile_commands.json परिवर्तित करता है। सामान्य सभा के बजाय आदेश का उपयोग करके:

 $ make release 

हमने असेंबली को रोकने के लिए रैपर को जोड़ा:

 $ make release CC=/path/to/C2Rust/scripts/cc-wrappers/cc 

रैपर एक JSON फ़ाइलों की एक निर्देशिका बनाते हैं, प्रति कॉल। दूसरी स्क्रिप्ट उन सभी को एक नई compile_commands.json फ़ाइल में एकत्रित करती है, जिसमें संकलन और संकलन दोनों कमांड हैं। फिर हमने C2Rust को बढ़ाया ताकि यह डेटाबेस से बिल्ड कमांड को पढ़े और प्रत्येक लिंक किए गए बाइनरी के लिए एक अलग टोकरा बनाए। इसके अलावा, C2Rust अब प्रत्येक बाइनरी फ़ाइल के लिए लाइब्रेरी निर्भरताएं भी पढ़ता है और स्वचालित रूप से उन्हें संबंधित build.rs फ़ाइल में जोड़ता है।

सुविधा में सुधार के लिए, सभी बाइनरी फ़ाइलों को कार्यक्षेत्र के अंदर रखकर एक समय में एकत्र किया जा सकता है। C2Rust शीर्ष-स्तरीय कार्यक्षेत्र Cargo.toml फ़ाइल बनाता है, इसलिए हम quake3-rs निर्देशिका में केवल cargo build साथ प्रोजेक्ट का निर्माण कर सकते हैं:

 $ tree -L 1 . ├── Cargo.lock ├── Cargo.toml ├── cgamex86_64 ├── ioquake3 ├── qagamex86_64 ├── renderer_opengl1_x86_64 ├── rust-toolchain └── uix86_64 $ cargo build --release 

खुरदरापन दूर करें

जब हमने पहली बार अनुवादित कोड को संकलित करने की कोशिश की, तो हम क्वेक 3 स्रोतों के साथ कुछ समस्याओं में भाग गए: ऐसे सीमावर्ती मामले थे जिन्हें C2Rust संभाल नहीं सका (न तो सही ढंग से, न ही किसी भी तरह)।

एरियर पॉइंटर्स

मूल स्रोत कोड में कई जगहों पर ऐसे भाव होते हैं जो अंतिम सरणी तत्व के बाद अगले तत्व को इंगित करते हैं। यहाँ एक सरल सी कोड उदाहरण है:

 int array[1024]; int *p; // ... if (p >= &array[1024]) { // error... } 

सी मानक (देखें, उदाहरण के लिए, C11, धारा 6.5.6 ) एक सरणी के अंत से परे एक तत्व को इंगित करने की अनुमति देता है। हालाँकि, जंग इस बात को मना करती है, भले ही हम केवल तत्व का पता लें। हमें AAS_TraceClientBBox फ़ंक्शन में ऐसे पैटर्न के उदाहरण मिले।

रस्ट कंपाइलर ने भी इसी तरह का संकेत दिया था, लेकिन वास्तव में G_TryPushingEntity में G_TryPushingEntity उदाहरण है, जहां सशर्त अनुदेश फॉर्म का है > नहीं >= । एक सूचक जो सीमा से बाहर चला जाता है, फिर सशर्त निर्माण के बाद dereferenced है, जो एक मेमोरी सुरक्षा बग है।

भविष्य में इस समस्या से बचने के लिए, हमने C2Rust ट्रांसपाइलर को ठीक किया ताकि यह सरणी अनुक्रमित संचालन का उपयोग करने के बजाय किसी सरणी तत्व के पते की गणना करने के लिए सूचक अंकगणितीय का उपयोग करे। इस फिक्स के लिए धन्यवाद, कोड जो समान पैटर्न "सरणी के अंत में तत्व पता" का उपयोग करता है, अब बिना संशोधनों के सही ढंग से अनुवादित और निष्पादित किया गया है।

चर लंबाई सरणी तत्व

हमने हर चीज का परीक्षण करने के लिए गेम लॉन्च किया, और तुरंत जंग से घबरा गए:

 thread 'main' panicked at 'index out of bounds: the len is 4 but the index is 4', quake3-client/src/cm_polylib.rs:973:17 

cm_polylib.c पर एक नज़र cm_polylib.c , हमने देखा कि यह निम्नलिखित संरचना में फ़ील्ड p को dereferences करता है:

 typedef struct { int numpoints; vec3_t p[4]; // variable sized } winding_t; 

संरचना में p फ़ील्ड लचीली सरणी सदस्य का एक संस्करण है जो C99 मानक द्वारा समर्थित नहीं है, लेकिन फिर भी gcc द्वारा स्वीकार किया जाता है। C2Rust सिंटैक्स C99 ( vec3_t p[] ) के साथ चर-लंबाई सरणियों के तत्वों को पहचानता है और C99 से पहले इस पैटर्न के संस्करणों की पहचान करने के लिए एक सरल vec3_t p[] लागू करता है (संरचनाओं के अंत में 0 और 1 के आकार); हमने ioquake3 स्रोत कोड में भी कई ऐसे उदाहरण पाए हैं।

उपरोक्त संरचना को C99 सिंटैक्स में बदलने से घबराहट समाप्त हो गई:

 typedef struct { int numpoints; vec3_t p[]; // variable sized } winding_t; 

सामान्य स्थिति में इस पैटर्न को स्वचालित रूप से ठीक करने का प्रयास (0 और 1 से भिन्न सरणी आकार के साथ) अत्यंत कठिन होगा, क्योंकि हमें सामान्य सरणियों और मनमानी आकारों की चर लंबाई के सरणियों के तत्वों के बीच अंतर करना होगा। इसलिए, इसके बजाय, हम अनुशंसा करते हैं कि आप मूल C कोड को मैन्युअल रूप से ठीक करें, जैसा कि हमने ioquake3 के साथ किया था।

इनलाइन असेंबलर कोड में बंधे ऑपरेंड

क्रैश का एक अन्य स्रोत /usr/include/bits/select.h सिस्टम हेडर से सी-असेंबलर कोड कोड था:

 # define __FD_ZERO(fdsp) \ do { \ int __d0, __d1; \ __asm__ __volatile__ ("cld; rep; " __FD_ZERO_STOS \ : "=c" (__d0), "=D" (__d1) \ : "a" (0), "0" (sizeof (fd_set) \ / sizeof (__fd_mask)), \ "1" (&__FDS_BITS (fdsp)[0]) \ : "memory"); \ } while (0) 

__FD_ZERO मैक्रो के आंतरिक संस्करण को परिभाषित करना। यह परिभाषा gcc का एक दुर्लभ सीमा रेखा मामला उठाती है: विभिन्न आकारों के साथ बंधे ऑपरेंड I / O। आउटपुट ऑपरेटर "=D" (__d1) रजिस्टर को 32-बिट मान के रूप में चर __d1 में __d1 , और "1" (&__FDS_BITS (fdsp)[0]) उसी रजिस्टर को पता fdsp->fds_bits से 64-बिट पॉइंटर के रूप में fdsp->fds_bits । gcc और clang इस बेमेल को हल करते हैं। 64-बिट rdi रजिस्टर का उपयोग करना और मान __d1 निर्दिष्ट करने से पहले इसके मूल्य को छोटा __d1 , और जंग डिफ़ॉल्ट रूप से LLVM शब्दार्थ का उपयोग करता है, जिसमें ऐसा मामला अपरिभाषित रहता है। डीबग बिल्ड में (रिलीज़ वाले में नहीं, जो अच्छा व्यवहार किया), हमने देखा कि दोनों ऑपरेंड को edi रजिस्टर में सौंपा जा सकता है, इस वजह से पॉइंटर को अंतर्निहित कोडांतरक कोड से पहले 32 बिट्स तक काट दिया जाता है, जो विफल हो जाता है।

चूंकि रस्ट बहुत कम बदलाव के साथ बिल्ट-इन rustc असेंबलर कोड को rustc पास करता है, इसलिए हमने C2Rust में इस विशेष मामले को ठीक करने का फैसला किया। हमने एक नया टोकरा c2rust-asm-casts लागू किया है जो c2rust-asm-casts और सहायक कार्यों का उपयोग करके रस्ट प्रकार प्रणाली के लिए इस समस्या को c2rust-asm-casts जो स्वचालित रूप से एक आंतरिक आकार में बंधे हुए ऑपरेंड का विस्तार करते हैं और दोनों ग्रंथियों को धारण करने के लिए पर्याप्त बड़े होते हैं। उपरोक्त कोड सही तरीके से निम्नलिखित में अनुवाद करता है:

 let mut __d0: c_int = 0; let mut __d1: c_int = 0; // Reference to the output value of the first operand let fresh5 = &mut __d0; // The internal storage for the first tied operand let fresh6; // Reference to the output value of the second operand let fresh7 = &mut __d1; // The internal storage for the second tied operand let fresh8; // Input value of the first operand let fresh9 = (::std::mem::size_of::<fd_set>() as c_ulong).wrapping_div(::std::mem::size_of::<__fd_mask>() as c_ulong); // Input value of the second operand let fresh10 = &mut *fdset.__fds_bits.as_mut_ptr().offset(0) as *mut __fd_mask; asm!("cld; rep; stosq" : "={cx}" (fresh6), "={di}" (fresh8) : "{ax}" (0), // Cast the input operands into the internal storage type // with optional zero- or sign-extension "0" (AsmCast::cast_in(fresh5, fresh9)), "1" (AsmCast::cast_in(fresh7, fresh10)) : "memory" : "volatile"); // Cast the operands out (types are inferred) with truncation AsmCast::cast_out(fresh5, fresh9, fresh6); AsmCast::cast_out(fresh7, fresh10, fresh8); 

यह ध्यान देने योग्य है कि इस कोड को fresh6 कोड की असेंबली में इनपुट और आउटपुट वैल्यू के लिए किसी भी प्रकार की आवश्यकता नहीं होती है, जब प्रकार के संघर्षों को हल करते हैं, तो उन पर भरोसा करने के बजाय आउटपुट के लिए जंग प्रकार (मुख्य रूप से fresh6 और fresh8 )।

ग्लोबल वेरिएबल्स को संरेखित किया

विफलता का अंतिम स्रोत एसएसई स्थिरांक को निम्नलिखित वैश्विक चर था:

 static unsigned char ssemask[16] __attribute__((aligned(16))) = { "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x00\x00\x00\x00" }; 

जंग वर्तमान में संरचनात्मक प्रकारों के लिए संरेखण विशेषता का समर्थन करता है, लेकिन वैश्विक चर के लिए नहीं, अर्थात्। static तत्व। हमने इस समस्या को हल करने के तरीकों पर विचार किया, या तो जंग में या C2Rust में, लेकिन अब ioquake3 में हमने इसे एक छोटी पैच फ़ाइल के साथ मैन्युअल रूप से ठीक करने का निर्णय लिया है। यह पैच फ़ाइल Rust ssemask निम्न के ssemask बदल देती है:

 #[repr(C, align(16))] struct SseMask([u8; 16]); static mut ssemask: SseMask = SseMask([ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 0, 0, 0, 0, ]); 

रनिंग क्वेक3-आरएस

जब cargo build --release , तो बायनेरिज़ का cargo build --release , लेकिन वे एक निर्देशिका संरचना के साथ target/release के तहत बनाए जाते हैं जो कि ioquake3 बाइनरी पहचान नहीं करता है। हमने एक ऐसी स्क्रिप्ट लिखी है जो सही निर्देशिका संरचना ( .pk3 फ़ाइलों को शामिल करने .pk3 फ़ाइलों सहित) को पुनः बनाने के लिए वर्तमान निर्देशिका में प्रतीकात्मक लिंक बनाती है:

 $ /path/to/make_quake3_rs_links.sh /path/to/quake3-rs/target/release /path/to/paks 

पथ /path/to/paks .pk3 को .pk3 फ़ाइलों वाली निर्देशिका को इंगित करना चाहिए।

अब चलिए खेल को चलाते हैं! हमें +set vm_game 0 करने की आवश्यकता है, आदि, इसलिए हम इन मॉड्यूल को रूस्ट साझा लाइब्रेरी के रूप में लोड करते हैं, और cl_renderer असेंबली के रूप में नहीं, साथ ही ओपन_१ रेंडरर का उपयोग करने के लिए cl_renderer।

 $ ./ioquake3 +set sv_pure 0 +set vm_game 0 +set vm_cgame 0 +set vm_ui 0 +set cl_renderer "opengl1" 

और ...


हमने रस्ट पर Quake3 लॉन्च किया!


यहाँ एक वीडियो है कि कैसे हम क्वेक 3 को स्थानांतरित करते हैं, गेम डाउनलोड करते हैं और इसे थोड़ा सा खेलते हैं:


आप हमारी रिपॉजिटरी की transpiled शाखा में ट्रांसप्लड स्रोतों का अध्ययन कर सकते हैं। इसके अलावा एक refactored शाखा है जिसमें कई पूर्व-लागू रिफैक्टिंग कमांड के समान स्रोत हैं ।

संक्रमण कैसे करें

यदि आप क्वेक 3 को स्थानांतरित करने और इसे स्वयं चलाने का प्रयास करना चाहते हैं, तो ध्यान रखें कि आपको इंटरनेट से अपने स्वयं के क्वेक 3 गेम संसाधनों या डेमो संसाधनों की आवश्यकता होगी। आपको C2Rust को स्थापित करने की भी आवश्यकता होगी (लेखन के समय, रात का आवश्यक संस्करण nightly-2019-12-05 , लेकिन हम अनुशंसा करते हैं कि आप नवीनतम संस्करण को खोजने के लिए C2Rust रिपॉजिटरी या crates.io पर नज़र डालें:

 $ cargo +nightly-2019-12-05 install c2rust 

और हमारे C2Rust और ioquake3 रिपॉजिटरी की प्रतियां:

 $ git clone <a href="/cdn-cgi/l/email-protection" class="__cf_email__" data-cfemail="dcbbb5a89cbbb5a8b4a9bef2bfb3b1">[email protected]</a>:immunant/c2rust.git $ git clone <a href="/cdn-cgi/l/email-protection" class="__cf_email__" data-cfemail="dcbbb5a89cbbb5a8b4a9bef2bfb3b1">[email protected]</a>:immunant/ioq3.git 

ऊपर दिए गए आदेश का उपयोग करके c2rust को स्थापित करने के विकल्प के रूप में, आप cargo build --release का उपयोग करके मैन्युअल रूप से C2Rust का निर्माण कर सकते हैं। किसी भी मामले में, C2Rust रिपॉजिटरी की अभी भी आवश्यकता होगी, क्योंकि इसमें ioquake3 ट्रांसप्लिमेंटेशन के लिए आवश्यक कंपाइलर आवरण स्क्रिप्ट शामिल हैं।

हमने एक स्क्रिप्ट पोस्ट की है जो स्वचालित रूप से सी कोड ट्रांसपोर्ट करती है और ssemask पैच को लागू करती है। इसका उपयोग करने के लिए, ioq3 रिपॉजिटरी के शीर्ष स्तर से निम्न कमांड चलाएँ:

 $ ./transpile.sh </path/to/C2Rust repository> </path/to/c2rust binary> 

इस कमांड को Rust कोड युक्त एक उपनिर्देशिका quake3-rs बनाना चाहिए, जिसके लिए आप cargo build --release और ऊपर वर्णित शेष चरणों को निष्पादित कर सकते हैं।