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

Fields

Modifier and Type	Field and Description
protected boolean	byteSwapEnabled_ Inidicates whether or not byte swapping is required.

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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.

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.

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.

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.

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.

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.

Method Detail

getByte

public byte getByte(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

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

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.

Parameters:

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

Returns:

the byte read.

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.

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.

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.

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.

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.

Parameters:

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

Returns:

the int read.

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.

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.

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.

getLong

public long getLong(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

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

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.

Parameters:

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

Returns:

the long read.

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.

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.

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.

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.

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.

Parameters:

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

Returns:

the short read.

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.

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.

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.

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.

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.

Parameters:

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

value - the value to be written.

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.

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.

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.

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.

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.

Parameters:

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

value - the int to be written.

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.

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.

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.

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.

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.

Parameters:

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

value - the long to be written.

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.

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.

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.

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.

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.

Parameters:

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

value - the short to be written.

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.

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.

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.

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.

Throws:

OutOfMemoryError - if there is insufficient virtual address space.

Returns:

the starting address of the virtual memory range.

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.

Throws:

OutOfMemoryError - if there is insufficient virtual address space.

IllegalArgumentException - if base is not a valid virtual address.

Parameters:

base - the desired address.

Returns:

the starting address of the virtual memory range.

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.

Throws:

IllegalArgumentException - if base is not a valid virtual address.

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.

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)