Christos Margiolis: projects

Inline function tracing with the kinst DTrace provider

Tue, 18 Jul 2023 00:00:00 +1200

Quick background

DTrace is a framework that gives administrators and kernel developers the ability to observe kernel behavior in real time. DTrace has modules called “providers”, that perform a particular instrumentation in the kernel (and sometimes userland) using “probes”.

kinst is a new low-level DTrace provider co-authored by Christos Margiolis and Mark Johnston for the FreeBSD operating system, which allows the user to trace arbitrary instructions in kernel functions. It is part of the base system as of FreeBSD 14.0.

kinst probes take the form of kinst::<function>:<instruction>, where <function> is the kernel function to be traced, and <instruction> is the offset to the instruction, relative to the beginning of the function, and can be obtained from the function’s disassembly. If the <instruction> field is left empty, kinst will trace all instructions in that function. Unlike FBT, kinst can also trace the entry and return points of inline functions (see Inline function tracing).

The origin of the name is inspired from an early paper written by A. Tamches and B. Miller discussing a tracing tool they developed called “KernInst”.

Usage

Find the offset corresponding to the third instruction in vm_fault() and trace it, printing the contents of the RSI register:

# kgdb
(kgdb) disas /r vm_fault
Dump of assembler code for function vm_fault:
   0xffffffff80f4e470 <+0>:     55      push   %rbp
   0xffffffff80f4e471 <+1>:     48 89 e5        mov    %rsp,%rbp
   0xffffffff80f4e474 <+4>:     41 57   push   %r15
...

# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}'
  2  81500                       vm_fault:4 0x827c56000
  2  81500                       vm_fault:4 0x827878000
  2  81500                       vm_fault:4 0x1fab9bef0000
  2  81500                       vm_fault:4 0xe16cf749000
  0  81500                       vm_fault:4 0x13587c366000
  ^C

Trace the return point of critical_enter(), which is an inline function:

# dtrace -n 'kinst::critical_enter:return'
dtrace: description 'kinst::critical_enter:return' matched 130 probes
CPU     ID                    FUNCTION:NAME
  1  71024                spinlock_enter:53
  0  71024                spinlock_enter:53
  1  70992                uma_zalloc_arg:49
  1  70925    malloc_type_zone_allocated:21
  1  70994                uma_zfree_arg:365
  1  70924             malloc_type_freed:21
  1  71024                spinlock_enter:53
  0  71024                spinlock_enter:53
  0  70947         _epoch_enter_preempt:122
  0  70949           _epoch_exit_preempt:28
  ^C

Inline function tracing

How it works

To trace inline functions, libdtrace makes use of the DWARF Debugging Standard, to detect if the function specified is an inline call. If it is, D syntax is transformed to create kinst probes for each of the inline copies found. All work is done in libdtrace, instead of kinst(4). This feature has been added to FreeBSD with this patch.

Contrary to how kinst expects a <function>:<instruction> tuple to create probes, for inline functions, <instruction> is replaced by entry and return.

Syntactic transformations

Suppose the user wants to trace a probe of the form:

kinst::<func>:<entry|return>
/<pred>/
{
	<acts>
}

libdtrace sees that we have specified entry or return, instead of an offset, which is what a regular kinst probe would look like, so it loops through all loaded kernel modules and parses their DWARF and ELF info to see if this function is an inline — if not, the probe is converted to an FBT one, so that we don’t duplicate FBT’s functionality in kinst:

# dtrace -dn 'kinst::malloc:entry {exit(0);}'
fbt::malloc:entry
{
        exit(0x0);
}

dtrace: description 'kinst::malloc:entry ' matched 1 probe
CPU     ID                    FUNCTION:NAME
  2  31144                     malloc:entry

If the function however is an inline, libdtrace will find all calls refering to this function and create new probes for each one of the inline copies found.

# dtrace -dn 'kinst::cam_iosched_has_more_trim:entry { printf("\t%d\t%s", pid, execname); }'
kinst::cam_iosched_get_trim:13,
kinst::cam_iosched_next_bio:13,
kinst::cam_iosched_schedule:40
{
	printf("\t%d\t%s", pid, execname);
}

