5.4.43. MessageBox component

The MessageBox component is designed to operate as a subcomponent to the VFS2 component. See VFS2 component. When used with a suitable driver, MessageBox permits passing of blocks of data, or messages, between the driver and the parent VFS2 device. The MessageBox component is not a hardware model, and is designed to operate efficiently within a Fast Models platform model.

The current MessageBox implementation is generic but is primarily designed to provide a transport layer for the VFS2 component.

A C header file, MBoxTypes.h, is supplied in the VFS2/C directory of Fast Models. This header file contains definitions of register offsets, control and status bits, and buffer sizes. The example MessageBox driver implementation in the VFS2/cpptest directory is a simple, polling implementation written in C++.

Figure 5.65 shows a view of the component in System Canvas.

Figure 5.65. MessageBox component in System Canvas

MessageBox component in System Canvas

This component is written in LISA+.

Ports

Table 5.121 provides a brief description of the MessageBox component ports.

Table 5.121. MessageBox ports

NamePort protocolTypeDescription
pvbus_sPVBusSlaveProvides memory-mapped access to the MessageBox registers and shared buffer.
messageMessageBoxSlaveDelivers messages to the parent component, and receives messages from the parent for delivery to the target driver.
intrSignalMasterOptional interrupt line used to indicate availability of incoming message data. Alternatively the status register can be polled.

MessageBox

The MessageBox component has one additional protocol.

The message port implements half of a protocol for communication with a parent device. The other half is implemented by the parent device. When the CONTROL register is written to with the MBOX_CONTROL_END value, the data between the START and END offsets in the buffer are sent by reference to the parent device. Either during this call, or afterwards, the parent device is free to invoke the other message behaviors to set up an incoming packet and set the RXREADY signal.

The protocol behaviors are:

begin_msg(void** buffer, uint32_t len)

Returns a pointer to the buffer for sending a message. len is ignored.

end_msg(uint32_t len)

Sets the START/END registers to indicate the start and end of the message in the buffer and sets the RXREADY signal.

message(const void* buffer, uint32_t len)

Indicates that a message has been received, and the contents are in the buffer with a length of len bytes. This behavior must be implemented by the parent device.

cancel_msg()

Cancel a message.

Parameters

Table 5.122 provides a description of the configuration parameters for the MessageBox component.

Table 5.122. MessageBox configuration parameters

Parameter nameDescriptionTypeAllowed valueDefault value
idMessageBox IDInteger-0x01400400

Registers

Table 5.123 provides a description of the configuration registers for the MessageBox component.

Table 5.123. MessageBox registers

Register nameOffsetAccessDescription
MESSAGEBOX_ID0x00read onlyReturns a user-configurable ID value.
MESSAGEBOX_DATA0x04read/writeSee DATA register.
MESSAGEBOX_CONTROL0x08read/writeSee CONTROL register.
MESSAGEBOX_STATUS0x0Cread onlySee STATUS signal bits.
MESSAGEBOX_START0x10read/writeSee START register.
MESSAGEBOX_END0x14read/writeSee END register.
MESSAGEBOX_IRQMASK0x18read/writeControls which of the status bits can cause the interrupt signal to be asserted.

DATA register

Writing to the DATA register writes to the buffer at the offset specified in the END register, and increments the register by 4.

Reading from the register reads from the buffer at the offset specified in the START register, and increments the register by 4.

CONTROL register

The CONTROL register issues commands to control message passing. The register can be programmed with one of two values:

1

Causes the START/END registers to be reset to 0 and clears the RXREADY bit in the STATUS register. This can also be done directly by programming the START/END registers to 0.

2

Causes the buffer memory between the START/END offsets to be sent to the parent component for processing. Typically the parent component performs some processing and at some point causes an incoming packet to be constructed in the buffer and the RXREADY signal to be set.

All other values for the CONTROL register are reserved.

STATUS signal bits

The STATUS signal returns status bits indicating whether more data can be transferred to or from the buffer and if there is a new incoming message available. The STATUS signal has three defined bits:

0 RXEMPTY

Set to 1 when START=END so no more receive data is available.

1 TXFULL

Set to 1 if END is incremented to the end of the buffer.

2 RXREADY

Set to 1 when an incoming packet is available for reading. This is reset to 0 when the DATA, START or END registers are accessed.

START register

When using the DATA register, the START register gives the offset of the next word to read from the buffer.

When accessing the buffer directly, for outgoing messages the START register is programmed to the start of the message. For incoming messages it indicates the start of the message. The offset is relative to the buffer start.

END register

When using the DATA register, the END register gives the offset to the first unused word after the end of the message.

When accessing the buffer directly, for outgoing messages the END register is programmed to 1 past the end of the message. For incoming messages it indicates 1 past the end of the message. The offset is relative to the buffer start.

Buffer

The data buffer is mapped starting at the device offset of 0x1000 and is currently 60KB in size, occupying the rest of the 64KB of device space. Do not use the first 4KB.

Interrupts

The interrupt line is asserted through sg::Signal::Set whenever STATUS & IRQMASK is non zero.

Debug features

The MessageBox component has no debug features.

Verification and testing

The MessageBox component has been tested through use with Linux operating systems.

Performance

The MessageBox component is not expected to significantly affect the performance of a PV system, but is itself dependent on the performance of the host filesystem.

Library dependencies

The MessageBox component has no dependencies on external libraries.

Copyright © 2008-2013 ARM. All rights reserved.ARM DUI 0423O
Non-ConfidentialID060613