program.h File Reference

Program storage API. More...

#include <stdint.h>

Include dependency graph for program.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	program
	Data structure for program information. More...

Macros
#define	PROGRAM_BANK_COUNT   12
	The maximum number of program banks. More...
#define	PROGRAM_COUNT   120
	The maximum number of programs that can be stored. More...
#define	PROGRAMS_PER_BANK   (PROGRAM_COUNT / PROGRAM_BANK_COUNT)
	The number of program per bank. More...

Functions
void	copy_current_bank_to (uint8_t target_bank)
	Copies all programs in the current bank to another bank. More...
void	copy_current_program_to (uint8_t target_program)
	Copies the current program to the specified position in memory. More...
char *	export_bank (const uint8_t number)
	Exports a program bank. More...
void	enter_program (uint8_t number)
	Loads and executes the specified program. More...
bool	import_bank (const uint8_t number, const char *data)
	Imports and stores a program bank given as a hex-string. More...
void	init_program_module (uint32_t program_initializer, void(*execute_program_callback)(uint32_t program_data))
	Initializes the program storage module. More...
uint32_t	read_program_data (uint8_t number)
	Reads a program data word from the specified position in memory. More...
void	update_current_program (uint32_t program_data)
	Updates and stores the current program. More...
void	wipe_current_bank (void)
	Reinitializes all programs in the current bank. More...
void	wipe_current_program (void)
	Reinitializes the currently loaded program. More...
void	write_program (uint8_t number, uint32_t data)
	Stores a given program data word in the specified position in memory. More...

Detailed Description

Program storage API.

This module takes care of loading, storing, copying and wiping program data. The programs are stored in EEPROM as 32-bit dwords - providing a generic container for flags, numbers - whatever is suitable for your program. It is advisable to define a union for easier access of these components in your application code - for example something like

union program_data = {
    uint32_t word;
    struct {
        bool flag0 : 1;
        bool flag1 : 1;
        bool flag2 : 1;
    } bit;
}

The programs are grouped into twelve banks of ten programs each - leaving 1568 bytes of EEPROM for other application specific data. Applications must implement and register a callback for program execution, which does whatever is necessary when a new program is loaded.

See also

init_program_module

Macro Definition Documentation

PROGRAM_BANK_COUNT

#define PROGRAM_BANK_COUNT   12

The maximum number of program banks.

PROGRAM_COUNT

#define PROGRAM_COUNT   120

The maximum number of programs that can be stored.

PROGRAMS_PER_BANK

#define PROGRAMS_PER_BANK   (PROGRAM_COUNT / PROGRAM_BANK_COUNT)

The number of program per bank.

Function Documentation

copy_current_bank_to()

void copy_current_bank_to

(

uint8_t

target_bank

)

Copies all programs in the current bank to another bank.

Irreversibly overwrites all programs in the target bank.

Parameters

target_bank

Target bank number [0..11].

copy_current_program_to()

void copy_current_program_to

(

uint8_t

target_program

)

Copies the current program to the specified position in memory.

Irreversibly overwrites the target program.

Parameters

target_program

Target program number [0..119].

enter_program()

void enter_program

(

uint8_t

number

)

Loads and executes the specified program.

Reads the new program data from EEPROM, updates the internal state and calls the registered callback function, which executes the program. If the specified program number is the same as the stored current program number, this function does nothing.

Parameters

number

Program number [0..119].

See also

init_program_module

export_bank()

char* export_bank

(

const uint8_t

number

)

Exports a program bank.

Reads the data from EEPROM and converts it to a string of hexadecimal digits.

Parameters

number

the number of the program bank to export

Returns

the programs stored in EEPROM as a hex-string

import_bank()

bool import_bank	(	const uint8_t	number,
		const char *	data
	)

Imports and stores a program bank given as a hex-string.

Overwrites stored program data!

Parameters

number	the number of the program bank to import [0..11]
data	the program bank to store as a string of hexadecimal digits

Returns

true if sanity checks passed

init_program_module()

void init_program_module	(	uint32_t	program_initializer,
		void(*)(uint32_t program_data)	execute_program_callback
	)

Initializes the program storage module.

Stores the specified program data initialization word, used in the wipe functions and registers the provided callback function, which is executed whenever the current program data word is updated either by wiping the program or loading a new one.

Parameters

program_initializer	On wiping, programs are initialized with this value.
execute_program_callback	Callback for program execution. This procedure is called with the program configuration data that was read from memory as the parameter program_data.

See also

wipe_current_program

enter_program

read_program_data()

uint32_t read_program_data

(

uint8_t

number

)

Reads a program data word from the specified position in memory.

Parameters

number

Program number [0..119].

update_current_program()

void update_current_program

(

uint32_t

program_data

)

Updates and stores the current program.

Parameters

program_data

the new configuration

wipe_current_bank()

void wipe_current_bank

(

void

)

Reinitializes all programs in the current bank.

See also

wipe_current_program

wipe_current_program()

void wipe_current_program

(

void

)

Reinitializes the currently loaded program.

Updates the internal program data word with the initializer, stores it and executes the initialized program.

write_program()

void write_program	(	uint8_t	number,
		uint32_t	data
	)

Stores a given program data word in the specified position in memory.

Parameters

number	Program number [0..119].
data	Program data as 32-bit dword.