مرحبًا بك في OpenOCD

يوفر OpenOCD دعم البرمجة والتصحيح على الشريحة (on-chip) ببنية معمارية متعددة الطبقات لواجهة JTAG ودعم TAP بما في ذلك:

• تشغيل (X)SVF لتسهيل المسح الضوئي للحواف الآلي وبرمجة FPGA/CPLD؛
• دعم أهداف التصحيح (مثل ARM, MIPS): التنفيذ خطوة بخطوة (single-stepping)، نقاط التوقف/نقاط المراقبة، التوصيف باستخدام gprof، إلخ؛
• برامج تشغيل رقائق الفلاش (مثل CFI, NAND, الفلاش الداخلي)؛
• مترجم Tcl مدمج لسهولة كتابة النصوص البرمجية.

تتوفر عدة واجهات شبكية للتفاعل مع OpenOCD: telnet, Tcl, و GDB. يتيح خادم GDB لـ OpenOCD العمل كـ "هدف بعيد" لتصحيح الأخطاء على مستوى المصدر للأنظمة المدمجة باستخدام برنامج GNU GDB (وغيرها التي تتحدث بروتوكول GDB، مثل IDA Pro).

يحتوي ملف README هذا على نظرة عامة حول المواضيع التالية:

• تعليمات البدء السريع،
• كيفية العثور على وبناء المزيد من وثائق OpenOCD،
• قائمة بالأجهزة المدعومة،
• عملية التثبيت والبناء،
• نصائح التغليف.

بدء سريع لمن لا يطيق الانتظار

إذا كان لديك لوحة شائعة، فما عليك سوى تشغيل OpenOCD مع ملف التكوين الخاص بها، على سبيل المثال:

openocd -f board/stm32f4discovery.cfg

إذا كنت تقوم بتوصيل محول معين بهدف محدد، فأنت بحاجة إلى تضمين كل من تكوين واجهة jtag وتكوين الهدف، على سبيل المثال:

openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \
        -f target/ti/calypso.cfg

openocd -f interface/stlink.cfg -c "transport select swd" \
        -f target/stm32l0.cfg

بعد بدء تشغيل OpenOCD، اتصل بـ GDB باستخدام

(gdb) target extended-remote localhost:3333

تثبيت OpenOCD

أسهل طريقة لتثبيت OpenOCD هي عبر مدير الحزم لنظام التشغيل الخاص بك.

• دبيان / أوبونتو

  root@kitploit:~

  sudo apt install openocd
  

• فيدورا

  root@kitploit:~

  sudo dnf install openocd
  

• macOS (عبر Homebrew)

  root@kitploit:~

  brew install open-ocd
  

• ويندوز (عبر MSYS2)

  root@kitploit:~

  pacman -S mingw-w64-x86_64-openocd
  

غالبًا ما تكون هذه الحزم أكثر استقرارًا من الإصدار الرئيسي المتطور (bleeding-edge Git mainline) حيث يحدث التطوير النشط. يقوم "المُغَلِّفون" (Packagers) بإنشاء إصدارات ثنائية من OpenOCD بعد أن ينشر المطورون إصدارات جديدة من الكود المصدر. إصدارات OpenOCD الأقدم ليست مناسبة لتشخيص المشكلات في الإصدار الحالي. يجب على المستخدمين البقاء على اتصال مع مسؤولي توزيعاتهم أو بائعي الواجهات لضمان تقديم التحديثات المناسبة بانتظام.

إذا كنت تستخدم إحدى هذه الحزم الثنائية، فيجب عليك الاتصال بـ المُغَلِّف للحصول على الدعم أو الإصدارات الثنائية الأحدث. لا يقدم مطورو OpenOCD دعمًا مباشرًا للثنائيات المعبأة.

ملاحظة لمُغَلِّفي OpenOCD

أنت مُغَلِّف لـ OpenOCD إذا كنت:

• تبيع الأجهزة الطرفية (dongles) وتتضمن ثنائيات مبنية مسبقًا؛
• تقدم أدوات أو IDEs (حل تطوير يدمج OpenOCD)؛
• تبني حزم (مثل ملفات RPM أو DEB لتوزيعة GNU/Linux).

