L4Env Phys. Memory Dataspace Manager Reference Manual

Contents

• Introduction
• Usage
  • Starting the DMphys Server (dm_phys)
  • Using the Client Libraries
  • Using the Dataspace Manager Server Support Library
• Client Library API Documentation
  • Dataspace Types
  • Open/Close/Copy Dataspaces
  • Various Memory Allocation Support Functions
  • Map Dataspace Regions
  • Dataspace Client Handling
  • Miscellaneous Function to Manage Memory Dataspaces
  • Debug Functions
• Dataspace Manager Server Support Library Documentation
  • Dataspace Management
  • Client Handling
  • Iterate Dataspace List
  • Initialization
  • Debugging
• IDL Interface Documentation
  • Generic Dataspace Manager Interface
  • Memory Dataspace Manager Interface
  • Physical Memory Dataspace Manager Interface
• Notes on Dataspace Access Rights

Introduction

The L4Env Phys. Memory Dataspace Manager (DMphys) manages the available phys. memory of a system. It implements and extents the L4Env Dataspace Manager Interface .

Features:

• DMphys support the definition of various memory pools. Each memory pool exclusively manages an area of the phys. memory. Memory pools can be used to reserve and use certain memory areas for special purposes. There are two predefined memory pools, one which holds ISA DMA capable memory (memory below 16MB) and one which holds all the remaining available memory (note that by default no memory is assigned to the ISA DMA memory pool, it must be configured with the --isa command line option of DMphys).
• DMphys supports the allocation of phys. contiguous and aligned memory.
• The memory provided by DMphys is "pinned". That means that once the memory is mapped to a client, no pagefaults will occur accessing that memory.
• DMphys supports 4MB-pages (aka superpages).

Usage

DMphys consists of two main parts, the DMphys server (dm_phys) and the dataspace manager client libraries (libdm_phys.a, libdm_mem.a and libdm_generic.a).

Starting the DMphys Server (dm_phys)

The DMphys server depends on the name server names and log. It is registered at the name server as "DM_PHYS".

Example grub boot menu entry:

module = (nd)/tftpboot/names
module = (nd)/tftpboot/log  
module = (nd)/tftpboot/dm_phys

Examples for pool configurations. Note, use page size aligned values only.

--pool=1,0x00401000,0x003ff000,0x00800000,linux
--isa=0x00800000,0x00800000,0x01000000

For most purposes, starting DMphys without any arguments should be sufficient. Possible command line arguments are:

-v | --verbose

Show memory and pool list on startup.

-p | --pool=pool,size[,low,high[,name]]

Memory pool configuration

pool

Memory pool number (0..7), predefined pools are pool 0 (default pool) and pool 7 (ISA DMA capable memory)

size

Memory pool size, if set to -1 DMphys will use all available memory

low,high

Memory pool min/max address. If set to -1, DMphys will use default values for low (0) and high (max phys. memory).

name

Memory pool name.

-m | --mem=size[,low,high[,name]]

Configuration for default memory pool (0). Default is to use all available memory.

-i | --isa=size[,low,high[,name]]

Configuration for ISA DMA memory pool (7). Default is to not allocate memory for the pool and set high to 16MB.

-r | --reserve=low,high

Do not use memory area (low,high) for any memory pool.

-l | --low=low

Set default min. address to low. It will be used if the min. address of a pool is set to -1.

-h | --high=high

Set default max. address to high. It will be used if the max. address of a pool is set to -1.

-R | --rmgr

Use the Resource Manager to allocate pool memory. If this option is set, a pool size must be specified for all pools (including the default memory pool!). Default is to allocate memory directly at Sigma0.

-n | --no_4M_pages

Do not use 4MB-pages (aka superpages) to map memory. If this option is set, DMphys will not be able to provide 4MB-pages to clients and the initialization of DMphys will take a longer time.

Using the Client Libraries

According to the IDL interface specification, the dataspace manager client API is seperated into serveral libraries:

• Generic dataspace manager client library (libdm_generic.a)
• Memory dataspace manager client library (libdm_mem.a)
• Physical memory dataspace manager client library (libdm_phys.a)

Each of these libraries provides wrapper functions for the according IDL interface functions and additional support functions to ease the use of the dataspace managers. Like the IDL interfaces, the libraries extend each other. This means that you must link libdm_generic.a and libdm_mem.a to your applications if you want to use functions of the memory dataspace manager interface, resp. all three libraries if you want to use functions of the physical memory dataspace manager interface.

Applications should always use the functions provided by the client libraries instead of the IDL interface functions. See the Client Library API Documentation for a detailed description of the API functions.

Using the Dataspace Manager Server Support Library

The Dataspace Manager Server Support Library (libdm_generic-server.a) provides several functions to ease the implementation of dataspace managers. The library mainly contains functions for bookkeeping and dataspace client handling. See the Dataspace Manager Server Support Library Documentation for a detailed description of the API functions.