docs(basic): add beginner-friendly comments clarifying ipv4_forward action data & ipv4_lpm usage (#699)

* docs(basic): clarify ipv4_forward action parameters for beginners

Signed-off-by: Arya Tayshete <avtayshete_b21@et.vjti.ac.in>

* Added suggested changes

Signed-off-by: Arya Tayshete <avtayshete_b21@et.vjti.ac.in>

---------

Signed-off-by: Arya Tayshete <avtayshete_b21@et.vjti.ac.in>

Author: xoaryaa

exercises/basic/basic.p4

@@ -7,11 +7,14 @@ const bit<16> TYPE_IPV4 = 0x800;
 
 /*************************************************************************
 *********************** H E A D E R S  ***********************************
+* This program skeleton defines minimal Ethernet and IPv4 headers and    *
+* a simple LPM (Longest-Prefix Match) IPv4 forwarding pipeline.          *
+* The exercise intentionally leaves TODOs for learners to implement.     *
 *************************************************************************/
 
-typedef bit<9>  egressSpec_t;
-typedef bit<48> macAddr_t;
-typedef bit<32> ip4Addr_t;
+typedef bit<9>  egressSpec_t;   // Standard BMv2 uses 9 bits for egress_spec
+typedef bit<48> macAddr_t;      // Ethernet MAC address
+typedef bit<32> ip4Addr_t;      // IPv4 address
 
 header ethernet_t {
     macAddr_t dstAddr;
@@ -44,7 +47,14 @@ struct headers {
 }
 
 /*************************************************************************
-*********************** P A R S E R  ***********************************
+*********************** P A R S E R  *************************************
+* New to P4? A typical parser does this:
+*   start -> parse_ethernet
+*   parse_ethernet:
+*       if etherType == TYPE_IPV4 -> parse_ipv4
+*       else accept
+*   parse_ipv4 -> accept
+* This skeleton leaves the actual states as a TODO to implement later.   *
 *************************************************************************/
 
 parser MyParser(packet_in packet,
@@ -53,7 +63,12 @@ parser MyParser(packet_in packet,
                 inout standard_metadata_t standard_metadata) {
 
     state start {
-        /* TODO: add parser logic */
+        /* TODO: add parser logic
+         * Suggested outline:
+         *   1) Extract Ethernet: packet.extract(hdr.ethernet);
+         *   2) If hdr.ethernet.etherType == TYPE_IPV4 -> parse IPv4
+         *   3) Otherwise -> transition accept
+         */
         transition accept;
     }
 }
@@ -70,31 +85,54 @@ control MyVerifyChecksum(inout headers hdr, inout metadata meta) {
 
 /*************************************************************************
 **************  I N G R E S S   P R O C E S S I N G   *******************
+* High-level intent:
+*   - Do an LPM lookup on IPv4 dstAddr
+*   - On hit, call ipv4_forward(next-hop MAC, output port)
+*   - Otherwise, drop or NoAction (as configured)                         *
 *************************************************************************/
 
 control MyIngress(inout headers hdr,
                   inout metadata meta,
                   inout standard_metadata_t standard_metadata) {
+
     action drop() {
         mark_to_drop(standard_metadata);
     }
 
+    /*********************************************************************
+     * NOTE FOR NEW READERS:
+     * 'ipv4_forward(dstAddr, port)' is invoked by table 'ipv4_lpm'.
+     *
+     * The values for 'dstAddr' and 'port' are *action data* supplied by
+     * the control plane when it installs entries in 'ipv4_lpm'.
+     *
+     * They mean:
+     *   - dstAddr  => Ethernet destination MAC for the next hop
+     *   - port     => output port (ultimately written to standard_metadata.egress_spec)
+     *
+     * Example (BMv2 simple_switch_CLI):
+     *   table_add ipv4_lpm ipv4_forward 10.0.1.1/32 => 00:00:00:00:01:00 1
+     * which passes MAC=00:00:00:00:01:00 and PORT=1 as action parameters
+     * into ipv4_forward(dstAddr, port).
+     *********************************************************************/
     action ipv4_forward(macAddr_t dstAddr, egressSpec_t port) {
         /*
             Action function for forwarding IPv4 packets.
 
-            This function is responsible for forwarding IPv4 packets to the specified
-            destination MAC address and egress port.
-
-            Parameters:
-            - dstAddr: Destination MAC address of the packet.
-            - port: Egress port where the packet should be forwarded.
-
-            TODO: Implement the logic for forwarding the IPv4 packet based on the
-            destination MAC address and egress port.
+            TODO: Implement the forwarding steps, for example:
+              - standard_metadata.egress_spec = port;
+              - hdr.ethernet.dstAddr = dstAddr;
+              - (optionally) set hdr.ethernet.srcAddr to the switch MAC for 'port'
+              - adjust IPv4 TTL and checksums as needed
         */
     }
 
+    /*********************************************************************
+     * LPM table for IPv4:
+     *   - Matches on hdr.ipv4.dstAddr using longest-prefix match (lpm)
+     *   - On hit, calls ipv4_forward with *action data* populated by the
+     *     control plane when it installs the table entry.
+     *********************************************************************/
     table ipv4_lpm {
         key = {
             hdr.ipv4.dstAddr: lpm;
@@ -110,14 +148,17 @@ control MyIngress(inout headers hdr,
 
     apply {
         /* TODO: fix ingress control logic
-         *  - ipv4_lpm should be applied only when IPv4 header is valid
+         *  - Good practice: apply ipv4_lpm only when the IPv4 header is valid, e.g.:
+         *      if (hdr.ipv4.isValid()) { ipv4_lpm.apply(); }
+         *    This skeleton currently applies unconditionally for the exercise.
          */
         ipv4_lpm.apply();
     }
 }
 
 /*************************************************************************
 ****************  E G R E S S   P R O C E S S I N G   *******************
+* Often used for queue marks, mirroring, or post-routing edits.          *
 *************************************************************************/
 
 control MyEgress(inout headers hdr,
@@ -128,6 +169,7 @@ control MyEgress(inout headers hdr,
 
 /*************************************************************************
 *************   C H E C K S U M    C O M P U T A T I O N   **************
+* This block shows how to compute IPv4 header checksum when needed.      *
 *************************************************************************/
 
 control MyComputeChecksum(inout headers hdr, inout metadata meta) {
@@ -153,28 +195,22 @@ control MyComputeChecksum(inout headers hdr, inout metadata meta) {
 
 /*************************************************************************
 ***********************  D E P A R S E R  *******************************
+* The deparser serializes headers back onto the packet in order.         *
 *************************************************************************/
 
 control MyDeparser(packet_out packet, in headers hdr) {
     apply {
         /*
-        Control function for deparser.
-
-        This function is responsible for constructing the output packet by appending
-        headers to it based on the input headers.
-
-        Parameters:
-        - packet: Output packet to be constructed.
-        - hdr: Input headers to be added to the output packet.
-
-        TODO: Implement the logic for constructing the output packet by appending
-        headers based on the input headers.
+        Typical implementation (left as a TODO for learners):
+            packet.emit(hdr.ethernet);
+            packet.emit(hdr.ipv4);   // per P4_16 spec, emit appends a header
+                                     // only if it is valid; no 'if' needed.
         */
     }
 }
 
 /*************************************************************************
-***********************  S W I T C H  *******************************
+***********************  S W I T C H  ***********************************
 *************************************************************************/
 
 V1Switch(