SysLink 3
=========

SysLink3 is the implementation of a minimal set of SysLink2 APIs, 
hosted over the new AMP (rpmsg) feature in Linux kernel v3.x, and the
corresponding support for an rpmsg-based MessageQ Transport on the BIOS side.

The rpmsg functionality is exposed to user space via a socket interface, 
provided in the upstream-rpmsg repo (see below).

The main public API currently supported is MessageQ.

For current constraints, see the TODO section below.

Platforms:
=========
Messaging has been validated between Linux to BIOS on:
1) OMAPL138 EVM board: ARM to DSP.
2) OMAP4430 Panda board: Dual ARM9 to Ducati CORE0 ("SysM3").


BUILD:
=====

Linux side:
===========

Kernel space:
------------

1) Clone the upstream-rpmsg repo, and checkout the v0.4 tag
   (on rpmsg_3.4_rc1 branch):
  * git clone git://github.com/GAnthony/upstream-rpmsg.git
  * git checkout -b <branch_name> v0.4

2a) The syslink3 repo (see below) etc/ directory contains the .config files 
   used for testing.
  [OMAPL138]  etc/omapl138/omapl138_rpmsg_3.4_rc1.config
  [HAWKBOARD] etc/omapl138/hawkboard_rpmsg_3.4_rc1.config
  [OMAP4430]  etc/panda/panda_rpmsg_3.4_rc1.config

2b) Key config parameters needed for rpmsg and socket driver to build/work:
   CONFIG_REMOTEPROC=m
   CONFIG_DAVINCI_REMOTEPROC=m
   CONFIG_RPMSG=m
   CONFIG_VIRTIO=m
   CONFIG_VIRTIO_RING=m

3) Code Sourcery Toolchain version used: arm-2010q1 

User space:
-----------

1) Install the BIOS IPC product into a tools repository (REPO) directory:
  - See sysbios-rpmsg repo Makefile to get correct IPC version.
  - http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/

2) Install the latest CMEM version into the tools repository:
  - http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/linuxutils/index.html

3) Clone the following to get SysLink3 libraries, NameServer daemon and samples:
  * git clone git://github.com/GAnthony/syslink3.git
  * git checkout -b <branch_name> v0.4

4) Makefile.inc:
  * Ensure the following settings correspond to your installation versions:
    IPCPRODVER = <ipc version> 
    CMEMPRODVER = <linuxutils version> 
  * If your Code Sourcery Toolchain is not included on your PATH, specify it
    in the file:
    CROSS = <path of your Code Sourcery Toolchain>
            e.g. /opt/cs/arm-2010q1/bin/arm-none-linux-gnueabi-

5) Build:
  % make REPO=<path to your tools repository>
OR:
  - Edit Makefile.inc, update REPO variable to point to the tools repository.
  % make

BIOS side:
==========

1) Clone the sysbios-rpmsg repo, and checkout the v0.4 tag
  (on the syslink3 branch):
  * git clone git://github.com/GAnthony/sysbios-rpmsg.git
  * git checkout -b <branch_name> v0.4

2) See the README for tools and build instructions (substitute GAnthony repo 
   for the omapzoom repo mentioned in the README).  
   * Use the tools versions listed in the Makefile.

3) Note that the MessageQCopy, srvmgr, resmgr, pm, and grcm modules are
   not currently compatible with the new BIOS IPC transport: TransportVirtio.
   They build, but are not compiled into the test sample: messageq_single.

4) The result of this build will be a messageq_single ELF binary in the
   src/ti/ipc/tests/<ti_platforms_X>/<profile>/ directory.

Test:
====

1) Setup a root file system.  This was tested using a root file system from: 
   http://narcissus.angstrom-distribution.org/
   [OMAPL138] "machine type" = da850-omapl138-evm
   [OMAP4430] "machine type" = pandaboard

2) Boot Linux on the target: 
   [OMAPL138] (eg: boot uImage over TFTP, and load fs over NFS)
   setenv bootfile=/gp/uImage.omapl138.rpmsg_3.4_rc1
   setenv bootargs=console=ttyS2,115200n8 root=/dev/nfs rw nfsroot=<nfs_server_ip>:<rfs_path>,nolock ip=dhcp rootdelay=5
   setenv bootcmd=dhcp;bootm c0700000

   [OMAP4430] (eg: boot uImage on MMC, and load fs over NFS):
   setenv bootargs 'root=/dev/nfs rw nfsroot=<nfs_server_ip>:<rfs_path> rootdelay=5 console=ttyO2,115200n8 noinitrd ip=dhcp'
   setenv bootcmd 'mmcinit 0;fatload mmc 0:1 0x80000000 uImage; bootm'

3) Copy the messageq_single binary (from sysbios-rpmsg repo) to the target
   /lib/firmware directory, renaming to the firmware filename for your
   platform:

   [OMAPL138] % cp <sysbios-rpmsg>/src/ti/ipc/tests/ti_platforms_evmOMAPL138_DSP/release/messageq_single.xe674 <target>/lib/firmware/da8xx-dsp.elf

   [OMAP4430] % cp <sysbios-rpmsg>/src/ti/ipc/tests/ti_platform_omap4430_core0/release/messageq_single.xem3 <target>/lib/firmware/ducati-m3-core0.xem3

