1. lxMicBoot

version_number=2.15.1.0001

1.1. Overview

Copyright (c) 2012-2013 Intel Corporation. All rights reserved.

Version:	2.15.1.0001
Released:	09/10/2014

Purpose
The purpose of this module is to provided Linux BASH scripts for booting and checking the status of the MIC uOS. These scripts 
can be used by other MIC test modules to boot the MIC uOS.

Runtime Environment
Linux system with MIC Linux loadable module. These scripts may be run stand alone in this environment or under the control of 
test modules running in the Intel(R) Modular Test Architecture Test Executive for Linux.

License Agreement
All code is under the Intel(R) software License which can be found at http://legal.intel.com. A copy of this agreement must be 
included if code is released outside Intel.

Hardware Description
MIC PCIe add in card, in a Linux based Host system. 




1.2. Version Info

 
Date		Version		Owner		Comments
04/04/2012	2.07.1.0001	DKJ		First official release, of 							this module.
							Initial version number 								based on script versions 								imported from lxMIcCfg and 
							lxMicMemory.
06/21/2012	2.08.1.0001	DKJ		Convert lxmicstart to use 								New MIC boot commands to 								control MIC uOS. Also:
							* Add support for 									  initializing micctrl 								  defaults
							* Add support for 									  initializing password-								  less SSH connection to 								  MIC uOS
07/31/2012	2.09.1.0001	DKJ		Change lxmicstart, so it 								does not wait for MIC to 								be in steady state
							before checking whether 								uOS is online
11/04/2012	2.10.1.0001	DKJ		Add more detail when 									lxmicstart fails to 									indicate why lxmicstart 								failed
11/30/2012	2.11.1.0001	DKJ		Adds check to verify that 								SELinux is disabled before 							booting the MIC uOS.
02/26/2013	2.12.1.0001	DKJ		Add calls to start micrasd 							when starting mpss service 							and booting uOS.
04/25/2013	2.13.1.0001	DKJ		Add -o option for 									lxmicstart, to support 								lxMicMonitor usage
10/02/2013	2.14.1.0001	DKJ		Added mic_id command line 								parameter to support 									operation with multiple 								MIC cards
09/10/2014	2.15.1.0001	DKJ		Fixed race condition in handling uOS_Temp file




	


				

1.3. Installation

Files installed by this module:
	
File	Description
lxMicBoot.txt	Text only help file.
lxMicBoot.chm	Smart help file.
lxmicstart		Script to boot MIC card
lxmicbooted	Script to check whether uOS is already booted on 			the MIC card, and boot if it isn't
lxmiccheck		Script to check whether uOS is already booted on 			the MIC card
lxmicready		Script which resets the MIC card to FW ready 				state
lxmicssh		Expect script which helps sets up password-less 			SSH access to the MIC uOS.
			This script assume MIC uOS is already booted and 			SSH keys already exist in $HOME/.ssh

NOTE: The scripts in this module are currently set to work with only one MIC card in a host system.

MPSS RPM:
A supported version of the MPSS RPM must be installed on the host host system.
This version requires at least MPSS 3126-13

Host board: 
The host board must be supported by the MPSS RPM team. Please see project contact for a list of 
supported boards. This release was tested with Intel Workstation Board W2600CR2.

Operating Systems:
The OS on the host board must be supported by the MPSS team. Currently, the supported OS are Red Hat 
Enterprise Linux 6.0 and Red Hat Desktop 6.0.

MIC card:
At least one supported MIC card must be plugged into a PCI-E slot on the supported host board. Please 
see project contact for a list of supported boards.

SELinux: 	There is a known issue with interaction between the MPSS SW and SELinux, that makes MIC uOS boot 
unreliable. The uOS Boot script in this module (i.e. lxmicstart) checks to verify that SELinux is Disabled 
before booting the MIC uOS.  If SELinux is not Disabled, lxmicstart will not boot the  MIC uOS, and will 
return a failure message indicating this.

