Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc-test.yaml: add more tests
Add extra tests to check if the new "var" type is properly
handled and to cover mutex context annotations.
Co-developed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <75af93a45151b630c94b7f77637d173e6119fd41.1774256269.git.mchehab+huawei@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
bc63427c
6e0d7b63
+1546
-2
+1546
-2
tools/unittests/kdoc-test.yaml
+1546
-2
tools/unittests/kdoc-test.yaml
···
22
22
*/
23
23
int func1(char *arg1) { return 0; };
24
24
25
-
26
25
expected:
27
26
- rst: |
28
27
.. c:function:: int func1 (char *arg1)
···
133
134
134
135
always return 0.
135
136
136
-
# TODO: how to handle timestamps at .TH?
137
137
man: |
138
138
.TH "func2" 9 "February 2026" "" "Kernel API Manual"
139
139
.SH NAME
···
150
152
.SH "SEE ALSO"
151
153
.PP
152
154
Kernel file \fBfunc2.c\fR
155
+
156
+
- name: doc_with_complex_table
157
+
description: Test if complex tables are handled
158
+
fname: mock.c
159
+
source: |
160
+
/**
161
+
* DOC: Supported input formats and encodings
162
+
*
163
+
* Depending on the Hardware configuration of the Controller IP, it supports
164
+
* a subset of the following input formats and encodings on its internal
165
+
* 48bit bus.
166
+
*
167
+
* +----------------------+----------------------------------+------------------------------+
168
+
* | Format Name | Format Code | Encodings |
169
+
* +======================+==================================+==============================+
170
+
* | RGB 4:4:4 8bit | ``MEDIA_BUS_FMT_RGB888_1X24`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
171
+
* +----------------------+----------------------------------+------------------------------+
172
+
* | RGB 4:4:4 10bits | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
173
+
* +----------------------+----------------------------------+------------------------------+
174
+
*/
175
+
expected:
176
+
- man: |
177
+
.TH "Supported input formats and encodings" 9 "March 2026" "" "Kernel API Manual"
178
+
.SH "Supported input formats and encodings"
179
+
Depending on the Hardware configuration of the Controller IP, it supports
180
+
a subset of the following input formats and encodings on its internal
181
+
48bit bus.
182
+
.PP
183
+
184
+
185
+
.TS
186
+
box;
187
+
l l l.
188
+
\fBFormat Name\fP \fBFormat Code\fP \fBEncodings\fP
189
+
_
190
+
RGB 4:4:4 8bit ``MEDIA_BUS_FMT_RGB888_1X24 V4L2_YCBCR_ENC_DEFAULT
191
+
RGB 4:4:4 10bits MEDIA_BUS_FMT_RGB101010_1X30 V4L2_YCBCR_ENC_DEFAULT``
192
+
.TE
193
+
.SH "SEE ALSO"
194
+
.PP
195
+
Kernel file \fBmock.c\fR
196
+
197
+
rst: |-
198
+
.. _Supported input formats and encodings:
199
+
**Supported input formats and encodings**
200
+
Depending on the Hardware configuration of the Controller IP, it supports
201
+
a subset of the following input formats and encodings on its internal
202
+
48bit bus.
203
+
+----------------------+----------------------------------+------------------------------+
204
+
| Format Name | Format Code | Encodings |
205
+
+======================+==================================+==============================+
206
+
| RGB 4:4:4 8bit | ``MEDIA_BUS_FMT_RGB888_1X24`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
207
+
+----------------------+----------------------------------+------------------------------+
208
+
| RGB 4:4:4 10bits | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
209
+
+----------------------+----------------------------------+------------------------------+
210
+
- name: func_with_ascii_artwork
211
+
description: Test if ascii artwork is properly output
212
+
fname: mock.c
213
+
source: |
214
+
/**
215
+
* add_cxl_resources() - reflect CXL fixed memory windows in iomem_resource
216
+
* @cxl_res: A standalone resource tree where each CXL window is a sibling
217
+
*
218
+
* Walk each CXL window in @cxl_res and add it to iomem_resource potentially
219
+
* expanding its boundaries to ensure that any conflicting resources become
220
+
* children. If a window is expanded it may then conflict with a another window
221
+
* entry and require the window to be truncated or trimmed. Consider this
222
+
* situation::
223
+
*
224
+
* |-- "CXL Window 0" --||----- "CXL Window 1" -----|
225
+
* |--------------- "System RAM" -------------|
226
+
*
227
+
* ...where platform firmware has established as System RAM resource across 2
228
+
* windows, but has left some portion of window 1 for dynamic CXL region
229
+
* provisioning. In this case "Window 0" will span the entirety of the "System
230
+
* RAM" span, and "CXL Window 1" is truncated to the remaining tail past the end
231
+
* of that "System RAM" resource.
232
+
*/
233
+
static int add_cxl_resources(struct resource *cxl_res);
234
+
expected:
235
+
- man: |-
236
+
.TH "add_cxl_resources" 9 "March 2026" "" "Kernel API Manual"
237
+
.SH NAME
238
+
add_cxl_resources \- reflect CXL fixed memory windows in iomem_resource
239
+
.SH SYNOPSIS
240
+
.B "int" add_cxl_resources
241
+
.BI "(struct resource *cxl_res " ");"
242
+
.SH ARGUMENTS
243
+
.IP "cxl_res" 12
244
+
A standalone resource tree where each CXL window is a sibling
245
+
.SH "DESCRIPTION"
246
+
Walk each CXL window in \fIcxl_res\fP and add it to iomem_resource potentially
247
+
expanding its boundaries to ensure that any conflicting resources become
248
+
children. If a window is expanded it may then conflict with a another window
249
+
entry and require the window to be truncated or trimmed. Consider this
250
+
situation:
251
+
.nf
252
+
253
+
|-- "CXL Window 0" --||----- "CXL Window 1" -----|
254
+
|--------------- "System RAM" -------------|
255
+
256
+
257
+
.fi
258
+
.PP
259
+
260
+
\&...where platform firmware has established as System RAM resource across 2
261
+
windows, but has left some portion of window 1 for dynamic CXL region
262
+
provisioning. In this case "Window 0" will span the entirety of the "System
263
+
RAM" span, and "CXL Window 1" is truncated to the remaining tail past the end
264
+
of that "System RAM" resource.
265
+
.SH "SEE ALSO"
266
+
.PP
267
+
Kernel file \fBmock.c\fR
268
+
rst: |
269
+
.. c:function:: int add_cxl_resources (struct resource *cxl_res)
270
+
271
+
reflect CXL fixed memory windows in iomem_resource
272
+
273
+
.. container:: kernelindent
274
+
275
+
**Parameters**
276
+
277
+
``struct resource *cxl_res``
278
+
A standalone resource tree where each CXL window is a sibling
279
+
280
+
**Description**
281
+
282
+
Walk each CXL window in **cxl_res** and add it to iomem_resource potentially
283
+
expanding its boundaries to ensure that any conflicting resources become
284
+
children. If a window is expanded it may then conflict with a another window
285
+
entry and require the window to be truncated or trimmed. Consider this
286
+
situation::
287
+
288
+
|-- "CXL Window 0" --||----- "CXL Window 1" -----|
289
+
|--------------- "System RAM" -------------|
290
+
291
+
...where platform firmware has established as System RAM resource across 2
292
+
windows, but has left some portion of window 1 for dynamic CXL region
293
+
provisioning. In this case "Window 0" will span the entirety of the "System
294
+
RAM" span, and "CXL Window 1" is truncated to the remaining tail past the end
295
+
of that "System RAM" resource.
296
+
297
+
- name: simple_tables
298
+
description: Test formatting two simple tables
299
+
fname: mock.c
300
+
source: |
301
+
/**
302
+
* bitmap_onto - translate one bitmap relative to another
303
+
* @dst: resulting translated bitmap
304
+
* @orig: original untranslated bitmap
305
+
* @relmap: bitmap relative to which translated
306
+
* @bits: number of bits in each of these bitmaps
307
+
*
308
+
* =============== ============== =================
309
+
* @orig tmp @dst
310
+
* 0 0 40
311
+
* 1 1 41
312
+
* =============== ============== =================
313
+
*
314
+
* And:
315
+
*
316
+
* =============== ============== =================
317
+
* @orig tmp @dst
318
+
* =============== ============== =================
319
+
* 9 9 95
320
+
* 10 0 40 [#f1]_
321
+
* =============== ============== =================
322
+
*/
323
+
void bitmap_onto(unsigned long *dst, const unsigned long *orig,
324
+
const unsigned long *relmap, unsigned int bits);
325
+
expected:
326
+
- man: |
327
+
.TH "bitmap_onto" 9 "March 2026" "" "Kernel API Manual"
328
+
.SH NAME
329
+
bitmap_onto \- translate one bitmap relative to another
330
+
.SH SYNOPSIS
331
+
.B "void" bitmap_onto
332
+
.BI "(unsigned long *dst " ","
333
+
.BI "const unsigned long *orig " ","
334
+
.BI "const unsigned long *relmap " ","
335
+
.BI "unsigned int bits " ");"
336
+
.SH ARGUMENTS
337
+
.IP "dst" 12
338
+
resulting translated bitmap
339
+
.IP "orig" 12
340
+
original untranslated bitmap
341
+
.IP "relmap" 12
342
+
bitmap relative to which translated
343
+
.IP "bits" 12
344
+
number of bits in each of these bitmaps
345
+
.SH "DESCRIPTION"
346
+
347
+
.TS
348
+
box;
349
+
l l l.
350
+
\fIorig\fP tmp \fIdst\fP
351
+
0 0 40
352
+
1 1 41
353
+
.TE
354
+
.PP
355
+
356
+
And:
357
+
.PP
358
+
359
+
360
+
.TS
361
+
box;
362
+
l l l.
363
+
\fIorig\fP tmp \fIdst\fP
364
+
.TE
365
+
9 9 95
366
+
10 0 40 [#f1]_
367
+
.SH "SEE ALSO"
368
+
.PP
369
+
Kernel file \fBmock.c\fR
370
+
371
+
rst: |
372
+
.. c:function:: void bitmap_onto (unsigned long *dst, const unsigned long *orig, const unsigned long *relmap, unsigned int bits)
373
+
374
+
translate one bitmap relative to another
375
+
376
+
.. container:: kernelindent
377
+
378
+
**Parameters**
379
+
380
+
``unsigned long *dst``
381
+
resulting translated bitmap
382
+
383
+
``const unsigned long *orig``
384
+
original untranslated bitmap
385
+
386
+
``const unsigned long *relmap``
387
+
bitmap relative to which translated
388
+
389
+
``unsigned int bits``
390
+
number of bits in each of these bitmaps
391
+
392
+
**Description**
393
+
394
+
=============== ============== =================
395
+
**orig** tmp **dst**
396
+
0 0 40
397
+
1 1 41
398
+
=============== ============== =================
399
+
400
+
And:
401
+
402
+
=============== ============== =================
403
+
**orig** tmp **dst**
404
+
=============== ============== =================
405
+
9 9 95
406
+
10 0 40 [#f1]_
407
+
=============== ============== =================
408
+
409
+
#
410
+
# Variable tests from Randy Dunlap's testset
411
+
#
412
+
- name: unsigned_long_var_on_uppercase
413
+
description: Test an unsigned long varaible in uppercase
414
+
fname: mock-vars.c
415
+
source: |
416
+
/**
417
+
* var ROOT_DEV - system root device
418
+
*
419
+
* @ROOT_DEV is either the successful root device or the root device
420
+
* that failed boot in the boot failure message.
421
+
*/
422
+
unsigned long ROOT_DEV;
423
+
expected:
424
+
- man: |
425
+
.TH "var ROOT_DEV" 9 "February 2026" "" "Kernel API Manual"
426
+
.SH NAME
427
+
ROOT_DEV \- system root device
428
+
.SH SYNOPSIS
429
+
unsigned long ROOT_DEV;
430
+
.SH "Description"
431
+
\fIROOT_DEV\fP is either the successful root device or the root device
432
+
that failed boot in the boot failure message.
433
+
.SH "SEE ALSO"
434
+
.PP
435
+
Kernel file \fBmock-vars.c\fR
436
+
rst: |
437
+
.. c:macro:: ROOT_DEV
438
+
439
+
``unsigned long ROOT_DEV;``
440
+
441
+
system root device
442
+
443
+
**Description**
444
+
445
+
**ROOT_DEV** is either the successful root device or the root device
446
+
that failed boot in the boot failure message.
447
+
- name: enum_var
448
+
description: Test an enum var with __read_mostly
449
+
fname: mock-vars.c
450
+
source: |
451
+
/**
452
+
* var system_state - system state used during boot or suspend/hibernate/resume
453
+
*
454
+
* @system_state can be used during boot to determine if it is safe to
455
+
* make certain calls to other parts of the kernel. It can also be used
456
+
* during suspend/hibernate or resume to determine the order of actions
457
+
* that need to be executed. The numerical values of system_state are
458
+
* sometimes used in numerical ordering tests, so the relative values
459
+
* must not be altered.
460
+
*/
461
+
enum system_states system_state __read_mostly;
462
+
expected:
463
+
- man: |
464
+
.TH "var system_state" 9 "February 2026" "" "Kernel API Manual"
465
+
.SH NAME
466
+
system_state \- system state used during boot or suspend/hibernate/resume
467
+
.SH SYNOPSIS
468
+
enum system_states system_state __read_mostly;
469
+
.SH "Description"
470
+
\fIsystem_state\fP can be used during boot to determine if it is safe to
471
+
make certain calls to other parts of the kernel. It can also be used
472
+
during suspend/hibernate or resume to determine the order of actions
473
+
that need to be executed. The numerical values of system_state are
474
+
sometimes used in numerical ordering tests, so the relative values
475
+
must not be altered.
476
+
.SH "SEE ALSO"
477
+
.PP
478
+
Kernel file \fBmock-vars.c\fR
479
+
rst: |
480
+
.. c:macro:: system_state
481
+
482
+
``enum system_states system_state __read_mostly;``
483
+
484
+
system state used during boot or suspend/hibernate/resume
485
+
486
+
**Description**
487
+
488
+
**system_state** can be used during boot to determine if it is safe to
489
+
make certain calls to other parts of the kernel. It can also be used
490
+
during suspend/hibernate or resume to determine the order of actions
491
+
that need to be executed. The numerical values of system_state are
492
+
sometimes used in numerical ordering tests, so the relative values
493
+
must not be altered.
494
+
- name: char_pointer_var
495
+
description: Test char * var with __ro_after_init
496
+
fname: mock-vars.c
497
+
source: |
498
+
/**
499
+
* var saved_command_line - kernel's command line, saved from use at
500
+
* any later time in the kernel.
501
+
*/
502
+
char *saved_command_line __ro_after_init;
503
+
expected:
504
+
- man: |
505
+
.TH "var saved_command_line" 9 "February 2026" "" "Kernel API Manual"
506
+
.SH NAME
507
+
saved_command_line \- kernel's command line, saved from use at any later time in the kernel.
508
+
.SH SYNOPSIS
509
+
char *saved_command_line __ro_after_init;
510
+
.SH "SEE ALSO"
511
+
.PP
512
+
Kernel file \fBmock-vars.c\fR
513
+
rst: |
514
+
.. c:macro:: saved_command_line
515
+
516
+
``char *saved_command_line __ro_after_init;``
517
+
518
+
kernel's command line, saved from use at any later time in the kernel.
519
+
- name: unsigned_long_with_default
520
+
description: Test an unsigned long var that is set to a default value
521
+
fname: mock-vars.c
522
+
source: |
523
+
/**
524
+
* var loop_per_jiffy - calculated loop count needed to consume one jiffy
525
+
* of time
526
+
*/
527
+
unsigned long loops_per_jiffy = (1<<12);
528
+
expected:
529
+
- man: |
530
+
.TH "var loops_per_jiffy" 9 "February 2026" "" "Kernel API Manual"
531
+
.SH NAME
532
+
loops_per_jiffy \- calculated loop count needed to consume one jiffy of time
533
+
.SH SYNOPSIS
534
+
unsigned long loops_per_jiffy = (1<<12);
535
+
.SH "Initialization"
536
+
default: (1<<12)
537
+
.SH "SEE ALSO"
538
+
.PP
539
+
Kernel file \fBmock-vars.c\fR
540
+
rst: |
541
+
.. c:macro:: loops_per_jiffy
542
+
543
+
``unsigned long loops_per_jiffy = (1<<12);``
544
+
545
+
calculated loop count needed to consume one jiffy of time
546
+
547
+
**Initialization**
548
+
549
+
default: ``(1<<12)``
550
+
- name: unsigned_long
551
+
description: test a simple unsigned long variable.
552
+
fname: mock-vars.c
553
+
source: |
554
+
/**
555
+
* var preset_lpj - lpj (loops per jiffy) value set from kernel
556
+
* command line using "lpj=VALUE"
557
+
*
558
+
* See Documentation/admin-guide/kernel-parameters.txt ("lpj=") for details.
559
+
*/
560
+
unsigned long preset_lpj;
561
+
expected:
562
+
- man: |
563
+
.TH "var preset_lpj" 9 "February 2026" "" "Kernel API Manual"
564
+
.SH NAME
565
+
preset_lpj \- lpj (loops per jiffy) value set from kernel command line using "lpj=VALUE"
566
+
.SH SYNOPSIS
567
+
unsigned long preset_lpj;
568
+
.SH "Description"
569
+
See Documentation/admin-guide/kernel-parameters.txt ("lpj=") for details.
570
+
.SH "SEE ALSO"
571
+
.PP
572
+
Kernel file \fBmock-vars.c\fR
573
+
rst: |
574
+
.. c:macro:: preset_lpj
575
+
576
+
``unsigned long preset_lpj;``
577
+
578
+
lpj (loops per jiffy) value set from kernel command line using "lpj=VALUE"
579
+
580
+
**Description**
581
+
582
+
See Documentation/admin-guide/kernel-parameters.txt ("lpj=") for details.
583
+
- name: char_array
584
+
description: test a char array variable
585
+
fname: mock-vars.c
586
+
source: |
587
+
/**
588
+
* var linux_proc_banner - text used from /proc/version file
589
+
*
590
+
* * first %s is sysname (e.g., "Linux")
591
+
* * second %s is release
592
+
* * third %s is version
593
+
*/
594
+
char linux_proc_banner[];
595
+
expected:
596
+
- man: |
597
+
.TH "var linux_proc_banner" 9 "February 2026" "" "Kernel API Manual"
598
+
.SH NAME
599
+
linux_proc_banner \- text used from /proc/version file
600
+
.SH SYNOPSIS
601
+
char linux_proc_banner[];
602
+
.SH "Description"
603
+
.IP \[bu]
604
+
first s is sysname (e.g., "Linux")
605
+
.IP \[bu]
606
+
second s is release
607
+
.IP \[bu]
608
+
third s is version
609
+
.SH "SEE ALSO"
610
+
.PP
611
+
Kernel file \fBmock-vars.c\fR
612
+
rst: |
613
+
.. c:macro:: linux_proc_banner
614
+
615
+
``char linux_proc_banner[];``
616
+
617
+
text used from /proc/version file
618
+
619
+
**Description**
620
+
621
+
* first ``s`` is sysname (e.g., "Linux")
622
+
* second ``s`` is release
623
+
* third ``s`` is version
624
+
- name: const_char_array
625
+
description: test a const char array variable
626
+
fname: mock-vars.c
627
+
source: |
628
+
/**
629
+
* var linux_banner - Linux boot banner, usually printed at boot time
630
+
*/
631
+
const char linux_banner[];
632
+
expected:
633
+
- man: |
634
+
.TH "var linux_banner" 9 "February 2026" "" "Kernel API Manual"
635
+
.SH NAME
636
+
linux_banner \- Linux boot banner, usually printed at boot time
637
+
.SH SYNOPSIS
638
+
const char linux_banner[];
639
+
.SH "SEE ALSO"
640
+
.PP
641
+
Kernel file \fBmock-vars.c\fR
642
+
rst: |
643
+
.. c:macro:: linux_banner
644
+
645
+
``const char linux_banner[];``
646
+
647
+
Linux boot banner, usually printed at boot time
648
+
- name: static_atomic64_t_var
649
+
description: test a static atomi64_t variable
650
+
fname: mock-vars.c
651
+
source: |
652
+
/**
653
+
* var diskseq - unique sequence number for block device instances
654
+
*
655
+
* Allows userspace to associate uevents to the lifetime of a device
656
+
*/
657
+
static atomic64_t diskseq;
658
+
expected:
659
+
- man: |
660
+
.TH "var diskseq" 9 "February 2026" "" "Kernel API Manual"
661
+
.SH NAME
662
+
diskseq \- unique sequence number for block device instances
663
+
.SH SYNOPSIS
664
+
static atomic64_t diskseq;
665
+
.SH "Description"
666
+
Allows userspace to associate uevents to the lifetime of a device
667
+
.SH "SEE ALSO"
668
+
.PP
669
+
Kernel file \fBmock-vars.c\fR
670
+
rst: |
671
+
.. c:macro:: diskseq
672
+
673
+
``static atomic64_t diskseq;``
674
+
675
+
unique sequence number for block device instances
676
+
677
+
**Description**
678
+
679
+
Allows userspace to associate uevents to the lifetime of a device
680
+
- name: unsigned_long_on_init
681
+
description: test an unsigned long var at "init" with a different timestamp.
682
+
fname: init/mock-vars.c
683
+
source: |
684
+
/**
685
+
* var rtnl_mutex - historical global lock for networking control operations.
686
+
*
687
+
* @rtnl_mutex is used to serialize rtnetlink requests
688
+
* and protect all kernel internal data structures related to networking.
689
+
*
690
+
* See Documentation/networking/netdevices.rst for details.
691
+
* Often known as the rtnl_lock, although rtnl_lock is a kernel function.
692
+
*/
693
+
unsigned long rtnl_mutex;
694
+
expected:
695
+
- man: |
696
+
.TH "var rtnl_mutex" 9 "February 2026" "init" "Kernel API Manual"
697
+
.SH NAME
698
+
rtnl_mutex \- historical global lock for networking control operations.
699
+
.SH SYNOPSIS
700
+
unsigned long rtnl_mutex;
701
+
.SH "Description"
702
+
\fIrtnl_mutex\fP is used to serialize rtnetlink requests
703
+
and protect all kernel internal data structures related to networking.
704
+
.PP
705
+
706
+
See Documentation/networking/netdevices.rst for details.
707
+
Often known as the rtnl_lock, although rtnl_lock is a kernel function.
708
+
.SH "SEE ALSO"
709
+
.PP
710
+
Kernel file \fBinit/mock-vars.c\fR
711
+
rst: |
712
+
.. c:macro:: rtnl_mutex
713
+
714
+
``unsigned long rtnl_mutex;``
715
+
716
+
historical global lock for networking control operations.
717
+
718
+
**Description**
719
+
720
+
**rtnl_mutex** is used to serialize rtnetlink requests
721
+
and protect all kernel internal data structures related to networking.
722
+
723
+
See Documentation/networking/netdevices.rst for details.
724
+
Often known as the rtnl_lock, although rtnl_lock is a kernel function.
725
+
726
+
727
+
- name: struct_kcov
728
+
fname: mock_tests/kdoc-drop-ctx-lock.c
729
+
source: |
730
+
/**
731
+
* struct kcov - kcov descriptor (one per opened debugfs file).
732
+
* State transitions of the descriptor:
733
+
*
734
+
* - initial state after open()
735
+
* - then there must be a single ioctl(KCOV_INIT_TRACE) call
736
+
* - then, mmap() call (several calls are allowed but not useful)
737
+
* - then, ioctl(KCOV_ENABLE, arg), where arg is
738
+
* KCOV_TRACE_PC - to trace only the PCs
739
+
* or
740
+
* KCOV_TRACE_CMP - to trace only the comparison operands
741
+
* - then, ioctl(KCOV_DISABLE) to disable the task.
742
+
*
743
+
* Enabling/disabling ioctls can be repeated (only one task a time allowed).
744
+
*/
745
+
struct kcov {
746
+
/**
747
+
* @refcount: Reference counter. We keep one for:
748
+
* - opened file descriptor
749
+
* - task with enabled coverage (we can't unwire it from another task)
750
+
* - each code section for remote coverage collection
751
+
*/
752
+
refcount_t refcount;
753
+
/**
754
+
* @lock: The lock protects mode, size, area and t.
755
+
*/
756
+
spinlock_t lock;
757
+
/**
758
+
* @mode: the kcov_mode
759
+
*/
760
+
enum kcov_mode mode __guarded_by(&lock);
761
+
/**
762
+
* @size: Size of arena (in long's).
763
+
*/
764
+
unsigned int size __guarded_by(&lock);
765
+
/**
766
+
* @area: Coverage buffer shared with user space.
767
+
*/
768
+
void *area __guarded_by(&lock);
769
+
/**
770
+
* @t: Task for which we collect coverage, or NULL.
771
+
*/
772
+
struct task_struct *t __guarded_by(&lock);
773
+
/**
774
+
* @remote: Collecting coverage from remote (background) threads.
775
+
*/
776
+
bool remote;
777
+
/**
778
+
* @remote_size: Size of remote area (in long's).
779
+
*/
780
+
unsigned int remote_size;
781
+
/**
782
+
* @sequence: Sequence is incremented each time kcov is reenabled,
783
+
* used by kcov_remote_stop(), see the comment there.
784
+
*/
785
+
int sequence;
786
+
};
787
+
expected:
788
+
- man: |
789
+
.TH "struct kcov" 9 "February 2026" "mock_tests" "Kernel API Manual"
790
+
.SH NAME
791
+
struct kcov \- kcov descriptor (one per opened debugfs file). State transitions of the descriptor:
792
+
.SH SYNOPSIS
793
+
struct kcov {
794
+
.br
795
+
.BI " refcount_t refcount;"
796
+
.br
797
+
.BI " spinlock_t lock;"
798
+
.br
799
+
.BI " enum kcov_mode mode;"
800
+
.br
801
+
.BI " unsigned int size;"
802
+
.br
803
+
.BI " void *area;"
804
+
.br
805
+
.BI " struct task_struct *t;"
806
+
.br
807
+
.BI " bool remote;"
808
+
.br
809
+
.BI " unsigned int remote_size;"
810
+
.br
811
+
.BI " int sequence;"
812
+
.br
813
+
.BI "
814
+
};
815
+
.br
816
+
817
+
.SH Members
818
+
.IP "refcount" 12
819
+
Reference counter. We keep one for:
820
+
.IP \[bu]
821
+
opened file descriptor
822
+
.IP \[bu]
823
+
task with enabled coverage (we can't unwire it from another task)
824
+
.IP \[bu]
825
+
each code section for remote coverage collection
826
+
.IP "lock" 12
827
+
The lock protects mode, size, area and t.
828
+
.IP "mode" 12
829
+
the kcov_mode
830
+
.IP "size" 12
831
+
Size of arena (in long's).
832
+
.IP "area" 12
833
+
Coverage buffer shared with user space.
834
+
.IP "t" 12
835
+
Task for which we collect coverage, or NULL.
836
+
.IP "remote" 12
837
+
Collecting coverage from remote (background) threads.
838
+
.IP "remote_size" 12
839
+
Size of remote area (in long's).
840
+
.IP "sequence" 12
841
+
Sequence is incremented each time kcov is reenabled,
842
+
used by \fBkcov_remote_stop\fP, see the comment there.
843
+
.SH "Description"
844
+
.IP \[bu]
845
+
initial state after \fBopen\fP
846
+
.IP \[bu]
847
+
then there must be a single ioctl(KCOV_INIT_TRACE) call
848
+
.IP \[bu]
849
+
then, \fBmmap\fP call (several calls are allowed but not useful)
850
+
.IP \[bu]
851
+
then, ioctl(KCOV_ENABLE, arg), where arg is
852
+
KCOV_TRACE_PC - to trace only the PCs
853
+
or
854
+
KCOV_TRACE_CMP - to trace only the comparison operands
855
+
.IP \[bu]
856
+
then, ioctl(KCOV_DISABLE) to disable the task.
857
+
.PP
858
+
859
+
Enabling/disabling ioctls can be repeated (only one task a time allowed).
860
+
.SH "SEE ALSO"
861
+
.PP
862
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
863
+
rst: |
864
+
.. c:struct:: kcov
865
+
866
+
kcov descriptor (one per opened debugfs file). State transitions of the descriptor:
867
+
868
+
.. container:: kernelindent
869
+
870
+
**Definition**::
871
+
872
+
struct kcov {
873
+
refcount_t refcount;
874
+
spinlock_t lock;
875
+
enum kcov_mode mode;
876
+
unsigned int size;
877
+
void *area;
878
+
struct task_struct *t;
879
+
bool remote;
880
+
unsigned int remote_size;
881
+
int sequence;
882
+
};
883
+
884
+
**Members**
885
+
886
+
``refcount``
887
+
Reference counter. We keep one for:
888
+
- opened file descriptor
889
+
- task with enabled coverage (we can't unwire it from another task)
890
+
- each code section for remote coverage collection
891
+
892
+
``lock``
893
+
The lock protects mode, size, area and t.
894
+
895
+
``mode``
896
+
the kcov_mode
897
+
898
+
``size``
899
+
Size of arena (in long's).
900
+
901
+
``area``
902
+
Coverage buffer shared with user space.
903
+
904
+
``t``
905
+
Task for which we collect coverage, or NULL.
906
+
907
+
``remote``
908
+
Collecting coverage from remote (background) threads.
909
+
910
+
``remote_size``
911
+
Size of remote area (in long's).
912
+
913
+
``sequence``
914
+
Sequence is incremented each time kcov is reenabled,
915
+
used by kcov_remote_stop(), see the comment there.
916
+
917
+
918
+
**Description**
919
+
920
+
- initial state after open()
921
+
- then there must be a single ioctl(KCOV_INIT_TRACE) call
922
+
- then, mmap() call (several calls are allowed but not useful)
923
+
- then, ioctl(KCOV_ENABLE, arg), where arg is
924
+
KCOV_TRACE_PC - to trace only the PCs
925
+
or
926
+
KCOV_TRACE_CMP - to trace only the comparison operands
927
+
- then, ioctl(KCOV_DISABLE) to disable the task.
928
+
929
+
Enabling/disabling ioctls can be repeated (only one task a time allowed).
930
+
931
+
- name: pool_offset
932
+
description: mock_tests/kdoc-drop-ctx-lock.c line 83
933
+
fname: mock_tests/kdoc-drop-ctx-lock.c
934
+
source: |
935
+
/**
936
+
* var pool_offset - Offset to the unused space in the currently used pool.
937
+
*
938
+
*/
939
+
size_t pool_offset __guarded_by(&pool_lock) = DEPOT_POOL_SIZE;
940
+
expected:
941
+
- man: |
942
+
.TH "var pool_offset" 9 "February 2026" "mock_tests" "Kernel API Manual"
943
+
.SH NAME
944
+
pool_offset \- Offset to the unused space in the currently used pool.
945
+
.SH SYNOPSIS
946
+
size_t pool_offset __guarded_by(&pool_lock) = DEPOT_POOL_SIZE;
947
+
.SH "Initialization"
948
+
default: DEPOT_POOL_SIZE
949
+
.SH "SEE ALSO"
950
+
.PP
951
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
952
+
rst: |
953
+
.. c:macro:: pool_offset
954
+
955
+
``size_t pool_offset __guarded_by(&pool_lock) = DEPOT_POOL_SIZE;``
956
+
957
+
Offset to the unused space in the currently used pool.
958
+
959
+
**Initialization**
960
+
961
+
default: ``DEPOT_POOL_SIZE``
962
+
- name: free_stacks
963
+
description: mock_tests/kdoc-drop-ctx-lock.c line 88
964
+
fname: mock_tests/kdoc-drop-ctx-lock.c
965
+
source: |
966
+
/**
967
+
* var free_stacks - Freelist of stack records within stack_pools.
968
+
*
969
+
*/
970
+
__guarded_by(&pool_lock) LIST_HEAD(free_stacks);
971
+
expected:
972
+
- man: |
973
+
.TH "var free_stacks" 9 "February 2026" "mock_tests" "Kernel API Manual"
974
+
.SH NAME
975
+
free_stacks \- Freelist of stack records within stack_pools.
976
+
.SH SYNOPSIS
977
+
__guarded_by(&pool_lock) LIST_HEAD(free_stacks);
978
+
.SH "SEE ALSO"
979
+
.PP
980
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
981
+
rst: |
982
+
.. c:macro:: free_stacks
983
+
984
+
``__guarded_by(&pool_lock) LIST_HEAD(free_stacks);``
985
+
986
+
Freelist of stack records within stack_pools.
987
+
- name: stack_pools
988
+
description: mock_tests/kdoc-drop-ctx-lock.c line 94
989
+
fname: mock_tests/kdoc-drop-ctx-lock.c
990
+
source: |
991
+
/**
992
+
* var stack_pools - Array of memory regions that store stack records.
993
+
*
994
+
*/
995
+
void **stack_pools __pt_guarded_by(&pool_lock);
996
+
expected:
997
+
- man: |
998
+
.TH "var stack_pools" 9 "February 2026" "mock_tests" "Kernel API Manual"
999
+
.SH NAME
1000
+
stack_pools \- Array of memory regions that store stack records.
1001
+
.SH SYNOPSIS
1002
+
void **stack_pools __pt_guarded_by(&pool_lock);
1003
+
.SH "SEE ALSO"
1004
+
.PP
1005
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1006
+
rst: |
1007
+
.. c:macro:: stack_pools
1008
+
1009
+
``void **stack_pools __pt_guarded_by(&pool_lock);``
1010
+
1011
+
Array of memory regions that store stack records.
1012
+
- name: prepare_report_consumer
1013
+
description: mock_tests/kdoc-drop-ctx-lock.c line 103
1014
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1015
+
source: |
1016
+
/**
1017
+
* prepare_report_consumer - prepare the report consumer
1018
+
* @flags: flags
1019
+
* @ai: not that AI
1020
+
* @other_info: yes that
1021
+
*/
1022
+
bool prepare_report_consumer(unsigned long *flags,
1023
+
const struct access_info *ai,
1024
+
struct other_info *other_info)
1025
+
__cond_acquires(true, &report_lock)
1026
+
{
1027
+
expected:
1028
+
- man: |
1029
+
.TH "prepare_report_consumer" 9 "February 2026" "mock_tests" "Kernel API Manual"
1030
+
.SH NAME
1031
+
prepare_report_consumer \- prepare the report consumer
1032
+
.SH SYNOPSIS
1033
+
.B "bool" prepare_report_consumer
1034
+
.BI "(unsigned long *flags " ","
1035
+
.BI "const struct access_info *ai " ","
1036
+
.BI "struct other_info *other_info " ");"
1037
+
.SH ARGUMENTS
1038
+
.IP "flags" 12
1039
+
flags
1040
+
.IP "ai" 12
1041
+
not that AI
1042
+
.IP "other_info" 12
1043
+
yes that
1044
+
.SH "SEE ALSO"
1045
+
.PP
1046
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1047
+
rst: |
1048
+
.. c:function:: bool prepare_report_consumer (unsigned long *flags, const struct access_info *ai, struct other_info *other_info)
1049
+
1050
+
prepare the report consumer
1051
+
1052
+
.. container:: kernelindent
1053
+
1054
+
**Parameters**
1055
+
1056
+
``unsigned long *flags``
1057
+
flags
1058
+
1059
+
``const struct access_info *ai``
1060
+
not that AI
1061
+
1062
+
``struct other_info *other_info``
1063
+
yes that
1064
+
- name: tcp_sigpool_start
1065
+
description: mock_tests/kdoc-drop-ctx-lock.c line 117
1066
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1067
+
source: |
1068
+
/**
1069
+
* tcp_sigpool_start - start a tcp message of @id, using @c
1070
+
* @id: TCP message ID
1071
+
* @c: the &tcp_sigpool to use
1072
+
*/
1073
+
int tcp_sigpool_start(unsigned int id, struct tcp_sigpool *c) __cond_acquires(0, RCU_BH)
1074
+
{
1075
+
expected:
1076
+
- man: |
1077
+
.TH "tcp_sigpool_start" 9 "February 2026" "mock_tests" "Kernel API Manual"
1078
+
.SH NAME
1079
+
tcp_sigpool_start \- start a tcp message of @id, using @c
1080
+
.SH SYNOPSIS
1081
+
.B "int" tcp_sigpool_start
1082
+
.BI "(unsigned int id " ","
1083
+
.BI "struct tcp_sigpool *c " ");"
1084
+
.SH ARGUMENTS
1085
+
.IP "id" 12
1086
+
TCP message ID
1087
+
.IP "c" 12
1088
+
the \fItcp_sigpool\fP to use
1089
+
.SH "SEE ALSO"
1090
+
.PP
1091
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1092
+
rst: |
1093
+
.. c:function:: int tcp_sigpool_start (unsigned int id, struct tcp_sigpool *c)
1094
+
1095
+
start a tcp message of **id**, using **c**
1096
+
1097
+
.. container:: kernelindent
1098
+
1099
+
**Parameters**
1100
+
1101
+
``unsigned int id``
1102
+
TCP message ID
1103
+
1104
+
``struct tcp_sigpool *c``
1105
+
the :c:type:`tcp_sigpool` to use
1106
+
- name: undo_report_consumer
1107
+
description: mock_tests/kdoc-drop-ctx-lock.c line 129
1108
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1109
+
source: |
1110
+
/**
1111
+
* undo_report_consumer - teardown a report consumer
1112
+
* @flags: those flags
1113
+
* @ai: not that AI
1114
+
* @other_info: yes that
1115
+
*/
1116
+
bool undo_report_consumer(unsigned long *flags,
1117
+
const struct access_info *ai,
1118
+
struct other_info *other_info)
1119
+
__cond_releases(true, &report_lock)
1120
+
{
1121
+
expected:
1122
+
- man: |
1123
+
.TH "undo_report_consumer" 9 "February 2026" "mock_tests" "Kernel API Manual"
1124
+
.SH NAME
1125
+
undo_report_consumer \- teardown a report consumer
1126
+
.SH SYNOPSIS
1127
+
.B "bool" undo_report_consumer
1128
+
.BI "(unsigned long *flags " ","
1129
+
.BI "const struct access_info *ai " ","
1130
+
.BI "struct other_info *other_info " ");"
1131
+
.SH ARGUMENTS
1132
+
.IP "flags" 12
1133
+
those flags
1134
+
.IP "ai" 12
1135
+
not that AI
1136
+
.IP "other_info" 12
1137
+
yes that
1138
+
.SH "SEE ALSO"
1139
+
.PP
1140
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1141
+
rst: |
1142
+
.. c:function:: bool undo_report_consumer (unsigned long *flags, const struct access_info *ai, struct other_info *other_info)
1143
+
1144
+
teardown a report consumer
1145
+
1146
+
.. container:: kernelindent
1147
+
1148
+
**Parameters**
1149
+
1150
+
``unsigned long *flags``
1151
+
those flags
1152
+
1153
+
``const struct access_info *ai``
1154
+
not that AI
1155
+
1156
+
``struct other_info *other_info``
1157
+
yes that
1158
+
- name: debugfs_enter_cancellation
1159
+
description: mock_tests/kdoc-drop-ctx-lock.c line 143
1160
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1161
+
source: |
1162
+
/**
1163
+
* debugfs_enter_cancellation - begin a cancellation operation on @file
1164
+
* @file: the target file
1165
+
* @cancellation: the operation to execute
1166
+
*/
1167
+
void debugfs_enter_cancellation(struct file *file,
1168
+
struct debugfs_cancellation *cancellation) __acquires(cancellation)
1169
+
{ }
1170
+
expected:
1171
+
- man: |
1172
+
.TH "debugfs_enter_cancellation" 9 "February 2026" "mock_tests" "Kernel API Manual"
1173
+
.SH NAME
1174
+
debugfs_enter_cancellation \- begin a cancellation operation on @file
1175
+
.SH SYNOPSIS
1176
+
.B "void" debugfs_enter_cancellation
1177
+
.BI "(struct file *file " ","
1178
+
.BI "struct debugfs_cancellation *cancellation " ");"
1179
+
.SH ARGUMENTS
1180
+
.IP "file" 12
1181
+
the target file
1182
+
.IP "cancellation" 12
1183
+
the operation to execute
1184
+
.SH "SEE ALSO"
1185
+
.PP
1186
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1187
+
rst: |
1188
+
.. c:function:: void debugfs_enter_cancellation (struct file *file, struct debugfs_cancellation *cancellation)
1189
+
1190
+
begin a cancellation operation on **file**
1191
+
1192
+
.. container:: kernelindent
1193
+
1194
+
**Parameters**
1195
+
1196
+
``struct file *file``
1197
+
the target file
1198
+
1199
+
``struct debugfs_cancellation *cancellation``
1200
+
the operation to execute
1201
+
- name: debugfs_leave_cancellation
1202
+
description: mock_tests/kdoc-drop-ctx-lock.c line 152
1203
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1204
+
source: |
1205
+
/**
1206
+
* debugfs_leave_cancellation - wrapup the cancellation operation on @file
1207
+
* @file: the target file
1208
+
* @cancellation: the operation to wrapup
1209
+
*/
1210
+
void debugfs_leave_cancellation(struct file *file,
1211
+
struct debugfs_cancellation *cancellation) __releases(cancellation)
1212
+
{ }
1213
+
expected:
1214
+
- man: |
1215
+
.TH "debugfs_leave_cancellation" 9 "February 2026" "mock_tests" "Kernel API Manual"
1216
+
.SH NAME
1217
+
debugfs_leave_cancellation \- wrapup the cancellation operation on @file
1218
+
.SH SYNOPSIS
1219
+
.B "void" debugfs_leave_cancellation
1220
+
.BI "(struct file *file " ","
1221
+
.BI "struct debugfs_cancellation *cancellation " ");"
1222
+
.SH ARGUMENTS
1223
+
.IP "file" 12
1224
+
the target file
1225
+
.IP "cancellation" 12
1226
+
the operation to wrapup
1227
+
.SH "SEE ALSO"
1228
+
.PP
1229
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1230
+
rst: |
1231
+
.. c:function:: void debugfs_leave_cancellation (struct file *file, struct debugfs_cancellation *cancellation)
1232
+
1233
+
wrapup the cancellation operation on **file**
1234
+
1235
+
.. container:: kernelindent
1236
+
1237
+
**Parameters**
1238
+
1239
+
``struct file *file``
1240
+
the target file
1241
+
1242
+
``struct debugfs_cancellation *cancellation``
1243
+
the operation to wrapup
1244
+
- name: acpi_os_acquire_lock
1245
+
description: mock_tests/kdoc-drop-ctx-lock.c line 161
1246
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1247
+
source: |
1248
+
/**
1249
+
* acpi_os_acquire_lock - Acquire a spinlock.
1250
+
* @lockp: pointer to the spinlock_t.
1251
+
*/
1252
+
acpi_cpu_flags acpi_os_acquire_lock(acpi_spinlock lockp)
1253
+
__acquires(lockp)
1254
+
{
1255
+
expected:
1256
+
- man: |
1257
+
.TH "acpi_os_acquire_lock" 9 "February 2026" "mock_tests" "Kernel API Manual"
1258
+
.SH NAME
1259
+
acpi_os_acquire_lock \- Acquire a spinlock.
1260
+
.SH SYNOPSIS
1261
+
.B "acpi_cpu_flags" acpi_os_acquire_lock
1262
+
.BI "(acpi_spinlock lockp " ");"
1263
+
.SH ARGUMENTS
1264
+
.IP "lockp" 12
1265
+
pointer to the spinlock_t.
1266
+
.SH "SEE ALSO"
1267
+
.PP
1268
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1269
+
rst: |
1270
+
.. c:function:: acpi_cpu_flags acpi_os_acquire_lock (acpi_spinlock lockp)
1271
+
1272
+
Acquire a spinlock.
1273
+
1274
+
.. container:: kernelindent
1275
+
1276
+
**Parameters**
1277
+
1278
+
``acpi_spinlock lockp``
1279
+
pointer to the spinlock_t.
1280
+
- name: acpi_os_release_lock
1281
+
description: mock_tests/kdoc-drop-ctx-lock.c line 172
1282
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1283
+
source: |
1284
+
/**
1285
+
* acpi_os_release_lock - Release a spinlock.
1286
+
* @lockp: pointer to the spinlock_t.
1287
+
* @not_used: these flags are not used.
1288
+
*/
1289
+
void acpi_os_release_lock(acpi_spinlock lockp, acpi_cpu_flags not_used)
1290
+
__releases(lockp)
1291
+
{
1292
+
expected:
1293
+
- man: |
1294
+
.TH "acpi_os_release_lock" 9 "February 2026" "mock_tests" "Kernel API Manual"
1295
+
.SH NAME
1296
+
acpi_os_release_lock \- Release a spinlock.
1297
+
.SH SYNOPSIS
1298
+
.B "void" acpi_os_release_lock
1299
+
.BI "(acpi_spinlock lockp " ","
1300
+
.BI "acpi_cpu_flags not_used " ");"
1301
+
.SH ARGUMENTS
1302
+
.IP "lockp" 12
1303
+
pointer to the spinlock_t.
1304
+
.IP "not_used" 12
1305
+
these flags are not used.
1306
+
.SH "SEE ALSO"
1307
+
.PP
1308
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1309
+
rst: |
1310
+
.. c:function:: void acpi_os_release_lock (acpi_spinlock lockp, acpi_cpu_flags not_used)
1311
+
1312
+
Release a spinlock.
1313
+
1314
+
.. container:: kernelindent
1315
+
1316
+
**Parameters**
1317
+
1318
+
``acpi_spinlock lockp``
1319
+
pointer to the spinlock_t.
1320
+
1321
+
``acpi_cpu_flags not_used``
1322
+
these flags are not used.
1323
+
- name: tx
1324
+
description: mock_tests/kdoc-drop-ctx-lock.c line 183
1325
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1326
+
source: |
1327
+
/**
1328
+
* tx - transmit message ID @id
1329
+
* @id: message ID to transmit
1330
+
*/
1331
+
int tx(int id) __must_hold(&txlock)
1332
+
{
1333
+
expected:
1334
+
- man: |
1335
+
.TH "tx" 9 "February 2026" "mock_tests" "Kernel API Manual"
1336
+
.SH NAME
1337
+
tx \- transmit message ID @id
1338
+
.SH SYNOPSIS
1339
+
.B "int" tx
1340
+
.BI "(int id " ");"
1341
+
.SH ARGUMENTS
1342
+
.IP "id" 12
1343
+
message ID to transmit
1344
+
.SH "SEE ALSO"
1345
+
.PP
1346
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1347
+
rst: |
1348
+
.. c:function:: int tx (int id)
1349
+
1350
+
transmit message ID **id**
1351
+
1352
+
.. container:: kernelindent
1353
+
1354
+
**Parameters**
1355
+
1356
+
``int id``
1357
+
message ID to transmit
1358
+
- name: contend_for_bm
1359
+
description: mock_tests/kdoc-drop-ctx-lock.c line 192
1360
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1361
+
source: |
1362
+
/**
1363
+
* contend_for_bm - try to become the bus master
1364
+
* @card: the &fw_card (describes the bus)
1365
+
*/
1366
+
enum bm_contention_outcome contend_for_bm(struct fw_card *card)
1367
+
__must_hold(&card->lock)
1368
+
{
1369
+
expected:
1370
+
- man: |
1371
+
.TH "contend_for_bm" 9 "February 2026" "mock_tests" "Kernel API Manual"
1372
+
.SH NAME
1373
+
contend_for_bm \- try to become the bus master
1374
+
.SH SYNOPSIS
1375
+
.B "enum bm_contention_outcome" contend_for_bm
1376
+
.BI "(struct fw_card *card " ");"
1377
+
.SH ARGUMENTS
1378
+
.IP "card" 12
1379
+
the \fIfw_card\fP (describes the bus)
1380
+
.SH "SEE ALSO"
1381
+
.PP
1382
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1383
+
rst: |
1384
+
.. c:function:: enum bm_contention_outcome contend_for_bm (struct fw_card *card)
1385
+
1386
+
try to become the bus master
1387
+
1388
+
.. container:: kernelindent
1389
+
1390
+
**Parameters**
1391
+
1392
+
``struct fw_card *card``
1393
+
the :c:type:`fw_card` (describes the bus)
1394
+
- name: prepare_report_producer
1395
+
description: mock_tests/kdoc-drop-ctx-lock.c line 202
1396
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1397
+
source: |
1398
+
/**
1399
+
* prepare_report_producer - prepare the report producer
1400
+
* @flags: still flags
1401
+
* @ai: some AI
1402
+
* @other_info: Populate @other_info; requires that the provided
1403
+
* @other_info not in use.
1404
+
*/
1405
+
void prepare_report_producer(unsigned long *flags,
1406
+
const struct access_info *ai,
1407
+
struct other_info *other_info)
1408
+
__must_not_hold(&report_lock)
1409
+
{ }
1410
+
expected:
1411
+
- man: |
1412
+
.TH "prepare_report_producer" 9 "February 2026" "mock_tests" "Kernel API Manual"
1413
+
.SH NAME
1414
+
prepare_report_producer \- prepare the report producer
1415
+
.SH SYNOPSIS
1416
+
.B "void" prepare_report_producer
1417
+
.BI "(unsigned long *flags " ","
1418
+
.BI "const struct access_info *ai " ","
1419
+
.BI "struct other_info *other_info " ");"
1420
+
.SH ARGUMENTS
1421
+
.IP "flags" 12
1422
+
still flags
1423
+
.IP "ai" 12
1424
+
some AI
1425
+
.IP "other_info" 12
1426
+
Populate \fIother_info\fP; requires that the provided
1427
+
\fIother_info\fP not in use.
1428
+
.SH "SEE ALSO"
1429
+
.PP
1430
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1431
+
rst: |
1432
+
.. c:function:: void prepare_report_producer (unsigned long *flags, const struct access_info *ai, struct other_info *other_info)
1433
+
1434
+
prepare the report producer
1435
+
1436
+
.. container:: kernelindent
1437
+
1438
+
**Parameters**
1439
+
1440
+
``unsigned long *flags``
1441
+
still flags
1442
+
1443
+
``const struct access_info *ai``
1444
+
some AI
1445
+
1446
+
``struct other_info *other_info``
1447
+
Populate **other_info**; requires that the provided
1448
+
**other_info** not in use.
1449
+
- name: crypto_alg_lookup
1450
+
description: mock_tests/kdoc-drop-ctx-lock.c line 215
1451
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1452
+
source: |
1453
+
/**
1454
+
* __crypto_alg_lookup() - lookup the algorithm by name/type/mask
1455
+
* @name: name to search for
1456
+
* @type: type to search for
1457
+
* @mask: mask to match
1458
+
*/
1459
+
struct crypto_alg *__crypto_alg_lookup(const char *name, u32 type,
1460
+
u32 mask)
1461
+
__must_hold_shared(&crypto_alg_sem)
1462
+
{
1463
+
expected:
1464
+
- man: |
1465
+
.TH "__crypto_alg_lookup" 9 "February 2026" "mock_tests" "Kernel API Manual"
1466
+
.SH NAME
1467
+
__crypto_alg_lookup \- lookup the algorithm by name/type/mask
1468
+
.SH SYNOPSIS
1469
+
.B "struct crypto_alg *" __crypto_alg_lookup
1470
+
.BI "(const char *name " ","
1471
+
.BI "u32 type " ","
1472
+
.BI "u32 mask " ");"
1473
+
.SH ARGUMENTS
1474
+
.IP "name" 12
1475
+
name to search for
1476
+
.IP "type" 12
1477
+
type to search for
1478
+
.IP "mask" 12
1479
+
mask to match
1480
+
.SH "SEE ALSO"
1481
+
.PP
1482
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1483
+
rst: |
1484
+
.. c:function:: struct crypto_alg * __crypto_alg_lookup (const char *name, u32 type, u32 mask)
1485
+
1486
+
lookup the algorithm by name/type/mask
1487
+
1488
+
.. container:: kernelindent
1489
+
1490
+
**Parameters**
1491
+
1492
+
``const char *name``
1493
+
name to search for
1494
+
1495
+
``u32 type``
1496
+
type to search for
1497
+
1498
+
``u32 mask``
1499
+
mask to match
1500
+
- name: down_read_trylock
1501
+
description: mock_tests/kdoc-drop-ctx-lock.c line 228
1502
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1503
+
source: |
1504
+
/**
1505
+
* down_read_trylock - trylock for reading
1506
+
* @sem: the semaphore to try to lock
1507
+
*
1508
+
* Returns: 1 if successful, 0 if contention
1509
+
*/
1510
+
extern int down_read_trylock(struct rw_semaphore *sem) __cond_acquires_shared(true, sem);
1511
+
expected:
1512
+
- man: |
1513
+
.TH "down_read_trylock" 9 "February 2026" "mock_tests" "Kernel API Manual"
1514
+
.SH NAME
1515
+
down_read_trylock \- trylock for reading
1516
+
.SH SYNOPSIS
1517
+
.B "int" down_read_trylock
1518
+
.BI "(struct rw_semaphore *sem " ");"
1519
+
.SH ARGUMENTS
1520
+
.IP "sem" 12
1521
+
the semaphore to try to lock
1522
+
.SH "RETURN"
1523
+
1 if successful, 0 if contention
1524
+
.SH "SEE ALSO"
1525
+
.PP
1526
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1527
+
rst: |
1528
+
.. c:function:: int down_read_trylock (struct rw_semaphore *sem)
1529
+
1530
+
trylock for reading
1531
+
1532
+
.. container:: kernelindent
1533
+
1534
+
**Parameters**
1535
+
1536
+
``struct rw_semaphore *sem``
1537
+
the semaphore to try to lock
1538
+
1539
+
**Return**
1540
+
1541
+
1 if successful, 0 if contention
1542
+
- name: tomoyo_read_lock
1543
+
description: mock_tests/kdoc-drop-ctx-lock.c line 236
1544
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1545
+
source: |
1546
+
/**
1547
+
* tomoyo_read_lock - Take lock for protecting policy.
1548
+
*
1549
+
* Returns: index number for tomoyo_read_unlock().
1550
+
*/
1551
+
int tomoyo_read_lock(void)
1552
+
__acquires_shared(&tomoyo_ss)
1553
+
{
1554
+
expected:
1555
+
- man: |
1556
+
.TH "tomoyo_read_lock" 9 "February 2026" "mock_tests" "Kernel API Manual"
1557
+
.SH NAME
1558
+
tomoyo_read_lock \- Take lock for protecting policy.
1559
+
.SH SYNOPSIS
1560
+
.B "int" tomoyo_read_lock
1561
+
.BI "(void " ");"
1562
+
.SH ARGUMENTS
1563
+
.IP "void" 12
1564
+
no arguments
1565
+
.SH "RETURN"
1566
+
index number for \fBtomoyo_read_unlock\fP.
1567
+
.SH "SEE ALSO"
1568
+
.PP
1569
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1570
+
rst: |
1571
+
.. c:function:: int tomoyo_read_lock (void)
1572
+
1573
+
Take lock for protecting policy.
1574
+
1575
+
.. container:: kernelindent
1576
+
1577
+
**Parameters**
1578
+
1579
+
``void``
1580
+
no arguments
1581
+
1582
+
**Return**
1583
+
1584
+
index number for tomoyo_read_unlock().
1585
+
- name: tomoyo_read_unlock
1586
+
description: mock_tests/kdoc-drop-ctx-lock.c line 247
1587
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1588
+
source: |
1589
+
/**
1590
+
* tomoyo_read_unlock - Release lock for protecting policy.
1591
+
*
1592
+
* @idx: Index number returned by tomoyo_read_lock().
1593
+
*/
1594
+
void tomoyo_read_unlock(int idx)
1595
+
__releases_shared(&tomoyo_ss)
1596
+
{ }
1597
+
expected:
1598
+
- man: |
1599
+
.TH "tomoyo_read_unlock" 9 "February 2026" "mock_tests" "Kernel API Manual"
1600
+
.SH NAME
1601
+
tomoyo_read_unlock \- Release lock for protecting policy.
1602
+
.SH SYNOPSIS
1603
+
.B "void" tomoyo_read_unlock
1604
+
.BI "(int idx " ");"
1605
+
.SH ARGUMENTS
1606
+
.IP "idx" 12
1607
+
Index number returned by \fBtomoyo_read_lock\fP.
1608
+
.SH "SEE ALSO"
1609
+
.PP
1610
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1611
+
rst: |
1612
+
.. c:function:: void tomoyo_read_unlock (int idx)
1613
+
1614
+
Release lock for protecting policy.
1615
+
1616
+
.. container:: kernelindent
1617
+
1618
+
**Parameters**
1619
+
1620
+
``int idx``
1621
+
Index number returned by tomoyo_read_lock().
1622
+
- name: c_stop
1623
+
description: mock_tests/kdoc-drop-ctx-lock.c line 256
1624
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1625
+
source: |
1626
+
/**
1627
+
* c_stop - stop the seq_file iteration
1628
+
* @m: the &struct seq_file
1629
+
* @p: handle
1630
+
*/
1631
+
void c_stop(struct seq_file *m, void *p)
1632
+
__releases_shared(&crypto_alg_sem)
1633
+
{ }
1634
+
expected:
1635
+
- man: |
1636
+
.TH "c_stop" 9 "February 2026" "mock_tests" "Kernel API Manual"
1637
+
.SH NAME
1638
+
c_stop \- stop the seq_file iteration
1639
+
.SH SYNOPSIS
1640
+
.B "void" c_stop
1641
+
.BI "(struct seq_file *m " ","
1642
+
.BI "void *p " ");"
1643
+
.SH ARGUMENTS
1644
+
.IP "m" 12
1645
+
the \fIstruct seq_file\fP
1646
+
.IP "p" 12
1647
+
handle
1648
+
.SH "SEE ALSO"
1649
+
.PP
1650
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1651
+
rst: |
1652
+
.. c:function:: void c_stop (struct seq_file *m, void *p)
1653
+
1654
+
stop the seq_file iteration
1655
+
1656
+
.. container:: kernelindent
1657
+
1658
+
**Parameters**
1659
+
1660
+
``struct seq_file *m``
1661
+
the :c:type:`struct seq_file <seq_file>`
1662
+
1663
+
``void *p``
1664
+
handle
1665
+
- name: spin_lock
1666
+
description: mock_tests/kdoc-drop-ctx-lock.c line 265
1667
+
fname: mock_tests/kdoc-drop-ctx-lock.c
1668
+
source: |
1669
+
/**
1670
+
* spin_lock - spin until the @lock is acquired
1671
+
* @lock: the spinlock
1672
+
*/
1673
+
void spin_lock(spinlock_t *lock)
1674
+
__acquires(lock) __no_context_analysis
1675
+
{ }
1676
+
expected:
1677
+
- man: |
1678
+
.TH "spin_lock" 9 "February 2026" "mock_tests" "Kernel API Manual"
1679
+
.SH NAME
1680
+
spin_lock \- spin until the @lock is acquired
1681
+
.SH SYNOPSIS
1682
+
.B "void" spin_lock
1683
+
.BI "(spinlock_t *lock " ");"
1684
+
.SH ARGUMENTS
1685
+
.IP "lock" 12
1686
+
the spinlock
1687
+
.SH "SEE ALSO"
1688
+
.PP
1689
+
Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
1690
+
rst: |
1691
+
.. c:function:: void spin_lock (spinlock_t *lock)
1692
+
1693
+
spin until the **lock** is acquired
1694
+
1695
+
.. container:: kernelindent
1696
+
1697
+
**Parameters**
1698
+
1699
+
``spinlock_t *lock``
1700
+
the spinlock