The DTC library, dtcreg, contains a set of functions that facilitate reading from and writing to registers on the DTC.

Opening and Closing

The code may be found in /home/msdim/ipmi/ipmitool-1.8.11/dtcreg, where dtcreg.o is the actual library and dtcreg.h is the associated header file.

Using dtcreg is much like file handling in C: you declare a handle, open/initialize the handle, perform read/write operations with the handle, and close the handle.

First, it should be noted that in building a program that uses ipmitool libraries, there are two external global variables that must be defined in the program being built. Define the following global variables:

int verbose = 0;
int csv_output = 0;

The handle for dtcreg is called hDTC. It contains an instance of the ipmi_intf (IPMI interface) structure called intf. In addition, it contains two 1-bit flags: int lock and int dblBridge. lock is set to 1 (true) once the handle is opened and communication with the MCH is established and is set to 0 (false) once the handle is closed; hence, a locked handle (which has been closed or never initialized) cannot have read/write commands used on it, avoiding segmentation faults. dblBridge determines whether communication is double bridged or single bridged (in general it will be double) and setting it to 0 means that single bridged communication will be used (anything but 0 implies double bridged).

The open statement is: int dtc_open(hDTC *handle, char *ip, int dblBridge). This different from the C fopen in two essential ways:

1. The address of the handle is passed to the first parameter.

2. dtc_open returns in error code (0 for success)

The second parameter is the ip address of the MCH in character string form, e.g. "". The third parameter sets whether the communication is single or double bridged (as explained previously) and should be set to either DTC_SINGLE or DTC_DOUBLE.

The close function is: int dtc_close(hDTC *handle). It accepts the address of a handle and returns an error code. This function should be called when a particular handle should not be used anymore, like at the end of the program.

Using hDTC, dtc_open, and dtc_close should look something like this:

  hDTC handle;
  dtc_open(&handle, "", DTC_DOUBLE);
  /* Read/write in here... */

Reading and Writing

There are 12 read/write functions. However, all of the functions come in two variations, so in truth, there are only 6 distinct functions. All of the functions ask for the handle as the first parameter and all return an error code. The second parameter is always a register address. However, there are two ways to enter the address: as an integer or as a string. The integer form is more useful if the functions are in, say, a "for" loop which runs through a number of registers. The string form is useful as register addresses are typically hexadecimal and look something like "0x2c". Therefore, each of the 6 distinct functions has an integer version and a hexadecimal-string version. Since the hexadecimal version is simply a wrapper function that calls the integer version with a translated parameter, the function name acquires an 'x' near the end, so the hexadecimal addressed version of dtc_read(...) is dtc_readx(...).


These are the most basic read and write functions and are called by the higher level read/write functions. dtc_read reads from one register and dtc_write writes to one register.

int dtc_read(hDTC handle, int regAddr, uint8_t dat[], int *lenRead) / dtc_readx(..., char *hexRegAddr, ..., ...)

The third parameter asks for an array of 8-bit unsigned integers which will contain the read data. The fourth parameter asks for the address of an integer in which the length of the read data will be stored, i.e. the length of the data array. The max array length that this (and all following functions) assumes is defined by MAX_DATA in dtcreg.h and is by default set to 16.

int dtc_write(hDTC handle, int regAddr, uint8_t dat) / dtc_writex(..., char *hexRegAddr, ...)

This is a simple function: the third parameter is the 8-bit value to write to the register.




dtcreg is built on ipmitool and is a wrapper for some of its structures and functions; so while using it does not require knowledge of the ipmitool code, programs built with it must include several additional libraries which are required by ipmitool.

-- MichaelDimitriyev - 16 Jun 2010

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r3 - 22 Jun 2010 - MichaelDimitriyev
  • Edit
  • Attach
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback