Skip to contentSkip to conversation

doc: Update blacklist and whitelist

PATCH In review Petr Vorel 3 participants 7 messages Nov 15, 2024

lore
Share & tools
lore

Petr Vorel

author
#0 lore raw

PATCH 1/2 doc: Update blacklist and whitelist

From: Petr Vorel <[email protected]>

getmsg, getpmsg, putmsg, putpmsg in man UNIMPLEMENTED(2), move them from whitelist to blacklist.

seccomp is now detected, therefore remove from whitelist.

Fixes 7248e5c5f7 ("doc: update syscalls statistics")
---
 doc/conf.py | 5 -----
 1 file changed, 5 deletions(-)
doc/conf.py +0 -5
index aed0cd50fd..e14c1387d0 100644
@@ -67,8 +67,6 @@ def generate_syscalls_stats(_):
         'fanotify_init',
         'fanotify_mark',
         'getdents64',
-        'getmsg',
-        'getpmsg',
         'inotify_add_watch',
         'inotify_rm_watch',
         'io_uring_enter',
@@ -79,8 +77,6 @@ def generate_syscalls_stats(_):
         'landlock_restrict_self',
         'lsetxattr',
         'newfstatat',
-        'putmsg',
-        'putpmsg',
         'pkey_alloc',
         'pkey_free',
         'pkey_mprotect',
@@ -90,7 +86,6 @@ def generate_syscalls_stats(_):
         'pwrite64',
         'quotactl_fd',
         'rt_sigpending',
-        'seccomp',
         'semtimedop',
         'sethostname',
     ]
Signature · 5 lines
2.45.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
author
#1 lore raw

PATCH 2/2 doc: Add URL to the sources in syscalls list

From: Petr Vorel <[email protected]>

Provide links to the sources of all tested syscalls. Users can inspect the test coverage :).

---
 doc/conf.py | 107 +++++++++++++++++++++++++++++++++-------------------
 1 file changed, 68 insertions(+), 39 deletions(-)
doc/conf.py +68 -39
index e14c1387d0..7c3da9e112 100644
@@ -28,9 +28,11 @@ extensions = [
 ]
 
 exclude_patterns = ["html*", '_static*']
