WTD: Assembly Language & ABI Programmers Guide

Archive RISC-V
1

The only instruction reference I find is “The RISC-V Instruction Set ManualVolume I: User-Level ISAVersion 2.1” here: https://riscv.org/specifications/ . I hear rumours of a reference card (ala System 360 green instruction card) but can’t find it.

Sam Falvo has something he’s started for his implementation of a RISC-V but it’s still not what I’d call a programmer’s reference: https://github.com/KestrelComputer/polaris/blob/master/processor/docs/instruction-set.md

Does no such thing exist? Are people only really coding in C/C++? I’m quite interested in familiarizing myself with RISC-V assembly programming so would appreciate any pointers for programmer user guides & references.

thanx,

– Ben Scherrey

2

Is this what you had in mind?

1 Like
3

Yes! Thanx! Now for a programmer’s guide… :slight_smile:

1 Like
4

Beware, it has typos. At least the JALR is marked UJ-type, but should be an I-type.

1 Like
5

Does anybody know when this (or a pre-release version) will be available.
In the ISA specification it simply says the following :-

Chapter 21

RISC-V Assembly Programmer's Handbook

This chapter is a placeholder for an assembly programmer's
  manual.

Hmm, how would I find out the schedule for this documents availability
Thx
Lee

1 Like
6

I would like to find something that completely focuses only on programming in risc-v assembly, not using c or anything else, just assembly. so far I cannot find anything. anyone have a direction to point me in? I am not trying to do this professionally, I just want to learn how to program in assembly using the hifive1 that I recently bought. I’ve been running around the internet for the past couple of weeks now trying to figure out what I am doing incorrectly that I cannot find something - anything! - aimed only at assembly. really disheartening so far :confused:

7

Did you look at the RISC-V Reader by Patterson and Waterman?

8

There is
https://github.com/riscv/riscv-asm-manual/blob/master/riscv-asm.md
but it is incomplete and a little out-of-date, and isn’t a tutorial on how to learn assembly language programming.

Palmer Dabbelt has a blog that talks about toolchain and linux kernel issues. Some of the blog posts explain how the toolchain works, with assembly language examples, and you can probably learn some useful info from that.
https://www.sifive.com/blog/2017/08/07/all-aboard-part-0-introduction/

You may also want to look at the processor specific Application Binary Interface (psABI).
https://github.com/riscv/riscv-elf-psabi-doc/blob/master/riscv-elf.md

Otherwise, I would suggest compiling small examples to assembly code and looking at the result.

The RISC-V Reader that Krste already mentioned is also a good reference.

9

@jimw yeah, but none of those things are anything like, say, the early 80s books by Rodnay Zaks or Lance Leventhal along the lines of “Learn to program in assembly language using the 8080/Z80/6800/6502/6809/8086/68000”.

Those books took you right from “What is binary? What is RAM? What is a register?” up to programming complete applications and advanced data structures.

We could really do with a modern version, and RISC-V is ideal for the purpose.

10

@Krste I bought both that book and the risc-v edition of the hardware/software textbook by patterson. chapter 3 has the reference stuff, but that book is aimed at people that already know assembly which is definitely not me. the textbook has been really good so far for learning the assembly, but nothing on actually just writing and compiling only assembly. both books keep contrasting to c and arm/x86 assembly snippets. neither book is like what @brucehoult is talking about, which is exactly what I am looking for. I haven’t done any significant programming at all which is why I became so interested in risc-v in the first place. thoughts?

11

You might like to take a look at the slides from our Berkeley introductory computer systems class: http://inst.eecs.berkeley.edu/~cs61c/fa17/
This is designed as a first class for those new to assembly code and machine structures.

1 Like
12

@Krste thank you. I’ll take a look at them

13

For what it’s worth I am trying to put one together here:

14

Great start! I’ve thought about writing such a book for many years, but never found time.

What you have now feels like a (one stop) reference for people who already know how to program, albeit they haven’t looked at how things work at a low level. Which is good – plenty of those these days with Python, PHP etc experience.

It would be nice to have something suitable for people with no programming experience at all to use to start with assembly language.

Maybe that’s too ambitious, but I feel it’s possible to make it quite approachable and meaningful by assuming nothing more than working stdin&stdout (whether by C library or read/write system calls, or magic memory locations like Spike) and building small programs designed to fit into a Unix shell pipeline and/or called as CGIs (parsing the env manually :slight_smile: ). CGIs are especially great because you can easily get pretty web pages (or parts of them) and everyone can relate to that.

I’d be tempted to put a little bit of history and answers to such questions as “Why binary?”, “Why 32 or 64 bits?”.

