cos710.h File Reference

Detailed Description

This module covers the Application Mode (AM) functionality of the specification CiA 710 (Generic CANopen bootloader). Support of the Generic CANopen bootloader is enabled by setting the symbol COS_BOOTLOADER_SUPPORT to 1.

The following table shows all objects supported for AM.

Index	Description	Function / Variable	Configuration Symbol
1F5Ah	Application security access	Cos710_Idx1F5A()	COS_BOOTLOADER_SUPPORT
1F5Bh	Mode switch timeout counter	Cos710_Idx1F5B()	COS_BOOTLOADER_SUPPORT
1F5Ch	Bootloader mode switch	Cos710_Idx1F5C()	COS_BOOTLOADER_SUPPORT

Please note that also CANopen Bootloader is required which supports the Bootloader Mode (BM), e.g. the CANopen Bootloader protocol stack.

Include dependency graph for cos710.h:

Data Structures
struct	CosBootloaderSeed_s
struct	CosBootloaderKey_s

Typedefs
typedef struct CosBootloaderSeed_s	CosBootloaderSeed_ts
typedef struct CosBootloaderKey_s	CosBootloaderKey_ts

Enumerations
enum	CosBootloaderEvent_e {   eCOS_BOOTLOADER_EVENT_ACCESS_GRANTED = 1 ,   eCOS_BOOTLOADER_EVENT_ACCESS_EXPIRED = 2 ,   eCOS_BOOTLOADER_EVENT_APPLICATION_BUSY = 3 }

Functions
void	CosBootloaderConfirmAppStop (void)
void	CosBootloaderEvent (uint8_t ubBootloaderEventV)
void	CosBootloaderGetSeed (CosBootloaderSeed_ts *ptsServerSeedV)
void	CosBootloaderRequestAppStop (void)
void	CosBootloaderStart (void)
bool_t	CosBootloaderValidateKey (CosBootloaderKey_ts *ptsClientKeyV, CosBootloaderSeed_ts *ptsServerSeedV)

Typedef Documentation

CosBootloaderKey_ts

typedef struct CosBootloaderKey_s CosBootloaderKey_ts

The structure CosBootloaderKey_s describes the key structure prepared by the client, i.e. the CANopen bootloader tool. It is used by CosBootloaderValidateKey().

CosBootloaderSeed_ts

typedef struct CosBootloaderSeed_s CosBootloaderSeed_ts

The structure CosBootloaderSeed_s describes the seed structure prepared by the server, i.e. the CANopen Slave application. It is used by CosBootloaderGetSeed() and CosBootloaderValidateKey().

Enumeration Type Documentation

CosBootloaderEvent_e

enum CosBootloaderEvent_e

The possible values for Bootloader events are listed in this enumeration. The function CosBootloaderEvent() is called to inform the application about possible events.

Enumerator
eCOS_BOOTLOADER_EVENT_ACCESS_GRANTED	Security access granted
eCOS_BOOTLOADER_EVENT_ACCESS_EXPIRED	Security access expired
eCOS_BOOTLOADER_EVENT_APPLICATION_BUSY	Application is busy

Function Documentation

CosBootloaderConfirmAppStop()

void CosBootloaderConfirmAppStop

(

void

)

See also

CosBootloaderRequestAppStop()

This function is called by the application to confirm a request to stop the application. An example implementation is shown by CosBootloaderRequestAppStop().

CosBootloaderEvent()

void CosBootloaderEvent

(

uint8_t

ubBootloaderEventV

)

Parameters

[in]

ubBootloaderEventV

Bootloader event

Note

The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called by the protocol stack in case of the following events:

• Security access granted
• Security access denied
• Application busy

Possible values for parameter ubBootloaderEventV are defined by the enumeration CosBootloaderEvent_e.

void CosBootloaderEvent(uint8_t ubBootloaderEventV)
{
   switch (ubBootloaderEventV)
   {
      case eCOS_BOOTLOADER_EVENT_ACCESS_GRANTED:
 
         break;
 
      case eCOS_BOOTLOADER_EVENT_ACCESS_EXPIRED:
 
         break;
 
      case eCOS_BOOTLOADER_EVENT_APPLICATION_BUSY:
 
         break;
 
   }
}

