			Linux Utils CMEM module
			-----------------------


This package contains a Linux kernel loadable module as well as the user
interface library.  It also contains a small set of tests.

This particular implementation of CMEM's loadable kernel module is based
on the Linux kernel's CMA support.  It requires a small in-kernel stub that
must be added to your Linux kernel source tree.

In order to build the source code you will need to edit products.mak, pointing
it to your KERNEL_INSTALL_DIR and your codegen directories.

Linux kernel stub
=================

There are a few files that must be placed in your kernel's source tree.
These files can be found in 'cmem/module/kernel'.

The file cmemk_stub.c must be added to your Linux kernel source tree.  While
it can reside anywhere, it is recommended to create a new 'drivers/cmem'
directory and place the files cmemk_stub.c and Makefile in there.  Since a
new directory is being added below 'drivers', you will need to modify the
file 'drivers/Makefile' to point to the 'cmem' subdirectory.  This can be
accomplished by adding the following line to the 'drivers/Makefile' file:
        obj-y	+= cmem/

The header file cmemk_stub.h must be added to your Linux kernel 'include'
directory.  Place it in:
        <linux_kernel>/include/linux/cmemk_stub.h

You must also insert a call to a function defined in cmemk_stub.c to your
machine's "early boot" code.  This function is named 'cmem_reserve_cma()'.
The basic way to do this is to add a '.reserve' element to your machine's
'MACHINE_START()' macro/struct.  There can be only one 'MACHINE_START()'
defined for your particular board.  For instance, with OMAP-L138 there is a
file named 'arch/arm/mach-davinci/board-da850-evm.c' that contains the
following:
MACHINE_START(DAVINCI_DA850_EVM, "DaVinci DA850/OMAP-L138/AM18x EVM")
        .atag_offset    = 0x100,
        .map_io         = da850_evm_map_io,
        .init_irq       = cp_intc_init,
        .timer          = &davinci_timer,
        .init_machine   = da850_evm_init,
        .init_late      = davinci_init_late,
        .dma_zone_size  = SZ_128M,
        .restart        = da8xx_restart,
MACHINE_END
You should add the following to this struct:
        .reserve        = cmem_reserve_cma,
If there is already a '.reserve' function defined then you will need to
either add a call to 'cmem_reserve_cma()' to the function assigned to the
'.reserve' element, or define a new function that calls the existing
function in addition to calling 'cmem_reserve_cma()', and assign that new
function to the '.reserve' struct element.

Stub kernel command-line parameters
-----------------------------------

The CMEM kernel stub cmemk_stub.c supports two kernel parameters that control
how much CMA memory to reserve.  These parameters are added to the u-boot
'bootargs' variable.

cmem_heapsize: specifies how much CMA memory to reserve for the CMEM heap.
cmem_pools: specifies how many buffers of a specified size are allocated for
        the specified number of pools.
Each size-type parameter can be specified using the standard "KMG" formatting.

For example, the following:
        cmem_heapsize=100000 cmem_pools=10x4096,2x1M,4x256K
says to allocate 3 pools:
        pool 1 w/ 10 buffers of size 4096
        pool 2 w/ 2 buffers of size 1 MB
        pool 3 w/ 4 buffers of size 256 KB
and a heap of size 100000.

A separate CMA region will be allocated for the heap as well as for each pool.

Building the code
=================

The file products.mak (at the top level of this tree) contains two
definitions used by the build subsystem:
        KERNEL_INSTALL_DIR - The base directory of your Linux kernel
        source tree
        TOOLCHAIN_PREFIX - the 'prefix' for the GNU ARM codegen tools
The TOOLCHAIN_PREFIX can contain the full path of the codegen tools, ending
with the tool prefix, i.e.:
        TOOLCHAIN_PREFIX=/db/toolsrc/library/vendors2005/cs/arm/arm-2008q1-126/bin/arm-none-linux-gnueabi-

or it can be just the tool prefix if your shell's $PATH contains your
codegen's 'bin' directory:
        TOOLCHAIN_PREFIX=arm-none-linux-gnueabi-
where you $PATH contains:
	/db/toolsrc/library/vendors2005/cs/arm/arm-2008q1-126/bin

Installing the loadable kernel module
=====================================

The loadable kernel module 'cmemk.ko' can be installed into a running
system with the command:
        % insmod cmemk.ko
The traditional non-CMA CMEM implementation supports a number of module
parameters to define block start/end and pool geometry.  With this CMA
CMEM implementation, these parameters have been superceded by the kernel
command-line parameters specified above (although block start/end is not
yet supported).  However, one can still specifiy 'useHeapIfPoolUnavailable=1'
when insmod'ing cmemk.ko.

API test
========

There is an API test contained in 'cmem/tests/apitest.c'.  To run
this test, suppy a buffer size as the only test parameter:
        % apitest 10240
If you have no heap space allocated (with 'heapsize=##' on the kernel
command-line) then the heap portion of the test will fail.

