SPI Programming Manual (G06.24+, H06.03+, J06.03+)

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-28
Defining Objects
13. The size of a response message should not grow larger than the smallest size ever
given as the recommended buffer size.
When an interface is first designed, the recommended buffer size should factor in an
estimate of how much the response is likely to grow in the future. Allow a generous
amount, but keep the buffer size within reason. The recommended buffer size can be
changed in later RVUs, but such a change does not increase the size of the buffer in
programs that were compiled before the change; it is desirable that those programs
continue to run.
A server can always return its current version of the response as long as that response
(in single response mode) fits in the smallest buffer size that ever was recommended
for the interface. If a response grows too large to fit into an earlier recommended buffer
size, then, at least for requesters using an earlier buffer size, the server should check
the version in the subsystem ID supplied in the command and return a version of the
response that fits in and is compatible with the buffer. The response does not need to
be exactly what the earlier version of the server returned—the response need only fit in
the requester’s buffer and contain at least all the items that were defined in the earlier
version. The server need do this only for single-response mode or if the first response
does not fit in the buffer in multiple-response mode.
Suppose the requester’s version is 11, the server’s version is 12, and the
recommended buffer size at version 11 is too small to hold some of the version 12
responses. If the version 12 server has to send one of those longer responses to a
version 11 requester and the requester’s buffer happens to be long enough (it declared
a buffer longer than the recommended size), the server can return the version 12
response. If the buffer happens not to be long enough, the version 12 server should
return a response that is cut back to fit in the size available. The response does not
need to be exactly what version 11 of the server returned—the response version 12 of
the server returns to a requester of version 11 need only fit in the requester’s buffer
and contain at least all the items that were defined in version 11 of the server.
If desired, your server can do more in the way of adjusting responses to the version of
the requester.
Defining Objects
To determine the kinds of n objects to be defined for the programmatic interface, start
with the set of object types it would make sense to present to a user of a human
command interface for the subsystem. For each of these object types, list the attributes
needed to define an object of that type.
If an object type has attributes that can be repeated indefinitely, that can cause trouble.
For one thing, SPI commands must have some definite upper limit on their size. Two
simple ways to avoid problems in this case are:
•
Impose an upper limit on the number of repetitions of the attributes. This approach
has its place, but often is not suitable.