Menu
▾
▴
[cadcdev-svn-commits] [SCM] branch master updated. v2.0.0-1084-g8bce82f
|
From: ljsebald <ljs...@us...> - 2023-10-16 03:13:09
|
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 8bce82fca68ebfcba54214a1122197b7464dd2d3 (commit)
via 0fd20ba7903f0c8349135715f456af744bf38ae0 (commit)
via 4277fc0ed0e1e2a637a5f717903a8f9dbd234559 (commit)
from 3e3b43cf757098c84cf4e67681a02ef3901c6cc8 (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 8bce82fca68ebfcba54214a1122197b7464dd2d3
Author: Falco Girgis <gyr...@gm...>
Date: Sun Oct 15 22:12:07 2023 -0500
Doxygen Cleanup/Centralization for Threading APIs (#319)
* Doxygen cleanup for threading APIs
- Cleaned up Doxygen documentation for
a. kthreads
b. C11 threads
c. pthreads
- Put everything relating to concurrency within a top-level "threading"
module/group, which is located in doc/pages/threading.dox
- Changed groups of related #defines from "modules" to just anonymous
groups which keeps them under their respective headers
- Marked everything with the _depr() attribute as deprecated within
Doxygen
* Addressed code review feedback
commit 0fd20ba7903f0c8349135715f456af744bf38ae0
Merge: 3e3b43c 4277fc0
Author: Lawrence Sebald <ljs...@us...>
Date: Sun Oct 15 23:10:18 2023 -0400
Merge pull request #322 from KallistiOS/matrix_alignment
Enforced matrix alignment, matrix ASM cleanup
commit 4277fc0ed0e1e2a637a5f717903a8f9dbd234559
Author: Falco Girgis <gyr...@gm...>
Date: Wed Oct 11 12:04:18 2023 -0500
Enforced matrix alignment, matrix ASM cleanup
1) Enforcing alignment for matrix_t types, so we stop getting unaligned
access crashes (at least for things not on the heap)
2) Minor formatting and stylistic changes to vector and matrix
assembly routines
- consistent spacing between operands
- normalized spaces vs tabs
3) Added doxygen warnings and notes for required and optimal alignments
-----------------------------------------------------------------------
Summary of changes:
doc/Doxyfile | 5 +-
doc/pages/threading.dox | 23 +
include/kos/cond.h | 4 +-
include/kos/genwait.h | 1 +
include/kos/mutex.h | 5 +-
include/kos/once.h | 1 +
include/kos/recursive_lock.h | 13 +-
include/kos/rwsem.h | 2 +
include/kos/sem.h | 2 +
include/kos/thread.h | 62 +-
include/kos/tls.h | 1 +
include/pthread.h | 1 +
include/threads.h | 9 +-
kernel/arch/dreamcast/include/dc/matrix.h | 18 +
kernel/arch/dreamcast/include/dc/vec3f.h | 2 +-
kernel/arch/dreamcast/include/dc/vector.h | 8 +-
kernel/arch/dreamcast/math/matrix.s | 910 +++++++++++++++---------------
kernel/arch/dreamcast/math/matrix3d.c | 2 +-
18 files changed, 555 insertions(+), 514 deletions(-)
create mode 100644 doc/pages/threading.dox
diff --git a/doc/Doxyfile b/doc/Doxyfile
index 35a0a9f..21baf29 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -475,7 +475,7 @@ LOOKUP_CACHE_SIZE = 0
# DOT_NUM_THREADS setting.
# Minimum value: 0, maximum value: 32, default value: 1.
-NUM_PROC_THREADS = 1
+NUM_PROC_THREADS = 0
#---------------------------------------------------------------------------
# Build related configuration options
@@ -910,7 +910,8 @@ WARN_LOGFILE =
INPUT = $(KOS_BASE)/include \
$(KOS_BASE)/kernel/arch/$(KOS_ARCH)/include \
$(KOS_BASE)/addons/include \
- $(KOS_BASE)/README.md
+ $(KOS_BASE)/README.md \
+ $(KOS_BASE)/doc/pages
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/doc/pages/threading.dox b/doc/pages/threading.dox
new file mode 100644
index 0000000..4fdcbe2
--- /dev/null
+++ b/doc/pages/threading.dox
@@ -0,0 +1,23 @@
+/** \defgroup threading Threading
+ \brief Threading and Concurrency
+
+ KOS offers a variety of different threading APIs, ranging from low-level
+ and platform-specific to high-level and cross-platform. Which you should
+ choose to interface with depends on the needs of your particular
+ application.
+
+ API |Description
+ -------------|-----------------------------------------
+ kthreads |Dreamcast-specific direct threading API
+ C11 threads |Cross-platform builtin C threading API
+ C++11 threads|Cross-platform builtin C++ threading API
+ pthreads |Cross-platform POSIX threading API
+
+ KOS's kthreads are the lowest-level threading back-end, with C11, C++11,
+ and POSIX threading APIs being thin layers of abstraction built upon
+ them. If you're writing a Dreamcast-specific application, kthreads
+ will give you the least indirection; however, if you're writing a
+ cross-platform application or simply want to use an API that you're
+ familiar with, one of the other cross-platform APIs may be preferable.
+
+*/
diff --git a/include/kos/cond.h b/include/kos/cond.h
index 5bccfa5..9a4df11 100644
--- a/include/kos/cond.h
+++ b/include/kos/cond.h
@@ -1,12 +1,13 @@
/* KallistiOS ##version##
include/kos/cond.h
- Copyright (C)2001,2003 Megan Potter
+ Copyright (C) 2001, 2003 Megan Potter
*/
/** \file kos/cond.h
\brief Condition variables.
+ \ingroup kthreads
This file contains the definition of a Condition Variable. Condition
Variables (or condvars for short) are used with a mutex to act as a lock and
@@ -70,6 +71,7 @@ typedef struct condvar {
This function allocates and initializes a new condition variable for use.
+ \deprecated
This function is formally deprecated and should not be used in new code.
Instead you should use either the static initializer or the cond_init()
function.
diff --git a/include/kos/genwait.h b/include/kos/genwait.h
index 720f0d7..e7462ad 100644
--- a/include/kos/genwait.h
+++ b/include/kos/genwait.h
@@ -8,6 +8,7 @@
/** \file kos/genwait.h
\brief Generic wait system.
+ \ingroup kthreads
The generic wait system in KOS, like many other portions of KOS, is based on
an idea from the BSD kernel. It allows you to sleep on any random object and
diff --git a/include/kos/mutex.h b/include/kos/mutex.h
index 5a2f936..d0ba5ce 100644
--- a/include/kos/mutex.h
+++ b/include/kos/mutex.h
@@ -8,6 +8,7 @@
/** \file kos/mutex.h
\brief Mutual exclusion locks.
+ \ingroup kthreads
This file defines mutual exclusion locks (or mutexes for short). The concept
of a mutex is one of the most common types of locks in a multi-threaded
@@ -71,7 +72,8 @@ typedef struct kos_mutex {
int count;
} mutex_t;
-/** \defgroup mutex_types Mutex types
+/** \name Mutex types
+ \brief Types of Mutexes supported by KOS
The values defined in here are the various types of mutexes that KallistiOS
supports.
@@ -98,6 +100,7 @@ typedef struct kos_mutex {
/** \brief Allocate a new mutex.
+ \deprecated
This function allocates and initializes a new mutex for use. This function
will always create mutexes of the type MUTEX_TYPE_NORMAL.
diff --git a/include/kos/once.h b/include/kos/once.h
index 5bdcc9f..a0f2585 100644
--- a/include/kos/once.h
+++ b/include/kos/once.h
@@ -10,6 +10,7 @@
/** \file kos/once.h
\brief Dynamic package initialization.
+ \ingroup kthreads
This file provides definitions for an object that functions the same way as
the pthread_once_t function does from the POSIX specification. This object
diff --git a/include/kos/recursive_lock.h b/include/kos/recursive_lock.h
index e22d982..bace334 100644
--- a/include/kos/recursive_lock.h
+++ b/include/kos/recursive_lock.h
@@ -7,12 +7,14 @@
/** \file kos/recursive_lock.h
\brief Definitions for a recursive mutex.
+ \ingroup kthreads
This file defines a recursive lock mechanism, similar to a mutex, but that a
single thread can obtain as many times as it wants. A single thread is still
limited to holding the lock at a time, but it can hold it an "unlimited"
number of times (actually limited to INT_MAX, but who's counting).
+ \deprecated
These are now just wrappers around the MUTEX_TYPE_RECURSIVE that is now
provided and will be removed at some point in the future. Please update your
code to use that type instead.
@@ -40,6 +42,7 @@ typedef mutex_t recursive_lock_t;
/** \brief Allocate a new recursive lock.
+ \deprecated
This function allocates a new recurisve lock that is initially not locked.
\return The created lock, or NULL on failure (errno will be set to ENOMEM to
@@ -49,6 +52,7 @@ recursive_lock_t *rlock_create(void) __depr("Use mutexes instead.");
/** \brief Destroy a recursive lock.
+ \deprecated
This function cleans up a recursive lock. It is an error to attempt to
destroy a locked recursive lock.
@@ -57,7 +61,8 @@ recursive_lock_t *rlock_create(void) __depr("Use mutexes instead.");
void rlock_destroy(recursive_lock_t *l) __depr("Use mutexes instead.");
/** \brief Lock a recursive lock.
-
+
+ \deprecated
This function attempts to lock the requested lock, and if it cannot it will
block until that is possible.
@@ -72,6 +77,7 @@ int rlock_lock(recursive_lock_t *l) __depr("Use mutexes instead.");
/** \brief Lock a recursive lock (with a timeout).
+ \deprecated
This function attempts to lock the requested lock, and if it cannot it will
block until either it is possible to acquire the lock or timeout
milliseconds have elapsed.
@@ -91,6 +97,7 @@ int rlock_lock_timed(recursive_lock_t *l, int timeout)
/** \brief Unlock a recursive lock.
+ \deprecated
This function releases the lock one time from the current thread.
\param l The recursive lock to unlock.
@@ -102,6 +109,7 @@ int rlock_unlock(recursive_lock_t *l) __depr("Use mutexes instead.");
/** \brief Attempt to lock a recursive lock without blocking.
+ \deprecated
This function attempts to lock a recursive lock without blocking. This
function, unlike rlock_lock and rlock_lock_timed is safe to call inside an
interrupt.
@@ -116,7 +124,8 @@ int rlock_unlock(recursive_lock_t *l) __depr("Use mutexes instead.");
int rlock_trylock(recursive_lock_t *l) __depr("Use mutexes instead.");
/** \brief Check if a recursive lock is currently held by any thread.
-
+
+ \deprecated
This function checks whether or not a lock is currently held by any thread,
including the calling thread. Note that this is <b>NOT</b> a safe way to
check if a lock <em>will</em> be held by the time you get around to locking
diff --git a/include/kos/rwsem.h b/include/kos/rwsem.h
index 0995375..471a5c4 100644
--- a/include/kos/rwsem.h
+++ b/include/kos/rwsem.h
@@ -7,6 +7,7 @@
/** \file kos/rwsem.h
\brief Definition for a reader/writer semaphore.
+ \ingroup kthreads
This file defines a concept of reader/writer semaphores. Basically, this
type of lock allows an unlimited number of "readers" to acquire the lock at
@@ -61,6 +62,7 @@ typedef struct rw_semaphore {
This function allocates a new reader/writer lock that is initially not
locked either for reading or writing.
+ \deprecated
This function is formally deprecated, and should not be used in newly
written code. Instead, please use rwsem_init().
diff --git a/include/kos/sem.h b/include/kos/sem.h
index 19705a6..f88135b 100644
--- a/include/kos/sem.h
+++ b/include/kos/sem.h
@@ -8,6 +8,7 @@
/** \file kos/sem.h
\brief Semaphores.
+ \ingroup kthreads
This file defines semaphores. A semaphore is a synchronization primitive
that allows a spcified number of threads to be in its critical section at a
@@ -46,6 +47,7 @@ typedef struct semaphore {
This function allocates and initializes a new semaphore for use.
+ \deprecated
This function is formally deprecated. Please update your code to use
sem_init() or static initialization with SEM_INITIALIZER instead.
diff --git a/include/kos/thread.h b/include/kos/thread.h
index 6a74ecb..c57004f 100644
--- a/include/kos/thread.h
+++ b/include/kos/thread.h
@@ -23,7 +23,7 @@ __BEGIN_DECLS
/** \file kos/thread.h
\brief Threading support.
- \ingroup threads
+ \ingroup kthreads
This file contains the interface to the threading system of KOS. Timer
interrupts are used to reschedule threads within the system.
@@ -41,8 +41,9 @@ __BEGIN_DECLS
\see kos/tls.h
*/
-/** \defgroup threads Threads
- \brief Threading API
+/** \defgroup kthreads KThreads
+ \brief KOS Native Threading API
+ \ingroup threading
The thread scheduler itself is a relatively simplistic priority scheduler.
There is no provision for priorities to erode over time, so keep that in
@@ -68,7 +69,6 @@ __BEGIN_DECLS
*/
/** \brief Maximal thread priority.
- \ingroup threads
This macro defines the maximum value for a thread's priority. Note that the
larger this number, the lower the priority of the thread.
@@ -76,14 +76,12 @@ __BEGIN_DECLS
#define PRIO_MAX 4096
/** \brief Default thread priority.
- \ingroup threads
Threads are created by default with the priority specified.
*/
#define PRIO_DEFAULT 10
/** \brief Size of a kthread's label
- \ingroup threads
Maximum number of characters in a thread's label or name
(including NULL terminator).
@@ -91,7 +89,6 @@ __BEGIN_DECLS
#define KTHREAD_LABEL_SIZE 256
/** \brief Size of a kthread's current directory
- \ingroup threads
Maximum number of characters in a thread's current working
directory (including NULL terminator).
@@ -107,7 +104,6 @@ LIST_HEAD(ktlist, kthread);
/* \endcond */
/** \brief Control Block Header
- \ingroup threads
Header preceeding the static TLS data segments as defined by
the SH-ELF TLS ABI (version 1). This is what the thread pointer
@@ -119,7 +115,6 @@ typedef struct tcbhead {
} tcbhead_t;
/** \brief Structure describing one running thread.
- \ingroup threads
Each thread has one of these structures assigned to it, which holds all the
data associated with the thread. There are various functions to manipulate
@@ -209,8 +204,8 @@ typedef struct kthread {
void *rv;
} kthread_t;
-/** \defgroup thd_flags Thread flag values
- \ingroup threads
+/** \name Thread flag values
+ \brief kthread_t::flags values
These are possible values for the flags field on the kthread_t structure.
These can be ORed together.
@@ -223,8 +218,8 @@ typedef struct kthread {
#define THD_DETACHED 4 /**< \brief Thread is detached */
/** @} */
-/** \defgroup thd_states Thread states
- \ingroup threads
+/** \name Thread states
+ \brief kthread_t::state values
Each thread in the system is in exactly one of this set of states.
@@ -238,7 +233,6 @@ typedef struct kthread {
/** @} */
/** \brief Thread creation attributes.
- \ingroup threads
This structure allows you to specify the various attributes for a thread to
have when it is created. These can only be modified (in general) at thread
@@ -268,8 +262,8 @@ typedef struct kthread_attr {
const char *label;
} kthread_attr_t;
-/** \defgroup thd_modes Threading system modes
- \ingroup threads
+/** \name Threading system modes
+ \brief kthread mode values
The threading system will always be in one of the following modes. This
represents either pre-emptive scheduling or an un-initialized state.
@@ -282,7 +276,6 @@ typedef struct kthread_attr {
/** @} */
/** \brief The currently executing thread.
- \ingroup threads
\warning
Do not manipulate this variable directly!
@@ -292,7 +285,6 @@ typedef struct kthread_attr {
extern kthread_t *thd_current;
/** \brief Block the current thread.
- \ingroup threads
Blocks the calling thread and performs a reschedule as if a context switch
timer had been executed. This is useful for, e.g., blocking on sync
@@ -309,7 +301,6 @@ extern kthread_t *thd_current;
int thd_block_now(irq_context_t *mycxt);
/** \brief Find a new thread to swap in.
- \ingroup threads
This function looks at the state of the system and returns a new thread
context to swap in. This is called from thd_block_now() and from the
@@ -324,7 +315,6 @@ int thd_block_now(irq_context_t *mycxt);
irq_context_t *thd_choose_new(void);
/** \brief Given a thread ID, locates the thread structure.
- \ingroup threads
\relatesalso kthread_t
\param tid The thread ID to retrieve.
@@ -334,7 +324,6 @@ irq_context_t *thd_choose_new(void);
kthread_t *thd_by_tid(tid_t tid);
/** \brief Enqueue a process in the runnable queue.
- \ingroup threads
\relatesalso kthread_t
This function adds a thread to the runnable queue after the process group of
@@ -351,7 +340,6 @@ kthread_t *thd_by_tid(tid_t tid);
void thd_add_to_runnable(kthread_t *t, int front_of_line);
/** \brief Removes a thread from the runnable queue, if it's there.
- \ingroup threads
\relatesalso kthread_t
This function removes a thread from the runnable queue, if it is currently
@@ -367,7 +355,6 @@ void thd_add_to_runnable(kthread_t *t, int front_of_line);
int thd_remove_from_runnable(kthread_t *thd);
/** \brief Create a new thread.
- \ingroup threads
\relatesalso kthread_t
This function creates a new kernel thread with default parameters to run the
@@ -387,7 +374,7 @@ int thd_remove_from_runnable(kthread_t *thd);
kthread_t *thd_create(int detach, void *(*routine)(void *param), void *param);
/** \brief Create a new thread with the specified set of attributes.
- \ingroup threads
+ \relatesalso kthread_t
This function creates a new kernel thread with the specified set of
parameters to run the given routine.
@@ -406,7 +393,6 @@ kthread_t *thd_create_ex(const kthread_attr_t *__RESTRICT attr,
void *(*routine)(void *param), void *param);
/** \brief Brutally kill the given thread.
- \ingroup threads
\relatesalso kthread_t
This function kills the given thread, removing it from the execution chain,
@@ -424,7 +410,6 @@ kthread_t *thd_create_ex(const kthread_attr_t *__RESTRICT attr,
int thd_destroy(kthread_t *thd);
/** \brief Exit the current thread.
- \ingroup threads
This function ends the execution of the current thread, removing it from all
execution queues. This function will never return to the thread. Returning
@@ -435,7 +420,6 @@ int thd_destroy(kthread_t *thd);
void thd_exit(void *rv) __noreturn;
/** \brief Force a thread reschedule.
- \ingroup threads
This function is the thread scheduler, and is generally called from a timer
interrupt. You will most likely never have a reason to call this function
@@ -455,7 +439,6 @@ void thd_exit(void *rv) __noreturn;
void thd_schedule(int front_of_line, uint64_t now);
/** \brief Force a given thread to the front of the queue.
- \ingroup threads
\relatesalso kthread_t
This function promotes the given thread to be the next one that will be
@@ -465,7 +448,6 @@ void thd_schedule(int front_of_line, uint64_t now);
void thd_schedule_next(kthread_t *thd);
/** \brief Throw away the current thread's timeslice.
- \ingroup threads
This function manually yields the current thread's timeslice to the system,
forcing a reschedule to occur.
@@ -473,7 +455,6 @@ void thd_schedule_next(kthread_t *thd);
void thd_pass(void);
/** \brief Sleep for a given number of milliseconds.
- \ingroup threads
This function puts the current thread to sleep for the specified amount of
time. The thread will be removed from the runnable queue until the given
@@ -486,7 +467,6 @@ void thd_pass(void);
void thd_sleep(int ms);
/** \brief Set a thread's priority value.
- \ingroup threads
\relatesalso kthread_t
This function is used to change the priority value of a thread. If the
@@ -503,7 +483,6 @@ void thd_sleep(int ms);
int thd_set_prio(kthread_t *thd, prio_t prio);
/** \brief Retrieve the current thread's kthread struct.
- \ingroup threads
...<truncated>...
hooks/post-receive
--
A pseudo Operating System for the Dreamcast.
|
