javax.realtime
Class RawMemoryAccess

java.lang.Object
  javax.realtime.RawMemoryAccess

Direct Known Subclasses:

RawMemoryFloatAccess

public class RawMemoryAccess
extends Object

Jamaica Real-Time Specification for Java class RawMemoryAccess.

This class enables the low-level access of a range of physical memory as a sequence of bytes. This class permits the development of device drivers using memory-mapped I/ O, flash memory, battery-backed RAM, etc.

The memory can be accessed as primitive types byte, short, int, long, or as arrays of these primitive types. No non-primitive types (Java references or Java objects) can be stored in this memory since this would undermine Java's inherent type safety for references and objects.

The byte ordering on accesses to the memory depends on the current setting of RealtimeSystem.BYTE_ORDER.

For access to some memory areas, such as parallel port, superuser privileges may be required - otherwise values read from the memory will always be zero.

Field Summary

protected boolean

byteSwapEnabled_ Inidicates whether or not byte swapping is required.

Constructor Summary

RawMemoryAccess(Object type, long size)
Constructor to create an instance of RawMemoryAccess for the given parameters and make this memory accessible.

RawMemoryAccess(Object type, long base, long size)
Constructor to create an instance of RawMemoryAccess for the given parameters and make this memory accessible.

Method Summary

byte	getByte(long offset) getByte reads a byte from the given offset in an atomic read operation.
void	getBytes(long offset, byte[] bytes, int low, int number) getBytes reads a number of bytes from the given offset.
int	getInt(long offset) getInt reads an int from the given offset.
void	getInts(long offset, int[] ints, int low, int number) getInts reads a number of ints from the given offset.
long	getLong(long offset) getLong reads a long from the given offset.
void	getLongs(long offset, long[] longs, int low, int number) getLongs reads a number of longs from the given offset.
long	getMappedAddress() getMappedAddress returns the virtual address where this memory region is mapped.
short	getShort(long offset) getShort reads a short from the given offset.
void	getShorts(long offset, short[] shorts, int low, int number) getShorts reads a number of shorts from the given offset.
long	map() map maps the physical memory into virtual memory.
long	map(long base) map maps the physical memory into virtual memory at the given base address.
long	map(long base, long size) map maps the physical memory into virtual memory at the given base address.
void	setByte(long offset, byte value) setByte writes a byte to the given offset.
void	setBytes(long offset, byte[] bytes, int low, int number) setBytes writes a number of bytes to the given offset.
void	setInt(long offset, int value) setInt writes an int to the given offset.
void	setInts(long offset, int[] ints, int low, int number) setInts writes a number of ints to the given offset.
void	setLong(long offset, long value) setLong writes a long to the given offset.
void	setLongs(long offset, long[] longs, int low, int number) setLongs writes a number of longs to the given offset.
void	setShort(long offset, short value) setShort writes a short to the given offset.
void	setShorts(long offset, short[] shorts, int low, int number) setShorts writes a number of shorts to the given offset.
protected int	swapBytes(int value)
protected long	swapBytes(long value)
protected short	swapBytes(short value)
void	unmap() unmap unmaps this range from virtual memory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

byteSwapEnabled_

protected boolean byteSwapEnabled_

Inidicates whether or not byte swapping is required.

Constructor Detail

RawMemoryAccess

public RawMemoryAccess(Object type,
                       long base,
                       long size)
                throws SecurityException,
                       OffsetOutOfBoundsException,
                       SizeOutOfBoundsException,
                       UnsupportedPhysicalMemoryException,
                       MemoryTypeConflictException,
                       OutOfMemoryError

Constructor to create an instance of RawMemoryAccess for the given parameters and make this memory accessible.

JamaicaVM currently does not support virtual memory, so no mapping of the specified memory will be performed by this constructor.

Parameters:

type - The type of the memory (e.g., PhysicalMemoryManager.DMA, etc). This may be an array of types if several type attributes are required. type may be null if any memory type is acceptable.

base - the base address of the range.

size - the size of the range.

Throws:

SecurityException - If the application is not allowed to access the specified range of memory or memory type.

SizeOutOfBoundsException - iff size is negative or base plus size extends into an illegal memory range.

OffsetOutOfBoundsException - iff base is invalid.

UnsupportedPhysicalMemoryException - If the specified memory type is not supported.

MemoryTypeConflictException - If the memory at the specified base address is incompatible with the attributes specified in the type parameter.

OutOfMemoryError - If there is no memory of the specified type available.

RawMemoryAccess

public RawMemoryAccess(Object type,
                       long size)
                throws SecurityException,
                       OffsetOutOfBoundsException,
                       SizeOutOfBoundsException,
                       UnsupportedPhysicalMemoryException,
                       MemoryTypeConflictException,
                       OutOfMemoryError

Constructor to create an instance of RawMemoryAccess for the given parameters and make this memory accessible.

The base address will be chosen freely by the implementation.

Parameters:

type - The type of the memory (e.g., PhysicalMemoryManager.DMA, etc). This may be an array of types if several type attributes are required. type may be null if any memory type is acceptable.

size - the size of the range.

Throws:

SecurityException - if the application is not allowed to access physical memory or memory of the specified type.

SizeOutOfBoundsException - iff size is negative or base plus size extends into an illegal memory range.

OffsetOutOfBoundsException - iff base is invalid.

UnsupportedPhysicalMemoryException - if the specified memory type is not supported.

MemoryTypeConflictException - if the memory at the specified base address is incompatible with the attributes specified in the type parameter.

OutOfMemoryError - if there is no memory of the specified type available.

Method Detail

getByte

public byte getByte(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

getByte reads a byte from the given offset in an atomic read operation.

Parameters:

offset - the offset of the byte from the beginning of this memory range.

Returns:

the byte read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - If offset is negative or greater than the size of the raw memory area.

getBytes

public void getBytes(long offset,
                     byte[] bytes,
                     int low,
                     int number)
              throws OffsetOutOfBoundsException,
                     SizeOutOfBoundsException

getBytes reads a number of bytes from the given offset. Each byte is read in an atomic read operation, several bytes may be read in one single atomic read.

Parameters:

offset - the offset of the bytes from the beginning of this memory range.

bytes - (out!) an array to hold the read bytes.

low - offset in bytes array where the first value is stored.

number - number of bytes to be read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= bytes.length or (low + number) < 0.

IllegalArgumentException - if bytes is null or number < 0.

getInt

public int getInt(long offset)
           throws OffsetOutOfBoundsException,
                  SizeOutOfBoundsException

getInt reads an int from the given offset. If naturally aligned, the int is read in an atomic read operation. If not aligned, the read may be not atomic.

Parameters:

offset - the offset of the first byte from the beginning of this memory range.

Returns:

the int read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

getInts

public void getInts(long offset,
                    int[] ints,
                    int low,
                    int number)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

getInts reads a number of ints from the given offset. If naturally aligned, each int is read in an atomic read operation. If not aligned, the read may be not atomic.

Parameters:

offset - the offset of the ints from the beginning of this memory range.

ints - (out!) an array to hold the read ints.

low - offset in ints array where the first value is stored.

number - number of ints to be read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= ints.length or (low + number) < 0.

IllegalArgumentException - if ints is null or number < 0.

getLong

public long getLong(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

getLong reads a long from the given offset. The read may be not atomic.

Parameters:

offset - the offset of the first byte from the beginning of this memory range.

Returns:

the long read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

getLongs

public void getLongs(long offset,
                     long[] longs,
                     int low,
                     int number)
              throws OffsetOutOfBoundsException,
                     SizeOutOfBoundsException

getLongs reads a number of longs from the given offset. The reads may be not atomic.

Parameters:

offset - the offset of the longs from the beginning of this memory range.

longs - (out!) an array to hold the read longs.

low - offset in longs array where the first value is stored.

number - number of longs to be read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= longs.length or (low + number) < 0.

IllegalArgumentException - if longs is null or number < 0.

getShort

public short getShort(long offset)
               throws OffsetOutOfBoundsException,
                      SizeOutOfBoundsException

getShort reads a short from the given offset. If naturally aligned, the short is read in an atomic read operation. If not aligned, the read may be not atomic.

Parameters:

offset - the offset of the first byte from the beginning of this memory range.

Returns:

the short read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

getShorts

public void getShorts(long offset,
                      short[] shorts,
                      int low,
                      int number)
               throws OffsetOutOfBoundsException,
                      SizeOutOfBoundsException

getShorts reads a number of shorts from the given offset. If naturally aligned, each short is read in an atomic read operation. If not aligned, the read may be not atomic.

Parameters:

offset - the offset of the shorts from the beginning of this memory range.

shorts - (out!) an array to hold the read shorts.

low - offset in shorts array where the first value is stored.

number - number of shorts to be read.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= shorts.length or (low + number) < 0.

IllegalArgumentException - if shorts is null or number < 0.

setByte

public void setByte(long offset,
                    byte value)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

setByte writes a byte to the given offset. This write may require a read of the neighboring bytes and may have unspecified effects on concurrently performed writes to this byte or neighboring bytes.

Parameters:

offset - the offset of the byte from the beginning of this memory range.

value - the value to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

setBytes

public void setBytes(long offset,
                     byte[] bytes,
                     int low,
                     int number)
              throws OffsetOutOfBoundsException,
                     SizeOutOfBoundsException

setBytes writes a number of bytes to the given offset. This write may require a read of the neighboring bytes and may have unspecified effects on concurrently performed writes to the bytes or neighboring bytes.

Parameters:

offset - the offset of the bytes from the beginning of this memory range.

bytes - an array that holds the bytes to be written.

low - offset in bytes array where the first value to be written will be taken from.

number - number of bytes to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= bytes.length or (low + number) < 0.

IllegalArgumentException - if bytes is null or number < 0.

setInt

public void setInt(long offset,
                   int value)
            throws OffsetOutOfBoundsException,
                   SizeOutOfBoundsException

setInt writes an int to the given offset. If naturally aligned, the int will be written in an atomic read operation on most processor architectures, but this behavior is not required.

Parameters:

offset - the offset of the first byte from the beginning of this memory range.

value - the int to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

setInts

public void setInts(long offset,
                    int[] ints,
                    int low,
                    int number)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

setInts writes a number of ints to the given offset. If naturally aligned, the ints will be written in an atomic read operation on most processor architectures, but this behavior is not required.

Parameters:

offset - the offset of the ints from the beginning of this memory range.

ints - an array that holds the ints to be written.

low - offset in ints array where the first value to be written will be taken from.

number - number of ints to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= ints.length or (low + number) < 0.

IllegalArgumentException - if ints is null or number < 0.

setLong

public void setLong(long offset,
                    long value)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

setLong writes a long to the given offset. The write may be not atomic.

Parameters:

offset - the offset of the first byte from the beginning of this memory range.

value - the long to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

setLongs

public void setLongs(long offset,
                     long[] longs,
                     int low,
                     int number)
              throws OffsetOutOfBoundsException,
                     SizeOutOfBoundsException

setLongs writes a number of longs to the given offset. The writes may be not atomic.

Parameters:

offset - the offset of the longs from the beginning of this memory range.

longs - an array that holds the longs to be written.

low - offset in longs array where the first value to be written will be taken from.

number - number of longs to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= longs.length or (low + number) < 0.

IllegalArgumentException - if longs is null or number < 0.

setShort

public void setShort(long offset,
                     short value)
              throws OffsetOutOfBoundsException,
                     SizeOutOfBoundsException

setShort writes a short to the given offset. This write may require a read of the neighboring bytes and may have unspecified effects on concurrently performed writes to this byte or neighboring bytes.

Parameters:

offset - the offset of the first byte from the beginning of this memory range.

value - the short to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

setShorts

public void setShorts(long offset,
                      short[] shorts,
                      int low,
                      int number)
               throws OffsetOutOfBoundsException,
                      SizeOutOfBoundsException

setShorts writes a number of shorts to the given offset. The writes may be not atomic.

Parameters:

offset - the offset of the shorts from the beginning of this memory range.

shorts - an array that holds the shorts to be written.

low - offset in shorts array where the first value to be written will be taken from.

number - number of shorts to be written.

Throws:

SizeOutOfBoundsException - if this is not mapped or offset specifies an address in an invalid address range.

OffsetOutOfBoundsException - if offset is negative or greater than the size of the raw memory area.

ArrayIndexOutOfBoundsException - if low < 0 or (low + number) >= shorts.length or (low + number) < 0.

IllegalArgumentException - if shorts is null or number < 0.

getMappedAddress

public long getMappedAddress()

getMappedAddress returns the virtual address where this memory region is mapped.

Returns:

the virtual address.

map

public long map()

map maps the physical memory into virtual memory. For JamaicaVM, this is a no-op since virtual memory is not supported.

Returns:

the starting address of the virtual memory range.

Throws:

OutOfMemoryError - if there is insufficient virtual address space.

map

public long map(long base)

map maps the physical memory into virtual memory at the given base address. For JamaicaVM, this is a no-op since virtual memory is not supported.

Parameters:

base - the desired address.

Returns:

the starting address of the virtual memory range.

Throws:

OutOfMemoryError - if there is insufficient virtual address space.

IllegalArgumentException - if base is not a valid virtual address.

map

public long map(long base,
                long size)

map maps the physical memory into virtual memory at the given base address. For JamaicaVM, this is a no-op since virtual memory is not supported.

Parameters:

base - the desired address.

size - The size of the mapped block. If this is smaller than the size of this RawMemoryAccess instance, then any accesses to memory after size will cause SizeOutOfBoundsException.

Returns:

the starting address of the virtual memory range.

Throws:

IllegalArgumentException - if base is not a valid virtual address.

unmap

public void unmap()

unmap unmaps this range from virtual memory. If the platform supports virtual memory, this frees the corresponding virtual memory address range.

If this is already unmapped, this operation is a nop.

While a raw memory object is unmapped, all accesses via set* or get* methods will result in a SizeOutOfBoundsException.

swapBytes

protected short swapBytes(short value)

swapBytes

protected int swapBytes(int value)

swapBytes

protected long swapBytes(long value)