Sun Microsystems Netra CP2500 User Manual

Netra™CP2500 Board

Programming Guide

For the Solaris™Operating System

Sun Microsystems, Inc. www.sun.com

Part No. 819-1749-11 March 2007, Revision A

Submit comments about this document at: http://www.sun.com/hwdocs/feedback

Copyright 2007Sun Microsystems,Inc., 4150Network Circle, SantaClara, California95054, U.S.A.All rightsreserved. Sun Microsystems,Inc. hasintellectual property rightsrelating totechnology thatis describedin thisdocument. Inparticular, andwithout

limitation, theseintellectual propertyrights mayinclude oneor more ofthe U.S.patents listedat http://www.sun.com/patentsand oneor more additionalpatents orpending patentapplications inthe U.S.and inother countries.

This documentand theproduct towhich itpertains are distributedunder licensesrestricting theiruse, copying,distribution, and decompilation. Nopart ofthe productor ofthis documentmay bereproducedin anyform byany meanswithout priorwritten authorizationof Sun andits licensors,if any.

Third-party software, includingfont technology,is copyrightedand licensedfrom Sun suppliers. Parts ofthe productmay bederived from BerkeleyBSD systems,licensed fromthe Universityof California.UNIX isa registered trademarkin

the U.S.and inother countries,exclusively licensedthrough X/OpenCompany, Ltd. Sun, Sun Microsystems,the Sunlogo, AnswerBook2,docs.sun.com, Netra,OpenBoot, andSolaris are trademarksor registered trademarksof

Sun Microsystems,Inc. inthe U.S.and inother countries. All SPARCtrademarks areused underlicense andare trademarks or registered trademarksof SPARCInternational, Inc.in theU.S. andin other

countries. Productsbearing SPARCtrademarks are basedupon anarchitecture developed by Sun Microsystems,Inc. The OPENLOOK andSun™ GraphicalUser Interfacewas developedby SunMicrosystems, Inc.for itsusers andlicensees. Sun acknowledges

the pioneeringefforts ofXerox in researchingand developingthe conceptof visualor graphicaluser interfacesfor thecomputer industry.Sun holds anon-exclusive licensefrom Xerox tothe XeroxGraphical UserInterface, whichlicense alsocovers Sun’slicensees whoimplement OPEN LOOK GUIsand otherwisecomply withSun’s writtenlicense agreements.

U.S. GovernmentRights—Commercial use.Government usersare subject to the Sun Microsystems, Inc.standard licenseagreement and applicable provisionsof theFAR andits supplements.

DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANYIMPLIED WARRANTY OFMERCHANTABILITY, FITNESSFOR A PARTICULAR PURPOSEOR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2007Sun Microsystems,Inc., 4150Network Circle, SantaClara, Californie95054, Etats-Unis.Tous droitsréservés. Sun Microsystems,Inc. ales droits depropriété intellectuelsrelatants à la technologie qui est décritdans ce document. Enparticulier,et sansla

limitation, cesdroits depropriété intellectuels peuvent inclure unou plusdes brevetsaméricains énumérésà http://www.sun.com/patents et un oules brevetsplus supplémentaires oules applicationsde breveten attentedans lesEtats-Unis etdans lesautrespays.

Ce produitou documentest protégé parun copyrightet distribuéavec deslicences quien restreignent l’utilisation,la copie,la distribution,et la décompilation. Aucunepartie dece produitou documentne peutêtre reproduite sousaucune forme,par quelquemoyen quece soit,sans l’autorisation préalableet écritede Sunet deses bailleursde licence,s’il yena.

Le logicieldétenu pardes tiers,et quicomprend latechnologie relative auxpolices decaractères, estprotégépar uncopyright etlicencié pardes fournisseurs deSun.

Des partiesde ceproduit pourront êtredérivées dessystèmes BerkeleyBSD licenciéspar l’Universitéde Californie.UNIX estune marque déposée auxEtats-Unis etdans d’autrespays etlicenciée exclusivementpar X/OpenCompany, Ltd.

