OCEOS/oceos protection

OCEOS Memory Protection For GR716

Memory Protection provides directives to deal with the Error Detection and Correction (EDAC) features of the GR716 and directives to deal with memory write protection units.
The GR716 internal memory is protected by error detection and correction (EDAC) and associated scrubbing functionality and OCEOS provides directives to control and monitor this.
The GR716 memory controller for external memory provides EDAC capability and OCEOS has directives to control and monitor this and also the MEMSCRUB external scrubber unit.
The GR716 provides a number of memory protection units that provide some memory write protection capability. The OCEOS directives allow these registers be set to provide various levels of memory write protection.

Memory Protection Introduction

The two memory protection units in the GR716 can be used to restrict write access to memory segments by selected system bus masters (MEMPROT0) and by selected DMA bus masters (MEMPROT1). Each unit allows four memory segments be defined for write protection. In addition MEMPROT0 can restrict access via the system bus AHB to APB bridges by selected system bus masters and the four DMA units to selected APB bus devices.

MEMPROT0 can protect four segments in the range 0x40000000 to 0x4FFFFFFF or the range 0x80000000 to 0x8041ffff, as well as specific APB units.

MEMPROT1 can protect four segments in the range 0x30000000 to 0x31000000 and restrict the access of any master on the DMA bus.

An attempt to write to a protected area causes an AMBA ERROR response which can cause an interrupt from MEMSCRUB or from one of the AHBSTAT units.
The memory protection directives relate to the EDAC and memory protection features of the GR716.

The internal instruction RAM and data RAM of the GR716 each has its own EDAC and scrubber support internal to the GR716. The internal scrubbers use one 32-bit word per burst and an appropriate number of cycles between bursts should be specified for each scrubber. The scrubbers can be individually configured to cause an interrupt when an uncorrectable error occurs and if this is done an appropriate handler for Interrupt Line 63, default Int 19, should be set up in advance.
The GR716 internal RAM can also be protected from external write accesses by the memory protection unit on the DMA bus (MEMPROT1). The external RAM memory controllers (FTMCTRL0/1) provide EDAC support, with scrubbing provided by the MEMSCRUB unit on the main system bus.

As the main external memory (FTMCTRL0) uses an 8-bit data bus the high 20% of this RAM is used for the EDAC check bits and cannot be used for data when EDAC is enabled.

(The GR716-MINI board has 2 MiB of main external RAM accessed via FTMCTRL0 and with EDAC enabled only addresses 0x40000000 to 0x40199997 can be used for data, the check bits are stored at addresses 0x4019999a to 0x401FFFFF, and addresses 0x40199998 and 0x40199999 cannot be used).
When using MEMSCRUB this restriction must be taken into account in setting the high address of the scrubbing range. (The GR716-MINI external RAM scrubber range is 0x40000000 to 0x40199997.)
On the GR716 the MEMSCRUB unit works in bursts of two 32-bit words, and an appropriate number of cycles between bursts should be specified.
MEMSCRUB can be configured to cause an interrupt due to correctable or uncorrectable error counts exceeding a pre-set threshold, and if this is done an appropriate handler for Interrupt Line 63, default Int 19, should be set up in advance (the same interrupt as for the internal scrubbers).

Two memory protection (MEMPROT) units, one for the main system bus, one for the DMA bus, each allow up to four memory segments be defined and can be configured to prevent writes by a specific bus master to a segment.

MEMPROT0 controls memory writes via the main memory controller FTMCTRL0 by selected bus masters for addresses 0x40000000 to 0x4FFFFFFF.

Note

If EDAC is in use with FTMCTRL0 the memory area to which access is allowed must include the EDAC check bits as well as the data.

MEMPROT0 can also restrict writes to APB bus addresses in the range 0x80000000 to 0x8041FFFF and to specific devices on the APB bus.
MEMPROT1 controls memory writes to the GR716 internal RAM from the DMA bus for addresses in the range 0x30000000 to 0x31FFFFFF.

Write access permission can be specified on an individual basis for each bus master on the DMA bus.

MEMPROT0/1 do not themselves cause a trap/interrupt when an attempt is made to write to protected memory, but as well as preventing the write return an AMBA ERROR response which can give rise to an interrupt from AHBSTAT1/0 respectively. If this used an appropriate error handler for Interrupt Line 63, default Int 19, should be set up in advance (the same interrupt as for the scrubbers).

Note

The appropriate clock gating must be set for it to be possible to use FTMCTRL, MEMSCRUB, or the MEMPROT units, and the appropriate GPIO pin selection also configured.

