Firewall FAQ

Note

System Firmware supports multiple SOC’s. When providing links to SOC-specific documentation, this document provides the example of AM65x SR1 SOC. Documentation for other SOC’s can be found by traversing similar path from the root of Chapter 5: SoC Family Specific Documentation.

Can I directly write to firewall configuration registers ?

No. Firewall configuration registers are only writable by System Firmware. They cannot be programmed by direct register writes.

How do I configure a firewall ?

Firewalls are configured using the TISCI_MSG_SET_FWL_REGION TISCI message.

Disabling a firewall is also done using the same API using the control word.

All the registers of a firewall can be configured using the above TISCI message.

How do I specify which firewall to program ?

Firewalls are identified to System Firmware by their ID. The ID of a firewall can be obtained from the Technical Reference Manual(TRM) of the SOC. Information on firewalls is provided in the chapter “System Interconnect” and the subsection “Interconnect Firewalls”.

TISCI_MSG_SET_FWL_REGION TISCI message takes firewall id as one of the arguments.

How do I know what permissions to program in the firewall ?

Privilege ID’s of the various initiators are described in the public SOC documentation Chapter 5: SoC Family Specific Documentation under “<SOC> Firewall Descriptions”. As an example for AM65X devices, this is listed under AM65x List of priv ids.

The values to program in the permission bits and the control registers can be found from the below section in the TRM.

“System Interconnect” -> “System Interconnect Registers” -> “Firewall Region Registers”

Are all firewalls user programmable ?

No. System Firmware maintains ownership of the following categories of firewalls.

1. Firewalls protecting DMSC-owned resources - e.g. secure proxies, firewall configuration port etc. These firewalls are marked as owned by dmsc in the firewall SOC data.
2. Firewalls protecting DMSC-managed resources i.e. NAVSS resources managed by RM. These firewalls are marked as owned by rm in the firewall SOC data.

The remaining firewalls are user programmable through the TISCI interface only.

The list of firewalls owned/initialized by System Firmware are listed for AM65X SR1 devices at

• AM65x Standard region-based slave firewall configuration
• AM65x Channelized slave firewall configuration

What is firewall ownership ?

Firewall ownership is a software concept implemented by System Firmware. A firewall region can be marked as owned by a specific host. This prevents the firewall region from being programmed/reprogrammed by another host and helps in firewall overlap checks.

By default, only firewalls required from System Firmware use are marked as owned by dmsc or rm. Rest of the firewalls have ownership set to none. Firewalls with owner set as none can be programmed by any host.

A host can claim ownership of a firewall region with owner set to none by using the TISCI_MSG_CHANGE_FWL_OWNER message. A host can use the same message to transfer a firewall region it owns to another host.

Who can update the firewall owner ?

The only one that can update the firewall owner, is the current owner. Requests from any other hosts will be rejected.

Who can update the start address and end address ?

The only one that can update the addresses, is the current owner. Requests from any other hosts will be rejected.

Is there any relationship between ownership and firewall permissions ?

The concept of firewall ownership is unrelated to firewall permissions. Firewall ownership is a software concept. Firewall permissions directly map to the underlying hardware registers. The owner of a firewall can configure firewall permissions as desired. System Firmware does not perform any checks on the firewall permissions supplied in the TISCI message arguments.

Is host ID the same as priv ID ?

No. Host ID is a software concept introduced by System Firmware to be differentiate between different entities on the device. Some of the entities can be on the same core. e.g. privileged software and unprivileged software running on the same core. See AM65X Host IDs.

Priv ID is a hardware concept. Every transaction on the interconnect has various attributes including but not limited to Priv ID, user/privileged, secure/non secure. Each host maps to a Priv ID. See AM65x List of priv ids for the mapping.

Is programming overlapping firewalls supported ?

Yes. Programming overlapping firewalls is supported. System Firmware performs additional checks when overlapping firewall regions are being programmed.

1. A background region cannot overlap with another background region.
2. A foreground region cannot overlap with another foreground region.

The above two checks are to prevent undefined behaviour as per hardware specification.

