[cadcdev-svn-commits] [SCM] branch master updated. v2.0.0-1177-ge1e1bb2

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "A pseudo Operating System for the Dreamcast.".

The branch, master has been updated
       via  e1e1bb214155a01edafbda8e43bde747787955b0 (commit)
       via  2a1df86d7761232fb132416c52ce0fa124248b64 (commit)
       via  573e7ee8acd82fc99f0b9335e847cc8e4ede0635 (commit)
       via  e844c3afc86948e6a79accc06d47c72421231f4b (commit)
       via  b514025474dfd4914d03ec8d202f65a3f21babab (commit)
      from  6ffd6a1772643b0a645ee9d0a4c956eb09b133d6 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit e1e1bb214155a01edafbda8e43bde747787955b0
Merge: 2a1df86 b514025
Author: Lawrence Sebald <ljs...@us...>
Date:   Tue Nov 28 20:59:25 2023 -0500

    Merge pull request #383 from KallistiOS/wdt_doxygen_update
    
    Watchdog Timer Documentation Improvements

commit 2a1df86d7761232fb132416c52ce0fa124248b64
Merge: 6ffd6a1 573e7ee
Author: Lawrence Sebald <ljs...@us...>
Date:   Tue Nov 28 20:58:23 2023 -0500

    Merge pull request #387 from sizious/utils-update
    
    Utils: Updating `bin2o` and `elf2bin`

commit 573e7ee8acd82fc99f0b9335e847cc8e4ede0635
Author: SiZiOUS <si...@gm...>
Date:   Fri Nov 24 23:45:52 2023 +0100

    `bin2o`: removing temporary folder after processing

commit e844c3afc86948e6a79accc06d47c72421231f4b
Author: SiZiOUS <si...@gm...>
Date:   Fri Nov 24 20:37:07 2023 +0100

    `elf2bin`: updating comment inside script

commit b514025474dfd4914d03ec8d202f65a3f21babab
Author: Falco Girgis <gyr...@gm...>
Date:   Thu Nov 23 01:02:38 2023 -0600

    Updated and improved Doxygen docs for WDT.
    
    - Watchdog timer documentation had a few errors within it
    - Watchdog timer documentation lacked a proper top-level group defined
      to put it in the main module index
    - Added a reference to the WDT from the RTC

-----------------------------------------------------------------------

Summary of changes:
 kernel/arch/dreamcast/include/arch/rtc.h |   4 ++
 kernel/arch/dreamcast/include/arch/wdt.h | 104 ++++++++++++++++++++-----------
 utils/bin2o/bin2o                        |  44 +++++++++----
 utils/elf2bin/elf2bin                    |   2 +-
 4 files changed, 103 insertions(+), 51 deletions(-)

diff --git a/kernel/arch/dreamcast/include/arch/rtc.h b/kernel/arch/dreamcast/include/arch/rtc.h
index bb8c4ed..a68f7cf 100644
--- a/kernel/arch/dreamcast/include/arch/rtc.h
+++ b/kernel/arch/dreamcast/include/arch/rtc.h
@@ -15,6 +15,8 @@
     standard C functions, like time(), rather than these when simply needing
     to fetch the current system time.
 
+    \sa arch/wdt.h
+
     \author Megan Potter
     \author Falco Girgis
 */
@@ -53,6 +55,8 @@ __BEGIN_DECLS
     with an epoch of January 1, 1950 00:00. Because of this, the Dreamcast's
     Y2K and the last timestamp it can represent before rolling over is 
     February 06 2086 06:28:15.
+
+    \sa wdt
 */
 
 /** \defgroup rtc_regs Registers
diff --git a/kernel/arch/dreamcast/include/arch/wdt.h b/kernel/arch/dreamcast/include/arch/wdt.h
index 9233305..c5d6700 100644
--- a/kernel/arch/dreamcast/include/arch/wdt.h
+++ b/kernel/arch/dreamcast/include/arch/wdt.h
@@ -1,14 +1,41 @@
 /* KallistiOS ##version##
 
    arch/dreamcast/include/wdt.h
-   Copyright (c) 2023 Falco Girgis
+   Copyright (C) 2023 Falco Girgis
 
 */
 