The MEMPROT units themselves must be configured to allow access to the registers of the other devices.
A handler for Interrupt Line 63, default Int 19, should be set up in advance if required. The directives here assume this has already been done.

Note

Where a register contains read-only bits the values set for those bits in the input data used with the directives below must be 0, if not the input will be treated as invalid.

API Functions

API Functions

Directive	Description	main	task	IRQ handler
oceos_protect_internal_EDAC_set()	Internal EDAC control and scrubbing	*	*	*
oceos_protect_internal_scrubber_set()	Set the internal memory scrubber control and interrupt	*	*	*
oceos_protect_internal_status_get()	Return the internal EDAC and scrubber status	*	*	*
oceos_protect_external_EDAC_set()	External RAM EDAC control and scrubbing	*	*	*
oceos_protect_external_status_get()	Return the main external RAM EDAC status register	*	*	*
oceos_protect_external_scrubber_set()	Set the parameters for the external scrubber unit MEMSCRUB	*	*	*
oceos_protect_external_scrubber_status_get()	Get the status of the external scrubber MEMSCRUB	*	*	*
oceos_protect_external_scrubbers_done_clear()	Clear the DONE bit in MEMSCRUB.STAT	*	*	*
oceos_protect_external_scrubber_position_get()	Get the current value of the MEMSCRUB position register	*	*	*
oceos_protect_unit_control()	Enable/disable protection by a MEMPROT unit	*	*	*
oceos_protect_segment_define()	Define the range of addresses	*	*	*
oceos_protect_memprot0_segment_control()	Control access to MEMPROT0 segments	*	*	*
oceos_protect_memprot1_segment_control()	Control access to MEMPROT1 segments	*	*	*
oceos_protect_APB_devices()	Control access to APB devices	*	*	*

oceos_protect_internal_EDAC_set()

Header File
protection.h

Description
Sets the configuration registers for the GR716 internal data RAM and internal instruction RAM.
These registers determine various characteristics, including whether EDAC is enabled.
As well as setting the registers this routine reads them back to check that they have been set as requested.

Prototype

enum DIRECTIVE_STATUS   oceos_protect_internal_EDAC_set(
    const unsigned int  data_config, // internal data memory configuration
    const unsigned int  inst_config  // internal instruction memory config
)

Parameters

Parameter	Description
data_config	Internal data memory configuration
inst_config	Internal instruction memory config

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INVALID_ID	Failed to set registers
INVALID_NUMBER	Problem with input parameter
SUCCESSFUL	All OK

Example Usage

enum DIRECTIVE_STATUS status;
status =  oceos_protect_internal_EDAC_set(0, 0);
if (SUCCESSFUL != status) {
  // Handle ERROR
}

oceos_protect_internal_scrubber_set()

Header File
protection.h

Description
Sets the configuration registers for the GR716 internal data RAM and internal instruction RAM scrubbers. These registers determine various scrubbing characteristics, including enabling the scrubbers. See GR716.h for further information. As well as setting the registers this routine reads them back to check that they have been set as requested.

Prototype

enum DIRECTIVE_STATUS   oceos_protect_internal_scrubber_set(
    const unsigned int  data_wash,         // data scrubber wash data
    const unsigned int  data_scrub_ctrl,   // data scrubber control
    const unsigned int  data_scrub_config, // data scrubber configuration
    const unsigned int  inst_wash,         // instruction scrubber wash data
    const unsigned int  inst_scrub_ctrl,   // instruction scrubber control
    const unsigned int  inst_scrub_config  // instruction scrubber config
)

Parameters

Parameter	Description
data_wash	Data scrubber wash data
data_scrub_ctrl	Data scrubber control
data_scrub_config	Data scrubber configuration
inst_wash	Instruction scrubber wash data
inst_scrub_ctrl	Instruction scrubber control
inst_scrub_config	Instruction scrubber config

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INVALID_ID	Failed to write to the register
INVALID_NUMBER	Problem with input parameter
SUCCESSFUL	All OK

Example Usage

enum DIRECTIVE_STATUS status;
status = oceos_protect_internal_scrubber_set(0x0, 0x0, 0x0, 0x0, 0x0, 0x0);
if (SUCCESSFUL != status) {
  // Handle ERROR
}

oceos_protect_internal_status_get()

Header File
protection.h

Description
Returns the current value of either the data or the instruction configuration registers.

Prototype

unsigned int           oceos_protect_internal_status_get(
    const unsigned int select_memory // 0 => data memory, 1 => instruction memory
)

Parameters