Sun, SunMicrosystems, lelogo Sun,AnswerBook2, docs.sun.com,Netra, OpenBoot,et Solarissont desmarquesde fabrique ou desmarques déposées deSun Microsystems,Inc. auxEtats-Unis etdans d’autres pays.

Toutes lesmarques SPARC sont utilisées sous licence et sont des marques defabrique oudes marquesdéposées deSPARC International,Inc. aux Etats-Uniset dansd’autres pays.Les produits portantles marquesSPARC sont baséssur unearchitecture développéepar Sun Microsystems, Inc.

L’interfaced’utilisation graphiqueOPEN LOOKet Sun™a étédéveloppée parSun Microsystems, Inc.pour sesutilisateurs etlicenciés. Sun reconnaît lesefforts de pionniers de Xeroxpour larecherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industriede l’informatique.Sun détientune licensenon exclusivede Xeroxsur l’interfaced’utilisation graphiqueXerox,cette licence couvrant égalementles licenciéesde Sunqui mettenten placel’interface d’utilisation graphiqueOPEN LOOKet quien outrese conforment aux licencesécrites deSun.

LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENTEXCLUES, DANSLA MESUREAUTORISEE PARLA LOIAPPLICABLE, YCOMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE UTILISATION PARTICULIERE OU A L’ABSENCE DE CONTREFAÇON.

Preface xi

1. Watchdog Timer 1

Overview 1

PICL Plug-In Module 2

Watchdog Node Management Code 5

OpenBoot PROM Interface 21

2. Environmental Monitoring 23

Environmental Monitoring Component Compatibility 24

Typical Environmental Monitoring System Application 24

Typical Cycle From Power Up to Shutdown 26

Environmental Monitoring Protection at the OpenBoot PROM 26

Environmental Monitoring Protection at the Operating System Level 26

Post Shutdown Recovery 27

Hardware Environmental Monitoring Functions 28

Switching Power On and Off 31

Inlet, Exhaust, and CPU Temperature Monitoring 31

Adjusting the Environmental Monitoring Warning, Critical, and Shutdown

Parameter Settings on the Board 32

OpenBoot PROM Environmental Monitoring 33

iii

Warning Temperature Response at OpenBoot PROM 33

Critical Temperature Response at OpenBoot PROM 33

Using the show-sensors Command at the OpenBoot PROM 34

Environmental Monitoring Application Programming 34

Reading Temperature Sensor States Using the PICL API 35

Using a Configuration File for Sensor Information 36

Solaris Driver Interface 36

Sample Application Program 37

Reading the CPU Temperature and Environmental Limits 41

3. User Flash 43

User Flash Usage and Implementation 43

User Flash Driver 44

OpenBoot PROM Device Tree and Properties 44

User Flash Device Files 45

Interface (Header) File 45

Application Programming Interface 45

Structures to Use in IOCTL Arguments 46

PROM Information Structure 46

User Flash User Interface Structure 47

Errors 47

Example Programs 47

Read Example Program 48

Write Example Program 49

Block Erase Example Program 51

Sample User Flash Application Program 53

Index 59

iv Netra CP2500 Board Programming Guide • March 2007

Figures

FIGURE 2-1 Typical Environmental Monitoring Application Block Diagram 25

FIGURE 2-2 Location of Environmental Monitoring Hardware on the Netra CP2500 Board – Top Side 29

FIGURE 2-3 Netra CP2500 Board Environmental Monitoring Functional Block Diagram 30

vi Netra CP2500 Board Programming Guide • March 2007

Tables

TABLE 1-1 Watchdog Plug-In Interfaces for Netra CP2500 Board Software 3

TABLE 1-2 Properties Under watchdog-controller Node 3

TABLE 1-3 Properties Under watchdog-timer Node 4

TABLE 2-1 Compatible Environmental Monitoring Components 24

