From: Byungchul Park <byungchul@sk.com>
To: linux-kernel@vger.kernel.org
Cc: kernel_team@skhynix.com, torvalds@linux-foundation.org,
damien.lemoal@opensource.wdc.com, linux-ide@vger.kernel.org,
adilger.kernel@dilger.ca, linux-ext4@vger.kernel.org,
mingo@redhat.com, peterz@infradead.org, will@kernel.org,
tglx@linutronix.de, rostedt@goodmis.org, joel@joelfernandes.org,
sashal@kernel.org, daniel.vetter@ffwll.ch, duyuyang@gmail.com,
johannes.berg@intel.com, tj@kernel.org, tytso@mit.edu,
willy@infradead.org, david@fromorbit.com, amir73il@gmail.com,
gregkh@linuxfoundation.org, kernel-team@lge.com,
linux-mm@kvack.org, akpm@linux-foundation.org, mhocko@kernel.org,
minchan@kernel.org, hannes@cmpxchg.org, vdavydov.dev@gmail.com,
sj@kernel.org, jglisse@redhat.com, dennis@kernel.org,
cl@linux.com, penberg@kernel.org, rientjes@google.com,
vbabka@suse.cz, ngupta@vflare.org, linux-block@vger.kernel.org,
josef@toxicpanda.com, linux-fsdevel@vger.kernel.org,
jack@suse.cz, jlayton@kernel.org, dan.j.williams@intel.com,
hch@infradead.org, djwong@kernel.org,
dri-devel@lists.freedesktop.org, rodrigosiqueiramelo@gmail.com,
melissa.srw@gmail.com, hamohammed.sa@gmail.com,
42.hyeyoo@gmail.com, chris.p.wilson@intel.com,
gwan-gyeong.mun@intel.com, max.byungchul.park@gmail.com,
boqun.feng@gmail.com, longman@redhat.com, hdanton@sina.com,
her0gyugyu@gmail.com
Subject: [PATCH v14 28/28] dept: Add documentation for Dept's APIs
Date: Wed, 8 May 2024 18:47:25 +0900 [thread overview]
Message-ID: <20240508094726.35754-29-byungchul@sk.com> (raw)
In-Reply-To: <20240508094726.35754-1-byungchul@sk.com>
This document describes the APIs of Dept.
Signed-off-by: Byungchul Park <byungchul@sk.com>
---
Documentation/dependency/dept_api.txt | 117 ++++++++++++++++++++++++++
1 file changed, 117 insertions(+)
create mode 100644 Documentation/dependency/dept_api.txt
diff --git a/Documentation/dependency/dept_api.txt b/Documentation/dependency/dept_api.txt
new file mode 100644
index 000000000000..8e0d5a118a46
--- /dev/null
+++ b/Documentation/dependency/dept_api.txt
@@ -0,0 +1,117 @@
+DEPT(DEPendency Tracker) APIs
+=============================
+
+Started by Byungchul Park <max.byungchul.park@sk.com>
+
+SDT(Single-event Dependency Tracker) APIs
+-----------------------------------------
+Use these APIs to annotate on either wait or event. These have been
+already applied into the existing synchronization primitives e.g.
+waitqueue, swait, wait_for_completion(), dma fence and so on. The basic
+APIs of SDT are:
+
+ /*
+ * After defining 'struct dept_map map', initialize the instance.
+ */
+ sdt_map_init(map);
+
+ /*
+ * Place just before the interesting wait.
+ */
+ sdt_wait(map);
+
+ /*
+ * Place just before the interesting event.
+ */
+ sdt_event(map);
+
+The advanced APIs of SDT are:
+
+ /*
+ * After defining 'struct dept_map map', initialize the instance
+ * using an external key.
+ */
+ sdt_map_init_key(map, key);
+
+ /*
+ * Place just before the interesting timeout wait.
+ */
+ sdt_wait_timeout(map, time);
+
+ /*
+ * Use sdt_might_sleep_start() and sdt_might_sleep_end() in pair.
+ * Place at the start of the interesting section that might enter
+ * schedule() or its family that needs to be woken up by
+ * try_to_wake_up().
+ */
+ sdt_might_sleep_start(map);
+
+ /*
+ * Use sdt_might_sleep_start_timeout() and sdt_might_sleep_end() in
+ * pair. Place at the start of the interesting section that might
+ * enter schedule_timeout() or its family that needs to be woken up
+ * by try_to_wake_up().
+ */
+ sdt_might_sleep_start_timeout(map, time);
+
+ /*
+ * Use sdt_might_sleep_start() and sdt_might_sleep_end() in pair.
+ * Place at the end of the interesting section that might enter
+ * schedule(), schedule_timeout() or its family that needs to be
+ * woken up by try_to_wake_up().
+ */
+ sdt_might_sleep_end();
+
+ /*
+ * Use sdt_ecxt_enter() and sdt_ecxt_exit() in pair. Place at the
+ * start of the interesting section where the interesting event might
+ * be triggered.
+ */
+ sdt_ecxt_enter(map);
+
+ /*
+ * Use sdt_ecxt_enter() and sdt_ecxt_exit() in pair. Place at the
+ * end of the interesting section where the interesting event might
+ * be triggered.
+ */
+ sdt_ecxt_exit(map);
+
+
+LDT(Lock Dependency Tracker) APIs
+---------------------------------
+Do not use these APIs directly. These are the wrappers for typical
+locks, that have been already applied into major locks internally e.g.
+spin lock, mutex, rwlock and so on. The APIs of LDT are:
+
+ ldt_init(map, key, sub, name);
+ ldt_lock(map, sub_local, try, nest, ip);
+ ldt_rlock(map, sub_local, try, nest, ip, queued);
+ ldt_wlock(map, sub_local, try, nest, ip);
+ ldt_unlock(map, ip);
+ ldt_downgrade(map, ip);
+ ldt_set_class(map, name, key, sub_local, ip);
+
+
+Raw APIs
+--------
+Do not use these APIs directly. The raw APIs of dept are:
+
+ dept_free_range(start, size);
+ dept_map_init(map, key, sub, name);
+ dept_map_reinit(map, key, sub, name);
+ dept_ext_wgen_init(ext_wgen);
+ dept_map_copy(map_to, map_from);
+ dept_wait(map, wait_flags, ip, wait_func, sub_local, time);
+ dept_stage_wait(map, key, ip, wait_func, time);
+ dept_request_event_wait_commit();
+ dept_clean_stage();
+ dept_stage_event(task, ip);
+ dept_ecxt_enter(map, evt_flags, ip, ecxt_func, evt_func, sub_local);
+ dept_ecxt_holding(map, evt_flags);
+ dept_request_event(map, ext_wgen);
+ dept_event(map, evt_flags, ip, evt_func, ext_wgen);
+ dept_ecxt_exit(map, evt_flags, ip);
+ dept_ecxt_enter_nokeep(map);
+ dept_key_init(key);
+ dept_key_destroy(key);
+ dept_map_ecxt_modify(map, cur_evt_flags, key, evt_flags, ip, ecxt_func, evt_func, sub_local);
--
2.17.1
prev parent reply other threads:[~2024-05-08 10:03 UTC|newest]
Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-08 9:46 [PATCH v14 00/28] DEPT(Dependency Tracker) Byungchul Park
2024-05-08 9:46 ` [PATCH v14 01/28] llist: Move llist_{head, node} definition to types.h Byungchul Park
2024-05-08 9:46 ` [PATCH v14 02/28] dept: Implement Dept(Dependency Tracker) Byungchul Park
2024-05-08 9:47 ` [PATCH v14 03/28] dept: Add single event dependency tracker APIs Byungchul Park
2024-05-08 9:47 ` [PATCH v14 04/28] dept: Add lock " Byungchul Park
2024-05-08 9:47 ` [PATCH v14 05/28] dept: Tie to Lockdep and IRQ tracing Byungchul Park
2024-05-08 9:47 ` [PATCH v14 06/28] dept: Add proc knobs to show stats and dependency graph Byungchul Park
2024-05-08 9:47 ` [PATCH v14 07/28] dept: Distinguish each syscall context from another Byungchul Park
2024-05-08 9:47 ` [PATCH v14 08/28] dept: Distinguish each work " Byungchul Park
2024-05-08 9:47 ` [PATCH v14 09/28] dept: Add a mechanism to refill the internal memory pools on running out Byungchul Park
2024-05-08 9:47 ` [PATCH v14 10/28] dept: Record the latest one out of consecutive waits of the same class Byungchul Park
2024-05-08 9:47 ` [PATCH v14 11/28] dept: Apply sdt_might_sleep_{start, end}() to wait_for_completion()/complete() Byungchul Park
2024-05-08 9:47 ` [PATCH v14 12/28] dept: Apply sdt_might_sleep_{start,end}() to swait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 13/28] dept: Apply sdt_might_sleep_{start, end}() to waitqueue wait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 14/28] dept: Apply sdt_might_sleep_{start, end}() to hashed-waitqueue wait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 15/28] dept: Apply sdt_might_sleep_{start, end}() to dma fence wait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 16/28] dept: Track timeout waits separately with a new Kconfig Byungchul Park
2024-05-08 9:47 ` [PATCH v14 17/28] dept: Apply timeout consideration to wait_for_completion()/complete() Byungchul Park
2024-05-08 9:47 ` [PATCH v14 18/28] dept: Apply timeout consideration to swait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 19/28] dept: Apply timeout consideration to waitqueue wait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 20/28] dept: Apply timeout consideration to hashed-waitqueue wait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 21/28] dept: Apply timeout consideration to dma fence wait Byungchul Park
2024-05-08 9:47 ` [PATCH v14 22/28] dept: Make Dept able to work with an external wgen Byungchul Park
2024-05-08 9:47 ` [PATCH v14 23/28] dept: Track PG_locked with dept Byungchul Park
2024-05-08 9:47 ` [PATCH v14 24/28] dept: Print event context requestor's stacktrace on report Byungchul Park
2024-05-08 9:47 ` [PATCH v14 25/28] cpu/hotplug: Use a weaker annotation in AP thread Byungchul Park
2024-05-08 9:47 ` [PATCH v14 26/28] fs/jbd2: Use a weaker annotation in journal handling Byungchul Park
2024-05-08 9:47 ` [PATCH v14 27/28] dept: Add documentation for Dept Byungchul Park
2024-05-08 9:47 ` Byungchul Park [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240508094726.35754-29-byungchul@sk.com \
--to=byungchul@sk.com \
--cc=42.hyeyoo@gmail.com \
--cc=adilger.kernel@dilger.ca \
--cc=akpm@linux-foundation.org \
--cc=amir73il@gmail.com \
--cc=boqun.feng@gmail.com \
--cc=chris.p.wilson@intel.com \
--cc=cl@linux.com \
--cc=damien.lemoal@opensource.wdc.com \
--cc=dan.j.williams@intel.com \
--cc=daniel.vetter@ffwll.ch \
--cc=david@fromorbit.com \
--cc=dennis@kernel.org \
--cc=djwong@kernel.org \
--cc=dri-devel@lists.freedesktop.org \
--cc=duyuyang@gmail.com \
--cc=gregkh@linuxfoundation.org \
--cc=gwan-gyeong.mun@intel.com \
--cc=hamohammed.sa@gmail.com \
--cc=hannes@cmpxchg.org \
--cc=hch@infradead.org \
--cc=hdanton@sina.com \
--cc=her0gyugyu@gmail.com \
--cc=jack@suse.cz \
--cc=jglisse@redhat.com \
--cc=jlayton@kernel.org \
--cc=joel@joelfernandes.org \
--cc=johannes.berg@intel.com \
--cc=josef@toxicpanda.com \
--cc=kernel-team@lge.com \
--cc=kernel_team@skhynix.com \
--cc=linux-block@vger.kernel.org \
--cc=linux-ext4@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-ide@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=longman@redhat.com \
--cc=max.byungchul.park@gmail.com \
--cc=melissa.srw@gmail.com \
--cc=mhocko@kernel.org \
--cc=minchan@kernel.org \
--cc=mingo@redhat.com \
--cc=ngupta@vflare.org \
--cc=penberg@kernel.org \
--cc=peterz@infradead.org \
--cc=rientjes@google.com \
--cc=rodrigosiqueiramelo@gmail.com \
--cc=rostedt@goodmis.org \
--cc=sashal@kernel.org \
--cc=sj@kernel.org \
--cc=tglx@linutronix.de \
--cc=tj@kernel.org \
--cc=torvalds@linux-foundation.org \
--cc=tytso@mit.edu \
--cc=vbabka@suse.cz \
--cc=vdavydov.dev@gmail.com \
--cc=will@kernel.org \
--cc=willy@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).