dtrace: description 'kinst::cam_iosched_has_more_trim:entry ' matched 4 probes
CPU     ID                    FUNCTION:NAME
  0  81502          cam_iosched_schedule:40     2       clock
  0  81501          cam_iosched_next_bio:13     2       clock
  2  81502          cam_iosched_schedule:40     2       clock
  1  81502          cam_iosched_next_bio:13     0	kernel
  1  81503          cam_iosched_schedule:40     0	kernel
^C

There can also be both inline and non-inline definitions of the same function. In this case, kinst creates an additional FBT probe for the non-inline definition.

The -d flag used in these examples to dump the D script after libdtrace has applied syntactic transformations, has been added to DTrace in commit 1e136a9cbd3a.

Heuristic for calculating the `entry` and `return` offsets

libdtrace reuses parts of the mechanism implemented in my inlinecall(1) program, which finds and prints all call sites of a given inline function:

$ ./inlinecall vm_page_mvqueue /usr/lib/debug/boot/kernel/kernel.debug
/usr/src/sys/vm/vm_page.c:4142
        [0xffffffff80f91541 - 0xffffffff80f91599]       /usr/src/sys/vm/vm_page.c:4195  vm_page_readahead_finish()
        [0xffffffff80f915f5 - 0xffffffff80f91603]       /usr/src/sys/vm/vm_page.c:4195  vm_page_readahead_finish()
        [0xffffffff80f9163d - 0xffffffff80f916c2]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()
        [0xffffffff80f916cd - 0xffffffff80f916e5]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()
        [0xffffffff80f916fe - 0xffffffff80f91747]       /usr/src/sys/vm/vm_page.c:4195  vm_page_deactivate()
        [0xffffffff80f91750 - 0xffffffff80f91768]       /usr/src/sys/vm/vm_page.c:4195  vm_page_deactivate()
        [0xffffffff80f94a59 - 0xffffffff80f94aa9]       /usr/src/sys/vm/vm_page.c:4195  vm_page_reclaim_contig_domain()
        [0xffffffff80f94de4 - 0xffffffff80f94df9]       /usr/src/sys/vm/vm_page.c:4195  vm_page_reclaim_contig_domain()
        [0xffffffff80f9661e - 0xffffffff80f96667]       /usr/src/sys/vm/vm_page.c:4202  vm_page_deactivate_noreuse()
        [0xffffffff80f96670 - 0xffffffff80f96688]       /usr/src/sys/vm/vm_page.c:4202  vm_page_deactivate_noreuse()
        [0xffffffff80f9669e - 0xffffffff80f966ea]       /usr/src/sys/vm/vm_page.c:4212  vm_page_launder()
        [0xffffffff80f966f3 - 0xffffffff80f9670b]       /usr/src/sys/vm/vm_page.c:4212  vm_page_launder()
        [0xffffffff80f96d4c - 0xffffffff80f96dac]       /usr/src/sys/vm/vm_page.c:4212  vm_page_advise()
        [0xffffffff80f96dac - 0xffffffff80f96e07]       /usr/src/sys/vm/vm_page.c:4202  vm_page_advise()

Most of the entries above appear twice but with different boundaries:

        [0xffffffff80f9163d - 0xffffffff80f916c2]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()
        [0xffffffff80f916cd - 0xffffffff80f916e5]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()

This means that the inline copy’s boundaries are split into more than one parts, which can be caused by having early returns inside the inline function. By using this assumption, we can deduce that the entry point of the function is 0xffffffff80f9163d, and each of the upper boundaries are the return points (i.e 0xffffffff80f916c2 and 0xffffffff80f916e5), so we end up with one entry and two return trace points.

However, this is not exactly true, because the final return address given by DWARF corresponds to the instruction after the actual return instruction. We can verify this in GDB using the two return addresses from the example above:

# kgdb
(kgdb) disas vm_page_activate
...
   0xffffffff80f916c0 <+144>:   jmp    0xffffffff80f91673 <vm_page_activate+67>
   0xffffffff80f916c2 <+146>:   add    $0x8,%rsp			<-- first address given by DWARF
