[wol HLD] Extend wol to support sending magic pattern in udp payload

doc/wol/Wake-on-LAN-HLD.md

@@ -16,6 +16,7 @@
 | Revision | Date       | Author     | Change Description |
 | -------- | ---------- | ---------- | ------------------ |
 | 1.0      | Nov 7 2023 | Zhijian Li | Initial proposal   |
+| 1.1      | Oct 11 2024 | Wenda Chu | extend wol by udp packet|
 
 ## Definitions/Abbreviations 
 
@@ -59,6 +60,9 @@ A new gNOI service `SONiCWolService` will be implemented in sonic-gnmi container
 
 ## Magic Packet
 
+Although the magic pattern is fixed which is a frame has 6 bytes of 0xFF, 16 repetitions of target mac and optional password bytes, we provide two flavours for uses, one is magic pattern in ethernet payload, another is magic pattern in UDP payload.
+
+### Magic Pattern in Ethernet Payload
 **Magic Packet** is a Ethernet frame with structure:
 
 * **Ethernet Frame Header**:
@@ -88,19 +92,56 @@ Offset   |0     |1     |2     |3     |4     |5     |
          +-----------------------------------------+
 ```
 
+### Magic Pattern in UDP Payload
+**Magic Packet** is a Ethernet frame with structure:
+
+* **IP Header**:
+  * **Destination IP**: user provided target IP address, cloud be IPv4 address or IPv6 address, default is `255.255.255.255`.
+* **UDP Header**:
+  * **Destination Port**: user provided target port, default is 9.
+* **UDP Payload**:
+  * Six bytes of all `0xff`. [6 bytes]
+  * Sixteen repetitions of the target device's MAC address. [96 bytes]
+  * (Optional) A four or six byte password. [4 or 6 bytes]
+
+```
+Byte     |
+Offset   |0     |1     |2     |3     |4     |5     |
+---------+------+------+------+------+------+------+
+           \      \      \      \      \      \     
+         +------+------+------+------+------+------+
+         |.. Destination IP(4 bytes or 16 bytes) ..|
+         +------+------+------+------+------+------+      
+           \      \      \      \      \      \      
+         +------+------+---------------------------+
+         |  ... Destination Port(2 bytes) ...      |   
+         +------+------+---------------------------+
+           \      \      \      \      \      \      
+         +------+------+------+------+------+------+------------------------------
+       N | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF |
+         +------+------+------+------+------+------+           UDP
+     N+6 | Target MAC (repeat 16 times, 96 bytes)  |           PAYLOAD
+         +-----------------------------------------+
+   N+102 |    Password (optional, 4 or 6 bytes)    |
+         +-----------------------------------------+
+```
+
 ## CLI Design
 
 The `wol` command is used to send magic packet to target device.
 
 ### Usage
 
 ```
-wol <interface> <target_mac> [-b] [-p password] [-c count] [-i interval]
+wol <interface> <target_mac> [-b] [-u] [-a ip-address] [-t udp-port] [-p password] [-c count] [-i interval]
 ```
 
 - `interface`: SONiC interface name.
 - `target_mac`: a list of target devices' MAC address, separated by comma.
 - `-b`: Use broadcast MAC address instead of target device's MAC address as **Destination MAC Address in Ethernet Frame Header**.
+- `-u`: Let device send magic pattern in udp payload, when this flag was used, -b won't work and destination mac is set by device's networking stack.
+- `-a ip-address`: This parameter only work when -u flag was used. Let device send packet to the ip address, this ip address cloud IPv4 address or IPv6 address.
+- `-t udp-port`: This parameter only work when -u flag was used. Let device send packet to the udp port.
 - `-p password`: An optional 4 or 6 byte password, in ethernet hex format or quad-dotted decimal[^3].
 - `-c count`: For each target MAC address, the `count` of magic packets to send. `count` must between 1 and 5. Default value is 1. This param must use with `-i`.
 - `-i interval`: Wait `interval` milliseconds between sending each magic packet. `interval` must between 0 and 2000. Default value is 0. This param must use with `-c`.
@@ -112,11 +153,15 @@ admin@sonic:~$ wol Ethernet10 00:11:22:33:44:55
 admin@sonic:~$ wol Ethernet10 00:11:22:33:44:55 -b
 admin@sonic:~$ wol Vlan1000 00:11:22:33:44:55,11:33:55:77:99:bb -p 00:22:44:66:88:aa
 admin@sonic:~$ wol Vlan1000 00:11:22:33:44:55,11:33:55:77:99:bb -p 192.168.1.1 -c 3 -i 2000
+admin@sonic:~$ wol Vlan1000 00:11:22:33:44:55,11:33:55:77:99:bb -u
+admin@sonic:~$ wol Vlan1000 00:11:22:33:44:55,11:33:55:77:99:bb -u -c 3 -i 2000
+admin@sonic:~$ wol Vlan1000 00:11:22:33:44:55,11:33:55:77:99:bb -u -a 192.168.255.255
+admin@sonic:~$ wol Vlan1000 00:11:22:33:44:55,11:33:55:77:99:bb -u -a 192.168.255.255 -t 7
 ```
 
 For the 4th example, it specifise 2 target MAC addresses and `count` is 3. So it'll send 6 magic packets in total.
 
-## gNOI Design
+## gNOI Design ( gNOI only support magic pattern in ethernet payload. )
 
 The gNOI service `SONiCWolService` will provide a `Wol` interface to user, which can be called to send magic packet to target device:
 
@@ -161,6 +206,8 @@ message WolResponse {
 | Input valid `count` and `interval`. | Parameter validation pass, send magic packet |
 | Input value of `count` or `interval` is out of range. | Parameter validation Fail |
 | Param `count` and `interval` not appear in input together. | Parameter validation Fail |
+| Param `-b` and `-u` not appear in input together. | Parameter validation Fail |
+| Param `-u` is required when using `-a ip-address` or `-t udp-port`. | Parameter validation Fail |
 | Mock a send magic packet failure (e.g., socket error) | Return user friendly error message |
 
 ### Functional Test