|
This layer corresponds to the presentation layer of the ISO Reference Model. The presentation layer drivers provide functions like receive an integer or send a record, which enable the cluster drivers to communicate with the run-time libraries of the tasks in an application using common data representations. The presentation layer converts between host and target system formats, e.g., if there are different floating-point formats, or a different ordering of the octets within an integer.
Presentation protocol 5 (P5) is used for the C6000, and in some other implementations of Diamond. P1 is an older protocol used by previous 3L software.
The P5 protocol operates on the host by reading a parameter block from the CPU. This contains all the information needed by the service being called. The block is held in a buffer and accessed by the presentation input functions (Present::get_int, Present::get_rec, etc). When all of the information in the buffer has been taken, the same buffer is reused to collect information being sent back to the CPU by the output functions (Present::put_int, Present::put_rec, etc).
 The service must read everything it needs from the buffer before it attempts to return any values to the DSP.
Usually, when the service returns, the server finishes by optionally calling put_int to send the service function's result as a final value in the buffer and then calling the push function to transmit the contents of the buffer back to the CPU. The server then waits for the next service request.
The current presentation layer uses a buffer of 8292 octets. The total size of any request (all the put calls) or response (all the get calls) must not exceed this.
Every cluster is given a pointer to a presentation layer, P. This provides the following member functions.
get_int
ps1_integer Present::get_int();
|
|
Read a single 32-bit integer from the input buffer.
|
|
put_int
void Present::put_int(ps1_integer);
|
|
Put a 32-bit integer to the output data buffer.
|
|
get_rec
size_t Present::get_rec(void *);
|
|
Get a record from the input data buffer. A record is transmitted as an array of octet values, rounded up to a multiple of four. The values are placed in the object pointed at by the parameter, and the function returns the number of octets received. The maximum size of a record is 4096 octets.
|
|
put_rec
void Present::put_rec(size_t, const void *);
|
|
Send a record to the output data buffer. A record is transmitted as an array of octet values, rounded up to a multiple of four. The first parameter gives the number of values and the second parameter locates the object containing them. The maximum size of a record is 4096 octets.
|
|
get_double
ps1_double Present::get_double(void);
|
|
Get a floating-point double value from the input data buffer.
|
|
put_double
void Present::put_double(ps1_double d);
|
|
Send a floating-point double value to the output data buffer.
|
|
get_bits
ps1_bits Present::get_bits(void);
|
|
Get an uninterpreted four-octet value from the input data buffer. This is the same as get_int when the host and CPU integer formats are equivalent.
|
|
put_bits
void Present::put_bits(ps1_bits b);
|
|
Send an uninterpreted four-octet value to the output data buffer. This is the same as put_int when the host and CPU integer formats are equivalent.
|
|
signal_host_sema
void Present::signal_host_sema(int n);
|
|
Signal an asynchronous event to the root processor. The root maintains 10 host semaphores, so the parameter must be in the range 0 ≤ n ≤ 9.
The protocol for communicating between the host and the root puts the root in charge; the host is usually passive and waits to be told what to do. During normal operation, the root sends a service request and then waits for a reply. signal_host_sema allows the host to break into this sequence and interrupt the root, making it signal one of the host semaphores. Threads in the root can wait for these semaphores using host_sema_wait and deal with the asynchronous event, rather than having to ask the host repeatedly if the event has occurred.
For example, you may wish to be able to ask a running application to display some status information. This can be done by having a thread on the root that waits on a host semaphore. When the semaphore is signalled, the thread can print out the required information and then wait for the semaphore to be signalled again.
Note that this function only signals a semaphore and does not transfer any data; all data transfers must be started by the root.
|
|
signal_host_mask
void Present::signal_host_mask(unsigned int m);
|
|
Call signal_host_sema for each bit set in a bitmask. The function takes a bitmask, m, and calls Present::signal_host_sema(n) for each bit (1<<n) set in the mask. So, signal_host_mask(5) calls Present::signal_host_sema(0) and Present::signal_host_sema(2). As there are only 10 host events, all bits in the mask except the least-significant 10 must be 0.
|
|
push
void Present::push(void);
|
|
Transmit the data buffer to the root CPU. This function must always be called before the server returns to read in the next command word. This is usually not needed inside clusters as the server automatically calls push after sending the result of the service as the final 'put'. You only need an explicit push if you are setting NoReply. Refer to the service loop.
|
|
|