Syscall Reference¶

ESPM exposes 102 syscalls (ESPM v0.2.0) as function pointers in the espm_sys_t struct. Modules call them through macros in espm.h (for example printf(...) maps to sys->printf(...)). The struct is defined in espm_module.h and must be identical between the standalone ESPM repo and the firmware copy.

Availability varies by chip

BLE syscalls require a BLE-capable chip, and the modem syscalls exist only on GPRS builds. See supported boards.

System and memory¶

Syscall	Signature	Purpose
`printf`	`int (const char *fmt, ...)`	Formatted output
`snprintf`	`int (char str, size_t size, const char fmt, ...)`	Formatted string buffer
`malloc`	`void *(size_t size)`	Heap allocation
`free`	`void (void *ptr)`	Heap free
`get_free_heap`	`uint32_t (void)`	Free heap in bytes
`reboot`	`void (void)`	Restart the device
`delay_ms`	`void (uint32_t ms)`	Block the task for N ms
`get_time_us`	`int64_t (void)`	Microsecond timestamp
`caps_malloc`	`void *(size_t size, uint32_t caps)`	Allocate with capability flags (SPIRAM, DMA, ...)
`caps_free`	`void (void *ptr)`	Free capability memory
`caps_get_free`	`size_t (uint32_t caps)`	Free memory for a capability
`random`	`uint32_t (void)`	32-bit PRNG value
`random_bytes`	`void (void *buf, size_t len)`	Fill buffer from the hardware RNG
`get_tick_count`	`uint32_t (void)`	FreeRTOS tick count
`get_chip_info`	`int (uint32_t model, uint32_t cores, uint32_t *rev)`	Chip model / cores / revision

Logging¶

Syscall	Signature	Purpose
`log_write`	`void (int level, const char tag, const char fmt, ...)`	Levelled log (ERROR, WARN, INFO, DEBUG, VERBOSE)

GPIO, UART, I2C¶

Syscall	Signature	Purpose
`gpio_set_dir`	`int (int pin, int mode)`	Set pin direction (GPIO 6-11 blocked on ESP32)
`gpio_set`	`int (int pin, int level)`	Drive a pin
`gpio_get`	`int (int pin)`	Read a pin
`uart_init`	`int (int port, uint32_t baud, int tx, int rx)`	Configure UART (-1 pin keeps current)
`uart_write`	`int (int port, const void *data, size_t len)`	Send bytes
`uart_read`	`int (int port, void *buf, size_t len, uint32_t timeout_ms)`	Receive bytes
`i2c_init`	`int (int port, int sda, int scl, uint32_t freq_hz)`	Configure I2C master
`i2c_write`	`int (int port, uint8_t addr, const void *data, size_t len)`	Write to a 7-bit address
`i2c_read`	`int (int port, uint8_t addr, void *buf, size_t len)`	Read from a 7-bit address

Crypto¶

Syscall	Signature	Purpose
`sha256`	`int (const void in, size_t len, void out)`	SHA-256 (32-byte output)
`hmac_sha256`	`int (const void key, size_t klen, const void data, size_t dlen, void *out)`	HMAC-SHA256
`chacha20`	`int (const uint8_t key[32], const uint8_t nonce[12], uint32_t counter, const void in, size_t len, void out)`	ChaCha20 stream cipher
`crypto_encrypt`	`int (const void plain, size_t plen, void out, size_t cap)`	C2 session AEAD encrypt (nonce \| ct \| tag)
`crypto_decrypt`	`int (const void in, size_t len, void out, size_t cap)`	C2 session AEAD decrypt
`hw_trng`	`uint32_t (void)`	Hardware RNG word
`hw_aes_block`	`void (const uint8_t key, const uint8_t in, uint8_t *out)`	Hardware AES-128 ECB block
`hw_sha256`	`void (const uint8_t data, size_t len, uint8_t out)`	Hardware SHA-256

WiFi - station mode¶

Syscall	Signature	Purpose
`wifi_scan_start`	`int (void)`	Active 802.11 scan (blocking)
`wifi_scan_get`	`int (void results, uint16_t count)`	Retrieve scan results
`wifi_connect`	`int (const char ssid, const char pass)`	Connect STA to an AP
`wifi_disconnect`	`int (void)`	Disconnect
`wifi_init_sta`	`int (void)`	Bring up STA mode (GPRS boards)
`wifi_deinit`	`int (void)`	Stop and free the WiFi radio (~30 KB)

WiFi - access point mode¶

Syscall	Signature	Purpose
`ap_start`	`int (const char ssid, const char pass, uint8_t channel, uint8_t max_conn)`	Create a SoftAP
`ap_stop`	`int (void)`	Tear down the SoftAP
`ap_get_clients`	`int (void buf, uint16_t count)`	List associated stations
`napt_enable`	`void (uint32_t ip_host, int enable)`	Toggle IPv4 NAT on the SoftAP

WiFi - raw 802.11 and sniffer¶

Syscall	Signature	Purpose
`wifi_80211_tx`	`int (const void *buf, int len, bool en_sys_seq)`	Inject a raw 802.11 frame
`wifi_set_channel`	`int (uint8_t channel, uint8_t ht_mode)`	Set channel (1-13)
`wifi_set_mac`	`int (const uint8_t mac[6])`	Override STA MAC (locally administered)
`wifi_get_ap_info`	`int (uint8_t bssid[6], uint8_t ssid, uint8_t ch, int8_t *rssi)`	Current AP info
`promisc_start`	`int (void)`	Enable promiscuous capture
`promisc_stop`	`int (void)`	Disable promiscuous mode
`promisc_read`	`int (void *buf, int max_len)`	Read the next captured frame
`arp_send`	`int (uint8_t op, const uint8_t smac, uint32_t sip, const uint8_t dmac, uint32_t dip)`	Inject a raw ARP frame

