To include shared-memory objects in VxWorks, select INCLUDE_SM_OBJ for inclusion in the project facility VxWorks view. Most of the configuration is already done automatically from usrSmObjInit( ) in usrConfig.c. However, you may also need to modify some values in the Params tab of the properties window to reflect your configuration; these are described in this section.

Shared-memory objects and the shared-memory network¹ use the same memory region, anchor address, and interrupt mechanism. Configuring the system to use shared-memory objects is similar to configuring the shared-memory network driver. For a more detailed description of configuring and using the shared-memory network, see VxWorks Network Programmer's Guide: Data Link Layer Network Components. If the default value for the shared-memory anchor address is modified, the anchor must be on a 256-byte boundary.

One of the most important aspects of configuring shared-memory objects is computing the address of the shared-memory anchor. The shared-memory anchor is a location accessible to all CPUs on the system, and is used by both VxMP and the shared-memory network driver. The anchor stores a pointer to the shared-memory header, a pointer to the shared-memory packet header (used by the shared-memory network driver), and a pointer to the shared-memory object header.

The address of the anchor is defined in the Params tab of the Properties window with the constant SM_ANCHOR_ADRS. If the processor is booted with the shared-memory network driver, the anchor address is the same value as the boot device (sm=anchorAddress). The shared-memory object initialization code uses the value from the boot line instead of the constant. If the shared-memory network driver is not used, modify the definition of SM_ANCHOR_ADRS as appropriate to reflect your system.

Two types of interrupts are supported and defined by SM_INT_TYPE: mailbox interrupts and bus interrupts (see VxWorks Network Programmer's Guide: Data Link Layer Network Components). Mailbox interrupts (SM_INT_MAILBOX) are the preferred method, and bus interrupts (SM_INT_BUS) are the second choice. If interrupts cannot be used, a polling scheme can be employed (SM_INT_NONE), but this is much less efficient.

When a CPU initializes its shared-memory objects, it defines the interrupt type as well as three interrupt arguments. These describe how the CPU is notified of events. These values can be obtained for any attached CPU by calling smCpuInfoGet( ).

The default interrupt method for a target is defined by SM_INT_TYPE, SM_INT_ARG1, SM_INT_ARG2, and SM_INT_ARG3 on the Params tab.

Shared-memory objects rely on a shared-memory region that is visible to all processors. This region is used to store internal shared-memory object data structures and the shared-memory system partition.

The shared-memory region is usually in dual-ported RAM on the master, but it can also be located on a separate memory card. The shared-memory region address is defined when configuring the system as an offset from the shared-memory anchor address, SM_ANCHOR_ADRS, as shown in Figure 6-3.

Figure 6-3:  Shared-Memory Layout

Shared-memory objects are initialized by default in the routine usrSmObjInit( ) in installDir/target/src/config/usrSmObj.c. The configuration steps taken for the master CPU differ slightly from those taken for the slaves.

The address for the shared-memory pool must be defined. If the memory is off-board, the value must be calculated (see Figure 6-5).

The example configuration in Figure 6-4 uses the shared memory in the master CPU's dual-ported RAM. On the Params tab of the properties window for the master, SM_OFF_BOARD is FALSE and SM_ANCHOR_ADRS is 0x600. SM_OBJ_MEM_ADRS is set to NONE, because on-board memory is used (it is malloc'ed at run-time); SM_OBJ_MEM_SIZE is set to 0x20000. For the slave, the board maps the base of the VME bus to the address 0x1000000. SM_OFF_BOARD is TRUE and the anchor address is 0x1800600. This is calculated by taking the VMEbus address (0x800000) and adding it to the anchor address (0x600). Many boards require further address translation, depending on where the board maps VME memory. In this example, the anchor address for the slave is 0x1800600, because the board maps the base of the VME bus to the address 0x1000000.

Figure 6-4:  Example Configuration: Dual-Ported Memory

In the example configuration in Figure 6-5, the shared memory is on a separate memory board. On the Params tab for the master, SM_OFF_BOARD is TRUE, SM_ANCHOR_ADRS is 0x3000000, SM_OBJ_MEM_ADRS is set to SM_ANCHOR_ADRS, and SM_OBJ_MEM_SIZE is set to 0x100000. For the slave board, SM_OFF_BOARD is TRUE and the anchor address is 0x2100000. This is calculated by taking the VMEbus address of the memory board (0x2000000) and adding it to the local VMEbus address (0x100000).

Figure 6-5:  Example Configuration: an External Memory Board

Some additional configuration are sometimes required to make the shared memory non-cacheable, because the shared-memory pool is accessed by all processors on the backplane. By default, boards with an MMU have the MMU turned on. With the MMU on, memory that is off-board must be made non-cacheable. This is done using the data structure sysPhysMemDesc in sysLib.c. This data structure must contain a virtual-to-physical mapping for the VME address space used for the shared-memory pool, and mark the memory as non-cacheable. (Most BSPs include this mapping by default.) See 7.3 Virtual Memory Configuration in this manual for additional information.

	CAUTION: For the MC68030, if the MMU is off, data caching must be turned off globally; see the reference entry for cacheLib.