To Disable SELinux:
*	On the host system, as root, edit /etc/selinux/config
*	Change the line which starts SELINUX=...  to 	SELINUX=disabled
*	Reboot the system
*	After the reboot use the command: sestatus to verify that 	SELinux is disabled.

To Re-Enable SELinux:
*	On the host system, as root, edit /etc/selinux/config
*	Change the line: SELINUX=disabled to SELINUX=permissive
*	Reboot the system.  During this reboot SELinux will detect 	the configuration change and will force file 
	label update, and then do a second reboot.
*	After reboot use the command: fixfiles relabel to update 	labels on all the files monitored by SELinux. 
	Responding N to question about cleaning out /tmp is OK.
*	Edit /etc/selinux/config and change SELINUX=permissive to 	SELINUX=enforcing
*	Then reboot again
*	After the reboot use the command: sestatus to verify that 	SELinux is enabled.  If the system 
	automatically starts CTC on reboot, sestatus will show the 	SELinux status as permissive since CTC 
	automatically sets SELinux to permissive mode when it 	starts, but only if SELinux is enabled.




1.4. Sub-Tests


lxmicbooted
lxmicstart
lxmiccheck
lxmicready
lxmicssh



1.5. lxmicbooted

Overview

This script is a wrapper for executing: lxmicstart check
This operation will:
*	Check whether the MIC uOS is booted on the MIC card specified by the mic_id command line parameter.
It reports success (i.e. PASSED) if the MIC status is online (i.e the uOS is booted). It does not attempt to change the MIC uOS 
status.



Parameter(s)

mic_id optional command line parameter. Specifies which MIC card (i.e. mic0, mic1, mic2, ...) to check. If this parameter is not 
specified, mic0 will be checked.

Test Execution Time

This test takes approximately 2 seconds to execute.

Dependencies/Limitations

See "Installation" for additional information on each of the following:

The MPSS RPM must be installed on the host system.

There must be a MIC card added to the system.

The host board must be supported by the MPSS team.

The OS must be a supported version.





1.6. lxmiccheck

Overview

This script is a wrapper for executing: lxmicstart check
This operation will:
*	Check whether the MIC uOS is booted on the MIC card specified by the mic_id command line parameter.
It reports success (i.e. PASSED) if the MIC status is online (i.e the uOS is booted). It does not attempt to change the MIC uOS 
status..


Parameter(s)

mic_id optional command line parameter. Specifies which MIC card (i.e. mic0, mic1, mic2, ...) to check. If this parameter is not 
specified, mic0 will be checked.

Test Execution Time

This test takes less than 1 minute to execute.

Dependencies/Limitations

See "Installation" for additional information on each of the following:

The MPSS RPM must be installed on the host system.

There must be a MIC card added to the system.

The host board must be supported by the MPSS team.

The OS must be a supported version.





1.7. lxmicready

Overview

This script is a wrapper for executing: lxmicstart ready
This operation will:
*	Reset the MIC card specified by the mic_id command line 	parameter.
*	If mic_id is not specified, all the MIC cards in the 	system will be reset to firmware ready state.
*	Wait for the specified  MIC card to be in the firmware 	ready state
It reports success (i.e. PASSED) if the MIC's status is ready (i.e the MIC firmware is ready).


Parameter(s)

mic_id optional command line parameter. Specifies which MIC card (i.e. mic0, mic1, mic2, ...) to reset. If this parameter is not 
specified all the MIC cards in the system will be reset.

Test Execution Time

This test may take a couple of minutes to execute.

Dependencies/Limitations

See "Installation" for additional information on each of the following:

The MPSS RPM must be installed on the host system.

There must be a MIC card added to the system.

The host board must be supported by the MPSS team.

The OS must be a supported version.





1.8. lxmicssh

Overview

This script is different from the other scripts in this package because:
*	It is a expect script while the others are bash scripts
*	It is called by the lxmicstart ssh operation, rather than 	invoking that operation.

