hitsumabushi

README

Hitsumabushi (ひつまぶし)

Package hitsumabushi provides APIs to generate JSON for go-build's -overlay option. Hitsumabushi aims to make Go programs work on almost everywhere by overwriting system calls with C function calls. Now the generated JSON works only for Linux/Arm64 and Windows/Amd64 so far. For GOOS=windows, Hitsumabushi replaces some functions that don't work on some special Windows-like systems.

Go version: 1.19-1.21

Example

On Arm Linux, run these commands:

cd example/helloworld
./run.sh

Tips

With VC++, you might have to call _rt0_amd64_windows_lib() at the beginning of the entry point explicitly. See also https://github.com/golang/go/issues/42190.

Documentation

Overview

Package hitsumabushi provides APIs to generate JSON for go-build's `-overlay` option. Hitsumabushi aims to make Go programs work on almost everywhere by overwriting system calls with C function calls. Now the generated JSON works only for Arm64 so far.

Index

• func CPUFilePath(os string) (string, error)
• func ClockFilePath(os string) (string, error)
• func FilesystemFilePath(os string) (string, error)
• func FutexFilePath(os string) (string, error)
• func GenOverlayJSON(options ...Option) ([]byte, error)
• func MemoryFilePath(os string) (string, error)
• func ThreadFilePath(os string) (string, error)
• type Option
  • func Args(args ...string) Option
  • func GOOS(os string) Option
  • func Overlay(from, to string) Option
  • func OverlayDir(dir string) Option
  • func PageSize(pageSize int) Option
  • func ReplaceDLL(from, to string) Option
  • func TestPkg(pkg string) Option

Functions

func CPUFilePath

func CPUFilePath(os string) (string, error)

CPUFilePath returns a C file's path for the CPU functions. This file works only when linux is specified as the GOOS option.

The file includes this function:

• int32_t hitsumabushi_getproccount()

The default implementation uses 1.

func ClockFilePath

func ClockFilePath(os string) (string, error)

ClockFilePath returns a C file's path for the clock functions. This file works only when linux is specified as the GOOS option.

The file includes this function:

• int hitsumabushi_clock_gettime(clockid_t clk_id, struct timespec *tp)

The default implementation calls clock_gettime.

func FilesystemFilePath

func FilesystemFilePath(os string) (string, error)

FilesystemFilePath returns a C file's path for the filesystem functions. This file works only when linux is specified as the GOOS option.

The file includes these functions:

• int32_t hitsumabushi_closefd(int32_t fd)
• int32_t hitsumabushi_open(char *name, int32_t mode, int32_t perm)
• int32_t hitsumabushi_read(int32_t fd, void *p, int32_t n)
• int32_t hitsumabushi_write1(uintptr_t fd, void *p, int32_t n)
• int32_t hitsumabushi_lseek(uintptr_t fd, off_t offset, int32_t whence)
• int32_t hitsumabushi_fcntl(int32_t fd, int32_t cmd, int32_t arg)
• int32_t hitsumabushi_fstat(int32_t fd, struct stat *stat)
• int32_t hitsumabushi_renameat(int32_t fd1, char* name1, int32_t fd2, char* name2)
• int32_t hitsumabushi_fstatat(int32_t fd, char* name, struct stat* p, int32_t flags)

The default implementation only handles stdout, stderr, and some pseudo-files.

func FutexFilePath

func FutexFilePath(os string) (string, error)

FutexFilePath returns a C file's path for the futex functions. This file works only when linux is specified as the GOOS option.

The file includes this function:

• int32_t hitsumabushi_futex(uint32_t *uaddr, int32_t futex_op, uint32_t val, const struct timespec *timeout, uint32_t *uaddr2, uint32_t val3)

The default implementation is a pseudo futex by pthread.

func GenOverlayJSON

func GenOverlayJSON(options ...Option) ([]byte, error)

GenOverlayJSON generates a JSON file for go-build's `-overlay` option. GenOverlayJSON returns a JSON file content, or an error if generating it fails.

Now the generated JSON works only for Arm64 so far.

func MemoryFilePath

func MemoryFilePath(os string) (string, error)

MemoryFilePath returns a C file's path for the memory functions. This file works only when linux is specified as the GOOS option.

The file includes these functions:

• void* hitsumabushi_sysAllocOS(uintptr_t n)
• void hitsumabushi_sysUnusedOS(void* v, uintptr_t n)
• void hitsumabushi_sysUsedOS(void* v, uintptr_t n)
• void hitsumabushi_sysHugePageOS(void* v, uintptr_t n)
• void hitsumabushi_sysFreeOS(void* v, uintptr_t n)
• void hitsumabushi_sysFaultOS(void* v, uintptr_t n)
• void* hitsumabushi_sysReserveOS(void* v, uintptr_t n)
• void hitsumabushi_sysMapOS(void* v, uintptr_t n)

The default implementation is a pseudo allocation by calloc without free.

For the implementation details, see https://cs.opensource.google/go/go/+/master:src/runtime/mem.go .

func ThreadFilePath

func ThreadFilePath(os string) (string, error)

Types

type Option

type Option func(*config)

func Args

func Args(args ...string) Option

Args is arguments when executing. The first argument must be a program name.

func GOOS

func GOOS(os string) Option

GOOS specifies GOOS to generate the JSON. The default value is runtime.GOOS.

func Overlay

func Overlay(from, to string) Option

Overlay adds or replaces an entry for the -overlay option.

func OverlayDir

func OverlayDir(dir string) Option

OverlayDir sets the temporary working directory where overlay files are stored.

func PageSize

func PageSize(pageSize int) Option

PageSize specifies the page size. The deafult value is 4096.

This works only for Linux.

func ReplaceDLL

func ReplaceDLL(from, to string) Option

ReplaceDLL replaces a DLL file name loaded at LoadLibraryW and LoadLibraryExW.

This works only for Windows.

func TestPkg

func TestPkg(pkg string) Option

TestPkg represents a package for testing. When generating a JSON, importing `runtime/cgo` is inserted in the testing package.