TABLE 2-2 Typical Netra CP2500 Board Hardware Environmental Monitoring Functions 28

TABLE 2-3 I2C Components 28

TABLE 2-4 PICL Temperature Sensor Class Node Properties 35

TABLE 2-5 Description of Values Displayed by Solaris Commands 42

TABLE 3-1 User Flash Node Properties 44

TABLE 3-2 System Calls 45

vii

viii Netra CP2500 Board Programming Guide • March 2007

Code Samples

CODE EXAMPLE 1-1 System Watchdog Node Management Code Example 5

CODE EXAMPLE 2-1 Sample envmond Application Program 37

CODE EXAMPLE 3-1 PROM Information Structure 46

CODE EXAMPLE 3-2 User Flash Interface Structure 47

CODE EXAMPLE 3-3 Read Action on User Flash Device 48

CODE EXAMPLE 3-4 Write Action on User Flash Device 49

CODE EXAMPLE 3-5 Block Erase Action on User Flash Device 51

CODE EXAMPLE 3-6 Sample User Flash Application Program 53

x Netra CP2500 Board Programming Guide • March 2007

Preface

The Netra CP2500 Board Programming Guide is written for program developers and users who want to program the Netra equipment manufacturer (OEM) systems, supply additional capability to an existing compatible system, or work in a laboratory environment for experimental purposes. You are required to have a basic knowledge of computers and digital logic programming to fully use the information in this document.

The Netra CP2500 can be used by network equipment providers (NEPs) and carriers to scale and improve the availability of next-generation, carrier-grade systems. The Netra CP2500 functions as a node board in a cPSB system rack or as a CPU board in the Netra CT 810 or 410 cPCI server.

™

CP2500 board in order to design original

How This Book Is Organized

Chapter 1 provides details on the Netra CP2500 watchdog timer driver and its

operation.

Chapter 2 describes the specific environmental monitoring functions of the Netra

CP2500.

Chapter 3 describes the user flash driver for the Netra CP2500 on-board flash

PROMs and how to use it.

Using UNIX Commands

This document may not contain information on basic UNIX®commands and procedures such as shutting down the system, booting the system, and configuring devices.

See one or more of the following for this information:

■ Solaris Handbook for Sun Peripherals

■ Solaris

™

Operating System (Solaris OS) documentation, which is at:

http://docs.sun.com

■ Other software documentation that you received with your system

Typographic Conventions

Typeface

AaBbCc123 The names of commands, files,

AaBbCc123 What you type, when contrasted

AaBbCc123 Book titles, new words or terms,

* The settings on your browser might differ from these settings.

Meaning Examples

Edit your.login file. and directories; on-screen computer output

with on-screen computer output

words to be emphasized. Replace command-line variables with real names or values.

Use ls -a to list all files.

% You have mail.

Password:

Read Chapter 6 in the User’s Guide.

These are called class options.

Yo u must be superuser to do this.

To delete a file, type rm filename.

xii Netra CP2500 Board Programming Guide • March 2007

Shell Prompts

Shell Prompt

C shell machine-name%

C shell superuser machine-name#

Bourne shell and Korn shell $

Bourne shell and Korn shell superuser #

Watchdog Timer

The system management controller (SMC) on the Netra CP2500 implements a watchdog service that captures catastrophic faults in the Solaris OS running on the CPU board. The watchdog service reports such faults to the baseboard management controller (BMC) by means of either an IPMI message or by a de-assertion of the CPU’s HEALTHY# signal.

This chapter contains the following sections:

■ “Overview” on page 1

■ “PICL Plug-In Module” on page 2

■ “Watchdog Node Management Code” on page 5

■ “OpenBoot PROM Interface” on page 21

Overview

The Netra CP2500 SMC provides two watchdog timers: the watchdog level 2 (WD2) timer and the watchdog level 1 (WD1) timer. Management applications (for example, the Managed Object Hierarchy on the Netra CT 810/410 server or a third-party application on a cPSB server) start the timers, and the Solaris OS periodically pats the timers before they expire. If the WD2 timer expires, the watchdog function of the WD2 timer forces the SPARC WD2 is 255 seconds.

