nz_appConfig.h File Reference

This file defines the Application Configuration interface. More...

Go to the source code of this file.

Data Structures
struct	CFG_BLOCK_HDR
struct	TABLE_BLOCK_HDR
struct	CFG_BLOCK_INFO
struct	FIRMWARE_FLAGS
struct	CFG_INFO
struct	CFG_COPY

Macros
#define	CFG_BLOCK_INFO_ID   0x0100
#define	CFG_BLOCK_NET_ID   0x0101
#define	CFG_BLOCK_WIFI_ID   0x0102
#define	CFG_BLOCK_SNMP_ID   0x0103
#define	CFG_BLOCK_GENERAL_ID   0x0104
#define	CFG_BLOCK_NET2_ID   0x0105
#define	CFG_BLOCK_SER_0TO7_ID   0x0108
#define	CFG_BLOCK_SER_8TO15_ID   0x0109
#define	CFG_BLOCK_SER_16TO23_ID   0x010A
#define	CFG_BLOCK_SER_24TO31_ID   0x010B
#define	CFG_BLOCK_STRING_31X8_ID   0x0110
	31 strings of 8 bytes each
#define	CFG_BLOCK_UC66_PORT_ID   0x0114
	UC Port ID for SBC66 boards.
#define	CFG_BLOCK_SBC66_PORT_ID   0x0115
	IO Ports for SBC66 Boards.
#define	CFG_BLOCK_RESERVE_ID   0xFF00
	ID 0xff00 to 0xffff is reserved.
#define	TABLE_BLOCK_UC66_PORT_ID   0x8200
	UC port ID for SBC66 boards.
#define	TABLE_BLOCK_SBC66_PORT_ID   0x8220
	IO Ports for SBC66 Boards.
#define	CFG_BLOCK_SIZE(cfgBlk)   (sizeof (((CFG_STRUCT*) 0)->cfgBlk) - sizeof (((CFG_STRUCT*) 0)->cfgBlk.reserve))
#define	CURRENT_FIRMWARE_UNKNOWN   0
#define	CURRENT_FIRMWARE_A   1
#define	CURRENT_FIRMWARE_B   2
#define	XEEMEM_CFG_STRUCT_SIZE   0x0C00
#define	XEEMEM_CFG_INFO_START_ADR   0x0000
#define	XEEMEM_CFG_INFO_END_ADR   0x001F
#define	XEEMEM_CFG_COPY_START_ADR   0x0020
#define	XEEMEM_CFG_COPY_END_ADR   0x03FF
#define	XEEMEM_CFG_COPY_STOP_ADR   0x0400 /* Address of first byte outside of CFG_COPY area */
#define	XEEMEM_CFG_COPY_BLOCKS   ((XEEMEM_CFG_COPY_END_ADR-XEEMEM_CFG_COPY_START_ADR+1)/32)
#define	XEEMEM_CFG_STRUCT_START_ADR   0x0400
#define	XEEMEM_CFG_STRUCT_END_ADR   (XEEMEM_CFG_STRUCT_START_ADR + XEEMEM_CFG_STRUCT_SIZE - 1)
#define	XEEMEM_USER_START_ADR   (XEEMEM_CFG_STRUCT_START_ADR + XEEMEM_CFG_STRUCT_SIZE)
#define	XEEMEM_USER_END_ADR   (XEEPROM_SIZE - 1)
#define	cfgIncCfgCopyAdr(adr)   ((adr>=(XEEMEM_CFG_COPY_STOP_ADR-32)) ? XEEMEM_CFG_COPY_START_ADR : (adr+32))
#define	CFG_INFO_MAGIC_NUMBER   0x536A
#define	CFG_VERSION_MAJOR   1
#define	CFG_VERSION_MINOR   0
#define	CFG_COPY_DATA_SIZE   26
#define	cfgGetDfltStruct(member, struc)   cfgGetDfltArray(offsetof(CFG_STRUCT, member), ((BYTE*)&struc), sizeof(struc))
#define	cfgGetStruct(member, struc)   cfgGetArray(offsetof(CFG_STRUCT, member), ((BYTE*)&struc), sizeof(struc))
#define	cfgGetByte(offset)   (((BYTE*)&cfgStruct)[offset]);

