Difference between revisions of "SW Service/API/SUSI4.0 USER MANUAL"
Weichih.lin (talk | contribs) |
Weichih.lin (talk | contribs) |
||
| Line 3,315: | Line 3,315: | ||
uint32_t SUSI_API SusiSMBReadQuick(uint32_t Id, uint8_t Addr) | uint32_t SUSI_API SusiSMBReadQuick(uint32_t Id, uint8_t Addr) | ||
| − | |||
| − | |||
:'''Description:''' | :'''Description:''' | ||
| Line 3,391: | Line 3,389: | ||
|} | |} | ||
| − | |||
| − | |||
=== '''3.5.8 SusiSMB'''WriteQuick === | === '''3.5.8 SusiSMB'''WriteQuick === | ||
Revision as of 11:08, 15 November 2016
SUSI – A Bridge to Simplify & Enhance H/W & Application Implementation Efficiency
When developers want to write an application that involves hardware access, they have to study the specifications to write the drivers. This is a time-consuming job and requires lots of expertise.
Advantech has done all the hard work for our customers with the release of a suite of Software APIs (Application Programming Interfaces), called Secured & Unified Smart Interface (SUSI).
SUSI provides not only the underlying drivers required but also a rich set of user-friendly, intelligent and integrated interfaces, which speeds development, enhances security and offers add-on value for Advantech platforms. SUSI plays the role of catalyst between developer and solution, and makes Advantech embedded platforms easier and simpler to adopt and operate with customer applications.
1.1 Functions
1.1.1 GPIO
General Purpose Input/Output is a flexible parallel interface that allows a variety of custom connections. It supports various Digital I/O devices – input devices like buttons, switches; output devices such as cash drawers, LED lights…etc. And, allows users to monitor the level of signal input or set the output status to switch on/off the device. Our APIs also provided Programmable GPIO and allows developers to dynamically set the GPIO input or output status.
1.1.2 SMBus
SMBus is the System Management Bus defined by Intel® Corporation in 1995. It is used in personal computers and servers for low-speed system management communications. Today, SMBus is used in all types of embedded systems. The SMBus APIs allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the SMBus protocols, allowing multiple simultaneous device control.
1.1.3 I2C
I2C is a bi-directional two wire bus that was developed by Philips for use in their televisions in the 1980s. Today, I2C is used in all types of embedded systems. The I2C API allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the I2C protocols, allowing multiple simultaneous device control.
1.1.4 Watchdog
A watchdog timer (WDT) is a device or electronic card that performs a specific operation after a certain period of time if something goes wrong with an electronic system and the system does not recover on its own.
A watchdog timer can be programmed to perform a warm boot (restarting the system) after a certain number of seconds during which a program or computer fails to respond following the most recent mouse click or keyboard action.
1.1.5 Hardware Monitor
The Hardware Monitor (HWM) APIs is a system health supervision API that inspects certain condition indexes, such as smart fan, fan speed, temperature, current, case open and voltage.
1.1.6 Backlight Control
The Backlight Control APIs allows a developer to interface platform to easily control brightness through PWM and backlight on/off.
1.1.7 Storage
Storage is a non-volatile storage, the storage APIs allows a developer to access storage information, read/write data to storage and lock/unlock data area (same like write protection) by a key.
1.1.8 Thermal Protection
Thermal Protection can select a thermal source to monitor. When source temperature reach the limit, SUSI can act protect function to protect system.
1.2 Benefits
- Faster Time to Market
- SUSI's unified API helps developers write applications to control the hardware without knowing the hardware specs of the chipsets and driver architecture.
- Reduced Project Effort
- When customers have their own devices connected to the onboard bus, they can either: study the data sheet and write the driver & API from scratch, or they can use SUSI to start the integration with a 50% head start. Developers can reference the sample program on the CD to see and learn more about the software development environment.
- Enhances Hardware Platform Reliability
- SUSI provides a trusted custom ready solution which combines chipset and library function support, controlling application development through SUSI enhances reliability and brings peace of mind.::::
- Flexible Upgrade Possibilities
- SUSI supports an easy upgrade solution for customers. Customers just need to install the new version SUSI that supports the new functions.
- Backward compatibility
- Support SUSI 3.0, iManager 2.0 and EAPI 1.0 interface. Customers don’t need to change any APIs in their applications.
1.3 Environment Requirements
1.3.1Operating Systems
- Windows XP Embedded
- Windows XP 32-bit
- Windows 7 (x86 / x64)
- WES7 (x86 / x64)
- Windows 8 Desktop (x86 / x64)
- Windows CE 5 / 6 / 7
- Linux (Project based, request from your local FAE)
- Android (Project based, request from your local FAE)
- QNX (Project based, request from your local FAE)
- VxWorks (Project based, request from your local FAE)
Susi4.h file includes the API declaration, constants and flags that are required for programming.
2.1 Status Codes
All SUSI API functions immediately return a status code from a common list of possible errors. Any function may return any of the defined status codes. See the Appendix for more detailed information.
#define SUSI_STATUS_NOT_INITIALIZED 0xFFFFFFFF
- Description
- The SUSI API library is not yet or unsuccessfully initialized. SusiLibInitialize needs to be called prior to the first access of any other SUSI API functions.
- Actions
- Call SusiLibInitialize.
#define SUSI_STATUS_INITIALIZED 0xFFFFFFFE
- Description
- Library is initialized.
- Actions
- None.
#define SUSI_STATUS_ALLOC_ERROR 0xFFFFFFFD
- Description
- Memory Allocation Error.
- Actions
- Free memory and try again.
#define SUSI_STATUS_DRIVER_TIMEOUT 0xFFFFFFFC
- Description
- Time out in driver. This is Normally caused by hardware/software semaphore timeout.
- Actions
- Retry.
#define SUSI_STATUS_INVALID_PARAMETER 0xFFFFFEFF
- Description
- One or more of the SUSI API functions call parameters are out of defined range.
- Actions
- Verify Function Parameters.
#define SUSI_STATUS_INVALID_BLOCK_ALIGNMENT 0xFFFFFEFE
- Description
- The Block Alignment is incorrect.
- Actions
- Use Inputs and Outputs to correctly select input and outputs.
#define SUSI_STATUS_INVALID_BLOCK_LENGTH 0xFFFFFEFD
- Description
- This means that the Block length is too long.
- Actions
- Use Alignment Capabilities information to correctly align write access.
#define SUSI_STATUS_INVALID_DIRECTION 0xFFFFFEFC
- Description
- The current Direction Argument attempts to set GPIOs to a unsupported direction. I.E. Setting GPI to Output.
- Actions
- Use Inputs and Outputs to correctly select input and outputs.
#define SUSI_STATUS_INVALID_BITMASK 0xFFFFFEFB
- Description
- The Bitmask Selects bits/GPIOs which are not supported for the current ID.
- Actions
- Use Inputs and Outputs to probe supported bits.
#define SUSI_STATUS_RUNNING 0xFFFFFEFA
- Description
- Watchdog timer already started.
- Actions
- Call SusiWDogStop before retrying.
#define SUSI_STATUS_UNSUPPORTED 0xFFFFFCFF
- Description
- This function or ID is not supported at the actual hardware environment.
- Actions
- None.
#define SUSI_STATUS_NOT_FOUND 0xFFFFFBFF
- Description
- Selected device was not found
- Actions
- None.
#define SUSI_STATUS_TIMEOUT 0xFFFFFBFE
- Description
- Device has no response.
- Actions
- None.
#define SUSI_STATUS_BUSY_COLLISION 0xFFFFFBFD
- Description
- The selected device or ID is busy or a data collision is detected.
- Actions
- Retry.
#define SUSI_STATUS_READ_ERROR 0xFFFFFAFF
- Description
- An error is detected during a read operation.
- Actions
- Retry.
#define SUSI_STATUS_WRITE_ERROR 0xFFFFFAFE
- Description
- An error is detected during a write operation.
- Actions
- Retry.
#define SUSI_STATUS_MORE_DATA 0xFFFFF9FF
- Description
- The amount of available data exceeds the buffer size. Storage buffer overflow was prevented. Read count was larger than the defined buffer length.
- Actions
- Either increase the buffer size or reduce the block length.
#define SUSI_STATUS_ERROR 0xFFFFF0FF
- Description
- Generic error message. No further error details are available.
- Actions
- None.
#define SUSI_STATUS_SUCCESS 0
- Description
- The operation is successful.
- Actions
- None.
2.2 ID
#define SUSI_ID_UNKNOWN 0xFFFFFFFF
- Description
- Undefined/Unknown ID
#define SUSI_ID_BOARD_MANUFACTURER_STR 0 #define SUSI_ID_BOARD_NAME_STR 1 #define SUSI_ID_BOARD_REVISION_STR 2 #define SUSI_ID_BOARD_SERIAL_STR 3 #define SUSI_ID_BOARD_BIOS_REVISION_STR 4 #define SUSI_ID_BOARD_HW_REVISION_STR 5 #define SUSI_ID_BOARD_PLATFORM_TYPE_STR 6
- Description
- Board information string ID, use in SusiBoardGetStringA.
#define SUSI_ID_GET_SPEC_VERSION  0x00000000 #define SUSI_ID_BOARD_BOOT_COUNTER_VAL 0x00000001 #define SUSI_ID_BOARD_RUNNING_TIME_METER_VAL 0x00000002 #define SUSI_ID_BOARD_PNPID_VAL 0x00000003 #define SUSI_ID_BOARD_PLATFORM_REV_VAL 0x00000004 #define SUSI_ID_BOARD_DRIVER_VERSION_VAL 0x00010000 #define SUSI_ID_BOARD_LIB_VERSION_VAL 0x00010001 #define SUSI_ID_BOARD_FIRMWARE_VERSION_VAL 0x00010002
- Description
- Board information value ID, use in SusiBoardGetValue.
#define SUSI_ID_HWM_TEMP_CPU 0x00020000 #define SUSI_ID_HWM_TEMP_CHIPSET 0x00020001 #define SUSI_ID_HWM_TEMP_SYSTEM 0x00020002 #define SUSI_ID_HWM_TEMP_CPU2 0x00020003 #define SUSI_ID_HWM_TEMP_OEM0 0x00020004 #define SUSI_ID_HWM_TEMP_OEM1 0x00020005 #define SUSI_ID_HWM_TEMP_OEM2 0x00020006 #define SUSI_ID_HWM_TEMP_OEM3 0x00020007 #define SUSI_ID_HWM_TEMP_OEM4 0x00020008 #define SUSI_ID_HWM_TEMP_OEM5 0x00020009
- Description
- Board temperature value ID, use in SusiBoardGetValue.
#define SUSI_ID_HWM_VOLTAGE_VCORE 0x00021000 #define SUSI_ID_HWM_VOLTAGE_VCORE2 0x00021001 #define SUSI_ID_HWM_VOLTAGE_2V5 0x00021002 #define SUSI_ID_HWM_VOLTAGE_3V3 0x00021003 #define SUSI_ID_HWM_VOLTAGE_5V 0x00021004 #define SUSI_ID_HWM_VOLTAGE_12V 0x00021005 #define SUSI_ID_HWM_VOLTAGE_5VSB 0x00021006 #define SUSI_ID_HWM_VOLTAGE_3VSB 0x00021007 #define SUSI_ID_HWM_VOLTAGE_VBAT 0x00021008 #define SUSI_ID_HWM_VOLTAGE_5NV 0x00021009 #define SUSI_ID_HWM_VOLTAGE_12NV 0x0002100A #define SUSI_ID_HWM_VOLTAGE_VTT 0x0002100B #define SUSI_ID_HWM_VOLTAGE_24V 0x0002100C #define SUSI_ID_HWM_VOLTAGE_DC 0x0002100D #define SUSI_ID_HWM_VOLTAGE_DCSTBY 0x0002100E #define SUSI_ID_HWM_VOLTAGE_OEM3 0x0002100F #define SUSI_ID_HWM_VOLTAGE_OEM0 0x00021010 #define SUSI_ID_HWM_VOLTAGE_OEM1 0x00021011 #define SUSI_ID_HWM_VOLTAGE_OEM2 0x00021012 #define SUSI_ID_HWM_VOLTAGE_OEM3 0x00021013 #define SUSI_ID_HWM_VOLTAGE_1V05 0x00021014 #define SUSI_ID_HWM_VOLTAGE_1V5 0x00021015 #define SUSI_ID_HWM_VOLTAGE_1V8 0x00021016
- Description
- Board voltage value ID, use in SusiBoardGetValue.
#define SUSI_ID_HWM_FAN_CPU 0x00022000 #define SUSI_ID_HWM_FAN_SYSTEM 0x00022001 #define SUSI_ID_HWM_FAN_CPU2 0x00022002 #define SUSI_ID_HWM_FAN_OEM0 0x00022003 #define SUSI_ID_HWM_FAN_OEM1 0x00022004 #define SUSI_ID_HWM_FAN_OEM2 0x00022005 #define SUSI_ID_HWM_FAN_OEM3 0x00022006 #define SUSI_ID_HWM_FAN_OEM4 0x00022007 #define SUSI_ID_HWM_FAN_OEM5 0x00022008 #define SUSI_ID_HWM_FAN_OEM6 0x00022009
- Description
- Board fan speed value ID, use in SusiBoardGetValue and Smart Fan Functions.
#define SUSI_ID_HWM_CURRENT_OEM0 0x00023000 #define SUSI_ID_HWM_CURRENT_OEM1 0x00023001 #define SUSI_ID_HWM_CURRENT_OEM2 0x00023002
- Description
- Board current value ID, use in SusiBoardGetValue.
#define SUSI_ID_SMBUS_SUPPORTED 0x00030000 #define SUSI_ID_I2C_SUPPORTED 0x00030100
- Description
- Board supported information value ID, use in SusiBoardGetValue.
#define SUSI_ID_SMBUS_EXTERNAL 0 #define SUSI_ID_SMBUS_OEM0 1 #define SUSI_ID_SMBUS_OEM1 2 #define SUSI_ID_SMBUS_OEM2 3 #define SUSI_ID_SMBUS_OEM3 4
- Description
- SMBus device ID, use in SMBus Functions.
#define SUSI_ID_I2C_EXTERNAL 0 #define SUSI_ID_I2C_OEM0 1 #define SUSI_ID_I2C_OEM1 2 #define SUSI_ID_I2C_OEM2 3
- Description
- I2C device ID, use in I2C Functions.
#define SUSI_ID_GPIO(GPIO_NUM) (GPIO_NUM) #define SUSI_ID_GPIO_BANK(BANK_NUM) (0x00010000 + BANK_NUM)
- Description
- GPIO device ID, use in GPIO Functions.
#define SUSI_ID_BACKLIGHT_1 0 #define SUSI_ID_BACKLIGHT_2 1 #define SUSI_ID_BACKLIGHT_3 2
- Description
- Backlight device ID, use in Backlight Functions.
#define SUSI_ID_STORAGE_STD 0x00000000 #define SUSI_ID_STORAGE_OEM0 0x00000001 #define SUSI_ID_STORAGE_OEM1 0x00000002
- Description
- Storage device ID, use in Storage Functions.
#define SUSI_ID_THERMAL_PROTECT_1 0 #define SUSI_ID_THERMAL_PROTECT_2 1 #define SUSI_ID_THERMAL_PROTECT_3 2 #define SUSI_ID_THERMAL_PROTECT_4 3
- Description
- Thermal protection device ID, use in Thermal Protection Functions
#define SUSI_ID_WATCHDOG_1 0 #define SUSI_ID_WATCHDOG_2 1 #define SUSI_ID_WATCHDOG_3 2
- Description
- Watchdog device ID, use in Watchdog Functions.
2.3 Item ID
#define SUSI_ID_I2C_MAXIMUM_BLOCK_LENGTH 0x00000000
- Description
- Watchdog capabilities item ID, use in SusiI2CGetCaps.
#define SUSI_ID_GPIO_INPUT_SUPPORT 0x00000000 #define SUSI_ID_GPIO_OUTPUT_SUPPORT 0x00000001
- Description
- GPIO capabilities item ID, use in SusiGPIOGetCaps.
#define SUSI_ID_VGA_BRIGHTNESS_MAXIMUM 0x00010000 #define SUSI_ID_VGA_BRIGHTNESS_MINIMUM 0x00010001
- Description
- VGA capabilities item ID, use in SusiVgaGetCaps.
#define SUSI_ID_STORAGE_TOTAL_SIZE 0x00000000 #define SUSI_ID_STORAGE_BLOCK_SIZE 0x00000001 #define SUSI_ID_STORAGE_LOCK_STATUS 0x00010000 #define SUSI_ID_STORAGE_PSW_MAX_LEN 0x00010000
- Description
- Storage capabilities item ID, use in SusiStorageGetCaps.
#define SUSI_ID_WDT_SUPPORT_FLAGS 0x00000000 #define SUSI_ID_WDT_DELAY_MAXIMUM 0x00000001 #define SUSI_ID_WDT_DELAY_MINIMUM 0x00000002 #define SUSI_ID_WDT_EVENT_MAXIMUM 0x00000003 #define SUSI_ID_WDT_EVENT_MINIMUM 0x00000004 #define SUSI_ID_WDT_RESET_MAXIMUM 0x00000005 #define SUSI_ID_WDT_RESET_MINIMUM 0x00000006 #define SUSI_ID_WDT_UNIT_MINIMUM 0x0000000F #define SUSI_ID_WDT_DELAY_TIME 0x00010001 #define SUSI_ID_WDT_EVENT_TIME 0x00010002 #define SUSI_ID_WDT_RESET_TIME 0x00010003 #define SUSI_ID_WDT_EVENT_TYPE 0x00010004
- Description
- Watchdog capabilities item ID, use in SusiWDogGetCaps.
#define SUSI_ID_FC_CONTROL_SUPPORT_FLAGS 0x00000000 #define SUSI_ID_FC_AUTO_SUPPORT_FLAGS 0x00000001
- Description
- Fan control capabilities item ID, use in SusiFanControlGetCaps.
#define SUSI_ID_TP_EVENT_SUPPORT_FLAGS 0x00000000 #define SUSI_ID_TP_EVENT_TRIGGER_MAXIMUM 0x00000001 #define SUSI_ID_TP_EVENT_TRIGGER_MINIMUM 0x00000002 #define SUSI_ID_TP_EVENT_CLEAR_MAXIMUM 0x00000003 #define SUSI_ID_TP_EVENT_CLEAR_MINIMUM 0x00000004
- Description
- Thermal protection capabilities item ID, use in SusiThermalProtectionGetCaps.
The SUSI APIs provide functions to control ADVANTECH platforms. SUSI API functions are based on a dynamic library. SUSI API can be implemented in various other programming languages.
3.1 Initialization Functions
3.1.1 SusiLibInitialize
uint32_t SUSI_API SusiLibInitialize(void)
- Description:
- General initialization of the SUSI API. Prior to calling any SUSI API functions, the library needs to be initialized by calling this function. The status code for all SUSI API function will be SUSI_STATUS_NOT_INITIALIZED unless this function is called.
- Parameters:
- None
- Return Status Code:
|
Condition |
Return Value |
|
Library initialized |
SUSI_STATUS_INITIALIZED |
|
Fail |
SUSI_STATUS_NOT_INITIALIZED |
|
Success |
SUSI_STATUS_SUCCESS |
3.1.2 SusiLibUninitialize
uint32_t SUSI_API SusiLibUninitialize(void)
- Description:
- General function to uninitialize the SUSI API library that should be called before program exit. In a dynamic library environment this function is not expected to replace the native uninitialized routines. It is expected that in this environments this function has no functionality.
- Parameters:
- None
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Success |
SUSI_STATUS_SUCCESS |
3.2 Information Functions
3.2.1 SusiBoardGetValue
uint32_t SUSI_API SusiBoardGetValue(uint32_t Id, uint32_t *pValue)
- Description:
- Getting information about the hardware platform in value format.
- Parameters:
- Id
- Selects target value. See Table 1 to Table 5.
- pValue
- Pointer to a buffer that receives the value's data.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pValue==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
- Table 1 Board information value ID
|
Id |
Description |
Unit |
|
SUSI_ID_GET_SPEC_VERSION |
API Specification Version |
|
|
SUSI_ID_BOARD_BOOT_COUNTER_VAL |
Boot Counter |
boot |
|
SUSI_ID_BOARD_RUNNING_TIME_METER_VAL |
Running Time Meter |
hour |
|
SUSI_ID_BOARD_PNPID_VAL |
Board Vendor PNPID |
|
|
SUSI_ID_BOARD_PLATFORM_REV_VAL |
Platform revision |
|
|
SUSI_ID_BOARD_DRIVER_VERSION_VAL |
Driver version |
|
|
SUSI_ID_BOARD_LIB_VERSION_VAL |
Library version |
|
|
SUSI_ID_BOARD_FIRMWARE_VERSION_VAL |
Firmware version |
|
- Table 2 Board voltage value ID
|
Id |
Description |
Unit |
|
SUSI_ID_HWM_VOLTAGE_VCORE |
CPU Core voltage |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_VCORE2 |
Second CPU Core voltage |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_2V5 |
2.5V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_3V3 |
3.3V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_5V |
5V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_12V |
12V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_5VSB |
5V Standby |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_3VSB |
3V Standby |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_VBAT |
CMOS Battery voltage |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_5NV |
-5V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_12NV |
-12V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_VTT |
DIMM voltage |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_24V |
24V |
millivolt |
|
SUSI_ID_HWM_VOLTAGE_OEM0~3 |
Other voltages |
millivolt |
- Table 3 Board temperature value ID
|
Id |
Description |
Unit |
|
SUSI_ID_HWM_TEMP_CPU |
CPU temperature |
0.1 Kelvin |
|
SUSI_ID_HWM_TEMP_CHIPSET |
Chipset temperature |
0.1 Kelvin |
|
SUSI_ID_HWM_TEMP_SYSTEM |
System temperature |
0.1 Kelvin |
|
SUSI_ID_HWM_TEMP_CPU2 |
CPU2 temperature |
0.1 Kelvin |
|
SUSI_ID_HWM_TEMP_OEM0~5 |
Other temperatures |
0.1 Kelvin |
- Table 4 Board fan speed value ID
|
Id |
Description |
Unit |
|
SUSI_ID_HWM_FAN_CPU |
CPU fan speed |
RPM |
|
SUSI_ID_HWM_FAN_SYSTEM |
System fan speed |
RPM |
|
SUSI_ID_HWM_FAN_CPU2 |
Second CPU fan speed |
RPM |
|
SUSI_ID_HWM_FAN_OEM0~6 |
Other fans |
RPM |
- Table 5 Board support information value ID
|
Id |
Description |
|
SUSI_ID_SMBUS_SUPPORTED |
Mask flags: SUSI_SMBUS_EXTERNAL_SUPPORTED SUSI_SMBUS_OEM0_SUPPORTED SUSI_SMBUS_OEM1_SUPPORTED SUSI_SMBUS_OEM2_SUPPORTED SUSI_SMBUS_OEM3_SUPPORTED |
|
SUSI_ID_I2C_SUPPORTED |
Mask flags: SUSI_ I2C_EXTERNAL_SUPPORTED SUSI_ I2C_OEM0_SUPPORTED SUSI_ I2C_OEM1_SUPPORTED SUSI_ I2C_OEM2_SUPPORTED |
3.2.2 SusiBoardGetStringA
uint32_t SUSI_API SusiBoardGetStringA(uint32_t Id, char *pBuffer, uint32_t *pBufLen)
- Description:
- Text information about the hardware platform.
- Parameters:
- Id
- Selects target string. See Table 6.
- pBuffer
- Pointer to a buffer that receives the value's data.
- pBufLen
- Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pBuffer parameter. When the function returns, this variable contains the size of the data copied to pBuffer including the terminating null character.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBufLen==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
pBufLen!=NULL&&*pBufLen&&pBuffer==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
strlength + 1 > *pBufLen |
SUSI_STATUS_MORE_DATA |
|
Success |
SUSI_STATUS_SUCCESS |
- Table 6 Board information string ID
|
Id |
Description |
|
SUSI_ID_BOARD_MANUFACTURER_STR |
Board Manufacturer Name |
|
SUSI_ID_BOARD_NAME_STR |
Board Name |
|
SUSI_ID_BOARD_REVISION_STR |
Board Revision |
|
SUSI_ID_BOARD_SERIAL_STR |
Board Serial Number |
|
SUSI_ID_BOARD_BIOS_REVISION_STR |
Board BIOS Revision |
|
SUSI_ID_BOARD_HW_REVISION_STR |
Hardware Revision |
|
SUSI_ID_BOARD_PLATFORM_TYPE_STR |
Platform type |
3.3 Backlight Functions
This function sub set facilitates backlight control for Integrated flat panel displays, typically LVDS.
- Table 7 Backlight ID
|
Id |
Description |
|
SUSI_ID_BACKLIGHT_1 |
Backlight Local Flat Panel 1 |
|
SUSI_ID_BACKLIGHT_2 |
Backlight Local Flat Panel 2 |
|
SUSI_ID_BACKLIGHT_3 |
Backlight Local Flat Panel 3 |
- Table 8 Backlight Enable Values
|
Name |
Description |
|
SUSI_BACKLIGHT_SET_ON |
Signifies that the Backlight be Enabled |
|
SUSI_BACKLIGHT_SET_OFF |
Signifies that the Backlight be Disabled |
3.3.1 SusiVgaGetCaps
uint32_t SUSI_API SusiVgaGetCaps(uint32_t Id, uint32_t ItemId, uint32_t *pValue);
- Description:
- Gets VGA capabilities.
- Parameters:
- Id
- Selects target device. See Table 7.
- ItemId
- Selects target capability. See Table 9.
- pValue
- Pointer to a buffer that receives the target capability.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pValue==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id or ItemId |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
- Table 9 VGA capabilities item Id
|
Item Id |
Description |
|
SUSI_ID_VGA_BRIGHTNESS_MAXIMUM |
Maximum backlight value |
|
SUSI_ID_VGA_BRIGHTNESS_MINIMUM |
Minimum backlight value |
3.3.2 SusiVgaGetBacklightEnable
uint32_t SUSI_API SusiVgaGetBacklightEnable(uint32_t Id, uint32_t *pEnable)
- Description:
- Gets current Backlight Enable state for specified Flat Panel.
- Parameters:
- Id
- Selects target device. See Table 7.
- pEnable
- Pointer to a buffer that receives the current backlight enable state. See Table 8.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pEnable==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.3 SusiVgaSetBacklightEnable
uint32_t SUSI_API SusiVgaSetBacklightEnable(uint32_t Id, uint32_t Enable)
- Description:
- Enables or disable the backlight of the selected flat panel display
- Parameters:
- Id
- Selects target device. See Table 7.
- Enable
- Backlight Enable options. See Table 8.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.4 SusiVgaGetBacklightBrightness
uint32_t SUSI_API SusiVgaGetBacklightBrightness(uint32_t Id, uint32_t *pBright)
- Description:
- Reads the current brightness of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- pBright
- Pointer to a buffer that receives the current backlight brightness value.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBright==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.5 SusiVgaSetBacklightBrightness
uint32_t SUSI_API SusiVgaSetBacklightBrightness(uint32_t Id, uint32_t Bright)
- Description:
- Reads the current brightness of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- Bright
- Backlight Brightness value.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Bright > MAX value || Bright < MIN value |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.6 SusiVgaGetBacklightLevel
uint32_t SUSI_API SusiVgaGetBacklightLevel(uint32_t Id, uint32_t *pLevel)
- Description:
- Reads the current brightness level of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- pLevel
- Pointer to a buffer that receives the current backlight brightness level. See Table 10.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pLevel==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
- Table 10 Brightness level range definition
|
Name |
Description |
|
SUSI_BACKLIGHT_LEVEL_MAXIMUM |
Maximum backlight level is 9 |
|
SUSI_BACKLIGHT_LEVEL_MINIMUM |
Minimum backlight level is 0 |
3.3.7 SusiVgaSetBacklightLevel
uint32_t SUSI_API SusiVgaSetBacklightLevel(uint32_t Id, uint32_t Level)
- Description:
- Sets the brightness level of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- Level
- Backlight Brightness level. See Table 10.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Level>SUSI_BACKLIGHT_LEVEL_MAXIMUM |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.8 SusiVgaGetPolarity
uint32_t SUSI_API SusiVgaGetPolarity(uint32_t Id, uint32_t *pPolarity)
- Description:
- Reads the current backlight polarity of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- pPolarity
- Pointer to a buffer that receives the current backlight polarity. See Table 11.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pPolarity==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
- Table 11 Brightness polarity definition
|
Name |
Description |
|
SUSI_BACKLIGHT_POLARITY_ON |
Backlight signal polarity ON |
|
SUSI_BACKLIGHT_ POLARITY_OFF |
Backlight signal polarity OFF |
3.3.9 SusiVgaSetPolarity
uint32_t SUSI_API SusiVgaSetPolarity(uint32_t Id, uint32_t Polarity)
- Description:
- Sets the polarity of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- Polarity
- Polarity state. See Table 11.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.10 SusiVgaGetFrequency
uint32_t SUSI_API SusiVgaGetFrequency(uint32_t Id, uint32_t *pFrequency)
- Description:
- Reads the current backlight frequency of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- pFrequency
- Pointer to a buffer that receives the current backlight frequency. (Unit: Hz)
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pFrequency==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.3.11SusiVgaSetFrequency
uint32_t SUSI_API SusiVgaSetFrequency(uint32_t Id, uint32_t Frequency)
- Description:
- Sets the frequency of the selected flat panel display.
- Parameters:
- Id
- Selects target device. See Table 7.
- Polarity
- Frequency value. (Unit: Hz)
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.4 I2C Functions
I2C APIs support standard 7 and 10 bits slave address mode. I2C APIs also support word command, it needs encode before set to parameter, see Table 13
- Table 12 I2C ID
|
Id |
Description |
|
SUSI_ID_I2C_EXTERNAL |
Main I2C host device |
|
SUSI_ID_I2C_OEM0~2 |
Other I2C host devices |
- Table 13 I2C command encode
|
Type |
Description |
|
Standard command |
Byte command |
|
Extend command |
Word command | 0x800000000 Ex. 0x8000FABC |
|
No command |
0x4000xxxx, ignore command parameter |
3.4.1 SusiI2CGetCaps
uint32_t SUSI_API SusiI2CGetCaps(uint32_t Id, uint32_t ItemId, uint32_t *pValue)
- Description:
- Gets I2C capabilities.
- Parameters:
- Id
- Selects target device. See Table 12.
- ItemId
- Selects target capability. See Table '14'.
- pValue
- Pointer to a buffer that receives the target capability.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pValue==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id or ItemId |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
- Table 14 I2C capabilities item Id
|
Item Id |
Description |
|
SUSI_ID_I2C_MAXIMUM_BLOCK_LENGTH |
I2C maximum block length |
|
|
|
3.4.2 SusiI2CWriteReadCombine
uint32_t SUSI_API SusiI2CWriteReadCombine(uint32_t Id, uint8_t Addr, uint8_t *pWBuffer, uint32_t WriteLen, uint8_t *pRBuffer, uint32_t ReadLen)
- Description:
- Universal function for read and write operations to the I2C bus.
- Parameters:
- Id
- Selects target device. See Table '14'.
- Addr
- First byte of I2C device address. 7-bit address only
- pWBuffer
- Pointer to a buffer containing the data to be transferred. This parameter can be NULL if the data is not required.
- WriteLen
- Size in bytes of the information pointed to by the pWBuffer parameter. If pWBuffer is NULL this will be ignored.
- pRBuffer
- Pointer to a buffer that receives the read data. This parameter can be NULL if the data is not required.
- Id
- ReadLen
- Size in bytes of the buffer pointed to by the pRBuffer parameter. If pRBuffer is NULL this will be ignored.
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
(WriteLen>1)&&(pWBuffer==NULL) |
SUSI _STATUS_INVALID_PARAMETER |
|
(RBufLen>1)&&(pRBuffer==NULL) |
SUSI _STATUS_INVALID_PARAMETER |
|
(WriteLen==0)&&(RBufLen==0) |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.4.3 SusiI2CReadTransfer
uint32_t SUSI_API SusiI2CReadTransfer(uint32_t Id, uint32_t Addr, uint32_t Cmd, uint8_t *pBuffer, uint32_t ReadLen)
- Description:
- Reads from a specific register in the selected I2C device. Reads from I2C device at the I2C address Addr the amount of ReadLen bytes to the buffer pBuffer while using the device specific command Cmd. Depending on the addressed I2C device Cmd can be a specific command or a byte offset.
- Parameters:
- Id
- Selects target device. See Table '14'.
- Addr
- Encoded 7/10 Bit I2C Device Address.
- Cmd
- Encoded I2C Device Command / Index. See Table '13'.
- pBuffer
- Pointer to a buffer that receives the read data.
- ReadLen
- Size in bytes of the buffer pointed to by the pBuffer parameter.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL || ReadLen==0 |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.4.4 SusiI2CWriteTransfer
uint32_t SUSI_API SusiI2CWriteTransfer(uint32_t Id, uint32_t Addr, uint32_t Cmd, uint8_t *pBuffer, uint32_t ByteCnt)
- Description:
- Write to a specific register in the selected I2C device. Writes to an I2C device at the I2C address Addr the amount of ByteCnt bytes from the buffer *pBuffer while using the device specific command Cmd. Depending on the addressed I2C device Cmd can be a specific command or a byte offset
- Parameters:
- Id
- Selects target device. See Table '14'.
- Addr
- Encoded 7/10 Bit I2C Device Address.
- Cmd
- Encoded I2C Device Command / Index. See Table '13'.
- pBuffer
- Pointer to a buffer that receives the write data.
- ByteCnt
- Size in bytes of the buffer pointed to by the pBuffer parameter.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL || ByteCnt==0 |
SUSI _STATUS_INVALID_PARAMETER |
|
ByteCnt > MaxLength |
SUSI_STATUS_INVALID_BLOCK_LENGTH |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.4.5 SusiI2CProbeDevice
uint32_t SUSI_API SusiI2CProbeDevice(uint32_t Id, uint32_t Addr)
- Description:
- Probes I2C address to test I2C device present.
- Parameters:
- Id
- Selects target device. See Table '14'.
- Addr
- Encoded 7/10 Bit I2C Device Address.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.4.6 SusiI2CGetFrequency
uint32_t SUSI_API SusiI2CGetFrequency(uint32_t Id, uint32_t *pFreq)
- Description:
- Get I2C clock frequency.
- Parameters:
- Id
- Selects target device. See Table '14'.
- pFreq
- Pointer to a buffer that receives the I2C clock frequency value. (Unit: Hz)
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
pFreq == NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Success |
SUSI_STATUS_SUCCESS |
3.4.7 SusiI2CSetFrequency
uint32_t SUSI_API SusiI2CSetFrequency(uint32_t Id, uint32_t Freq)
- Description:
- Set I2C clock frequency.
- Parameters:
- Id
- Selects target device. See Table '14'.
- Freq
- I2C clock frequency value. (Unit: Hz)
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Success |
SUSI_STATUS_SUCCESS |
3.5 SMBus Functions
SMBus is the System Management Bus defined by Intel® Corporation in 1995. It is used in personal computers and servers for low-speed system management communications.
- Table 15 SMBus ID
|
Id |
Description |
|
SUSI_ID_ SMBUS _EXTERNAL |
Main SMBus host device |
|
SUSI_ID_SMBUS_OEM0~3 |
Other SMBus host devices |
3.5.1 SusiSMBReadByte
uint32_t SUSI_API SusiSMBReadByte(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint8_t *pData)
- Description:
- Read a byte of data from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to read data from.
- pData
- Pointer to a variable in which the function reads the byte data.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pData==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.2 SusiSMBWriteByte
uint32_t SUSI_API SusiSMBWriteByte(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint8_t Data)
- Description:
- Write a byte of data to the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to write data to.
- Data
- Specifies the byte data to be written.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.3 SusiSMBReadWord
uint32_t SUSI_API SusiSMBReadWord(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint16_t *pData)
- Description:
- Read a word of data from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to read data from.
- pData
- Pointer to a variable in which the function reads the word data.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pData==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.4 SusiSMBWriteWord
uint32_t SUSI_API SusiSMBWriteWord(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint16_t Data)
- Description:
- Write a word of data to the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to write data to.
- Data
- Specifies the word data to be written.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.5 SusiSMBReceiveByte
uint32_t SUSI_API SusiSMBReceiveByte(uint32_t Id, uint8_t Addr, uint8_t *pData)
- Description:
- Receive a byte of data from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- pData
- Pointer to a variable in which the function receive the byte data.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.6 SusiSMBSendByte
uint32_t SUSI_API SusiSMBSendByte(uint32_t Id, uint8_t Addr, uint8_t Data)
- Description:
- Send a byte of data to the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Data
- Specifies the word data to be sent.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.7 SusiSMBReadQuick
uint32_t SUSI_API SusiSMBReadQuick(uint32_t Id, uint8_t Addr)
- Description:
- Turn SMBus device function off (on) or disable (enable) a specific device mode.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.8 SusiSMBWriteQuick
uint32_t SUSI_API SusiSMBWriteQuick(uint32_t Id, uint8_t Addr)
- Description:
- Turn SMBus device function off (on) or disable (enable) a specific device mode.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.9 SusiSMBReadBlock
uint32_t SUSI_API SusiSMBReadBlock(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint8_t *pBuffer, uint32_t *pLength)
- Description:
- Read multi-data from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to read data from.
- pBuffer
- Pointer to a byte array in which the function reads the block data.
- pLength
- Pointer to a byte in which specifies the number of bytes to be read and also return succeed bytes.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.10 SusiSMBWriteBlock
uint32_t SUSI_API SusiSMBWriteBlock(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint8_t *pBuffer, uint32_t Length)
- Description:
- Write multi-data from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to write data to.
- pBuffer
- Pointer to a byte array in which the function writes the block data.
- Length
- Specifies the number of bytes to be write.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.11 SusiSMBI2CReadBlock
uint32_t SUSI_API SusiSMBI2CReadBlock(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint8_t *pBuffer, uint32_t *pLength)
- Description:
- Read multi-data using I2C block protocol from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to read data from.
- pBuffer
- Pointer to a byte array in which the function reads the block data.
- pLength
- Pointer to a byte in which specifies the number of bytes to be read and also return succeed bytes.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |
3.5.12 SusiSMBI2CWriteBlock
uint32_t SUSI_API SusiSMBI2CWriteBlock(uint32_t Id, uint8_t Addr, uint8_t Cmd, uint8_t *pBuffer, uint32_t Length)
- Description:
- Write multi-data using I2C block protocol from the target slave device in the SMBus.
- Parameters:
- Id
- Selects target device. See Table '15'.
- Addr
- Specifies the 8-bit device address, ranging from 0x00 to 0xFF. Whether to give a 1 (read) or 0 (write) to the LSB of slave address could be ignored.
- Cmd
- Specifies the offset or command of the device register to write data to.
- pBuffer
- Pointer to a byte array in which the function writes the block data.
- Length
- Specifies the number of bytes to be write.
- Id
- Return Status Code:
|
Condition |
Return Value |
|
Library uninitialized |
SUSI_STATUS_NOT_INITIALIZED |
|
pBuffer==NULL |
SUSI _STATUS_INVALID_PARAMETER |
|
Unknown Id |
SUSI _STATUS_UNSUPPORTED |
|
Device unsupported |
SUSI _STATUS_UNSUPPORTED |
|
Bus Busy SDA/SDC low |
SUSI_STATUS_BUSY_COLLISION |
|
Arbitration Error/Collision Error On Write 1 write cycle SDA Remains low |
SUSI_STATUS_BUSY_COLLISION |
|
Time-out due to clock stretching |
SUSI_STATUS_TIMEOUT |
|
Address Non-ACK |
SUSI_STATUS_NOT_FOUND |
|
Write Non-ACK |
SUSI_STATUS_WRITE_ERROR |
|
Success |
SUSI_STATUS_SUCCESS |