Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

SysLink Notify

From Texas Instruments Wiki
Jump to: navigation, search

Introduction

"Notify" is an IPC mechanism that allows notification of events from one processor to another. It first appeared in SYS/BIOS and SysLink packages. Since its first appearance in SysLink, community usage has become common enough to compel Linux developers to incorporate the Notify module directly into the Linux kernel. The SysLink interface was essentially adopted as-is, and SysLink's implementation was ported to the Linux kernel.

USE_SYSLINK_NOTIFY vs CONFIG_SYSLINK_NOTIFY (or CONFIG_SYSLINK_NOTIFY_MODULE)

In addition to providing an implementation, SysLink is also a user of the Notify module, invoking its APIs as part of other SysLink modules/mechanisms. SysLink contains code for communicating to *either* the SysLink Notify or the Linux kernel 'notify' implementation. The SysLink control for choosing one or the other code set is implemented via a C preprocessor macro named USE_SYSLINK_NOTIFY. When set to 1, SysLink's Notify module is fully self-contained in the build of the SysLink kernel module syslink.ko, and SysLink makes calls to that code. When set to 0, SysLink's Notify module is partially present in the build of syslink.ko, and at the lowest level SysLink makes calls to the in-kernel Linux implementation instead of executing the SysLink low-level implementation.

Since both SysLink's and the Linux kernel's implementations are accomplishing the same functionality, they can't co-exist in the same system. The presense of Linux's 'notify' module is controlled by the kernel configuration, so SysLink must adapt. This adaptation is made simple because of the fact that syslink.ko must be built in association with a configured Linux kernel, so SysLink code can inspect the Linux kernel configuration and act accordingly.

The Linux kernel also contains a C-level control for controlling the existence of the Linux kernel 'notify' module, named CONFIG_SYSLINK_NOTIFY. Unfortunately, this control is named very similarly to SysLink's control. When set to 1, Linux's 'notify' module is built and included in the Linux kernel (including "init" bootup code that conflicts with what SysLink's Notify module initializes).

This name similarity is especially confusing since both control names contain "SYSLINK_NOTIFY". In the sense of SysLink's USE_SYSLINK_NOTIFY, it says to "use the notify module present in SysLink". In the sense of the Linux kernel's CONFIG_SYSLINK_NOTIFY, it says to "configure the module otherwise known as 'SysLink Notify'", since the Notify module was originally defined by the SysLink package.

The Linux kernel 'notify' implementation can be either directly built-in to the kernel so that it's present when the kernel boots, or it can be configured as a loadable module and inserted into the Linux kernel at runtime (module name notifyk.ko). For both cases SysLink must not include its Notify implementation, and when the Linux kernel 'notify' is configured as a loadable module it must be inserted into the running kernel before SysLink's loadable module syslink.ko is inserted, in order to satisfy Linux kernel 'notify' references from SysLink. When the Linux kernel 'notify' is configured as a loadable module, the Linux kernel macro CONFIG_SYSLINK_NOTIFY_MODULE is #define'd instead of CONFIG_SYSLINK_NOTIFY. Subsequent references in this document to CONFIG_SYSLINK_NOTIFY also apply for the CONFIG_SYSLINK_NOTIFY_MODULE case.

"Recent" SysLink releases contain auto-detection of the kernel control and automatically "#define USE_SYSLINK_NOTIFY" (when CONFIG_SYSLINK_NOTIFY is not #define'd) or don't #define it (when CONFIG_SYSLINK_NOTIFY is #define'd), so most system integrators don't have to worry about it.

There is also a 'make' variable named USE_SYSLINK_NOTIFY present in the SysLink build framework that provides some control of the setting of the C preprocessor macro USE_SYSLINK_NOTIFY. Typically it can be left unset to allow the auto-detection feature to kick in, but you can explicitly set it to provide some direct control, for example:

   % make USE_SYSLINK_NOTIFY=0 syslink

will force the SysLink build to use the Linux kernel's 'notify' implementation, effectively disabling the auto-detection (note: doesn't work in SysLink 2.10.07 and previous nor 2.20.00). Setting the 'make' variable USE_SYSLINK_NOTIFY=1, however, will not force usage of SysLink's Notify implementation, but will instead trigger some validation of the Linux kernel's configuration (see below).

Older SysLink releases contained a manual setting of the 'make' variable USE_SYSLINK_NOTIFY, easily allowing a conflict between SysLink and the Linux kernel. If your Linux kernel contained a 'notify' implementation, you had to set USE_SYSLINK_NOTIFY=0, and if your Linux kernel did not contain it, you had to set USE_SYSLINK_NOTIFY=1 (which was the default for TI814X & TI816X processors).

Even in SysLink releases that contain the auto-detection of the CONFIG_SYSLINK_NOTIFY setting, it's still possible to manually set the 'make' variable USE_SYSLINK_NOTIFY=1. When doing so, the auto-detect code will instead become auto-validation code, ensuring that the two settings don't confict (and #error'ing if they do).

Symptoms of having both #define'd

When both USE_SYSLINK_NOTIFY and CONFIG_SYSLINK_NOTIFY are #define'd, a kernel crash will likely result. This crash happens because SysLink's Notify module initialization code has changed the state of HW upon which Notify is implemented, but that HW has already been initialized/setup for use by the Linux kernel 'notify' module.

Symptoms of having neither #define'd

Your SysLink kernel module (syslink.ko) build will fail with unresolved references to Linux kernel 'notify' module APIs.

Limitations with respect to cache usage

Starting in SysLink 2.20, SharedRegion 0 (SR0) can be made cacheable from the HLOS side. It is recommended that SR0 be non-cached as the cache management of internal data structures in SR0 may reduce performance, but enabling HLOS-side cache is supported.

Note that in TI81XX Linux-based systems, the Linux-side in-kernel notify driver is not cache aware, and will malfunction if SR0 is made cacheable. Further, the VPSS driver directly uses the in-kernel notify driver (to avoid a kernel dependency on SysLink, a good thing). So enabling cache on SR0 may not be possible in that environment. However, if you're not using the VPSS driver, and you want to enable Linux-side cache for SR0, the SysLink Notify driver may be used.

Implications on other SharedRegions

SharedRegions other than SR0 can be made cacheable regardless of which Notify driver is used. The Notify only uses SR0 for its internal structures.

Implications on different OSes

This information applies only to Linux. In QNX there is only the SysLink-provided Notify driver, whereas in BIOS there is only the IPC-provided Notify driver.