nachos.machine
Class Lib

java.lang.Object
  extended by nachos.machine.Lib

public final class Lib
extends Object

Provides miscellaneous library routines.


Method Summary
static void assertNotReached()
          Asserts that this call is never made.
static void assertNotReached(String message)
          Asserts that this call is never made, with the specified error messsage.
static void assertTrue(boolean expression)
          Asserts that expression is true.
static void assertTrue(boolean expression, String message)
          Asserts that expression is true.
static void bytesFromInt(byte[] array, int offset, int value)
          Convert an int into its little-endian byte string representation.
static void bytesFromInt(byte[] array, int offset, int length, int value)
          Convert an int into a little-endian byte string representation of the specified length.
static byte[] bytesFromInt(int value)
          Convert an int into its little-endian byte string representation, and return an array containing it.
static void bytesFromShort(byte[] array, int offset, short value)
          Convert a short into its little-endian byte string representation.
static int bytesToInt(byte[] array, int offset)
          Convert to an int from its little-endian byte string representation.
static int bytesToInt(byte[] array, int offset, int length)
          Convert to an int from a little-endian byte string representation of the specified length.
static short bytesToShort(byte[] array, int offset)
          Convert to a short from its little-endian byte string representation.
static String bytesToString(byte[] array, int offset, int length)
          Convert to a string from a possibly null-terminated array of bytes.
static int bytesToUnsignedShort(byte[] array, int offset)
          Convert to an unsigned short from its little-endian byte string representation.
static void checkConstructor(Class cls, Class[] parameterTypes)
          Verifies that the specified class is public and not abstract, and that a constructor with the specified signature exists and is public.
static void checkDerivation(Class cls, Class superCls)
          Verify that the specified class extends or implements the specified superclass.
static void checkField(Class cls, String fieldName, Class fieldType)
          Verifies that the specified class is public, and that a non-static field with the specified name and type exists, is public, and is not final.
static void checkMethod(Class cls, String methodName, Class[] parameterTypes, Class returnType)
          Verifies that the specified class is public, and that a non-static method with the specified name and signature exists, is public, and returns the specified type.
static void checkStaticField(Class cls, String fieldName, Class fieldType)
          Verifies that the specified class is public, and that a static field with the specified name and type exists and is public.
static void checkStaticMethod(Class cls, String methodName, Class[] parameterTypes, Class returnType)
          Verifies that the specified class is public, and that a static method with the specified name and signature exists, is public, and returns the specified type.
static OpenFile cloneFile(OpenFile file)
          Take a read-only snapshot of a file.
static Object constructObject(String className)
          Create and return a new instance of the named class, using the constructor that takes no arguments.
static void debug(char flag, String message)
          Print message if flag was enabled on the command line.
static int divRoundUp(int a, int b)
          Divide two non-negative integers, round the quotient up to the nearest integer, and return it.
static void enableDebugFlags(String flagsString)
          Enable all the debug flags in flagsString.
static int extend(int bits, int lowest, int size)
          Mask out and shift a bit substring; then sign extend the substring.
static int extract(int bits, int lowest, int size)
          Mask out and shift a bit substring.
static long extract(long bits, int lowest, int size)
          Mask out and shift a bit substring.
static Class loadClass(String className)
          Load and return the named class, terminating Nachos on any error.
static byte[] loadFile(OpenFile file)
          Load an entire file into memory.
static double random()
          Return a random double between 0.0 (inclusive) and 1.0 (exclusive).
static int random(int range)
          Return a random integer between 0 and range - 1.
static void seedRandom(long randomSeed)
          Seed the random number generater.
static void strictReadFile(OpenFile file, int position, byte[] buf, int offset, int length)
          Read a file, verifying that the requested number of bytes is read, and verifying that the read operation took a non-zero amount of time.
static boolean test(char flag)
          Tests if flag was enabled on the command line.
static boolean test(long flag, long bits)
          Test if a bit is set in a bit string.
static String toHexString(int i)
          Creates a padded upper-case string representation of the integer argument in base 16.
static String toHexString(int i, int pad)
          Creates a padded upper-case string representation of the integer argument in base 16, padding to at most the specified number of digits.
static Class tryLoadClass(String className)
          Load and return the named class, or return null if the class could not be loaded.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

seedRandom

public static void seedRandom(long randomSeed)
Seed the random number generater. May only be called once.

Parameters:
randomSeed - the seed for the random number generator.

random

public static int random(int range)
Return a random integer between 0 and range - 1. Must not be called before seedRandom() seeds the random number generator.

Parameters:
range - a positive value specifying the number of possible return values.
Returns:
a random integer in the specified range.

random

public static double random()
Return a random double between 0.0 (inclusive) and 1.0 (exclusive).

Returns:
a random double between 0.0 and 1.0.

assertTrue

public static void assertTrue(boolean expression)
Asserts that expression is true. If not, then Nachos exits with an error message.

Parameters:
expression - the expression to assert.

assertTrue

public static void assertTrue(boolean expression,
                              String message)
Asserts that expression is true. If not, then Nachos exits with the specified error message.

Parameters:
expression - the expression to assert.
message - the error message.

assertNotReached

public static void assertNotReached()
Asserts that this call is never made. Same as assertTrue(false).


assertNotReached

public static void assertNotReached(String message)
Asserts that this call is never made, with the specified error messsage. Same as assertTrue(false, message).

Parameters:
message - the error message.

debug

public static void debug(char flag,
                         String message)
Print message if flag was enabled on the command line. To specify which flags to enable, use the -d command line option. For example, to enable flags a, c, and e, do the following:

nachos -d ace

Nachos uses several debugging flags already, but you are encouraged to add your own.

Parameters:
flag - the debug flag that must be set to print this message.
message - the debug message.

test

public static boolean test(char flag)
Tests if flag was enabled on the command line.

Parameters:
flag - the debug flag to test.
Returns:
true if this flag was enabled on the command line.

enableDebugFlags

public static void enableDebugFlags(String flagsString)
Enable all the debug flags in flagsString.

Parameters:
flagsString - the flags to enable.

strictReadFile

public static void strictReadFile(OpenFile file,
                                  int position,
                                  byte[] buf,
                                  int offset,
                                  int length)
Read a file, verifying that the requested number of bytes is read, and verifying that the read operation took a non-zero amount of time.

Parameters:
file - the file to read.
position - the file offset at which to start reading.
buf - the buffer in which to store the data.
offset - the buffer offset at which storing begins.
length - the number of bytes to read.

loadFile

public static byte[] loadFile(OpenFile file)
Load an entire file into memory.

Parameters:
file - the file to load.
Returns:
an array containing the contents of the entire file, or null if an error occurred.

cloneFile

public static OpenFile cloneFile(OpenFile file)
Take a read-only snapshot of a file.

Parameters:
file - the file to take a snapshot of.
Returns:
a read-only snapshot of the file.

bytesFromShort

public static void bytesFromShort(byte[] array,
                                  int offset,
                                  short value)
Convert a short into its little-endian byte string representation.

Parameters:
array - the array in which to store the byte string.
offset - the offset in the array where the string will start.
value - the value to convert.

bytesFromInt

public static void bytesFromInt(byte[] array,
                                int offset,
                                int value)
Convert an int into its little-endian byte string representation.

Parameters:
array - the array in which to store the byte string.
offset - the offset in the array where the string will start.
value - the value to convert.

bytesFromInt

public static byte[] bytesFromInt(int value)
Convert an int into its little-endian byte string representation, and return an array containing it.

Parameters:
value - the value to convert.
Returns:
an array containing the byte string.

bytesFromInt

public static void bytesFromInt(byte[] array,
                                int offset,
                                int length,
                                int value)
Convert an int into a little-endian byte string representation of the specified length.

Parameters:
array - the array in which to store the byte string.
offset - the offset in the array where the string will start.
length - the number of bytes to store (must be 1, 2, or 4).
value - the value to convert.

bytesToShort

public static short bytesToShort(byte[] array,
                                 int offset)
Convert to a short from its little-endian byte string representation.

Parameters:
array - the array containing the byte string.
offset - the offset of the byte string in the array.
Returns:
the corresponding short value.

bytesToUnsignedShort

public static int bytesToUnsignedShort(byte[] array,
                                       int offset)
Convert to an unsigned short from its little-endian byte string representation.

Parameters:
array - the array containing the byte string.
offset - the offset of the byte string in the array.
Returns:
the corresponding short value.

bytesToInt

public static int bytesToInt(byte[] array,
                             int offset)
Convert to an int from its little-endian byte string representation.

Parameters:
array - the array containing the byte string.
offset - the offset of the byte string in the array.
Returns:
the corresponding int value.

bytesToInt

public static int bytesToInt(byte[] array,
                             int offset,
                             int length)
Convert to an int from a little-endian byte string representation of the specified length.

Parameters:
array - the array containing the byte string.
offset - the offset of the byte string in the array.
length - the length of the byte string.
Returns:
the corresponding value.

