How it Works
Kontron
Loading...
KEAPI
User Manual
37 pgs1.01 Mb0

Kontron KEAPI User Manual

Software specification
for
Kontron EAPI
Version 1.21
Author: Martin Kroul
Software specification for Kontron EAPI
Contents
CONTENTS 2
1 INTRODUCTION 5
1.1 Purpose of this document 5
1.2 KEAPI overview 5
1.3 Architectural overview 5
1.4 Operating systems 6
2 FUNCTION DOCUMENTATION 6
2.1 Return values 6
2.1.1 Functional errors 6
2.1.2 Remote connection errors 6
2.2 Initialization 7
2.2.1 KEApiLibInitialize 7
2.2.2 KEApiLibUnInitialize 7
2.3 General information 7
2.3.1 KEApiGetBoardInfo 7
2.3.2 KEApiGetBootCounter 8
2.3.3 KEApiSystemUpTime 8
2.3.4 KEApiGetSystemStateAmt 9
2.3.5 KEApiSetSystemStateAmt 9
2.3.6 KEApiSetSystemState 9
2.3.7 KEApiGetIntruderStatus 10
2.3.8 KEApiResetIntruderStatus 10
2.4 CPU 10
2.4.1 KEApiGetCpuFreq 10
2.4.2 KEApiGetCpuInfo 11
2.4.3 KEApiGetCpuPerformance 11
2.4.4 KEApiSetCpuPerformance 12
2.5 Memory 12
2.5.1 KEApiGetMemoryInfo 12
2.5.2 KEApiGetMemoryModuleCount 13
2.5.3 KEApiGetMemoryModuleInfo 13
2.6 Hard disks and partitions 14
2.6.1 KEApiGetDiskDriveCount 14
2.6.2 KEApiGetDiskDriveList 14
2.6.3 KEApiGetDiskDrivePartitionCount 14
2.6.4 KEApiGetDiskDrivePartitionList 15
2.7 Battery 15
2.7.1 KEApiGetBatteryCount 15
2
Software specification for Kontron EAPI
2.7.2 KEApiGetBatteryInfo 15
2.7.3 KEApiGetBatteryState 16
2.8 Temperature sensors 17
2.8.1 KEApiGetTempSensorCount 17
2.8.2 KEApiGetTempSensorList 17
2.8.3 KEApiGetTempSensorValue 17
2.8.4 KEApiGetCpuTemp 18
2.8.5 KEApiGetChipsetTemp 18
2.8.6 KEApiGetSystemTemp 18
2.9 Voltage sensors 19
2.9.1 KEApiGetVoltageSensorCount 19
2.9.2 KEApiGetVoltageSensorList 19
2.9.3 KEApiGetVoltageSensorValue 19
2.10 Fan Control 20
2.10.1 KEApiGetFanCount 20
2.10.2 KEApiGetFanList 20
2.10.3 KEApiGetFanSpeed 21
2.10.4 KEApiGetFanMode 21
2.10.5 KEApiSetFanModeManual 21
2.10.6 KEApiSetFanModeThermalCruise 22
2.10.7 KEApiGetCpuFanSpeed 22
2.10.8 KEApiSetCpuFanSpeed 22
2.10.9 KEApiGetSystemFanSpeed 23
2.10.10 KEApiSetSystemFanSpeed 23
2.11 Display 23
2.11.1 KEApiGetDisplayCount 23
2.11.2 KEApiGetBacklightValue 24
2.11.3 KEApiSetBacklightValue 24
2.12 Network and PCI devices 24
2.12.1 KEApiGetNetworkDeviceCount 24
2.12.2 KEApiGetNetworkDeviceList 25
2.12.3 KEApiGetPciDeviceCount 25
2.12.4 KEApiGetPciDeviceList 25
2.13 Storage area 26
2.13.1 KEApiGetStorageCount 26
2.13.2 KEApiGetStorageSize 26
2.13.3 KEApiStorageRead 27
2.13.4 KEApiStorageWrite 27
2.14 I2C 27
2.14.1 KEApiGetI2cBusCount 27
2.14.2 KEApiI2cWrite 28
2.14.3 KEApiI2cRead 28
2.15 SMBus 29
2.15.1 KEApiGetSmbusCount 29
2.15.2 KEApiSmbusQuickCommand 29
2.15.3 KEApiSmbusSendByte 29
2.15.4 KEApiSmbusReceiveByte 30
2.15.5 KEApiSmbusWriteByte 30
2.15.6 KEApiSmbusReadByte 31
3
Software specification for Kontron EAPI
Author
Date
Change summary
Version
Martin Kroul
20.6.2010
Document created
1.0
Martin Kroul
5.7.2010
Major changes in functionality according to conf. call
30.6.2010
1.1
Martin Kroul
28.1.2011
First official release of KEAPI for Windows and Linux
- restructuralization of function names, parameters and types
- no changes in functionality
1.2
Martin Kroul
26.4.2011
VxWorks added to list of supported operating systems
1.21
2.15.7 KEApiSmbusWriteWord 31
2.15.8 KEApiSmbusReadWord 32
2.15.9 KEApiSmbusWriteBlock 32
2.15.10 KEApiSmbusReadBlock 32
2.16 GPIO 33
2.16.1 KEApiGpioGetCount 33
2.16.2 KEApiGpioGetDirectionCaps 33
2.16.3 KEApiGpioGetDirection 34
2.16.4 KEApiGpioSetDirection 34
2.16.5 KEApiGpioGetLevel 34
2.16.6 KEApiGpioSetLevel 35
2.17 Watchdog 35
2.17.1 KEApiWatchdogEnable 35
2.17.2 KEApiWatchdogTrigger 35
2.17.3 KEApiWatchdogDisable 36
3 ABOUT KONTRON 37
Revision history
Legal notice:
All data is for information purposes only and not guaranteed for legal purposes. Subject to change without notice. Information in this datasheet has been carefully checked and is believed to be accurate; however, no responsibility is assumed for inaccuracies. All brand or product names are trademarks or registered trademarks of their respective owners.
4
Software specification for Kontron EAPI
1 Introduction
1.1 Purpose of this document
This document describes Kontron Embedded API – a software library that enables programmers to easily create their applications for monitoring and control hardware resources of Kontron boards, modules, systems and platforms.
1.2 KEAPI overview
KEAPI is written in C language and distributed as a dynamic-linked library so it can be used by arbitrary application developed in C, C++ or higher programming languages simply by linking to the project.
KEAPI library provides a set of functions for
Obtaining basic information about the system  CPU performance control  Temperature and voltage sensors monitoring  Monitoring and control of fans  Display backlight control  Access to EEPROM user storage area  I2C and SMBus communication  GPIO control  Watchdog
All KEAPI functions can be called remotely from another computer over network (TCP/IP). KEAPI is compatible with PICMG EAPI specification (http://www.picmg.org/pdf/COM_EAPI_R1_0.pdf).
This means that it implements all functions defined by this specification. However, these functions offer just a small part of KEAPI functionalities and don’t allow remote connection.
1.3 Architectural overview
Kontron EAPI is a layer between Kontron hardware and user application. KEAPI functions either use hardware drivers and operating system calls to perform requested operation on local board or connects to KEAPI server that is installed on remote board somewhere on the internet. The KEAPI server application listens on a predefined port (default is 7890) and waits for incoming request. When the request comes, it uses KEAPI library to perform the operation and sends result back to the client.
Fig.1. – Kontron EAPI Architecture
5
Software specification for Kontron EAPI
KEAPI_RET_ERROR
General Error
KEAPI_RET_PARAM_ERROR
Wrong parameter value
KEAPI_RET_PARAM_NULL
Parameter is NULL (memory not pre-allocated)
KEAPI_RET_WD_TIMEOUT_NOT_SUPPORTED
WD timeout not supported
KEAPI_RET_BUFFER_OVERFLOW
Buffer overflow (probably configuration error)
KEAPI_RET_SETTING_ERROR
Error while setting value or feature (enable, disable)
KEAPI_RET_RETRIEVAL_ERROR
Error while retrieving information
KEAPI_RET_WRITE_ERROR
Cannot write to file
KEAPI_RET_READ_ERROR
Cannot read file
KEAPI_RET_MALLOC_ERROR
Memory allocation failed
KEAPI_RET_LIBRARY_ERROR
Exported function could not be loaded from library
KEAPI_RET_WMI_ERROR
Problems while reading from WMI
KEAPI_RET_NOT_INITIALIZED
KEAPI library is not initialized
KEAPI_RET_PARTIAL_SUCCESS
Part of requested information couldn’t be retrieved.
Returned information isn’t complete.
KEAPI_RET_FUNCTION_NOT_SUPPORTED
Function is not supported on current platform/HW
KEAPI_RET_FUNCTION_NOT_IMPLEMENTED
Function is not yet implemented
KEAPI_RET_INVALID_IP
IP address is not in a valid format
KEAPI_RET_RMT_CON_ERROR
Remote connection failed
KEAPI_RET_RPC_ERR_MAX_CONN_COUNT_EXCEEDED
Connection limit on the client side was reached
KEAPI_RET_RPC_ERR_SOCKET_ERROR
Error with socket manipulation
KEAPI_RET_RPC_ERR_CONNECTION_NOT_FOUND
Connection for given board handle does not exist
KEAPI_RET_RPC_ERR_NOT_IMPLEMENTED
Remote function call is not implemented
KEAPI_RET_RPC_ERR_SOCKET_TIMEOUT
Time limit for select() function expired
KEAPI_RET_RPC_ERR_PACKET_ERROR
Wrong format of KEAPI packet
1.4 Operating systems
This document describes KEAPI interface for Linux, Windows XP, Windows Vista - 32/64, Windows 7 - 32/64, VxWorks.
2 Function Documentation
Main part of Kontron EAPI is dynamic-linked library with API functions. Before using any of these functions, KEAPI has to be initialized and connection to the board has to be established by calling the KEApiLibInitialize() function. This function returns a board handle (unique four-byte number) that will other KEAPI functions take as their first parameter. The KEApiLibInitialize() function may be called several times for simultaneous connection to several boards. When KEAPI is no longer needed, the KEApiLibUnInitialize() function should be called.
Memory for structures and variables that will be used by KEAPI functions to store information must be pre-allocated by the user application. KEAPI by itself doesn’t allocate memory for output parameters.
2.1 Return values
If everything goes well, all KEAPI functions return KEAPI_RET_SUCCESS. If some error occurs, the returned error message differs for various functions. Error messages can be basically divided into two groups: Functionality errors and Connection errors.
2.1.1 Functional errors
2.1.2 Remote connection errors
6
Software specification for Kontron EAPI
in/out
Parameter name
Description
in
pHostIp
IP address of a remote computer. If it is set to NULL or “localhost” then localhost is considered to be the target machine (no KEAPI server running on the machine is needed). If it is set to “127.0.0.1”, then it connects to KEAPI server running on the local machine (can be used for testing KEAPI server application locally)
in
port
Port number where KEAPI server is listening, default is 7890.
out
pBoardHandle
Returned pointer to the handle of selected board. BoardHandle == 0 means localhost.
In
logLevel
Level of details
LV_ERROR = 0x01,  LV_WARN = 0x02,  LV_INFO = 0x04,  LV_DEBUG = 0x08,  LV_TRACE = 0x10,  LV_ALLTIME = 0xFF
in
pLogFile
Name of the log file. Can be NULL if logging not needed.
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
2.2 Initialization
2.2.1 KEApiLibInitialize
KEAPI_CALLTYPE KEAPI_UINT32 KEApiLibInitialize (
KEAPI_PCHAR pHostIp,
KEAPI_UINT32 port,
KEAPI_PUINT32 pBoardHandle,
KEAPI_UINT32 logLevel, KEAPI_PCHAR pLogFile
);
Description:
Initialization of Kontron EAPI.
Parameters:
2.2.2 KEApiLibUnInitialize
KEAPI_CALLTYPE KEAPI_UINT32 KEApiLibUnInitialize (
KEAPI_UINT32 boardHandle );
Description:
Uninitialization of Kontron EAPI on a selected board.
Parameters:
2.3 General information
2.3.1 KEApiGetBoardInfo
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetBoardInfo (
KEAPI_UINT32 boardHandle, PBOARD_INFO pBoardInfo );
7
Software specification for Kontron EAPI
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
out
pBoardInfo
Returned board info structure BOARD_INFO
in/out
Parameter name
Description
In
boardHandle
Handle of selected board
Out
pBootCount
Number of boot cycles
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
out
pSystemUpTime
Pointer to a variable that receives system running time in seconds
Description:
Provides information about Kontron motherboard.
Parameters:
Structure used:
typedef struct Board_Info
{
KEAPI_CHAR boardManufacturer[MAX_STR]; // Board manufacturer KEAPI_CHAR boardName[MAX_STR]; // Board name KEAPI_CHAR boardVersion[MAX_STR]; // Board version KEAPI_CHAR boardSerialNumber[MAX_STR]; // Board serial number KEAPI_CHAR biosVersion[MAX_STR]; // Bios version KEAPI_CHAR biosDate[MAX_STR]; // BIOS date in format
dd/mm/yyyy } BOARD_INFO, *PBOARD_INFO;
2.3.2 KEApiGetBootCounter
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetBootCounter (
KEAPI_UINT32 boardHandle, KEAPI_PINT32 pBootCount );
Description:
Provides information about number of boot cycles within the board's lifetime.
Parameters:
2.3.3 KEApiSystemUpTime
KEAPI_CALLTYPE KEAPI_UINT32 KEApiSystemUpTime (
KEAPI_UINT32 boardHandle, KEAPI_PINT32 pSystemUpTime );
Description:
Provides time left since last boot in seconds.
Parameters:
8
Software specification for Kontron EAPI
in/out
Parameter name
Description
in
pHostIp
IP address of the remote board
in
pUser
User name for host AMT
in
pPassword
Password for host AMT
out
pSystemState
Pointer to variable that will receive remote board's state
SYSTEM_STATE_TURN_ON, 0 SYSTEM_STATE_TURN_OFF, 1 SYSTEM_STATE_HIBERNATE, 2
in/out
Parameter name
Description
in
pHostIp
IP address of the remote board
in
pUser
User name for host AMT
in
pPassword
Password for host AMT
in
systemState
Desired system state
SYSTEM_STATE_TURN_ON, 0 SYSTEM_STATE_TURN_OFF, 1 SYSTEM_STATE_RESTART, 3
2.3.4 KEApiGetSystemStateAmt
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetSystemStateAmt (
KEAPI_PCHAR pHostIp, KEAPI_PCHAR pUser, KEAPI_PCHAR pPassword, KEAPI_PINT32 pSystemState );
Description:
Uses Intel AMT to get information about state of remote board (turned on, turned off or hibernated). The remote board must support Intel AMT and enable it in BIOS. AMT functionality can be tested via web browser (fill in address http:// “remote board’s IP” :16992 and AMT web page should appear).
Parameters:
2.3.5 KEApiSetSystemStateAmt
KEAPI_CALLTYPE KEAPI_UINT32 KEApiSetSystemStateAmt (
KEAPI_PCHAR pHostIp, KEAPI_PCHAR pUser, KEAPI_PCHAR pPassword, KEAPI_INT32 systemState );
Description:
Uses Intel AMT to turn on, turn off or restart remote board. If the remote board doesn’t support Intel AMT, then the KEApiSetSystemState() function using OS call can be used instead.
Parameters:
2.3.6 KEApiSetSystemState
KEAPI_CALLTYPE KEAPI_UINT32 KEApiSetSystemState (
KEAPI_UINT32 boardHandle, KEAPI_INT32 systemState );
Description:
Uses operating system’s command to turn on, turn off or restart remote board. There is no guarantee that the command was performed correctly i.e. if the system hangs.
9
Software specification for Kontron EAPI
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
in
systemState
Desired system state
SYSTEM_STATE_TURN_OFF, 1 SYSTEM_STATE_HIBERNATE, 2 SYSTEM_STATE_RESTART, 3
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
out
pIntruderStatus
Pointer to a variable that receives actual intruder status
INTRUDER_STATUS_CASE CLOSED, 0 INTRUDER_STATUS_CASE OPENED , 1
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
Parameters:
2.3.7 KEApiGetIntruderStatus
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetIntruderStatus (
KEAPI_UINT32 boardHandle, KEAPI_PINT32 pIntruderStatus );
Description:
Provides actual information whether computer case was opened or not.
Parameters:
2.3.8 KEApiResetIntruderStatus
KEAPI_CALLTYPE KEAPI_UINT32 KEApiResetIntruderStatus (
KEAPI_UINT32 boardHandle );
Description:
Resets the case intruder status.
Parameters:
2.4 CPU
2.4.1 KEApiGetCpuFreq
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetCpuFreq (
KEAPI_UINT32 boardHandle, KEAPI_INT8 freqType, KEAPI_PINT32 frequency );
Description:
Provides information about CPU frequency
minimal supported CPU frequency: CPU_FREQUENCY_MIN, 0 maximal supported CPU frequency: CPU_FREQUENCY_MAX, 1 current CPU frequency: CPU_FREQUENCY_CURRENT, 2.
10
Software specification for Kontron EAPI
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
in
freqType
Type of frequency (minimal (CPU_FREQUENCY_MIN, 0), maximal (CPU_FREQUENCY_MAX, 1), current (CPU_FREQUENCY_CURRENT, 2))
out
frequency
Frequency of the CPU, in kHz
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
out
pCpuInfo
Returned CPU_INFO structure
Parameters:
2.4.2 KEApiGetCpuInfo
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetCpuInfo (
KEAPI_UINT32 boardHandle, PCPU_INFO pCpuInfo );
Description:
Provides information about processors.
Parameters:
Structure used:
typedef struct Cpu_Info
{
KEAPI_CHAR cpuName[MAX_STR]; // CPU name KEAPI_INT32 cpuCount; // Number of CPUs KEAPI_INT32 cpuCoreCount; // Number of cores of each CPU KEAPI_INT32 cpuThreadCount; // Number of CPU threads KEAPI_FLOAT cpuMaxCoreSpeed; // Designed core speed in MHz KEAPI_INT32 fsbSpeed; // FSB speed in MHz KEAPI_INT32 l1Cache; // L1 cache size in kB KEAPI_INT32 l2Cache; // L2 cache size in kB KEAPI_INT32 l3Cache; // L3 cache size in kB
} CPU_INFO, *PCPU_INFO;
2.4.3 KEApiGetCpuPerformance
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetCpuPerformance (
KEAPI_UINT32 boardHandle, KEAPI_PINT8 pPerformanceType,
KEAPI_PINT8 pPerformancePercentage
);
Description:
Linux: Provides information about the current CPU performance mode
high performance: CPU_PERFORMANCE_HIGH, 0 power save mode: CPU_PERFORMANCE_POWER_SAVE, 1 on demand mode: CPU_PERFORMANCE_ON_DEMAND, 2 conservative mode: CPU_PERFORMANCE_CONSERVATIVE, 3.
Windows: Provides information about the current CPU performance in percentage
11
Software specification for Kontron EAPI
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
out
pPerformanceType
Pointer to the type of current CPU performance. The type is given by a number (0 – 3 where:
0 - high performance  1 - power save mode  2 - on demand mode  3 - conservative mode
) . Supported only on Linux
out
pPerformancePercentage
Pointer to current CPU performance in percentage. Supported only on Windows
in/out
Parameter name
Description
in
boardHandle
Handle of the selected board
in
performanceType
CPU performance type Supported only on Linux
in
performancePercentage
CPU performance in percentage Supported only on Windows
in/out
Parameter name
Description
in
boardHandle
Handle of selected board
out
pMemoryInfo
Returned MEMORY_INFO structure
Parameters:
2.4.4 KEApiSetCpuPerformance
KEAPI_CALLTYPE KEAPI_UINT32 KEApiSetCpuPerformance (
KEAPI_UINT32 boardHandle, KEAPI_INT8 performanceType,
KEAPI_INT8 performancePercentage
);
Description:
Linux: Allows you to set the type of the CPU performance
high performance: CPU_PERFORMANCE_HIGH, 0 power save mode: CPU_PERFORMANCE_POWER_SAVE, 1 on demand mode: CPU_PERFORMANCE_ON_DEMAND, 2 conservative mode: CPU_PERFORMANCE_CONSERVATIVE, 3.
Windows: Allows you to set CPU performance in percentage
Parameters:
2.5 Memory
2.5.1 KEApiGetMemoryInfo
KEAPI_CALLTYPE KEAPI_UINT32 KEApiGetMemoryInfo (
KEAPI_UINT32 boardHandle, PMEMORY_INFO pMemoryInfo );
Description:
Provides information about physical memory.
Parameters:
12
Loading...
+ 25 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use