Machine Level Interface

We have grouped here a number of routines that you can use to access your machine at a low-level.
With this low-level machine interface you can read and write to memory.
You can also set up your own machine language routines and call them.

Some of the routines listed below are unsafe, in the sense that phix cannot protect you if you use them incorrectly. You could crash your program or even your system.

Under Windows, the operating system will usually pop up a termination box giving a diagnostic message plus register information.
Under Linux you will typically get a segmentation violation.
To assist programmers in debugging code involving these unsafe routines, we have supplied [DEV (safe.e)] safe.e , an alternative to machine.e . If you copy euphoria\include\safe.e into the directory containing your program, and you rename safe.e as machine.e in that directory, your program will run using safer (but slower) versions of these low-level routines. safe.e can catch many errors, such as poking into a bad memory location. See the comments at the top of safe.e for complete instructions on how to use it. When using a package such as Win32Lib that does not use the allocate() function, you can only make limited use of safe.e .
These machine-level-interface routines are important because they allow phix programmers to access low-level features of the hardware and operating system.
For some applications this is essential.

Machine code routines can be written by hand, or taken from the disassembled output of a compiler for C or some other language. There are many examples of inline assembly needed for the phix runtime, perhaps the simplest of which is builtins\VM\pLen.e which implements the length() function. Remember that your machine code will be running in 32-bit protected mode. See demo\dos32\callmach.ex for an example.
peek - read one or more bytes from memory
poke - write one or more bytes to memory
mem_copy - copy a block of memory
mem_set - set a block of memory to a value
call - call a machine language routine
allocate - allocate a block of memory
free - deallocate a block of memory
allocate_string - allocate a string of characters with 0 terminator
register_block - register an externally-allocated block of memory
unregister_block - unregister an externally-allocated block of memory
int_to_bytes - convert an integer to 4 bytes
bytes_to_int - convert 4 bytes to an integer
int_to_bits - convert an integer to a sequence of bits
bits_to_int - convert a sequence of bits to an integer
atom_to_floatNN - convert an atom to a sequence of 4/8/10 bytes in IEEE 32/64/80-bit floating-point format
floatNN_to_atom - convert a sequence of 4/8/10 bytes in IEEE 32/64/80-bit floating-point format, to an atom
set_rand - set the random number generator so it will generate a repeatable series of random numbers
crash_file - specify the file for writing error diagnostics if phix detects an error in your program.
crash_message - specify a message to be printed if phix detects an error in your program