Also pointing out that for most purposes the contents of memory and registers are NOT in fact binary numbers, but merely a collection of bits. Interpretation is arbitrary. Some instructions (and operations e.g. sequential instruction fetch) happen to treat them as if they were binary integers coded in a particular way, and others as floating point encoded in another particular way, but there is nothing essential about that.

I’d probably leave a discussion of floating point until much much later. Inexactness and error propagation and so forth are pretty advance topics, and not related at all to assembly language as such.

Anyway, it’s easy for me to take 10 minutes to type a couple of paragraphs here, but you’ve clearly put many many hours into actually writing a book – fantastic!!!

15

Hey Bruce, Thanks for the encouragement.

I’m not following the CGI idea. But the rest is in the direction I’m thinking of going.

The float was an appendix. I moved it up to see how it would work. It might work in a chapter/section on the F and D extensions. If I’m lucky I’ll find an editor that can help improve the fluidity once it nears some critical mass (you know any?)

Yeah the not a number thing is a big deal too. I usually lecture on that by using the word ‘context’ and asking students to tell me what a vertical bar and a circle that I write on the chalkboard represents. I usually get ten, two, negative 2, 0x31 0x32, but never 0x49 0x4f,… I always end it by pointing out that I was talking about the moon Io to drive home the need to always understand the context that within which things are interpreted!

A bottom-of-the line machine with a user-interface like the old CP/M ddt app with a simulated UART and some I/O bits is the sort of thing I would like to use to let the reader experiment with to get a VERY hands-on understanding of the instructions and observing the CPU state (which in this case is wonderfully simple.) spike might work, but the little I know of it so far suggests that it is being way too helpful with things like its byte-flipping when printing memory contents and I have not found anything on how to run stand-alone code in it. A newbie is likely to get very confused with helpful layers (I know I would!) And gdb… that is a universe in itself.

I suppose I could just write a RV32IM simulator that works like ddt. Barest of bare bones. No magic behind the scenes. I’d even skip the interactive assembler in lieu of using gas+objcopy to generate raw binary files that could be loaded. Maybe take it as far as gcc to drive home the linker and function calling conventions.

Boy this takes me back: http://www.gaby.de/cpm/manuals/archive/cpm22htm/ch4.htm

I’m thinking these commands: d, f, g, m, r, s, t, x… and I suppose l (ell) would be useful as well.

You know of a sim that runs at this level? Or do I kill a weekend creating one? …at least it will be fun!

1 Like
16

Hi John, I really like what you’ve created.

You might also like to check out my blog on an open Arty RISC-V computer I’m developing called the ‘ArtyRV board’ (see http://lavaworkshop.tumblr.com).

The project includes an interactive RISC-V disassembler, which is built right in to the ‘RVStudio’ IDE. Currently the disassembler loads in and disassembles RV32I binary and coe files, but will soon handle Intel hex (and probably elf) files as well.

I’m planning to implement some console commands for dumping memory contents to the terminal (as ASCII and hex), dumping disassembled code to the terminal, uploading intel hex files, jump to address, etc (these will be wrapped into the IDE as well). So you basically have real hardware (implemented in the Arty FPGA) and tools to help explore that hardware. I myself prefer real hardware (I’m an electronics design engineer, as well as a software developer).

In addition to ASM and C, I’m toying with integrating a tiny BASIC and extending it with real-time features (a 1 second ticker with independent ‘tasks’), so users can write simple home automation programs, for example.

I’m making the RVStudio IDE (it’s fully custom) so it’s super simple. In other words, all complexity is striped out, so users can learn about RISC-V, ASM and C coding, VHDL, etc. in essence. I found SiFive’s work really good, but they are deeply technical, which can be a bit daunting for new users. I want to recapture that spirit of excitement, exploration, and can-do that the computers in the '80s elicited, and inspire a new generation of creatives.

If you have any suggestions or comments (eg. maybe we can integrate your info with my project ie. interactive help), please feel free to email (service@lavasoftware.com) or message me.

btw, blog sections include:

  • Summary
  • Introduction
  • Finding a RISC-V core for the Arty
  • Getting the RISC-V core running
  • Designing a VGA video controller
  • The beauty of bare metal RISC-V
  • An interactive RISC-V disassembler
  • Programming the ArtyRV board in C
  • RVStudio gets a powerful IDE
  • Where do we go from here?
1 Like
17

OOhhhh!!! This is cool!

I could see the as-yet unwritten per-instruction details pages to be very useful. How might they be presented in your IDE? Embedded using some markup of some sort? Or are you thinking links to web pages?

-John