This interface enables the development of Intel SoC firmware/operating system provisioning applications. This API is not re-entrant. More...

#include <xfstkdldrapi.h>

Public Member Functions
	xfstkdldrapi ()
	Constructs a new xfstkdldrapi instance. More...

virtual	~xfstkdldrapi ()
	Distructs a xfstkdldrapi instance. More...

virtual bool	idrqresponse (unsigned char *buffer, int maxsize)
	Allows for the retrieval of the IDRQ response from a device. More...

virtual bool	downloadcli (const char cli, const char usbsn=NULL)
	API method to simulate CLI. More...

virtual bool	downloadfw (char *fwfile)
	Allows downloading a fwimage via spi. More...

virtual bool	hashverify (char *hashfile, bool write)
	Allows for the writing of a device hash or comparing of the hash to a golden hash file. More...

virtual void	setResponsebuffer (unsigned char *responseBuffer, int &maxsize)
	Set the response buffer for downloader operations. More...

virtual bool	downloadcsdb (char fwdnx, char miscbin, char cmdcode, char fwimage, bool direct)
	download csdb payloads More...

virtual bool	downloadfw (char fwdnx, char fwimage, char *gpflags)
	Performs single shot firmware only download. More...

virtual bool	downloados (char osdnx, char osimage, char *gpflags)
	Performs single shot operating system only download. More...

virtual bool	downloadfwos (char fwdnx, char fwimage, char osdnx, char osimage, char *gpflags)
	Performs single shot firmware and operating system download. More...

virtual bool	downloadfwos (char fwdnx, char fwimage, char osdnx, char osimage, char gpflags, char softfuse)
	Performs single shot firmware and operating system download. More...

virtual bool	downloadmtfwosasync (char fwdnx, char fwimage, char osdnx, char osimage, char gpflags, char usbsn)
	Performs parallel multitarget firmware and operating system download in async mode, it will return after the download to the device is done. More...

virtual bool	downloadmtfwosasync (char fwdnx, char fwimage, char osdnx, char osimage, char gpflags, char usbsn, char *softfuse)
	Performs parallel multitarget firmware and operating system download in async mode, it will return after the download to the device is done. More...

virtual bool	registerstatuscallback (xfstkstatuspfn statuspfn, void *clientdata)
	Registers a callback with the xfstk api in order to obtain download status information. More...

virtual void	settargetretrycount (int retries)
	Sets the number of retries to perform during faulty USB I/O. More...

virtual void	setloglevel (unsigned long loglevel)
	Sets log level for the API to limit the messages send back to the callback. More...

virtual void	setsoftfusepath (bool include, char *softfuse)
	Sets the files path for softfuse. More...

virtual void	setmiscdnxpath (bool enable, char *miscdnx)
	Sets the files path for miscdnx, this one is only for advanced feature in TNG USB 3.0 POC. More...

virtual int	getavailabletargets ()
	Reports the number of available targets connected to the host system. More...

virtual int	getavailabletargets (unsigned long devicetype)
	Reports the number of available targets connected to the host system for devicetype. More...

virtual int	getavailabletargets (SoCDevices *socdevices)
	Reports the number of available targets connected to the host system. More...

virtual void	usbdevicemutexlock ()
	Lock the usb device mutex, only call this before scanning the device for USBSN. More...

virtual void	usbdevicemutexunlock ()
	Unlock the usb device mutex, call this after a UBS device is found and before call downloadmtfwosasync(). More...

virtual void	getversion (char *version)
	Get the XFSTK API version string. More...

virtual std::string	getfullversion (void) const
	Get the XFSTK API version string. More...

virtual bool	getlasterror (LastError *er)
	Get the Last error from XFSTK API version string. More...

virtual void	setusbreadwritedelay (unsigned long delayms)
	Set the delay time for before each USB bulk read/write in miliseconds. More...

virtual void	setwipeifwi (bool enable)
	Not a POR feature, only a testing/debug feature. More...

Detailed Description

This interface enables the development of Intel SoC firmware/operating system provisioning applications. This API is not re-entrant.

Below is a diagram illustrating the general host/target configurations that the API can be used in.

\image html xfstkcmdclientflow.png

REM

Constructor & Destructor Documentation

xfstkdldrapi::xfstkdldrapi ( )

