1# MLIR : Language Server Protocol
2
3[TOC]
4
5This document describes the tools and utilities related to supporting
6[LSP](https://microsoft.github.io/language-server-protocol/) IDE language
7extensions for the MLIR textual assembly format. An LSP language extension is
8generally comprised of two components; a language client and a language server.
9A language client is a piece of code that interacts with the IDE that you are
10using, such as VSCode. A language server acts as the backend for queries that
11the client may want to perform, such as "Find Definition", "Find References",
12etc.
13
14## MLIR LSP Language Server : `mlir-lsp-server`
15
16MLIR provides an implementation of an LSP language server in the form of the
17`mlir-lsp-server` tool. This tool interacts with the MLIR C++ API to support
18rich language queries, such as "Find Definition".
19
20### Supporting custom dialects and passes
21
22`mlir-lsp-server`, like many other MLIR based tools, relies on having the
23appropriate dialects registered to be able to parse in the custom assembly
24formats used in the textual .mlir files. The `mlir-lsp-server` found within the
25main MLIR repository provides support for all of the upstream MLIR dialects and
26passes. Downstream and out-of-tree users will need to provide a custom
27`mlir-lsp-server` executable that registers the entities that they are
28interested in. The implementation of `mlir-lsp-server` is provided as a library,
29making it easy for downstream users to register their dialect/passes and simply
30call into the main implementation. A simple example is shown below:
31
32```c++
33#include "mlir/Tools/mlir-lsp-server/MlirLspServerMain.h"
34
35int main(int argc, char **argv) {
36  mlir::DialectRegistry registry;
37  registerMyDialects(registry);
38  registerMyPasses();
39  return failed(mlir::MlirLspServerMain(argc, argv, registry));
40}
41```
42
43### Design
44
45The design of `mlir-lsp-server` is largely comprised of three different
46components:
47
48*   Communication and Transport (via JSON-RPC)
49*   Language Server Protocol
50*   MLIR Language Server
51
52![Index Map Example](/includes/img/mlir-lsp-server-server_diagram.svg)
53
54#### Communication and Transport
55
56`mlir-lsp-server` communicates with the language client via JSON-RPC over
57stdin/stdout. In the code, this is the `JSONTransport` class. This class knows
58nothing about the Language Server Protocol, it only knows that JSON-RPC messages
59are coming in and JSON-RPC messages are going out. The handling of incoming and
60outgoing LSP messages is left to the `MessageHandler` class. This class routes
61incoming messages to handlers in the `Language Server Protocol` layer for
62interpretation, and packages outgoing messages for transport. This class also
63has limited knowledge of the LSP, and only has information about the three main
64classes of messages: notifications, calls, and replies.
65
66#### Language Server Protocol
67
68`LSPServer` handles the interpretation of the finer LSP details. This class
69registers handlers for LSP messages and then forwards to the `MLIR Language
70Server` for processing. The intent of this component is to hold all of the
71necessary glue when communicating from the MLIR world to the LSP world. In most
72cases, the LSP message handlers simply forward to the `MLIR Language Server`. In
73some cases however, the impedance mismatch between the two requires more
74complicated glue code.
75
76#### MLIR Language Server
77
78`MLIRServer` provides the internal MLIR-based implementation of all of LSP
79queries. This is the class that directly interacts with the MLIR C++ API,
80including parsing .mlir text files, running passes, etc.
81
82## Editor Plugins
83
84LSP Language plugins are available for many popular editors, and in principle
85`mlir-lsp-server` should work with any of them, though feature set and interface
86may vary. Below are a set of plugins that are known to work:
87
88### Visual Studio Code
89
90Provides MLIR language IDE features for VS code.
91
92#### Setup
93
94This extension requires the `mlir-lsp-server` language server. If not found in
95your path, you must specify the path of the server in the settings of this
96extension.
97
98#### Developing in the LLVM monorepo
99
100This extension is actively developed within the LLVM monorepo, at
101`mlir/utils/vscode`. When developing or deploying this extension within the LLVM
102monorepo, a few extra steps for setup are required:
103
104*   Copy `mlir/utils/textmate/mlir.json` to the extension directory and rename
105    to `grammar.json`.
106
107#### Features
108
109*   Syntax highlighting for .mlir files and `mlir` markdown blocks
110*   go-to-definition and cross references
111    *   Definitions include the source file locations of operations in the .mlir
112