Date: Wed,  8 May 2024 18:47:25 +0900
From: Byungchul Park <byungchul@...com>
To: linux-kernel@...r.kernel.org
Cc: kernel_team@...ynix.com,
	torvalds@...ux-foundation.org,
	damien.lemoal@...nsource.wdc.com,
	linux-ide@...r.kernel.org,
	adilger.kernel@...ger.ca,
	linux-ext4@...r.kernel.org,
	mingo@...hat.com,
	peterz@...radead.org,
	will@...nel.org,
	tglx@...utronix.de,
	rostedt@...dmis.org,
	joel@...lfernandes.org,
	sashal@...nel.org,
	daniel.vetter@...ll.ch,
	duyuyang@...il.com,
	johannes.berg@...el.com,
	tj@...nel.org,
	tytso@....edu,
	willy@...radead.org,
	david@...morbit.com,
	amir73il@...il.com,
	gregkh@...uxfoundation.org,
	kernel-team@....com,
	linux-mm@...ck.org,
	akpm@...ux-foundation.org,
	mhocko@...nel.org,
	minchan@...nel.org,
	hannes@...xchg.org,
	vdavydov.dev@...il.com,
	sj@...nel.org,
	jglisse@...hat.com,
	dennis@...nel.org,
	cl@...ux.com,
	penberg@...nel.org,
	rientjes@...gle.com,
	vbabka@...e.cz,
	ngupta@...are.org,
	linux-block@...r.kernel.org,
	josef@...icpanda.com,
	linux-fsdevel@...r.kernel.org,
	jack@...e.cz,
	jlayton@...nel.org,
	dan.j.williams@...el.com,
	hch@...radead.org,
	djwong@...nel.org,
	dri-devel@...ts.freedesktop.org,
	rodrigosiqueiramelo@...il.com,
	melissa.srw@...il.com,
	hamohammed.sa@...il.com,
	42.hyeyoo@...il.com,
	chris.p.wilson@...el.com,
	gwan-gyeong.mun@...el.com,
	max.byungchul.park@...il.com,
	boqun.feng@...il.com,
	longman@...hat.com,
	hdanton@...a.com,
	her0gyugyu@...il.com
Subject: [PATCH v14 28/28] dept: Add documentation for Dept's APIs

This document describes the APIs of Dept.

Signed-off-by: Byungchul Park <byungchul@...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@...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

Powered by blists - more mailing lists