Using ipmi_sim For A Real BMC
            -----------------------------

So you want to create a real BMC.  This is now possible with the
simulator.  So it's really not a simulator in this case, but that's
its heritage, so the name is still stuck.  Maybe I'll change it later.

Anyway, It can do most of the work without even writing any C code,
just with configuration.  It probably won't do everything you want out
of the box, though, so it has plugin capability to let you add your
own code to handle special conditions.

This documentation assumes a good working knowledge of IPMI.


How It Works
------------

The simulator has the two standard configuration files as defined in
the ipmi_sim_cmd.5 and ipmi_lan.5 man pages.  The LAN configuration
file defines the lan interfaces and a few other things, like SOL
configuration.

The emulator command file has commands to define the IPMI structure of
the system, like management controllers, sensors, FRU data, SDRs, etc.

So to create a BMC, you define the LAN interfaces, the management
controllers, the sensors, etc. in your system.  You can tie the FRU
data to physical files on the system (like EEPROMS in sysfs, or real
files).  You can tie the sensors to files, like sensors in sysfs.  You
can also write custom code and tie it in to set the sensor values.


Management Controllers
----------------------

To have a management controller handled by ipmi_sim, you have to add
it via the mc_add command, then you have to enable it with mc_enable.
This is a virtual management controller.  You have to add the BMC at
0x20, of course, but you can add others, too, if that makes sense.
For instance, if you have multiple boards in the system, it may make
sense to define a virtual MC for each board.  This is pretty simple.
Note that the capabilities you set with the mc_add command affect what
the MC can do.  You can't add SDRs, for instance, if the MC doesn't
have SDR capability.


LAN Configuration
-----------------

The LAN configuration file mostly defines the LAN interfaces.  It also
has a lot of simulator configuration, like how to start virtual
machine sessions tied to the management controllers and how the VMs
interface to the simulator.  These aren't terribly useful for a real
BMC (though the serial interface might one day with some
modifications).

The name of the BMC is set here.  This is used for a few things, like
to tell where to store persistent information (in
/var/ipmi_sim/<name>) and in logging.

A few other things in the file are SOL configuration, chassis control
handling, and loading custom code.  These are discussed later.


Sensors
-------

Sensors are added with the emulator command file with the sensor_add
command.  This command also lets you poll a file for data and has a
lot of options for massaging the data from the file into the 256 byte
value returned by an IPMI sensor.  It also lets you tie a dependency
to a discrete sensor, so that the enabling of the sensor can be done
based on a bit in the other discrete sensor.  For instance, a power
supply sensor has a presence bit in it, the power supply voltage and
current sensors can depend on that bit to be enabled or disabled.

If you are writing custom code to handle a sensor, you still have to
add it with sensor_add, then you can use the sensor number to
manipulate the sensor's value.  You have three main functions to do
this:

ipmi_mc_sensor_set_enabled() will let you enable or disable a sensor
directly.  Generally you would modify the sensor enable based upon the
presence of the entity the sensor measures.

ipmi_mc_sensor_set_value() sets a threshold sensor's value.

ipmi_mc_sensor_set_bit() sets/clears a discrete sensor bit.


SDRs
----

If you have sensors, you need SDRs to describe them.  You can directly
add these via the emulator command main_sdr_add (or device_sdr_add),
but that only deals with raw data and is a fairly inconvenient way to
do this.

The main SDRs for an MC are persistent and stored in
/var/ipmi_sim/<system-name/sdr.<ipmb-addr>.main.  For instance, the
main SDRs for a BMC at 0x20 are in /var/ipmi_sim/<name>/sdr.20.main.
If the user makes changes, they are stored there.  But, you can store
your SDRs here, too.

The easier way is to use the SDR compiler in the sdrcomp directory,
which can output data in the persistence format.  Then you can write
your SDRs in a more human-readable (or perhaps ipmi-engineer-readable)
format rather than just a bunch of bits.  Then generate the file and
copy it into the right place.


Serial Over LAN
---------------

As mentioned earlier, you can define SOL port in the lan configuration
file.  You can assign a physical serial port to a SOL port.  This is
described in the docs and is pretty straightforward.

There are a couple of unusual things about this, though.

One is that you can create a SOL interface on an MC besides the BMC.
But the standard SOL protocol will still work with it.  This means you
can use "ipmitool -t <mc>" to address a specific SOL instance, which
is convenient if you want to tie SOL interfaces to specific MCs.  Yes,
it's kind of an abuse of the spec, but it works and is convenient.

The other unusual thing about the SOL implementation is that it can
have a history buffer.  So say you want to keep around the last 64K or
so of data without having to be constantly connected to the BMC.  You
can define a 64K history buffer and connect to the BMC later to fetch
it.

You have two ways to fetch it.  The first is that the history buffer
appears as a second SOL instance at instance 2.  So you can connect to
SOL instance 2 and it will dump all the history.  The disadvantage of
this approach is that ipmitool cannot connect to SOL instances besides
1 without a special patch.

The other way to fetch it is to define a FRU data buffer that holds
the history.  You can define which FRU device does this.  Then you can
use the FRU data fetching commands to get the data.  The disadvantage
of this is that FRU data is limited to 64K.


FRU Data
--------

FRU data has already been mentioned with respect to SOL, but you can
create FRU data for an MC with the mc_add_fru_data emulator command.
You can either directly define the FRU data there (not ideal for a
real BMC) or tie it to a file.  Reading and writing all work.


Chassis Control
---------------

You can define an external command to handle chassis control commands.
The ipmi_sim_chassiscontrol file gives a framework for writing your
own script for handling this, and defines the various things that can
be done.  This is how reset, power, and boot control are done.


Custom Code
-----------

As mentioned before, you can load your own custom modules to do
whatever you like.  

Any module must define the following function:

int ipmi_sim_module_init(sys_data_t *sys, const char *initstr);

This is used to initialize the module.  It is called after the
configuration has been read from the LAN configuration file, but
before the emulator commands are run.  The module must also define the
following function:

int ipmi_sim_module_print_version(sys_data_t *sys, char *initstr);

This should print out an identifier and version number to standard out.

The module may optionally define the following function:

int ipmi_sim_module_post_init(sys_data_t *sys);

This is called after the emulator command file is run.  This can be
used to finish up configuration of things, add functions to sensors,
do any sensor initialization, or anything else that needs to be done
after the emulator commands are run.

The include files in lanserv/OpenIPMI define the interface function
that a module may use.  Primarily, serv.h and mcserv.c.


Threading
---------

The ipmi_sim code itself is not multi-threaded.  You cannot have
concurrent calls into any of the code.  You can, however, define your
own threads using pthreads as long as none of them call into the
ipmi_sim code.


What's Still Missing
--------------------

ipmi_sim currently does not have any provisions for direct IPMI
support or the handling of any I2C commands.  This should be fairly
easy to add, but has not yet been needed.

Lots of other things are probably missing, too, of course, but it's
hard to know what you don't know...