Class: VirtualBox::Vm::Board

Inherits:
Object
  • Object
show all
Defined in:
lib/virtual_box/vm/board.rb

Overview

Specification for a virtual machine’s motherboard.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Board

Creates a new motherboard specification based on the given attributes.

Parameters:

  • options (Hash<Symbol, Object>) (defaults to: {}) —

    ActiveRecord-style initial values for attributes; can be used together with Board#to_hash to save and restore



104
105
106
107
 
# File 'lib/virtual_box/vm/board.rb', line 104

def initialize(options = {})
  reset
  options.each { |k, v| self.send :"#{k}=", v }
end

Instance Attribute Details

#accelerate_3d ⇒ Boolean

Whether the VM supports 3D acceleration.

3D acceleration will only work with the proper guest extensions.

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/virtual_box/vm/board.rb', line 63

def accelerate_3d
  @accelerate_3d
end

#acpi ⇒ Boolean

Whether the VM supports ACPI.

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/virtual_box/vm/board.rb', line 33

def acpi
  @acpi
end

#audio ⇒ Boolean

True if the motherboard includes an audio chipset.

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/virtual_box/vm/board.rb', line 91

def audio
  @audio
end

#bios_boot_menu ⇒ Boolean, Symbol

Whether the BIOS allows the user to temporarily override the boot VM device.

If false, no override is allowed. Otherwise, the user can press F12 at boot time to select a boot device. The user gets a prompt at boot time if the value is true. If the value is :menu_only the user does not get a prompt, but can still press F12 to select a device.

Returns:

  • (Boolean, Symbol) 


81
82
83
 
# File 'lib/virtual_box/vm/board.rb', line 81

def bios_boot_menu
  @bios_boot_menu
end

#bios_logo_display_time ⇒ Integer

The number of seconds to display the BIOS logo when the board boots.

Returns:

  • (Integer) 


73
74
75
 
# File 'lib/virtual_box/vm/board.rb', line 73

def bios_logo_display_time
  @bios_logo_display_time
end

#bios_logo_fade_in ⇒ Boolean

Whether the BIOS logo will fade in when the board boots.

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/virtual_box/vm/board.rb', line 67

def bios_logo_fade_in
  @bios_logo_fade_in
end

#bios_logo_fade_out ⇒ Boolean

Whether the BIOS logo will fade out when the board boots.

Returns:

  • (Boolean) 


70
71
72
 
# File 'lib/virtual_box/vm/board.rb', line 70

def bios_logo_fade_out
  @bios_logo_fade_out
end

#boot_order ⇒ Array<Symbol>

Indicates the boot device search order for the VM’s BIOS.

This is an array that can contain the following symbols: :floppy+, :dvd, :disk, :net. Symbols should not be repeated.

Returns:

  • (Array<Symbol>) 


87
88
89
 
# File 'lib/virtual_box/vm/board.rb', line 87

def boot_order
  @boot_order
end

#cpus ⇒ Integer

The number of CPUs (cores) on this board.

Returns:

  • (Integer) 


9
10
11
 
# File 'lib/virtual_box/vm/board.rb', line 9

def cpus
  @cpus
end

#efi ⇒ Boolean

If true, EFI firmware will be used instead of BIOS, for booting.

The VirtualBox documentation states that EFI booting is highly experimental, and should only be used to virtualize MacOS.

Returns:

  • (Boolean) 


98
99
100
 
# File 'lib/virtual_box/vm/board.rb', line 98

def efi
  @efi
end

#hardware_id ⇒ String

The UUID presented to the guest OS.

Returns:

  • (String) 


20
21
22
 
# File 'lib/virtual_box/vm/board.rb', line 20

def hardware_id
  @hardware_id
end

#hardware_virtualization ⇒ Boolean

Whether the VMM attempts to use hardware support (Intel VT-x or AMD-V).

Hardware virtualization can increase VM performance, especially used in conjunction with the other hardware virtualization options. However, using hardware virtualization in conjunction with other hypervisors can crash the host machine.

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/virtual_box/vm/board.rb', line 47

def hardware_virtualization
  @hardware_virtualization
end

#io_apic ⇒ Boolean

Whether the VM supports I/O APIC.

This is necessary for 64-bit OSes, but makes the virtualization slower.

Returns:

  • (Boolean) 


38
39
40
 
