=========================================== Auto-generated documentation of the ULM ISA [TOC] =========================================== If you have have a full tex-live installation a documentation can be generated from your `isa.txt` description. With additional comments the documentation can be further enhanced. Here some auto-generated __Documentation of the ULM Instruction Set__. ---- SHELL (path=session10/doc/, hide) ----------------------------------------- make refman mkdir -p /home/www/htdocs/numerik/hpc/ss22/hpc0/session10/io/ cp 1_ulm_build/io/refman.pdf /home/www/htdocs/numerik/hpc/ss22/hpc0/session10/io/ -------------------------------------------------------------------------------- :links: Documentation of the ULM Instruction Set -> https://www.mathematik.uni-ulm.de/numerik/hpc/ss22/hpc0/session10/io/refman.pdf Installing Tex-Live =================== ULM generator will create TeX files for the reference manual. You therefor need need a TeX installation. We tested TeX installations on the following platforms: - On WSL with `sudo apt-get install texlive-full`. - On MacOS download and install __MaxTeX__. :links: MaxTeX -> https://www.tug.org/mactex/ How to Generate the Documentation ================================= In the `ulm-generator` directory run `make refman`. Additional Comments for the Instruction Set =========================================== Additional comments in `isa.txt` can enhance the documentation but can enhance it. The above linked documentation was generated from this ISA specification: :import: session10/doc/0_ulm_variants/io/isa.txt [fold] If a mnemonic is used for more than one instruction (e.g. `addq`) it is helpful to provide information what the mnemonic means in general. For example `addq` in general adds integers: ---- CODE (type=txt) ----------------------------------------------------------- @addq # Integer addition # # And Maybe you want to write even more about this mnemonic. -------------------------------------------------------------------------------- You see that with `@addq` the attached comment block is used as such a general description. For each instruction you can provide after the opcode line a more specific description. For example, in this `addq` instruction the first operand is an immediate value ---- CODE (type=txt) ----------------------------------------------------------- 0x0A RRR # Adds an immediate value X to register %Y. Stores result in register %Z. : addq X, %Y, %Z ulm_add64(X, ulm_regVal(Y), Z); -------------------------------------------------------------------------------- Whereas in this `addq` instruction the first operand is a register. So let's point that out: ---- CODE (type=txt) ----------------------------------------------------------- 0x0E RRR # Adds register %X to register %Y. Stores result in register %Z. : addq %X, %Y, %Z ulm_add64(ulm_regVal(X), ulm_regVal(Y), Z); -------------------------------------------------------------------------------- For Comparison: Other ISA Documentations ======================================== Below you see some documentations for architecture of practical relevance. For each of them the complete manual is linked but also a small extract describing just one instruction. You will note that the ULM documentation reflects in simplified form what you actually can find out in the field. Like in the ULM documentation the format of the instruction (including the opcode), the assembly notation and the effect is described. - __Arm instruction for integer addition__ (Full: __Arm Architecture__) Pretty much every smartphone uses a processor that implements an Arm instruction set architecture. The __ARM__ architecture received big public attention when Apple announced to switch from Intel processors to their own processors (__M1__ and successors). Apple's processors implement the ARM architecture. - __RISC-V instruction for integer addition__ (Full: __RISC-V__) Open source standard. Recently it gained lots of momentum. Personal opinion and pure speculation: Might some day challenge ARM for being the dominant RISC architecture. - __MIPS instruction for integer addition__ (Full: __MIPS__) __MIPS is a legendary architecture__. Often used in computer science classes to teach computer architecture because of its clean design. Development began in the 80s by MIPS Computer Systems. They announced in 2021 their transition to RISC-V. - __Intel 64 instruction for integer addition__ (Full: __Intel 64 Architecture__) Because this is a CISC (Complex Instruction Set Architecture) it is no surprise to have more than just one or two instructions for adding integers. :links: ARM -> https://en.wikipedia.org/wiki/ARM_architecture_family M1 -> https://en.wikipedia.org/wiki/Apple_M1 Intel 64 Architecture -> https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-vol-2a-manual.pdf Intel 64 instruction for integer addition -> https://www.felixcloutier.com/x86/add RISC-V -> https://www.mathematik.uni-ulm.de/numerik/hpc/ss22/hpc0/slides/riscv-spec-20191213.pdf RISC-V instruction for integer addition -> https://www.mathematik.uni-ulm.de/numerik/hpc/ss22/hpc0/slides/add_RISC_V.pdf Arm Architecture -> https://www.mathematik.uni-ulm.de/numerik/hpc/ss22/hpc0/slides/DDI0487E_a_armv8_arm.pdf Arm instruction for integer addition -> https://www.mathematik.uni-ulm.de/numerik/hpc/ss22/hpc0/slides/add_Armv8.pdf MIPS instruction for integer addition -> https://www.mathematik.uni-ulm.de/numerik/hpc/ss22/hpc0/slides/add_MIPS.pdf MIPS -> https://s3-eu-west-1.amazonaws.com/downloads-mips/documents/MD00086-2B-MIPS32BIS-AFP-6.06.pdf MIPS is a legendary architecture -> https://en.wikipedia.org/wiki/MIPS_architecture