Sockets (BSD-like)¶

Syscall	Signature	Purpose
`sock_create`	`int (int domain, int type, int proto)`	Create a socket
`sock_connect`	`int (int fd, const void *addr, uint32_t len)`	Connect
`sock_send`	`int (int fd, const void *buf, size_t len, int flags)`	Send
`sock_recv`	`int (int fd, void *buf, size_t len, int flags)`	Receive
`sock_close`	`int (int fd)`	Close
`sock_bind`	`int (int fd, const void *addr, uint32_t len)`	Bind
`sock_listen`	`int (int fd, int backlog)`	Listen
`sock_accept`	`int (int fd, void addr, uint32_t addrlen)`	Accept
`sock_select`	`int (int fd, int timeout_ms)`	Wait for readable
`sendto`	`int (int fd, const void buf, size_t len, int flags, const void addr, uint32_t addrlen)`	Send a UDP datagram
`recvfrom`	`int (int fd, void buf, size_t len, int flags, void addr, uint32_t *addrlen)`	Receive a UDP datagram
`setsockopt`	`int (int fd, int level, int optname, const void *optval, uint32_t optlen)`	Set a socket option

Network and DNS¶

Syscall	Signature	Purpose
`dns_resolve`	`int (const char host, uint32_t ip_out)`	Resolve a hostname to IPv4
`get_local_ip`	`int (uint32_t ip_out, uint32_t mask_out)`	Local IP and netmask
`get_arp_mac`	`int (uint32_t ip_host, uint8_t mac_out[6])`	MAC from the ARP cache
`icmp_ping`	`int (uint32_t ip_host, uint32_t timeout_ms)`	Single ICMP echo (RTT in ms)

BLE¶

Syscall	Signature	Purpose
`ble_controller_init`	`int (void)`	Start the controller + NimBLE (on-demand)
`ble_controller_deinit`	`void (void)`	Stop BLE, free ~130 KB
`ble_scan`	`int (uint32_t duration_ms, void results, uint16_t count)`	Passive scan
`ble_adv_start`	`int (const uint8_t data, uint8_t len, uint16_t itvl_ms, const uint8_t addr)`	Start advertising
`ble_adv_stop`	`int (void)`	Stop advertising
`ble_set_addr`	`int (const uint8_t addr[6])`	Override the BLE address
`ble_connect`	`int (const uint8_t addr[6], uint8_t addr_type, uint32_t timeout_ms)`	Connect to a peripheral
`ble_disconnect`	`int (uint16_t conn_handle)`	Disconnect
`ble_gatt_discover`	`int (uint16_t conn, void services, uint16_t count)`	Enumerate services
`ble_gatt_chars`	`int (uint16_t conn, uint16_t start, uint16_t end, void chars, uint16_t count)`	Enumerate characteristics
`ble_gatt_read`	`int (uint16_t conn, uint16_t val_handle, void buf, size_t len)`	Read a characteristic
`ble_gatt_write`	`int (uint16_t conn, uint16_t val_handle, const void *data, size_t len)`	Write a characteristic

Tasks and synchronization¶

Syscall	Signature	Purpose
`task_create`	`int (void (fn)(void ), const char name, uint32_t stack_words, void arg, int priority)`	Spawn a task
`task_exit`	`void (void)`	Exit the current task
`task_notify_wait`	`int (uint32_t timeout_ms)`	Wait for a stop notification
`task_notify_by_name`	`int (const char *task_name, uint32_t value)`	Notify a task by name
`watchdog_feed`	`void (void)`	Reset the per-module watchdog
`mutex_create`	`void *(void)`	Create a recursive mutex
`mutex_take`	`int (void *handle, uint32_t timeout_ms)`	Acquire
`mutex_give`	`void (void *handle)`	Release
`mutex_delete`	`void (void *handle)`	Destroy
`queue_create`	`void *(uint32_t len, uint32_t item_size)`	Create a queue
`queue_send`	`int (void handle, const void item, uint32_t timeout_ms)`	Enqueue
`queue_recv`	`int (void handle, void item, uint32_t timeout_ms)`	Dequeue
`queue_delete`	`void (void *handle)`	Destroy a queue

NVS¶

Syscall	Signature	Purpose
`nvs_set`	`int (const char key, const void data, size_t len)`	Write a blob (key <= 15 chars)
`nvs_get`	`int (const char key, void buf, size_t *len)`	Read a blob
`nvs_del`	`int (const char *key)`	Delete a key

C2 messaging¶

Syscall	Signature	Purpose
`cmd_register`	`int (const char name, espm_cmd_handler_t handler, void module_ctx)`	Register a command (<= 31 chars)
`cmd_unregister`	`void (const char *name)`	Unregister (auto on stop)
`msg_info`	`bool (const char tag, const char msg, const char *request_id)`	Info message
`msg_result`	`bool (const char tag, const char msg, const char *request_id)`	Completion marker (mandatory)
`msg_error`	`bool (const char tag, const char msg, const char *request_id)`	Error message
`msg_data`	`bool (const char tag, const void data, size_t len, bool eof, const char *request_id)`	Binary data frame

Cellular / modem (GPRS builds)¶

Syscall	Signature	Purpose
`modem_at`	`int (const char cmd, char resp, size_t resp_len, uint32_t timeout_ms)`	Raw AT command
`modem_signal`	`int (int rssi_out, char oper_out)`	Signal quality and operator
`modem_sms_send`	`int (const char number, const char message)`	Send an SMS

Version field¶

espm_sys_t carries a uint32_t api_version field identifying the ABI revision. A module must be built against a matching ESPM version (v0.2.0) so its syscall layout lines up with the firmware.