...
   0xffffffff80f916e0 <+176>:   call   0xffffffff80bed360 <panic>	<-- last instruction
									<-- second address should be here

It turns out that 0xffffffff80f916e5 is, in fact, outside vm_page_activate() altogether!

(kgdb) x/i 0xffffffff80f916e5
   0xffffffff80f916e5:  data16 cs nopw 0x0(%rax,%rax,1)

After running a couple of tests, I came to the conclusion that there are two possible cases with return addresses:

If the inline copy’s DIE has DW_AT_lowpc and DW_AT_highpc set, the return address is always outside the inline function’s boundaries.
If the inline copy’s DIE has DW_AT_ranges set, only the last return address is outside the inline function’s boundaries.
Combining the two bullets above, if the return address of the inline function is the same as the upper boundary of the caller function, it’s outside both the inline copy’s and the caller function’s boundaries.

In order to fix this, we have to go one instruction back whenever we come across one of those 3 cases.

Finally the entry offset is calculated as:

inline_bound_lo - caller_bound_lo

And the return one, including the modifications (if any) discussed above, as:

inline_bound_hi - caller_bound_lo

These offsets are then used to create regular kinst probes of the form kinst::<func>:<instruction>, which is what kinst actually expects:

# dtrace -dn 'kinst::vm_page_mvqueue:entry,kinst::vm_page_mvqueue:return'
dtrace: description 'kinst::vm_page_mvqueue:entry,kinst::vm_page_mvqueue:return' matched 22 probes
kinst::vm_page_readahead_finish:33,
kinst::vm_page_readahead_finish:121,
kinst::vm_page_activate:13,
kinst::vm_page_deactivate:14,
kinst::vm_page_reclaim_contig_domain:1961,
kinst::vm_page_deactivate_noreuse:14,
kinst::vm_page_launder:14,
kinst::vm_page_advise:236,
kinst::vm_page_advise:332,
kinst::vm_page_readahead_finish:220,
kinst::vm_page_activate:146,
kinst::vm_page_activate:176,
kinst::vm_page_deactivate:87,
kinst::vm_page_deactivate:115,
kinst::vm_page_reclaim_contig_domain:2041,
kinst::vm_page_reclaim_contig_domain:2884,
kinst::vm_page_deactivate_noreuse:87,
kinst::vm_page_deactivate_noreuse:115,
kinst::vm_page_launder:90,
kinst::vm_page_launder:118,
kinst::vm_page_advise:330,
kinst::vm_page_advise:421
{
}

CPU     ID                    FUNCTION:NAME
  3  95381              vm_page_activate:13 
  3  95389             vm_page_activate:146 
  2  95381              vm_page_activate:13 
  2  95389             vm_page_activate:146 
  1  95387               vm_page_advise:332 
  1  95400               vm_page_advise:421 
  1  95387               vm_page_advise:332 
  1  95400               vm_page_advise:421 
  1  95387               vm_page_advise:332 
^C

Using DWARF to find call sites of inline functions

Tue, 07 Feb 2023 00:00:00 +1200

What is DWARF?

From the DWARF Debugging Standard’s documentation:

This document defines a format for describing programs to facilitate user source level debugging. This description can be generated by compilers, assemblers and linkage editors. It can be used by debuggers and other tools.

Debugging information entries (DIEs) are represented as a tree, one per compilation unit (CU). Each DIE has a tag (DW_TAG_*, see DWARF PDF Figure 1) denoting its class, and attributes (DW_AT_*, see DWARF PDF Figure 2) denoting its various characteristics, associated with it.

The next entry of a DIE is a child DIE. If a DIE doesn’t have children, the next entry is a “sibling”.

Consider the following structure:

CU1 (DW_TAG_compile_unit)
	func1 (DW_TAG_subprogram)
		DW_AT_foo
		DW_AT_bar
		func2 (DW_TAG_subprogram)
			DW_AT_foo
			DW_AT_bar
	myvar (DW_TAG_variable)
		DW_AT_foo
		DW_AT_bar
CU2 (DW_TAG_compile_unit)
	...

CU1 has func1 and myvar as chidren and CU2 as siblings. func1 has func2 as a child.