When shared-memory objects are initialized, the memory size as well as the maximum number of each object type must be specified. The master processor specifies the size of memory using the constant SM_OBJ_MEM_SIZE. Symbolic constants are used to set the maximum number of different objects. These constants are specified on the Params tab of the properties window. See Table 6-5 for a list of these constants.

Table 6-5:  Configuration Constants for Shared-Memory Objects

Symbolic Constant	Default Value	Description
SM_OBJ_MAX_TASK	40	Maximum number of tasks using shared-memory objects.
SM_OBJ_MAX_SEM	30	Maximum number of shared semaphores (counting and binary).
SM_OBJ_MAX_NAME	100	Maximum number of names in the name database.
SM_OBJ_MAX_MSG_Q	10	Maximum number of shared message queues.
SM_OBJ_MAX_MEM_PART	4	Maximum number of user-created shared-memory partitions.

If the size of the objects created exceeds the shared-memory region, an error message is displayed on CPU 0 during initialization. After shared memory is configured for the shared objects, the remainder of shared memory is used for the shared-memory system partition.

The routine smObjShow( ) displays the current number of used shared-memory objects and other statistics, as follows:

-> smObjShow 
value = 0 = 0x0

The routine is automatically included if INCLUDE_SM_OBJ is selected for inclusion in the project facility VxWorks view. The output of smObjShow( ) is sent to the standard output device, and looks like the following:

Shared Mem Anchor Local Addr : 0x600 
Shared Mem Hdr Local Addr    : 0x363ed0 
Attached CPU                 : 2 
Max Tries to Take Lock       : 0 
Shared Object Type      Current      Maximum      Available 
------------------      -------      -------      --------- 
Tasks                         1           40             39 
Binary Semaphores             3           30             27 
Counting Semaphores           0           30             27 
Messages Queues               1           10              9 
Memory Partitions             1            4              3 
Names in Database             5          100             95 

	CAUTION: If the master CPU is rebooted, it is necessary to reboot all the slaves. If a slave CPU is to be rebooted, it must not have tasks pended on a shared-memory object.

The following example shows the configuration for a multiprocessor system with three CPUs. The master is CPU 0, and shared memory is configured from its dual-ported memory. This application has 20 tasks using shared-memory objects, and uses 12 message queues and 20 semaphores. The maximum size of the name database is the default value (100), and only one user-defined memory partition is required. On CPU 0, the shared-memory pool is configured to be on-board. This memory is allocated from the processor's system memory. On CPU 1 and CPU 2, the shared-memory pool is configured to be off-board. Table 6-6 shows the values set on the Params tab of the properties window for INCLUDE_SM_OBJECTS in the project facility.

Table 6-6:  Configuration Settings for Three CPU System

CPU	Symbolic Constant	Value
Master (CPU 0)	SM_OBJ_MAX_TASK	20
	SM_OBJ_MAX_SEM	20
	SM_OBJ_MAX_NAME	100
	SM_OBJ_MAX_MSG_Q	12
	SM_OBJ_MAX_MEM_PART	1
	SM_OFF_BOARD	FALSE
	SM_MEM_ADRS	NONE
	SM_MEM_SIZE	0x10000
	SM_OBJ_MEM_ADRS	NONE
	SM_OBJ_MEM_SIZE	0x10000
Slaves (CPU 1, CPU 2)	SM_OBJ_MAX_TASK	20
	SM_OBJ_MAX_SEM	20
	SM_OBJ_MAX_NAME	100
	SM_OBJ_MAX_MSG_Q	12
	SM_OBJ_MAX_MEM_PART	1
	SM_OFF_BOARD	TRUE
	SM_ANCHOR_ADRS	(char *) 0xfb800000
	SM_MEM_ADRS	SM_ANCHOR_ADRS
	SM_MEM_SIZE	0x80000
	SM_OBJ_MEM_ADRS	(SM_MEM_ADRS + SM_MEM_SIZE)
	SM_OBJ_MEM_SIZE	0x80000

Note that for the slave CPUs, the value of SM_OBJ_MEM_SIZE is not actually used.

Initialization is performed by default in usrSmObjInit( ), in installDir/target/src/config/usrSmObj.c. On the master CPU, the initialization of shared-memory objects consists of the following:

1. Setting up the shared-memory objects header and its pointer in the shared-memory anchor, with smObjSetup( ).

1. Initializing shared-memory object parameters for this CPU, with smObjInit( ).

1. Attaching the CPU to the shared-memory object facility, with smObjAttach( ).

On slave CPUs, only steps 2 and 3 are required.

The routine smObjAttach( ) checks the setup of shared-memory objects. It looks for the shared-memory heartbeat to verify that the facility is running. The shared-memory heartbeat is an unsigned integer that is incremented once per second by the master CPU. It indicates to the slaves that shared-memory objects are initialized, and can be used for debugging. The heartbeat is the first field in the shared-memory object header; see 6.5 Troubleshooting.

1:  Also known as the backplane network.