Sun Microsystems Netra CP2500 Operating instructions

Sun Microsystems, Inc.
www.sun.com
Submit comments about this document at: http://www.sun.com/hwdocs/feedback
Netra™CP2500 Board
Programming Guide
For the Solaris™Operating System
Part No. 819-1749-11
March 2007, Revision A

Copyright 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.
Sun Microsystems, Inc. has intellectual property rights relating to technology that is described in this document. In particular, and without
limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or
more additional patents or pending patent applications in the U.S. and in other countries.
This document and the product to which it pertains are distributed under licenses restricting their use, copying, distribution, and
decompilation. No part of the product or of this document may be reproduced in any form by any means without prior written authorization of
Sun and its licensors, if any.
Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.
Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in
the U.S. and in other countries, exclusively licensed through X/Open Company, Ltd.
Sun, Sun Microsystems, the Sun logo, AnswerBook2, docs.sun.com, Netra, OpenBoot, and Solaris are trademarks or registered trademarks of
Sun Microsystems, Inc. in the U.S. and in other countries.
All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and in other
countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.
The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges
the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun
holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN
LOOK GUIs and otherwise comply with Sun’s written license agreements.
U.S. Government Rights—Commercial use. Government users are subject to the Sun Microsystems, Inc. standard license agreement and
applicable provisions of the FAR and its supplements.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT,
ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
Copyright 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, Californie 95054, Etats-Unis. Tous droits réservés.
Sun Microsystems, Inc. a les droits de propriété intellectuels relatants à la technologie qui est décrit dans ce document. En particulier, et sans la
limitation, ces droits de propriété intellectuels peuvent inclure un ou plus des brevets américains énumérés à http://www.sun.com/patents et
un ou les brevets plus supplémentaires ou les applications de brevet en attente dans les Etats-Unis et dans les autres pays.
Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, la distribution, et la
décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans
l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y ena.
Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des
fournisseurs de Sun.
Des parties de ce produit pourront être dérivées des systèmes Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque
déposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd.
Sun, Sun Microsystems, le logo Sun, AnswerBook2, docs.sun.com, Netra, OpenBoot, et Solaris sont des marques de fabrique ou des marques
déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays.
Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc.
aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun
Microsystems, Inc.
L’interface d’utilisation graphique OPEN LOOK et Sun™ a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun
reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique
pour l’industrie de l’informatique. Sun détient une license non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence
couvrant également les licenciées de Sun qui mettent en place l’interface d ’utilisation graphique OPEN LOOK et qui en outre se conforment
aux licences écrites de Sun.
LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES
OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT
TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE UTILISATION PARTICULIERE OU A
L’ABSENCE DE CONTREFAÇON.

iii
Contents
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

iv Netra CP2500 Board Programming Guide • March 2007
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

v
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

vii
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

viii Netra CP2500 Board Programming Guide • March 2007

ix
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

xNetra CP2500 Board Programming Guide • March 2007

xi
Preface
The Netra CP2500 Board Programming Guide is written for program developers and
users who want to program the Netra™CP2500 board in order to design original
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.
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.

xii Netra CP2500 Board Programming Guide • March 2007
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*
* The settings on your browser might differ from these settings.
Meaning Examples
AaBbCc123 The names of commands, files,
and directories; on-screen
computer output
Edit your.login file.
Use ls -a to list all files.
% You have mail.
AaBbCc123 What you type, when contrasted
with on-screen computer output
%su
Password:
AaBbCc123 Book titles, new words or terms,
words to be emphasized.
Replace command-line variables
with real names or values.
Read Chapter 6 in the User’s Guide.
These are called class options.
You must be superuser to do this.
To delete a file, type rm filename.

Preface xiii
Shell Prompts
Related Documentation
Online documents are available at:
http://www.sun.com/documentation
Shell Prompt
C shell machine-name%
C shell superuser machine-name#
Bourne shell and Korn shell $
Bourne shell and Korn shell superuser #
Title Part Number
Netra CP2500 Board Release Notes 819-1748
Netra CP2500 Board Installation and Technical Reference
Manual
819-1747
Netra CP2500 Board Programming Guide 819-1749
Netra CP2500 Board Safety and Compliance Manual 819-1750
Netra CP2500 Rear Transition Module Installation and
Technical Reference Manual
819-1753
Important Safety Information for Sun Hardware Systems 816-7190

xiv Netra CP2500 Board Programming Guide • March 2007
Documentation, Support, and Training
Third-Party Web Sites
Sun is not responsible for the availability of third-party web sites mentioned in this
document. Sun does not endorse and is not responsible or liable for any content,
advertising, products, or other materials that are available on or through such sites
or resources. Sun will not be responsible or liable for any actual or alleged damage
or loss caused by or in connection with the use of or reliance on any such content,
goods, or services that are available on or through such sites or resources.
Sun Welcomes Your Comments
Sun is interested in improving its documentation and welcomes your comments and
suggestions. You can submit your comments by going to:
http://www.sun.com/hwdocs/feedback
Please include the title and part number of your document with your feedback:
Netra CP2500 Board Programming Guide, part number 819-1749-11
Sun Function URL
Documentation http://www.sun.com/documentation/
Support http://www.sun.com/support/
Training http://www.sun.com/training/

1
CHAPTER 1
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®processor to optionally reset. The maximum range for
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.

2Netra CP2500 Board Programming Guide • March 2007
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.

Chapter 1 Watchdog Timer 3
PICL interfaces for the watchdog plug-in module include the nodes watchdog-
controller 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
watchdog-
controller
WdOp Represents a watchdog subsystem.
watchdog-timer State Represents a watchdog timer hardware that belongs to its
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.
TABLE 1-2 Properties Under watchdog-controller Node
Property Operations Description
WdOp arm Activates all timers under the controller with values already set for
WdTimeout and WdAction.
disarm All active timers under the controller will be stopped.

4Netra CP2500 Board Programming Guide • March 2007
To identify current settings of watchdog-controller, issue the command
prtpicl -v as shown in the sample output below.
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*
* A platform might not support a specified timeout resolution. For example, Netra CT 810/410 systems only take -1, 0, and 100 to 6553500
msec in increments of 100 msec for level 1; and -1, 0, and 1000 to 255000 in increments of 1000 msec for level 2.
Varies by system
and timer level
Indicates the timer initial countdown value. Should be set prior
to arming the timer.
WdAction\
\ 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.
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.
#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

Chapter 1 Watchdog Timer 5
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.
:_class watchdog-timer
:name watchdog-level2
CODE EXAMPLE 1-1 System Watchdog Node Management Code Example
/*
* Copyright 2003 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#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

6Netra CP2500 Board Programming Guide • March 2007
#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"
CODE EXAMPLE 1-1 System Watchdog Node Management Code Example (Continued)