The debug file can be generated by compiling with the -g option. To dump DWARF info you can use readelf -wi <file> and dwarfdump <file>.

Inline functions in DWARF

DIEs of inline function declarations have the DW_TAG_subprogram tag and the DW_AT_inline attribute. DIEs of inline copies of this function will have the DW_TAG_inlined_subroutine tag.

Attributes inline copies can have include:

DW_AT_abstract_origin: DIE offset to the inline declaration.
DW_AT_call_file: Integer denoting the file the function is called in.
DW_AT_call_line: File line.
DW_AT_call_column: File column.
DW_AT_low_pc and DW_AT_high_pc: Lower and upper call boundaries. Explained in the next section.
DW_AT_ranges: Explained in the next section.

For example, if we dump the DWARF info for my FreeBSD kernel:

$ readelf -wi /usr/lib/debug/boot/kernel/kernel.debug > ~/foo

We find that vfs_freevnodes_dec gets inlined:

 <1><1dfa144>: Abbrev Number: 94 (DW_TAG_subprogram)
    <1dfa145>   DW_AT_name        : (indirect string) vfs_freevnodes_dec
    <1dfa149>   DW_AT_decl_file   : 1
    <1dfa14a>   DW_AT_decl_line   : 1447
    <1dfa14c>   DW_AT_prototyped  : 1
    <1dfa14c>   DW_AT_inline      : 1

Inline copies will have DW_AT_abstract_origin point to the declaration’s DIEs offset, in this case 0x1dfa144. If we look for 0x1dfa144, we do indeed find a few inline copies.

 <3><1dfe45e>: Abbrev Number: 24 (DW_TAG_inlined_subroutine)
    <1dfe45f>   DW_AT_abstract_origin: <0x1dfa144>
    <1dfe463>   DW_AT_low_pc      : 0xffffffff80cf701d
    <1dfe46b>   DW_AT_high_pc     : 0x38
    <1dfe46f>   DW_AT_call_file   : 1
    <1dfe470>   DW_AT_call_line   : 3458
    <1dfe472>   DW_AT_call_column : 5

 <3><1dfd2e2>: Abbrev Number: 58 (DW_TAG_inlined_subroutine)
    <1dfd2e3>   DW_AT_abstract_origin: <0x1dfa144>
    <1dfd2e7>   DW_AT_ranges      : 0x1f1290
    <1dfd2eb>   DW_AT_call_file   : 1
    <1dfd2ec>   DW_AT_call_line   : 3405
    <1dfd2ee>   DW_AT_call_column : 3

  ...there are more

As I described in the first section, a debug file may consist of multiple CUs that define the same inline function. We want treat each CU independently, that is, each inline copy is handled relative to its CU.

Calculating call boundaries

There are 2 cases we have to take care of when calculating the actual call boundaries of an inline copy.

The DIE has `DW_AT_low_pc` and `DW_AT_high_pc`

 <3><1dfe45e>: Abbrev Number: 24 (DW_TAG_inlined_subroutine)
    <1dfe45f>   DW_AT_abstract_origin: <0x1dfa144>
    <1dfe463>   DW_AT_low_pc      : 0xffffffff80cf701d
    <1dfe46b>   DW_AT_high_pc     : 0x38
    <1dfe46f>   DW_AT_call_file   : 1
    <1dfe470>   DW_AT_call_line   : 3458
    <1dfe472>   DW_AT_call_column : 5

In this case, the lower boundary is low_pc and the upper boundary is low_pc + high_pc, which, for the DIE shown in this example, the boundaries are:

low = 0xffffffff80cf701d
high = 0xffffffff80cf701d + 0x38 = 0xffffffff80cf7055

The DIE has `DW_AT_ranges`

 <3><1dfd2e2>: Abbrev Number: 58 (DW_TAG_inlined_subroutine)
    <1dfd2e3>   DW_AT_abstract_origin: <0x1dfa144>
    <1dfd2e7>   DW_AT_ranges      : 0x1f1290
    <1dfd2eb>   DW_AT_call_file   : 1
    <1dfd2ec>   DW_AT_call_line   : 3405
    <1dfd2ee>   DW_AT_call_column : 3

