search

riscv / riscv-isa-manual

RISC-V Instruction Set Manual
https://riscv.org/
Creative Commons Attribution 4.0 International
3.48k stars 599 forks source link

Up-to-date deep link-able RISC-V spec? #989

Open sethp opened 1 year ago

sethp commented 1 year ago

First off, thank you so much for the effort you've put into the RISC-V specs! They're absolutely a joy to read, and I really appreciate including the various commentary about why various decisions were made. As a neophyte to ISA design, I find those discussions of the possible tradeoffs incredibly helpful.

I'm using a writing project as an excuse to learn more about the RISC-V ISA, and I discovered today that I've been working based on a somewhat outdated version of the specs from 2017: when I google "riscv spec" the second result is a link to https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf

a screenshot of google results showing the top two results, with the second as indicated

Also, for completeness: I've had the same experience with "riscv privileged spec" offering me a path to https://riscv.org/wp-content/uploads/2017/05/riscv-privileged-v1.10.pdf .

I've been using the 2017 one there primarily as I've discovered that the PDF viewers built into browsers (well, at least the Safari, Chrome, and Firefox that I tested) support fragment linking: e.g. https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf#section.1.1 or https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf#page=42 . That allows me to leave a specific link in the document, so I can jump straight to the relevant section for ease of reference.

So, my question: is there a stable URL that offers a more recent version of the spec with content-type: application/pdf so my browser knows to display its contents? All I can find at the moment for up-to-date specs are content-type: application/octet-stream, which my browser downloads and opens, but loses the link fragment in the process. And, a bit spicier of a question: what do you think of updating the riscv.org robots.txt to disallow crawling /wp-content/uploads/2017/05?

gfavor commented 1 year ago

Not a direct link, but this home page for the ISA manuals ( https://github.com/riscv/riscv-isa-manual) has a link, if you look down the page, that always points to the latest release of both manuals.

On Sat, Mar 11, 2023 at 12:50 PM sethp @.***> wrote:

First off, thank you so much for the effort you've put into the RISC-V specs! They're absolutely a joy to read, and I really appreciate including the various commentary about why various decisions were made. As a neophyte to ISA design, I find those discussions of the possible tradeoffs incredibly helpful.

I'm using a writing project as an excuse to learn more about the RISC-V ISA, and I discovered today that I've been working based on a somewhat outdated version of the specs from 2017: when I google "riscv spec" the second result is a link to https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf

[image: a screenshot of google results showing the top two results, with the second as indicated] https://user-images.githubusercontent.com/241129/224504091-ba322caf-84be-4380-b947-237ffae31c56.png

Also, for completeness: I've had the same experience with "riscv privileged spec" offering me a path to https://riscv.org/wp-content/uploads/2017/05/riscv-privileged-v1.10.pdf .

I've been using the 2017 one there primarily as I've discovered that the PDF viewers built into browsers (well, at least the Safari, Chrome, and Firefox that I tested) support fragment linking: e.g. https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf#section.1.1 or https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf#page=42 . That allows me to leave a specific link in the document, so I can jump straight to the relevant section for ease of reference.

So, my question: is there a stable URL that offers a more recent version of the spec with content-type: application/pdf so my browser knows to display its contents? All I can find at the moment for up-to-date specs are content-type: application/octet-stream, which my browser downloads and opens, but loses the link fragment in the process. And, a bit spicier of a question: what do you think of updating the riscv.org robots.txt to disallow crawling /wp-content/uploads/2017/05?

— Reply to this email directly, view it on GitHub https://github.com/riscv/riscv-isa-manual/issues/989, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALLX6GU4C7VGCDM7KLV3ZNTW3TQQ7ANCNFSM6AAAAAAVXV6M3I . You are receiving this because you are subscribed to this thread.Message ID: @.***>

sethp commented 1 year ago

Thanks for the suggestion! I took a look through there, and all I could find were ultimately various links to the github release assets, which (at least all the ones I tried) all are being served as content-type: application/octet-stream (i.e. as downloads, not something that "opens in browser"). Did I miss something?

sethp commented 1 year ago

I noticed that the links from riscv.org also look like they're going straight to the github release assets, too. The docs seem to suggest it ought to be possible, at some level, to control what content type an asset is served with. Unfortunately, the docs are at least wrong about the expected request format, and once I stopped getting 400 errors I still wasn't able to get it to respect the asset's application/pdf content type. I opened a support ticket to get some eyes from GitHub on what their API should be doing, and I'll let you know if that goes anywhere useful.

In the meantime, I'll probably throw a recent version up in a public backblaze bucket or something (it's not like there's a shortage of internet-connected object stores in this day and age). Then, in 2029 someone can experience the joy of asking "why have I been looking at something from early 2023 this whole time?" :upside_down_face:

gfavor commented 1 year ago

No you didn't. The linked page contains links to the latest release of each of the two ISA manuals as PDF documents.

On Sat, Mar 11, 2023 at 1:01 PM sethp @.***> wrote:

Thanks for the suggestion! I took a look through there, and all I could find were ultimately various links to the github release assets, which (at least all the ones I tried) all are being served as content-type: application/octet-stream (i.e. as downloads, not something that "opens in browser"). Did I miss something?

— Reply to this email directly, view it on GitHub https://github.com/riscv/riscv-isa-manual/issues/989#issuecomment-1465017245, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALLX6GU45FIGIZ4C65ACO2TW3TRY7ANCNFSM6AAAAAAVXV6M3I . You are receiving this because you commented.Message ID: @.***>

sethp commented 1 year ago

The docs seem to suggest it ought to be possible, at some level, to control what content type an asset is served with.

Just wanted to follow up on this: I heard back from the support folks, and they said:

Due to the way Release assets are stored, users won't get back the original content type when retrieving the asset.

So it seems the content-type there is just a metadata field, not something that can be used to mark e.g. a PDF as a PDF instead of a generic byte stream.

I've gone ahead and uploaded the current latest "ratified" specs to a bucket that does serve them with the more specific content type, they're available here:

I'd still encourage y'all to update the robots.txt to disallow crawling the /wp-content/ path and consider an alternative hosting arrangement, at least for the ratified versions. I keep finding myself accidentally landing on the spec from six years ago via google searches, and it seems a shame that I'm missing out on the benefits of y'all's excellent efforts during that time.