/* * Copyright 2005 Sun Microsystems, Inc. All rights reserved. * Use is subject to license terms. */ #pragma ident "@(#)ontario_pcp_spec.txt 1.5 05/06/17 SMI" /***************************************************** * * Platform Channel Protocol (PCP) Specification * * PSARC CASE : 2005/372 | * ******************************************************/ 1. Introduction. This document explains in detail about the platform channel protocol (PCP) used by Host and ALOM tasks to communicate over platform channels on Ontario/Erie platforms. | | 2. Platform Channel Protocol Format To initiate messages on platform channels, the sender first sends the platform channel message header to the receiver. The message header is sent in network byte order. The message header always starts with a magic number, which will be same for all types messages on platform channels, to avoid message framing errors. /* * magic number for Platform Channel Protocol (PCP) * ~(rot13("PCP_") = 0xAFBCAFA0 * rot13 is a simple Caesar-cypher encryption that replaces each English * letter with the one 13 places forward or back along the alphabet. */ #define PLAT_CHNL_PROT_MAGIC_NUM (0xAFBCAFA0) The magic number is followed by protocol version. The protocol version field can be used for compatabiity of future protocol format changes. #define PLAT_CHNL_PROT_VER_1 1 Based on the message type ('msg_type') the message data is interpreted differently. The 'msg_type' and 'sub_type' fields are provided by user applications. /* * Platform Channel Request Message Header. */ typedef struct pcp_req_msg_hdr { uint32_t magic_num; /* magic number */ uint8_t proto_ver; /* version info for */ /* backward compatibility */ uint8_t msg_type; /* provided by user apps */ uint8_t sub_type; /* provided by user apps */ uint8_t rsvd_pad; /* padding bits */ uint32_t xid; /* transaction id */ uint32_t timeout; /* timeout in seconds */ uint32_t msg_len; /* length of request or response data */ uint16_t msg_cksum; /* 16-bit checksum of req msg data */ uint16_t hdr_cksum; /* 16-bit checksum of req hdr */ } pcp_req_msg_hdr_t; /* * Platform Channel Response Message Header. */ typedef struct pcp_resp_msg_hdr { uint32_t magic_num; /* magic number */ uint8_t proto_ver; /* version info for */ /* backward compatibility */ uint8_t msg_type; /* passed to user apps */ uint8_t sub_type; /* passed to user apps */ uint8_t rsvd_pad; /* for padding */ uint32_t xid; /* transaction id */ uint32_t timeout; /* timeout in seconds */ uint32_t msg_len; /* length of request or response data */ uint32_t status; /* response status */ uint16_t msg_cksum; /* 16-bit checksum of resp msg data */ uint16_t hdr_cksum; /* 16-bit checksum of resp hdr */ } pcp_resp_msg_hdr_t; The transaction id (xid) field is used to match the request and response messages. The timeout value indicates to the receiver the time in seconds the sender expects the response. (-1) indicates no response is wanted; (0) indicates | a willingness to wait forever. | #define PCP_TO_NO_RESPONSE (-1) #define PCP_TO_WAIT_FOREVER (0) The message length (msg_len) field tells the length of message data. The header and message checksum values (msg_cksum & hdr_cksum) are used for data integrity of message header and data. The receiver after receiving the message header waits until it gets 'msg_len' bytes before interpreting the message data. The status field in the message header is used in the response message to communicate following generic errors to the message sender. #define PCP_OK (0) /* message received okay */ #define PCP_ERROR (1) /* generic error */ #define PCP_HDR_CKSUM_ERROR (2) /* header checksum error */ #define PCP_MSG_CKSUM_ERROR (3) /* message checksum error */ #define PCP_XPORT_ERROR (4) /* message in complete error */ After sending the message header, the sender sends the message data. The sender waits for the response message, if it is expecting for a response. The message data, supplied by the user applications is assumed tobe already in some known byte order (network byte or XDR or ???). 3. Platform Channel Protocol Library interfaces. 3.1. Guidelines for communicate with Service Controller using libpcp | interfaces via virtual channels on Ontario platform. | a) If any Solaris consumer wants to use libpcp interfaces, first it | needs to have a private contract with libpcp. | libpcp ARC case: 2005/372 | libpcp contract netadmin alias: contract-2005-372@sun.com | b) For communicating from Host to Service Controller (SC) using virtual | channels on Ontario, glvc/hypervisor (FWARC/2005/173) needs to create | a seperate virtual channel for every channel consumer. This information | needs to be added to platform specific Partition Descriptor (PD) which | resides in System firmware. Based on PD, glvc/hypervisor creates virtual | channel device nodes under /devices/virtual-devices@xxx directory in | Ontario platform. libpcp consumers provides this virtual channel device | node to libpcp initialization routine (pcp_init()). | c) For proper message exchange between Solaris applications (i.e libpcp | consumers) and Service Controller via platform virtual channels, libpcp | consumers and Service Controller side needs to define and implement | appropriate support for following information. | - 'msg_type' and 'sub_type' fields in request and response message | headers. | - message data format for request and response messages. | (i.e 'msg_data' field in pcp_msg_t struct) | - support for implementing functionality based on libpcp consumer specific | requirements. This support needs to be implemented in both libpcp | consumer side on Solaris and in Service Controller firmware. | Note: libpcp does not define or interpret 'msg_type', 'sub_type' or | message data format fields. | d) It's libpcp consumer's responsibility to make sure that they are | running on appropriate Platform with appropriate Service Controller | firmware to communicate on virtual channels using libpcp interfaces. | 3.2. Interface Table | ------------------------------------------------------------ Name Stability comments ------------------------------------------------------------ struct pcp_msg_t project private - function pcp_init() project private - function pcp_send_recv project private - function pcp_close project private - ------------------------------------------------------------ 3.3. Interfaces Description. | The host (solaris) applications provide message in the following format to Platform Channel Host Library for sending to the receiver (i.e Service processor ). struct pcp_msg { uint8_t msg_type; uint8_t sub_type; uint32_t msg_len; void *msg_data; } pcp_msg_t; The host library copies the 'msg_type', 'sub_type' and 'msg_len' fields into the platform channel message header. The format of 'msg_data' is to be defined for every application seperately. Every application will have a different format for 'msg_data' in request message and for 'msg_data' in response message. Platform Channel Host Interface Library provides following interfaces to host applications for communication on platform channels: a). The host applications first call "pcp_init()" with complete channel device path name as an argument to initialize the specific platform channel. The actual device path names for each platform channel to be defined. (TBD). The platform channel device pathnames will be defined in the host library header file. /* * Function: Initialize Platform Channel connection. * * Arguments: * * char *channel_dev_path - Complete device path of platform channel. * * Return: * * 0 - Platform channel initialization success. * (-ve) - Platform channel initialization failure. * * Different return values: * * PCPL_INVALID_ARGS - invalid args. * PCPL_GLVC_ERROR - glvc driver error. * PCPL_ERROR - for other libpcp internal errors. * */ int pcp_init(char *channel_dev_path); b). The host applications shall call "pcp_close()" after the communication on platform channel is done. This is just a cleanup routine. /* * Function: Close Platform Channel connection. * * Arguments: None * * Return: * * 0 - Success * -1 - Failure */ int pcp_close(void); c). The host applications shall call "pcp_send_recv()" for sending and receiving messages on platform channels. The host applications shall supply the pointer to the 'resp_msg'. The host library will create memory for the 'msg_data' buffer in response msg and the host applications are expected to free this msg_data buffer in response msg. The timeout value signifies the time in seconds the host application expects a response message. If the host applications are not interested in response message the timeout value can be set to PCP_TO_NO_RESPONE. /* * Function: Send Request message and Receive response message on platform * channel. * * Arguments: * * pcp_msg_t *req_msg - Pointer to Request message * pcp_msg_t *resp_msg - Pointer to Response message. * uint32_t timeout - timeout value in seconds. * * Return: * ( 0 ) - Success * ( -ve ) - Host library returns any of the generic errors defined above * for pcp_send_recv failures. * * Different return values: * * * PCPL_INVALID_ARGS - invalid args. * PCPL_GLVC_TIMEOUT - glvc call timeout. * PCPL_XPORT_ERROR - transport error in request message * noticed by receiver. * PCPL_MALLOC_FAIL - malloc failure. * PCPL_CKSUM_ERROR - checksum error. */ int pcp_send_recv(pcp_msg_t *req_msg, pcp_msg_t *resp_msg, uint32_t timeout); Note: see "usr/src/lib/libpcp/common/libpcp.h" more libpcp api return codes. 4. 'libpcp' interface usage by user application. libpcp api is available to user applications as a shared library (libpcp.so). The libpcp.so library will reside under "/usr/platform/`uname -i`/lib/" directory on Ontario and Erie platforms. libpcp user applications should follow following sequence of steps to exchange messages with SC on Ontario and Erie platforms. a). Call pcp_init() with appropriate application specific channel device path. Note: Refer platform specific PD (partition descriptor) about different channels. glvc driver creates channels device nodes under /devices/virtual-devices@100/ directory on Ontario platform. b). If pcp_init() fails (i.e return value < 0 ), the libpcp user application can not proceed further in using libpcp api to communicate with SC. At this point, the user application may want log an error and exit in using libpcp api. c). Call pcp_send_recv() with appropriate arguments for sending/receiving messages. d). If pcp_send_recv() fails either repeat step 'c' or goto step 'g'. e). If pcp_send_recv is successful, free the response message data memory. libpcp allocates memory for the response message data. Applications should free the memory using free() call. (i.e "free(resp_msg->msg_data") ) f). To exchange more messages with SC, goto step 'c', or if message exchange with SC is done goto step 'g'. g). Call pcp_close(). h). Message exchange with SC is completed. 5. Platform Channl Communication Block Diagram on Ontario platform. See Figure 1 for current libpcp interface users and complete communication path from libpcp user apps to Service processor. ________ | SunVTS | | ALOM |____ _______ | Task | | | |___ |________| | |SunVTS | | . _________ | |_______| | . | SunMC | | | . | ALOM | | | ________ . | Task |__ | ________ |____| | . |________| | | | | | | . _________ | | | SunMC |______| | . | |__| | |________| | | _______ . _________ ______ | Data |____| |libpcp | | | . | | | | | Socket |____ __________ | |__| Glvc |_.__| Hyper- |__| VBSC |___| Monitor|__ | | |____| | |_______| . | -Visor | |______| |________| | | | Explorer | | | . |_________| | | |__________| __| | . __________ | | | |_______| . | Explorer | | | __________ | . | ALOM |__| | | | | . | Task | | | Picl |__| . |__________| | | Plugin | . | |__________| . _________ | . | Picl | | . | Plugin |_____| . | Task | . |_________| . <-- Libpcp ---><---- Solaris ------->. <-System FW -><------ SC firmware -----> Users. Figure 1 : libpcp user apps <-> Service Processor communication mechanism over platform channels.