Constructs a new xfstkdldrapi instance.

Parameters

None

Returns: a pointer to a physical instance of xfstkdldrapi.

Exceptions

None

Note: None

virtual xfstkdldrapi::~xfstkdldrapi ( )

virtual

Distructs a xfstkdldrapi instance.

Parameters

None

Returns: a pointer to a physical instance of xfstkdldrapi.

Exceptions

None

Note: None

Member Function Documentation

virtual bool xfstkdldrapi::idrqresponse	(	unsigned char *	buffer,
		int	maxsize
	)

virtual

Allows for the retrieval of the IDRQ response from a device.

DEPRECATED: Use setResponsebuffer & downloadercli methods

Parameters

buffer	is the where the IDRQ response will be stored
maxsize	is the maximum space allocated for buffer

Returns: TRUE if operation was a success or else FALSE

Exceptions

none

Note: Method currently only works for Merrifield platforms only

virtual bool xfstkdldrapi::downloadcli	(	const char *	cli,
		const char *	usbsn = `NULL`
	)

virtual

API method to simulate CLI.

Parameters

CLI	string
usbsn	serial number string of device to perform operation on.

Returns: TRUE if operation was a success or else FALSE

Exceptions

none

virtual bool xfstkdldrapi::downloadfw ( char * fwfile )

virtual

Allows downloading a fwimage via spi.

Parameters

fwfile is the file that is downloaded

Returns: TRUE if downloads without error

Exceptions

none

virtual bool xfstkdldrapi::hashverify	(	char *	hashfile,
		bool	write
	)

virtual

Allows for the writing of a device hash or comparing of the hash to a golden hash file.

Parameters

hashfile	is the file that will be written to, or the golden file that will be compared to
write	is the value that determines whether to write to file(TRUE) or read from and compare(FALSE)

Returns: TRUE if matching hashes or else FALSE

Exceptions

none

Note: If writing HASH destination file must be present

virtual void xfstkdldrapi::setResponsebuffer	(	unsigned char *	responseBuffer,
		int &	maxsize
	)

virtual

Set the response buffer for downloader operations.

Parameters

responseBuffer	buffer to be used
maxsize	the maximum size of the buffer

Returns: none

Exceptions

\note Call this before running the operations that elicit a response from the device

Note: The maxsize input variable will be updated with the buffer size retrieved from the device

virtual bool xfstkdldrapi::downloadcsdb	(	char *	fwdnx,
		char *	miscbin,
		char *	cmdcode,
		char *	fwimage,
		bool	direct
	)

virtual

download csdb payloads

DEPRECATED: Use setResponsebuffer & downloadercli methods

Parameters

fwdnx	Firmware download and execute (DnX) module.
miscbin	CSDB Payload file
cmdcode	CSDB command code
fwimage	Firmware binary image.
direct	command no longer valid

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: It is recommended to use the downloadcli() method for CSDB instead

virtual bool xfstkdldrapi::downloadfw	(	char *	fwdnx,
		char *	fwimage,
		char *	gpflags
	)

virtual

Performs single shot firmware only download.

Parameters

fwdnx	Firmware download and execute (DnX) module.
fwimage	Firmware binary image.
gpflags	General purpose flags to control download process. For firmware only download specify 0x80000000.

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: gpflags can be set to other values. Please contact your Intel representative for additional details.

virtual bool xfstkdldrapi::downloados	(	char *	osdnx,
		char *	osimage,
		char *	gpflags
	)

virtual

Performs single shot operating system only download.

Parameters

osdnx	Operating System download and execute (DnX) module.
osimage	Operating System binary image.
gpflags	General purpose flags to control download process. For os only download specify 0x80000001.

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: gpflags can be set to other values. Please contact your Intel representative for additional details.

virtual bool xfstkdldrapi::downloadfwos	(	char *	fwdnx,
		char *	fwimage,
		char *	osdnx,
		char *	osimage,
		char *	gpflags
	)

virtual

Performs single shot firmware and operating system download.

Parameters

fwdnx	Firmware download and execute (DnX) module.
fwimage	Firmware binary image.
osdnx	Operating System download and execute (DnX) module.
osimage	Operating System binary image.
gpflags	General purpose flags to control download process. For firmware & os download specify 0x80000001.

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: gpflags can be set to other values. Please contact your Intel representative for additional details.

