From 6cc6f530b5c39e854d24ded45ebe4127e817ff2f Mon Sep 17 00:00:00 2001
From: "Luke T. Shumaker" <lukeshu@lukeshu.com>
Date: Sat, 19 Oct 2024 17:40:55 -0600
Subject: w5500: Tidy comments

---
 cmd/sbc_harness/hw/w5500.c    | 39 ++++++++++++++++++++++++++++++++++-----
 cmd/sbc_harness/hw/w5500_ll.h | 11 +++++++----
 2 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/cmd/sbc_harness/hw/w5500.c b/cmd/sbc_harness/hw/w5500.c
index 7bd2fde..bfeacee 100644
--- a/cmd/sbc_harness/hw/w5500.c
+++ b/cmd/sbc_harness/hw/w5500.c
@@ -3,11 +3,11 @@
  * Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
  * SPDX-Licence-Identifier: AGPL-3.0-or-later
  *
+ * -----------------------------------------------------------------------------
  * https://github.com/Wiznet/ioLibrary_Driver/blob/b981401e7f3d07015619adf44c13998e13e777f9/Ethernet/wizchip_conf.c
  * https://github.com/Wiznet/ioLibrary_Driver/blob/b981401e7f3d07015619adf44c13998e13e777f9/Ethernet/W5500/w5500.h
- * https://github.com/Wiznet/ioLibrary_Driver/blob/b981401e7f3d07015619adf44c13998e13e777f9/socket.c
- *
- * SPDX-Licence-Identifier: BSD-3-Clause
+ * https://github.com/Wiznet/ioLibrary_Driver/blob/b981401e7f3d07015619adf44c13998e13e777f9/Ethernet/W5500/w5500.c
+ * https://github.com/Wiznet/ioLibrary_Driver/blob/b981401e7f3d07015619adf44c13998e13e777f9/Ethernet/socket.c
  *
  * Copyright (c)  2013, WIZnet Co., LTD.
  * All rights reserved.
@@ -36,13 +36,42 @@
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * SPDX-Licence-Identifier: BSD-3-Clause
+ *
+ * -----------------------------------------------------------------------------
+ * https://github.com/Wiznet/ioLibrary_Driver/blob/b981401e7f3d07015619adf44c13998e13e777f9/license.txt
+ *
+ * Copyright (c) 2014 WIZnet Co.,Ltd.
+ * Copyright (c) WIZnet ioLibrary Project.
+ * All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-Licence-Identifier: MIT
  */
 
 #include <pico/time.h>     /* for sleep_ms() */
 #include <hardware/gpio.h> /* pico-sdk:hardware_gpio */
 
-#include <libcr/coroutine.h>
-#include <libmisc/vcall.h>
+#include <libcr/coroutine.h> /* for cr_yield() */
+#include <libmisc/vcall.h>   /* for VCALL_SELF() */
 
 #include "hw/w5500_ll.h"
 #include "hw/w5500.h"
diff --git a/cmd/sbc_harness/hw/w5500_ll.h b/cmd/sbc_harness/hw/w5500_ll.h
index 4a08a6e..b0a023a 100644
--- a/cmd/sbc_harness/hw/w5500_ll.h
+++ b/cmd/sbc_harness/hw/w5500_ll.h
@@ -1,4 +1,7 @@
-/* hw/w5500_ll.h - Low-level W5500 header-only library
+/* hw/w5500_ll.h - Low-level header library for the WIZnet W5500 chip
+ *
+ * Based entirely on the W5500 datasheet, v1.1.0.
+ * https://docs.wiznet.io/img/products/w5500/W5500_ds_v110e.pdf
  *
  * Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
  * SPDX-Licence-Identifier: AGPL-3.0-or-later
@@ -278,12 +281,12 @@ static_assert(sizeof(struct w5500ll_block_sock_reg) == 0x30);
  *     ┃                              ║           V ┃┃ V                                           ┃
  *     ┃                              ╠═══════════╝ ┃┃ ╚═══════════╗                               ┃
  *     ┃                         (CMD_DISCON)       ┃┃             ║                               ┃
- *     ┃  Both sides sent    ┌┈┈┈<(send FIN)>┈┈┈┈┈┈┐┃┃             ║                               ┃
+ *     ┃   Both sides sent   ┌┈┈┈<(send FIN)>┈┈┈┈┈┈┐┃┃             ║                               ┃
  *     ┃  FIN at the "same"  ┊        V            └┃┃┈┈┈┈┈┈┈┈>(recv FIN)                          ┃
  *     ┃   time; both are    ┊  ┌────────────┐     ┌┃┃┈┈┈┈┈┈┈┈<(send ACK)                          ┃
  *     ┃   active closers    ┊  │ FIN_WAIT_1 │     ┊┃┃             V                               ┃
- *     ┃        / \          ┊  └────────────┘     ┊┃┃      ┌────────────┐                         ┃
- *     ┃ ,-----'   '-----,   ┊     V     V         ┊┃┃      │ CLOSE_WAIT │                         ┃
+ *     ┃         / \         ┊  └────────────┘     ┊┃┃      ┌────────────┐                         ┃
+ *     ┃ ,------'   '------, ┊     V     V         ┊┃┃      │ CLOSE_WAIT │                         ┃
  *     ┃          ╔════════════════╝     ║         ┊┃┃      └────────────┘                         ┃
  *     ┃      (recv FIN)<┈┈┈┈┤        ╔══╝         ┊┃┃             V                               ┃
  *     ┃  ┌┈┈<(send ACK)>┈┈┐ ┊        ║            ┊┃┃             ║                               ┃
-- 
cgit v1.2.3-2-g168b