This is a bit more involved. DW_AT_ranges refers to the .debug_ranges section found in debug files. We can dump the ranges:

$ dwarfdump -N /usr/lib/debug/boot/kernel/kernel.debug
.debug_ranges
 Ranges group 0:
                ranges: 3 at .debug_ranges offset 0 (0x00000000) (48 bytes)
                        [ 0] range entry    0x00000019 0x00000073
                        [ 1] range entry    0x0000007e 0x00000106
                        [ 2] range end      0x00000000 0x00000000
 Ranges group 1:
                ranges: 3 at .debug_ranges offset 48 (0x00000030) (48 bytes)
                        [ 0] range entry    0x00000022 0x0000006a
                        [ 1] range entry    0x0000007e 0x00000106
                        [ 2] range end      0x00000000 0x00000000
 ...

If we search for 0x1f1290 (the inline copy’s ranges), we find its range group:

 Ranges group 38809:
                ranges: 3 at .debug_ranges offset 2036368 (0x001f1290) (48 bytes)
                        [ 0] range entry    0x000025c8 0x000025f9
                        [ 1] range entry    0x0000261a 0x00002621
                        [ 2] range end      0x00000000 0x00000000

To get the call boundaries, we add each range entry’s boundaries to the DW_AT_low_pc of the root DIE of the CU. The root DIE is found programmatically, but I happen to know that in this case, the root DIE is:

 <0><1dee9fb>: Abbrev Number: 1 (DW_TAG_compile_unit)
    <1dee9fc>   DW_AT_producer    : (indirect string) FreeBSD clang version 13.0.0 (git@github.com:llvm/llvm-project.git llvmorg-13.0.0-0-gd7b669b3a303)
    <1deea00>   DW_AT_language    : 12	(C99)
    <1deea02>   DW_AT_name        : (indirect string) /usr/src/sys/kern/vfs_subr.c
    <1deea06>   DW_AT_stmt_list   : 0x6cb448
    <1deea0a>   DW_AT_comp_dir    : (indirect string) /usr/obj/usr/src/amd64.amd64/sys/GENERIC
    <1deea0e>   DW_AT_low_pc      : 0xffffffff80cf4020
    <1deea16>   DW_AT_high_pc     : 0xde3d

Finally, we end up with the following boundaries:

low = 0xffffffff80cf4020 + 0x000025c8 = 0xffffffff80cf65e8
high = 0xffffffff80cf4020 + 0x000025f9 = 0xffffffff80cf6619

low = 0xffffffff80cf4020 + 0x0000261a = 0xffffffff80cf663a
high = 0xffffffff80cf4020 + 0x00002621 = 0xffffffff80cf6641

Finding the caller function

There are cases where we want to know which function an inline function is being called from. Because DWARF does not encode that information, we’ll have to scan ELF symbol tables.

$ readelf -s /usr/lib/debug/boot/kernel/kernel.debug

Since we know the inline copy’s boundaries, we only have to find which symbol’s boundaries the inline copy is inside. In other words, the following condition has to be met:

sym_lower_bound <= inline_lower_bound <= inline_upper_bound <= sym_upper_bound

Because searching through ELF symbol tables manually and doing calculations by hand would take too long, the best way to do this is programmatically through LibELF.

inlinecall(1)

I wrote a little program that does everything I talked about in this post automatically. It works on FreeBSD as-is, and most likely needs some modification to get it to work on other platforms.

The program takes an inline function name and a debug file as arguments:

inlinecall <function> <file>

And outputs the results in the following form:

cu1_func_declaration_file:line
	[low_bound - high_bound]	inline_copy1_file:line	caller_func()
	[low_bound - high_bound]	inline_copy2_file:line	caller_func()
	...
cu2_func_declaration_file:line
	...
...

For example:

$ inlinecall critical_enter /usr/lib/debug/boot/kernel/kernel.debug
/usr/src/sys/sys/systm.h:175
        [0xffffffff809eb51f - 0xffffffff809eb526]       /usr/src/sys/kern/kern_intr.c:1387      intr_event_handle()