Referenced by main().

Here is the caller graph for this function:

virtual bool xfstkdldrapi::downloadfwos	(	char *	fwdnx,
		char *	fwimage,
		char *	osdnx,
		char *	osimage,
		char *	gpflags,
		char *	softfuse
	)

virtual

Performs single shot firmware and operating system download.

Parameters

fwdnx	Firmware download and execute (DnX) module.
fwimage	Firmware binary image.
osdnx	Operating System download and execute (DnX) module.
osimage	Operating System binary image.
gpflags	General purpose flags to control download process. For firmware & os download specify 0x80000001.
softfuse	Softfuse binary image.

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: gpflags can be set to other values. Please contact your Intel representative for additional details.

virtual bool xfstkdldrapi::downloadmtfwosasync	(	char *	fwdnx,
		char *	fwimage,
		char *	osdnx,
		char *	osimage,
		char *	gpflags,
		char *	usbsn
	)

virtual

Performs parallel multitarget firmware and operating system download in async mode, it will return after the download to the device is done.

Parameters

fwdnx	Firmware download and execute (DnX) module.
fwimage	Firmware binary image.
osdnx	Operating System download and execute (DnX) module.
osimage	Operating System binary image.
gpflags	General purpose flags to control download process. For firmware & os download specify 0x80000001.
usbsn	the usb serial number of the device, client need to detect the USB serial number first and provide it to the API.

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: gpflags can be set to other values. Please contact your Intel representative for additional details. When programming multiple targets 1 thread will be spawned per target if possible.; **** The client app will need to detect the device and use the detected USBSN to start a thread to call this API, prefered method for MFG tools.

Referenced by DlThreadObj::DldrRun().

Here is the caller graph for this function:

virtual bool xfstkdldrapi::downloadmtfwosasync	(	char *	fwdnx,
		char *	fwimage,
		char *	osdnx,
		char *	osimage,
		char *	gpflags,
		char *	usbsn,
		char *	softfuse
	)

virtual

Performs parallel multitarget firmware and operating system download in async mode, it will return after the download to the device is done.

Parameters

fwdnx	Firmware download and execute (DnX) module.
fwimage	Firmware binary image.
osdnx	Operating System download and execute (DnX) module.
osimage	Operating System binary image.
gpflags	General purpose flags to control download process. For firmware & os download specify 0x80000001.
usbsn	the usb serial number of the device, client need to detect the USB serial number first and provide it to the API.
softfuse	Softfuse binary image.

Returns: True / False status indicating provisioning success / failure.

Exceptions

None

Note: gpflags can be set to other values. Please contact your Intel representative for additional details. When programming multiple targets 1 thread will be spawned per target if possible.; **** The client app will need to detect the device and use the detected USBSN to start a thread to call this API, prefered method for MFG tools.

virtual bool xfstkdldrapi::registerstatuscallback	(	xfstkstatuspfn	statuspfn,
		void *	clientdata
	)

virtual

Registers a callback with the xfstk api in order to obtain download status information.

Parameters

statuspfn	Pointer to a callback function which has the same signature as xfstkstatuspfn.
clientdata	Optional pointer to a client data object. Can be NULL.

Returns: True / False status indicating registration success / failure.

Exceptions

None

See Also: This setting can be used to work around host side USB issues. Such issues may be caused by faulty usb hubs, usb hub daisy chains, very high host system load, poor quality usb cables, usb enumeration delays within host operating system, etc...

Referenced by DlThreadObj::DldrRun(), and main().

Here is the caller graph for this function:

virtual void xfstkdldrapi::settargetretrycount ( int retries )

virtual

Sets the number of retries to perform during faulty USB I/O.

Parameters

retries Integer value corresponding to the number of times to retry faulty USB I/O transfers. Default is 40.

Returns: None

Exceptions

None

Note: This setting can be used to work around host side USB issues. Such issues may be caused by faulty usb hubs, usb hub daisy chains, very high host system load, poor quality usb cables, usb enumeration delays within host operating system, etc...

Referenced by DlThreadObj::DldrRun(), and main().

Here is the caller graph for this function:

virtual void xfstkdldrapi::setloglevel ( unsigned long loglevel )

virtual

Sets log level for the API to limit the messages send back to the callback.