كمُغَلِّف، ستواجه أولى التقارير عن معظم المشكلات. عندما تصلح تلك المشكلات لمستخدميك، قد يساعد حلك في منع مئات (إن لم يكن آلاف) الأسئلة الأخرى من مستخدمين آخرين.

إذا لم يعمل شيء ما معك، فيرجى العمل على إبلاغ مطوري OpenOCD بكيفية تحسين النظام أو التوثيق لتجنب المشكلات المستقبلية، والمتابعة لمساعدتنا في ضمان حل المشكلة بالكامل في إصداراتنا المستقبلية.

مع ذلك، يرغب مطورو OpenOCD أيضًا في أن تتبع بعض الاقتراحات:

• أرسل التصحيحات (patches)، بما في ذلك ملفات التكوين، إلى المنبع، وشارك في المناقشات؛
• فعّل جميع الخيارات التي يدعمها OpenOCD، حتى تلك غير المرتبطة بأجهزتك الخاصة؛
• استخدم برنامج تشغيل واجهة المحول "ftdi" للأجهزة القائمة على FTDI.

وثائق OpenOCD

بالإضافة إلى الوثائق الموجودة في الشجرة (in-tree)، يمكن الاطلاع على أحدث الأدلة عبر الإنترنت على عناوين URL التالية:

• دليل مستخدم OpenOCD: http://openocd.org/doc/html/index.html

• دليل مطور OpenOCD: http://openocd.org/doc/doxygen/html/index.html

تعكس هذه الإصدارات أحدث إصدارات التطوير، لذلك يقدم القسم التالي كيفية بناء الوثائق الكاملة من الحزمة.

لمزيد من المعلومات، راجع هذه المستندات أو اتصل بالمطورين عن طريق الاشتراك في القائمة البريدية لمطوري OpenOCD: [email protected]

بناء وثائق OpenOCD

بشكل افتراضي، تقوم عملية بناء OpenOCD بإعداد الوثائق بتنسيق "Info" وتثبيتها بالطريقة القياسية، بحيث يمكن الوصول إليها عبر info openocd.

بالإضافة إلى ذلك، يمكن إنتاج دليل مستخدم OpenOCD بالتنسيقات المختلفة التالية:

إذا تم تعيين PDFVIEWER، فإن هذا يقوم بإنشاء وعرض دليل المستخدم بصيغة PDF.

make pdf && ${PDFVIEWER} doc/openocd.pdf

إذا تم تعيين HTMLVIEWER، فإن هذا يقوم بإنشاء وعرض دليل المستخدم بصيغة HTML.

make html && ${HTMLVIEWER} doc/openocd.html/index.html

يحتوي دليل مطور OpenOCD على معلومات حول البنية الداخلية وتفاصيل أخرى حول الكود:

ملاحظة: تأكد من تثبيت doxygen، اكتب doxygen --version

make doxygen && ${HTMLVIEWER} doxygen/index.html

الأجهزة المدعومة

محولات JTAG

AM335x, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835, Bus Blaster, Buspirate, Cadence DPI, Cadence vdebug, Chameleon, CMSIS-DAP, Cortino, Cypress KitProg, DENX, Digilent JTAG-SMT2, DLC 5, DLP-USB1232H, embedded projects, Espressif USB JTAG Programmer, eStick, FlashLINK, FlossJTAG, Flyswatter, Flyswatter2, FTDI FT232R, Gateworks, Hoegl, ICDI, ICEBear, J-Link, JTAG VPI, JTAGkey, JTAGkey2, JTAG-lock-pick, KT-Link, Linux GPIOD, Lisa/L, LPC1768-Stick, Mellanox rshim, MiniModule, NGX, Nuvoton Nu-Link, Nu-Link2, NXHX, NXP IMX GPIO, OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, Presto, Redbee, Remote Bitbang, RLink, SheevaPlug devkit, Stellaris evkits, ST-LINK (SWO tracing supported), STM32-PerformanceStick, STR9-comStick, sysfsgpio, Tigard, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster, USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe, Xverve.