3. Same host must own both the foreground and background region in case of an overlap. If any of the overlapping regions is owned by none (unowned/wildcard region) following rules apply: - Unowned foreground region cannot overlap with owned background region. - Unowned background region can overlap with foreground region owned by any host. These checks prevent one host from using a foreground region to override firewall configuration performed by another host

Before programming overlapping firewall regions, please claim ownership of both the regions using the TISCI_MSG_CHANGE_FWL_OWNER message.

What are background and foreground regions ?

The firewall IP supports the concept for foreground and background regions. The firewall permissions specified in a background region can be overridden by using a foreground region.

A region can be specified as foreground or background using a bit in the control register. Please refer to the following section in TRM for more information.

“System Interconnect” -> “System Interconnect Registers” -> “Firewall Region Registers”

Following restrictions apply from hardware perspective.

1. A background region cannot overlap with another background region.
2. A foreground region cannot overlap with another foreground region.
3. A foreground region cannot span two background regions.

How do I debug firewall issues ?

The programmed firewall settings can be read back by the owner using TISCI_MSG_GET_FWL_REGION.

Direct readback of the firewall configuration registers is not currently allowed.

When a firewall exception occurs, the exception data is sent out via the enabled trace method. The data sent out is the dump of the firewall exception registers as defined in below section in the corresponding device TRM.

“System Interconnect” -> “System Interconnect Registers” -> “Firewall Exception Registers”

The following is an example of an exception log description that was sent via the enabled traces.

FWL Bit 0x1D
Exception addr 0x45B0B800
  FWL Exception 0x1129800
  0x30000
  0x707FFF20
  0x0
  0xFF82360
  0x8

The exception description can be interpreted as follows:

1. Line 1 (FWL Bit …) - This should be ignored.
2. Line 2 (Exception addr …) - This is the base address of the exception logging registers.
3. Line 3 (FWL Exception …) - Let this number be N, then:

• N[0-7] - Destination ID
• N[8-23] - Source ID

4. Line 4 - Let this number be N, then:

• N[0-15] - Not relevant for debugging.
• N[16-23] - Represents the exception type. Refer to the table below.

5. Line 5 - Lower 32 bits of the transaction address.
6. Line 6 - Let this number be N, then:

• N[0-15] - Upper 16 bits of the transaction address.

7. Line 7 - Let this number be N, then:

• N[0-7] - The PRIV ID of the initiator that caused the illegal transaction.
• N[8] - Represents the security level of the transaction.
• N[9] - Represents the privilege level of the transaction.
• N[10] - When set, it indicates a cacheable transaction.
• N[11] - When set, it indicates a debug transaction.
• N[12] - When set, it indicates a read transaction.
• N[13] - When set, it indicates a write transaction.
• N[16-27] - Route ID

8. Line 8 - Let this number be N, then:

• N[0-9] - Represents the transaction byte count.

Line4[16-23]	Exception Type.
0x00	Reserved.
0x01	No region enabled but firewall is active. One region must be enabled for whitelist firewall.
0x02	Incoming address does not hit any active region.
0x03	Priv-ID not authorized to access incoming address region, or Priv-ID not found in any slot for hit region.
0x04	Cacheable error, a cacheable transaction attempting to read/write non-cached marked region.
0x05	Debug error, a debug transaction attempting to read/write a debug not-allowed region.
0x06	Read error, a transaction attempting to read from read not-allowed region.
0x07	Write error, a transaction attempting to write a write not-allowed region.
0x08	4KB Crossing error, a transaction attempting to cross a 4KB boundary.

The 6 hex values shown above correspond to the 2 exception header registers and 4 exception data registers in the order shown in the TRM.

Warning

Please note that this format is being deprecated in favour of a binary format in conformance with the rest of traces supplied by System Firmware.

How are DMSC-managed resources firewalled ?

NAVSS resources managed by DMSC (UDMA channels, Rings, Proxy channels and IRQ) are firewalled automatically when the corresponding RM TISCI messages are sent.

Accessing these resources before sending the corresponding RM TISCI message will result in a firewall exception.