# File 'lib/virtual_box/vm/board.rb', line 38

def io_apic
  @io_apic
end

#nested_paging ⇒ Boolean

Whether the VMM uses hardware support for nested paging.

The option is used only if hardware_virtualization is set.

Returns:

  • (Boolean) 


52
53
54
 
# File 'lib/virtual_box/vm/board.rb', line 52

def nested_paging
  @nested_paging
end

#os ⇒ Symbol

The OS that will be running in the virtualized VM.

Used to improve the virtualization performance.

Returns:

  • (Symbol) 


26
27
28
 
# File 'lib/virtual_box/vm/board.rb', line 26

def os
  @os
end

#pae ⇒ Boolean

Whether the VM supports PAE (36-bit address space).

Returns:

  • (Boolean) 


30
31
32
 
# File 'lib/virtual_box/vm/board.rb', line 30

def pae
  @pae
end

#ram ⇒ Integer

The amount of megabytes of RAM on this board.

Returns:

  • (Integer) 


13
14
15
 
# File 'lib/virtual_box/vm/board.rb', line 13

def ram
  @ram
end

#tagged_tlb ⇒ Boolean

Whether the VMM uses hardware support for tagged TLB (VPID).

The option is used only if hardware_virtualization is set.

Returns:

  • (Boolean) 


57
58
59
 
# File 'lib/virtual_box/vm/board.rb', line 57

def tagged_tlb
  @tagged_tlb
end

#video_ram ⇒ Integer

The amount of megabytes of video RAM on this board’s video card.

Returns:

  • (Integer) 


16
17
18
 
# File 'lib/virtual_box/vm/board.rb', line 16

def video_ram
  @video_ram
end

Class Method Details

.list_os_types ⇒ Hash<String, String> mapping from each VirtualBox OS type ID to its description

Queries VirtualBox for available OS types.

Returns:

  • (Hash<String, String> mapping from each VirtualBox OS type ID to its description) —

    Hash<String, String> mapping from each VirtualBox OS type ID to its description



274
275
276
277
278
279
280
281
282
 
# File 'lib/virtual_box/vm/board.rb', line 274

def self.list_os_types
  output = VirtualBox.run_command! ['VBoxManage', '--nologo', 'list',
                                    '--long', 'ostypes']
  types = output.split("\n\n").map do |os_info|
    i = Hash[os_info.split("\n").map { |line| line.split(':').map(&:strip) }]
    [i['ID'], i['Description']]
  end
  Hash[types]
end

.os_types ⇒ Hash<Symbol|String, String|Symbol>

The OS types supported by the VirtualBox installation.

Returns:

  • (Hash<Symbol|String, String|Symbol>) —

    mapping from programmer-friendly symbols (e.g. :linux26) to proper VirtualBox OS IDs, and from VirtualBox IDs and description strings to programmer-friendly symbols



256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/virtual_box/vm/board.rb', line 256

def self.os_types
  return @os_types if @os_types
  
  @os_types = {}
  list_os_types.each do |key, value|
    os_id = key.downcase.to_sym
    @os_types[key] = os_id
    @os_types[key.downcase] = os_id
    @os_types[value] = os_id
    @os_types[os_id] = key
  end
  @os_types
end

Instance Method Details

#from_params(params) ⇒ VirtualBox::Vm::Board

Parses “VBoxManage showvminfo –machinereadable” output into this instance.

Parameters:

  • params (Hash<String, String>) —

    the “VBoxManage showvminfo” output, parsed by Vm.parse_machine_readble

Returns:



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/virtual_box/vm/board.rb', line 162

def from_params(params)
  self.cpus = params['cpus'].to_i
  self.ram = params['memory'].to_i
  self.video_ram = params['vram'].to_i
  self.hardware_id = params['hardwareuuid']
  self.os = self.class.os_types[params['ostype']]

  self.pae = params['pae'] == 'on'    
  self.acpi = params['acpi'] == 'on'    
  self.io_apic = params['io_apic'] == 'on'    

  self.hardware_virtualization = params['hwvirtex'] == 'on'    
  self.nested_paging = params['nestedpaging'] == 'on'    
  self.tagged_tlb = params['vtxvpid'] == 'on'    

  self.efi = params['firmware'] == 'efi'
  self.bios_logo_fade_in = params['bioslogofadein'] == 'on'
  self.bios_logo_fade_out = params['bioslogofadeout'] == 'on'
  self.bios_logo_display_time = params['bioslogodisplaytime'].to_i
  
  self.bios_boot_menu = case params['bootmenu']
  when 'disabled'
     false
  when 'message'
    :menu_only
  else
    true
  end
  
  self.boot_order = []
  %w(boot1 boot2 boot3 boot4).each do |boot_key|
    next unless params[boot_key] && params[boot_key] != 'none'
    boot_order << params[boot_key].to_sym
  end
  
  self.audio = params['audio'] != 'none'
  
  self
