CHAPTER 2. OPENIPMI
The GLIB OS Handler
An OS handler is already defined for glib and will work with threads. It is defined in the include file ipmi_glib.h; see that file for more details. To allocate a GLIB OS handler, use:
o s _ h n d = i p m i _ g l i b _ g e t _ o s _ h a n d l e r ( ) ;
Presumably, GLIB handles the waking of threads, so unlike the POSIX version no wakeup signal is required.
All the other the OS handler functions are done with the standard functions in the OS handler, described in section 2.2.2.
Almost all OpenIPMI calls that do anything besides fetch a piece of local data will return an integer error value. A zero means no error. Two types of errors are returned, system errors (which are standard Unix errno values) and IPMI errors (which are the standard IPMI error codes). You can use the macros IPMI_IS_OS_ERR and IPMI_IS_IPMI_ERR to tell the type of error, and IPMI_GET_OS_ERR and IPMI_GET_IPMI_ERR to get the actual error values.
Note that if your system doesn’t have Unix-type error numbers, you will have to provide those for the OpenIPMI library.
If a function returns an error, any callbacks provided to that function will never be called. If a function that takes a callback returns success, the callback will always be called, even if the object associated has ceased to exist. If an object with outstandard operations ceases to exist, all the callbacks for outstanding operations will be called with ECANCELED as the error. Errors are passed into many callbacks, if an error is present the rest of the data in the callback is probably not valid except for the cb_data variable you provide, and possibly the object the callback is associated with. The object the callback is associated with may be NULL if it has ceased to exist.
As mentioned before, you may or may not be using locking, but you must read this section anyway. Locking here involves existance of entities as well as normal locking.
Locking has changed between OpenIPMI 1.3 and 1.4. In OpenIPMI 1.3, locks were held in user callbacks. Locking was very course grained and the locks were recursive, so this was generally not a problem. However, in general it is a bad idea to hold locks in user callbacks. The user might have two domains and cause deadlocks between them. For instance, if the user had one thread in a callback from domain 1 that then called a function in domain 2, and another thread in a callback from domain 2 that called a function in domain 1, the system can deadlock. This is because the first thread holds locks in domain 1 that the second thread needs for the function in domain 1, and the second thread holds locks in domain 2 that the first thread needs for the domain 2 function. Because of this, locking strategy has changed in OpenIPMI 1.4. The interfaces and basic usage are completely unchanged, but the semantics have changed.
The basic principle of locking is that if you are in a callback for an IPMI object (an IPMI object is passed in the callback), that object is refcounted (marked in-use) and the system cannot delete it. In any callback