# OS_SetProtectionRegion*

## Syntax

  `#include <nitro/os.h>`
  (`Specifies address and size`)
  `OS_SetProtectionRegion( regionNo, address, sizeStr );`
  `void OS_SetProtectionRegionEx( int regionNo, u32 address, u32 sizeDef );`
  (`Specifies parameters`)
  `void OS_SetProtectionRegionParam( int regionNo, u32 param );`
  `void OS_SetProtectionRegion0( u32 param )`;
  `void OS_SetProtectionRegion1( u32 param );`
  `void OS_SetProtectionRegion2( u32 param );`
  `void OS_SetProtectionRegion3( u32 param );`
  `void OS_SetProtectionRegion4( u32 param );`
  `void OS_SetProtectionRegion5( u32 param );`
  `void OS_SetProtectionRegion6( u32 param );`
  `void OS_SetProtectionRegion7( u32 param );`

## Arguments

regionNo | Protection Region number. Specify a value between 0 and 7.
address | Base address (starting address). Specify as type u32.
sizeStr | String indicating area size. Only certain strings such as 4KB, 8KB, etc. can be specified.
sizeDef | Value indicating the area size. It is of the form "`OS_PR_SIZE_xxx`," where "`xxx`" is 4KB, 8KB, ... 4GB.
param | Logical sum of specified base address and area size values. This logical sum value is set in CP15.

## Return Values

None.

## Description

Sets the Protection Region's base address (starting address) and size. Also, with the `OS_SetProtectionRegion` function, the protection unit is enabled at the same time.

The Protection Region's settings are closely related to system behavior. When making these settings, be sure you understand the design of the Protection Region and how each area is used.

### `• OS_SetProtectionRegion`

The `OS_SetProtectionRegion` function is a macro. The `regionNo` argument is the region number of the Protection Region being set. The string itself is used as the argument by the macro, so you cannot use the value to specify a variable. You should specify a number between 0 and 7.

The `address` argument is the base address (starting address) of the Protection Region being set. Specify as type u32. The alignment restrictions of the specified address will vary, depending on the size of the Protection Region. The Protection Region's starting address must be a multiple of the area size. Thus, if the Protection Region is 4KB, then the lower 12 bits of the address expressed as a u32 value must be 0.

The `sizeStr` argument is a string that indicates the area size of the Protection Region.

> 4KB 8KB 16KB 32KB 64KB 128KB 256KB 512KB
> 1MB 2MB 4MB 8MB 16MB 32MB 64MB 128MB 256MB 512MB
> 1GB 2GB 4GB

> Example:
> `OS_SetProtectionRegion( 2, 0x02080000, 32KB );`

Regardless of the status before calling the `OS_SetProtectionRegion` function, the region becomes enabled.

### `• OS_SetProtectionRegionEx`

The `OS_SetProtectionRegionEx` function was created to make it possible to pass variables for region numbers for which this was not possible because the `OS_SetProtectionRegion` function was a macro.

The `regionNo` argument is the region number of the Protection Region being set. It takes the values 0 through 7.

The `address` argument is the base address (starting address) of the Protection Region being set. Everything else is the same as with the `OS_SetProtectionRegion` function.

The `sizeDef` argument is a value of the form `OS_PR_SIZE_xxx`. Any of the following can be specified in `xxx`.

> 4KB 8KB 16KB 32KB 64KB 128KB 256KB 512KB
> 1MB 2MB 4MB 8MB 16MB 32MB 64MB 128MB 256MB 512MB
> 1GB 2GB 4GB

> Example:
> `OS_SetProtectionRegionEx( 2, 0x02080000, OS_PR_SIZE_32KB );`

### `• OS_SetProtectionRegionParam`

The `OS_SetProtectionRegionParam` function is used to set the base address and region size, using the Protection Region's internal parameter format. The `regionNo` argument is the same as in the `OS_SetProtectionRegionEx` function. The `param` parameter is the logical sum of the base address and `HW_C6_PR_SIZE_xxx`, which is the value set to express the area size. `xxx` takes the string named for `sizeStr` (that is, 4KB or 8KB or ... 4GB). In addition, add `HW_C6_PR_ENABLE` in the logical sum to enable the region.

> Example:
> `OS_SetProtectionRegionParam( 2, 0x02080000 | HW_C6_PR_32KB | HW_C6_PR_ENABLE );`

### `• OS_SetProtectionRegion0 - OS_SetProtectionRegion7`

The functions `OS_SetProtectionRegion0` through `OS_SetProtectionRegion7` are used for specifying the region numbers of `OS_SetProtectionRegionParam` using the function names. The `param` argument is the same as in the `OS_SetProtectionRegionParam` function.

## Internal Operation

Modifies register 6 of the system control co-processor CP15.

## See Also

`OS_EnableProtectionUnit`
`OS_DisableProtectionUnit`
`OS_GetProtectionRegion*`

## Revision History

2007/10/25 Added the `OS_SetProtectionRegionEx` function. Also added other descriptions.
2004/07/08 Described `HW_C6_PR_ENABLE`.
2004/05/28 Initial version.

CONFIDENTIAL