// Panopticon - A libre program analysis library for machine code
// Copyright (C) 2014-2018  The Panopticon Developers
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

//! A library for disassembling and analysing binary code.
//!
//! The panopticon crate implements structures to model the in-memory representation of a
//! program including is control flow, call graph and memory maps.
//! The most important types and their interaction are as follows:
//!
//! ```text
//! Project
//! ├── Region
//! │   └── Layer
//! └── Program
//!     └── Function
//!         └── BasicBlock
//!             └── Mnemonic
//!                 └── Statement
//! ```
//!
//! The [`Program`](program/index.html), [`Function`](function/index.html),
//! [`BasicBlock`](basic_block/index.html) and [`Statement`](il/struct.Statement.html)
//! types model the behaviour of code.
//! The [`Region`](region/index.html) and [`Layer`](layer/index.html) types
//! represent how the program is laid out in memory.
//!
//! # Code
//!
//! Panopticon models code as a collection of programs. Each
//! [`Program`](program/index.html) consists of functions. A [`Function`](function/index.html) a graph with nodes representing a
//! sequence of instructions and edges representing jumps. These instruction sequences are [`BasicBlock`s](basic_block/index.html)
//! and contain a list of [`Mnemonic`](mnemonic/index.html)s. The meaning of each
//! `Mnemonic` is described in the [RREIL][1] language. Each mnemonic includes a sequence of
//! [`Statement`s](il/struct.Statement.html) implementing it.
//!
//! Panopticon allows multiple programs per project. For example, imagine a C# application that calls into a
//! native DLL written in C. Such an application would have two program instances. One for the CIL
//! code of the C# part of the application and one for the AMD64 object code inside the DLL.
//!
//! The [`Disassembler`](disassembler/index.html) and [`CodeGen`](codegen/index.html) are used to fill `Function`
//! structures with `Mnemonic`s.
//!
//! # Data
//!
//! The in-memory layout of an executable is modeled using the [`Region`](region/index.html), [`Layer`](layer/index.html) and
//! [`Cell`](layer/type.Cell.html) types. All data is organized into `Region`s. Each `Region` is an array of
//! `Cell`s numbered from 0 to n. Each `Cell` is an is either
//! undefined or has a value between 0 and 255 (both including). `Region`s are read
//! only. Changing their contents is done by applying `Layer` instance to them. A `Layer`
//! reads part of a `Region` or another `Layer` and returns a new `Cell` array. For example, `Layer`
//! can decrypt parts of a `Region` or replace individual `Cell`s with new
//! ones.
//!

//! In normal operation there is one `Region` for each memory address space, one on
//! Von-Neumann machines two on Harvard architectures. Other uses for `Region`s are
//! applying functions to `Cell` array where the result is not equal in size to the
//! input (for example uncompressing parts of the executable image).

#![recursion_limit = "1024"]
#![warn(missing_docs)]

#[macro_use] extern crate log;
extern crate num_traits;
extern crate byteorder;
extern crate goblin;
#[macro_use] extern crate error_chain;
extern crate leb128;
extern crate petgraph;
extern crate smallvec;
extern crate memmap;
extern crate simple_logger;
extern crate chrono;
extern crate vec_map;
extern crate ron_uuid;

#[cfg(not(test))]
extern crate quickcheck;
#[cfg(test)]
#[macro_use] extern crate quickcheck;

pub use ron_uuid::UUID;

mod table;
pub use self::table::{
    Name,
    NameRef,
    Names,
    Strings,
    StrRef,
    Segments,
    SegmentRef,
    Table
};

mod value;
pub use self::value::{
    Variable,
    Constant,
    Value,
    Segment
};

mod constraint;
pub use self::constraint::{
    Constraint
};

mod guard;
pub use self::guard::{
    Guard
};

mod il;
pub use self::il::{
    Operation,
    Statement,
    Endianess,
    CallTarget,
    MemoryOperation,
    FlowOperation,
    Area,
};

mod bitcode;
pub use self::bitcode::{
    Bitcode,
    BitcodeIter
};

mod function;
pub use self::function::{
    Function,
    CfgNode,
    IntoStatementRange,
};

mod statements;
pub use self::statements::{
    RewriteControl,
    Statements,
};

mod basic_block;
pub use self::basic_block::{
    BasicBlock,
    BasicBlockIndex,
    BasicBlockIterator,
};

mod mnemonic;
pub use self::mnemonic::{
    Mnemonic,
    MnemonicIndex,
    MnemonicIterator,
};

mod region;
pub use self::region::{
    Region,
};

mod architecture;
pub use self::architecture::{
    Architecture,
    Match,
    TestArch,
};

mod loader;
pub use self::loader::{
    Content,
    Machine,
    Pointer,
};

mod errors {
    #![allow(missing_docs)]
    error_chain!{
        foreign_links {
            Fmt(::std::fmt::Error);
            Io(::std::io::Error);
            Leb128(::leb128::read::Error);
            Goblin(::goblin::error::Error);
            Utf8String(::std::string::FromUtf8Error);
            Utf8Str(::std::str::Utf8Error);
        }
    }
}
pub use errors::*;

/// Our string type.
pub type Str = ::std::borrow::Cow<'static,str>;