end

#reset ⇒ VirtualBox::Vm::Board

Resets to default settings.

The defaults are chosen somewhat arbitrarily by the gem’s author.

Returns:



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/virtual_box/vm/board.rb', line 206

def reset
  self.cpus = 1
  self.ram = 512
  self.video_ram = 18
  self.hardware_id = UUID.generate

  self.os = :other    
  self.pae = false
  self.acpi = true
  self.io_apic = false
  
  self.hardware_virtualization = true
  self.nested_paging = true
  self.tagged_tlb = true
  self.accelerate_3d = false
  
  self.efi = false
  self.bios_logo_fade_in = false    
  self.bios_logo_fade_out = false
  self.bios_logo_display_time = 0
  self.bios_boot_menu = false
  
  self.boot_order = [:disk, :net, :dvd]
  
  self.audio = false
  self
end

#to_hash ⇒ Hash<Symbol, Object>

Hash capturing this motherboard specification. Can be passed to Board#new.

Returns:

  • (Hash<Symbol, Object>) —

    Ruby-friendly Hash that can be used to re-create this motherboard specification



238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/virtual_box/vm/board.rb', line 238

def to_hash
  { :cpus => cpus, :ram => ram, :video_ram => video_ram,
    :hardware_id => hardware_id, :os => os, :pae => pae, :acpi => acpi,
    :io_apic => io_apic, :hardware_virtualization => hardware_virtualization,
    :nested_paging => nested_paging, :tagged_tlb => tagged_tlb,
    :accelerate_3d => accelerate_3d, :efi => efi,
    :bios_logo_fade_in => bios_logo_fade_in,
    :bios_logo_fade_out => bios_logo_fade_out,
    :bios_logo_display_time => bios_logo_display_time,
    :bios_boot_menu => bios_boot_menu, :audio => audio }
end

#to_params ⇒ Array<String>

Arguments to “VBoxManage modifyvm” describing the VM’s general settings.

Returns:

  • (Array<String>) —

    arguments that can be concatenated to a “VBoxManage modifyvm” command



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/virtual_box/vm/board.rb', line 113

def to_params
  params = []
  params.push '--cpus', cpus.to_s
  params.push '--memory', ram.to_s
  params.push '--vram', video_ram.to_s
  params.push '--hardwareuuid', hardware_id
  params.push '--ostype',
             self.class.os_types[self.class.os_types[os.to_s]]
      
  params.push '--pae', pae ? 'on' : 'off'
  params.push '--acpi', acpi ? 'on' : 'off'
  params.push '--ioapic', io_apic ? 'on' : 'off'
  
  params.push '--hwvirtex', hardware_virtualization ? 'on' : 'off'
  params.push '--nestedpaging',
      (hardware_virtualization && nested_paging) ? 'on' : 'off'
  params.push '--vtxvpid',
      (hardware_virtualization && tagged_tlb) ? 'on' : 'off'
  
  params.push '--firmware', efi ? 'efi' : 'bios'
  params.push '--bioslogofadein', bios_logo_fade_in ? 'on' : 'off'
  params.push '--bioslogofadeout', bios_logo_fade_out ? 'on' : 'off'
  params.push '--bioslogodisplaytime', bios_logo_display_time.to_s

  bios_boot_menu_str = case bios_boot_menu
  when false
    'disabled'
  when :menu_only
    'message'
  else
    'messageandmenu'
  end
  params.push '--biosbootmenu', bios_boot_menu_str
  unique_boot_order = boot_order.uniq
  1.upto(4) do |i|
    device = unique_boot_order[i - 1]
    params.push "--boot#{i}", (device ? device.to_s : 'none')
  end
  
  params.push '--audio', (audio ? 'null' : 'none') 
  
  params
end