lib.rs 4.92 KB
Newer Older
Isaac Oscar Gariano's avatar
Isaac Oscar Gariano committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14
// Copyright 2017 The Australian National University
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
//     http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

qinsoon's avatar
qinsoon committed
15 16 17
//! # Utility crate that serves Zebu
//!
//! It includes:
qinsoon's avatar
qinsoon committed
18
//!
qinsoon's avatar
qinsoon committed
19 20 21 22 23 24 25 26 27 28 29 30
//! * data structures
//!   * double linked list
//!   * linked hashmap/set
//! * extra functions for existing types
//!   * string
//!   * vector
//! * Address/ObjectReference type
//! * utility functions for
//!   * memory
//!   * mathematics
//!   * bit operations

31 32
#[macro_use]
extern crate rodal;
qinsoon's avatar
qinsoon committed
33
extern crate byteorder;
qinsoon's avatar
qinsoon committed
34 35 36
extern crate doubly;

// these type aliases make source code easier to read
qinsoon's avatar
qinsoon committed
37

qinsoon's avatar
qinsoon committed
38
/// size in bits
39
pub type BitSize    = usize;
qinsoon's avatar
qinsoon committed
40
/// size in bytes
41
pub type ByteSize   = usize;
qinsoon's avatar
qinsoon committed
42 43 44
/// offset in byte
pub type ByteOffset = isize;
/// word value
45
pub type Word       = usize;
qinsoon's avatar
qinsoon committed
46

qinsoon's avatar
qinsoon committed
47 48 49 50
/// Zebu make an assumption that it will only support 64 bits architecture
/// However, ideally we should always use pointer size, or pointer-size type defined here.
/// But we may have hard coded u64 or 64 somewhere.
//  TODO: fix the hard code
51
#[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
qinsoon's avatar
qinsoon committed
52 53
pub const LOG_POINTER_SIZE : usize = 3;

qinsoon's avatar
qinsoon committed
54
/// pointer size in byte
qinsoon's avatar
qinsoon committed
55
pub const POINTER_SIZE     : ByteSize = 1 << LOG_POINTER_SIZE;
qinsoon's avatar
qinsoon committed
56
/// word size in byte
qinsoon's avatar
qinsoon committed
57 58
pub const WORD_SIZE        : ByteSize = 1 << LOG_POINTER_SIZE;

qinsoon's avatar
qinsoon committed
59
/// linked hashmap implementation copied from container-rs with modification
60
mod linked_hashmap;
qinsoon's avatar
qinsoon committed
61
/// linked hashset implementation based on LinkedHashMap
qinsoon's avatar
qinsoon committed
62
mod linked_hashset;
qinsoon's avatar
qinsoon committed
63 64

// re-export these data structures
65

66
pub use linked_hashmap::LinkedHashMap;
qinsoon's avatar
qinsoon committed
67
pub use linked_hashset::LinkedHashSet;
qinsoon's avatar
qinsoon committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
pub use self::doubly::DoublyLinkedList;

/// mem module:
/// * conversions of bit representations
/// * re-export memmap and memsec crate
pub mod mem;

/// mathematics utilities
pub mod math;

mod address;
/// Address represents an arbitrary memory address (valid or not)
pub use address::Address;
/// ObjectReference is a reference to an object (the address is guaranteed to be valid with an object)
pub use address::ObjectReference;
83

qinsoon's avatar
qinsoon committed
84 85 86 87 88 89 90 91 92 93 94
// These modules provide operations on Vector, and String.
// They are not found in the standard library.
// (maybe because they are likely inefficient?)
/// vector utilities
pub mod vec_utils;
/// string utilities
pub mod string_utils;
/// bit operations
pub mod bit_utils;

/// the macro to create LinkedHashMap
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
#[macro_export]
macro_rules! linked_hashmap {
    (@single $($x:tt)*) => (());
    (@count $($rest:expr),*) => (<[()]>::len(&[$(linked_hashmap!(@single $rest)),*]));

    ($($key:expr => $value:expr,)+) => { linked_hashmap!($($key => $value),+) };
    ($($key:expr => $value:expr),*) => {
        {
            let _cap = linked_hashmap!(@count $($key),*);
            let mut _map = LinkedHashMap::with_capacity(_cap);
            $(
                _map.insert($key, $value);
            )*
            _map
        }
    };
}
qinsoon's avatar
qinsoon committed
112

qinsoon's avatar
qinsoon committed
113
/// the macro to create LinkedHashSet
114
#[macro_export]
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
macro_rules! linked_hashset {
    (@single $($x:tt)*) => (());
    (@count $($rest:expr),*) => (<[()]>::len(&[$(linked_hashset!(@single $rest)),*]));

    ($($value:expr,)+) => { linked_hashset!($($value),+) };
    ($($value:expr),*) => {
        {
            let _cap = linked_hashset!(@count $($key),*);
            let mut _map = LinkedHashSet::with_capacity(_cap);
            $(
                _map.insert($value);
            )*
            _map
        }
    };
}

qinsoon's avatar
qinsoon committed
132
/// print trace!() log if condition is true (the condition should be a constant boolean)
133 134 135 136 137 138 139 140 141
#[macro_export]
macro_rules! trace_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            trace!($($arg)*)
        }
    }
}

qinsoon's avatar
qinsoon committed
142
/// print info!() log if condition is true (the condition should be a constant boolean)
143 144 145 146 147 148 149 150 151
#[macro_export]
macro_rules! info_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            info!($($arg)*)
        }
    }
}

qinsoon's avatar
qinsoon committed
152
/// print debug!() log if condition is true (the condition should be a constant boolean)
153 154 155 156 157 158 159 160 161
#[macro_export]
macro_rules! debug_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            debug!($($arg)*)
        }
    }
}

qinsoon's avatar
qinsoon committed
162
/// print warn!() log if condition is true (the condition should be a constant boolean)
163 164 165 166 167 168 169 170 171
#[macro_export]
macro_rules! warn_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            warn!($($arg)*)
        }
    }
}

qinsoon's avatar
qinsoon committed
172
/// print error!() log if condition is true (the condition should be a constant boolean)
173 174 175 176 177 178 179 180
#[macro_export]
macro_rules! error_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            error!($($arg)*)
        }
    }
}