gocc

README

GOCC: Compile C to Go Assembly

This utility transpiles C code to Go assembly. It uses the LLVM toolchain to compile C code to assembly and machine code and generates Go assembly from it, as well as the corresponding Go stubs. This is useful for certain features such as using intrinsics, which are not supported by the Go ecosystem. The example folder includes matrix multiplication using intrinsics compiled to ARM Linux, x86_x64 and Apple Silicon.

Features

• Remote compilation using a docker container with all toolchains (including Apple Silicon) pre-installed.
• Only requires clang and objdump to be installed in order to compile.
• Auto-detects the appropriate version of clang and objdump to use.
• Supports cross-compilation.
• Auto-generates Go stubs for the C functions by parsing C code.
• Automatically formats go assembly using asmfmt.

Using Remotely (default)

The easiest way to use this tool is to use it remotely. This will use a docker container with all the toolchains pre-installed. This is the default mode of operation and requires no additional setup. The only requirement is to have go installed on your machine.

First, we need to install gocc command-line tool. This will install the gocc command in your $GOPATH/bin folder, or $GOBIN. Make sure to add it to your $PATH variable as well.

go install github.com/kelindar/gocc/cmd/gocc@latest

Next, you can use it to compile your C code to Go assembly. For example, to compile the matmul_avx.c file, you can run the following command:

gocc matmul_avx.c --arch avx2

Setting up locally

Before you use it, you need to install the LLVM toolchain. On Ubuntu, you can do it with the following commands:

sudo apt install build-essential
bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

For cross-compilation you will also need to install the appropriate toolchain. For example, for ARM Linux:

sudo apt install -qy binutils-aarch64-linux-gnu gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

Limitations

This tool does not support most of the C features, it's not a replacement for C/Go. If you are using this for production code, make sure to test the generated code thoroughly. Also, this is not meant to be general-purpose tool, but rather a tool for solving my own problems of speeding up certain routines.

• Only supports C code that can be compiled by clang.
• Does not support C++ code or templates for now.
• Does not support call statements, thus require you to inline your C functions
• Currently limited to 4 arguments per function and must be 64-bit.

Resources

The ideas of this are built on top of others who have done similar things, such as

• c2goasm and asm2plan9s by Minio
• gorse/goat by Gorse
• A Primer on Go Assembly
• Go Function in Assembly
• Stack frame layout on x86-64
• Compiler Explorer (interactive)

Documentation

Overview

Copyright 2022 gorse Project Authors Copyright 2023 Roman Atachiants

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type File
• type Local
  • func NewLocal(arch *config.Arch, source, outputDir, packageName string, options ...string) (*Local, error)
  • func (t *Local) Close() error
  • func (t *Local) Output() (*WebResult, error)
  • func (t *Local) Translate() error
• type Remote
  • func NewRemote(target string, source, outputDir, packageName string, options ...string) (*Remote, error)
  • func (t *Remote) Translate() error
• type WebRequest
• type WebResult

Types

type File

type File struct {
	Name string `json:"name" uri:"name" binding:"required"`
	Body []byte `json:"body"`
}

File represents a file

type Local

type Local struct {
	Arch       *config.Arch
	Clang      *cc.Compiler
	ObjDump    *cc.Disassembler
	Source     string
	Assembly   string
	Object     string
	GoAssembly string
	Go         string
	Package    string
	Options    []string
}

Local translates a C file to Go assembly

func NewLocal

func NewLocal(arch *config.Arch, source, outputDir, packageName string, options ...string) (*Local, error)

NewLocal creates a new translator that uses locally installed toolchain

func (*Local) Close

func (t *Local) Close() error

Cleanup cleans up the temporary files

func (*Local) Output

func (t *Local) Output() (*WebResult, error)

Output returns the output files as a web result

func (*Local) Translate

func (t *Local) Translate() error

Translate translates the source file to Go assembly

type Remote

type Remote struct {
	Target  string
	Source  string
	Package string
	Output  string
	Options []string
	Client  *req.Client
}

Remote represents a remote translator

func NewRemote

func NewRemote(target string, source, outputDir, packageName string, options ...string) (*Remote, error)

NewRemote creates a new translator that uses remote server

func (*Remote) Translate

func (t *Remote) Translate() error

Translate translates the source file to Go assembly

type WebRequest

type WebRequest struct {
	File
	Arch    string   `uri:"arch" binding:"required"`
	Package string   `uri:"package" form:"package"`
	Options []string `uri:"options" form:"options"`
}

WebRequest represents a request to the remote server

type WebResult

type WebResult struct {
	Asm File `json:"asm"`
	Go  File `json:"go"`
}

WebResult represents a result from the remote server