TI81XX PSP IOMMU Driver User Guide

Linux PSP IOMMU Driver Guide

Linux PSP

IMPORTANT

DM816x refers to DM816x/AM389x devices unless specified.
DM814x refers to DM814x/AM387x devices unless specified.
DM81xx refers to both DM816x, DM814x and DM813x.

Introduction

IOMMU driver provides set of kernel APIs for other kernel modules to configure/program a specific IOMMU in the system. It also provides set of APIs for managing virtual address space through IOMMU. This document describes the framework and the list of APIs. It also provides information on debugging the iommu from user space.

NOTE

"IOMMU" is the same as "System MMU" from the Technical Reference Manual.

IOMMU Framework

The framework consists of 3 layers, Core, Architecture Hook and Consumers

Core

This layer consists of the iommu platform driver, iovmm virtual space manager and debug-fs for debugging the IOMMUs. This layer abstracts the underlying IOMMU architecture and provides a glue interface to the actual hardware. It supports reference counting mechanism so that many consumers can use the same IOMMU instance. The number of IOMMU instances available in a platform differs from platform to platform. Similarly, the names and resources for each IOMMU instance can differ from platform to platform. For example, System MMU's name could be "sys" and IO address will differ from other instances. This information is provided in the platform data during system boot.

Files

          Driver: arch/arm/plat-omap/iommu.c
             VMM: arch/arm/plat-omap/iovmm.c
        Debug-FS: arch/arm/plat-omap/iommu-debug.c
platform devices: arch/arm/mach-omap2/omap-iommu.c

Exported APIs

This block provides APIs to configure/program the TLB and Page Table for an IOMMU. Refer respective header files for API signature and parameters.

Architecture APIs

• install_iommu_arch: Register a new architecture hook with the core layer.
• uninstall_iommu_arch: Un-register an architecture hook from the core layer.

Consumer APIs

• iommu_get: Consumer can query for an IOMMU specifying the name of the IOMMU instance. The API will return the IOMMU object which will be used to identify the IOMMU in all other APIs. The reference count for a IOMMU will be incremented on every get. The API will enable the clock for the module. It will also flush all the TLB entries (ref_count == 0).
• iommu_save_ctx: Save the context of an IOMMU, This saves the MMRs to the memory. Will be used during power management.
• iommu_restore_ctx: Re-store the saved IOMMU context.
• iommu_arch_version: Return the IOMMU architecture version number.
• iotlb_cr_to_e: Convert the CR field to entry field and return it.
• iotlb_cr_to_virt: Convert the CR field to virtual address and return it.
• load_iotlb_entry: Set a TLB entry in the IOMMU.
• flush_iotlb_page: Delete an IOTLB entry based on the passed virtual address.
• flush_iotlb_range: Same as above but a virtual address range is specified as input.
• flush_iotlb_all: Clear all IOTLB entries.
• iommu_set_twl: Enable table walking logic for an IOMMU
• iommu_dump_ctx: Print all the MMRs in the IOMMU. Used by Debug-FS.
• dump_tlb_entries: Print all the TLB entries in the IOMMU. Used by Debug-FS.
• foreach_iommu_device: Looping helper for all IOMMU devices.
• iopgtable_store_entry: Store the passed page table entry ("e") in the page table for the specified IOMMU.
• iopgtable_lookup_entry: Search for a specified page table entry ("e") in the page table for the specified IOMMU.
• iopgtable_clear_entry: Clear a specified page table entry ("e") in the page table for the specified IOMMU.
• iommu_set_da_range: This is a helper used to set a valid device address range for a IOMMU. This range will be used to validate any device virtual address passed to other APIs.
• iommu_put: This does the exact opposite of iommu_get. Consumer should release an IOMMU object if it is done with using the instance.

Architecture Hooks

These are hooks for a specific IOMMU architecture. For example, the IOMMUs used in omap2/3 and DM81xx devices fall under omap2 architecture. This layer provides the architecture specific hooks which will configure/program the hardware.

Files

   omap2 Arch hook: arch/arm/mach-omap2/iommu2.c

Exported APIs

