xFSTK  0.0.0
Intel SoC Cross Platform Firmware & Software Tool Kit
Public Member Functions | List of all members
xfstkdldrapi Class Reference

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::xfstkdldrapi ( )

Constructs a new xfstkdldrapi instance.

Parameters
None
Returns
a pointer to a physical instance of xfstkdldrapi.
Exceptions
None
Note
None

◆ ~xfstkdldrapi()

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

◆ idrqresponse()

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
bufferis the where the IDRQ response will be stored
maxsizeis 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

◆ downloadcli()

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

API method to simulate CLI.

Parameters
CLIstring
usbsnserial number string of device to perform operation on.
Returns
TRUE if operation was a success or else FALSE
Exceptions
none

◆ downloadfw() [1/2]

virtual bool xfstkdldrapi::downloadfw ( char *  fwfile)
virtual

Allows downloading a fwimage via spi.

Parameters
fwfileis the file that is downloaded
Returns
TRUE if downloads without error
Exceptions
none

◆ hashverify()

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
hashfileis the file that will be written to, or the golden file that will be compared to
writeis 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

◆ setResponsebuffer()

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

Set the response buffer for downloader operations.

Parameters
responseBufferbuffer to be used
maxsizethe maximum size of the buffer
Returns
none
Exceptions

◆ downloadcsdb()

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

download csdb payloads

DEPRECATED: Use setResponsebuffer & downloadercli methods

Parameters
fwdnxFirmware download and execute (DnX) module.
miscbinCSDB Payload file
cmdcodeCSDB command code
fwimageFirmware binary image.
directcommand 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

◆ downloadfw() [2/2]

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

Performs single shot firmware only download.

Parameters
fwdnxFirmware download and execute (DnX) module.
fwimageFirmware binary image.
gpflagsGeneral 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.

◆ downloados()

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

Performs single shot operating system only download.

Parameters
osdnxOperating System download and execute (DnX) module.
osimageOperating System binary image.
gpflagsGeneral 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.

◆ downloadfwos() [1/2]

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

Performs single shot firmware and operating system download.

Parameters
fwdnxFirmware download and execute (DnX) module.
fwimageFirmware binary image.
osdnxOperating System download and execute (DnX) module.
osimageOperating System binary image.
gpflagsGeneral 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:

◆ downloadfwos() [2/2]

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
fwdnxFirmware download and execute (DnX) module.
fwimageFirmware binary image.
osdnxOperating System download and execute (DnX) module.
osimageOperating System binary image.
gpflagsGeneral purpose flags to control download process. For firmware & os download specify 0x80000001.
softfuseSoftfuse 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.

◆ downloadmtfwosasync() [1/2]

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
fwdnxFirmware download and execute (DnX) module.
fwimageFirmware binary image.
osdnxOperating System download and execute (DnX) module.
osimageOperating System binary image.
gpflagsGeneral purpose flags to control download process. For firmware & os download specify 0x80000001.
usbsnthe 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:

◆ downloadmtfwosasync() [2/2]

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
fwdnxFirmware download and execute (DnX) module.
fwimageFirmware binary image.
osdnxOperating System download and execute (DnX) module.
osimageOperating System binary image.
gpflagsGeneral purpose flags to control download process. For firmware & os download specify 0x80000001.
usbsnthe usb serial number of the device, client need to detect the USB serial number first and provide it to the API.
softfuseSoftfuse 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.

◆ registerstatuscallback()

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

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

Parameters
statuspfnPointer to a callback function which has the same signature as xfstkstatuspfn.
clientdataOptional 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:

◆ settargetretrycount()

virtual void xfstkdldrapi::settargetretrycount ( int  retries)
virtual

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

Parameters
retriesInteger 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:

◆ setloglevel()

virtual void xfstkdldrapi::setloglevel ( unsigned long  loglevel)
virtual

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

Parameters
unsignedlong, loglevel
Returns
None
Exceptions
None

◆ setsoftfusepath()

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

◆ setmiscdnxpath()

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

◆ getavailabletargets() [1/3]

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:

◆ getavailabletargets() [2/3]

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.

◆ getavailabletargets() [3/3]

virtual int xfstkdldrapi::getavailabletargets ( SoCDevices socdevices)
virtual

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

Parameters
socdevicesAn 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.

◆ usbdevicemutexlock()

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.

◆ usbdevicemutexunlock()

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.

◆ getversion()

virtual void xfstkdldrapi::getversion ( char *  version)
virtual

Get the XFSTK API version string.

Parameters
char*,clientshould allocate memory for this version string, should be at least 8 byte long.
Returns
None
Exceptions
None
Note

◆ getfullversion()

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

Get the XFSTK API version string.

Parameters

◆ getlasterror()

virtual bool xfstkdldrapi::getlasterror ( LastError er)
virtual

Get the Last error from XFSTK API version string.

Parameters
LastError*,clientshould allocate memory for the LastError.
Returns
true/false
Exceptions
None
Note

Referenced by DlThreadObj::DldrRun().

Here is the caller graph for this function:

◆ setusbreadwritedelay()

virtual void xfstkdldrapi::setusbreadwritedelay ( unsigned long  delayms)
virtual

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

Parameters
unsignedlong 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:

◆ setwipeifwi()

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: