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


-- | Bindings to https://github.com/anrieff/libcpuid
--   
--   Please see the README on GitHub at
--   <a>https://github.com/dtaskoff/hlibcpuid#readme</a>
@package hlibcpuid
@version 0.2.0


-- | A wrapper around <b>cpu_id_t</b> from
--   <a>https://github.com/anrieff/libcpuid</a>.
--   
--   Usage:
--   
--   <pre>
--   cpuid &gt;&gt;= \case
--    Left err -&gt; error err
--    Right CPUID {..} -&gt; do
--      mapM_ putStrLn
--        [ "Available CPU information"
--        , "------------------------------------------"
--        , "vendor string: " ++ vendorString
--        , "brand string: " ++ brandString
--        , "has a time-stamp counter (TSC): " ++  if hasTSC then "yes" else "no"
--        , "# physical cores per processor: " ++ show physicalCores
--        , "# logical cores per processor: " ++ show logicalCores
--        , "# processors: " ++ show (div totalLogicalCores logicalCores)
--        ]
--   </pre>
module System.LibCPUID.CPUID

-- | CPU information and features.
data CPUID
CPUID :: String -> String -> Bool -> Int -> Int -> Int -> CPUID

-- | CPU vendor string, e.g. "GenuineIntel".
[vendorString] :: CPUID -> String

-- | CPU brand string, e.g. "Intel(R) Core(TM) i5-7500 CPU @ 3.40GHz".
[brandString] :: CPUID -> String

-- | Is a time-stamp counter available.
[hasTSC] :: CPUID -> Bool

-- | Number of physical cores per processor.
[physicalCores] :: CPUID -> Int

-- | Number of logical cores per processor.
[logicalCores] :: CPUID -> Int

-- | Total number of logical cores, which is <a>logicalCores</a> multiplied
--   by the number of processors.
[totalLogicalCores] :: CPUID -> Int

-- | Get CPU information and features, or an error message, if the CPU
--   can't be identified by libcpuid.
cpuid :: IO (Either String CPUID)

-- | Check if the CPUID instruction is supported.
isCPUIDPresent :: IO Bool
instance Foreign.Storable.Storable System.LibCPUID.CPUID.CPUID


-- | Calculate the CPU clock, by using a time-stamp counter.
--   
--   Usage:
--   
--   <pre>
--   do
--     tscMark &lt;- initialise
--     mark tscMark
--     foo
--     unmark tscMark
--     clock &lt;- clockBy tscMark
--   </pre>
module System.LibCPUID.TSC
data TSCMark

-- | Initialise a <a>TSCMark</a>.
initialise :: IO TSCMark

-- | Mark a time interval for calculating the CPU clock frequency.
mark :: TSCMark -> IO ()

-- | Unmark a time interval for calculating the CPU clock frequency.
unmark :: TSCMark -> IO ()

-- | Calculate the CPU clock frequency in MHz, for an interval, marked with
--   <a>mark</a>, and <a>unmark</a>. If the interval is insufficient, the
--   result will be -1.
clockBy :: TSCMark -> IO Int


-- | Bindings to <a>https://github.com/anrieff/libcpuid</a>.
--   
--   Currently implemented:
--   
--   <ul>
--   <li>getting CPU vendor and brand strings, TSC availability, number of
--   physical, and logical cores</li>
--   <li>measuring CPU clock frequency using a time-stamp counter and time
--   intervals</li>
--   <li>getting CPU clock frequency as reported by the OS</li>
--   <li>measuring CPU clock frequency using a busy-wait cycle</li>
--   </ul>
module System.LibCPUID

-- | Get the total number of logical cores (even if CPUID is not present).
--   If CPUID is present, the following is true:
--   
--   <ul>
--   <li><pre><a>getTotalLogicalCores</a> = <a>totalLogicalCores</a>
--   <a>&lt;$&gt;</a> <a>cpuid</a></pre></li>
--   </ul>
getTotalLogicalCores :: IO Int

-- | Get the CPU clock frequency in MHz, as reported by the OS (which may
--   differ from the true clock). If the OS is not supported, the result
--   will be -1.
clockByOS :: IO Int

-- | Get the CPU clock frequency in MHz, after performing a busy-wait cycle
--   for the given time in ms. If RDTSC is not supported, the result will
--   be -1.
clockMeasure :: Int -> ShouldQuadCheck -> IO Int

-- | Should <a>clockMeasure</a> do a more thorough measurement (quadruple
--   checking).
newtype ShouldQuadCheck
ShouldQuadCheck :: Bool -> ShouldQuadCheck

-- | Get the CPU clock frequency in MHz, by trying all available methods.
--   If all of them fail, the result will be -1.
clock :: IO Int

-- | CPU information and features.
data CPUID
CPUID :: String -> String -> Bool -> Int -> Int -> Int -> CPUID

-- | CPU vendor string, e.g. "GenuineIntel".
[vendorString] :: CPUID -> String

-- | CPU brand string, e.g. "Intel(R) Core(TM) i5-7500 CPU @ 3.40GHz".
[brandString] :: CPUID -> String

-- | Is a time-stamp counter available.
[hasTSC] :: CPUID -> Bool

-- | Number of physical cores per processor.
[physicalCores] :: CPUID -> Int

-- | Number of logical cores per processor.
[logicalCores] :: CPUID -> Int

-- | Total number of logical cores, which is <a>logicalCores</a> multiplied
--   by the number of processors.
[totalLogicalCores] :: CPUID -> Int

-- | Get CPU information and features, or an error message, if the CPU
--   can't be identified by libcpuid.
cpuid :: IO (Either String CPUID)
data TSCMark

-- | Initialise a <a>TSCMark</a>.
initialise :: IO TSCMark

-- | Mark a time interval for calculating the CPU clock frequency.
mark :: TSCMark -> IO ()

-- | Unmark a time interval for calculating the CPU clock frequency.
unmark :: TSCMark -> IO ()

-- | Calculate the CPU clock frequency in MHz, for an interval, marked with
--   <a>mark</a>, and <a>unmark</a>. If the interval is insufficient, the
--   result will be -1.
clockBy :: TSCMark -> IO Int