-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Binding for the cpuid machine instruction on x86 compatible
processors
--   
--   This module provides the function <a>cpuid</a> for accessing
--   information about the currently running IA-32 processor. Both a
--   function for calling the <a>cpuid</a> instruction directly, and some
--   convenience functions for common uses are provided. This package is
--   only portable to IA-32 machines.
@package cpuid
@version 0.2


-- | This module provides the function <a>cpuid</a> for accessing the cpuid
--   instruction on modern IA-32 processors. Additionally, some convenience
--   functions are provided, which perform some of the (really complicated
--   and obstruse) decoding.
--   
--   As an example, you may use the following program to measure the
--   overhead of calling this function:
--   
--   <pre>
--   module Main(main) where
--   
--   import Text.Printf
--   import System.Cpuid
--   
--   main :: IO ()
--   main =
--       do (a, b, c, d) &lt;- cpuid 0
--          printf "basic CPUID usage: EAX=0: %8x %8x %8x %8x\n\n" a b c d
--          vs &lt;- vendorString
--          printf "Vendor string: %s\n\n" vs
--          vs &lt;- brandString
--          printf "Brand string: %s\n\n" vs
--          printf "Cache information:\n"
--          infos &lt;- cacheInfo
--          mapM_ (\ v -&gt; putStrLn $ "  " ++ show v) infos
--          putStrLn ""
--          ProcessorInfo{piFamily = fam, piModel = mod, piStepping = step, piType = typ} &lt;- processorInfo
--          printf "processor info: family: %d, model: %d, stepping: %d, processor type: %d\n" fam mod step typ
--   </pre>
module System.Cpuid

-- | Cache associativity. For some entries, this is not specified in the
--   manual. We report these as <a>DirectMapped</a>.
data Associativity
SetAssociative :: Ways -> Associativity
DirectMapped :: Associativity

-- | Page size. Some entries can have alternative page sizes, therefore the
--   complicated type.
data PageSize
PageSize :: Int -> PageSize
PageSizeOr :: PageSize -> PageSize -> PageSize

-- | Associativity in a set-associative cache.
data Ways
Ways :: Int -> Ways

-- | Number of entries in a TLB.
data Entries
Entries :: Int -> Entries

-- | Cache size. Some entries can have alternative cache sizes, therefore
--   the complicated type.
data CacheSize
CacheSize :: Int -> CacheSize
CacheSizeOr :: CacheSize -> CacheSize -> CacheSize

-- | Information for caches and TLBs.
data CacheInfo

-- | Configuration of code TLB.
InstructionTLB :: (Maybe CacheSize) -> PageSize -> Associativity -> Entries -> CacheInfo

-- | Configuration of data TLB.
DataTLB :: (Maybe CacheSize) -> PageSize -> Associativity -> Entries -> CacheInfo

-- | First-level code cache configuration.
FirstLevelICache :: CacheSize -> Associativity -> LineSize -> CacheInfo

-- | First-level code cache configuration.
FirstLevelDCache :: CacheSize -> Associativity -> LineSize -> CacheInfo

-- | No second level support.
NoSecondLevelCache :: CacheInfo

-- | Second-level cache configuration.
SecondLevelCache :: CacheSize -> Associativity -> LineSize -> (Maybe BytesPerSector) -> CacheInfo

-- | No third level support.
NoThirdLevelCache :: CacheInfo

-- | Internal use only.
NoSecondOrThirdLevelCache :: CacheInfo

-- | Second-level cache configuration.
ThirdLevelCache :: CacheSize -> Associativity -> LineSize -> (Maybe BytesPerSector) -> CacheInfo

-- | Trace cache (1st-level code cache) configuration.
TraceCache :: MuOps -> Associativity -> CacheInfo

-- | Prefetching information.
Prefetching :: Int -> CacheInfo

-- | Line size in a cache.
data LineSize
LineSize :: Int -> LineSize

-- | MuOps in a processors trace cache.
data MuOps
MuOps :: Int -> MuOps

-- | Bytes per sector in a cache.
data BytesPerSector
BytesPerSector :: Int -> BytesPerSector

-- | Processor information.
data ProcessorInfo
ProcessorInfo :: Int -> Int -> Int -> Int -> ProcessorInfo

-- | Processor family.
piFamily :: ProcessorInfo -> Int

-- | Processor model.
piModel :: ProcessorInfo -> Int

-- | Processor stepping.
piStepping :: ProcessorInfo -> Int
piType :: ProcessorInfo -> Int

-- | Execute the <tt>cpuid</tt> instructions with the given argument in the
--   EAX register. Return the values of the registers EAX, EBX, ECX and EDX
--   in that order.
cpuid :: Word32 -> IO (Word32, Word32, Word32, Word32)

-- | Retrieve basic processor information from the processor using the
--   <tt>cpuid</tt> instruction.
processorInfo :: IO ProcessorInfo

-- | Execute the <tt>cpuid</tt> instruction and return the vendor string
--   reported by that instruction.
vendorString :: IO String

-- | Execute the <tt>cpuid</tt> instruction and return the brand string
--   (processor name and maximum frequency) reported by that instruction.
brandString :: IO String

-- | Fetch all available cache information from the processor, using the
--   <tt>cpuid</tt> instruction. The list is not ordered.
cacheInfo :: IO [CacheInfo]
instance Show CacheInfo
instance Show Associativity
instance Show BytesPerSector
instance Show LineSize
instance Show CacheSize
instance Show PageSize
instance Show MuOps
instance Show Ways
instance Show Entries