[General]: Notes on urdmsr instruction
- Dominant language
- HTML
- Stars
- 29
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
### Feedback or Inquiry
First, and emphatically, I'm delighted this project exists and am looking forward to the official release.
I've recently spent some time implementing a kernel module to support urdmsr; what follows is impressions from the new documentation format of that instruction [here](https://intel.github.io/SDM/sdm.html?instr=URDMSR).
- I don't recall seeing the Intrinsics listed in the current SDM. Their inclusion here is most welcome. Having intrinsic version information here would be even more helpful, particularly for new instructions like this one.
- I love the categories at the top of the page, and also love that it's a link to the category description and catalog. Hoping that features makes it into the MSR documentation.
- The doubling up of columns in the first table (e.g., Opcode/Instruction) is an unfortunate holdover from the limitations of the dead-tree version. I think screens are wide enough now that the doubling up can be eliminated.
- The parameter subscripting solves a problem that's been so endemic I didn't realize until now how annoying it was. The existing SDM forced me to puzzle out which parameter was input and which was output. The subscripting solves that. Wonderful! I'm a little concerned about how that interacts with cutting and pasting. `r64_1` or `r64_a` (underscores, not subscripts) have their own problems. I'll take the win for now.
- Making "Results" and "Inputs" explicit: also wonderful.
- The `CPUID` column highlights the information I'm most likely to be looking for, but as an occasional user I'm still going to need to trek over to the cpuid instruction documentation to find out what `USER_MSR` means. Perhaps make `USER_MSR` a link (much like the "misc" category)? An even more convenient answer for occasional users would be provided the cpuid intrinsic code that tests for `USER_MSR`, but I can see where that might be annoying to more experienced users. Definitely keep the cpuid category in the first table, though.
- I would personally like the "V" and "N.E." and "ModRM:r/m" to be links as well, but I can see an argument where that's getting too busy.
- There are two sections labelled "Operation (URDMSR, Standard variant)", which I assume refer to the version that stores the MSR value in memory and the version that stores the MSR value in another register. I'd need to dig into the code to figure out which is the case. Could the section title reproduce the instruction parameters?
- Appreciating the tool tips in the operation sections, and the fact that the variables and calls are linked underneath, and that fact that the the pages for the calls list what else uses those calls. It's annoying that "MSRBITMAPADDR" doesn't occur in the volume 4 MSR documentation, but I can see why you're not trying to solve every problem at once.
- I'd welcome link to the exception definitions.
Overall, much easier to read, much greater levels of discoverability. Great work!
Contributor guide
Research direction
Start with the URDMSR documentation page linked in the issue and review each of the listed presentation, linking, and labeling suggestions. No file or test is named, so the first task is to determine which proposals are in scope and locate the corresponding documentation-generation or website entry points. Done means the selected improvements are implemented with clear section labels and links, and the page remains understandable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- html
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100