Functions
void	cfgInit (BYTE *pCfgStructInfo)
BYTE	cfgIsXeepromValid (void)
void	cfgInvalidateXeeprom (void)
BYTE	cfgGetDfltArray (WORD offset, BYTE *buf, BYTE length)
BYTE	cfgBlkGetArray (WORD cfgBlkId, WORD offset, BYTE *buf, BYTE length)
BYTE	cfgGetArray (WORD offset, BYTE *buf, BYTE length)
void	cfgSaveByte (WORD offset, BYTE val)
void	cfgSaveArray (WORD offsetCfg, BYTE *buf, WORD length)
void	cfgSave (void)

Variables
FIRMWARE_FLAGS	firmwareFlags

Detailed Description

This file defines the Application Configuration interface.

Author

Modtronix Engineering

Compiler:

MPLAB XC16 Compiler

Description

This file defines the Application Configuration interface. The implementation has to be done in a separate c file by creating instances of the defined functions. The Netcruzer library contains one implementation:

• nz_appConfigXEE.c, this is a default implementation for storing the application configuration in an external SPI EEPROM.

See Usage for details how to use it.

Configuration

The following defines are used to configure this module, and should be placed in projdefs.h. Note that all items marked [-DEFAULT-] are defaults, and do not have to be placed in projdefs.h if they contain desired configuration! For details, see Project Configuration.

// *********************************************************************
// ------------ AppConfig Configuration (from nz_appConfig.h) -------------
// *********************************************************************
//Normally the CFG_STRUCT is located in the external Flash. It is placed there by the bootloader.
//If a bootloader is not used, it has to be define in code, and copied to the external Flash.
#define CFG_STRUCT_IN_CODE

Usage

To use this module, the following must be done:

• Copy the Configuration section above (from nz_appConfig.h) to the projdefs.h file.
• In this "Configuration" section, change any default values if required (if default values should be used, define is not required in projdefs.h).
• Add a default implementation c file to the MPLAB project, like nz_appConfigXEE.c for example.
• Include nz_appConfig.h in the c file it is used in.
• All DONE! The functions defined in this file can now be used in the project.

Software License Agreement

The software supplied herewith is owned by Modtronix Engineering, and is protected under applicable copyright laws. The software supplied herewith is intended and supplied to you, the Company customer, for use solely and exclusively on products manufactured by Modtronix Engineering. The code may be modified and can be used free of charge for commercial and non commercial applications. All rights are reserved. Any use in violation of the foregoing restrictions may subject the user to criminal sanctions under applicable laws, as well as to civil liability for the breach of the terms and conditions of this license.

THIS SOFTWARE IS PROVIDED IN AN 'AS IS' CONDITION. NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.

File History

2013-10-28, David H. (DH):

• Initial version

Macro Definition Documentation

#define CFG_BLOCK_SIZE

(

cfgBlk)

(sizeof (((CFG_STRUCT*) 0)->cfgBlk) - sizeof (((CFG_STRUCT*) 0)->cfgBlk.reserve))

Get's size of CFG_BLOCK element in CFG_STRUCT, minus the reserve bytes.

#define cfgGetByte

(

offset)

(((BYTE*)&cfgStruct)[offset]);

Get a single byte in cfgStruct structure.

Parameters

offset

Offset in cfgStruct of requested byte

Returns

Returns requested byte

#define cfgGetDfltStruct	(		member,
			struc
	)		cfgGetDfltArray(offsetof(CFG_STRUCT, member), ((BYTE*)&struc), sizeof(struc))