The WD1 timer is typically set to a shorter interval than the WD2 timer. Management applications can examine the expiration status of the WD1 timer to get advance warning if the main timer, WD2, is about to expire. The management application has to start WD1 before it can start WD2. If WD1 expires, then WD2 starts only if enabled. The maximum range for WD1 is 6553.5 seconds.

The Solaris PICL module provides interfaces to the watchdog timer in SMC.

processor to optionally reset. The maximum range for

PICL Plug-In Module

The watchdog subsystem is managed by a platform information and control library (PICL) plug-in module. This PICL plug-in module provides a set of PICL properties to the system, which enables a Solaris PICL client to specify the attributes of the watchdog system.

To use the PICL API to set the watchdog properties, your application must follow the following sequence:

Note – The following instructions are not server-specific. Check your server

documentation for additional software configuration that might be needed with the watchdog timer.

1. If the watchdog timer is running, stop it by disabling the primary HEALTHY# signal monitoring for the CPU card on which the watchdog timer is to be changed.

2. In your application, use the PICL API to disarm, set, and arm the active watchdog timer.

Refer to the picld(1M), libpicl(3LIB), and libpicltree(3LIB) man pages for a complete description of the PICL architecture and programming interface. Develop your application to use the PICL programming interface to do the following:

■ Disarm the active watchdog timer.

■ Change the watchdog timer PICL properties to the required values.

■ Re-arm the watchdog timer. The properties of watchdog-controller and

watchdog-timer are defined in

TABLE 1-1, TABLE 1-2, and TABLE 1-3.

3. Re-enable the primary HEALTHY# signal monitoring on the CPU card in the specified slot.

2 Netra CP2500 Board Programming Guide • March 2007

PICL interfaces for the watchdog plug-in module include the nodes watchdogcontroller and watchdog-timer. See

TABLE 1-1, TABLE 1-2, and TABLE 1-3 for

descriptions of the properties of these nodes.

TABLE 1-1 Watchdog Plug-In Interfaces for Netra CP2500 Board Software

PICL Class Property Meaning

watchdogcontroller

watchdog-timer State Represents a watchdog timer hardware that belongs to its

TABLE 1-2 Properties Under watchdog-controller Node

Property Operations Description

WdOp arm Activates all timers under the controller with values already set for

WdOp Represents a watchdog subsystem.

controller. Each timer depends on the status of its peers to be activated or deactivated.

WdTimeout Timeout for the watchdog timer.

WdAction Action to be taken after the watchdog expires.

WdTimeout and WdAction.

disarm All active timers under the controller will be stopped.

Chapter 1 Watchdog Timer 3

TABLE 1-3 Properties Under watchdog-timer Node

Property Values Description

State armed Indicates timer is armed or running. Cleared by disarm.

expired Indicates timer has expired. Cleared by

disarm.

disarmed Default value set at startup time. Indicates timer is disarmed or

stopped.

WdTimeout

WdAction

Varies by system and timer level

Indicates the timer initial countdown value. Should be set prior to arming the timer.

none Default value. No action is taken.

alarm Sends notifications to system alarm hardware by means of

HEALTHY#.

reset Performs a soft or hard reset of the system (implementation

specific).

reboot Reboots the system.

* A platform mightnot supporta specified timeout resolution. Forexample, NetraCT 810/410systems onlytake -1,0, and100 to6553500

msec in increments of 100 msec for level 1; and -1, 0, and 1000 to 255000 in increments of 1000 msec for level 2.

\ A specific timer node might not support all action types. For example, Netra CT watchdog level 1 timer supports only none, alarm,

and reboot actions. Watchdog level 2 timer supports only none and reset.

To identify current settings of watchdog-controller, issue the command

prtpicl -v as shown in the sample output below.

# prtpicl -v ... watchdog (watchdog-controller,26000000532) :WdOp <WRITE-ONLY> :_class watchdog-controller :name watchdog watchdog-level1 (watchdog-timer, 26000000536) :WdAction alarm :WdTimeout 0x2710 :State disarmed :_class watchdog-timer :name watchdog-level1 watchdog-level2 (watchdog-timer, 26000000539) :WdAction none :WdTimeout 0xffffffff :State disarmed

4 Netra CP2500 Board Programming Guide • March 2007

:_class watchdog-timer :name watchdog-level2

Watchdog Node Management Code

CODE EXAMPLE 1-1 contains an example of the code used for managing the watchdog

timer nodes. This code can be used to change watchdog timer action and timeout values and also to arm and disarm the watchdog controller.

CODE EXAMPLE 1-1 System Watchdog Node Management Code Example

#pragma ident "@(#)wdadm.c 1.6 03/10/16 SMI"

/* * This program is used to manage the system watchdog nodes. * Please refer to libpicl(3LIB) for information on picl APIs * To compile: * cc -o wdadm -lpicl wdadm.c */

#include <stdio.h> #include <stdlib.h> #include <stdarg.h> #include <string.h> #include <strings.h> #include <errno.h> #include <alloca.h> #include <libintl.h> #include <locale.h> #include <unistd.h> #include <assert.h> #include <inttypes.h> #include <sys/termios.h> #include <picl.h>

/* * Error codes */ #define EM_USAGE 0

Chapter 1 Watchdog Timer 5

CODE EXAMPLE 1-1 System Watchdog Node Management Code Example (Continued)

#define EM_INIT 1 #define EM_GETROOT 2 #define EM_GETPVALBYNAME 3

#define USAGE_STR "Usage:\n"\ "wdadm -l [<controller_name:timer_name>...]\n"\ "wdadm -m <controller_name:timer_name> [-t <timeout>]"\ " [-a action]]\n"\ "wdadm -c <controller_name> -o <op>\n"

#define DETAILED_HELP "wdadm - System Watchdog Controller Administration\n"\ "Description:\n"\ "The operations include displaying status (-l), modifying the values (-m)\n"\ "and executing commands on the watchdog controller (-c).\n"\ "This utility must be run with super user permissions.\n"\ "OPTIONS\n"\ " -l list all the watchdog timer nodes.\n"\ " Each Timer node is denoted as controller:timer\n"\ " Example:\n"\ " wdadm -l - lists all the nodes\n"\ " wdadm -l c1:t1 c1:t2 - lists c:t1 and c:t2 nodes\n"\ " c1 - controller name\n"\ " t1 - timer name\n"\ " -m modify the timeout and action parameters for a timer node.\n"\ " Example:\n"\ " wdadm -m c1:t1 -t <timeout in ms> -a <action>\n"\ " wdadm -m c1:t1 -t <timeout in ms>\n"\ " wdadm -m c1:t1 -a <action>\n"\ " Note: Before using this option, the controller must be\n"\ " disarmed (using -c option).\n"\ " -c Execute commands on the watchdog controller node\n"\ " Commands supported are : arm, disarm\n"\ " Example:\n"\ " wdadm -c controller -o arm\n"\ " arms the watchdog controller node called controller\n"

#define HEADER "NAME (controller:timer)\t\tSTATUS"\ "\t\tACTION\t\tTIMEOUT\n" #define PRINT_FORMAT "\t%-10s\t%-10s\t%d" #define ILLEGAL_TIMEOUT -999

/* watchdog properties */ #define WATCHDOG_ACTION "WdAction" #define WATCHDOG_TIMEOUT "WdTimeout" #define WATCHDOG_STATUS "State" #define WATCHDOG_OP "WdOp" #define PICL_WATCHDOG_CONTROLLER "watchdog-controller"

6 Netra CP2500 Board Programming Guide • March 2007

CODE EXAMPLE 1-1 System Watchdog Node Management Code Example (Continued)

