Diagnosis system

Collaboration diagram for Diagnosis system:

Functions
MLPIRESULT	mlpiSystemGetDisplayedDiagnosis (const MLPIHANDLE connection, MlpiDiagnosis *diagnosis)
MLPIRESULT	mlpiSystemSetDiagnosis (const MLPIHANDLE connection, const MlpiDiagnosisCategory category, const USHORT number, const WCHAR16 *diagnosisText=0)
MLPIRESULT	mlpiSystemGetNewestDiagnosisIndex (const MLPIHANDLE connection, ULONG *index)
MLPIRESULT	mlpiSystemGetOldestDiagnosisIndex (const MLPIHANDLE connection, ULONG *index)
MLPIRESULT	mlpiSystemGetDiagnosisLog (const MLPIHANDLE connection, const ULONG index, MlpiDiagnosis *diagnosisLog, const ULONG numElements, ULONG *numElementsRet)
MLPIRESULT	mlpiSystemConvertDiagnosisNumberToText (const MLPIHANDLE connection, const ULONG diagnosisNumber, WCHAR16 *diagnosisText, const ULONG numElements)
MLPIRESULT	mlpiSystemSetBootLed (const MLPIHANDLE connection, const MlpiLedPattern pattern, const LONG count=-1)
MLPIRESULT	mlpiSystemClearBootLed (const MLPIHANDLE connection)

Detailed Description

The following functions provide access to the internal diagnosis logbook on the target device. For a detailed description of all error codes and diagnosis numbers, please have a look to the diagnosis help of the device you are connected too.

Function Documentation

MLPIRESULT mlpiSystemGetDisplayedDiagnosis	(	const MLPIHANDLE	connection,
		MlpiDiagnosis *	diagnosis
	)

This function reads the displayed diagnostic message of the device. The displayed diagnosis is the diagnosis with the highest severity of all currently active diagnoses. This means, that the displayed diagnostic message can differ from the latest or last inserted diagnostic message.

Parameters

[in]	connection	Handle for multiple connections.
[out]	diagnosis	Pointer to structure where the diagnosis will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Read the displayed diagnostic message of the device.
MlpiDiagnosis diagnosis;
memset(&diagnosis, 0, sizeof(diagnosis));
MLPIRESULT result = mlpiSystemGetDisplayedDiagnosis(connection, &diagnosis);

if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
} else {
  printf("\n0x%08X %s", diagnosis.number, W2A16(diagnosis.text));
}

MLPIRESULT mlpiSystemSetDiagnosis	(	const MLPIHANDLE	connection,
		const MlpiDiagnosisCategory	category,
		const USHORT	number,
		const WCHAR16 *	diagnosisText = 0
	)

This function writes a diagnosis with message to the diagnosis system of the device. The diagnostic group is set to 0x3F automatically.

Parameters

[in]	connection	Handle for multiple connections.
[in]	category	Diagnosis category (MlpiDiagnosisCategory).
[in]	number	User specific diagnosis number.
[in]	diagnosisText	Diagnosis text.

Note

The maximum length of a diagnosis text is 60 characters.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Write a diagnosis with message to the diagnosis system of the device.
USHORT number = 1;
WCHAR16 diagnosisText[] = L"This is a new diagnosis";
MLPIRESULT result = mlpiSystemSetDiagnosis(connection, MLPI_DIAGNOSIS_ERROR_NONFATAL, number, diagnosisText);

MLPIRESULT mlpiSystemGetNewestDiagnosisIndex	(	const MLPIHANDLE	connection,
		ULONG *	index
	)

Each new diagnosis in the diagnosis logbook gets a unique incremented diagnosis index. This function returns the index of the latest and therefore most recently inserted diagnosis. This index can be used as a parameter using the function mlpiSystemGetDiagnosisLog to read the complete logbook of the newest diagnostic messages.

Parameters

[in]	connection	Handle for multiple connections.
[out]	index	Pointer to variable where the index of the newest diagnosis will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Read the index of the latest diagnosis in the diagnosis logbook of the device.
ULONG index = 0;
MLPIRESULT result = mlpiSystemGetNewestDiagnosisIndex(connection, &index);

MLPIRESULT mlpiSystemGetOldestDiagnosisIndex	(	const MLPIHANDLE	connection,
		ULONG *	index
	)

As the device is limited in memory resources, it is not possible to hold all diagnostic messages in the logbook from the start of power up. Because of that, older diagnostic messages are first swapped to disk and then discarded. Use this function to get the index of the oldest diagnostic message that is still in memory and can be returned by the function mlpiSystemGetDiagnosisLog.

Parameters

[in]	connection	Handle for multiple connections.
[out]	index	Pointer to variable where the index of oldest diagnosis will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Read the index of oldest diagnosis in the diagnosis logbook of the device.
ULONG index = 0;
MLPIRESULT result = mlpiSystemGetOldestDiagnosisIndex(connection, &index);