+github = 'https://github.com/linux-test-project/ltp'
+master = f'{github}/blob/master'
 extlinks = {
-    'repo': ('https://github.com/linux-test-project/ltp/%s', '%s'),
-    'master': ('https://github.com/linux-test-project/ltp/blob/master/%s', '%s'),
+    'repo': (f'{github}/%s', '%s'),
+    'master': (f'{master}/%s', '%s'),
     'git_man': ('https://git-scm.com/docs/git-%s', 'git %s'),
     # TODO: allow 2nd parameter to show page description instead of plain URL
     'kernel_doc': ('https://docs.kernel.org/%s.html', 'https://docs.kernel.org/%s.html'),
@@ -56,39 +58,53 @@ def generate_syscalls_stats(_):
     generate a file that is included in the statistics documentation section.
     """
     output = '_static/syscalls.rst'
+    syscalls_dir = 'testcases/kernel/syscalls'
 
+    # format syscall_name : folder (for URL, optional)
     # sometimes checking testcases/kernel/syscalls file names are not enough,
     # because in some cases (i.e. io_ring) syscalls are tested, but they are
     # part of a more complex scenario. In the following list, we define syscalls
     # which we know they are 100% tested already.
-    white_list = [
-        'epoll_pwait2',
-        'fadvise64',
-        'fanotify_init',
-        'fanotify_mark',
-        'getdents64',
-        'inotify_add_watch',
-        'inotify_rm_watch',
-        'io_uring_enter',
-        'io_uring_register',
-        'io_uring_setup',
-        'landlock_add_rule',
-        'landlock_create_ruleset',
-        'landlock_restrict_self',
-        'lsetxattr',
-        'newfstatat',
-        'pkey_alloc',
-        'pkey_free',
-        'pkey_mprotect',
-        'prlimit64',
-        'pread64',
-        'pselect6',
-        'pwrite64',
-        'quotactl_fd',
-        'rt_sigpending',
-        'semtimedop',
-        'sethostname',
-    ]
+    # Or syscalls are here to get their folder.
+    white_list = {
+        'epoll_pwait2': 'epoll_pwait',
+        'fadvise64': 'fadvise',
+        'fanotify_init': 'fanotify',
+        'fanotify_mark': 'fanotify',
+        'futex_wait': 'futex',
+        'futex_waitv': 'futex',
+        'futex_wake': 'futex',
+        'getdents64': 'getdents',
+        'inotify_add_watch': 'inotify',
+        'inotify_rm_watch': 'inotify',
+        'inotify_init1': 'inotify',
+        'io_uring_enter': 'io_uring',
+        'io_uring_register': 'io_uring',
+        'io_uring_setup': 'io_uring',
+        'ioprio_get': 'ioprio',
+        'ioprio_set': 'ioprio',
+        'landlock_add_rule': 'landlock',
+        'landlock_create_ruleset': 'landlock',
+        'landlock_restrict_self': 'landlock',
+        'lsetxattr': 'lgetxattr', # llistxattr, lremovexattr
+        'newfstatat': 'fstatat',
+        'pkey_alloc': 'pkeys',
+        'pkey_free': 'pkeys',
+        'pkey_mprotect': 'pkeys',
+        'pread64': 'preadv',
+        'prlimit64': 'getrlimit',
+        'process_vm_readv': 'cma',
+        'process_vm_writev': 'cma',
+        'pselect6': 'select',
+        'pwrite64': 'pwrite',
+        'quotactl_fd': 'quotactl',
+        'rt_sigpending': 'sigpending',
+        'semtimedop': 'ipc/semop',
+        'sethostname': 'setdomainname',
+        'timerfd_gettime': 'timerfd',
+        'timerfd_settime': 'timerfd',
+        'timerfd_create': 'timerfd',
+    }
 
     # populate with not implemented, reserved, unmaintained syscalls defined
     # inside the syscalls file
@@ -144,28 +160,38 @@ def generate_syscalls_stats(_):
                 ker_syscalls.append(match.group('syscall'))
 
     # collect all LTP tested syscalls
-    ltp_syscalls = []
-    for root, _, files in os.walk('../testcases/kernel/syscalls'):
+    ltp_syscalls = {}
+    for root, _, files in os.walk('../' + syscalls_dir):
         for myfile in files:
             if myfile.endswith('.c'):
-                ltp_syscalls.append(myfile)
+                ltp_syscalls[myfile] = root[3:]
 
     # compare kernel syscalls with LTP tested syscalls
     syscalls = {}
+    url = {}
     for kersc in ker_syscalls:
         if kersc in black_list:
             continue
 
         if kersc not in syscalls:
-            if kersc in white_list:
+            if kersc in white_list.keys():
                 syscalls[kersc] = True
+                if white_list[kersc]:
+                    url[kersc] = syscalls_dir + '/' + white_list[kersc]
+
                 continue
 
             syscalls[kersc] = False
 
-        for ltpsc in ltp_syscalls:
+        for ltpsc in ltp_syscalls.keys():
             if ltpsc.startswith(kersc):
                 syscalls[kersc] = True
+                if kersc in url:
+                    continue
+                # Be conservative and use only directories which match exactly the syscall.
+                # Otherwise mkdir will be linked to mkdirat, openat to openat2, etc.
+                if os.path.basename(ltp_syscalls[ltpsc]) == kersc:
+                    url[kersc] = ltp_syscalls[ltpsc]
 
     # generate the statistics file
     tested_syscalls = [key for key, val in syscalls.items() if val]
@@ -192,18 +218,21 @@ def generate_syscalls_stats(_):
     ]
 
     for sysname, tested in syscalls.items():
+        name = f'{sysname}'
         if tested:
+            if sysname in url.keys():
+                name = f'`{sysname} <{github}/tree/master/{url[sysname]}>`_'
             if (index_tested % 3) == 0:
-                table_tested.append(f'    * - {sysname}\n')
+                table_tested.append(f'    * - {name}\n')
             else:
-                table_tested.append(f'      - {sysname}\n')
+                table_tested.append(f'      - {name}\n')
 
             index_tested += 1
         else:
             if (index_untest % 3) == 0:
-                table_untest.append(f'    * - {sysname}\n')
+                table_untest.append(f'    * - {name}\n')
             else:
-                table_untest.append(f'      - {sysname}\n')
+                table_untest.append(f'      - {name}\n')
 
             index_untest += 1
 
Signature · 5 lines
2.45.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
#2 lore raw

Re: [LTP] [PATCH 2/2] doc: Add URL to the sources in syscalls list

Hi Petr,

Quoted 30 lines · Petr Vorel
doc/conf.py +30 -0
+    # Or syscalls are here to get their folder.
+    white_list = {
+        'epoll_pwait2': 'epoll_pwait',
+        'fadvise64': 'fadvise',
+        'fanotify_init': 'fanotify',
+        'fanotify_mark': 'fanotify',
+        'futex_wait': 'futex',
+        'futex_waitv': 'futex',
+        'futex_wake': 'futex',
+        'getdents64': 'getdents',
+        'inotify_add_watch': 'inotify',
+        'inotify_rm_watch': 'inotify',
+        'inotify_init1': 'inotify',
+        'io_uring_enter': 'io_uring',
+        'io_uring_register': 'io_uring',
+        'io_uring_setup': 'io_uring',
+        'ioprio_get': 'ioprio',
+        'ioprio_set': 'ioprio',
+        'landlock_add_rule': 'landlock',
+        'landlock_create_ruleset': 'landlock',
+        'landlock_restrict_self': 'landlock',
+        'lsetxattr': 'lgetxattr', # llistxattr, lremovexattr
+        'newfstatat': 'fstatat',
+        'pkey_alloc': 'pkeys',
+        'pkey_free': 'pkeys',
+        'pkey_mprotect': 'pkeys',
+        'pread64': 'preadv',
+        'prlimit64': 'getrlimit',
+        'process_vm_readv': 'cma',
+        'process_vm_writev': 'cma',

doc/conf.py def generate_syscalls_stats(_): · line 107

Quoted 10 lines
doc/conf.py +10 -0
+        'pselect6': 'select',
+        'pwrite64': 'pwrite',
+        'quotactl_fd': 'quotactl',
+        'rt_sigpending': 'sigpending',
+        'semtimedop': 'ipc/semop',
+        'sethostname': 'setdomainname',
+        'timerfd_gettime': 'timerfd',
+        'timerfd_settime': 'timerfd',
+        'timerfd_create': 'timerfd',
+    }

The problem with this approach and the reason why I didn't use it, is that if you change the testing folder, you need to update the docs generator script. But I also see the goal, so probably this is the only approach we should follow.

Andrea

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#3 lore raw

Re: [LTP] [PATCH 2/2] doc: Add URL to the sources in syscalls list

Quoted 44 lines

Hi Petr,

Quoted 30 lines · Petr Vorel
doc/conf.py +30 -0
+    # Or syscalls are here to get their folder.
+    white_list = {
+        'epoll_pwait2': 'epoll_pwait',
+        'fadvise64': 'fadvise',
+        'fanotify_init': 'fanotify',
+        'fanotify_mark': 'fanotify',
+        'futex_wait': 'futex',
+        'futex_waitv': 'futex',
+        'futex_wake': 'futex',
+        'getdents64': 'getdents',
+        'inotify_add_watch': 'inotify',
+        'inotify_rm_watch': 'inotify',
+        'inotify_init1': 'inotify',
+        'io_uring_enter': 'io_uring',
+        'io_uring_register': 'io_uring',
+        'io_uring_setup': 'io_uring',
+        'ioprio_get': 'ioprio',
+        'ioprio_set': 'ioprio',
+        'landlock_add_rule': 'landlock',
+        'landlock_create_ruleset': 'landlock',
+        'landlock_restrict_self': 'landlock',
+        'lsetxattr': 'lgetxattr', # llistxattr, lremovexattr
+        'newfstatat': 'fstatat',
+        'pkey_alloc': 'pkeys',
+        'pkey_free': 'pkeys',
+        'pkey_mprotect': 'pkeys',
+        'pread64': 'preadv',
+        'prlimit64': 'getrlimit',
+        'process_vm_readv': 'cma',
+        'process_vm_writev': 'cma',

doc/conf.py def generate_syscalls_stats(_): · line 107

Quoted 10 lines
doc/conf.py +10 -0
+        'pselect6': 'select',
+        'pwrite64': 'pwrite',
+        'quotactl_fd': 'quotactl',
+        'rt_sigpending': 'sigpending',
+        'semtimedop': 'ipc/semop',
+        'sethostname': 'setdomainname',
+        'timerfd_gettime': 'timerfd',
+        'timerfd_settime': 'timerfd',
+        'timerfd_create': 'timerfd',
+    }
Quoted 4 lines

The problem with this approach and the reason why I didn't use it, is that if you change the testing folder, you need to update the docs generator script. But I also see the goal, so probably this is the only approach we should follow.

Other thing would be move around folders, but IMHO some syscalls are really related, that's why it's good they are in "ipc" subfolder. OTOH bind(), send(), recvmsg(), ... aren't in "net or "network" subfolder.

Whole this was inspired by Metan's suggestion to deriver info about syscalls from the folder.

Kind regards,
Petr

Quoted 1 line

Andrea

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#4 lore raw

Re: [LTP] [PATCH 2/2] doc: Add URL to the sources in syscalls list

In reply to Andrea Cervesato via ltp

Hi all,

Quoted 44 lines

Hi Petr,

Quoted 30 lines · Petr Vorel
doc/conf.py +30 -0
+    # Or syscalls are here to get their folder.
+    white_list = {
+        'epoll_pwait2': 'epoll_pwait',
+        'fadvise64': 'fadvise',
+        'fanotify_init': 'fanotify',
+        'fanotify_mark': 'fanotify',
+        'futex_wait': 'futex',
+        'futex_waitv': 'futex',
+        'futex_wake': 'futex',
+        'getdents64': 'getdents',
+        'inotify_add_watch': 'inotify',
+        'inotify_rm_watch': 'inotify',
+        'inotify_init1': 'inotify',
+        'io_uring_enter': 'io_uring',
+        'io_uring_register': 'io_uring',
+        'io_uring_setup': 'io_uring',
+        'ioprio_get': 'ioprio',
+        'ioprio_set': 'ioprio',
+        'landlock_add_rule': 'landlock',
+        'landlock_create_ruleset': 'landlock',
+        'landlock_restrict_self': 'landlock',
+        'lsetxattr': 'lgetxattr', # llistxattr, lremovexattr
+        'newfstatat': 'fstatat',
+        'pkey_alloc': 'pkeys',
+        'pkey_free': 'pkeys',
+        'pkey_mprotect': 'pkeys',
+        'pread64': 'preadv',
+        'prlimit64': 'getrlimit',
+        'process_vm_readv': 'cma',
+        'process_vm_writev': 'cma',

doc/conf.py def generate_syscalls_stats(_): · line 107

Quoted 10 lines
doc/conf.py +10 -0
+        'pselect6': 'select',
+        'pwrite64': 'pwrite',
+        'quotactl_fd': 'quotactl',
+        'rt_sigpending': 'sigpending',
+        'semtimedop': 'ipc/semop',
+        'sethostname': 'setdomainname',
+        'timerfd_gettime': 'timerfd',
+        'timerfd_settime': 'timerfd',
+        'timerfd_create': 'timerfd',
+    }
Quoted 4 lines

The problem with this approach and the reason why I didn't use it, is that if you change the testing folder, you need to update the docs generator script. But I also see the goal, so probably this is the only approach we should follow.

Also, my first version was to match only syscalls, which are the folder with the same name as the syscall. If we prefer this is better, I can post this version.

@Andrea @Cyril: Other think I would like to have our metadata doc somehow generated for the master. But that would require to have installed asciidoctor on container, that will not work for sphinx. Also our metadata syntax is somehow LTP specific (at least /*\ starter) and having doc on 2 places (readthedocs https://linux-test-project.readthedocs.io/ and static metadata doc file uploaded to releases (e.g.
https://github.com/linux-test-project/ltp/releases/download/20240930/metadata.20240930.html)
is not optimal. I also like python scripting more than perl (used for metadata).

Other option would be to drop metadata syntax and transform docs to sphinx format. But that would require a lot of scripting, we would not want to do it manually.

Also, doc added to releases vs. online doc:
* Should we add generated readthedocs to releases? One could have docs forever.
* Should we have also the latest release doc in online readthedocs? Or even for
* all releases? ATM we have just master.

Kind regards,
Petr

Quoted 1 line

Andrea

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#5 lore raw

Re: [LTP] [PATCH 2/2] doc: Add URL to the sources in syscalls list

Hi Petr,

Quoted 8 lines · Petr Vorel

@Andrea @Cyril: Other think I would like to have our metadata doc somehow generated for the master. But that would require to have installed asciidoctor on container, that will not work for sphinx. Also our metadata syntax is somehow LTP specific (at least /*\ starter) and having doc on 2 places (readthedocshttps://linux-test-project.readthedocs.io/ and static metadata doc file uploaded to releases (e.g.
https://github.com/linux-test-project/ltp/releases/download/20240930/metadata.20240930.html)
is not optimal. I also like python scripting more than perl (used for metadata).

I remember we talked with Cyril long time ago about this. Yes, it's possibly something which requires a move from asciidoc to sphinx syntax. It's not so difficult. The rules are pretty simple, since we really don't have much information inside the asciidoc format.

Most of the times, it's only a matter of replacing /*\ with /** and to change [Description/Algorithm] with ===== underline.

Quoted 7 lines

Other option would be to drop metadata syntax and transform docs to sphinx format. But that would require a lot of scripting, we would not want to do it manually.

Also, doc added to releases vs. online doc:
* Should we add generated readthedocs to releases? One could have docs forever.
* Should we have also the latest release doc in online readthedocs? Or even for
* all releases? ATM we have just master.

I think it makes sense to have it in the release, but I don't know if it's possible to generate a single file in a easy way. Maybe take a look at singlehtml.

Andrea

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
author
#6 lore raw
In reply to Petr Vorel
Quoted 18 lines

From: Petr Vorel <[email protected]>

getmsg, getpmsg, putmsg, putpmsg in man UNIMPLEMENTED(2), move them from whitelist to blacklist.

seccomp is now detected, therefore remove from whitelist.

Fixes 7248e5c5f7 ("doc: update syscalls statistics")
---
 doc/conf.py | 5 -----
 1 file changed, 5 deletions(-)
doc/conf.py +0 -0
index aed0cd50fd..e14c1387d0 100644

doc/conf.py def generate_syscalls_stats(_): · line 71

Quoted 5 lines
doc/conf.py +0 -2
@@ -67,8 +67,6 @@ def generate_syscalls_stats(_):
         'fanotify_init',
         'fanotify_mark',
         'getdents64',
-        'getmsg',
-        'getpmsg',

Actually these 2 were supposed to be moved to blacklist.

doc/conf.py def generate_syscalls_stats(_): · line 83

Quoted 9 lines
doc/conf.py +0 -2
         'inotify_add_watch',
         'inotify_rm_watch',
         'io_uring_enter',
@@ -79,8 +77,6 @@ def generate_syscalls_stats(_):
         'landlock_restrict_self',
         'lsetxattr',
         'newfstatat',
-        'putmsg',
-        'putpmsg',

And these two as well.

doc/conf.py def generate_syscalls_stats(_): · line 91

Quoted 11 lines
doc/conf.py +0 -1
         'pkey_alloc',
         'pkey_free',
         'pkey_mprotect',
@@ -90,7 +86,6 @@ def generate_syscalls_stats(_):
         'pwrite64',
         'quotactl_fd',
         'rt_sigpending',
-        'seccomp',
         'semtimedop',
         'sethostname',
     ]

Diff to the correct code below. I'm sorry for the noise. Corrected code is in my fork in case somebody wants to test it:
https://github.com/pevik/ltp/commits/refs/heads/doc/syscalls-url.fixes/

+++ doc/conf.py
@@ -96,11 +96,15 @@ def generate_syscalls_stats(_):

         '_newselect',
         '_sysctl',
         'afs_syscall',
+        'getmsg',
+        'getpmsg',
         'cachectl',
         'create_module',
         'get_kernel_syms',
         'mq_getsetattr',
         'nfsservctl',
+        'putmsg',
+        'putpmsg',
         'query_module',
         'reserved177',
         'reserved193',
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp