javax.realtime
Class RawMemoryAccess

java.lang.Object
  |
  +--javax.realtime.RawMemoryAccess

Direct Known Subclasses:

RawMemoryFloatAccess

public class RawMemoryAccess

extends java.lang.Object

An instance of RawMemoryAccess models a range of physical memory as a fixed sequence of bytes. A full complement of accessor methods allow the contents of the physical area to be accessed through offsets from the base, interpreted as byte, short, int, or long data values or as arrays of these types.

Whether the offset addresses the high-order of low-order byte is based on the value of the BYTE_ORDER static boolean variable in class RealtimeSystem. The RawMemoryAccess class allows a real-time program to implement device drivers, memory-mapped I/O, flash memory, battery-backed RAM, and similar low-level software.

A raw memory area cannot contain references to Java objects. Such a capability would be unsafe (since it could be used to defeat Java's type checking) and error-prone (since it is sensitive to the specific representational choices made by the Java compiler).

Many of the constructors and methods in this class throw OffsetOutOfBoundsException. This exception means that the value given in the offset parameter is either negative or outside the memory area.

Many of the constructors and methods in this class throw SizeOutOfBoundsException. This exception means that the value given in the size parameter is either negative, larger than an allowable range, or would cause an accessor method to access an address outside of the memory area.

Unlike other integral parameters in this chapter, negative values are valid for byte, short, int and long values that are copied in and out of memory by the set and get methods of this class.

Field Summary

private long	base
private java.lang.Runnable	logic
private long	size

Constructor Summary

protected	RawMemoryAccess(long base, long size)
	RawMemoryAccess(java.lang.Object type, long size) Construct an instance of RawMemoryAccess with the given parameters.
	RawMemoryAccess(java.lang.Object type, long base, long size) Construct an instance of RawMemoryAccess with the given parameters.
protected	RawMemoryAccess(javax.realtime.RawMemoryAccess memory, long base, long size) Constructor reserved for use by the memory object factory.

Method Summary

static javax.realtime.RawMemoryAccess	create(java.lang.Object type, long size)
static javax.realtime.RawMemoryAccess	create(java.lang.Object type, long base, long size)
byte	getByte(long offset) Get the byte at the given offset.
void	getBytes(long offset, byte[] bytes, int low, int number) Gets nunber bytes starting at the given offset and assign them to the byte array starting at the position low.
int	getInt(long offset) Gets the int at the given offset.
void	getInts(long offset, int[] ints, int low, int number) Gets number ints starting at the given offset and assign them to the int array passed at position low.
long	getLong(long offset) Gets the long at the given offset.
void	getLongs(long offset, long[] longs, int low, int number) Gets number longs starting at the given offset and assign them to the long array passed starting at position low.
long	getMappedAddress() Gets the virtual memory location at which the memory region is mapped.
short	getShort(long offset) Gets the short at the given offset.
void	getShorts(long offset, short[] shorts, int low, int number) Gets number shorts starting at the give offset and assign them to the short array passed starting at position low.
long	map() Maps the physical memory range into virtual memory.
long	map(long base) Maps the physical memory range into virtual memory at the specified location.
long	map(long base, long size) Maps the physical memory range into virtual memory.
void	setByte(long offset, byte value) Sets the byte at the given offset.
void	setBytes(long offset, byte[] bytes, int low, int number) Sets number bytes starting at the give offset from the byte array passed starting at position low.
void	setInt(long offset, int value) Sets the int at the given offset.
void	setInts(long offset, int[] ints, int low, int number) Sets number ints starting at the given offset from the int array passed starting at position low.
void	setLong(long offset, long value) Sets the long at the given offset.
void	setLongs(long offset, long[] longs, int low, int number) Sets number longs starting at the given offset from the long array passed starting at position low.
void	setShort(long offset, short value) Sets the short at the given offset.
void	setShorts(long offset, short[] shorts, int low, int number) Sets number shorts starting at the given offset from the short array passed starting at position low.
javax.realtime.RawMemoryAccess	subregion(long offset, long size) Construct a RawMemoryAccess area at offset bytes from the base of this area.
void	unmap() Unmap the physical memory range from virtual memory.

Methods inherited from class java.lang.Object

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

Field Detail

base

private long base

size

private long size

logic

private java.lang.Runnable logic

Constructor Detail

RawMemoryAccess

public RawMemoryAccess(java.lang.Object type,
                       long size)
                throws java.lang.SecurityException,
                       OffsetOutOfBoundsException,
                       SizeOutOfBoundsException,
                       UnsupportedPhysicalMemoryException,
                       MemoryTypeConflictException

Construct an instance of RawMemoryAccess with the given parameters.

Parameters:

type - An Object representing the type of memory required. Used to define the base address and control the mapping.

size - The size of the area in bytes.

Throws:

java.lang.SecurityException - The application doesn't have permissions to access physical memory or the given type of memory.

OffsetOutOfBoundsException - The address is invalid.

UnsupportedPhysicalMemoryException - Thrown if the underlying hardwre does not support the given type.

MemoryTypeConflictException - The specified base does not point to memory that matches the request type, or if type specifies attributes with a conflict.

MemoryInUseException - The specified memory is already in use.

SizeOutOfBoundsException

RawMemoryAccess

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

Construct an instance of RawMemoryAccess with the given parameters.

Parameters:

type - An Object representing the type of memory required. Used to define the base address and control the mapping.

base - The physical memory address of the region.

size - The size of the area in bytes.

Throws:

java.lang.SecurityException - The application doesn't have permissions to access physical memory or the given type of memory.

OffsetOutOfBoundsException - The address is invalid.

UnsupportedPhysicalMemoryException - Thrown if the underlying hardwre does not support the given type.

MemoryTypeConflictException - The specified base does not point to memory that matches the request type, or if type specifies attributes with a conflict.

MemoryInUseException - The specified memory is already in use.

SizeOutOfBoundsException

RawMemoryAccess

protected RawMemoryAccess(long base,
                          long size)

RawMemoryAccess

protected RawMemoryAccess(javax.realtime.RawMemoryAccess memory,
                          long base,
                          long size)

Constructor reserved for use by the memory object factory.

Method Detail

create

public static javax.realtime.RawMemoryAccess create(java.lang.Object type,
                                                    long size)

create

public static javax.realtime.RawMemoryAccess create(java.lang.Object type,
                                                    long base,
                                                    long size)

getByte

public byte getByte(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

Get the byte at the given offset.

Parameters:

offset - The offset at which to read the byte.

Returns:

The byte read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getBytes

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

Gets nunber bytes starting at the given offset and assign them to the byte array starting at the position low.

Parameters:

offset - The offset at which to start reading.

bytes - The array into which the read items are placed.

low - the offset which is the starting point in the given array for the read items to be placed.

number - The number of items to read.

Returns:

The integer read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getInt

public int getInt(long offset)
           throws OffsetOutOfBoundsException,
                  SizeOutOfBoundsException

Gets the int at the given offset.

Parameters:

offset - The offset at which to read the integer.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getInts

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

Gets number ints starting at the given offset and assign them to the int array passed at position low.

Parameters:

offset - The offset at which to start reading.

ints - The array into which the read items are placed.

low - The offset which is the starting point in the given array for the read items to be placed.

number - The number of items to read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getLong

public long getLong(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

Gets the long at the given offset.

Parameters:

offset - The offset at which to read the long.

Returns:

The long read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getLongs

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

Gets number longs starting at the given offset and assign them to the long array passed starting at position low.

Parameters:

offset - The offset at which to start reading.

longs - The array into which the read items are placed.

low - The offset which is the starting point in the given array for the read items to be placed.

number - The number of items to read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getMappedAddress

public long getMappedAddress()

Gets the virtual memory location at which the memory region is mapped.

Returns:

The virtual address to which this is mapped (for reference purposes). Same as the base address if virtual memory is not supported.

getShort

public short getShort(long offset)
               throws OffsetOutOfBoundsException,
                      SizeOutOfBoundsException

Gets the short at the given offset.

Parameters:

offset - The offset at which to read the short.

Returns:

The short read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

getShorts

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

Gets number shorts starting at the give offset and assign them to the short array passed starting at position low.

Parameters:

offset - The offset at which to start reading.

shorts - The array into which the read items are placed.

low - The offset which is the starting point in the given array for the read items to be placed.

number - The number of items to read.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

map

public long map()

Maps the physical memory range into virtual memory. No-op if the system doesn't support virtual memory.

map

public long map(long base)

Maps the physical memory range into virtual memory at the specified location. No-op if the system doesn't support virtual memory.

Parameters:

base - The location to map at the virtual memory space.

Returns:

The starting point of the virtual memory.

map

public long map(long base,
                long size)

Maps the physical memory range into virtual memory. No-op if the system doesn't support virtual memory.

Parameters:

base - The location to map at the virtual memory space.

size - The size of the block to map in.

Returns:

The starting point of the virtual memory.

setByte

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

Sets the byte at the given offset.

Parameters:

offset - The offset at which to write the byte.

value - The byte to write.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

setBytes

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

Sets number bytes starting at the give offset from the byte array passed starting at position low.

Parameters:

offset - The offset at which to start writing.

bytes - The array from which the items are obtained.

low - The offset which is the starting point in the given array for the items to be obtained.

number - The number of items to write.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

setInt

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

Sets the int at the given offset.

Parameters:

offset - The offset at which to write the integer.

value - The integer to write.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

setInts

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

Sets number ints starting at the given offset from the int array passed starting at position low.

Parameters:

offset - The offset at which to start writing.

ints - The array from which the itmes are obtained.

low - The offset which is the starting point in the given array for the items to be obtained.

number - The number of items to write.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

setLong

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

Sets the long at the given offset.

Parameters:

offset - The offset at which to write the long.

value - The long to write.

Throws:

OffsetOutOfBoundsException - The offset in invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

setLongs

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

Sets number longs starting at the given offset from the long array passed starting at position low.

Parameters:

offset - The offset at which to start writing.

longs - The array from which the items are obtained.

low - The offset which is the starting point in the given array for the items to be obtained.

number - The number of items to write.

Throws:

OffsetOutOfboundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

OffsetOutOfBoundsException

setShort

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

Sets the short at the given offset.

Parameters:

offset - The offset at which to write the short.

value - The short to write.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

setShorts

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

Sets number shorts starting at the given offset from the short array passed starting at position low.

Parameters:

offset - The offset at which to start writing.

shorts - The array from which the items are obtained.

low - The offset which is the starting point in the given array for the items to be obtained.

number - The number of items to write.

Throws:

OffsetOutOfBoundsException - The offset is invalid.

SizeOutOfBoundsException - The size is negative or extends into an invalid address range.

unmap

public void unmap()

Unmap the physical memory range from virtual memory. No-op if the system doesn't support virtual memory.

subregion

public javax.realtime.RawMemoryAccess subregion(long offset,
                                                long size)

Construct a RawMemoryAccess area at offset bytes from the base of this area.