Re-org SDK dir (#4690)

This commit is contained in:
Jack May
2019-06-17 11:04:38 -07:00
committed by GitHub
parent 5bf87de136
commit 2a7a9fdf03
45 changed files with 40 additions and 40 deletions

44
sdk/bpf/c/README.md Normal file
View File

@ -0,0 +1,44 @@
## Development
### Quick start
To get started create a `makefile` containing:
```make
include path/to/bpf.mk
```
and `src/program.c` containing:
```c
#include <solana_sdk.h>
bool entrypoint(const uint8_t *input) {
SolKeyedAccount ka[1];
uint8_t *data;
uint64_t data_len;
if (!sol_deserialize(buf, ka, SOL_ARRAY_SIZE(ka), NULL, &data, &data_len)) {
return false;
}
print_params(1, ka, data, data_len);
return true;
}
```
Then run `make` to build `out/program.o`.
Run `make help` for more details.
### Unit tests
Built-in support for unit testing is provided by the
[Criterion](https://criterion.readthedocs.io/en/master/index.html) test framework.
To get started create the file `test/example.c` containing:
```c
#include <criterion/criterion.h>
#include "../src/program.c"
Test(test_suite_name, test_case_name) {
cr_assert(true);
}
```
Then run `make test`.
### Limitations
* Programs must be fully contained within a single .c file
* No libc is available but `solana_sdk.h` provides a minimal set of primitives

19
sdk/bpf/c/bpf.ld Normal file
View File

@ -0,0 +1,19 @@
PHDRS
{
text PT_LOAD ;
rodata PT_LOAD ;
dynamic PT_DYNAMIC ;
}
SECTIONS
{
. = SIZEOF_HEADERS;
.text : { *(.text) } :text
.rodata : { *(.rodata) } :rodata
.dynamic : { *(.dynamic) } :dynamic
.dynsym : { *(.dynsym) } :dynamic
.dynstr : { *(.dynstr) } :dynamic
.gnu.hash : { *(.gnu.hash) } :dynamic
.rel.dyn : { *(.rel.dyn) } :dynamic
.hash : { *(.hash) } :dynamic
}

253
sdk/bpf/c/bpf.mk Normal file
View File

@ -0,0 +1,253 @@
LOCAL_PATH := $(dir $(lastword $(MAKEFILE_LIST)))
INSTALL_SH := $(abspath $(LOCAL_PATH)/../scripts/install.sh)
all:
.PHONY: help all clean
ifneq ($(V),1)
_@ :=@
endif
INC_DIRS ?=
SRC_DIR ?= ./src
TEST_PREFIX ?= test_
OUT_DIR ?= ./out
OS := $(shell uname)
ifeq ($(DOCKER),1)
$(warning DOCKER=1 is experimential and may not work as advertised)
LLVM_DIR = $(LOCAL_PATH)../dependencies/llvm-docker/
LLVM_SYSTEM_INC_DIRS := /usr/local/lib/clang/8.0.0/include
else
LLVM_DIR = $(LOCAL_PATH)../dependencies/llvm-native/
LLVM_SYSTEM_INC_DIRS := $(LLVM_DIR)/lib/clang/8.0.0/include
endif
ifdef LLVM_DIR
CC := $(LLVM_DIR)/bin/clang
CXX := $(LLVM_DIR)/bin/clang++
LLD := $(LLVM_DIR)/bin/ld.lld
OBJ_DUMP := $(LLVM_DIR)/bin/llvm-objdump
endif
SYSTEM_INC_DIRS := \
$(LOCAL_PATH)inc \
$(LLVM_SYSTEM_INC_DIRS) \
C_FLAGS := \
-Werror \
-O2 \
-fno-builtin \
-std=c17 \
$(addprefix -isystem,$(SYSTEM_INC_DIRS)) \
$(addprefix -I,$(INC_DIRS))
CXX_FLAGS := \
$(C_FLAGS) \
-std=c++17 \
BPF_C_FLAGS := \
$(C_FLAGS) \
-target bpf \
-fPIC \
BPF_CXX_FLAGS := \
$(CXX_FLAGS) \
-target bpf \
-fPIC \
-fomit-frame-pointer \
-fno-exceptions \
-fno-asynchronous-unwind-tables \
-fno-unwind-tables \
BPF_LLD_FLAGS := \
-z notext \
-shared \
--Bdynamic \
$(LOCAL_PATH)bpf.ld \
--entry entrypoint \
OBJ_DUMP_FLAGS := \
-color \
-source \
-disassemble \
TESTFRAMEWORK_RPATH := $(abspath $(LOCAL_PATH)../dependencies/criterion/lib)
TESTFRAMEWORK_FLAGS := \
-DSOL_TEST \
-isystem $(LOCAL_PATH)../dependencies/criterion/include \
-L $(LOCAL_PATH)../dependencies/criterion/lib \
-rpath $(TESTFRAMEWORK_RPATH) \
-lcriterion \
# The "-rpath" in TESTFRAMEWORK_FLAGS doesn't work in macOS so rewrite the name
# post-link.
# TODO: Find a better way
MACOS_ADJUST_TEST_DYLIB := \
$(if $(filter $(OS),Darwin),\
$(_@)install_name_tool -change libcriterion.3.dylib $(TESTFRAMEWORK_RPATH)/libcriterion.3.dylib, \
: \
)
TEST_C_FLAGS := \
$(C_FLAGS) \
$(TESTFRAMEWORK_FLAGS) \
TEST_CXX_FLAGS := \
$(CXX_FLAGS) \
$(TESTFRAMEWORK_FLAGS) \
help:
@echo ''
@echo 'BPF Program makefile'
@echo ''
@echo 'This makefile will build BPF Programs from C or C++ source files into ELFs'
@echo ''
@echo 'Assumptions:'
@echo ' - Programs are located in the source directory: $(SRC_DIR)/<program name>'
@echo ' - Programs are named by their directory name (eg. directory name:src/foo/ -> program name:foo)'
@echo ' - Tests are located in their corresponding program directory and must being with "test_"'
@echo ' - Output files will be placed in the directory: $(OUT_DIR)'
@echo ''
@echo 'User settings'
@echo ' - The following setting are overridable on the command line, default values shown:'
@echo ' - Show commands while building: V=1'
@echo ' V=$(V)'
@echo ' - List of include directories:'
@echo ' INC_DIRS=$(INC_DIRS)'
@echo ' - List of system include directories:'
@echo ' SYSTEM_INC_DIRS=$(SYSTEM_INC_DIRS)'
@echo ' - Location of source directories:'
@echo ' SRC_DIR=$(SRC_DIR)'
@echo ' - Location to place output files:'
@echo ' OUT_DIR=$(OUT_DIR)'
@echo ' - Location of LLVM:'
@echo ' LLVM_DIR=$(LLVM_DIR)'
@echo ''
@echo 'Usage:'
@echo ' - make help - This help message'
@echo ' - make all - Build all the programs and tests, run the tests'
@echo ' - make programs - Build all the programs'
@echo ' - make tests - Build and run all tests'
@echo ' - make dump_<program name> - Dumps the contents of the program to stdout'
@echo ' - make <program name> - Build a single program by name'
@echo ' - make <test name> - Build and run a single test by name'
@echo ''
@echo 'Available programs:'
$(foreach name, $(PROGRAM_NAMES), @echo ' - $(name)'$(\n))
@echo ''
@echo 'Available tests:'
$(foreach name, $(TEST_NAMES), @echo ' - $(name)'$(\n))
@echo ''
@echo 'Example:'
@echo ' - Assuming a programed named foo (src/foo/foo.c)'
@echo ' - make foo'
@echo ' - make dump_foo'
@echo ''
define C_RULE
$1: $2
@echo "[cc] $1 ($2)"
$(_@)mkdir -p $(dir $1)
$(_@)$(CC) $(BPF_C_FLAGS) -o $1 -c $2 -MD -MF $(1:.o=.d)
endef
define CC_RULE
$1: $2
@echo "[cxx] $1 ($2)"
$(_@)mkdir -p $(dir $1)
$(_@)$(CXX) $(BPF_CXX_FLAGS) -o $1 -c $2 -MD -MF $(1:.o=.d)
endef
define O_RULE
$1: $2
@echo "[llc] $1 ($2)"
$(_@)mkdir -p $(dir $1)
$(_@)$(LLC) $(BPF_LLC_FLAGS) -o $1 $2
endef
define SO_RULE
$1: $2
@echo "[lld] $1 ($2)"
$(_@)mkdir -p $(dir $1)
$(_@)$(LLD) $(BPF_LLD_FLAGS) -o $1 $2
endef
define TEST_C_RULE
$1: $2
@echo "[test cc] $1 ($2)"
$(_@)mkdir -p $(dir $1)
$(_@)$(CC) $(TEST_C_FLAGS) -o $1 $2 -MD -MF $(1:.o=.d)
$(_@)$(MACOS_ADJUST_TEST_DYLIB) $1
endef
define TEST_CC_RULE
$1: $2
@echo "[test cxx] $1 ($2)"
$(_@)mkdir -p $(dir $1)
$(_@)$(CXX) $(TEST_CXX_FLAGS) -o $1 $2 -MD -MF $(1:.o=.d)
$(_@)$(MACOS_ADJUST_TEST_DYLIB) $1
endef
define TEST_EXEC_RULE
$1: $2
$2$(\n)
endef
.PHONY: $(INSTALL_SH)
$(INSTALL_SH):
$(_@)$(INSTALL_SH)
PROGRAM_NAMES := $(notdir $(basename $(wildcard $(SRC_DIR)/*)))
define \n
endef
all: programs tests
$(foreach PROGRAM, $(PROGRAM_NAMES), \
$(eval -include $(wildcard $(OUT_DIR)/$(PROGRAM)/*.d)) \
\
$(eval $(PROGRAM): %: $(addprefix $(OUT_DIR)/, %.so)) \
$(eval $(PROGRAM)_SRCS := \
$(addprefix $(SRC_DIR)/$(PROGRAM)/, \
$(filter-out $(TEST_PREFIX)%,$(notdir $(wildcard $(SRC_DIR)/$(PROGRAM)/*.c $(SRC_DIR)/$(PROGRAM)/*.cc))))) \
$(eval $(PROGRAM)_OBJS := $(subst $(SRC_DIR), $(OUT_DIR), \
$(patsubst %.c,%.o, \
$(patsubst %.cc,%.o,$($(PROGRAM)_SRCS))))) \
$(eval $($(PROGRAM)_SRCS): $(INSTALL_SH)) \
$(eval $(call SO_RULE,$(OUT_DIR)/$(PROGRAM).so,$($(PROGRAM)_OBJS))) \
$(foreach _,$(filter %.c,$($(PROGRAM)_SRCS)), \
$(eval $(call C_RULE,$(subst $(SRC_DIR),$(OUT_DIR),$(_:%.c=%.o)),$_))) \
$(foreach _,$(filter %.cc,$($(PROGRAM)_SRCS)), \
$(eval $(call CC_RULE,$(subst $(SRC_DIR),$(OUT_DIR),$(_:%.cc=%.o)),$_))) \
\
$(eval TESTS := $(notdir $(basename $(wildcard $(SRC_DIR)/$(PROGRAM)/$(TEST_PREFIX)*.c)))) \
$(eval $(TESTS) : %: $(addprefix $(OUT_DIR)/$(PROGRAM)/, %)) \
$(eval TEST_NAMES := $(TEST_NAMES) $(TESTS)) \
$(foreach TEST, $(TESTS), \
$(eval $(TEST)_SRCS := \
$(addprefix $(SRC_DIR)/$(PROGRAM)/, \
$(notdir $(wildcard $(SRC_DIR)/$(PROGRAM)/$(TEST).c $(SRC_DIR)/$(PROGRAM)/$(TEST).cc)))) \
$(eval $($(TEST)_SRCS): $(INSTALL_SH)) \
$(foreach _,$(filter %.c,$($(TEST)_SRCS)), \
$(eval $(call TEST_C_RULE,$(subst $(SRC_DIR),$(OUT_DIR),$(_:%.c=%)),$_))) \
$(foreach _,$(filter %.cc, $($(TEST)_SRCS)), \
$(eval $(call TEST_CC_RULE,$(subst $(SRC_DIR),$(OUT_DIR),$(_:%.cc=%)),$_))) \
$(eval $(call TEST_EXEC_RULE,$(TEST),$(addprefix $(OUT_DIR)/$(PROGRAM)/, $(TEST)))) \
) \
)
.PHONY: $(PROGRAM_NAMES)
programs: $(PROGRAM_NAMES)
.PHONY: $(TEST_NAMES)
tests: $(TEST_NAMES)
dump_%: %
$(_@)$(OBJ_DUMP) $(OBJ_DUMP_FLAGS) $(addprefix $(OUT_DIR)/, $(addsuffix .so, $<))
clean:
rm -rf $(OUT_DIR)

348
sdk/bpf/c/inc/solana_sdk.h Normal file
View File

@ -0,0 +1,348 @@
#pragma once
/**
* @brief Solana C-based BPF program utility functions and types
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* Pick up static_assert if C11 or greater
*
* Inlined here until <assert.h> is available
*/
#if (defined _ISOC11_SOURCE || (defined __STDC_VERSION__ && __STDC_VERSION__ >= 201112L)) && !defined (__cplusplus)
#undef static_assert
#define static_assert _Static_assert
#endif
/**
* Numeric types
*/
#ifndef __LP64__
#error LP64 data model required
#endif
typedef signed char int8_t;
typedef unsigned char uint8_t;
typedef signed short int16_t;
typedef unsigned short uint16_t;
typedef signed int int32_t;
typedef unsigned int uint32_t;
typedef signed long int int64_t;
typedef unsigned long int uint64_t;
typedef int64_t ssize_t;
typedef uint64_t size_t;
#if defined (__cplusplus) || defined(static_assert)
static_assert(sizeof(int8_t) == 1);
static_assert(sizeof(uint8_t) == 1);
static_assert(sizeof(int16_t) == 2);
static_assert(sizeof(uint16_t) == 2);
static_assert(sizeof(int32_t) == 4);
static_assert(sizeof(uint32_t) == 4);
static_assert(sizeof(int64_t) == 8);
static_assert(sizeof(uint64_t) == 8);
#endif
/**
* NULL
*/
#define NULL 0
/**
* Boolean type
*/
#ifndef __cplusplus
#include <stdbool.h>
#endif
/**
* Helper function that prints a string to stdout
*/
void sol_log(const char *);
/**
* Helper function that prints a 64 bit values represented in hexadecimal
* to stdout
*/
void sol_log_64(uint64_t, uint64_t, uint64_t, uint64_t, uint64_t);
/**
* Prefix for all BPF functions
*
* This prefix should be used for functions in order to facilitate
* interoperability with BPF representation
*/
#define SOL_FN_PREFIX __attribute__((always_inline)) static
/**
* Size of Public key in bytes
*/
#define SIZE_PUBKEY 32
/**
* Public key
*/
typedef struct {
uint8_t x[SIZE_PUBKEY];
} SolPubkey;
/**
* Compares two public keys
*
* @param one First public key
* @param two Second public key
* @return true if the same
*/
SOL_FN_PREFIX bool SolPubkey_same(const SolPubkey *one, const SolPubkey *two) {
for (int i = 0; i < sizeof(*one); i++) {
if (one->x[i] != two->x[i]) {
return false;
}
}
return true;
}
/**
* Keyed Account
*/
typedef struct {
SolPubkey *key; /** Public key of the account */
bool is_signer; /** Transaction was signed by this account's key */
uint64_t *lamports; /** Number of lamports owned by this account */
uint64_t userdata_len; /** Length of data in bytes */
uint8_t *userdata; /** On-chain data within this account */
SolPubkey *owner; /** Program that owns this account */
} SolKeyedAccount;
/**
* Copies memory
*/
SOL_FN_PREFIX void sol_memcpy(void *dst, const void *src, int len) {
for (int i = 0; i < len; i++) {
*((uint8_t *)dst + i) = *((const uint8_t *)src + i);
}
}
/**
* Compares memory
*/
SOL_FN_PREFIX int sol_memcmp(const void *s1, const void *s2, int n) {
for (int i = 0; i < n; i++) {
uint8_t diff = *((uint8_t *)s1 + i) - *((const uint8_t *)s2 + i);
if (diff) {
return diff;
}
}
return 0;
}
/**
* Fill a byte string with a byte value
*/
SOL_FN_PREFIX void *sol_memset(void *b, int c, size_t len) {
uint8_t *a = (uint8_t *) b;
while (len > 0) {
*a = c;
a++;
len--;
}
}
/**
* Find length of string
*/
SOL_FN_PREFIX size_t sol_strlen(const char *s) {
size_t len = 0;
while (*s) {
len++;
s++;
}
return len;
}
/**
* Computes the number of elements in an array
*/
#define SOL_ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
/**
* Panics
*
* Prints the line number where the panic occurred and then causes
* the BPF VM to immediately halt execution. No accounts' userdata are updated
*/
#define sol_panic() _sol_panic(__LINE__)
SOL_FN_PREFIX void _sol_panic(uint64_t line) {
sol_log_64(0xFF, 0xFF, 0xFF, 0xFF, line);
uint8_t *pv = (uint8_t *)1;
*pv = 1;
}
/**
* Asserts
*/
#define sol_assert(expr) \
if (!(expr)) { \
_sol_panic(__LINE__); \
}
/**
* Structure that the program's entrypoint input data is deserialized into.
*/
typedef struct {
SolKeyedAccount* ka; /** Pointer to an array of SolKeyedAccount, must already
point to an array of SolKeyedAccounts */
uint64_t ka_num; /** Number of SolKeyedAccount entries in `ka` */
const uint8_t *data; /** pointer to the instruction data */
uint64_t data_len; /** Length in bytes of the instruction data */
const SolPubkey *program_id; /** program_id of the currently executing program */
} SolParameters;
/**
* De-serializes the input parameters into usable types
*
* Use this function to deserialize the buffer passed to the program entrypoint
* into usable types. This function does not perform copy deserialization,
* instead it populates the pointers and lengths in SolKeyedAccount and data so
* that any modification to lamports or account data take place on the original
* buffer. Doing so also eliminates the need to serialize back into the buffer
* at program end.
*
* @param input Source buffer containing serialized input parameters
* @param params Pointer to a SolParameters structure
* @return Boolean true if successful.
*/
SOL_FN_PREFIX bool sol_deserialize(
const uint8_t *input,
SolParameters *params,
uint64_t ka_num
) {
if (NULL == input || NULL == params) {
return false;
}
params->ka_num = *(uint64_t *) input;
if (ka_num < *(uint64_t *) input) {
return false;
}
input += sizeof(uint64_t);
for (int i = 0; i < params->ka_num; i++) {
// key
params->ka[i].is_signer = *(uint64_t *) input != 0;
input += sizeof(uint64_t);
params->ka[i].key = (SolPubkey *) input;
input += sizeof(SolPubkey);
// lamports
params->ka[i].lamports = (uint64_t *) input;
input += sizeof(uint64_t);
// account userdata
params->ka[i].userdata_len = *(uint64_t *) input;
input += sizeof(uint64_t);
params->ka[i].userdata = (uint8_t *) input;
input += params->ka[i].userdata_len;
// owner
params->ka[i].owner = (SolPubkey *) input;
input += sizeof(SolPubkey);
}
params->data_len = *(uint64_t *) input;
input += sizeof(uint64_t);
params->data = input;
input += params->data_len;
params->program_id = (SolPubkey *) input;
input += sizeof(SolPubkey);
return true;
}
/**
* Debugging utilities
* @{
*/
/**
* Prints the hexadecimal representation of a public key
*
* @param key The public key to print
*/
SOL_FN_PREFIX void sol_log_key(const SolPubkey *key) {
for (int j = 0; j < sizeof(*key); j++) {
sol_log_64(0, 0, 0, j, key->x[j]);
}
}
/**
* Prints the hexadecimal representation of an array
*
* @param array The array to print
*/
SOL_FN_PREFIX void sol_log_array(const uint8_t *array, int len) {
for (int j = 0; j < len; j++) {
sol_log_64(0, 0, 0, j, array[j]);
}
}
/**
* Prints the program's input parameters
*
* @param params Pointer to a SolParameters structure
*/
SOL_FN_PREFIX void sol_log_params(const SolParameters *params) {
sol_log("- Program identifier:");
sol_log_key(params->program_id);
sol_log("- Number of KeyedAccounts");
sol_log_64(0, 0, 0, 0, params->ka_num);
for (int i = 0; i < params->ka_num; i++) {
sol_log(" - Is signer");
sol_log_64(0, 0, 0, 0, params->ka[i].is_signer);
sol_log(" - Key");
sol_log_key(params->ka[i].key);
sol_log(" - Lamports");
sol_log_64(0, 0, 0, 0, *params->ka[i].lamports);
sol_log(" - Userdata");
sol_log_array(params->ka[i].userdata, params->ka[i].userdata_len);
sol_log(" - Owner");
sol_log_key(params->ka[i].owner);
}
sol_log("- Instruction data\0");
sol_log_array(params->data, params->data_len);
}
/**@}*/
/**
* Program instruction entrypoint
*
* @param input Buffer of serialized input parameters. Use sol_deserialize() to decode
* @return true if the instruction executed successfully
*/
bool entrypoint(const uint8_t *input);
#ifdef SOL_TEST
/**
* Stub log functions when building tests
*/
#include <stdio.h>
void sol_log(const char *s) {
printf("sol_log: %s\n", s);
}
void sol_log_64(uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5) {
printf("sol_log_64: %llu, %llu, %llu, %llu, %llu\n", arg1, arg2, arg3, arg4, arg5);
}
#endif
#ifdef __cplusplus
}
#endif
/**@}*/

2
sdk/bpf/c/inc/stdio.h Normal file
View File

@ -0,0 +1,2 @@
#pragma once
typedef void *FILE;

2
sdk/bpf/c/inc/stdlib.h Normal file
View File

@ -0,0 +1,2 @@
#pragma once
#include <solana_sdk.h>

7
sdk/bpf/c/inc/string.h Normal file
View File

@ -0,0 +1,7 @@
#pragma once
#include <solana_sdk.h>
#define memcpy sol_memcpy
#define memset sol_memset
#define strlen sol_strlen

View File

@ -0,0 +1 @@
#pragma once

1
sdk/bpf/c/inc/wchar.h Normal file
View File

@ -0,0 +1 @@
#pragma once