Copy given member structure (structure in CFG_STRUCT) to destination structure. The default values for cfgStruct is returned, NOT THE CURRENT application configuration values! The current application configuration values are stored in the external EEPROM, and are retrieved via the cfgGetStruct() function! For example: cfgGetDfltStruct(ser.avail, serInfo.avail);

Parameters

member	Requested member in CFG_STRUCT
struc	Destination structure to copy requested structure to

#define cfgGetStruct	(		member,
			struc
	)		cfgGetArray(offsetof(CFG_STRUCT, member), ((BYTE*)&struc), sizeof(struc))

Copy given member structure in EEPROM cfgStruct to destination structure. For example: cfgGetStruct(ser.avail, serInfo.avail);

Parameters

member	Requested member in APP_CONFIG
struc	Destination structure to copy requested structure to

#define cfgIncCfgCopyAdr

(

adr)

((adr>=(XEEMEM_CFG_COPY_STOP_ADR-32)) ? XEEMEM_CFG_COPY_START_ADR : (adr+32))

Increment CFG_COPY address. Can use a mask if XEEMEM_CFG_COPY_END_ADR is all '1' on right

Function Documentation

BYTE cfgBlkGetArray	(	WORD	cfgBlkId,
		WORD	offset,
		BYTE *	buf,
		BYTE	length
	)

Get array from the given Config Block (CFG_BLOCK_XXX). Is copied to given destination buffer (buf).

Parameters

cfgBlkId	The source Config Block (CFG_BLOCK_XXX) id, is a CFG_BLOCK_xxx_ID define, like CFG_BLOCK_NET_ID for example.
offset	Offset of the array to return, in the given "Config Block"
buf	Destination buffer
length	Number of bytes to copy

Returns

Returns number of bytes copied

BYTE cfgGetArray	(	WORD	offset,
		BYTE *	buf,
		BYTE	length
	)

Get array from Configuration Structure in the External EEPROM. Is copied to given destination buffer (buf).

Parameters

offset	Offset in cfgStruct to use as source
buf	Destination buffer
length	Number of bytes to copy

Returns

Returns number of bytes copied

BYTE cfgGetDfltArray	(	WORD	offset,
		BYTE *	buf,
		BYTE	length
	)

Copy array of bytes from given offset in DEFAULT cfgStruct to given destination buffer (buf). The default values for cfgStruct is returned, NOT THE CURRENT application configuration values! The current application configuration values are stored in the external EEPROM, and are retrieved via the cfgGetArray() function!

Parameters

offset	Offset in cfgStruct to use as source
buf	Destination buffer
length	Number of bytes to copy

Returns

Returns number of bytes copied

void cfgInit

(

BYTE *

pCfgStructInfo)

Pre-Condition:

fsysInit() is already called.

void cfgInvalidateXeeprom

(

void

)

Invalidate external EEPROM. Done by setting magic number to 0. On reboot, contents of External EEPROM will be reloaded.

BYTE cfgIsXeepromValid

(

void

)

Validate if the contents of the external EEPROM is valid. If not, it is initialized with the default configuration.

Returns

0 if not valid, else non 0 value

void cfgSave

(

void

)

Save Application Configuartion data to EEPROM

void cfgSaveArray	(	WORD	offsetCfg,
		BYTE *	buf,
		WORD	length
	)

Saves the given array in CFG_STRUCT configuration (external EEPROM) with the given data. The array is securely saved, ensuring EEPROM is not corrupted if power faulure occurs during before done. This is achieved by first saving a copy to the CFG_COPY area of the EEPROM, and then saving the actual value in CFG_STRUCT.

Parameters

offsetCfg	Contains the offset in the APP_CONFIG structure of the array to save
buf	Source data to save
length	Number of bytes to save

void cfgSaveByte	(	WORD	offset,
		BYTE	val
	)

Saves a single by to the Configuration Structure of the External EEPROM.

Parameters

offset	Contains the offset in the CFG_STRUCT structure of the byte to save
val	Byte to save