Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
executable file 600 lines (504 sloc) 21.9 KB
* This file is part of Espruino, a JavaScript interpreter for Microcontrollers
* Copyright (C) 2013 Gordon Williams <>
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at
* ----------------------------------------------------------------------------
* Misc utils and cheapskate stdlib implementation
* ----------------------------------------------------------------------------
#ifndef JSUTILS_H_
#define JSUTILS_H_
#include "platform_config.h"
#include <stddef.h>
#include <string.h>
#include <stdlib.h>
#include <stdarg.h> // for va_args
#include <stdint.h>
#include <stdbool.h>
#include <math.h>
#define JS_VERSION "2v13"
In code:
TODO - should be fixed
FIXME - will probably break if used
OPT - potential for speed optimisation
#define ESPR_NO_GET_SET 1
#ifndef alloca
#define alloca(x) __builtin_alloca(x)
#if defined(ESP8266)
// Use this in #ifdef to select flash/non-flash code
// For the esp8266 we need the posibility to store arrays in flash, because mem is so small
#define IN_FLASH_MEMORY __attribute__((section(".irom.literal"))) __attribute__((aligned(4)))
/** Place constant strings into flash when we can in order to save RAM space. Strings in flash
must be accessed with word reads on aligned boundaries, so we'll have to copy them before
regular use. */
#define FLASH_STR(name, x) static const char name[] IN_FLASH_MEMORY = x
/** FLASH_STRCMP compares a string in RAM with a string in FLASH (2nd arg) */
#define FLASH_STRCMP flash_strcmp
/// Get the length of a string in flash
size_t flash_strlen(const char *str);
/// Copy a string from flash to RAM
char *flash_strncpy(char *dest, const char *source, size_t cap);
/// memcopy a byte from flash to RAM
unsigned char *flash_memcpy(unsigned char *dest, const unsigned char *source, size_t cap);
/// Compare a string in memory with a string in flash
int flash_strcmp(const char *mem, const char *flash);
/** Read a uint8_t from this pointer, which could be in RAM or Flash.
On ESP8266 you have to read flash in 32 bit chunks, so force a 32 bit read
and extract just the 8 bits we want */
#define READ_FLASH_UINT8(ptr) ({ uint32_t __p = (uint32_t)(char*)(ptr); volatile uint32_t __d = *(uint32_t*)(__p & (uint32_t)~3); ((uint8_t*)&__d)[__p & 3]; })
/** Read a uint16_t from this pointer, which could be in RAM or Flash. */
#define READ_FLASH_UINT16(ptr) (READ_FLASH_UINT8(ptr) | (READ_FLASH_UINT8(((char*)ptr)+1)<<8) )
// On non-ESP8266, const stuff goes in flash memory anyway
#define FLASH_STR(name, x) static const char name[] = x
/** Read a uint8_t from this pointer, which could be in RAM or Flash.
On ARM this is just a standard read, it's different on ESP8266 */
#define READ_FLASH_UINT8(ptr) (*(uint8_t*)(ptr))
/** Read a uint16_t from this pointer, which could be in RAM or Flash.
On ARM this is just a standard read, it's different on ESP8266 */
#define READ_FLASH_UINT16(ptr) (*(uint16_t*)(ptr))
/** FLASH_STRCMP is simply strcmp, it's only special on ESP8266 */
#define FLASH_STRCMP strcmp
typedef uint64_t JsfWord;
typedef uint32_t JsfWord;
#if defined(ESP8266)
/** For the esp8266 we need to add CALLED_FROM_INTERRUPT to all functions that may execute at
interrupt time so they get loaded into static RAM instead of flash. We define
it as a no-op for everyone else. This is identical the ICACHE_RAM_ATTR used elsewhere. */
#define CALLED_FROM_INTERRUPT __attribute__((section(".iram1.text")))
#if defined(ESP32)
#include "esp_attr.h"
#define STRINGIFY_HELPER(x) #x
#define NOT_USED(x) ( (void)(x) )
#if !defined(__USB_TYPE_H) && !defined(CPLUSPLUS) && !defined(__cplusplus) // it is defined in this file too!
#undef FALSE
#undef TRUE
//typedef enum {FALSE = 0, TRUE = !FALSE} bool;
#define FALSE (0)
#define TRUE (1)
//typedef unsigned char bool;
#ifndef DBL_MIN
#define DBL_MIN 2.2250738585072014e-308
#ifndef DBL_MAX
#define DBL_MAX 1.7976931348623157e+308
/* Number of JS Variables allowed and JS Variable reference format.
There are (on 32 bit platforms):
* 4 bytes of data at the start
* 4 JsVarRef + 1 JsVarRefCounter
* 2 bytes of flags at the end
See comments after JsVar in jsvar.c for more info.
JsVarRef = uint8_t -> 12 bytes/JsVar so JSVAR_CACHE_SIZE = (RAM - 3000) / 12
JsVarRef = uint16_t -> 13->16 bytes/JsVar so JSVAR_CACHE_SIZE = (RAM - 3000) / 16
JsVarRef = uint32_t -> 20 bytes/JsVar so JSVAR_CACHE_SIZE = (RAM - 3000) / 20
NOTE: JSVAR_CACHE_SIZE must be at least 2 less than the number we can fit in JsVarRef
See jshardware.c FLASH constants - all this must be able to fit in flash
// Probably Linux - 32 bits allow us to allocate more blocks of variables,
// but is a lot less efficient with memory
typedef uint32_t JsVarRef;
typedef int32_t JsVarRefSigned;
#define JSVARREF_BITS 32
/** JsVarRaf stores References for variables - We treat 0 as null
* NOTE: we store JSVAR_DATA_STRING_* as actual values so we can do #if on them below
#if JSVAR_FORCE_16_BYTE // Forces full 16 bits used -> 16 bit JsVar
// This creates less (and faster) code for the Espruino interpreter,
// but isn't as efficient with memory.
#define JSVARREF_BITS 16
typedef uint16_t JsVarRef;
typedef int16_t JsVarRefSigned;
// Otherwise use just enough bits for everything we need. We set
// JSVARREF_BITS to enough for JSVAR_CACHE_SIZE, and then look at
// how much space is left over, and adjust JSVARREFCOUNT_BITS
// to fit in what is remaining
#elif JSVAR_CACHE_SIZE <= 254 // 12 bytes
#define JSVARREFCOUNT_PACK_BITS 8 // ensure we have enough space to store a 'double'. This is effectively just wasted space
typedef uint8_t JsVarRef;
typedef int8_t JsVarRefSigned;
#elif JSVAR_CACHE_SIZE <= 1023 // 12 bytes
#define JSVARREF_BITS 10
#define JSVARREFCOUNT_PACK_BITS 2 // ensure we have enough space to store a 'double'
#define JSVARREFCOUNT_BITS 6 // 48 - (10*4 + 2)
typedef uint16_t JsVarRef;
typedef int16_t JsVarRefSigned;
#elif JSVAR_CACHE_SIZE <= 2047 // 12 bytes
#define JSVARREF_BITS 11
#define JSVARREFCOUNT_BITS 4 // 48 - 11*4
typedef uint16_t JsVarRef;
typedef int16_t JsVarRefSigned;
#elif JSVAR_CACHE_SIZE <= 4095 // 13 bytes
#define JSVARREF_BITS 12
#define JSVARREFCOUNT_BITS 8 // 56 - 12*4
typedef uint16_t JsVarRef;
typedef int16_t JsVarRefSigned;
#elif JSVAR_CACHE_SIZE <= 8191 // 13 bytes
#define JSVARREF_BITS 13
#define JSVARREFCOUNT_BITS 4 // 56 - 13*4
typedef uint16_t JsVarRef;
typedef int16_t JsVarRefSigned;
#elif JSVAR_CACHE_SIZE <= 65535 // 16 bytes
#define JSVARREF_BITS 16
typedef uint16_t JsVarRef;
typedef int16_t JsVarRefSigned;
#error "Assuming 16 bit refs we can't go above 65534 elements"
#define JSVARREF_MIN (-(1<<(JSVARREF_BITS-1)))
#define JSVARREF_MAX ((1<<(JSVARREF_BITS-1))-1)
#if defined(__WORDSIZE) && __WORDSIZE == 64
// 64 bit needs extra space to be able to store a function pointer
/// Max length of JSV_NAME_ strings
/// Max length of JSV_NAME_ strings
/// Max length for a JSV_STRING, JsVar.varData.ref.refs (see comments under JsVar decl in jsvar.h)
/// Max length for a JSV_STRINGEXT, JsVar.varData.ref.lastChild (see comments under JsVar decl in jsvar.h)
In the above, ideally we'd just ask the compiler for the the address offset of the relevant
field, but because they are bitfields we can't get pointers to them!
/** This is the amount of characters at which it'd be more efficient to use
* a flat string than to use a normal string... */
// Sanity checks
typedef uint8_t JsVarRefCounter;
#error "Assumed JSVARREFCOUNT_BITS was 8 or less"
#pragma message "required length (bits) : 64"
#pragma message "initial data block length (bits) : " STRINGIFY(JSVAR_DATA_STRING_NAME_LEN*8)
#pragma message "3x refs plus packing (bits) : " STRINGIFY(JSVARREF_BITS*3 + JSVARREFCOUNT_PACK_BITS)
#error JsVarDataRef is not big enough to store a double value
typedef int32_t JsVarInt;
typedef uint32_t JsVarIntUnsigned;
typedef float JsVarFloat;
typedef double JsVarFloat;
typedef int64_t JsSysTime;
#define JSSYSTIME_INVALID ((JsSysTime)-1)
#define JSLEX_MAX_TOKEN_LENGTH 64 ///< Maximum length we allow tokens (eg. variable names) to be
#define JS_ERROR_TOKEN_BUF_SIZE 16 ///< see jslTokenAsString
#define JS_NUMBER_BUFFER_SIZE 70 ///< Enough for 64 bit base 2 + minus + terminating 0
#define JS_MAX_FUNCTION_ARGUMENTS 256 ///< How many arguments can be used with Function.apply
/* If we have less free variables than this, do a garbage collect on Idle.
* Note that the check for free variables takes an amount of time proportional
* to the size of JS_VARS_BEFORE_IDLE_GC */
// javascript specific names
#define JSPARSE_RETURN_VAR "return" // variable name used for returning function results
#define JSPARSE_PROTOTYPE_VAR "prototype"
#define JSPARSE_CONSTRUCTOR_VAR "constructor"
#define JSPARSE_INHERITS_VAR "__proto__"
// internal names that hopefully nobody will be able to access
#define JS_HIDDEN_CHAR '\xFF' // initial character of var name determines that we shouldn't see this stuff
#define JSPARSE_FUNCTION_CODE_NAME JS_HIDDEN_CHAR_STR"cod" // the function's code!
#define JSPARSE_FUNCTION_SCOPE_NAME JS_HIDDEN_CHAR_STR"sco" // the scope of the function's definition
#define JSPARSE_FUNCTION_THIS_NAME JS_HIDDEN_CHAR_STR"ths" // the 'this' variable - for bound functions
#define JSPARSE_FUNCTION_NAME_NAME JS_HIDDEN_CHAR_STR"nam" // for named functions (a = function foo() { foo(); })
#define JSPARSE_FUNCTION_LINENUMBER_NAME JS_HIDDEN_CHAR_STR"lin" // The line number offset of the function
#define JS_EVENT_PREFIX "#on"
#define JS_TIMEZONE_VAR "tz"
#define JS_GRAPHICS_VAR "gfx"
#define JSPARSE_EXCEPTION_VAR "except" // when exceptions are thrown, they're stored in the root scope
#define JSPARSE_STACKTRACE_VAR "sTrace" // for errors/exceptions, a stack trace is stored as a string
#if !defined(NO_ASSERT)
// Place assert strings into flash to save RAM
#define assert(X) do { \
FLASH_STR(flash_X, __STRING(X)); \
if (!(X)) jsAssertFail(__FILE__,__LINE__,flash_X); \
} while(0)
#elif defined(__STRING)
// Normal assert with string in RAM
#define assert(X) do { if (!(X)) jsAssertFail(__FILE__,__LINE__,__STRING(X)); } while(0)
// Limited assert due to compiler not being able to stringify a parameter
#define assert(X) do { if (!(X)) jsAssertFail(__FILE__,__LINE__,""); } while(0)
#define assert(X) do { } while(0)
/// Used when we have enums we want to squash down
#define PACKED_FLAGS __attribute__ ((__packed__))
/// Used before functions that we want to ensure are not inlined (eg. "void NO_INLINE foo() {}")
#define NO_INLINE __attribute__ ((noinline))
/// Put before functions that we always want inlined
#if defined(__GNUC__) && !defined(__clang__)
#if defined(LINK_TIME_OPTIMISATION) && !defined(SAVE_ON_FLASH) && !defined(DEBUG)
#define ALWAYS_INLINE __attribute__ ((gnu_inline)) __attribute__((always_inline)) inline
#define ALWAYS_INLINE __attribute__ ((gnu_inline)) inline
// clang seems to hate being asked to inline when the definition
// isn't in the same file
/// Maximum amount of locks we ever expect to have on a variable (this could limit recursion) must be 2^n-1
#define JSV_LOCK_MAX 15
/// preprocessor power of 2 - suitable up to 16 bits
#define NEXT_POWER_2(X) \
(((X) | (X)>>1 | (X)>>2 | (X)>>3 | \
(X)>>4 | (X)>>5 | (X)>>6 | (X)>>7 | \
(X)>>8 | (X)>>9 | (X)>>10 | (X)>>11 | \
(X)>>12 | (X)>>13 | (X)>>14 | (X)>>15)+1)
/// Proprocessor get bit number
#define GET_BIT_NUMBER(X) \
(((X)== 1)? 0: \
((X)== 2)? 1: \
((X)== 4)? 2: \
((X)== 8)? 3: \
((X)== 16)? 4: \
((X)== 32)? 5: \
((X)== 64)? 6: \
((X)== 128)? 7: \
((X)== 256)? 8: \
((X)== 512)? 9: \
((X)== 1024)?10: \
((X)== 2048)?11: \
((X)== 4096)?12: \
((X)== 8192)?13: \
((X)==16384)?14: \
// To handle variable size bit fields
#define BITFIELD_DECL(BITFIELD, N) uint32_t BITFIELD[((N)+31)/32]
#define BITFIELD_GET(BITFIELD, N) ((BITFIELD[(N)>>5] >> ((N)&31))&1)
#define BITFIELD_SET(BITFIELD, N, VALUE) (BITFIELD[(N)>>5] = (BITFIELD[(N)>>5]& (uint32_t)~(1 << ((N)&31))) | (uint32_t)((VALUE)?(1 << ((N)&31)):0) )
#define BITFIELD_CLEAR(BITFIELD) memset(BITFIELD, 0, sizeof(BITFIELD)) ///< Clear all elements
// Array of 4 bit values - returns unsigned
#define NIBBLEFIELD_DECL(BITFIELD, N) uint16_t BITFIELD[((N)+1)/2]
#define NIBBLEFIELD_GET(BITFIELD, N) ((BITFIELD[(N)>>1] >> (((N)&1)*4)) & 15)
#define NIBBLEFIELD_SET(BITFIELD, N, VALUE) (BITFIELD[(N)>>1] = (BITFIELD[(N)>>1]& (uint32_t)~(15 << (((N)&1)*4))) | (uint32_t)(((VALUE)&15) << (((N)&1)*4)) )
#define NIBBLEFIELD_CLEAR(BITFIELD) memset(BITFIELD, 0, sizeof(BITFIELD)) ///< Clear all elements
#if defined(NRF51_SERIES)
// Cortex-M0 does not support unaligned reads
#define UNALIGNED_UINT16(addr) ((((uint16_t)*((uint8_t*)(addr)+1)) << 8) | (*(uint8_t*)(addr)))
#define UNALIGNED_UINT16(addr) (*(uint16_t*)addr)
bool isWhitespace(char ch);
bool isNumeric(char ch);
bool isHexadecimal(char ch);
bool isAlpha(char ch);
bool isIDString(const char *s);
char charToUpperCase(char ch);
char charToLowerCase(char ch);
/** escape a character - if it is required. This may return a reference to a static array,
so you can't store the value it returns in a variable and call it again.
If jsonStyle=true, only string escapes supported by JSON are used */
const char *escapeCharacter(char ch, bool jsonStyle);
/** Parse radix prefixes, or return 0 */
int getRadix(const char **s, bool *hasError);
/// Convert a character to the hexadecimal equivalent (or -1)
int chtod(char ch);
/// Convert 2 characters to the hexadecimal equivalent (or -1)
int hexToByte(char hi, char lo);
/* convert a number in the given radix to an int */
long long stringToIntWithRadix(const char *s,
int forceRadix, //!< if radix=0, autodetect
bool *hasError, //!< If nonzero, set to whether there was an error or not
const char **endOfInteger //!< If nonzero, this is set to the point at which the integer finished in the string
/* convert hex, binary, octal or decimal string into an int */
long long stringToInt(const char *s);
// forward decl
struct JsLex;
// ------------
typedef enum {
} JsExceptionType;
void jsAssertFail(const char *file, int line, const char *expr);
#define DBG_INFO 0
#define DBG_VERBOSE 1
#if defined(DEBUG) || __FILE__ == DEBUG_FILE
#define jsDebug(dbg_type, format, ...) jsiConsolePrintf("[" __FILE__ "]:" format, ## __VA_ARGS__)
#define jsDebug(dbg_type, format, ...) do { } while(0)
#if (defined DEBUG ) || ( defined __FILE__ == DEBUG_FILE)
#define jsDebug(dbg_type, format, ...) jsiConsolePrintf("[" __FILE__ "]:" format, ## __VA_ARGS__)
#define jsDebug(dbg_type, format, ...) do { } while(0)
// Normal functions thet place format string in ram
void jsExceptionHere(JsExceptionType type, const char *fmt, ...);
void jsError(const char *fmt, ...);
void jsWarn(const char *fmt, ...);
// Special jsError and jsWarn functions that place the format string into flash to save RAM
#define jsExceptionHere(type, fmt, ...) do { \
FLASH_STR(flash_str, fmt); \
jsExceptionHere_flash(type, flash_str, ##__VA_ARGS__); \
} while(0)
void jsExceptionHere_flash(JsExceptionType type, const char *fmt, ...);
#define jsError(fmt, ...) do { \
FLASH_STR(flash_str, fmt); \
jsError_flash(flash_str, ##__VA_ARGS__); \
} while(0)
void jsError_flash(const char *fmt, ...);
#define jsWarn(fmt, ...) do { \
FLASH_STR(flash_str, fmt); \
jsWarn_flash(flash_str, ##__VA_ARGS__); \
} while(0)
void jsWarn_flash(const char *fmt, ...);
// ------------
/// Error flags for internal errors - update jswrap_espruino_getErrorFlags if you add to this
typedef enum {
JSERR_RX_FIFO_FULL = 1, ///< The IO buffer (ioBuffer in jsdevices.c) is full and data was lost. Happens for character data and watch events
JSERR_BUFFER_FULL = 2, ///< eg. Serial1's buffer exceeded the max size. Doesn't happen if you have an on('data') callback
JSERR_CALLBACK = 4, ///< A callback (on data/watch/timer) caused an error and was removed
JSERR_LOW_MEMORY = 8, ///< Memory is running low - Espruino had to run a garbage collection pass or remove some of the command history
JSERR_MEMORY = 16, ///< Espruino ran out of memory and was unable to allocate some data that it needed.
JSERR_MEMORY_BUSY = 32, ///< Espruino was busy doing something with memory (eg. garbage collection) so an IRQ couldn't allocate memory
JSERR_UART_OVERFLOW = 64, ///< A UART received data but it was not read in time and was lost
JSERR_WARNINGS_MASK = JSERR_LOW_MEMORY ///< Issues that are warnings, not actual problems
} PACKED_FLAGS JsErrorFlags;
/** Error flags for things that we don't really want to report on the console,
* but which are good to know about */
extern volatile JsErrorFlags jsErrorFlags;
/** Convert a string to a JS float variable where the string is of a specific radix. */
JsVarFloat stringToFloatWithRadix(
const char *s, //!< The string to be converted to a float
int forceRadix, //!< The radix of the string data, or 0 to guess
const char **endOfFloat //!< If nonzero, this is set to the point at which the float finished in the string
/** convert a string to a floating point JS variable. */
JsVarFloat stringToFloat(const char *str);
void itostr_extra(JsVarInt vals,char *str,bool signedVal,unsigned int base); // like itoa, but uses JsVarInt (good on non-32 bit systems)
static ALWAYS_INLINE void itostr(JsVarInt val,char *str,unsigned int base) {
itostr_extra(val, str, true, base);
char itoch(int val);
// super ftoa that does fixed point and radix
void ftoa_bounded_extra(JsVarFloat val,char *str, size_t len, int radix, int fractionalDigits);
// normal ftoa with bounds checking
void ftoa_bounded(JsVarFloat val,char *str, size_t len);
/// Wrap a value so it is always between 0 and size (eg. wrapAround(angle, 360))
JsVarFloat wrapAround(JsVarFloat val, JsVarFloat size);
typedef void (*vcbprintf_callback)(const char *str, void *user_data);
* Espruino-special printf with a callback.
* The supported format specifiers are:
* * `%d` = int
* * `%0#d` or `%0#x` = int padded to length # with 0s
* * `%x` = int as hex
* * `%L` = JsVarInt
* * `%Lx`= JsVarInt as hex
* * `%f` = JsVarFloat
* * `%s` = string (char *)
* * `%c` = char
* * `%v` = JsVar * (doesn't have to be a string - it'll be converted)
* * `%q` = JsVar * (in quotes, and escaped)
* * `%Q` = JsVar * (in quotes, and escaped the JSON subset of escape chars)
* * `%j` = Variable printed as JSON
* * `%t` = Type of variable
* * `%p` = Pin
* Anything else will assert
void vcbprintf(vcbprintf_callback user_callback, void *user_data, const char *fmt, va_list argp);
/// This one is directly usable..
void cbprintf(vcbprintf_callback user_callback, void *user_data, const char *fmt, ...);
/// a snprintf replacement so mbedtls doesn't try and pull in the whole stdlib to cat two strings together
int espruino_snprintf_va( char * s, size_t n, const char * fmt, va_list argp );
/// a snprintf replacement so mbedtls doesn't try and pull in the whole stdlib to cat two strings together
int espruino_snprintf( char * s, size_t n, const char * fmt, ... );
//#define RAND_MAX (0x7FFFFFFFU) // needs to be unsigned!
/// a rand() replacement that doesn't need malloc (!!!)
int rand();
/// a rand() replacement that doesn't need malloc (!!!)
void srand(unsigned int seed);
/// Clip X between -128 and 127
char clipi8(int x);
/// Convert the given value to a signed integer assuming it has the given number of bits
int twosComplement(int val, unsigned char bits);
/// quick integer square root
unsigned short int int_sqrt32(unsigned int x);
/** get the amount of free stack we have, in bytes */
size_t jsuGetFreeStack();
#ifdef ESP32
void *espruino_stackHighPtr; //Used by jsuGetFreeStack
#endif /* JSUTILS_H_ */