1Kernel driver pmbus
2====================
3
4Supported chips:
5  * Ericsson BMR45X series
6    DC/DC Converter
7    Prefixes: 'bmr450', 'bmr451', 'bmr453', 'bmr454'
8    Addresses scanned: -
9    Datasheet:
10 http://archive.ericsson.net/service/internet/picov/get?DocNo=28701-EN/LZT146395
11  * Linear Technology LTC2978
12    Octal PMBus Power Supply Monitor and Controller
13    Prefix: 'ltc2978'
14    Addresses scanned: -
15    Datasheet: http://cds.linear.com/docs/Datasheet/2978fa.pdf
16  * Generic PMBus devices
17    Prefix: 'pmbus'
18    Addresses scanned: -
19    Datasheet: n.a.
20
21Author: Guenter Roeck <guenter.roeck@ericsson.com>
22
23
24Description
25-----------
26
27This driver supports hardware montoring for various PMBus compliant devices.
28It supports voltage, current, power, and temperature sensors as supported
29by the device.
30
31Each monitored channel has its own high and low limits, plus a critical
32limit.
33
34Fan support will be added in a later version of this driver.
35
36
37Usage Notes
38-----------
39
40This driver does not probe for PMBus devices, since there is no register
41which can be safely used to identify the chip (The MFG_ID register is not
42supported by all chips), and since there is no well defined address range for
43PMBus devices. You will have to instantiate the devices explicitly.
44
45Example: the following will load the driver for an LTC2978 at address 0x60
46on I2C bus #1:
47$ modprobe pmbus
48$ echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device
49
50
51Platform data support
52---------------------
53
54Support for additional PMBus chips can be added by defining chip parameters in
55a new chip specific driver file. For example, (untested) code to add support for
56Emerson DS1200 power modules might look as follows.
57
58static struct pmbus_driver_info ds1200_info = {
59	.pages = 1,
60	/* Note: All other sensors are in linear mode */
61	.direct[PSC_VOLTAGE_OUT] = true,
62	.direct[PSC_TEMPERATURE] = true,
63	.direct[PSC_CURRENT_OUT] = true,
64	.m[PSC_VOLTAGE_IN] = 1,
65	.b[PSC_VOLTAGE_IN] = 0,
66	.R[PSC_VOLTAGE_IN] = 3,
67	.m[PSC_VOLTAGE_OUT] = 1,
68	.b[PSC_VOLTAGE_OUT] = 0,
69	.R[PSC_VOLTAGE_OUT] = 3,
70	.m[PSC_TEMPERATURE] = 1,
71	.b[PSC_TEMPERATURE] = 0,
72	.R[PSC_TEMPERATURE] = 3,
73	.func[0] = PMBUS_HAVE_VIN | PMBUS_HAVE_IIN | PMBUS_HAVE_STATUS_INPUT
74		   | PMBUS_HAVE_VOUT | PMBUS_HAVE_STATUS_VOUT
75		   | PMBUS_HAVE_IOUT | PMBUS_HAVE_STATUS_IOUT
76		   | PMBUS_HAVE_PIN | PMBUS_HAVE_POUT
77		   | PMBUS_HAVE_TEMP | PMBUS_HAVE_STATUS_TEMP
78		   | PMBUS_HAVE_FAN12 | PMBUS_HAVE_STATUS_FAN12,
79};
80
81static int ds1200_probe(struct i2c_client *client,
82			const struct i2c_device_id *id)
83{
84	return pmbus_do_probe(client, id, &ds1200_info);
85}
86
87static int ds1200_remove(struct i2c_client *client)
88{
89	return pmbus_do_remove(client);
90}
91
92static const struct i2c_device_id ds1200_id[] = {
93	{"ds1200", 0},
94	{}
95};
96
97MODULE_DEVICE_TABLE(i2c, ds1200_id);
98
99/* This is the driver that will be inserted */
100static struct i2c_driver ds1200_driver = {
101	.driver = {
102		   .name = "ds1200",
103		   },
104	.probe = ds1200_probe,
105	.remove = ds1200_remove,
106	.id_table = ds1200_id,
107};
108
109static int __init ds1200_init(void)
110{
111	return i2c_add_driver(&ds1200_driver);
112}
113
114static void __exit ds1200_exit(void)
115{
116	i2c_del_driver(&ds1200_driver);
117}
118
119
120Sysfs entries
121-------------
122
123When probing the chip, the driver identifies which PMBus registers are
124supported, and determines available sensors from this information.
125Attribute files only exist if respective sensors are suported by the chip.
126Labels are provided to inform the user about the sensor associated with
127a given sysfs entry.
128
129The following attributes are supported. Limits are read-write; all other
130attributes are read-only.
131
132inX_input		Measured voltage. From READ_VIN or READ_VOUT register.
133inX_min			Minimum Voltage.
134			From VIN_UV_WARN_LIMIT or VOUT_UV_WARN_LIMIT register.
135inX_max			Maximum voltage.
136			From VIN_OV_WARN_LIMIT or VOUT_OV_WARN_LIMIT register.
137inX_lcrit		Critical minimum Voltage.
138			From VIN_UV_FAULT_LIMIT or VOUT_UV_FAULT_LIMIT register.
139inX_crit		Critical maximum voltage.
140			From VIN_OV_FAULT_LIMIT or VOUT_OV_FAULT_LIMIT register.
141inX_min_alarm		Voltage low alarm. From VOLTAGE_UV_WARNING status.
142inX_max_alarm		Voltage high alarm. From VOLTAGE_OV_WARNING status.
143inX_lcrit_alarm		Voltage critical low alarm.
144			From VOLTAGE_UV_FAULT status.
145inX_crit_alarm		Voltage critical high alarm.
146			From VOLTAGE_OV_FAULT status.
147inX_label		"vin", "vcap", or "voutY"
148
149currX_input		Measured current. From READ_IIN or READ_IOUT register.
150currX_max		Maximum current.
151			From IIN_OC_WARN_LIMIT or IOUT_OC_WARN_LIMIT register.
152currX_lcrit		Critical minimum output current.
153			From IOUT_UC_FAULT_LIMIT register.
154currX_crit		Critical maximum current.
155			From IIN_OC_FAULT_LIMIT or IOUT_OC_FAULT_LIMIT register.
156currX_alarm		Current high alarm.
157			From IIN_OC_WARNING or IOUT_OC_WARNING status.
158currX_max_alarm		Current high alarm.
159			From IIN_OC_WARN_LIMIT or IOUT_OC_WARN_LIMIT status.
160currX_lcrit_alarm	Output current critical low alarm.
161			From IOUT_UC_FAULT status.
162currX_crit_alarm	Current critical high alarm.
163			From IIN_OC_FAULT or IOUT_OC_FAULT status.
164currX_label		"iin" or "ioutY"
165
166powerX_input		Measured power. From READ_PIN or READ_POUT register.
167powerX_cap		Output power cap. From POUT_MAX register.
168powerX_max		Power limit. From PIN_OP_WARN_LIMIT or
169			POUT_OP_WARN_LIMIT register.
170powerX_crit		Critical output power limit.
171			From POUT_OP_FAULT_LIMIT register.
172powerX_alarm		Power high alarm.
173			From PIN_OP_WARNING or POUT_OP_WARNING status.
174powerX_crit_alarm	Output power critical high alarm.
175			From POUT_OP_FAULT status.
176powerX_label		"pin" or "poutY"
177
178tempX_input		Measured temperature.
179			From READ_TEMPERATURE_X register.
180tempX_min		Mimimum temperature. From UT_WARN_LIMIT register.
181tempX_max		Maximum temperature. From OT_WARN_LIMIT register.
182tempX_lcrit		Critical low temperature.
183			From UT_FAULT_LIMIT register.
184tempX_crit		Critical high temperature.
185			From OT_FAULT_LIMIT register.
186tempX_min_alarm		Chip temperature low alarm. Set by comparing
187			READ_TEMPERATURE_X with UT_WARN_LIMIT if
188			TEMP_UT_WARNING status is set.
189tempX_max_alarm		Chip temperature high alarm. Set by comparing
190			READ_TEMPERATURE_X with OT_WARN_LIMIT if
191			TEMP_OT_WARNING status is set.
192tempX_lcrit_alarm	Chip temperature critical low alarm. Set by comparing
193			READ_TEMPERATURE_X with UT_FAULT_LIMIT if
194			TEMP_UT_FAULT status is set.
195tempX_crit_alarm	Chip temperature critical high alarm. Set by comparing
196			READ_TEMPERATURE_X with OT_FAULT_LIMIT if
197			TEMP_OT_FAULT status is set.
198