CosBootloaderGetSeed()

void CosBootloaderGetSeed

(

CosBootloaderSeed_ts *

ptsServerSeedV

)

Parameters

[out]

ptsServerSeedV

Pointer to seed structure

See also

CosBootloaderValidateKey()

Note

The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function copies a random seed to the structure of parameter ptsSeedV for calculation of a key which is required for Bootloader security access. This function is called by the protocol stack upon read access to object 1F5A_h (Application security access).

#include <stdlib.h>  // for rand() function call
 
typedef struct MySeed_s {
   int32_t  slRandom;
   uint32_t ulSerial;
} MySeed_ts;
 
void CosBootloaderGetSeed(CosBootloaderSeed_ts * ptsSeedV)
{
   //----------------------------------------------------------------------------------------------
   // copy a random seed to the structure ptsSeedV
   //
   MySeed_ts   *ptsMySeedT;
 
   ptsMySeedT = (MySeed_ts *) ptsSeedV;
 
   ptsMySeedT->slRandom = rand();
   ptsMySeedT->ulSerial = CosMgrGetSerialNumber();
}

CosBootloaderRequestAppStop()

void CosBootloaderRequestAppStop

(

void

)

Note

The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called by the protocol stack upon writing the value B3_h to object 1F5C_h (Bootloader mode switch). The function is application specific and shall stop all application critical functions before entering the bootloader mode (BM).

void CosBootloaderRequestAppStop(void)
{
   //---------------------------------------------------------------------------------------------------
   // shutdown the application here, e.g.
   // - switch active outputs off
   // - stop drive
   // - store data in memory
   //
 
   //---------------------------------------------------------------------------------------------------
   // confirm the shutdown request 
   //
   CosBootloaderConfirmAppStop();
 
}

CosBootloaderStart()

void CosBootloaderStart

(

void

)

Note

The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called by the protocol stack in case the Mode switch timeout counter (data object 1F5B_h) has expired. The function shall shutdown the CANopen Slave protocol stack and jump to the bootloader.

An example implementation is shown here:

void CosBootloaderStart(void)
{
   //---------------------------------------------------------------------------------------------------
   // shutdown the CANopen Slave protocol stack
   //
   CosMgrRelease();
 
   //---------------------------------------------------------------------------------------------------
   // Jump to bootloader by using the McIapJumpToBoot() function call or any custom specific function
   //
   McIapJumpToBoot();
}

CosBootloaderValidateKey()

bool_t CosBootloaderValidateKey	(	CosBootloaderKey_ts *	ptsClientKeyV,
		CosBootloaderSeed_ts *	ptsServerSeedV )

Parameters

[in]	ptsClientKeyV	Pointer to client key structure
[in]	ptsServerSeedV	Pointer to server seed structure

Returns

true if key is valid, otherwise false

See also

CosBootloaderGetSeed()

Note

The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function validates the client key given by ptsClientKeyV against the server seed defined by parameter ptsServerSeedV. The function shall return true in case the validation is successful, otherwise it shall return false. In case the validation is successful, access to the protected data objects 1F5B_h (Mode switch timeout counter) and 1F5C_h (Bootloader mode switch) is granted.

This function is called by the protocol stack upon write access to object 1F5A_h (Application security access).

bool_t CosBootloaderValidateKey(CosBootloaderKey_ts * ptsClientKeyV, CosBootloaderSeed_ts * ptsServerSeedV)
{
   bool_t   btResultT = false;
 
   if ( (ptsClientKeyV != (CosBootloaderKey_ts *) 0L) && (ptsServerSeedV != (CosBootloaderSeed_ts *) 0L) )
   {
      //-------------------------------------------------------------------------------------------
      // perform check here and set 'btResultT' to true in case the check pass
      //
   }
 
   return (btResultT);
}