riscv-asm-vim

KO | EN

gitlite — search

#hacktoberfest #ruby #php #python #shell #wordpress #dotfiles #cli #android #javascript #erlang #vim

★ 16 Open GitHub ↗

Advanced RISC-V assembly syntax highlight for Vim and Neovim.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Advanced RISC-V Assembly Highlight for Vim and Neovim

## Overview

This Vim plugin is designed to enhance your RISC-V assembly coding experience. It achieves this by offering comprehensive syntax highlighting and providing support for both standard and custom RISC-V extensions, including instructions and registers. Additionally, the plugin is configurable by using RISC-V ISA extension naming conventions, recognizes GNU Assembly (GAS) directives, and incorporates smart indent functionality.

## Features
1. Syntax Highlighting:

- Full coverage of standard RISC-V instructions and registers for improved code readability.
    - Clear and intuitive color coding to distinguish different elements in your RISC-V assembly code.

2. Customization:

- Add custom RISC-V extensions consist of instructions and CSRs to tailor the plugin to your specific needs.
    - Follows RISC-V ISA Extension Naming Conventions to enable certain extensions, ensuring compatibility and standardization.

3. GAS Directives:

- Recognizes and highlights GNU Assembly (GAS) directives for a seamless coding experience with popular RISC-V assemblers.

4. Smart Indent:

- Provides smart indent functionality for improved code structure and alignment.

## Installation

### [VimPlug](https://github.com/junegunn/vim-plug)

1. Add the following text to the vim-plug section in your `.vimrc`:

```VimL
Plug 'henry-hsieh/riscv-asm-vim'
```

2. Reload `.vimrc` and run `:PlugInstall` in Vim.

### [Vundle](https://github.com/VundleVim/Vundle.vim)

1. Add the following text to the vundle section in your `.vimrc`:

```VimL
Plugin 'henry-hsieh/riscv-asm-vim'
```

2. There are two methods to install the plugin.

* Reload `.vimrc` and run `:PlugInstall` in Vim.

* Use command line:

```Shell
vim +PluginInstall +qall
```

### [Pathogen](https://github.com/tpope/vim-pathogen)

1. Use command line:

```Shell
cd ~/.vim/bundle
git clone https://github.com/henry-hsieh/riscv-asm-vim
```

### [Packer.nvim](https://github.com/wbthomason/packer.nvim)

1. Add the following to your packer startup function:

```lua
use {
  "henry-hsieh/riscv-asm-vim",
}
```

2. Install the plugin:

* Reload `init.lua` and run `:PackerSync` in Neovim.

### [lazy.nvim](https://github.com/folke/lazy.nvim)

1. Add the following to your lazy.nvim startup function:

```lua
{
  "henry-hsieh/riscv-asm-vim",
  ft = { "riscv_asm" },
}
```

2. Install the plugin:

* Reload `init.lua` and run `:Lazy install` in Neovim.
    * Or if you are using **install missing plugins**, just restart Neovim.

## Usage

1. Any file with a `.S` extension will be loaded as RISC-V assembly syntax.
   Note that this will override default asm syntax.

2. Set filetype in Vim.

```VimL
set ft=riscv_asm
```

3. Add modeline in your files.

```c
// vim: ft=riscv_asm
```

## Options

To set the option of this plugin, you can use either Vimscript or Lua (Neovim only). Put the options in your Vim/Neovim startup file.

### Highlight All Supported RISC-V ISA

**Vimscript:**
```VimL
let g:riscv_asm_all_enable = 1
```

**Neovim Lua:**
```lua
vim.g.riscv_asm_all_enable = true
```
If the option is defined (set to any value), the plugin will ignore the value of `g:riscv_asm_isa` and highlight all instructions and registers supported by the plugin. If an invalid sequence in `g:riscv_asm_isa` is detected, the plugin will automatically highlight all instructions and registers, too.

### Specify the Extensions You Want to Highlight

**Vimscript:**
```VimL
let g:riscv_asm_isa = 'RV64GC'
```

**Neovim Lua:**
```lua
vim.g.riscv_asm_isa = 'RV64GC'
```

The value of `g:riscv_asm_isa` aligns with RISC-V ISA extension naming conventions, allowing Vim to highlight specified RISC-V ISAs and extensions. By default, the plugin activates only the RV64GC extension, resulting in the highlighting of RV64I, M, A, F, D, C, Zicsr, and Zifencei instructions and registers.

While the version numbers of extensions can be parsed, the plugin currently does not utilize them. Here are examples of combinations of ISA extensions and version numbers:

- `rv32i2` (RV32I v2.0)
- `rv32i2p2` (RV32I v2.2)
- `rv32i2_p2` (RV32I v2.0, P v2.0)
- `rv32i2p2p1` (RV32I v2.2, P v1.0)
- `rv32i2p2_p1p2` (RV32I v2.2, P v1.2)

It's important to note that the ISA name is case insensitive, and underscores may provide hints to the parser but are not required in all situations.

#### Currently Supported Extensions

* Base Integer ISAs or Profiles

* Unprivileged Extensions

| Extension              | Full Name                                                                                   | Supported Version |
|:---------------------- |:------------------------------------------------------------------------------------------- |:----------------- |
| `M`                    | Integer Multiplication and Division                                                         | 2.0               |
| `A`                    | Atomics                                                                                     | 2.1               |
| `F`                    | Single-Precision Floating-Point                                                             | 2.2               |
| `D`                    | Double-Precision Floating-Point                                                             | 2.2               |
| `G`                    | General                                                                                     |                   |
| `Q`                    | Quad-Precision Floating-Point                                                               | 2.2               |
| `C`                    | 16-bit Compressed Instructions                                                              | 2.0               |
| `B`                    | Bit Manipulation                                                                            | 1.0               |
| `V`                    | Vector Instructions                                                                         | 1.1               |

* Privileged Extensions

* Additional Unprivileged Extensions

* Additional Privileged Extensions

#### Conflict Extensions

#### Rules Should Be Followed

1. Ensure that you specify extensions in the sequence listed in [Currently Supported Extensions](#currently-supported-extensions). Always choose one of the base integer ISAs or profiles, and place the base ISA name at the beginning of the option. An exception is the general-purpose extension `G`, which can replace the RV32I and RV64I base ISAs. Do not specify more than one base ISA and profile, as this will result in a parser error. Extensions should be added in the following order: unprivileged, privileged, additional unprivileged, and additional privileged. Extensions within the same category should adhere to the order in the corresponding table.

2. If the supported version of an extension is unspecified in the table, *DO NOT* including the version in the sequence.

3. Insert an underscore between two consecutive multi-letter extensions, i.e. additional extensions, for clarity.

4. Some extensions and privileged extensions cannot coexist; refer to [Conflict Extensions](#conflict-extensions). Avoid including conflicting extensions in the option.

Following table contains some examples of valid and invalid ISA extension combinations:

### Add Custom Extensions with Instructions and CSRs

**Vimscript:**
```VimL
let g:riscv_asm_custom_isa = [{'name': 'Xcustom'}]
```

**Neovim Lua:**
```lua
vim.g.riscv_asm_custom_isa = {{name = 'Xcustom'}}
```

The custom ISA extensions are construct by a list of dictionaries, each representing a custom ISA extension. Each custom extension has following configuration options:

- `name`: _String_, **mandatory**. The custom extension name which starts with the letter 'X'.
- `ver`: _Float/Number_, **optional**. The version of the custom extension.
- `inst`: _List of Strings_, **optional**. Common instructions for all `XLEN`.
- `csr`: _List of Strings_, **optional**. Common CSRs for all `XLEN`.
- `inst32`: _List of Strings_, **optional**. Instructions for `XLEN=32`.
- `csr32`: _List of Strings_, **optional**. CSRs for `XLEN=32`.
- `inst64`: _List of Strings_, **optional**. Instructions for `XLEN=64`.
- `csr64`: _List of Strings_, **optional**. CSRs for `XLEN=64`.
- `inst128`: _List of Strings_, **optional**. Instructions for `XLEN=128`.
- `csr128`: _List of Strings_, **optional**. CSRs for `XLEN=128`.

#### Highlight the Custom Extensions

Like the standard extensions, you can use `g:riscv_asm_isa` to control enablement of the custom extensions, or use `g:riscv_asm_all_enable` to highlight all of the standard extensions and the custom extensions. The syntax in `g:riscv_asm_isa` should comply with the RISC-V ISA extension naming conventions:

1. The string is case insensitive.

2. The name of a custom extension should start with the letter 'X' followed by an alphabetical name and an optional version number.

3. The custom extensions must be listed after all standard extensions.

4. Like other multi-letter extensions, must be separated from other multi-letter extensions by an underscore.

5. If multiple custom extensions are listed, they should be ordered alphabetically.

If you did not specify the `ver` of a custom extension defined in `g:riscv_asm_custom_isa`, you should not list the custom extension with any version number. Following table listed some valid or invalid sequence with the two custom extensions in the [examples](#examples-of-adding-the-custom-extensions).

#### Examples of Adding the Custom Extensions

Vim example for adding two custom extensions, `Xangle` and `Xbargle`:

```VimL
let g:riscv_asm_custom_isa =
\ [
\     {
\         'name': 'Xargle',
\         'ver': 1.0,
\         'inst': ['inst_1', 'inst_2'],
\         'csr': ['csr_1', 'csr_2'],
\         'inst32': ['inst32_1', 'inst32_2'],
\         'csr32': ['csr32_1', 'csr32_2'],
\         'inst64': ['inst64_1', 'inst64_2'],
\         'csr64': ['csr64_1', 'csr64_2'],
\     },
\     {
\         'name': 'Xbargle',
\     },
\ ]
```
Equivalent example of Neovim Lua:

```lua
vim.g.riscv_asm_custom_isa = {
    {
        name = 'Xargle',
        ver = 1.0,
        inst = {'inst_1', 'inst_2'},
        csr = {'csr_1', 'csr_2'},
        inst32 = {'inst32_1', 'inst32_2'},
        csr32 = {'csr32_1', 'csr32_2'},
        inst64 = {'inst64_1', 'inst64_2'},
        csr64 = {'csr64_1', 'csr64_2'},
    },
    {
        name = 'Xbargle',
    },
}
```

### Display Debug Information

**Vimscript:**
```VimL
let g:riscv_asm_debug = 1
```

**Neovim Lua:**
```lua
vim.g.riscv_asm_debug = true
```

If the option is defined (set to any value), the plugin will display more information while it's parsing the value of `g:riscv_asm_isa` or the custom extensions.

## Other VIM plugins

### Tagbar
[Tagbar](https://github.com/preservim/tagbar) is a Vim plugin that provides an easy way to browse the tags of the current file and get an overview of its structure. Follow steps in [Tagbar Wiki](https://github.com/preservim/tagbar/wiki#risc-v-asm) to apply it.

## Contributing

Contributions are welcome! If you encounter issues or have suggestions for improvements, please open an issue or submit a pull request on the [riscv-asm-vim](https://github.com/henry-hsieh/riscv-asm-vim).

## License

This plugin is licensed under the [MIT License](LICENSE.md).

riscv-asm-vim

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README