أهداف التصحيح

ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M), FA526, Feroceon/Dragonite, XScale. ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64), ESP32, ESP32-S2, ESP32-S3, Intel Quark, LS102x-SAP, RISC-V, ST STM8, Xtensa.

برامج تشغيل الفلاش

ADUC702x, AT91SAM, AT91SAM9 (NAND), ATH79, ATmega128RFA1, Atmel SAM, AVR, CFI, DSP5680xx, EFM32, EM357, eSi-RISC, eSi-TSMC, EZR32HG, FM3, FM4, Freedom E SPI, GD32, i.MX31, Kinetis, LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPC3180, LPC32xx, LPCSPIFI, Marvell QSPI, MAX32, Milandr, MXC, NIIET, nRF51, nRF52 , NuMicro, NUC910, Nuvoton NPCX, onsemi RSL10, Orion/Kirkwood, PIC32mx, PSoC4/5LP/6, Raspberry RP2040, Renesas RPC HF and SH QSPI, S3C24xx, S3C6400, SiM3x, SiFive Freedom E, Stellaris, ST BlueNRG, STM32, STM32 QUAD/OCTO-SPI for Flash/FRAM/EEPROM, STMSMI, STR7x, STR9x, SWM050, TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF, XMC1xxx, XMC4xxx.

بناء OpenOCD

يحتوي ملف INSTALL على تعليمات عامة لتشغيل configure وتجميع كود مصدر OpenOCD. يتم توفير هذا الملف افتراضيًا لجميع حزم GNU autotools. إذا لم تكن معتادًا على GNU autotools، فيجب عليك قراءة تلك التعليمات أولاً.

ملاحظة: إذا كان ملف INSTALL غير موجود، فهذا يعني أنك تستخدم كود المصدر من فرع تطوير، وليس من إصدار OpenOCD. في هذه الحالة، اتبع التعليمات الواردة في 'Compiling OpenOCD' أدناه، وسيتم إنشاء الملف بواسطة الأمر الأول ./bootstrap.

يحاول باقي هذا المستند تقديم بعض الإرشادات لأولئك الذين يبحثون عن تثبيت سريع.

تبعيات OpenOCD

يتطلب بناء OpenOCD حاليًا GCC أو Clang. بدأ المطورون في فرض تحذيرات صارمة على الكود (-Wall, -Werror, -Wextra، والمزيد) واستخدام ميزات خاصة بـ C99: الدوال المضمنة (inline functions)، المُهيّئات المُسماة (named initializers)، خلط التصريحات مع الكود، وحيل أخرى. بينما قد يكون من الممكن استخدام مترجمات أخرى، يجب أن تكون حديثة نسبيًا وقد تتطلب توسيع الدعم لإزالة الامتدادات الخاصة بـ GCC بشكل شرطي.

ستحتاج أيضًا إلى:

• make
• libtool
• pkg-config >= 0.23 أو pkgconf
• libjim >= 0.79

بالإضافة إلى ذلك، للبناء من Git:

• autoconf >= 2.69
• automake >= 1.14
• texinfo >= 5.0

برامج تشغيل المحولات الاختيارية القائمة على USB تحتاج libusb-1.0.

برامج تشغيل محولات USB-Blaster و ASIX Presto و OpenJTAG الاختيارية تحتاج مكتبة libftdi.

برنامج تشغيل محول CMSIS-DAP الاختياري يحتاج مكتبة HIDAPI.

برنامج تشغيل محول linuxgpiod الاختياري يحتاج مكتبة libgpiod.

برنامج تشغيل محول J-Link الاختياري يحتاج مكتبة libjaylink.

فك التجميع الاختياري لـ ARM (disassembly) يحتاج مكتبة capstone.

البرنامج النصي الاختياري للتطوير checkpatch يحتاج إلى:

• perl
• python
• python-ply
• pymarkdownlnt

تجميع OpenOCD

لبناء OpenOCD، استخدم تسلسل الأوامر التالي:

./bootstrap
./configure [options]
make
sudo make install

الأمر bootstrap مطلوب فقط عند البناء من مستودع Git. تنتج خطوة configure ملفات Makefile المطلوبة لبناء OpenOCD، وعادةً ما يتم توفير خيار واحد أو أكثر لها. ستقوم خطوة 'make' الأولى ببناء OpenOCD ووضع الملف التنفيذي النهائي في './src/'. الخطوة الأخيرة (الاختيارية)، make install، تضع جميع الملفات في الموقع المطلوب.

