lib.rs 5.1 KB
Newer Older
Isaac Oscar Gariano's avatar
Isaac Oscar Gariano committed
1
// Copyright 2017 The Australian National University
qinsoon's avatar
qinsoon committed
2
//
Isaac Oscar Gariano's avatar
Isaac Oscar Gariano committed
3 4 5
// 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
qinsoon's avatar
qinsoon committed
6
//
Isaac Oscar Gariano's avatar
Isaac Oscar Gariano committed
7
//     http://www.apache.org/licenses/LICENSE-2.0
qinsoon's avatar
qinsoon committed
8
//
Isaac Oscar Gariano's avatar
Isaac Oscar Gariano committed
9 10 11 12 13 14
// 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
qinsoon's avatar
qinsoon committed
39
pub type BitSize = usize;
qinsoon's avatar
qinsoon committed
40
/// size in bytes
qinsoon's avatar
qinsoon committed
41
pub type ByteSize = usize;
qinsoon's avatar
qinsoon committed
42 43 44
/// offset in byte
pub type ByteOffset = isize;
/// word value
qinsoon's avatar
qinsoon committed
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
pub const LOG_POINTER_SIZE: usize = 3;
qinsoon's avatar
qinsoon committed
53

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
pub const WORD_SIZE: ByteSize = 1 << LOG_POINTER_SIZE;
qinsoon's avatar
qinsoon committed
58

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;
63 64
/// linked multi-key hashmap implementation
mod linked_multimap;
qinsoon's avatar
qinsoon committed
65 66
/// tree implementation
mod tree;
qinsoon's avatar
qinsoon committed
67 68

// re-export these data structures
69

70
pub use linked_hashmap::LinkedHashMap;
qinsoon's avatar
qinsoon committed
71
pub use linked_hashset::LinkedHashSet;
72
pub use linked_multimap::LinkedMultiMap;
qinsoon's avatar
qinsoon committed
73 74
pub use linked_multimap::LinkedRepeatableMultiMap;
pub use tree::Tree;
qinsoon's avatar
qinsoon committed
75 76 77 78 79 80 81 82 83 84 85 86 87
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;
qinsoon's avatar
qinsoon committed
88 89
/// ObjectReference is a reference to an object
/// (the address is guaranteed to be valid with an object)
qinsoon's avatar
qinsoon committed
90
pub use address::ObjectReference;
91

qinsoon's avatar
qinsoon committed
92 93 94 95 96 97 98 99 100 101 102
// 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
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
#[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
120

qinsoon's avatar
qinsoon committed
121
/// the macro to create LinkedHashSet
122
#[macro_export]
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
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
140
/// print trace!() log if condition is true (the condition should be a constant boolean)
141 142 143 144 145 146 147 148 149
#[macro_export]
macro_rules! trace_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            trace!($($arg)*)
        }
    }
}

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

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

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

qinsoon's avatar
qinsoon committed
180
/// print error!() log if condition is true (the condition should be a constant boolean)
181 182 183 184 185 186 187
#[macro_export]
macro_rules! error_if {
    ($cond: expr, $($arg:tt)*) => {
        if $cond {
            error!($($arg)*)
        }
    }
Isaac Oscar Gariano's avatar
Isaac Oscar Gariano committed
188
}