This block provides APIs to manage the virtual address space through IOMMU.

• find_iovm_area: Find the iovma which has the specified device virtual address.
• da_to_va: Returns mopu virtual address which corresponds to a given device virtual address.
• iommu_vmap: Create 1-n-1 mapping with given scatter gather table and return device virtual address. Scatter gather table element must be io page size aligned.
• iommu_vunmap: Release virtual mapping obtained by iommu_vmap().
• iommu_vmalloc: Allocate a buffer linearly and create 1-n-1 mapping and return device virtual address again, which might be adjusted if 'IOVMF_DA_ANON' flag is set.
• iommu_vfree: Release memory allocated by 'iommu_vmalloc().
• iommu_kmap: Create 1-1-1 mapping and return device virtual address again, which can be adjusted if 'IOVMF_DA_ANON' flag is set.
• iommu_kunmap: Release virtual mapping obtained by 'iommu_kmap()'.
• iommu_kmalloc: Allocate buffer linearly and create 1-1-1 mapping and return device virtual address again, which might be adjusted if 'IOVMF_DA_ANON' flag is set.
• iommu_kfree: Release virtual mapping obtained by iommu_kmalloc().

Consumer

Consumer is a client (in kernel) which uses the IOMMU framework to configure/program the IOMMU hardware. For example, syslink will have to configure/program the system mmu before loading the DSP firmware. Syslink module could accomplish this using the APIs exported by the IOMMU core layer.

Enabling IOMMU support in kernel

IOMMU support is enabled by default for all OMAP2/3 and DM81xx platforms. The Debug-FS interface for IOMMU is optional. The Debug-FS interface currently could be built only as a module.

Debugging IOMMU

The Debug-FS exports following entries to assist in debugging the IOMMU driver/hardware. As mentioned in previous section, Debug-FS interface for IOMMU is optional. Note: The Debug-FS interface could be built only as a module.

Please follow the steps given below to debug IOMMU,

• Debug-FS config variable should be enabled in the kernel configuration from the following location,

  System Type  --->  
 TI OMAP Common Features  --->  
       <M> Export OMAP IOMMU internals in DebugFS

• After enabling, build the module,

  make modules

The binary should be available in arch/arm/plat-omap/iommu-debug.ko

• Insert the module in the target

  insmod iommu-debug.ko 

• The debug-fs should be mounted to view the entries

  mount -t debugfs none /sys/kernel/debug/

After this the iommu debug-fs entries should be available under /sys/kernel/debug/iommu. This folder will be referred as iommu debug-fs root' or simply debug root here after.

• Each IOMMU instance will have a sub-directory under the above mentioned debug root. For example, if a platform had "System" and "Ducati" MMU there should be two folders one as /sys/kernel/debug/iommu/ducati and one as /sys/kernel/debug/iommu/sys.

• Each IOMMU instance will have the following Debug-FS entries.
  • ver: Display the IOMMU architecture version. Read Only.
  • mem: Search the vma for the specified device virtual address and dump the buffer for specified size.
  • mmap: List each memory mapped entry (i.e. start, end, size, flags) for the IOMMU instance.
  • nr_tlb_entries: Number of TLB entries available in the IOMMU architecture. Read Only.
  • pagetable: Dump all the entries in the IO page table for the IOMMU instance.
  • reg: Dump all the MMRs for the IOMMU instance. Read Only.
  • tlb: Dump all the TLB entries for the IOMMU instance.

Note: use echo to write a value to a Debug-FS entry. Use cat to display the contents of a Debug-FS entry

IOMMU Instances in TI Devices

The table below captures the list of the IOMMU instances for different TI devices.

IOMMU Instances

Platform	Instance Name	Clock Name	Number of TLB entries	Base Address
OMAP3	isp	cam_ick	8	0x480bd400
	iva2	iva2_ick	32	0x5d000000
OMAP4	ducati	ducati_ick	32	0x55082000
	tesla	tesla_ick	32	0x4A066000
DM81xx	ducati	ducati_ick	32	0x55082000
	sys	mmu_cfg_ick	32	0x48010000