/usr/src/sys/sys/systm.h:175
        [0xffffffff80a051f4 - 0xffffffff80a05208]       /usr/src/sys/kern/kern_malloc.c:431     malloc_type_freed()
        [0xffffffff80a0514c - 0xffffffff80a0515b]       /usr/src/sys/kern/kern_malloc.c:388     malloc_type_zone_allocated()
/usr/src/sys/sys/systm.h:175
        [0xffffffff80a263c4 - 0xffffffff80a263d3]       /usr/src/sys/kern/kern_resource.c:509   rtp_to_pri()
/usr/src/sys/sys/systm.h:175
        [0xffffffff80a28f59 - 0xffffffff80a28f5f]       /usr/src/sys/kern/kern_rmlock.c:775     _rm_assert()
        [0xffffffff80a29087 - 0xffffffff80a2908d]       /usr/src/sys/kern/kern_rmlock.c:801     _rm_assert()
        [0xffffffff80a29eb0 - 0xffffffff80a29eb7]       /usr/src/sys/kern/kern_rmlock.c:645     _rm_rlock_debug()
        [0xffffffff80a28c4b - 0xffffffff80a28c5a]       /usr/src/sys/kern/kern_rmlock.c:160     unlock_rm()
...more

Nested inline functions

inlinecall(1) resolves nested inline functions recursively:

$ ./inlinecall critical_enter /usr/lib/debug/boot/kernel/kernel.debug
/usr/src/sys/sys/systm.h:175
        [0xffffffff80a19d7a - 0xffffffff80a19d8b]       /usr/src/sys/sys/buf_ring.h:80  drbr_enqueue()
/usr/src/sys/sys/systm.h:175
        [0xffffffff80a6387a - 0xffffffff80a6388b]       /usr/src/sys/sys/buf_ring.h:80  drbr_enqueue()
...

Looking at the definition of critical_enter()’s caller function in buf_ring.h:

static __inline int
buf_ring_enqueue(struct buf_ring *br, void *buf)
{
	...
	critical_enter();
	...
}

Even though inlinecall(1) reported that critical_enter() is called from drbr_enqueue() in buf_ring.h:80, we see that it’s called from buf_ring_enqueue() instead, but buf_ring_enqueue() is also an inline function:

$ ./inlinecall buf_ring_enqueue /usr/lib/debug/boot/kernel/kernel.debug
/usr/src/sys/sys/buf_ring.h:63
        [0xffffffff80a19d7a - 0xffffffff80a19dcd]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
        [0xffffffff80a19ddc - 0xffffffff80a19e18]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
        [0xffffffff80a19e1f - 0xffffffff80a19e3b]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
/usr/src/sys/sys/buf_ring.h:63
        [0xffffffff80a6387a - 0xffffffff80a638cd]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
        [0xffffffff80a638dc - 0xffffffff80a63918]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
        [0xffffffff80a6391f - 0xffffffff80a6393b]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
/usr/src/sys/sys/buf_ring.h:63
        [0xffffffff80d1f81a - 0xffffffff80d1f879]       /usr/src/sys/net/ifq.c:57       drbr_enqueue()
        [0xffffffff80d1f91d - 0xffffffff80d1f964]       /usr/src/sys/net/ifq.c:57       drbr_enqueue()
        [0xffffffff80d1f9dd - 0xffffffff80d1f9f5]       /usr/src/sys/net/ifq.c:57       drbr_enqueue()
/usr/src/sys/sys/buf_ring.h:63
        [0xffffffff80ff07ba - 0xffffffff80ff080d]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
        [0xffffffff80ff081c - 0xffffffff80ff0858]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()
        [0xffffffff80ff085f - 0xffffffff80ff087b]       /usr/src/sys/net/ifq.h:337      drbr_enqueue()

Here drbr_enqueue() is defined twice — once in ifq.h and once in ifq.c. The definition in ifq.h is also an inline definition, and in ifq.c it’s a non-inline one. We know that buf_ring_enqueue() is called from the non-inline version of drbr_enqueue(), otherwise inlinecall(1) would have reported the function which calls the inline version of drbr_enqueue().

