hyperctl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd42c9d0ce6995577336ac5d079c38b2dbcf5f0b
+  data.tar.gz: d71520d05bb74c3bb584868fbdb9663be22b7b6c
+SHA512:
+  metadata.gz: d90ca4e32248d536a58eb2a9f463e69caa9cbf8617d2d9e0b86358f38f95e2727292476c0ac94ba5acceadf373ee4c6db6075f7cacbd19acfbad78f63bc856d8
+  data.tar.gz: f3fdfd9fbc3ee5c449efddcd8af2daf59ed74123efe78769add4bffd3d9e7ae87942133907d3504cc65c51fb7a8f4783f2313056f63eaa2d2e511b2c24d4d523

data/.gitignore

@@ -0,0 +1,12 @@
+.bundle
+doc/
+*.gem
+Gemfile.lock
+*.orig
+*.patch
+*.rej
+.ruby-version
+*.swp
+tmp/aruba/
+.vagrant
+.yardoc

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+script: "bundle exec rake spec"
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,200 @@
+Ruby hyperctl Gem
+=================
+
+[![Build Status](https://travis-ci.org/jhoblitt/hyperctl.png)](https://travis-ci.org/jhoblitt/hyperctl)
+
+#### Table of Contents
+
+1. [Summary](#summary)
+2. [Description](#description)
+3. [Install](#install)
+4. [Usage](#usage)
+5. [Versioning](#versioning)
+6. [Support](#support)
+7. [Contributing](#contributing)
+8. [See Also](#see-also)
+
+Summary
+-------
+
+A utility for enabling/disabling hyperthreading
+
+
+Description
+-----------
+
+This Gem provides a simple cli utility named `hyperctl` that can check the
+status of and [with appropriate permissions] enable/disable
+hyperthreading/SMT/sibling cores on Linux via the
+[`sysfs`](https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt)
+pseudo filesystem.  It should be compatible with most modern Linux
+distributions as long as `sysfs` is mounted at `/sysfs`.
+
+
+Install
+-------
+
+### via rubygems
+
+    gem install hyperctl
+
+### from git repo with bundler
+
+    bundle install
+    bundle exec rake install
+
+
+Usage
+-----
+
+### `hyperctl`
+
+    Usage:
+      hyperctl
+      hyperctl (--enable | --disable) [--quiet]
+      hyperctl --status (--enable | --disable) [--quiet]
+      hyperctl -h | --help
+      hyperctl --version
+
+    Options:
+      --enable      Enable hyperthreading.
+      --disable     Diable hyperthreading.
+      --status      Report hyperthreading state.
+      --quiet       Suppress stdout.
+      --version     Show version.
+      -h --help     Show this screen.
+
+#### Exit codes
+
+* `0` - success
+* `1` - option parsing related error
+* `2` - system error (Eg., permission denied)
+* `3` - status does not match desired state
+
+#### no options
+
+Prints the current status of hyperthreading on the system to the `stdout`.
+Exits with `0` if no errors were encountered.
+
+    $ hyperctl
+    cpu0 : enabled  - hypertheading: enabled
+    cpu1 : enabled  - hypertheading: enabled
+    cpu2 : enabled  - hypertheading: enabled
+    cpu3 : enabled  - hypertheading: enabled
+    cpu4 : enabled  - hypertheading: enabled
+    cpu5 : enabled  - hypertheading: enabled
+    cpu6 : enabled  - hypertheading: enabled
+    cpu7 : enabled  - hypertheading: enabled
+
+#### `(--enable | --disable) [--quiet]`
+
+Attempt to enable or disable all hyperthread/SMT/sibling cores on the system.
+Exits with `0` upon success, `2` for system errors, or `3` for state change
+failures (unlikely).
+
+With appropriate permissions to modify the appropriate sysfs entries:
+
+    $ sudo hyperctl --disable
+    cpu0 : enabled  - hypertheading: disabled
+    cpu1 : enabled  - hypertheading: disabled
+    cpu2 : enabled  - hypertheading: disabled
+    cpu3 : enabled  - hypertheading: disabled
+    cpu4 : disabled - hypertheading: disabled
+    cpu5 : disabled - hypertheading: disabled
+    cpu6 : disabled - hypertheading: disabled
+    cpu7 : disabled - hypertheading: disabled
+    $ echo $?
+    0
+
+Without appropriate permissions:
+
+    $ hyperctl --disable
+    Permission denied @ rb_sysopen - /sys/devices/system/cpu/cpu4/online
+    $ echo $?
+    2
+
+#### `--status (--enable | --disable) [--quiet]`
+
+Checks the status of hyperthread/SMT/sibling cores on the system. Exits with
+`0` if the state matches the `(--enable | --disable)` option, otherwise with
+`3`
+
+System already in `--disable` state:
+
+    $ sudo hyperctl --status --disable
+    cpu0 : enabled  - hypertheading: disabled
+    cpu1 : enabled  - hypertheading: disabled
+    cpu2 : enabled  - hypertheading: disabled
+    cpu3 : enabled  - hypertheading: disabled
+    cpu4 : disabled - hypertheading: disabled
+    cpu5 : disabled - hypertheading: disabled
+    cpu6 : disabled - hypertheading: disabled
+    cpu7 : disabled - hypertheading: disabled
+    $ echo $?
+    0
+
+System not in `--enable` state:
+
+    $ sudo hyperctl --status --enable
+    cpu0 : enabled  - hypertheading: disabled
+    cpu1 : enabled  - hypertheading: disabled
+    cpu2 : enabled  - hypertheading: disabled
+    cpu3 : enabled  - hypertheading: disabled
+    cpu4 : disabled - hypertheading: disabled
+    cpu5 : disabled - hypertheading: disabled
+    cpu6 : disabled - hypertheading: disabled
+    cpu7 : disabled - hypertheading: disabled
+    $ echo $?
+    3
+
+#### `[--quiet]`
+
+Suppresses the `stdout` status message.  Intended for usage from scripts.
+
+    $ sudo hyperctl --status --enable --quiet
+    $ echo $?
+    3
+
+    $ sudo hyperctl --status --disable --quiet
+    $ echo $?
+    0
+
+
+Versioning
+----------
+
+This Gem is versioned according to the [Semantic Versioning
+2.0.0](http://semver.org/spec/v2.0.0.html) specification.
+
+
+Support
+-------
+
+Please log tickets and issues at [github](https://github.com/jhoblitt/hyperctl)
+
+
+Contributing
+------------
+
+1. Fork it on github
+2. Make a local clone of your fork
+3. Create a topic branch.  Eg, `feature/mousetrap`
+4. Make/commit changes
+    * Commit messages should be in
+      [imperative tense](http://git-scm.com/book/ch5-2.html)
+    * Check that `Rspec` unit tests are not broken and coverage is added for
+      new features - `bundle exec rake spec`
+    * Documentation of API/features is updated as appropriate in the README
+5. When the feature is complete, rebase / squash the branch history as
+   necessary to remove "fix typo", "oops", "whitespace" and other trivial
+   commits
+6. Push the topic branch to github
+7. Open a Pull Request (PR) from the *topic branch* onto parent repo's `master`
+   branch
+
+
+See Also
+--------
+
+* [Linux sysfs docs](https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt)
+* [Linux cpu-hotplug docs](https://www.kernel.org/doc/Documentation/cpu-hotplug.txt)

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new do |t|
+  t.files         = ['lib/**/*.rb']
+  t.stats_options = ['--list-undoc']
+end
+
+task :default => [
+  :spec,
+]

data/bin/hyperctl

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+
+require 'hyperctl'
+require "docopt"
+
+doc = <<DOCOPT
+#{__FILE__}
+
+Usage:
+  #{__FILE__}
+  #{__FILE__} (--enable | --disable) [--quiet]
+  #{__FILE__} --status (--enable | --disable) [--quiet]
+  #{__FILE__} -h | --help
+  #{__FILE__} --version
+
+Options:
+  --enable      Enable hyperthreading.
+  --disable     Diable hyperthreading.
+  --status      Report hyperthreading state.
+  --quiet       Suppress stdout.
+  --version     Show version.
+  -h --help     Show this screen.
+
+DOCOPT
+
+
+@options = {}
+begin
+  @options = Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+  exit 1
+end
+
+if @options['--version']
+  puts Hyperctl::VERSION
+  exit 0
+end
+
+hctl = Hyperctl::Sysfs.new
+
+exit_code = 0
+
+begin
+  if @options['--status']
+    exit_code = check_status(hctl)
+  elsif @options['--enable'] || @options['--disable']
+    exit_code = change_state(hctl)
+  end
+
+  unless @options['--quiet']
+    text = Hyperctl.status(hctl)
+    puts text
+  end
+rescue Errno::EACCES => e
+  puts e.message
+  exit 2
+end
+
+exit exit_code
+
+BEGIN {
+  def change_state(hctl)
+    if @options['--enable']
+      Hyperctl.enable(hctl)
+      hctl.refresh
+      return check_status(hctl)
+    end
+
+    if @options['--disable']
+      Hyperctl.disable(hctl)
+      hctl.refresh
+      return check_status(hctl)
+    end
+
+    raise
+  end
+
+  def check_status(hctl)
+    if @options['--enable']
+      return hctl.all_cores_enabled? ? 0 : 3
+    end
+
+    if @options['--disable']
+      return hctl.all_siblings_disabled? ? 0 : 3
+    end
+
+    raise
+  end
+}

data/hyperctl.gemspec

@@ -0,0 +1,33 @@
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+require 'hyperctl/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'hyperctl'
+  s.version     = Hyperctl::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Joshua Hoblitt']
+  s.email       = ['jhoblitt@cpan.org']
+  s.homepage    = 'https://github.com/jhoblitt/hyperctl'
+  s.summary     = %q{A utility for enabling/disabling hyperthreading}
+  s.description = %q{This Gem provides a simple cli utility named `hyperctl`
+that can check the status of and [with appropriate permissions] enable/disable
+hyperthreading/SMT/sibling cores on Linux via the `sysfs` pseudo filesystem.
+It should be compatible with most modern Linux distributions as long as `sysfs` is mounted at `/sysfs`.}
+  s.license     = 'Apache 2.0'
+
+  s.required_ruby_version = '>= 1.8.7'
+  s.add_runtime_dependency('docopt', '~> 0.5.0')
+  s.add_development_dependency('rspec', '~> 3.0')
+  s.add_development_dependency('rspec-expectations', '~> 3.0')
+  s.add_development_dependency('rspec-mocks', '~> 3.0')
+  s.add_development_dependency('rake', '~> 10.0')
+  s.add_development_dependency('fakefs', '~> 0.5.2')
+  s.add_development_dependency('mocha', '~> 1.0')
+  s.add_development_dependency('yard', '~> 0.8')
+
+  s.rubygems_version = '>= 1.6.1'
+  s.files            = `git ls-files`.split("\n")
+  s.test_files       = `git ls-files -- {spec,features}/*`.split("\n")
+  s.executables      = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_path     = 'lib'
+end

data/lib/hyperctl/sysfs.rb

@@ -0,0 +1,189 @@
+class Hyperctl::Sysfs
+  attr_accessor :cpu_info
+
+  # @api private
+  def initialize
+    @cpu_info = refresh
+  end
+
+  # Refresh the `cpu_info` [Hash] of the current CPU states
+  #
+  # @return [Hash] of cpu status
+  # @api public
+  def refresh
+    info = {}
+
+    # get a listing of all cpu cores
+    cpu_dirs = Dir.glob('/sys/devices/system/cpu/cpu[0-9]*')
+
+    cpu_dirs.each do |d|
+      # find the "name" of the cpu based on the sysfs dir. Eg, cpu15
+      cpu_name = File.basename d
+      cpu_idx = cpu_name.to_sym
+      info[cpu_idx] = { :name => cpu_name }
+
+      # find the numeric core_id. Eg, 15 in sysfs as
+      # /sys/devices/system/cpu/cpu3/topology/core_id but we can parse it from
+      # the path
+      core_id = cpu_name.match(/cpu(\d+)/)[1].to_i
+      info[cpu_idx][:core_id] = core_id
+
+      # is the cpu online?
+      # if a CPU is online, /sys/devices/system/cpu/cpu1/online will be 1,
+      # otherwise 0.  cpu0 appears to be special and does not have the online
+      # sysfs entry on any of the systems I inspected. I suspect that it might
+      # get this attribute if CONFIG_BOOTPARAM_HOTPLUG_CPU0 is enabled per
+      # https://www.kernel.org/doc/Documentation/cpu-hotplug.txt
+      path = File.join(d, 'online')
+      online = false
+      if File.exist?(path)
+        online = to_bool(File.read(path).chomp)
+      elsif core_id == 0
+        # cpu0 gets a special pass if the online attr is missing
+        online = true
+      end
+      info[cpu_idx][:online] = online
+
+      next unless online
+
+      # does the cpu have any [SMT] siblings?
+      # The attr /sys/devices/system/cpu/cpu6/topology/thread_siblings_list
+      # will list all siblings including the cpu's own core_id This attr is not
+      # present if the cpu is offline This attr is not present under EL5.x
+      # (2.6.18-164.el5PAE) on the one system I inspected that appears to have
+      # HT disabled in the bios (/proc/cpuinfo shows the ht cpu flag but
+      # there's no siblings list)
+      path = File.join(d, 'topology/thread_siblings_list')
+      if File.exist?(path)
+        sibs = File.read(path).chomp.split(',')
+        # convert core_id(s) to be numeric
+        sibs.map! {|s| s.to_i }
+        # remove the cpu's core_id from the list
+        sibs = sibs - [ core_id ]
+        unless sibs.empty?
+          info[cpu_idx][:thread_siblings_list] = sibs
+        end
+      end
+    end
+
+    @cpu_info = info
+  end
+
+  # List of all CPUs in system by numeric core id
+  #
+  # @return [Array<Integer>] of core ids
+  # @api public
+  def cores
+    cores = []
+    cpu_info.each_key.sort_by {|k| cpu_info[k][:core_id] }.each do |k|
+      cores << cpu_info[k][:core_id]
+    end
+
+    return cores
+  end
+
+  # List of online CPUs in system by numeric core id
+  #
+  # @return [Array<Integer>] of core ids
+  # @api public
+  def online_cores
+    cores = []
+    cpu_info.each_key.sort_by {|k| cpu_info[k][:core_id] }.each do |k|
+      core_id = cpu_info[k][:core_id]
+      if cpu_info[k][:online] == true
+        cores << core_id
+      end
+    end
+
+    return cores
+  end
+
+  # List of offline CPUs in system by numeric core id
+  #
+  # @return [Array<Integer>] of core ids
+  # @api public
+  def offline_cores
+    cores = []
+    cpu_info.each_key.sort_by {|k| cpu_info[k][:core_id] }.each do |k|
+      core_id = cpu_info[k][:core_id]
+      if cpu_info[k][:online] == false
+        cores << core_id
+      end
+    end
+
+    return cores
+  end
+
+  # List of sibling (aka hyperthread/SMT) CPUs in system by numeric core id
+  #
+  # @return [Array<Integer>] of core ids
+  # @api public
+  def sibling_cores
+    cores = []
+    checked_cores = []
+    cpu_info.each_key.sort_by {|k| cpu_info[k][:core_id] }.each do |k|
+      cpu = cpu_info[k]
+      checked_cores << cpu[:core_id]
+
+      if cpu.has_key?(:thread_siblings_list)
+        (cpu[:thread_siblings_list] - checked_cores).each do |core_id|
+          # check to see if the core is already disabled
+          # XXX this probably isn't nessicary as a disabled core appears to #
+          # never be listed as a sibiling
+          if cpu_info[k][:online] == true
+            cores << core_id
+          end
+        end
+      end
+    end
+
+    return cores
+  end
+
+  # Are all phyical/hyperthread/SMT/sibling cores enabled?
+  #
+  # @return [Bool] of status
+  # @api public
+  def all_cores_enabled?
+    cores.count == online_cores.count
+  end
+
+  # Are all hyperthread/SMT/sibling cores Disabled?
+  #
+  # @return [Bool] of status
+  # @api public
+  def all_siblings_disabled?
+    sibling_cores.empty?
+  end
+
+  # Enable a CPU by numeric core id
+  #
+  # @param core_id [Integer]
+  # @api public
+  def self.enable_core(core_id)
+    set_core(core_id, '1')
+  end
+
+  # Disable a CPU by numeric core id
+  #
+  # @param core_id [Integer]
+  # @api public
+  def self.disable_core(core_id)
+    set_core(core_id, '0')
+  end
+
+  private
+
+  def to_bool(s)
+    return true if s =~ /^1$/
+    return false
+  end
+
+  def self.set_core(core_id, state)
+    path = File.join('/sys/devices/system/cpu', "cpu#{core_id.to_s}", 'online')
+    # doesn't work in ruby 1.8.7: File.write(path, '0')
+    File.open(path, 'w') do |f|
+      f.write(state)
+    end
+  end
+end # class Hyperctl::Sysfs

data/lib/hyperctl/version.rb

@@ -0,0 +1,3 @@
+module Hyperctl
+  VERSION = '0.1.0'
+end

data/lib/hyperctl.rb

@@ -0,0 +1,43 @@
+require 'hyperctl/sysfs'
+
+module Hyperctl
+  # Enable all sibling cores
+  #
+  # @param hctl [Hyperctl::Sysfs] object
+  # @api public
+  def self.enable(hctl)
+    # as far as I can tell, there's no way to discover the topology information
+    # for which cores and siblings if either of them is disabled.  So we are
+    # just trying to enable everything that is disabled...
+    cores = hctl.offline_cores
+    cores.each {|core_id| Hyperctl::Sysfs.enable_core(core_id) }
+  end
+
+  # Disable all sibling cores
+  #
+  # @param hctl [Hyperctl::Sysfs] object
+  # @api public
+  def self.disable(hctl)
+    cores = hctl.sibling_cores
+    cores.each {|core_id| Hyperctl::Sysfs.disable_core(core_id) }
+  end
+
+  # Generate a pretty formatted string of sibling core status
+  #
+  # @param hctl [Hyperctl::Sysfs] object
+  # @return [String] the generated string
+  # @api public
+  def self.status(hctl)
+    cpu_info = hctl.cpu_info
+    text = ""
+    cpu_info.each_key.sort_by {|k| cpu_info[k][:core_id] }.each do |k|
+      cpu = cpu_info[k]
+      state = cpu[:online] ? 'enabled' : 'disabled'
+      ht = cpu.has_key?(:thread_siblings_list) ? 'enabled' : 'disabled'
+      text << "#{sprintf('%-5s',k.to_s)}: #{sprintf('%-8s', state)}"
+      text << " - hypertheading: #{ht}\n"
+    end
+
+    return text
+  end
+end # module Hyperctl

data/spec/hyperctl_spec.rb

@@ -0,0 +1,123 @@
+require 'spec_helper'
+
+describe Hyperctl do
+  let(:hctl) { Hyperctl::Sysfs.new }
+
+  describe '#status' do
+    context '8 physical cores with HT enabled' do
+      include_context "cpuinfo_8core_w_ht"
+
+      text =<<EOS
+cpu0 : enabled  - hypertheading: enabled
+cpu1 : enabled  - hypertheading: enabled
+cpu2 : enabled  - hypertheading: enabled
+cpu3 : enabled  - hypertheading: enabled
+cpu4 : enabled  - hypertheading: enabled
+cpu5 : enabled  - hypertheading: enabled
+cpu6 : enabled  - hypertheading: enabled
+cpu7 : enabled  - hypertheading: enabled
+cpu8 : enabled  - hypertheading: enabled
+cpu9 : enabled  - hypertheading: enabled
+cpu10: enabled  - hypertheading: enabled
+cpu11: enabled  - hypertheading: enabled
+cpu12: enabled  - hypertheading: enabled
+cpu13: enabled  - hypertheading: enabled
+cpu14: enabled  - hypertheading: enabled
+cpu15: enabled  - hypertheading: enabled
+EOS
+      it do
+        hctl.stubs(:cpu_info).returns(info)
+        expect(Hyperctl.status(hctl)).to eq(text)
+      end
+    end # 8 physical cores with HT enabled
+
+    context '12 physical cores with HT disabled' do
+      include_context "cpuinfo_12core_wo_ht"
+      text =<<EOS
+cpu0 : enabled  - hypertheading: disabled
+cpu1 : enabled  - hypertheading: disabled
+cpu2 : enabled  - hypertheading: disabled
+cpu3 : enabled  - hypertheading: disabled
+cpu4 : enabled  - hypertheading: disabled
+cpu5 : enabled  - hypertheading: disabled
+cpu6 : enabled  - hypertheading: disabled
+cpu7 : enabled  - hypertheading: disabled
+cpu8 : enabled  - hypertheading: disabled
+cpu9 : enabled  - hypertheading: disabled
+cpu10: enabled  - hypertheading: disabled
+cpu11: enabled  - hypertheading: disabled
+cpu12: disabled - hypertheading: disabled
+cpu13: disabled - hypertheading: disabled
+cpu14: disabled - hypertheading: disabled
+cpu15: disabled - hypertheading: disabled
+cpu16: disabled - hypertheading: disabled
+cpu17: disabled - hypertheading: disabled
+cpu18: disabled - hypertheading: disabled
+cpu19: disabled - hypertheading: disabled
+cpu20: disabled - hypertheading: disabled
+cpu21: disabled - hypertheading: disabled
+cpu22: disabled - hypertheading: disabled
+cpu23: disabled - hypertheading: disabled
+EOS
+      it do
+        hctl.stubs(:cpu_info).returns(info)
+
+        expect(Hyperctl.status(hctl)).to eq(text)
+      end
+    end # 12 physical cores with HT disabled
+  end #status
+
+  describe '#disable' do
+    context '8 physical cores with HT enabled' do
+      include_context "cpuinfo_8core_w_ht"
+
+      it 'should turn cores off' do
+        hctl.stubs(:cpu_info).returns(info)
+        8.upto(15).each do |core_id|
+          Hyperctl::Sysfs.expects(:disable_core).with(core_id).once
+        end
+
+        Hyperctl.disable(hctl)
+      end
+    end # 8 physical cores with HT enabled
+
+    context '12 physical cores with HT disabled' do
+      include_context "cpuinfo_12core_wo_ht"
+
+      it 'should do nothing' do
+        # all SMT cores are already disabled
+        hctl.stubs(:cpu_info).returns(info)
+        Hyperctl::Sysfs.expects(:disable_core).never
+
+        Hyperctl.disable(hctl)
+      end
+    end # 12 physical cores with HT disabled
+  end #disable
+
+  describe '#enable' do
+    context '8 physical cores with HT enabled' do
+      include_context "cpuinfo_8core_w_ht"
+
+      it 'should do nothing' do
+        # all SMT cores are already enabled
+        hctl.stubs(:cpu_info).returns(info)
+        Hyperctl::Sysfs.expects(:enable_core).never
+
+        Hyperctl.enable(hctl)
+      end
+    end # 8 physical cores with HT enabled
+
+    context '12 physical cores with HT disabled' do
+      include_context "cpuinfo_12core_wo_ht"
+
+      it 'should turn cores on' do
+        hctl.stubs(:cpu_info).returns(info)
+        12.upto(23).each do |core_id|
+          Hyperctl::Sysfs.expects(:enable_core).with(core_id).once
+        end
+
+        Hyperctl.enable(hctl)
+      end
+    end # 12 physical cores with HT disabled
+  end #enable
+end

data/spec/hyperctl_sysfs_spec.rb

@@ -0,0 +1,154 @@
+require 'spec_helper'
+# pp must be required before fakefs
+# see: https://github.com/defunkt/fakefs/issues/99
+require 'pp'
+require 'fakefs/spec_helpers'
+
+describe Hyperctl::Sysfs do
+  let(:hctl) { Hyperctl::Sysfs.new }
+  include FakeFS::SpecHelpers
+
+  context 'on a 8 physical core w/ HT enabled system' do
+    include_context "sysfs_8core_w_ht"
+    include_context "cpuinfo_8core_w_ht"
+
+    context 'fakefs sanity checks' do
+      it { expect(File.exists?(sysfs('cpu1', 'online'))).to be true }
+      it { expect(File.exists?(sysfs('cpu1', 'topology/thread_siblings_list'))).to be true }
+      it { expect(sysfs('cpu1', 'topology/thread_siblings_list')).to contain(/1,9/) }
+    end
+
+    describe '#new' do
+      it 'finds all the cores' do
+        expect(hctl.cpu_info).to eq(info)
+      end
+    end
+
+    describe '#disable_core' do
+      it 'disbles core_id 15' do
+        Hyperctl::Sysfs.disable_core(15)
+
+        expect(sysfs('cpu15', 'online')).to contain(/^0$/)
+      end
+    end
+
+    context '#cores' do
+      it 'lists all cores' do
+        expect(hctl.cores).to eq((0 .. 15).to_a)
+      end
+    end
+
+    context '#online_cores' do
+      it 'lists all enabled cores' do
+        expect(hctl.online_cores).to eq((0 .. 15).to_a)
+      end
+    end
+
+    context '#offline_cores' do
+      it 'lists all disabled cores' do
+        expect(hctl.offline_cores).to eq []
+      end
+    end
+
+    context '#sibling_cores' do
+      it 'lists all smt cores' do
+        expect(hctl.sibling_cores).to eq((8 .. 15).to_a)
+      end
+    end
+
+    context '#all_cores_enabled?' do
+      it 'returns true' do
+        expect(hctl.all_cores_enabled?).to be true
+      end
+    end
+
+    context '#all_siblings_disabled?' do
+      it 'returns false' do
+        expect(hctl.all_siblings_disabled?).to be false
+      end
+    end
+
+    context '#enable_core' do
+      it 'enables core_id 15' do
+        Hyperctl::Sysfs.enable_core(15)
+
+        expect(sysfs('cpu15', 'online')).to contain(/^1$/)
+      end
+    end
+  end # on a 8 physical core w/ HT enabled system
+
+  context 'on a 12 physical core w/ HT diabled system' do
+    include_context "sysfs_12core_wo_ht"
+    include_context "cpuinfo_12core_wo_ht"
+
+    context 'fakefs sanity checks' do
+      it { expect(File.exists?(sysfs('cpu0', 'online'))).to be false }
+      it { expect(File.exists?(sysfs('cpu0', 'topology/thread_siblings_list'))).to be true }
+
+      it { expect(File.exists?(sysfs('cpu1', 'online'))).to be true }
+      it { expect(File.exists?(sysfs('cpu1', 'topology/thread_siblings_list'))).to be true }
+
+      it { expect(File.exists?(sysfs('cpu23', 'online'))).to be true }
+      it { expect(File.exists?(sysfs('cpu23', 'topology/thread_siblings_list'))).to be false }
+    end
+
+    context '#new' do
+      it 'finds all the cores' do
+        hctl =  Hyperctl::Sysfs.new
+        expect(hctl.cpu_info).to eq(info)
+      end
+    end
+
+    context '#disable_core' do
+      it 'disbles core_id 15' do
+        Hyperctl::Sysfs.disable_core(15)
+
+        expect(sysfs('cpu15', 'online')).to contain(/^0$/)
+      end
+    end
+
+    context '#cores' do
+      it 'lists all cores' do
+        expect(hctl.cores).to eq((0 .. 23).to_a)
+      end
+    end
+
+    context '#online_cores' do
+      it 'lists all enabled cores' do
+        expect(hctl.online_cores).to eq((0 .. 11).to_a)
+      end
+    end
+
+    context '#offline_cores' do
+      it 'lists all disabled cores' do
+        expect(hctl.offline_cores).to eq((12 .. 23).to_a)
+      end
+    end
+
+    context '#sibling_cores' do
+      it 'lists all smt cores' do
+        expect(hctl.sibling_cores).to eq []
+      end
+    end
+
+    context '#all_cores_enabled?' do
+      it 'returns false' do
+        expect(hctl.all_cores_enabled?).to be false
+      end
+    end
+
+    context '#all_siblings_disabled?' do
+      it 'returns true' do
+        expect(hctl.all_siblings_disabled?).to be true
+      end
+    end
+
+    context '#enable_core' do
+      it 'enables core_id 15' do
+        Hyperctl::Sysfs.enable_core(15)
+
+        expect(sysfs('cpu15', 'online')).to contain(/^1$/)
+      end
+    end
+  end # on a 12 physical core w/ HT disabled system
+end

data/spec/spec_helper.rb

@@ -0,0 +1,102 @@
+require 'hyperctl'
+
+RSpec.configure do |config|
+  config.mock_framework = :mocha
+end
+
+def sysfs(cpu_name, attr)
+  File.join('/sys/devices/system/cpu/', cpu_name, attr)
+end
+
+def mksysfs(cpu_name, attr, value)
+  path = sysfs(cpu_name, attr)
+  dir  = File.dirname path
+  FileUtils.mkdir_p dir
+  File.open(path, 'w+') do |f|
+    f.write(value)
+  end
+end
+
+RSpec::Matchers.define :contain do |content|
+  match do |path|
+    File.read(path) =~ content
+  end
+end
+
+# 2.6.32-431.5.1.el6.x86_64
+# 2 x Intel(R) Xeon(R) CPU E5-2643 0 @ 3.30GHz
+RSpec.shared_context 'sysfs_8core_w_ht' do
+  before do
+    0.upto(15).each do |core_id|
+      next if core_id == 0
+      mksysfs("cpu#{core_id}", 'online', "1\n")
+    end
+    0.upto(7).each do |core_id|
+      mksysfs("cpu#{core_id}", 'topology/thread_siblings_list', "#{core_id},#{core_id + 8}\n")
+    end
+    8.upto(15).each do |core_id|
+      mksysfs("cpu#{core_id}", 'topology/thread_siblings_list', "#{core_id},#{core_id - 8}\n")
+    end
+  end
+end
+
+RSpec.shared_context 'cpuinfo_8core_w_ht' do
+  info = {}
+  0.upto(7).each do |core_id|
+    name = "cpu#{core_id}"
+    info[name.to_sym] = {
+      :core_id              => core_id,
+      :online               => true,
+      :thread_siblings_list => [ core_id + 8 ],
+      :name                 => name,
+    }
+  end
+  8.upto(15).each do |core_id|
+    name = "cpu#{core_id}"
+    info[name.to_sym] = {
+      :core_id              => core_id,
+      :online               => true,
+      :thread_siblings_list => [ core_id - 8 ],
+      :name                 => name,
+    }
+  end
+
+  let(:info) { info }
+end
+
+# 2.6.32-431.5.1.el6.x86_64
+# 2 x Intel(R) Xeon(R) CPU           X5675  @ 3.07GHz
+RSpec.shared_context 'sysfs_12core_wo_ht' do
+  before do
+    0.upto(11).each do |core_id|
+      mksysfs("cpu#{core_id}", 'topology/thread_siblings_list', "#{core_id}\n")
+      next if core_id == 0
+      mksysfs("cpu#{core_id}", 'online', "1\n")
+    end
+    12.upto(23).each do |core_id|
+      mksysfs("cpu#{core_id}", 'online', "0\n")
+    end
+  end
+end
+
+RSpec.shared_context 'cpuinfo_12core_wo_ht' do
+  info = {}
+  0.upto(11).each do |core_id|
+    name = "cpu#{core_id}"
+    info[name.to_sym] = {
+      :core_id              => core_id,
+      :online               => true,
+      :name                 => name,
+    }
+  end
+  12.upto(23).each do |core_id|
+    name = "cpu#{core_id}"
+    info[name.to_sym] = {
+      :core_id              => core_id,
+      :online               => false,
+      :name                 => name,
+    }
+  end
+
+  let(:info) { info }
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: hyperctl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joshua Hoblitt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docopt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: |-
+  This Gem provides a simple cli utility named `hyperctl`
+  that can check the status of and [with appropriate permissions] enable/disable
+  hyperthreading/SMT/sibling cores on Linux via the `sysfs` pseudo filesystem.
+  It should be compatible with most modern Linux distributions as long as `sysfs` is mounted at `/sysfs`.
+email:
+- jhoblitt@cpan.org
+executables:
+- hyperctl
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/hyperctl
+- hyperctl.gemspec
+- lib/hyperctl.rb
+- lib/hyperctl/sysfs.rb
+- lib/hyperctl/version.rb
+- spec/hyperctl_spec.rb
+- spec/hyperctl_sysfs_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/jhoblitt/hyperctl
+licenses:
+- Apache 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.4
+signing_key: 
+specification_version: 4
+summary: A utility for enabling/disabling hyperthreading
+test_files:
+- spec/hyperctl_spec.rb
+- spec/hyperctl_sysfs_spec.rb
+- spec/spec_helper.rb
+has_rdoc: