oxidecomputer / oxidecomputer/usdt

documentation of `asm` contents?

Open
#65 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
145
Forks
15
Avg merge
14m
Merged PRs (30d)
6

Description

hi! related to #64, i couldn't tell what the intent of a few asm blocks were to figure out if there might be other ways of getting the same results.. i think that everything i'm seeing might just be assembler directives for some specific target, but here goes:

in no-linker.rs there's a clr rax but clr is not an x86 instruction. is this expected to be assembled by an assembler that translates clr to "clear", either by xor rax, rax or mov rax, 0?

is_enabled_rec and probe_rec are a series of assembler directives and not specific instructions themselves. i think the consequence here is that is_enabled will always be 0 (due to clr rax) and the probe_rec section would never execute. if it were to execute, i think there would be no instructions there but the nop, with the directives just setting up bytes describing a probe record elsewhere in the binary?

in linker.rs, there's a .reference directive but that's not a directive i can recall seeing anywhere. is there a specific assembler that does recognize this directive, where a reader (me, hi) could go to learn more about what this should cause the assembler to emit?

since call_instruction in linker.rs references aarch64, i think this also implies that the no-linker paths could reasonably be tried on aarch64 which would then (no clr, but also no rax 😁)

most of these questions are the result of trying to understand why an explicit call/bl are necessary here - since we can an expected set of arguments for a probe, i'd expect to be able to transmute to an appropriate-arity extern "C" function that is then called rust-style. that leaves the calling convention and specific instruction in the hands of the compiler, and would let you delete the isa-specific bits i think!

and finally, i see a lot of preserves_flags in asm blocks. i would strongly recommend some // Safety: -style comments about why those options are correct - if clr rax above is interpreted as xor rax, rax, for example, the option is just incorrect and could result in bad flag-clobbering. i think the same is possible in the calling-a-probe case, since no calling conventions i know of ensure that status registers are preserved.. the likelihood of this being a real problem, though, seems low: i haven't often seen llvm keep a boolean in a flags register especially across an interesting number of operations.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the inline assembly in usdt-impl/src/no-linker.rs, record.rs, and linker.rs, especially the linked ranges for clr, probe records, .reference, call_instruction, and preserves_flags. Document the assembler and architecture assumptions, and clarify the safety rationale for the assembly options; the issue does not name a test or a specific documentation destination.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.