4) Copy the MessageQApp and lad daemon to the target:
   % cp <syslink3>/src/samples/MessageQApp <target>/home/user
   % cp <syslink3>/src/daemon/lad <target>/home/user

5) On the target, load the BIOS firmware and rpmsg socket driver:
   (Eg: See etc/<platform>/load_firmware.sh):
   % depmod -a
   % if [ ! -d "/debug" ]; then
        mkdir /debug
   % fi
   % mount -t debugfs none /debug
   % modprobe remoteproc
   % modprobe davinci_remoteproc  # [OMAPL138]
   % modprobe virtio_rpmsg_bus
   % modprobe rpmsg_proto

6) To dump the trace on the remote proc:
   (See etc/<platform>/dump_trace.sh):
   % cat /debug/remoteproc/davinci-rproc.0/trace0   # [OMAPL138]

7) Start the NameServer daemon: (based on Link Arbiter Daemon):
   (See etc/run_lad.sh):
   % lad lad.txt

8) Copy the <syslink3>/src/samples/MessageQApp sample to the target and Run:
   % MessageQApp

9) Expected Output: Linux side:

% MessageQApp

Entered MessageQApp_execute
Local MessageQId: 0x1
Remote queueId  [0x10000]
Exchanging 100 messages with remote processor...
MessageQ_get #0 Msg = 0x183b0
Exchanged 1 messages with remote processor
MessageQ_get #1 Msg = 0x183b0
Exchanged 2 messages with remote processor
MessageQ_get #2 Msg = 0x183b0
[...]
Exchanged 98 messages with remote processor
MessageQ_get #98 Msg = 0x183b0
Exchanged 99 messages with remote processor
MessageQ_get #99 Msg = 0x183b0
Exchanged 100 messages with remote processor
Sample application successfully completed!
Leaving MessageQApp_execute

10) Expected Output: BIOS trace:  [OMAPL138]

% dump_trace.sh

3 IpcMemory entries at 0xc4000000
messageq_single.c:main: MultiProc id = 1
TransportVirtioSetup_attach: remoteProcId: 0
tsk1Fxn: created MessageQ: SLAVE; QueueID: 0x10000
Awaiting sync message from host...
Received msg from (procId:remoteQueueId): 0x0:0x1
        payload: 8 bytes; loops: 100 with printing.
Got msg #0 (40 bytes) from core 0
Sending msg Id #0 to core 0
Got msg #1 (40 bytes) from core 0
Sending msg Id #1 to core 0
[...]
Got msg #98 (40 bytes) from core 0
Sending msg Id #98 to core 0
Got msg #99 (40 bytes) from core 0
Sending msg Id #99 to core 0
Awaiting sync message from host...

11) To unload the firmware and stop the coprocessor:
   (See etc/<platform>/unload_firmware.sh)
   % rmmod rpmsg_proto
   % rmmod virtio_rpmsg_bus
   % rmmod davinci_remoteproc   # [OMAPL138]
   % rmmod remoteproc

CMEM:
=====
CMEM (Contiguous MEMory allocator) is currently the only supported way to
allocate a contiguous block of memory from a user space application to 
share with the remote core. 

See the CMEM documentation link below for an overview.

Passing a pointer to a shared memory buffer is demonstrated in the Linux and 
BIOS side tests: nano_test.c.

See etc/omapl138/nano_test.sh for usage with the ALSA utility arecord and the
OMAPL138 sound driver.

Build:
======
1) See readme.txt in <linuxutils_install_dir>/packages/ti/sdo/linuxutils/cmem

2) % cd src/module
   % make
   % make install

Install:
========
1) Add mem= line to carveout CMEM memory from Linux: 
   (eg for OMAPL138 EVM with 128M DDR):
      # setenv bootargs "mem=112M console=ttyS2,115200n8 root=/dev/nfs rw nfsroot=146.252.160.87:/exports/gp/omapl138_angstrom_rfs,nolock ip=dhcp rootdelay=5"

2) insmod cmemk.ko, specifying physical start, end addresses:
      % insmod cmemk.ko phys_start=0xc7000000 phys_end=0xc8000000

Documentation:
==============

* http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/syslink/latest/docs/html/index.html
* http://free-electrons.com/pub/video/2011/elce/elce-2011-ben-cohen-remote-processor-messaging-450p.webm
* https://github.com/ohadbc/upstream-rpmsg/blob/rpmsg_3.4_rc1/Documentation/rpmsg.txt
* https://github.com/ohadbc/upstream-rpmsg/blob/rpmsg_3.4_rc1/Documentation/virtual/virtio-spec.txt
* http://www.omappedia.org/wiki/Syslink_3
* http://processors.wiki.ti.com/index.php/CMEM_Overview

Known Issues:
============
* Build for Panda board is broken on sysbios-rpmsg repo.
* Cleanup on abnormal process termination or NameServer timeouts not completely   handled.
* For each interrupt from the DSP, a second spurious call to the irq function
  in davinci_remoteproc is occuring, despite the fact that there is no
  actual second interrupt.  A hack was put in to ignore this second spurious
  interrupt until a patch to the interrupt handling code on davinci is found.

TODO:
=====
* Multiple platform build support in both syslink3 and sysbios-rpmsg repos.
* Add OSAL, and replace printf in API modules with Log_printf.
* Support multiple processes.
* Make TransportVirtio compatible with MessageQCopy and rpmsg-omx.