Parameter	Description
select_memory	0 for data memory, 1 for instruction memory

Returns
This function returns unsigned int.

unsigned int	Description
0	ERROR
> 0	Value of configuration register

Example Usage

unsigned int value;
value = oceos_protect_internal_status_get(1);
if (0 == value) {
  // Handle ERROR
}

oceos_protect_external_EDAC_set()

Header File
protection.h

Description
Sets the EDAC control register (MCFG3) in the external memory controller.
The value input is checked to ensure all read-only bits are 0.
The value is not read back for checking as some fields can change.
The external EDAC present bit (ME) is checked to make sure it is set.

Prototype

enum DIRECTIVE_STATUS   oceos_protect_external_EDAC_set(
    const unsigned int              setting
)

Parameters

Parameter	Description
setting	Configuration value, only low order 12 bits are used

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	EDAC not present
INVALID_NUMBER	High order 20 bits not 0
SUCCESSFUL	All OK

Example Usage

enum DIRECTIVE_STATUS status;
status = oceos_protect_external_EDAC_set(0xcafebabe);
if (SUCCESSFUL != status) {
  // Handle ERROR
}

oceos_protect_external_status_get()

Header File
protection.h

Description
Returns the contents of the EDAC control register (MCFG3) in the external memory controller (FTMCTRL).

Prototype

unsigned int            oceos_protect_external_status_get();

Parameters

Parameter	Description

Returns
This function returns unsigned int.

unsigned int	Description
0	Clock is off
> 0	Value of FTMCTRL.MCFG3

Example Usage

unsigned int reg_value;
reg_value = oceos_protect_external_status_get();

oceos_protect_external_scrubber_set()

Header File
protection.h

Description
Set the parameters for the external memory scrubber unit MEMSCRUB

N.B. On the GR716 the burst length used by MEMSCRUB is 2. The same wash data is written to MEMSCRUB twice to fill its buffer

N.B. Values input are checked to ensure all read-only bits are 0. The memory controller should have EDAC enabled (this is not checked)

Prototype

enum DIRECTIVE_STATUS   oceos_protect_external_scrubber_set(
    const unsigned int  config,            // configuration
    const unsigned int  error_thresh,      // error threshold
    const unsigned int  wash_data,         // used to initialise memory
    const unsigned int  range1_low,        // first range start address
    const unsigned int  range1_high,       // first range end address
    const unsigned int  range2_low,        // second range start address
    const unsigned int  range2_high        // second range end address
)

Parameters

Parameter	Description
config	MEMSCRUB.CONFIG - configuration
error_thresh	MEMSCRUB.ERROR - interrupt conditions
wash_data	MEMSCRUB.INIT - wash data (used twice)
range1_low	MEMSCRUB.RANGEL - range 1 start address
range1_high	MEMSCRUB.RANGEH - range 2 end address
range2_low	MEMSCRUB.RANGEL2 - range 2 start address
range2_high	MEMSCRUB.RANGEH2 - range 2 end address

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INVALID_NUMBER	If any read-only bits are set
SUCCESSFUL	All OK

Example Usage

enum DIRECTIVE_STATUS status;
status = oceos_protect_external_scrubber_set(0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0);
if (SUCCESSFUL != status) {
  // Handle ERROR
}

oceos_protect_external_scrubber_status_get()

Header File
protection.h

Description
Returns the external memory scrubber status register MEMSCRUB.STAT as required to re-enable interrupts on task completion.

Prototype

unsigned int            oceos_protect_external_scrubber_status_get();

Parameters

Parameter	Description

Returns
This function returns unsigned int.

unsigned int	Description
>= 0	MEMSCRUB.STAT value

Example Usage

unsigned int reg_value;
reg_value = oceos_protect_external_scrubber_status_get();

oceos_protect_external_scrubbers_done_clear()

Header File
protection.h

Description
Clears the DONE bit in MEMSCRUB.STAT as required to re-enable interrupts on task completion.

Prototype

enum DIRECTIVE_STATUS   oceos_protect_external_scrubbers_done_clear();

Parameters

Parameter	Description
SUCCESSFUL	All OK

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
SUCCESSFUL	If All OK

Example Usage

enum DIRECTIVE_STATUS status;
status = oceos_protect_external_scrubbers_done_clear();

oceos_protect_external_scrubber_position_get()

Header File
protection.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_protect_unit_control()

Header File
protection.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_protect_segment_define()

Header File
protection.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_protect_memprot0_segment_control()

Header File
protection.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_protect_memprot1_segment_control()

Header File
protection.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_protect_APB_devices()

Header File
protection.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage