Chapter 3. Communicating with the Administrator

The Direct-Link device administrator is an OS task, sdadmin, which allows several tasks to communicate with other devices on the Data Highway or Data Highway Plus network. Communication between application tasks and sdadmin is performed with messages according to message formats defined in the file sdmsgs.h.

A client task may determine the task id of sdadmin by querying the name server on the node on which sdadmin is running. By default, the name sdadmin is registered by the administrator with the name server. There is a command-line option which can tell sdadmin to register a different name, if necessary. In a QNX 4 network, client tasks on any network node may send requests to the administrator because of the virtual circuit capability of QNX. If a task knows on which node sdadmin is running, it can use the library function name_locate to find it and prepare to send messages to it.

Each message transaction consists of a request message and a response message. The request is sent to sdadmin by means of the send function and the response is returned by sdadmin by means of the reply function.

The type of the request is defined by the first byte of the message. It must contain one of the values which are defined in sdmsgs.h as SD_READ, SD_WRITE, etc. The format of the rest of the message is determined by this type. There is a structure defined in sdmsgs.h for each request type. For example, a request of type SD_READ has the format of the C structure SDREAD.

.
#define SD_READ 16
.
.
typedef struct SDREAD
{
 sd_common common; /* Common to all requests */
 int handle;
 int wait;
} sd_read;

For each request type, there is a corresponding response message structure. The response structure has the same name as the request structure, except that the letter r is inserted after the sd_ prefix. For example, the response message for an SD_READ request is a message of type sd_r_read.

typedef struct SDRREAD
{
 sd_r_common common;
 unsigned char len;
 unsigned char dst;
 unsigned char src;
 unsigned char cmd;
 unsigned char sts;
 unsigned char tns_lsb;
 unsigned char tns_msb;
 unsigned char data[ MAX_DH_MSG_LEN - 6 ];
} sd_r_read;

Each request begins with a common structure which contains two fields: the type of the request to which sdadmin is responding and the card number to which the request refers. Each response also begins with a common structure which contains two fields: the type of response and a result code. The response type should match the request type and the result code indicates the success or failure of the requested operation and gives a reason for a failed operation. The result code contains one of the values defined as SD_R_OK, SD_R_WRITE_FAILED, etc. If the request type field contains a value not defined in sdmsgs.h, the result code SD_R_UNKNOWN_REQUEST is returned in the response.

typedef struct SDCOMMON
{
 char type;
 char card_num;
} sd_common;

typedef struct SDRCOMMON
{
 char type;
 char result_code;
} sd_r_common;

The following sections describe how and when to use each request type and how to interpret the responses. The requests can be categorized into four classes: administrator control, card control, access control and Data Highway access.

3.1. Administrator Control

There are two messages in this category: SD_SHUTDOWN and SD_DEBUG_FLAGS. For these requests, the card_num field within the sd_common structure is not used, but it is checked to ensure that it is valid.

3.1.1. SD_SHUTDOWN

The SD_SHUTDOWN request tells sdadmin to terminate. The administrator then releases any system resources, replies SD_R_OK to the requesting task and terminates. The Direct-Link cards are reset to remove them from the Data Highway network. If card_num is not between 0 and 7, SD_SHUTDOWN returns SD_R_BAD_PARM.

3.1.2. SD_DEBUG_FLAGS

The sdadmin task can optionally generate trace information which is useful in debugging its operation. This option was incorporated to facilitate debugging the sdadmin task itself and should be of little interest to application programmers. It is documented here for completeness.

For most efficient operation, the debug flags should be zero.

Each bit of the debug flags word corresponds to a class of trace output messages. When a bit is on, trace messages of that type are written (appended) to the trace device or file. These bits are not mutually exclusive; any or all of the bits may be set at once.

The device or file to which the trace output is written is given in the dev_name field. If it is the null string (""), the output is written to the standard output of sdadmin.

The SD_D_MSG_RCV bit (bit 0) enables tracing of receipt of messages from OS tasks. The request type and task id are printed.

The SD_D_TASK_DEATH bit (bit 1) enables tracing of task death messages received by sdadmin. Such a message is received whenever a task terminates. The task id of the dead task is printed.

The SD_D_GEN_ERRS bit (bit 2) enables the output of general error messages from the administrator. These are usually errors in interacting with the peer processor on the Direct-Link card.

The SD_D_INFO bit (bit 3) enables the output of general information related to service requests.

The SD_D_INTS bit (bit 4) controls the printing of messages which trace the processing caused by interrupts from the Direct-Link cards.

The result code of the sd_r_debug_flags response should be SD_R_OK. If card_num is not between 0 and 7, SD_DEBUG_FLAGS returns SD_R_BAD_PARM.