test

OpenBoot 3.x Command Reference Manual

Virtual Memory

The User Interface provides interactive commands for examining and setting memory. With it, you can:

Memory operators let you read from and write to any memory location. All memory addresses shown in the examples that follow are virtual addresses.

A variety of 8-bit, 16-bit, and 32-bit (and in some systems, 64-bit) operations are provided. In general, a c (character) prefix indicates an 8-bit (one byte) operation; a w (word) prefix indicates a 16-bit (doublet) operation; an l (longword) prefix indicates a 32-bit (quadlet) operation; and an x prefix indicates a 64-bit (octlet) operation.

waddr, qaddr, and oaddr indicate addresses with alignment restrictions. For example, qaddr indicates 32-bit (4 byte) alignment; on many systems such an address must be a multiple of 4, as shown in the following example: 

ok 4028 l@ 
ok 4029 l@ 
Memory address not aligned 
ok

Forth, as implemented in OpenBoot, adheres closely to the ANS Forth Standard. If you explicitly want a 16-bit fetch, a 32-bit fetch or (on some systems) a 64-bit fetch, use w@, l@ or x@ instead of @. Other memory and device register access commands also follow this convention.

Table 4-11 lists commands used to access memory.

Table 4-11 Memory Access Commands

Command  

Stack Diagram 

Description 
!

( x a-addr -- ) 

Store a number at a-addr.
+!

( nu a-addr -- ) 

Add nu to the number stored at a-addr.
@

( a-addr -- x ) 

Fetch a number from a-addr.
2!

( x1 x2 a-addr -- ) 

Store 2 numbers at a-addr, x2 at lower address.
2@

( a-addr -- x1 x2 )  

Fetch 2 numbers from a-addr, x2 from lower address.
blank

( addr len -- ) 

Set len bytes of memory beginning at addr to the space character (decimal 32).
c!

( byte addr -- ) 

Store byte at addr.
c@

( addr -- byte ) 

Fetch a byte from addr.
cpeek

( addr -- false | byte true ) 

Attempt to fetch the byte at addr. Return the data and true if the access was successful. Return false if a read access error occurred.
cpoke

( byte addr -- okay? ) 

Attempt to store the byte to addr. Return true if the access was successful. Return false if a write access error occurred.
comp

( addr1 addr2 len -- diff? ) 

Compare two byte arrays. diff? is 0 if the arrays are identical, diff? is -1 if the first byte that is different is lesser in the string at addr1, diff? is 1 otherwise.
dump

( addr len -- ) 

Display len bytes of memory starting at addr.
erase

( addr len -- ) 

Set len bytes of memory beginning at addr to 0.
fill

( addr len byte -- ) 

Set len bytes of memory beginning at addr to the value byte.
l!

( q qaddr -- ) 

Store a quadlet q at qaddr.
l@

( qaddr -- q ) 

Fetch a quadlet q from qaddr.
lbflips

( qaddr len -- ) 

Reverse the bytes in each quadlet in the specified region. 
lwflips

( qaddr len -- ) 

Swap the doublets in each quadlet in specified region. 
lpeek

( qaddr -- false | quad true ) 

Attempt to fetch the quadlet at qaddr. Return the data and true if the access was successful. Return false if a read access error occurred.
lpoke

( q qaddr -- okay? ) 

Attempt to store the quadlet 8 at qaddr. Return true if the access was successful. Return false if a a write access error occurred.
move

( src-addr dest-addr len -- ) 

Copy len bytes from src-addr to dest-addr.
off

( a-addr -- ) 

Store false at a-addr.
on

( a-addr -- ) 

Store true at a-addr.
unaligned-l!

( q addr -- ) 

Store a quadlet q, any alignment
unaligned-l@

( addr -- q ) 

Fetch a quadlet q, any alignment.
unaligned-w!

( w addr -- ) 

Store a doublet w, any alignment.
unaligned-w@

( addr -- w ) 

Fetch a doublet w, any alignment.
w!

( w waddr -- ) 

Store a doublet w at waddr.
w@

( waddr -- w) 

Fetch a doublet w from waddr.
<w@

( waddr -- n ) 

Fetch doublet n from waddr, sign-extended.
wbflips

( waddr len -- ) 

Swap the bytes in each doublet in the specified region. 
wpeek

( waddr -- false | w true ) 

Attempt to fetch the doublet w at waddr. Return the data and true if the access was successful. Return false if a read access error occurred.
wpoke

( w waddr -- okay? ) 

Attempt to store the doublet w to waddr. Return true if the access was successful. Return false if a write access error occurred.

The memory access commands listed in Table 4-12 are available only on 64-bit OpenBoot implementations.

Table 4-12 64-Bit Memory Access Functions

Command 

Stack Diagram 

Description 
<l@

( qaddr -- n ) 

Fetch quadlet from qaddr, sign-extended. 
x@

( oaddr -- o ) 

Fetch octlet from an octlet aligned address. 
x!

( o oaddr -- ) 

Store octlet to an octlet aligned address. 

xbflips

( oaddr len -- ) 

Reverse the bytes in each octlet in the given region.The behavior is undefined if len is not a multiple of /x.

xlflips

( oaddr len -- ) 

Reverse the quadlets in each octlet in the given region. The bytes in each quadlet are not reversed. The behavior is undefined if len is not a multiple of /x.

xwflips

( oaddr len -- ) 

Reverse the doublets in each octlet in the given region. The bytes in each doublet are not reversed. The behavior is undefined if len is not a multiple of /x.

The dump command is particularly useful. It displays a region of memory as both bytes and ASCII values. The example below displays the contents of 20 bytes of memory starting at virtual address 10000. 

ok 10000 20 dump						
(Display 20 bytes of memory starting at virtual address
10000)
       \/ 1  2  3  4  5  6  7   8  9  a  b  c  d  e  f  v123456789abcdef
 10000 05 75 6e 74 69 6c 00 40  4e d4 00 00 da 18 00 00 .until.@NT..Z...
 10010 ce da 00 00 f4 f4 00 00  fe dc 00 00 d3 0c 00 00 NZ..tt..~\..S...
ok

Some implementations support variants of dump that display memory as 16-, 32- and 64-bit values. You can use sifting dump (see "Searching the Dictionary") to find out if your system has such variants.

If you try to access an invalid memory location (with @, for example), the operation may abort and display an error message, such as Data Access Exception or Bus Error.

Table 4-13 lists memory mapping commands.

Table 4-13 Memory Mapping Commands

Command 

Stack Diagram 

Description 
alloc-mem

( len -- a-addr ) 

Allocate len bytes of memory; return the virtual address.
free-mem

( a-addr len -- ) 

Free memory allocated by alloc-mem.

The following screen is an example of the use of alloc-mem and free-mem.