عرض مصدر Arduino/progmem

<noinclude>{{DISPLAYTITLE:الكلمة <code>PROGMEM</code> المفتاحية في  أردوينو}}</noinclude>
تُستعمَل الكلمة <code>PROGMEM</code> المفتاحية مع المتغيرات عندما يراد تخزين بياناتها في ذاكرة البرنامج (الذاكرة flash) بدلًا من تخزينها في الذاكرة SRAM. لمزيد من المعلومات حول أنواع الذاكرة المتاحة في أردوينو، اطلع على هذه الصفحة.

تصنَّف الكلمة <code>PROGMEM</code> المفتاحية ضمن «مقيدات المتغيرات» (variable qualifier)، ويجب استعمالها مع أنواع البيانات المعرَّفة في المكتبة [http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html pgmspace.h] فقط. تخبر هذه الكلمة المصرَّف بأنَّ يضع بيانات المتغير التي استعملت معه في الذاكرة flash بدلًا من وضعها في الذاكرة SRAM حيث يجب أن تخزَّن بالحالة الطبيعية.

الكلمة <code>PROGMEM</code> المفتاحية هي جزءٌ من المكتبة [http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html pgmspace.h]. تُضمَّن هذه المكبتة تلقائيًّا في الإصدارات الحديثة من أردوينو IDE. على أي حال، إن كنت تستعمل إصدارًا أقدم من 1.0 (2011)، فيجب أن تُضمِّن المكتبة يدويًّا في بداية شيفرتك باستعمال <code>[[Arduino/include|include#]]</code>:<syntaxhighlight lang="arduino">
#include <avr/pgmspace.h>


</syntaxhighlight>

== البنية العامة ==
<syntaxhighlight lang="arduino">
const dataType variableName[] PROGMEM = {data0, data1, data3…};


</syntaxhighlight>يمثِّل <code>dataType</code> أي نوع من البيانات، و <code>variableName</code> اسم مصفوفة البيانات المراد تخزينها في الذاكرة flash.

انتبه إلى أنَّه لمَّا كانت الكلمة <code>PROGMEM</code> المفتاحية مُقيِّدةً لمتغيرٍ، فلا يوجد قاعدة تُحتِّم وجودها في مكان محدَّد أثناء التصريح عن متغير؛ هذا يعني أنَّ المصرِّف في أردوينو يقبل جميع التعريفات المذكورة في المثال الآتي. مع ذلك، أشارت بعض الاختبارات أنَّ <code>PROGMEM</code>، في إصدارات مختلفة من أردوينو (التي تستعمل المصرِّف GCC)، قد تعمل في موضع محدَّد دون غيره عند التصريح عن متغير. جُرُّب المثال الثاني في قسم الأمثلة في الإصدار أردوينو 13؛ قد يعمل المثال في إصدارات سابقة بشكل أفضل إن وُضعَت <code>PROGMEM</code> بعد اسم المتغير.<syntaxhighlight lang="arduino">
const dataType variableName[] PROGMEM = {};
const PROGMEM dataType variableName[] = {};
const dataType PROGMEM variableName[] = {};
</syntaxhighlight>لمَّا كان بالإمكان استعمال الكلمة <code>PROGMEM</code> المفتاحية مع متغير واحد، فيُستحسَن استعمالها مع مصفوفة (أو  أيَّة هيكلية مشابهة في C لتخزين البيانات سواءً ذُكرَت في هذا التوثيق أم لا) لاحتواء البيانات المراد تخزينها في الذاكرة flash إن كانت هذه البيانات كبيرة.

استعمال <code>PROGMEM</code> يتطلب تنفيذ إجراء مكوَّن من خطوتين. فبعد تخزين البيانات في الذاكرة flash (الخطوة الأولى)، يجب استعمال توابع (دوال) خاصة معرَّفة في المكتبة [http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html pgmspace.h] من أجل قراءة هذه البيانات من ذاكرة البرنامج ووضعها في الذاكرة SRAM، وبذلك يمكننا الاستفادة من هذه البيانات واستعمالها.

== أمثلة ==
توضِّح الشيفرة التالية كيفية كتابة بيانات على الذاكرة flash ثمَّ قراءتها مجدَّدًا منها:<syntaxhighlight lang="arduino">
// حفظ بعض الأعداد الصحيحة عديمة الإشارة
const PROGMEM  uint16_t charSet[]  = { 65000, 32796, 16843, 10, 11234};

// حفظ بعض المحارف
const char signMessage[] PROGMEM  = {"I AM PREDATOR,  UNSEEN COMBATANT. CREATED BY THE UNITED STATES DEPART"};

unsigned int displayInt;
int k;    // متغير عدَّاد
char myChar;


void setup() {
  Serial.begin(9600);
  while (!Serial);  // انتظار اتصال المنفذ التسلسلي

  // اكتب هنا أي شيء تريد تهيئته وتنفيذه لمرة واحدة
  // إعادة قراءة الأعداد الصحيحة 
  for (k = 0; k < 5; k++)
  {
    displayInt = pgm_read_word_near(charSet + k);
    Serial.println(displayInt);
  }
  Serial.println();

  // إعادة قراءة المحارف
  for (k = 0; k < strlen_P(signMessage); k++)
  {
    myChar =  pgm_read_byte_near(signMessage + k);
    Serial.print(myChar);
  }

  Serial.println();
}

void loop() {
  // اكتب هنا برنامجك لتنفيذه بشكل متكرر

}

</syntaxhighlight>يُستحسَن عند العمل مع مقدار كبير من النصوص، مثل احتواء المشروع على شاشة LCD،  إنشاء وتهيئة [[Arduino/array|مصفوفة]] من السلاسل النصية لتخزين هذه النصوص فيها. لمَّا كانت السلاسل النصية نفسها هي [[Arduino/array|مصفوفات]]، فيجب استعمال [[Arduino/array|مصفوفة ثنائية الأبعاد]]. يوضح المثال التالي فكرة وضع البيانات كبيرة الحجم في ذاكرة البرنامج:<syntaxhighlight lang="arduino">
/*
 PROGMEM string demo
 How to store a table of strings in program memory (flash),
 and retrieve them.

 Information summarized from:
 http://www.nongnu.org/avr-libc/user-manual/pgmspace.html

 Setting up a table (array) of strings in program memory is slightly complicated, but
 here is a good template to follow.

 Setting up the strings is a two-step process. First define the strings.
*/

#include <avr/pgmspace.h>
const char string_0[] PROGMEM = "String 0";   // هي السلسلة المراد تخزينها. غيرها بما يناسب برنامجك "String 0" السلسلة
const char string_1[] PROGMEM = "String 1";
const char string_2[] PROGMEM = "String 2";
const char string_3[] PROGMEM = "String 3";
const char string_4[] PROGMEM = "String 4";
const char string_5[] PROGMEM = "String 5";


// ثم أنشئ جدولًا يشير إلى هذه السلاسل النصية

const char* const string_table[] PROGMEM = {string_0, string_1, string_2, string_3, string_4, string_5};

char buffer[30];    // تأكد من أن يكون حجم هذه المصفوفة كبيرًا بما يكفي ليستع لأكبر سلسلة نصية

void setup()
{
  Serial.begin(9600);
  while(!Serial); // انتظر حتى يتصل المنفذ التسلسلي
  Serial.println("OK");
}


void loop()
{
  /* يتطلب استعمال جدول السلاسل النصية الموجود في ذاكرة 
     .البرنامج استعمال دوال خاصة لجلب البيانات
      سلسلة نصية من ذاكرة البرنامج strcpy_P تنسخ الدالة
      .(في حالتنا buffer هي ذاكرة المتغير) RAM إلى الذاكرة
      كبير ما يكفي  RAM تأكد من أن الجزء المحجوز في الذاكرة 
      .ليسع البيانات المستعادة من ذاكرة البرنامج
      */


  for (int i = 0; i < 6; i++)
  {
    strcpy_P(buffer, (char*)pgm_read_word(&(string_table[i]))); // Necessary casts and dereferencing, just copy.
    Serial.println(buffer);
    delay( 500 );
  }
}

</syntaxhighlight>

== ملاحظات وتحذيرات ==
انتبه رجاءً إلى أنَّ المتغيرات يجب أن تكون إمَّا متغيرات عامة أو متغيرات محلية ساكنة (عُرِّفت باستعمال الكلمة <code>[[Arduino/static|static]]</code> المفتاحية) لتتمكن من استعمال الكلمة <code>PROGMEM</code> معها.

لن يعمل المثال التالي عند وضعه ضمن متغير:<syntaxhighlight lang="arduino">
const char long_str[] PROGMEM = "Hi, I would like to tell you a bit about myself.\n";

</syntaxhighlight>بينما سيعمل التصريح التالي لمتغير إن عُرِّف محليًّا داخل دالة:<syntaxhighlight lang="arduino">
const static char long_str[] PROGMEM = "Hi, I would like to tell you a bit about myself.\n"

</syntaxhighlight>

== الاستدعاء <code>F()</code>‎ الموسَّع ==
عندما يُستعمَل أمرٌ مثل:<syntaxhighlight lang="arduino">
Serial.print("Write something on  the Serial Monitor");

</syntaxhighlight>تُحفَظ السلسلة النصية المراد طباعتها بشكل طبيعي في الذاكرة RAM. إن كانت شيفرتك تطبع الكثير من النصوص على المنفذ التسلسلي، فسيؤدي ذلك إلى امتلاء الذاكرة. إن كان لديك مساحة فارغة في الذاكرة flash، فيمكنك أن تستثمرها بسهولة بتخزين هذه النصوص فيها عبر استعمال الصيغة التالية:<syntaxhighlight lang="arduino">
Serial.print(F("Write something on the Serial Monitor that is stored in FLASH"));

</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[Arduino/sizeof|sizeof()‎]]</code>: تعيد الحجم المحجوز من الذاكرة بالبايت لمتغير أو مصفوفة معيَّنة.

* أنواع الذاكرة الموجودة في أردوينو.

== مصادر ==
* [https://www.arduino.cc/reference/en/language/variables/utilities/progmem/ صفحة PROGMEM في توثيق أردوينو الرسمي.]
[[تصنيف: Arduino]]
[[تصنيف: Arduino Constants & Variables]]