#define WATCHDOG_DISARMED "disarmed"

/* * data structure that will be passed as argument to * picl_walk_tree_by_class callback function */ typedef struct { int start_index; int max_index; char **list; char *name; char *action; char *op; int32_t timeout; int error_code; } wdadm_args_t;

static char *prog; static picl_nodehdl_t rooth; static int count = 0;

/* * Error mesage texts */ static char *err_msg[] = { /* program usage */ USAGE_STR, /* 0 */ /* picl call failed messages */ "picl_initialize failed: %s\n", /* 1 */ "picl_get_root failed: %s\n", /* 2 */ "picl_get_propval_by_name failed: %s\n" /* 3 */ };

#define NUM_ERROR_CODES 7 /* mapping between picl error codes and errno */ static int error_map[][2] = { {PICL_SUCCESS, 0}, { PICL_FAILURE, -1}, {PICL_VALUETOOBIG, E2BIG}, {PICL_NODENOTFOUND, ENODEV}, {PICL_PERMDENIED, EPERM}, {PICL_NOSPACE, ENOMEM}, {PICL_INVALIDARG, EINVAL} };

static int picl2errno(int piclerr) { int i; for (i = 0; i < NUM_ERROR_CODES; i++) { if (error_map[i][0] == piclerr) return (error_map[i][1]);

Chapter 1 Watchdog Timer 7

CODE EXAMPLE 1-1 System Watchdog Node Management Code Example (Continued)

} return (-1); }

static void print_errmsg(char *message, ...) { va_list ap;

va_start(ap, message); (void) fprintf(stderr, "%s: ", prog); (void) vfprintf(stderr, message, ap); va_end(ap); }

/* * Print wdadm usage */ static void usage(void) { print_errmsg(gettext(err_msg[EM_USAGE])); exit(1); }

/* * This function is used to read picl property. The value is copied * into vbuf. * memory allocated for vbuf must be free’d by caller */ static picl_errno_t wdadm_get_picl_prop(picl_nodehdl_t nodeh, const char *prop_name, void **vbuf) { picl_errno_t err; picl_propinfo_t pinfo; picl_prophdl_t proph;

/* get the information about the property */ if ((err = picl_get_propinfo_by_name(nodeh, prop_name, &pinfo, &proph)) != PICL_SUCCESS) { return (err); }

*vbuf = malloc(pinfo.size); if (vbuf == NULL) return (PICL_NOSPACE);

8 Netra CP2500 Board Programming Guide • March 2007

CODE EXAMPLE 1-1 System Watchdog Node Management Code Example (Continued)

/* read the property value */ if ((err = picl_get_propval(proph, *vbuf, pinfo.size)) != PICL_SUCCESS) { return (err); } return (PICL_SUCCESS); }

/* * This function is used to set the value of a picl property */ static picl_errno_t wdadm_set_picl_prop(picl_nodehdl_t nodeh, const char *prop_name, void *vbuf, int size) { picl_errno_t err; picl_propinfo_t pinfo; picl_prophdl_t proph; void *tmp_buf;

if ((err = picl_get_propinfo_by_name(nodeh, prop_name, &pinfo, &proph)) != PICL_SUCCESS) { return (err); }

tmp_buf = alloca(pinfo.size); if (tmp_buf == NULL) { return (PICL_NOSPACE); } if (size > pinfo.size) { return (PICL_VALUETOOBIG); }

bzero(tmp_buf, pinfo.size); (void) memcpy(tmp_buf, vbuf, size);

/* set the property value */ if ((err = picl_set_propval(proph, vbuf, pinfo.size)) != PICL_SUCCESS) { return (err); } return (PICL_SUCCESS); }

/* * This function prints the timeout, state, action of a * watchdog-timer node

Chapter 1 Watchdog Timer 9

+ 51 hidden pages

Sun Microsystems Netra CP2500 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Figures

Tables

Code Samples

Watchdog Timer

Overview

PICL Plug-In Module

Watchdog Node Management Code