The <peekpoke.h> header file


  
This header file contains the following functions:
peek                peek_l              peek_w              peekIO
peekIO_w            poke                poke_l              poke_w
pokeIO              pokeIO_w            speek               speek_l
speek_w

Functions


void poke (any_type addr, unsigned char byte);

Stores a byte in the memory.

poke is a macro which stores a byte byte at the address addr into the memory, where addr need not to be necessary a pointer. Instead, it can be of any type (usually an integer) which may represent a memory address in a sensible way. So, it allows storing bytes into the memory using the style which is common in most dialects of BASIC language. For example, to store a byte 255 at the first byte of the video memory, do this:
poke (0x4C00, 255);
NOTE: Do not use poke for sending bytes to I/O ports! Use pokeIO instead.

void pokeIO (any_type addr, unsigned char byte);

Sends a byte to an I/O port.

poke is not reliable when sending data to memory-mapped I/O ports. Suppose that you have a device mapped on the address port, and that this device requests sending a sequence ot bytes 127,0,255,0 to this address to be reset. If you simply try to do
poke (port, 127);
poke (port, 0);
poke (port, 255);
poke (port, 0);
the compiler will (incorrectly) conclude that sending a sequence of bytes to the same address is a nonsense, because the new value will overwrite the previous one (assuming that the address points to a memory), so the optimizer will ignore all stores but the last one. Such behaviour is correct when port is a normal memory address, but it is not correct when port is an address of a memory-mapped I/O port. To prevent such behaviour, use pokeIO instead of poke, i.e. write
pokeIO (port, 127);
pokeIO (port, 0);
pokeIO (port, 255);
pokeIO (port, 0);
Basically, pokeIO works exactly like poke, but prevents any unwanted optimizations generated by the compiler. It may be used even for storing bytes into the memory, but poke will generate better code when working with memory.

void poke_w (any_type addr, unsigned short word);

Stores a word in the memory.

poke_w is like poke, but stores a word into the memory instead of a byte.

void pokeIO_w (any_type addr, unsigned short word);

Sends a word to an I/O port.

pokeIO_w is like pokeIO, but sends a word to the I/O port instead of a byte.

void poke_l (any_type addr, unsigned long dword);

Stores a double word in the memory.

poke_l is like poke, but stores a double word into the memory instead of a byte.

unsigned char peek (any_type addr);

Fetch a byte from the memory.

peek is a macro which fetchs a byte byte from the address addr into the memory, where addr need not to be necessary a pointer. Instead, it can be of any type (usually an integer) which may represent a memory address in a sensible way. So, it allows fetching bytes from the memory using the style which is common in most dialects of BASIC language. For example, to read a first byte from the video memory, do this:
byte = peek (0x4C00);
NOTE: Do not use peek for reading I/O ports! Use peekIO instead.

unsigned char peekIO (any_type addr);

Reads a byte from an I/O port.

peek is not reliable when reading data memory-mapped I/O ports. For example, suppose that the user wants to wait until the programable timer on the TI-89 (its vaule may be read from the address 0x600017) reaches value 255. The following construction seems quite good:
while (peek (0x600017) != 255);
However, it will cause an infinity loop. Namely, the compiler will notice that the same value is read in the loop. As normal memory location can not be changed without explicite writing to it, and there is nothing in the loop which changes address 0x600017, the optimizer will move memory reading out of the loop to make the code more efficient. Such behaviour is correct for ordinary memory locations. But, the compiler does not know anything about the fact that 0x600017 is not an ordinary memory location but an I/O port, which may be changed unpredictably (purely by the hardware, without any program control). To prevent such behaviour, use peekIO instead of peek, i.e. write
while (peek (0x600017) != 255);
Basically, peekIO works exactly like peek, but prevents any unwanted optimizations generated by the compiler. Always use peekIO for reading memory-mapped I/O ports, else you may have troubles (especially in short loops). For example, to read the keyboard column mask on TI-89, do
key_mask = peekIO (0x60001B);
peekIO may be used even for reading bytes into the memory, but peek will generate better code when working with memory. However, use peekIO to read any memory location which may change on a way which is unpredictable from the aspect of a normal program flow (for example, a memory location which is changed in the body of the interrupt handler).

unsigned short peek_w (any_type addr);

Fetch a word from the memory.

peek_w is like peek, but fetches a word from the memory instead of a byte.

NOTE: Do not use peek_w for reading I/O ports! Use peekIO_w instead.

unsigned short peekIO_w (any_type addr);

Reads a word from an I/O port.

peekIO_w is like peekIO, but reads a word from the I/O port instead of a byte.

unsigned long peek_l (any_type addr);

Fetch a double word from the memory.

peek_l is like peek, but fetches a double word from the memory instead of a byte.

char speek (any_type addr);

Fetch a signed byte from the memory.

speek is like peek, but the result is interpreted as a signed byte.

short speek_w (any_type addr);

Fetch a signed word from the memory.

speek_w is like peek_w, but the result is interpreted as a signed word.

long speek_l (any_type addr);

Fetch a signed double word from the memory.

speek_l is like peek_l, but the result is interpreted as a signed double word.

Return to the main index