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 or 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.

Constructor Summary

RawMemoryAccess(java.lang.Object type, long size)
Creates a RawMemoryAccess object based on the parameters passed.

RawMemoryAccess(java.lang.Object type, long base, long size)
Creates a RawMemoryAccess object based on the parameters passed.

Method Summary

byte	getByte(long offset) Get the byte at the given offset.
void	getBytes(long offset, byte[] bytes, int low, int number) Get number bytes starting at the given offset and assign them to the byte array passed starting at position low.
int	getInt(long offset) Get the int at the given offset.
void	getInts(long offset, int[] ints, int low, int number) Get number ints starting at the given offset and assign them to the int array passed starting at position low.
long	getLong(long offset) Get the long at the given offset.
void	getLongs(long offset, long[] longs, int low, int number) Get number longs starting at the given offset and assign them to the long array passed starting at position low.
long	getMappedAddress() Returns the virtual memory location at which the memory region is mapped.
short	getShort(long offset) Get the short at the given offset.
void	getShorts(long offset, short[] shorts, int low, int number) Get number shorts starting at the given 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) Set the byte at the given offset.
void	setBytes(long offset, byte[] bytes, int low, int number) Set number bytes starting at the given offset from the byte array passed starting at position low.
void	setInt(long offset, int value) Set the int at the given offset.
void	setInts(long offset, int[] ints, int low, int number) Set number ints starting at the given offset from the int array passed starting at position low.
void	setLong(long offset, long value) Set the long at the given offset.
void	setLongs(long offset, long[] longs, int low, int number) Set number longs starting at the given offset from the long array passed starting at position low.
void	setShort(long offset, short value) Set the short at the given offset.
void	setShorts(long offset, short[] shorts, int low, int number) Set number shorts starting at the given offset from the short array passed starting at position low.
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

Constructor Detail

RawMemoryAccess

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

Creates a RawMemoryAccess object based on the parameters passed.

Parameters:

type - An Object representing the type of memory required ( e.g., dma, shared, etc) - used to define the base address and control the mapping.

base - The starting address for this physical memory area.

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.

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

UnsupportedPhysicalMemoryException - Thrown if the underlying hardware 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.

RawMemoryAccess

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

Creates a RawMemoryAccess object based on the parameters passed.

Parameters:

type - An Object representing the type of memory required ( e.g., dma, shared, etc) - 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.

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

UnsupportedPhysicalMemoryException - Thrown if the underlying hardware 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.

Method Detail

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.

getBytes

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

Get number bytes starting at the given offset and assign them to the byte array passed starting at position low.

getInt

public int getInt(long offset)
           throws OffsetOutOfBoundsException,
                  SizeOutOfBoundsException

Get the int at the given offset.

Parameters:

offset - The offset at which to read the integer.

Returns:

The int read.

getInts

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

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

getLong

public long getLong(long offset)
             throws OffsetOutOfBoundsException,
                    SizeOutOfBoundsException

Get the long at the given offset.

Parameters:

offset - The offset at which to read the long.

Returns:

The long read.

getLongs

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

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

getShort

public short getShort(long offset)
               throws OffsetOutOfBoundsException,
                      SizeOutOfBoundsException

Get the short at the given offset.

Parameters:

offset - The offset at which to read the short.

Returns:

The short read.

getShorts

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

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

setByte

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

Set the byte at the given offset.

Parameters:

offset - The offset at which to write the byte.

value - The byte to write.

setBytes

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

Set number bytes starting at the given offset from the byte array passed starting at position low.

setInt

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

Set the int at the given offset.

Parameters:

offset - The offset at which to write the int.

value - The integer to write.

setInts

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

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

setLong

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

Set the long at the given offset.

Parameters:

offset - The offset at which to write the long.

value - The long to write.

setLongs

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

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

setShort

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

Set the short at the given offset.

Parameters:

offset - The offset at which to write the short.

value - The short to write.

setShorts

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

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

getMappedAddress

public long getMappedAddress()

Returns 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.

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.

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 - Teh size of the block to map in.

unmap

public void unmap()

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