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. Generated Go assembly will try to use at little binary codes as possible, making the output more suitable for tuning, or to give you a starting point, but do note that not everything can be expressed in Plan9 assembly plus the disassembly process is sometimes buggy (which is the reason why some instructions will still use binary).

Features

• 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.
• Annotated C functions will have their Go stubs auto-generated.
• Automatically formats go assembly using asmfmt.

Annotating C functions

Only functions with gocc annotation will be compiled into Go functions, note that there's some limitations for parameters - for example when using Go slices, 3 parameters in C have to be used (base pointer, length and capacity). The tool will check whether the C signature is compatible with the go signature.

An example annotation:

// gocc: simd_fn(input string) int64
int64_t simd_fn(char *input1, uint64_t input1_len) {
  ...
}

Setting up locally

Before you use gocc, you need to install the LLVM toolchain. On Ubuntu, you can do it with the following commands (LLVM 15 was used the most during development of gocc):

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

On macOS, you'll need to install Xcode, which includes clang and other build essentials:

xcode-select --install

The example folder includes matrix multiplication using intrinsics compiled for amd64 and arm64, as well as an example that only uses clang's auto-vectorization. See the example/gen.sh script to see how gocc can be invoked.

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 requires you to inline your C functions.
• No dynamic memory allocation.
• Currently limited to 6 arguments per function.

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, ...) (*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
	FuncSuffix string
	Assembly   string
	Object     string
	GoAssembly string
	GoStub     string
	Package    string
	Options    []string
}

Local translates a C file to Go assembly

func NewLocal

func NewLocal(arch *config.Arch, source, outputDir, suffix, functionSuffix, 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