-/** \file   arch/wdt.h
-    \brief  Watchdog Timer API
+/** \file    arch/wdt.h
+    \brief   Watchdog Timer API
+    \ingroup wdt
+
+    This file provides an API for configuring and utilizing the SH4's watchdog
+    timer as either a reset or an interval timer.
+
+    \sa timer.h, rtc.h
+
+    \author Falco Girgis
+*/
+
+#ifndef __ARCH_WDT_H
+#define __ARCH_WDT_H
+
+#include <sys/cdefs.h>
+__BEGIN_DECLS
+
+#include <stdint.h>
+
+/** \defgroup wdt   Watchdog Timer
+    \brief          Driver for using the WDT as a reset or interval timer
+
+    The watchdog timer (WDT) is a special-purpose timer peripheral integrated
+    within the Dreamcast's SH4 CPU.
+
+    \warning
+    At this time, there are no known emulators which are emulating the WDT,
+    as it was never used in commercial games; however, it works perfectly fine
+    on real hardware.
 
-    This file provides an API built around utilizing the SH4's watchdog timer.
     There are two different modes of operation which are supported:
         - watchdog mode: counter overflow causes a reset interrupt
         - interval timer mode: counter overflow invokes a callback function
@@ -16,7 +43,7 @@
     To start the WDT in watchdog mode, use wdt_enable_watchdog(). To use the 
     WDT as a general-purpose interval timer, use wdt_enable_timer().
 
-    The timer can be stopped in either mode by calling wdt_disable_timer().
+    The timer can be stopped in either mode by calling wdt_disable().
 
     \warning
     Once the WDT has been enabled, special care must be taken to disable it
@@ -25,49 +52,46 @@
     an unhandled exception (depending on which mode was used), preventing you
     from gracefully returning to a DC-Load session when testing.
 
-    \sa timer.h, rtc.h
-
-    \author Falco Girgis
+    \sa rtc
 */
 
-#ifndef __ARCH_WDT_H
-#define __ARCH_WDT_H
-
-#include <sys/cdefs.h>
-__BEGIN_DECLS
-
-#include <stdint.h>
-
-/** \brief Clock divider settings 
+/** \brief   Clock divider settings
+    \ingroup wdt
  
     Denominators used to set the frequency divider
     for the input clock to the WDT.
  */
 typedef enum WDT_CLK_DIV {
-    WDT_CLK_DIV_32,     /** \brief Period: 41us */
-    WDT_CLK_DIV_64,     /** \brief Period: 82us */
-    WDT_CLK_DIV_128,    /** \brief Period: 164us */
-    WDT_CLK_DIV_256,    /** \brief Period: 328us */
-    WDT_CLK_DIV_512,    /** \brief Period: 656us */
-    WDT_CLK_DIV_1024,   /** \brief Period: 1.31ms */
-    WDT_CLK_DIV_2048,   /** \brief Period: 2.62ms */
-    WDT_CLK_DIV_4096    /** \brief Period: 5.25ms */
+    WDT_CLK_DIV_32,     /**< \brief Period: 41us */
+    WDT_CLK_DIV_64,     /**< \brief Period: 82us */
+    WDT_CLK_DIV_128,    /**< \brief Period: 164us */
+    WDT_CLK_DIV_256,    /**< \brief Period: 328us */
+    WDT_CLK_DIV_512,    /**< \brief Period: 656us */
+    WDT_CLK_DIV_1024,   /**< \brief Period: 1.31ms */
+    WDT_CLK_DIV_2048,   /**< \brief Period: 2.62ms */
+    WDT_CLK_DIV_4096    /**< \brief Period: 5.25ms */
 } WDT_CLK_DIV;
 
-/** \brief Reset signal type
- 
+/** \brief   Reset signal type
+    \ingroup wdt
+
     Specifies the kind of reset to be performed when the WDT
     overflows in watchdog mode.
 */
 typedef enum WDT_RST {
-    WDT_RST_POWER_ON,   /** \brief Power-On Reset */
-    WDT_RST_MANUAL      /** \brief Manual Reset */
+    WDT_RST_POWER_ON,   /**< \brief Power-On Reset */
+    WDT_RST_MANUAL      /**< \brief Manual Reset */
 } WDT_RST;
 
-/* \brief WDT interval timer callback function type */
+/* \brief   WDT interval timer callback function type
+   \ingroup wdt
+
+   Type of the callback function to be passed to wdt_enable_timer().
+*/
 typedef void (*wdt_callback)(void *user_data);
 
-/** \brief  Enables the WDT as an interval timer
+/** \brief   Enables the WDT as an interval timer
+    \ingroup wdt
 
     Stops the WDT if it was previously running and reconfigures it 
     to be used as a generic interval timer, calling the given callback
@@ -100,7 +124,8 @@ void wdt_enable_timer(uint8_t initial_count,
                       wdt_callback callback,
                       void *user_data);
 
-/** \brief  Enables the WDT in watchdog mode
+/** \brief   Enables the WDT in watchdog mode
+    \ingroup wdt
 
     Stops the WDT if it was previously running and reconfigures it 
     to be used as a typical watchdog timer, generating a resest 
@@ -121,7 +146,8 @@ void wdt_enable_watchdog(uint8_t initial_count,
                          WDT_CLK_DIV clk_config,
                          WDT_RST reset_select);
 
-/** \brief  Fetches the counter value
+/** \brief   Fetches the counter value
+    \ingroup wdt
  
     Returns the current 8-bit value of the WDT counter. 
 
@@ -131,7 +157,8 @@ void wdt_enable_watchdog(uint8_t initial_count,
 */
 uint8_t wdt_get_counter(void);
 
