הערות ב-Verilog: הערת שורה, הערה מרובת שורות וסגנון תיעוד

שתי הצורות

Verilog תומכת בדיוק בשני תחבירים של הערות, ושניהם הועתקו מ-C:

// הערה של שורה אחת: כל מה שאחרי // ועד סוף השורה לא נלקח בחשבון.

/* הערה מרובת שורות.
   יכולה להשתרע על כמה שורות שרוצים.
   נסגרת עם כוכבית-לוכסן תואמים. */

module example;
    initial begin
        $display("the simulator never sees the comments above");
        $finish;
    end
endmodule

זה כל התחביר. אין # כמו ב-Python, אין -- כמו ב-VHDL, אין סגנון Lisp. רק // ו-/* ... */.

מתי להשתמש בכל אחת

ב-// תשתמשו כמעט בכל פעם. היא קצרה יותר, אי אפשר לשכוח לסגור אותה בטעות, והיא מתאימה באופן טבעי לדרך שבה כותבים Verilog (הצהרה אחת בכל שורה, עם ההערה באותה שורה או בשורה הסמוכה):

output reg [7:0] data,  // הבית שאנחנו מוציאים ב-tx_serial
output reg       valid, // גבוה בזמן שה-data משודר
input  wire      ready  // הצרכן בהמשך השרשרת מוכן לקבל

/* ... */ משמשת בעיקר לשני דברים: בלוקי כותרת גדולים בראש הקובץ, ונטרול זמני של קטע קוד בזמן דיבאג. מקרה הנטרול מסוכן, המשיכו לקרוא.

המלכודת של "אין קינון"

הערות בלוק לא מתקננות. אם מנסים להפוך להערה אזור שכבר מכיל הערת בלוק, ה-*/ הראשון סוגר את הבלוק החיצוני, לא את הפנימי:

/* חיצונית
   /* פנימית */    // <-- ה-*/ הזה סוגר את ההערה החיצונית
   עדיין פעיל בקוד המקור מבחינת ה-parser
*/

התוצאה: שגיאת תחביר במקום לא צפוי, בשורה שנראית תקינה.

כשצריך לנטרל אזור, העדיפו אחת מהאפשרויות:

1. להוסיף // בתחילת כל שורה. רוב העורכים עושים את זה בלחיצת מקש.

2. להשתמש בשמירת preprocessor:

   `ifdef DISABLED
       // קוד שלא אמור לעבור קומפילציה
   `endif
   

התבנית השנייה היא גם הדרך לשמור כמה תצורות build בקובץ אחד.

pragma של סינתזה: הערות שאינן הערות

כלים של יצרנים משתמשים בהערות בפורמט מיוחד כהוראות צדדיות. הסימולטור עדיין מתעלם מהן, אבל כלי הסינתזה קורא אותן:

// synthesis translate_off
initial begin
    $display("simulator-only setup");
end
// synthesis translate_on

שני ה-pragma אומרים לכלי הסינתזה "דלג על כל מה שבין הסימנים האלה". האיות המדויק משתנה בין יצרנים (synthesis, synopsys, pragma, xilinx וכו'), אז בדקו בתיעוד של הכלי שלכם. מה שחשוב לדעת: הערות ב-Verilog הן לפעמים חלק מהפונקציונליות.

מוסכמות לבלוק כותרת

קבצי Verilog שחיים הרבה זמן כמעט תמיד מתחילים בבלוק כותרת. הפורמט המדויק נקבע במדיניות הצוות, אבל הנה דוגמה טיפוסית:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : משדר UART מסוג 8-N-1. מקבל בית ב-`data` כש-`valid`
//               פעיל ומוציא אותו ב-`serial_out`. `baud_tick`
//               חייב לתת פולס אחד בכל מחזור baud.
// Ports       : clk        : שעון המערכת
//               reset_n    : reset סינכרוני פעיל בנמוך
//               baud_tick  : פולס של מחזור אחד בכל מרווח baud
//               data       : הבית לשידור
//               valid      : מופעל כדי להתחיל שידור
//               serial_out : ה-wire שיוצא מה-FPGA
//               busy       : גבוה בזמן ש-frame בדרך
// Author      : example@team
// Revision    : 2026-05-26 - initial version
// -----------------------------------------------------------------------------

module uart_tx (
    input  wire       clk,
    input  wire       reset_n,
    input  wire       baud_tick,
    input  wire [7:0] data,
    input  wire       valid,
    output reg        serial_out,
    output reg        busy
);
    // ... body ...
endmodule

העיקר הוא לא הקישוט. העיקר הוא שמי שיפתח את הקובץ הזה בעוד שנה, כנראה אתם, יוכל לקרוא ארבע שורות ולדעת מה הוא עושה, מה הוא מצפה לקבל ומה הוא מפיק. התועלת הזו גדלה עם גודל הפרויקט.

הערות בשורה שמצדיקות את קיומן

טעות נפוצה היא להסביר מה שורה עושה כשהקוד כבר מראה את זה:

// רע: ההערה חוזרת על הקוד
count <= count + 1;   // מגדיל את count

// טוב יותר: ההערה מסבירה למה השורה הזו כאן
count <= count + 1;   // מונה מחזורים חופשי לחותמות זמן

מה שהערות טובות בו במיוחד הוא להסביר את ה_למה_ שהקוד לא יכול להראות בעצמו: איזה סעיף במפרט מקודד מוזר עוקב אחריו, למה רגיסטר רחב בביט אחד ממה שנראה, למה מקרה default מוגדר ל-'x במקום ל-'0. השתמשו בהן בשביל זה. את המובן מאליו השאירו לקוד.

נסו בעצמכם

הבלוק שלמטה מכיל את כל צורות ההערות. הריצו אותו: הפלט לא יפתיע אתכם, אבל מבנה הקובץ אמור ללמד משהו:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : מחבר מלא של ביט אחד. מוציא `sum` ו-`cout` מתוך a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // ביט המחובר הראשון
    input  wire b,      // ביט המחובר השני
    input  wire cin,    // נשא כניסה ממחבר מסדר נמוך יותר
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* שתי המשוואות למטה הן מחבר מלא מספר הלימוד.
       Sum הוא הזוגיות של שלוש הכניסות, ו-cout הוא
       רוב מתוך שלוש. */
    assign sum  = a ^ b ^ cin;
    assign cout = (a & b) | (cin & (a ^ b));
endmodule

module test;
    reg  a, b, cin;
    wire sum, cout;

    full_adder dut(.a(a), .b(b), .cin(cin), .sum(sum), .cout(cout));

    initial begin
        // עוברים על כל 8 צירופי הכניסה.
        for (integer i = 0; i < 8; i = i + 1) begin
            {a, b, cin} = i[2:0];
            #1 $display("a=%b b=%b cin=%b -> sum=%b cout=%b",
                        a, b, cin, sum, cout);
        end
        $finish;
    end
endmodule

עכשיו ראיתם את כל צורות ההערות ש-Verilog תומכת בהן. שאר דפי התיעוד משתמשים בהן כמצופה: בלוקי כותרת בראש מודולים ארוכים, // של שורה אחת ליד פורטים, והערות בלוק רק כשיש פסקה שלמה של הסבר לתעד.