Parameters

unsigned long, loglevel

Returns: None

Exceptions

None

virtual void xfstkdldrapi::setsoftfusepath	(	bool	include,
		char *	softfuse
	)

virtual

Sets the files path for softfuse.

Parameters

type	- bool - include/exclude softfuse.
type	- char * - string path for softfuse file.

Returns: None

Exceptions

None

Note

virtual void xfstkdldrapi::setmiscdnxpath	(	bool	enable,
		char *	miscdnx
	)

virtual

Sets the files path for miscdnx, this one is only for advanced feature in TNG USB 3.0 POC.

Parameters

type	- bool - enable/disable miscdnx.
type	- char * - string path for miscdnx file.

Returns: None

Exceptions

None

Note

virtual int xfstkdldrapi::getavailabletargets ( )

virtual

Reports the number of available targets connected to the host system.

Parameters

None

Returns: Integer value representing the number of conencted targets

Exceptions

None

Note: Visibility of targets is dependent on your firmware configuration. If you are having a problem detecting targets please contact your Intel representative for assistance.

Referenced by main().

Here is the caller graph for this function:

virtual int xfstkdldrapi::getavailabletargets ( unsigned long devicetype )

virtual

Reports the number of available targets connected to the host system for devicetype.

Parameters

None

Returns: Integer value representing the number of conencted targets

Exceptions

None

Note: Visibility of targets is dependent on your firmware configuration. If you are having a problem detecting targets please contact your Intel representative for assistance.

virtual int xfstkdldrapi::getavailabletargets ( SoCDevices * socdevices )

virtual

Reports the number of available targets connected to the host system.

Parameters

socdevices An array of the socdevice port mapping data for detected devices

Returns: Integer value representing the number of conencted targets

Exceptions

None

Note: The data from socdevices can be used by Client Apps to display the port info and usbsn based the physical port.

virtual void xfstkdldrapi::usbdevicemutexlock ( )

virtual

Lock the usb device mutex, only call this before scanning the device for USBSN.

Parameters

None

Returns: None

Exceptions

None

Note: Since libusb driver is not multi thread safe during USB device enumeration, we added this lock for thread safty.

virtual void xfstkdldrapi::usbdevicemutexunlock ( )

virtual

Unlock the usb device mutex, call this after a UBS device is found and before call downloadmtfwosasync().

Parameters

None

Returns: None

Exceptions

None

Note: Client should not hold this lock when call the API downloadmtfwosasync() to start download since this mutex is shared with API \ It will block the API if it is in lock status before call the API.

virtual void xfstkdldrapi::getversion ( char * version )

virtual

Get the XFSTK API version string.

Parameters

char*,client should allocate memory for this version string, should be at least 8 byte long.

Returns: None

Exceptions

None

Note

virtual std::string xfstkdldrapi::getfullversion ( void ) const

virtual

Get the XFSTK API version string.

Parameters

\return std::string

Exceptions

None

Note

virtual bool xfstkdldrapi::getlasterror ( LastError * er )

virtual

Get the Last error from XFSTK API version string.

Parameters

LastError*,client should allocate memory for the LastError.

Returns: true/false

Exceptions

None

Note

Referenced by DlThreadObj::DldrRun().

Here is the caller graph for this function:

virtual void xfstkdldrapi::setusbreadwritedelay ( unsigned long delayms )

virtual

Set the delay time for before each USB bulk read/write in miliseconds.

Parameters

unsigned long delayms.

Returns: true/false

Exceptions

None

Note: For some hubs or PCI -E USB cards, it may adjust this delay to make it more stable.

Referenced by DlThreadObj::DldrRun().

Here is the caller graph for this function:

virtual void xfstkdldrapi::setwipeifwi ( bool enable )

virtual

Not a POR feature, only a testing/debug feature.

Set enable or disable to wipe out ifwi image content before flash the new ifwi, If set gpflags = 0x80000000 and set to enable, then it will only wipe out ifwi wout flashing a new one, to make the device like a virgin part, but it won't erase OS and user data though.

Parameters

bool	- true - enable, false - disable.

Returns: true/false

Exceptions

None

Note

Referenced by DlThreadObj::DldrRun().

Here is the caller graph for this function:

The documentation for this class was generated from the following file:

xfstkdldrapi.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation