Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Macros | Functions
Image Management And Configuration [OPENAPI_IMAGE]

Macros

#define OPEN_IMAGE_NAME_NONE   "none"
 
#define OPEN_UBOOT_VERSION_LENGTH   17 /* UBOOT_VERSION_LENGTH + 1 */
 

Functions

open_error_t openapiBootCodeUpdate (openapiClientHandle_t *client_handle, uint32_t unit)
 Updates the bootcode from the currently activated image. More...
 
open_error_t openapiBootCodeVersion (openapiClientHandle_t *client_handle, open_buffdesc *version)
 Gets the boot code version from the current active image. More...
 
open_error_t openapiImageActivate (openapiClientHandle_t *client_handle, uint32_t unit, open_buffdesc *imageLabel, OPEN_BOOL_t updateBootCode)
 Sets the specified image as the active image for the subsequent re-boots. More...
 
open_error_t openapiImageDelete (openapiClientHandle_t *client_handle, uint32_t unit, open_buffdesc *imageLabel)
 Deletes the specified image. More...
 
open_error_t openapiImageDescrGet (openapiClientHandle_t *client_handle, open_buffdesc *imageLabel, open_buffdesc *imageDescr)
 Get the text description for a given image. More...
 
open_error_t openapiImageDescrSet (openapiClientHandle_t *client_handle, open_buffdesc *imageLabel, open_buffdesc *imageDescr)
 Set the text description for a given image. More...
 
open_error_t openapiImageLabelIsValid (openapiClientHandle_t *client_handle, open_buffdesc *imageLabel, OPEN_BOOL_t *isValid)
 Determines if the image label refers to a valid image name. More...
 
open_error_t openapiImageLabelsGet (openapiClientHandle_t *client_handle, open_buffdesc *activeLabel, open_buffdesc *backupLabel)
 Get the label names for both active and backup images. More...
 
open_error_t openapiImageNamesGet (openapiClientHandle_t *client_handle, uint32_t unit, open_buffdesc *activeImage, open_buffdesc *backupImage, open_buffdesc *activatedImage)
 Get the image names for both active, backup, and activated. More...
 
open_error_t openapiImageUpgrade (openapiClientHandle_t *client_handle, open_buffdesc *imagePath, open_buffdesc *imageLabel)
 Get a locally copied image path, perform validation on it and on success, upgrade the switch with this image. More...
 

Detailed Description

Function Documentation

open_error_t openapiBootCodeUpdate ( openapiClientHandle_t client_handle,
uint32_t  unit 
)

Updates the bootcode from the currently activated image.

Parameters
[in]client_handleClient handle from registration API.
[in]unitUnit number
-Minimum value 1
-Maximum value openapiUnitMgrUnitMaxGet()
Return values
OPEN_E_NONEif validation is successful.
OPEN_E_PARAMif parameters is not defined correctly.
OPEN_E_UNAVAILNot supported for this platform.
Note
This API is valid for the management unit in a stacking build.

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiBootCodeVersion ( openapiClientHandle_t client_handle,
open_buffdesc version 
)

Gets the boot code version from the current active image.

Parameters
[in]client_handleClient handle from registration API.
[out]versionBoot code version
Return values
OPEN_E_NONEBoot code version get successful.
OPEN_E_FAILBoot code version get failed.
OPEN_E_PARAMError in parameter passed.

OpEN API Version: 1.19

Examples:
image_example.c.
open_error_t openapiImageActivate ( openapiClientHandle_t client_handle,
uint32_t  unit,
open_buffdesc imageLabel,
OPEN_BOOL_t  updateBootCode 
)

Sets the specified image as the active image for the subsequent re-boots.

Parameters
[in]client_handleClient handle from registration API.
[in]unitUnit number
-Minimum value 1
-Maximum value openapiUnitMgrUnitMaxGet()
[in]imageLabelImage label name
-Minimum length 1
-Maximum value openapiImageFileNameMaxLengthGet()
[in]updateBootCodeOPEN_TRUE to activate, else OPEN_FALSE
Return values
OPEN_E_NONEif text set successful.
OPEN_E_FAILif text set failed.
OPEN_E_PARAMif parameters is not defined correctly.
OPEN_E_NOT_FOUNDif image not found.
OPEN_E_UNAVAILif the specified image is not the backup image
OPEN_E_EXISTSif the image is already activated

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageDelete ( openapiClientHandle_t client_handle,
uint32_t  unit,
open_buffdesc imageLabel 
)

Deletes the specified image.

Parameters
[in]client_handleClient handle from registration API.
[in]unitUnit number
-Minimum value 1
-Maximum value openapiUnitMgrUnitMaxGet()
[in]imageLabelImage label name
-Minimum length 1
-Maximum value openapiImageFileNameMaxLengthGet()
Return values
OPEN_E_NONEif text set successful.
OPEN_E_FAILif text set failed.
OPEN_E_PARAMif parameters is not defined correctly.
OPEN_E_NOT_FOUNDif image not found.
OPEN_E_UNAVAILif the specified image is active/activated.
Note
The current active image is never deleted.
The activated backup image is never deleted.
Some products with dual image capability permit the user to delete the backup image only.

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageDescrGet ( openapiClientHandle_t client_handle,
open_buffdesc imageLabel,
open_buffdesc imageDescr 
)

Get the text description for a given image.

Parameters
[in]client_handleClient handle from registration API
[in]imageLabelImage label name
-Buffer size should be openapiImageFileNameMaxLengthGet()
[out]imageDescrAssociated text
-Buffer size should be OPENAPI_DEFAULT_IMAGE_DESCR_MAX
Return values
OPEN_E_NONEif text get successful.
OPEN_E_FAILif text get failed.
OPEN_E_PARAMif parameters is not defined correctly.
OPEN_E_NOT_FOUNDif image not found.

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageDescrSet ( openapiClientHandle_t client_handle,
open_buffdesc imageLabel,
open_buffdesc imageDescr 
)

Set the text description for a given image.

Parameters
[in]client_handleClient handle from registration API
[in]imageLabelImage label name
-Minimum length 1
-Maximum value openapiImageFileNameMaxLengthGet()
[in]imageDescrAssociated text
-Minimum length 1
-Maximum length OPENAPI_DEFAULT_IMAGE_DESCR_MAX
Return values
OPEN_E_NONEif text set successful.
OPEN_E_FAILif text set failed.
OPEN_E_PARAMif parameters is not defined correctly.
OPEN_E_NOT_FOUNDif image not found.
OPEN_E_UNAVAILThe image is currently in-use.

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageLabelIsValid ( openapiClientHandle_t client_handle,
open_buffdesc imageLabel,
OPEN_BOOL_t isValid 
)

Determines if the image label refers to a valid image name.

Parameters
[in]client_handleClient handle from registration API.
[in]imageLabelImage label name
-Minimum length 1
-Maximum value openapiImageFileNameMaxLengthGet()
[out]isValidReturns OPEN_TRUE if image label is valid, else OPEN_FALSE if not
Return values
OPEN_E_NONEvalidation was successful. isValid contains a legitimate value only in this case.
OPEN_E_FAILvalidation failed.
OPEN_E_PARAMparameters were not defined correctly.
Note
This API expects the identifying string (label) used to refer to each code image file residing in non-volatile memory on the switch, such as "active" and "backup". It is not the actual name of a specific image (e.g. "8.2.0.1").
This function doesn't test validity of the label itself, but the validity of what the label refers to. In some cases, what this function expects to be passed in is either "active" or "backup", while on some platforms, a valid label might be "image1" or "image2". openapiImageLabelsGet can be used to obtain these label names.
A deleted image (e.g., via openapiImageDelete) will be reported as invalid by this function, because what the corresponding label (e.g., "backup") refers to is not present or available.

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageLabelsGet ( openapiClientHandle_t client_handle,
open_buffdesc activeLabel,
open_buffdesc backupLabel 
)

Get the label names for both active and backup images.

Parameters
[in]client_handleClient handle from registration API
[out]activeLabelActive label name
[out]backupLabelBackup label name
Return values
OPEN_E_NONEif label get successful.
OPEN_E_FAILif label get failed.
OPEN_E_PARAMif parameters is not defined correctly.
Note
This API provides the identifying string (label) used to refer to each code image file residing in non-volatile memory on the switch, such as "active" and "backup". It is not the actual name of a specific image (e.g. "8.2.0.1").
Buffer size for image labels should be openapiImageFileNameMaxLengthGet().

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageNamesGet ( openapiClientHandle_t client_handle,
uint32_t  unit,
open_buffdesc activeImage,
open_buffdesc backupImage,
open_buffdesc activatedImage 
)

Get the image names for both active, backup, and activated.

Parameters
[in]client_handleClient handle from registration API.
[in]unitUnit number
-Minimum value 1
-Maximum value openapiUnitMgrUnitMaxGet()
[out]activeImageActive image name
[out]backupImageBackup image name
[out]activatedImageActivated image name
Return values
OPEN_E_NONEif name get successful.
OPEN_E_FAILif name get failed.
OPEN_E_PARAMif parameters is not defined correctly.
Note
This API provides the names of the code image files residing in non-volatile memory on the switch (e.g. "8.2.1.1").
Buffer size for image names should be openapiImageFileNameMaxLengthGet().
An image name of OPEN_IMAGE_NAME_NONE indicates the image is not present on the device.

OpEN API Version: 1.8

Examples:
image_example.c.
open_error_t openapiImageUpgrade ( openapiClientHandle_t client_handle,
open_buffdesc imagePath,
open_buffdesc imageLabel 
)

Get a locally copied image path, perform validation on it and on success, upgrade the switch with this image.

Parameters
[in]client_handleClient handle from registration API.
[in]imagePathComplete path for the image in Linux
[in]imageLabelActive or Backup image label
Return values
OPEN_E_NONEif image validation and upgrade are successful.
OPEN_E_FAILif image validation or upgrade fails.
OPEN_E_PARAMif parameters is not defined correctly.
OPEN_E_UNAVAILif platform does not support function.
Note
This API validates a locally downloaded image. If successful, the switch image identified by the imageLabel is updated.
This API expects the imageLabel parameter to contain the identifying string (label) used to refer to each code image file residing in non-volatile memory on the switch, such as "active" and "backup". It is not the actual name of a specific image (e.g. "8.2.0.1").
Buffer size for imagePath and imageLabel should be openapiImageFileNameMaxLengthGet().

OpEN API Version: 1.14

Examples:
image_example.c.