[openib-general] OpenSM Coding style

[Eitan Zahavi]

Hi,

Unlike the kernel code that adhere to the LINUX kernel coding style,
OpenSM uses coding style that was developed by Intel during the IBAL code
development.
Although being different then the Kernel style OpenSM style is extensive and
strictly followed
during the several years of its development. 
It is needless to say keeping a standard coding style is important to any
project (especially the side of OpenSM).

The full list of rules is presented below. I think we should keep it as
OpenSM is a user level project that is mature. 
The point is that we MUST make sure any new code added is following the
current coding style. 
Even if we later decide to use the kernel style (which I doubt the need for)
we have to keep the current rules.

Some automaton for checking for these rules and fixing violations is
provided by the script osm_check_n_fix.
The following emacs automation can also be used for indentation rule and
some simple fixes

Apparently the new osm_vendor_umad.* code breaks some of the rules. I hope
we can agree to fix these violations.

Thanks

Eitan Zahavi

OpenSM Coding Style Rules
----------------------------------------
OpenSM incorporates a coding style that includes the following rules:
1.	Use { } on a separate line then the if and else 
2.	Use function declaration/definition style that includes:
a.	A standard header that is readable by robodoc
b.	Each parameter is defined on its own line and indented by 2 spaces.
c.	Use IN or OUT or IN OUT prefix for each parameter
3.	Each struct also have a typedef with the format :
typedef struct _x {...} x_t;
4.	Logs:
a.	Most functions that have access to the log object use :
OSM_LOG_ENTER( p_log, <function name>);
and 
OSM_LOG_EXIT( p_log );
b.	The following log verbosity levels are defined:
OSM_LOG_ERROR	- report fabric response errors or any abnormal algorithmic
condition (see c).
OSM_LOG_INFO - Information regarding major results of fabric initialization
and SA operations
OSM_LOG_VERBOSE - Detailed information of initialization activities and SA
operations
OSM_LOG_DEBUG - Even more information - intended for debugging of OpenSM
OSM_LOG_FUNCS - ENTER and EXIT function only
OSM_LOG_FRAMES - MAD contents
OSM_LOG_ROUTING - Dump out routing results.
OSM_LOG_SYS - Information that should go into /var/log/messages
c.	ERROR messages should be numbered by the following rule: 
<module code 2 hex digits><serial err number in the module>
An example error statement should look like:
osm_log( p_log, OSM_LOG_ERROR, "<function name>: ERR 1B02: "
                "Error Init of qlock pool (%d).\n",  status  );
Module codes are unique to each C file. 
d.	Any message should include the function name it is part of. For
example:
osm_log( p_log, OSM_LOG_DEBUG,
               "__add_new_mgrp_port: "
               "create new port with proxy_join FALSE\n");
5.	Each module should have a module header (see osm_base.h for example)
describing the module intent, thread safety opacity, etc.
6.	Usage of TABs is not allowed. Indentation is 3 space instead. This
provides "editor invariable" behavior. 
7.	No spaces at end of line.

EMACS Rules Enforcement Automation
--------------------------------------------------------
;; prevent emacs from using tabs during identation
(setq indent-tabs-mode nil)
(setq-default indent-tabs-mode nil)
(custom-set-variables
'(tab-width 3)
'(tcl-continued-indent-level 3))

;; making C style like OpenSM :
(defun my-c-mode-common-hook ()
  ;; my customizations for all of c-mode, c++-mode, objc-mode, java-mode
  (c-set-offset 'substatement-open 0)
  (c-set-offset 'arglist-intro '+)
  ;(c-set-offset 'arglist-cont 0)
  ;; other customizations can go here
  )
(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)

;; utilities for C file indentation etc
(defun kill-oel-spaces ()
  (interactive)
  (goto-char 1)
  (replace-regexp "[ \t]$" "")
  )

(defun untabify-buffer ()
  (interactive)
  (end-of-buffer)
  (untabify 1 (point) )
  )

(defun indent-buffer ()
  (interactive)
  (end-of-buffer)
  (indent-region 1 (point) nil)
  )

(defun fix-brace-on-if-statements ()
  (interactive)
  (goto-char 1)
  (replace-regexp "^\\([ \t]*if.*\\)[{]" "\\1
{")
  )

(defun fix-brace-on-else-statements ()
  (interactive)
  (goto-char 1)
  (replace-regexp "^[ \t]*[}][ \t]+else+[ \t][{]" "}
  else
   {")
  )

(defun beauty-c-buffer ()
  (interactive)
  (fix-brace-on-if-statements)
  (fix-brace-on-else-statements)
  (indent-buffer)
  (kill-oel-spaces)
  (untabify-buffer))

Eitan Zahavi
Design Technology Director
Mellanox Technologies LTD
Tel:+972-4-9097208
Fax:+972-4-9593245
P.O. Box 586 Yokneam 20692 ISRAEL


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openfabrics.org/pipermail/general/attachments/20050820/93db8627/attachment.html>