لعرض قائمة بجميع الخيارات المدعومة، قم بتشغيل ./configure --help

خيارات التجميع المتبادل (Cross-compiling)

يتم دعم التجميع المتبادل بالطريقة القياسية لـ autotools، كل ما عليك فعله هو تحديد ثلاثي الهدف للتجميع المتبادل في خيار --host، على سبيل المثال للبناء المتبادل لنظام ويندوز 32 بت باستخدام MinGW على دبيان:

./configure --host=i686-w64-mingw32 [options]

لجعل pkg-config يعمل بشكل جيد للتجميع المتبادل، قد تحتاج إلى برنامج نصي إضافي للالتفاف كما هو موضح في https://autotools.io/pkgconfig/cross-compiling.html.

هذا مطلوب لإخبار pkg-config أين يبحث عن مكتبات الهدف التي يعتمد عليها OpenOCD. بدلاً من ذلك، يمكنك تحديد متغيرات البيئة *_CFLAGS و *_LIBS مباشرة، انظر ./configure --help للحصول على التفاصيل.

للحصول على برنامج نصي كامل إلى حد ما يقوم بكل هذا نيابة عنك، انظر contrib/cross-build.sh.

أجهزة المنفذ المتوازي (Parallel Port Dongles)

إذا كنت ترغب في الوصول إلى المنفذ المتوازي باستخدام واجهة PPDEV، فيجب عليك تحديد كل من --enable-parport و --enable-parport-ppdev، لأن الخيار الأخير هو خيار لبرنامج تشغيل parport.

وينطبق الشيء نفسه على خيار --enable-parport-giveio، يجب عليك استخدام كلا الخيارين --enable-parport و --enable-parport-giveio إذا كنت ترغب في استخدام giveio بدلاً من طريقة الوصول إلى المنفذ المتوازي ioperm.

الحصول على OpenOCD من Git

يمكنك تنزيل إصدار Git الحالي باستخدام عميل Git من اختيارك من المستودع الرئيسي: git://git.code.sf.net/p/openocd/code

قد تفضل استخدام مرآة:

• http://repo.or.cz/r/openocd.git
• git://repo.or.cz/openocd.git

باستخدام عميل سطر أوامر Git، يمكنك استخدام الأمر التالي لإعداد نسخة محلية من المستودع الحالي (تأكد من عدم وجود دليل باسم "openocd" في الدليل الحالي):

git clone git://git.code.sf.net/p/openocd/code openocd

ثم يمكنك تحديث ذلك في الوقت المناسب باستخدام git pull.

توجد أيضًا واجهة gitweb، والتي يمكنك استخدامها إما لتصفح المستودع أو لتنزيل لقطات عشوائية باستخدام HTTP: http://repo.or.cz/w/openocd.git.

اللقطات هي أرشيفات مضغوطة (tarballs) لشجرة المصدر، حجم كل منها حوالي 1.3 ميجابايت في وقت كتابة هذا.

تفويض الأذونات

يُمنع بشدة تشغيل OpenOCD بصلاحيات الجذر/الإدارية لأسباب أمنية.

بالنسبة لأجهزة USB على GNU/Linux، يجب عليك استخدام ملف contrib/60-openocd.rules. من المحتمل أن يكون موجودًا في مكان ما في /etc/udev/rules.d، ولكن استشر وثائق نظام التشغيل الخاص بك للتأكد. لا تنس إضافة نفسك إلى مجموعة "plugdev".

بالنسبة لمحولات المنفذ المتوازي على GNU/Linux و FreeBSD، يرجى تغيير أذونات جهاز العقدة "ppdev" (parport* أو ppi*) وفقًا لذلك.

بالنسبة لمحولات parport على ويندوز، تحتاج إلى تشغيل install_giveio.bat (من الممكن أيضًا استخدام "ioperm" مع Cygwin بدلاً من ذلك) لإعطاء المستخدمين العاديين أذونات الوصول المباشر إلى سجلات "LPT".