This is ServerU Bypass Watch Dog kernel module (driver) and control utility for ServerU Netmap series running Intel 3rd generation bypass for both electric and optical devices. Unpack this tar ball (su_bpwd_fbsd-v1.X.Y.tar.bz2), build the kernel module and the utility while logged as root: tar vxzf su_bpwd_fbsd-v1.X.Y.tar.bz2 make clean ; make ; make serveru-bpwd-ctl Load the kernel module: kldload ./su_bpwd.ko Make it persistent (load on boot time): make install echo su_bpwd_load=\"YES\" >> /boot/loader.conf You will have the following files installed: /usr/local/sbin/serveru-bpwd-ctl /boot/modules/su_bpwd.ko This kernel module will create the following device node on FreeBSD: /dev/bpwd This device will allow for userland access to the kernel module and hardware information for read and write commands allowing for run-time bypass config. ServerU Bypass/Watchdog Access Code: v1.1.0 2014-04-07 for FreeBSD Usage: ./serveru-bpwd-ctl -S Scan known device. Usage: ./serveru-bpwd-ctl -r -d [i2c_address] -c [command] SMBUS read word data protocol Usage: ./serveru-bpwd-ctl -w -d [i2c_address] -c [command] -o [byte_data] SMBUS write byte data protocol Usage: ./serveru-bpwd-ctl -I -d [i2c_address] Get Bypass module information Global argument: -v: be verbose -h: help Here are some useful examples on how to use this utility - Query general running config information: ./serveru-bpwd-ctl -I -d 0x37 - Reset all bypass pairs to factory defaults: ./serveru-bpwd-ctl -w -d 0x37 -c 0x0A -o 0x00 - Save State to NVRAM: ./serveru-bpwd-ctl -w -d 0x37 -c 0x0B -o 0x00 CAUTION: NVRAM has a 10,000 write limit before start failing so make sure everything is working as you want before actually saving. For a complete list of commands see the introductory README bellow and once you fully understood how you should use this tool and what it can do, you may want to read ServerU-3rdGen-Bypass-Programming-ReferenceManual.pdf ============================================================================== INTRODUCTION UNDERSTANDING HOW 3RD GENERATION BYPASS WORKS ON SERVERU APPLIANCES ServerU appliances equipped with 2nd Generation bypass controllers like ServerU Netmap L-100 has BIOS configuration which allows basically for two states: - System OFF: configured bypass pairs are enabled and bypass is ON - Run-time: when kernel is compiled with Intel Watchdog support bypass is OFF while kernel is loaded and responsive. If kernel is not compiled with Intel Watchdog bypass is always OFF as long as power is ON. But ServerU appliances equipped with 3rd generation bypass controllers are like ServerU Netmap L-800 or ServerU Netmap L-400 with bypass enabled expansion cards have a much more complete and efficient fully programmable bypass interface. This generation has the following 3 cyclic states: (System OFF) => (Just-ON) => (Run-time) => (System OFF) Those 3 states mean: 1 - (System OFF): ServerU device is powered off or non energized 2 - (Just-ON): This is the brief moment when internal power supply is turned ON but operating system and driver is still not loaded 3 - (Run-time): Run-time is when the driver code is loaded, and the program can take over the bypass/watchdog functions. This state is active only when su_bpwd kernel module is loaded, otherwise we have a 4th state, the Unsupervised Run-time state. 4 - (U-Run-time): Unsupervised Run-time state is a non optimal run time state where the su_bpwd kernel module is not loaded. The default behavior for ServerU appliances are: - (System OFF): all bypass pairs are ON and bypass is Active - (Just-ON): all bypass pairs are OFF and bypass is Disabled, all watchdog timers are ON with 5 seconds timeout, it means bypass will be ON (Active) after 5 seconds of unresponsive kernel, ie kernel panic, system freeze or load average so high kernel becomes fully unresponsive. - (Run-time): exactly the same as (Just-ON) mode. - (U-Run-time): all bypass pairs are OFF and bypass is Disabled, all but since there is no kernel module, watchdog timers are always OFF meaning bypass will be Inactive forever while system is powered on and bypass will never be Active even on high load, freeze, panic or any other unhealthy condition on OS operation. We try to make the defaults safe and useful enough so you quite won't need to program your bypass. However you may want to change individual bypass pair timers or behavior on individual each one of the 3 supported ciclic states. For programming purposes we offer a utility called serveru-bpwd-ctl which has the following basic syntax: serveru-bpwd-ctl -w -d [i2c_address] -c [command] [-o ] For ServerU Netmap L-800 and for L-400 devices, [i2c_address] is usualy 0x37 while [command] is a long list of commands which can be on different modes. For commands on Write mode (W) one may want to provide additional data as [-o ] parameter on the above syntax. Command [command] itself is always a hex value, while modes can be: R = Read Only command W = Write Only command RW = Read/Write command The whole command list and it's function follows in table below: cmd mode description ------------------------------------------------------------------------------- 0x01 R Querying CPLD Major Version 0x02 R Querying CPLD Minor Version 0x03 R Querying Module Capability 0x04 R Querying Bypass Capability on System OFF state 0x05 R Querying Bypass Capability on JUST-ON State 0x06 R Querying Bypass Capability on Run-Time State 0x07 R Querying Maximum Level of Timer Interval for Watchdog1 (in run-time state) 0x08 R Querying Maximum Level of Timer Interval for Watchdog2 (in run-time state) 0x09 R Querying Maximum Level of Timer Interval for Watchdog3 in Just-on State 0x0A W Setting Modules Back to Factory Default 0x0B W Saving Current Settings to Flash 0x0C RW Querying Board ID 0x0F RW Enabling just-on bypass forcefully by simulating just-on instance 0x10 RW Querying and Setting Bypass Status in System-off State 0x11 RW Querying and Setting Bypass Status in Just-on State 0x12 RW Querying and Setting Bypass Status in Run-Time State 0x20 R Querying Watchdog1 Running Status 0x21 RW Setting Bypass Pairs When Watchdog1 Timer Expires 0x22 RW Querying and Setting Watchdog1 Timer 0x23 R Querying Time to Expiration of Watchdog1 Timer 0x24 W Starting Watchdog1 Timer 0x25 W Stopping Watchdog1 Timer in run-time State 0x30 RW Querying Watchdog2 Running Status 0x31 RW Setting Bypass Pairs when Watchdog2 Expires 0x32 RW Querying and Setting Watchdog2 Timer 0x33 R Querying Time to Expiration of Watchdog2 Timer 0x34 W Starting Watchdog2 Time 0x35 W Stopping Watchdog2 Timer in run-time State 0x40 R Querying Watchdog3 Running Status 0x41 RW Setting Bypass Pairs when Watchdog3 Expires 0x42 RW Querying and Setting Watchdog3 Timer 0x43 R Querying Time to Expiration of Watchdog3 0x45 W Stopping Watchdog3 Timer To disable all 4 bypass on run-time mode as well as just-on mode, set watchdog3 timer to 01 second and force just-on mode we can: ./serveru-bpwd-ctl -w -d 0x37 -c 0x41 -o 0x04 WRITE ADDRESS:0x37 Command:0x41 Data:0x 4...OK ./serveru-bpwd-ctl -w -d 0x37 -c 0x42 -o 0x01 WRITE ADDRESS:0x37 Command:0x42 Data:0x 1...OK ./serveru-bpwd-ctl -w -d 0x37 -c 0x11 -o 0x01 WRITE ADDRESS:0x37 Command:0x11 Data:0x 1...OK ./serveru-bpwd-ctl -w -d 0x37 -c 0x0f -o 0x02 WRITE ADDRESS:0x37 Command:0x11 Data:0x f...OK All ports will be disabled after and bypass mode will be immediately ON, you will notice all NIC port leds, both carrier sense and ethernet speed will be off and you will hear the relay click on electric interfaces or see the opto relay blink on fibre ports. How does it work? We have used command 0x41 in write mode find out which bypass pair we want to disable when Watchdog3 expires, we selected 0x04 for all four pairs. Later we used command 0x42, you can see by the command table what it does: it will set Watchdog3 value to 0x01 which means 1 in decimal. With command 0x11 we set Just-ON state to ON and with command 0x0f we forced Just-ON state. Now remember, if you reset your appliance or reboot it, Just-ON state is already set to 1 second and set to ON for all 4 ports and Just-ON state is forced ON, it means even after a reboot/reset all 4 ports will still be in bypass mode. To reset everything back to the default you may just check the initial examples and the 0x0A command on the above table and run it: ./serveru-bpwd-ctl -w -d 0x37 -c 0x0A -o 0x00 If you run it on your system booted you will immediately hear or see the relays getting turned off and you will see all NIC LEDs back on, the Operating System will again see the NICs as Active and everything will work back. Now with commands 0x21 and 0x22 we will set bypass Watchdog1 timers to 15 secs. ./serveru-bpwd-ctl -w -d 0x37 -c 0x21 -o 0x0f [enter] WRITE ADDRESS:0x30 Command:0x21 DATA:0x0f...OK Command 0x21 will set which bypass pairs will be Active when Watchdog1 expire, the entered value is 0x0f which means all bypass pairs according to the Manual you can check (ServerU-3rdGen-Bypass-Programming-ReferenceManual.pdf). Now with command 0x22 we will set Watchdog1 timer to 15 seconds, it's an easy task, 15 converted to hexadecimal is 0x0F so all we have to do is: ./serveru-bpwd-ctl -w -d 0x37 -c 0x22 -o 0x0f WRITE ADDRESS:0x30 Command:0x22 DATA:0x0f...OK Again: command 0x22 with 0x0f seconds. It means Watchdog1 will expire after 15 seconds. And which bypass pairs will be disabled when the timer expires? All 4 ports as we set on command 0x21. ABOUT WATCHDOG TIMERS Watchdog timers are independent and unrelated. You have 3 different timers which can be used on different States (run-time, just-on) and with different interface pairs. It means for example you can programm ServerU 3rd generation bypass pairs on a L-800 device to behave like this: 1 - (System OFF): only 3 bypass pairs will be Active It's important to be able to pick which pairs may be Active upon power off / system off to avoid loops for example. So let's say you have NIC pairs 1, 2 and 3 in a bridged environment which is just OK to be in bypass mode when system is off, but port pair 4 is has one port connected to the switch with a given IP address and the other port is connected to the switch with another given application IP address. If this port enters in Active bypass mode you will have a switch loop just like if both ends of a cable were connected to the switch. Programming which pairs you want bypass Active while powered off is good to avoid such a problem. 2 - (Just-ON): all 4 bypass pairs will be Active You've just started the system, operating system is not yet up and running but while it loads you may want to start network negotiation. 3 - (Run-Time): Watchdog1 is set to 5 seconds for NIC pair number 1 if system gets unresponsive for 5 seconds this bypass port will be ON (Active) and the bridge environment set by the OS will be replaced by an Active bypass. If system gets responsive again bypass mode may be OFF and the OS may work as a bridge again. 4 - (Run-Time): Watchdog2 is set to 10 seconds for NIC pair 2, let's say this port is not that critical and 10 seconds is acceptable to wait before entering Active Bypass mode. 5 - (Run-Time): Watchdog3 is set to 15 seconds for 3 NIC pairs, if it happens all selected NIC pairs may have bypass Active just like (System-OFF) state, even if system is powered ON and running, but something very serious happened just like a kernel panic, system unresponsiveness for over 15 seconds due to CPU extarvation or cooling temperature, or any other reason that the system simply became useless and kernel can't say "I'M ALIVE" to the hardware. In the above programmable situation, the 4th NIC port will never enter Active bypass mode because we want to avoid Switch loop under any possible situation. So you can have several timeout criteria for several running states on every single individual bypass port with ServerU Netmap series equipped with 3rd generation bypass interfaces. For a complete reference please see: ServerU-3rdGen-Bypass-Programming-ReferenceManual.pdf If you have doubts regarding any special condition which is not documented in this PDF file or any other question please open a Support Ticket. AUTHORS - Patrick Tracanelli - Jean Melo SUPPORT http://support.serveru.us support@serveru.us LICENSE This code is licensed under simplified BSD License, check the source files for terms. REVISION: v0.0.3 - Initial preliminary revision for early ServerU customers v0.0.9 - Prepare for public release v1.0.0 - Support FreeBSD 9, implement timer 2 and timer 3 v1.0.1 - Programmable Reference Manual in PDF is now available and both kernel module and utility reflects the manual. v1.0.5 - We have changed NVRAM defaults due to unsupervised Run-mode v1.0.6 - We now support the missing Just-ON state, not that useful but now fully supported. v1.0.7 - Updated the PDF manual with more examples and hex values refs, and make sure kernel module reflects the documentation and vice-versa. v1.0.8 - Completely give up on command names/alias and issue only hex commands. We have implemented all commands. Updated NVRAM to prepare for ServerU Netmap L-400 which will have bypass only on selected expansions. Proble if L-400 or L-800. v1.0.9 - Fix -I mode. Again fix some bugs for L-400 expansions and prepare for L-400 early adopters. L-100 is now unofficially EoL. Add FreeBSD 10 specifics support. v1.1.0 - Add FreeBSD 10 improvements and FreeBSD 11 support. Forget about versioning we now detect L-400 and L-800 automagically.