-/** \brief  Sets the counter value
+/** \brief   Sets the counter value
+    \ingroup wdt
  
     Sets the current 8-bit value of the WDT counter.
 
@@ -141,7 +168,8 @@ uint8_t wdt_get_counter(void);
 */
 void wdt_set_counter(uint8_t value);
 
-/** \brief  Resets the counter value 
+/** \brief   Resets the counter value
+    \ingroup wdt
  
     "Petting" or "kicking" the WDT is the same thing as
     resetting its counter value to 0.
@@ -150,7 +178,8 @@ void wdt_set_counter(uint8_t value);
 */
 void wdt_pet(void);
 
-/** \brief Disables the WDT
+/** \brief   Disables the WDT
+    \ingroup wdt
     
     Disables the WDT if it was previously enabled, 
     otherwise does nothing. 
@@ -159,7 +188,8 @@ void wdt_pet(void);
 */
 void wdt_disable(void);
 
-/** \brief  Returns whether the WDT is enabled
+/** \brief   Returns whether the WDT is enabled
+    \ingroup wdt
 
     Checks to see whether the WDT has been enabled.
 
diff --git a/utils/bin2o/bin2o b/utils/bin2o/bin2o
index c0eadf8..ac43f86 100755
--- a/utils/bin2o/bin2o
+++ b/utils/bin2o/bin2o
@@ -9,12 +9,21 @@ set -o pipefail
 set -o nounset
 set -o errexit
 
+me=`basename "$0"`
+
 error() {
-        echo "bin2o:" "$@" 1>&2
+	echo "$me: error:" "$@" 1>&2
+}
+
+# Remove the temporary directory
+cleanup() {
+	if [ -d "$WORKDIR" ]; then
+		rm -r "$WORKDIR"
+	fi
 }
 
 if [ $# != 3 ]; then
-	echo "usage: $0 \<input file\> \<symbol\> \<output file\>"
+	echo "usage: $me <input.bin> <symbol> <output.o>"
 	exit 0
 fi
 
@@ -38,29 +47,38 @@ TMPFILE3="$WORKDIR/objb$$.o"
 # Gotta do a different binary target here depending on the target.
 case $KOS_ARCH in
 dreamcast)
-        # shellcheck disable=SC2086
+	# shellcheck disable=SC2086
 	echo ".section .rodata; .align 2; " | "$KOS_AS" $KOS_AFLAGS -o "$TMPFILE3"
-        # shellcheck disable=SC2181
-	if [ $? -ne 0 ]; then exit 1; fi
+	# shellcheck disable=SC2181
+	if [ $? -ne 0 ]; then
+		cleanup
+		exit 1
+	fi
 	echo "SECTIONS { .rodata : { _$2 = .; *(.data); _$2_end = .; } }" > "$TMPFILE1"
 	"$KOS_LD" --no-warn-mismatch --format binary --oformat elf32-shl "$1" --format elf32-shl "$TMPFILE3" -o "$TMPFILE2" -r -EL -T "$TMPFILE1"
-        # shellcheck disable=SC2181
-	if [ $? -ne 0 ]; then exit 1; fi
+	# shellcheck disable=SC2181
+	if [ $? -ne 0 ]; then
+		cleanup
+		exit 1
+	fi
 	"$KOS_OBJCOPY" --set-section-flags .rodata=alloc,load,data,readonly "$TMPFILE2" "$3"
-        ;;
+	;;
 
 gba)
 	echo "SECTIONS { .rodata : { $2 = .; *(.data); $2_end = .; } }" > "$WORKDIR/script.ld"
 	"$KOS_LD" --no-warn-mismatch --format binary --oformat elf32-littlearm "$1" -o "$3" -r -EL -T "$WORKDIR/script.ld"
-        ;;
+	;;
 
 ps2)
 	echo "OUTPUT_ARCH(mips:5900) SECTIONS { .rodata : { _$2 = .; *(.data); _$2_end = .; } }" > "$WORKDIR/script.ld"
 	"$KOS_LD" --no-warn-mismatch --format binary --oformat elf64-littlemips -mips3 "$1" -o "$3" -r -EL -T "$WORKDIR/script.ld"
-        ;;
+	;;
 
 *)
-        error "unsupported architecture \"$KOS_ARCH\""
-        exit 1
-        ;;
+	error "unsupported architecture \"$KOS_ARCH\""
+	cleanup
+	exit 1
+	;;
 esac
+
+cleanup
diff --git a/utils/elf2bin/elf2bin b/utils/elf2bin/elf2bin
index b4ffbfa..2d6f7a5 100644
--- a/utils/elf2bin/elf2bin
+++ b/utils/elf2bin/elf2bin
@@ -3,7 +3,7 @@
 # elf2bin
 # script to convert an elf program to a bin(ary) program
 # then you can use 'scramble' to generate a '1ST_READ.BIN' file
-# this script is basically using 'strip' and 'objcopy'.
+# this script is basically a simplified 'kos-objcopy'.
 
 me=`basename "$0"`
 


hooks/post-receive
-- 
A pseudo Operating System for the Dreamcast.