nfy(1)

Sat, 02 Apr 2022 00:00:00 +1200

A minimal and daemonless notification program for X.

Source code | Download 0.2 | Man page

Features

Very lightweight. ~250 lines of C.
Probably no dependencies, apart from the pre-installed X11 ones. Xlib, libXft and libXrandr.
Multiple notifications are queued using a lock file. This avoids the trouble of having a daemon (e.g D-Bus) constantly running in the background.
Non-blocking behavior, so that it can be used inside scripts easily.
Configuration is done by editing config.h and recompiling the source code, in a similar fashion to suckless utilities. No knowledge of C is required to edit the file. Compilation takes around 1 second.
Clicking on the notification window will make it disappear.

nfy works by piping text into it. Text cannot be passed as argument:

$ echo 'hello world' | nfy
$ nfy < foo.txt

If stdin is empty, it exits with an error:

$ nfy
nfy: stdin is empty

Install

First make sure all settings in config.mk are set according to your system’s configuration, then:

# make install clean

Notes

If you want to use nfy(1) with cron(8), make sure to export the X Display variable inside the script running nfy(1):

export DISPLAY=":0.0"

Alternatively, export the variable in the crontab file directly.

Send feedback and bugs to <christos@margiolis.net>.

FreeBSD sound mixer improvements

Fri, 25 Feb 2022 00:00:00 +1200

This project was part of Google Summer of Code 2021, but development is still active. The development report can be found on the FreeBSD Wiki. The reason behind this project is that the FreeBSD’s OSS mixer capabilities were really basic and outdated — even un/muting didn’t exist and one had to write custom scripts for such a basic task. Setting default audio devices had to be done by tweaking sysctls and programs needing to use the mixer required DIY implementations as there was no mixer library available. The project was merged to upstream on FreeBSD 14.0.

Kernel patches

Un/muting (commit)

I decided that un/muting is better to be implemented in sound(4) in order to avoid having to write daemons or use files. The way this works is by implementing the SOUND_MIXER_READ_MUTE and SOUND_MIXER_WRITE_MUTE ioctls, which did exist in older OSS implementations, but were considered obselete. One thing to note is that the functionality isn’t the same as their old one. Older OSS versions had those 2 ioctls take/return an integer with a value of 0 or 1, which indicated whether the whole mixer is muted or not. My implementation takes/returns a bitmask that tells which devices are muted. This allows us to mute and unmute only the devices we want, instead of the whole mixer. If you’re familiar with the OSS API, this bitmask works the same way as DEVMASK, RECMASK and RECSRC.

Playback/recording mode information (commit)

Here I implemented a sysctl (dev.pcm.<N>.mode) which gives information about a device’s playback/recording mode. The rationale for this control is to include /dev/sndstat’s mixer information in the output of the new mixer(8). The sysctl can return the following values (NOTE: these values are OR’ed together if more than one mode is supported):

Value	Meaning
0x01	Mixer
0x02	Playback device
0x04	Recording device

Userland

mixer(3) implementation (commit)

mixer(3) provides a simple interface for working with the OSS mixer. The man page explains how the library works, including some examples, so there’s no need to repeat myself. You can see the library in action in the source code for mixer(8).

The basic structure of a program looks like this (link with -lmixer):

#include <err.h>
#include <mixer.h>

int
main(int argc, char *argv[])
{
	struct mixer *m;
	const char *name = "/dev/mixer0";

	if ((m = mixer_open(name)) == NULL)
		err(1, "mixer_open(%s)", name);

	/* do stuff */

	mixer_close(m);
	
	return (0);
}

mixer(8) rewrite (commit)

This implementation is a complete rewrite of the old mixer(8) utility. It now uses mixer(3) as a backend and implements all the new features the library provides. It’s got more command line options and works with a control-oriented interface inspired by OpenBSD’s mixerctl(8). Again, everything is detailed in the man page.

Old mixer(8) output:

$ mixer.old