bytesToString

public static String bytesToString(byte[] array,
                                   int offset,
                                   int length)
Convert to a string from a possibly null-terminated array of bytes.

Parameters:
array - the array containing the byte string.
offset - the offset of the byte string in the array.
length - the maximum length of the byte string.
Returns:
a string containing the specified bytes, up to and not including the null-terminator (if present).

extract

public static int extract(int bits,
                          int lowest,
                          int size)
Mask out and shift a bit substring.

Parameters:
bits - the bit string.
lowest - the first bit of the substring within the string.
size - the number of bits in the substring.
Returns:
the substring.

extract

public static long extract(long bits,
                           int lowest,
                           int size)
Mask out and shift a bit substring.

Parameters:
bits - the bit string.
lowest - the first bit of the substring within the string.
size - the number of bits in the substring.
Returns:
the substring.

extend

public static int extend(int bits,
                         int lowest,
                         int size)
Mask out and shift a bit substring; then sign extend the substring.

Parameters:
bits - the bit string.
lowest - the first bit of the substring within the string.
size - the number of bits in the substring.
Returns:
the substring, sign-extended.

test

public static boolean test(long flag,
                           long bits)
Test if a bit is set in a bit string.

Parameters:
flag - the flag to test.
bits - the bit string.
Returns:
true if (bits & flag) is non-zero.

toHexString

public static String toHexString(int i)
Creates a padded upper-case string representation of the integer argument in base 16.

Parameters:
i - an integer.
Returns:
a padded upper-case string representation in base 16.

toHexString

public static String toHexString(int i,
                                 int pad)
Creates a padded upper-case string representation of the integer argument in base 16, padding to at most the specified number of digits.

Parameters:
i - an integer.
pad - the minimum number of hex digits to pad to.
Returns:
a padded upper-case string representation in base 16.

divRoundUp

public static int divRoundUp(int a,
                             int b)
Divide two non-negative integers, round the quotient up to the nearest integer, and return it.

Parameters:
a - the numerator.
b - the denominator.
Returns:
ceiling(a / b).

tryLoadClass

public static Class tryLoadClass(String className)
Load and return the named class, or return null if the class could not be loaded.

Parameters:
className - the name of the class to load.
Returns:
the loaded class, or null if an error occurred.

loadClass

public static Class loadClass(String className)
Load and return the named class, terminating Nachos on any error.

Parameters:
className - the name of the class to load.
Returns:
the loaded class.

constructObject

public static Object constructObject(String className)
Create and return a new instance of the named class, using the constructor that takes no arguments.

Parameters:
className - the name of the class to instantiate.
Returns:
a new instance of the class.

checkDerivation

public static void checkDerivation(Class cls,
                                   Class superCls)
Verify that the specified class extends or implements the specified superclass.

Parameters:
cls - the descendant class.
superCls - the ancestor class.

checkConstructor

public static void checkConstructor(Class cls,
                                    Class[] parameterTypes)
Verifies that the specified class is public and not abstract, and that a constructor with the specified signature exists and is public.

Parameters:
cls - the class containing the constructor.
parameterTypes - the list of parameters.

checkMethod

public static void checkMethod(Class cls,
                               String methodName,
                               Class[] parameterTypes,
                               Class returnType)
Verifies that the specified class is public, and that a non-static method with the specified name and signature exists, is public, and returns the specified type.

Parameters:
cls - the class containing the non-static method.
methodName - the name of the non-static method.
parameterTypes - the list of parameters.
returnType - the required return type.

checkStaticMethod

public static void checkStaticMethod(Class cls,
                                     String methodName,
                                     Class[] parameterTypes,
                                     Class returnType)
Verifies that the specified class is public, and that a static method with the specified name and signature exists, is public, and returns the specified type.

Parameters:
cls - the class containing the static method.
methodName - the name of the static method.
parameterTypes - the list of parameters.
returnType - the required return type.

checkField

public static void checkField(Class cls,
                              String fieldName,
                              Class fieldType)
Verifies that the specified class is public, and that a non-static field with the specified name and type exists, is public, and is not final.

Parameters:
cls - the class containing the field.
fieldName - the name of the field.
fieldType - the required type.

checkStaticField

public static void checkStaticField(Class cls,
                                    String fieldName,
                                    Class fieldType)
Verifies that the specified class is public, and that a static field with the specified name and type exists and is public.

Parameters:
cls - the class containing the static field.
fieldName - the name of the static field.
fieldType - the required type.