The script:
*	Assumes the MIC uOS is already booted
*	Assumes SSH keys have been created and installed in 	/root/.ssh on the host system
*	Establishes a SSH connection with the MIC uOS, specified 	by mic_id, and updates that MIC card's ssh fingerprint in 
	$HOME/.ssh/known_hosts on the host system.  Note: If this 	script is run by the root user $HOME will be /root



Parameter(s)

mic_id optional command line parameter. Specifies which MIC card (i.e. mic0, mic1, mic2, ...) to use. If this parameter is not 
specified, the command will fail.

Test Execution Time

This test takes less than 5 seconds to execute.

Dependencies/Limitations

See "Installation" for additional information on each of the following:

The MPSS RPM must be installed on the host system.

There must be a MIC card added to the system.

The host board must be supported by the MPSS team.

The OS must be a supported version.





1.9. lxmicstart

Overview

This script is used to control the state of the MIC card and the MIC uOS. Several MIC control operations are supported by the 
script's command line parameter.  To run lxmicstart with a command line parameter enter:
*	lxmicstart [-o] [<command>] [mic_id]

If no command is specified lxmicstart defaults to the online operation.
If -o  switch is specified, completion status is written to stdout.
If -o switch is not specified, completion status is written to the flag file: uOS_Booted

See Command Parameter descriptions, below, for information on how each command handles the mic_id parameter.

When lxmicstart completes the operation it writes the completion status to either stdout or the uOS_Booted flag file. If the 
operation succeeds the completion status will be    the string PASSED.  If the operation fails, the flag file will contain the string 
FAILED: <failure message>.
The <faillure message> gives more details about which MIC control operation failed. See Error Codes for a list of failure 
messages and what they indicate.


Parameter(s)
*	ssh	Initializes SSH known_hosts with fingerprint for 			current MIC card and uOS. Only used for on-board 			memory tests.
		This command ignores mic_id and initializes SSH 			known_hosts for all the MIC cards in the system.

*  online	Starts MPSS service, if not already running, and 			boots MIC uOS, on the MIC specified by mic_id, 				if it is not already online.
		If mic_id is not specified, all of the MIC cards 			in the system may be booted.
*	check	Checks whether MIC uOS is already online on the MIC 			specified by mic_id.  Does not attempt to change 			state of MIC or the uOS.
		If mic_id is not specified, the state of mic0 is 			checked.
*	ready	Resets the MIC card specified by mic_id and waits for 		it to enter firmware ready state.
		If mic_id is not specified, all the MIC cards in the 			system are reset.
*	help	Prints lxmicstart help information.


Test Execution Time

Varies depending on the requested operation, and the state of the MIC and uOS. May take a few minutes if the MIC must be 
reset or the uOS has to be booted.

Dependencies/Limitations
See "Installation" for additional information on each of the following:

The MPSS RPMs must be installed on the host system.

There must be a MIC card added to the system.

The host board must be supported by the MPSS team.

The OS must be a supported version.

For lxmicstart ssh SSH keys must exist in /root/.ssh on the host system.





1.10. Parameters



See lxmicstart for a description of the parameters.



1.11. Error Codes


lxmicstart failure messages include:
*	uOS Boot Failed which indicates that after a micctrl --boot command the MIC was not able to get to online state.
*	MPSS Service not started which indicate that following a service mpss start command the MPSS service state did not 
become running
*	MIC reset failed which indicates that after a micctrl --reset command the MIC was not able to get to ready state.
*	SELinux is NOT disabled which indicates that SELinux is not Disabled.  SELinux must be disabled to reliably boot the MIC 
uOS.  See Installation for instructions on how to disable SELinux.



1.12. Glossary


Term	Definition

Host Board	The baseboard into which the MIC card is plugged via a PCI-e slot. 

MCE	Machine Check Error

MIC	Many Integrated Cores - an add-in card with processors and memory, to offload compute intensive processing

micrasd	MIC RAS (Reliability Availability Serviceability) Daemon. Logs MIC MCE's on host system.

uOS	micro-OS - an embedded OS on the MIC card, which runs separately from the OS on the host board.

UUT	Unit Under Test - the MIC card which is being tested.
header text	 