Mixer vol      is currently set to  85:85
Mixer pcm      is currently set to 100:100
Mixer speaker  is currently set to  74:74
Mixer line     is currently set to   1:1
Mixer mic      is currently set to  67:67
Mixer mix      is currently set to  74:74
Mixer rec      is currently set to  37:37
Mixer igain    is currently set to   0:0
Mixer ogain    is currently set to 100:100
Mixer monitor  is currently set to  67:67
Recording source: mic

New mixer(8) output:

$ mixer

pcm0:mixer: <Realtek ALC662 rev3 (Analog 2.0+HP/2.0)> on hdaa0 kld snd_hda (play/rec) (default)
    vol       = 0.85:0.85     pbk
    pcm       = 1.00:1.00     pbk
    speaker   = 0.74:0.74     rec
    line      = 0.01:0.01     rec
    mic       = 0.67:0.67     rec src
    mix       = 0.74:0.74     rec
    rec       = 0.37:0.37     pbk
    igain     = 0.00:0.00     pbk
    ogain     = 1.00:1.00     pbk
    monitor   = 0.67:0.67     rec

Code and manuals

Thermometer using PIC16F877A and BME280

Mon, 14 Feb 2022 00:00:00 +1200

This embedded system measures temperature and humidity and outputs the data on an LCD. The BME280 sensor can also do pressure but I didn’t implement it because the MCU had no more space available. The whole project can be found here; I’ve also included datasheets for the MCU, sensor and LCD.

Development was done on FreeBSD using the workflow I describe here. If you’re using Microchip’s own tools, you’ll have to make some small changes to the code, but nothing too extreme.

The source code.

Components

Microchip PIC16F877A-I/P microcontroller.
Adafruit BME280 temperature, humidity and pressure sensor.
16x2 LCD.
1x 16MHz crystal oscillator.
2x 10kΩ resistor.
2x 300Ω resistor.
1x 10kΩ potentiometer.
2x 22pF ceramic capacitor.
2x LED.
2x push-button.
Breadboard and wires.
3x AAA batteries (4.5V total) or a 9V battery with a 5V voltage divider.

Safe temperature range

Component	Operating temperature
PIC16F877A	-40°C - 85°C
BME280	-40°C - 85°C
LCD	-20°C - 70°C

So, it’s best for the system to operate in the -20°C to 70°C range.

Schematic

You can also get the PDF version.

Christos Margiolis: projects

Inline function tracing with the kinst DTrace provider

Table of Contents

Quick background

Usage

Inline function tracing

How it works

Syntactic transformations

Heuristic for calculating the `entry` and `return` offsets

Using DWARF to find call sites of inline functions

Table of contents

What is DWARF?

Inline functions in DWARF

Calculating call boundaries

The DIE has `DW_AT_low_pc` and `DW_AT_high_pc`

The DIE has `DW_AT_ranges`

Finding the caller function

inlinecall(1)

Nested inline functions

nfy(1)

Features

Install

Notes

FreeBSD sound mixer improvements

Table of contents

Kernel patches

Un/muting (commit)

Playback/recording mode information (commit)

Userland

mixer(3) implementation (commit)

mixer(8) rewrite (commit)

Code and manuals

Thermometer using PIC16F877A and BME280

Components

Safe temperature range

Schematic

Christos Margiolis: projects

Inline function tracing with the kinst DTrace provider

Table of Contents

Quick background

Usage

Inline function tracing

How it works

Syntactic transformations

Heuristic for calculating the entry and return offsets

Using DWARF to find call sites of inline functions

Table of contents

What is DWARF?

Inline functions in DWARF

Calculating call boundaries

The DIE has DW_AT_low_pc and DW_AT_high_pc

The DIE has DW_AT_ranges

Finding the caller function

inlinecall(1)

Nested inline functions

nfy(1)

Features

Install

Notes

FreeBSD sound mixer improvements

Table of contents

Kernel patches

Un/muting (commit)

Playback/recording mode information (commit)

Userland

mixer(3) implementation (commit)

mixer(8) rewrite (commit)

Code and manuals

Thermometer using PIC16F877A and BME280

Components

Safe temperature range

Schematic

Heuristic for calculating the `entry` and `return` offsets

The DIE has `DW_AT_low_pc` and `DW_AT_high_pc`

The DIE has `DW_AT_ranges`