MLPIRESULT mlpiSystemGetDiagnosisLog	(	const MLPIHANDLE	connection,
		const ULONG	index,
		MlpiDiagnosis *	diagnosisLog,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function reads the device diagnosis log. The function returns an array of diagnostic messages starting from newer to older diagnostic messages. Each diagnosis in the diagnosis logbook has a unique incrementing diagnosis index. You need to specify from which index you want to start reading the diagnosis logbook. To get the index of the latest and thus most recently inserted diagnosis, you can use the function mlpiSystemGetNewestDiagnosisIndex. As the device is limited in memory resources, it is not possible to hold all diagnostic messages in the logbook from the start of power up. Because of that, older diagnostic messages are first swapped to disk and then discarded. Use the function mlpiSystemGetOldestDiagnosisIndex to get the oldest available diagnosis to read. Diagnostic messages which are not located between the oldest and newest diagnosis index can no longer be read by this function. This function will therefore return the number of diagnoses that have actually been read. This function will not return an error if the number of diagnoses you want to read is larger than the number of diagnoses that are available.

Parameters

[in]	connection	Handle for multiple connections.
[in]	index	Index of the first diagnosis index to start reading.
[out]	diagnosisLog	Pointer to an array of structure where the diagnosis will be stored.
[in]	numElements	Number of MlpiDiagnosis elements available in 'diagnosisLog' for reading.
[out]	numElementsRet	Number of elements used.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Read the complete diagnosis log of the device.
MlpiDiagnosis diagnosisLog[1000];
ULONG numElementsRet = 0;
ULONG indexNewest = 0;
ULONG indexOldest = 0;
memset(diagnosisLog, 0, sizeof(diagnosisLog));

mlpiSystemGetOldestDiagnosisIndex(connection, &indexOldest);
mlpiSystemGetNewestDiagnosisIndex(connection, &indexNewest);
mlpiSystemGetDiagnosisLog(connection, indexNewest, diagnosisLog, min(indexNewest-indexOldest,_countof(diagnosisLog)), &numElementsRet);

for (ULONG i=0; i<numElementsRet; i++){
  printf("\n%i 0x%X %s", diagnosisLog[i].index, diagnosisLog[i].number, W2A16(diagnosisLog[i].text));
}

MLPIRESULT mlpiSystemConvertDiagnosisNumberToText	(	const MLPIHANDLE	connection,
		const ULONG	diagnosisNumber,
		WCHAR16 *	diagnosisText,
		const ULONG	numElements
	)

This function tries to retrieve a textual description for a given diagnosis number. Please note that this is not possible for every diagnosis number that is returned from the system. This includes user-specific diagnosis numbers or diagnosis numbers which represent a group of error conditions. In case no match was found, the string "No entry found in data base" is returned.

Parameters

[in]	connection	Handle for multiple connections.
[in]	diagnosisNumber	Diagnosis number.
[out]	diagnosisText	String where the diagnosis text will be stored.
[in]	numElements	Number of WCHAR16 elements available in 'diagnosisText' for reading.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Read the textual description for a diagnosis number.
ULONG diagnosisNumber = 0xF02D1001;
WCHAR16 diagnosisText[256] = L"";
MLPIRESULT result = mlpiSystemConvertDiagnosisNumberToText(connection, diagnosisNumber, diagnosisText, _countof(diagnosisText));

if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
} else {
  printf("\n%08X means: %s", diagnosisNumber, W2A16(diagnosisText));
}

MLPIRESULT mlpiSystemSetBootLed	(	const MLPIHANDLE	connection,
		const MlpiLedPattern	pattern,
		const LONG	count = -1
	)

This function switch on the boot LED 'BT' (if available) regarding the selected MlpiLedPattern pattern.

Note

Because the system use the boot LED 'BT' for signal boot status, the function will return an error if system is still booting.

• MLPI_E_NOTINITIALIZED: Boot end not achieved yet.
• MLPI_E_STARTERROR: Boot finished with error(s), reboot may be required.

Parameters

[in]	connection	Handle for multiple connections.
[in]	pattern	LED pattern.
[in]	count	Count of repeat pattern. Use "-1" for repeat infinite.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Switch on the boot LED 'BT' permanently.
MLPIRESULT result = mlpiSystemSetBootLed(connection, MLPI_LED_PATTERN_GREEN);

if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
}

MLPIRESULT mlpiSystemClearBootLed

(

const MLPIHANDLE

connection

)

This function switch off the boot LED 'BT' (if available).

Note

Because the system use the boot LED 'BT' for signal boot status, the function will return an error if system is still booting.

• MLPI_E_NOTINITIALIZED: Boot end not achieved yet.
• MLPI_E_STARTERROR: Boot finished with error(s), reboot may be required.

Parameters

[in]

connection

Handle for multiple connections.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Switch off the boot LED 'BT'.
MLPIRESULT result = mlpiSystemClearBootLed(connection);

if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
}