/* * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * Use is subject to license terms. */ #pragma ident "@(#)pcp_app_prog_if.txt 1.2 06/08/07 SMI" ++++++++++++++++++++++++++++++++++++++++++++++ + + + Ontaio and Erie + + PCP Application Programming Interfaces + + + ++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + Revision History: + + + + Version Author Date Comments + + 1.1 Venu M. 04/18/06 Initial version + + 1.2 Venu M. 08/07/06 Updated document + + + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1.0 Introduction This document describes the application programming interfaces and various data structures and defines for Ontario and Erie platform specific applications - SunVTS, SunMC, Explorer & Picl Plugin - to communicate with System Controller (ALOM) over platform virtual channels. Solaris PCP user apps use 'libpcp' library interfaces to send/receive messages with SC. Refer to libpcp specification document for detailed information on using libpcp library interfaces (PSARC 2005/372). 2.0 PCP Message format Solaris PCP user apps and SC use following main data structure to exchange messages. typedef struct pcp_msg { uint8_t msg_type; uint8_t sub_type; uint16_t rsvd_pad; uint32_t msg_len; void *msg_data; } pcp_msg_t; In the "pcp_msg_t" data structure, 'msg_type' and 'sub_type' signify the type of message being sent, 'msg_len' signifies the lengh of the 'msg_data' and 'msg_data' points to a data buffer that contains the message data. In PCP app programming model, typically, Solaris user apps send a request message (in 'pcp_msg_t' format by using libpcp pcp_send_recv() interface) to SC and receive a response message in 'pcp_msg_t' format. The 'msg_type' and 'sub_type' fields are application specific information. Based on 'msg_type' and 'sub_type' fields, Solaris PCP apps and SC tasks take appropriate actions. To avoid accidentally one application sending its message to SC over a different application's virtual channel, in the current implementation, 'msg_type's are chosen such that they are unique across all PCP apps. 'sub_type's are NOT chosen to be unique across PCP apps. After receiving messages, user apps (and SC tasks) should check msg_type/sub_type fields to make sure that the message it received is correct message destined to them. 3.0 Application Specific Data Structures and Defines 3.1 SunVTS Host <-> SC Loopback Test Interfaces SunVTS Loopback Test Messages : ++++++++++++++++++++++++++++++ SunVTS loopback test sends request message of PCP_HSCLB_TEST type to SC for sending loopback packet. The request message data is in "pcp_hsclb_req_t" format. The response message of PCP_HSCLB_TEST_R type is returned with the response message data in "pcp_hsclb_resp_t" format. Data Strucrures and Defines: ++++++++++++++++++++++++++++ /* Message Types */ #define PCP_HSCLB_TEST (1) #define PCP_HSCLB_TEST_R (2) /* Sub Types - None */ /* Request Message Data Format */ typedef struct pcp_hsclb_req { uint32_t pkt_size; /* followed by packet data (uint8_t []) */ } pcp_hsclb_req_t; /* Response Message Data Format */ typedef struct pcp_hsclb_resp { uint32_t status; uint32_t pkt_size; /* followed by packet data (uint8_t []) */ } pcp_hsclb_resp_t; The 'status' field can contain one of the following possible values: #define PCP_HSCLB_OK (1) #define PCP_HSCLB_ERROR (2) 3.2 Explorer (aka. 'snapshot' ) Interfaces The Explorer application sends request message of different types mentioned below to get various information (i.e sc command output) from SC. In all request messages, the message type is set to PCP_SNAPSHOT and sub type is set to an appropriate type depending on which SC command output is required. The msg_len and msg_data fields are set to zero/NULL respectively as these fields are not used. The response message contains message type of PCP_SNAPSHOT_R and the the sub type contains an appropriate type dependinng on which SC command output is requested. For example, PCP_SNAPHOT/PCP_SNAPSHOT_SHOWDATE types (msg_type/sub_type) are sent in request message for requesting 'showdate' SC command output. The response message contains PCP_SNAPSHOT_R/PCP_SNAPSHOT_SHOWDATE_R (msg_type/sub_type) types and the msg_data points to a buffer containing the 'showdate' sc command output. Data Structures and Defines: ++++++++++++++++++++++++++++ /* Message Types */ #define PCP_SNAPSHOT (11) #define PCP_SNAPSHOT_R (12) /* Sub Types */ // To rertieve 'showdate' output #define PCP_SNAPSHOT_SHOWDATE (1) #define PCP_SNAPSHOT_SHOWDATE_R (2) // To retrieve 'showsc' output #define PCP_SNAPSHOT_SHOWSC (3) #define PCP_SNAPSHOT_SHOWSC_R (4) // To retrieve 'showsc version' output #define PCP_SNAPSHOT_SHOWSC_VER (5) #define PCP_SNAPSHOT_SHOWSC_VER_R (6) // To retrieve 'showenvironment' output #define PCP_SNAPSHOT_SHOWENV (7) #define PCP_SNAPSHOT_SHOWENV_R (8) // To retrieve 'showfaults -v' output #define PCP_SNAPSHOT_SHOWFAULTS_V (9) #define PCP_SNAPSHOT_SHOWFAULTS_V_R (10) // To retrieve 'showfru' output #define PCP_SNAPSHOT_SHOWFRU (11) #define PCP_SNAPSHOT_SHOWFRU_R (12) // To retrieve 'showplatform -v' output #define PCP_SNAPSHOT_SHOWPLATFORM_V (13) #define PCP_SNAPSHOT_SHOWPLATFORM_V_R (14) // To retieve 'shownetwork' output #define PCP_SNAPSHOT_SHOWNETWORK (15) #define PCP_SNAPSHOT_SHOWNETWORK_R (16) // To retrieve 'showusers' output #define PCP_SNAPSHOT_SHOWUSERS (17) #define PCP_SNAPSHOT_SHOWUSERS_R (18) // To retrieve 'showlogs -v -g 0 -p p' output #define PCP_SNAPSHOT_SHOWLOGS_V (19) #define PCP_SNAPSHOT_SHOWLOGS_V_R (20) // To retrieve 'showkeyswitch' output #define PCP_SNAPSHOT_SHOWKEYSWITCH (21) #define PCP_SNAPSHOT_SHOWKEYSWITCH_R (22) // To retrieve 'showcomponent' output #define PCP_SNAPSHOT_SHOWCOMPONENT (23) #define PCP_SNAPSHOT_SHOWCOMPONENT_R (24) // To retrieve 'showhost' output #define PCP_SNAPSHOT_SHOWHOST (25) #define PCP_SNAPSHOT_SHOWHOST_R (26) // To retrieve 'consolehistory -v' output #define PCP_SNAPSHOT_CONSOLEHISTORY_V (27) #define PCP_SNAPSHOT_CONSOLEHISTORY_V_R (28) /* Request Message Data Format - NOT USED */ // msg_len/msg_data should be set 0/NULL /* Response Message Data Format */ typedef struct pcp_snapshot_hdr { uint32_t status; uint32_t size; /* followed by snapshot data (char *) of 'size' bytes */ } pcp_snapshot_hdr_t; The 'status' field can contain one of the following possible values: #define PCP_SNAPSHOT_OK 1 #define PCP_SNAPSHOT_ERROR 2 Note: The user application should check for 'status' field to see if the SC returned successful response message or not. If the 'status' field shows an error means SC encountered an error while acting on the request message (this could be due to many reasons, such as, the request message contains an invalid type/data or SC encountered some internal error etc..). If the status field shows success only, the response message contains complete data that user application is expecting. 3.3 Solaris Picl Plugin Interfaces Solaris Picl plugin uses following message types and data structures to enable/disable hard drive service LEDs (blue led). /* Message Types */ #define PCP_SBL_CONTROL 3 #define PCP_SBL_CONTROL_R 4 /* Sub Type - NOT USED */ /* Request Message Data Format */ typedef struct pcp_sbl_req { uint32_t sbl_id; uint32_t sbl_action; } pcp_sbl_req_t; The 'sbl_id' field can contain one of the possible values: #define PCP_SBL_HDD0 0 #define PCP_SBL_HDD1 1 #define PCP_SBL_HDD2 2 #define PCP_SBL_HDD3 3 The 'sbl_action' can contain one of the possible values: #define PCP_SBL_ENABLE 1 #define PCP_SBL_DISABLE 2 /* Response Message Data Format */ typedef struct pcp_sbl_resp { uint32_t status; uint32_t sbl_id; uint32_t sbl_state; } pcp_sbl_resp_t; The 'status' field can contain one of the following possible values: #define PCP_SBL_OK (1) #define PCP_SBL_ERROR (2) The 'sbl_state' can contain one of the following possible values: /* sbl_state */ #define SBL_STATE_ON 1 #define SBL_STATE_OFF 2 #define SBL_STATE_UNKNOWN 3 For example, to enable hard drive 0 service led, picl plugin sends a request message with PCP_SBL_CONTROL type (msg_type) and message data points to a buffer (in pcp_sbl_req_t format) containing 'sbl_id' as PCP_SBL_HDD0 and 'sbl-action' as PCP_SBL_ENABLE . The response message contains of type PCP_SBL_CONTROL_R and the respone message data points to a buffer (in pcp_sbl_resp_t format) with appropriate values.