DigiBee Coding Guidelines

Version: 0.6

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 1
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 DOC NO: DGB-QP-QPD-0010-GD-2005
FILE NAME: DigiBee_coding_guidelines_0.6.doc
MARKETING STATUS: For Approval
NO:
FILING PATH: The repository Path
TITLE: DigiBee Coding Guidelines
ABSTRACT: This document presents the design and coding guidelines for development of
multimedia sub-system. The design guidelines focus on easy integration of
the sub-system to the system. The coding guideline focus on having a
common coding style across the team and on avoiding common
programming pitfalls by capturing the learnings.
KEY WORDS: Coding guidelines, Design guidelines, guidelines.

APPROVED BY: PREPARED BY:

Name: Name: Gomathi Sankar

Date: Date: Jul-13-2004

Name: Name: Satya Dev M.V.R

Date: Date: Jul-18-2004

Name:
Date:

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 2
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

AUTHOR INFORMATION

Author Designation Department Date Signature

Multimedia Systems
Gomathi Sankar Multimedia Jul-05-2004
Architect
Senior technical
Satya Dev Systems 18-Jul-2005
member

DOCUMENT APPROVAL

Name Designation Department Date Signature

Digibee
Balvinder Singh To be approved
Microsystems

REVISION HISTORY

Comments Date Revision

Initial draft Jun-21-2004 0.1
Review comments incorporated Jul-05-2004 0.2
Verified and approved Jul-13-2004 1.0
Changes in the guidelines related to commenting style and
Feb-01-2005 1.1
documentation guidelines added
Coding guide line which are common for all teams.
18-Jul-2005 0.1
Made document more generic to all teams.
FSM coding guidelines were added April 30, 2006 0.2
Reviewed by Dr. Shafi/Sharath/Girish April 30, 2006 0.3
Test script configuration guidelines have been included May 08, 2006 0.4
Modified the test script based on review comments 0.5
REVIEW DETAILS

Reviewer Comments Date Revision

Ashok
Muthukumar
Review comments enclosed as document Jul-01-2004 0.1
Saravanan
Balvinder
Satya
Ashok
Gomathi
Sankar
Balaji

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 3
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

TABLE OF CONTENTS
1 OVERVIEW.............................................................................................................................................................. 5
1.1 Scope & Objectives.......................................................................................................................................
Objectives....................................................................................................................................... 5
1.2 Document Conventions.................................................................................................................................
Conventions................................................................................................................................. 5
2 CODING GUIDELINES............................................................................................................................................ 5
2.1 Code Base Maintenance...............................................................................................................................
Maintenance............................................................................................................................... 5
2.2 File extension Conventions............................................................................................................................
Conventions............................................................................................................................ 6
2.3 Headers.........................................................................................................................................................
Headers ......................................................................................................................................................... 6
2.4 Assembly files Headers.................................................................................................................................
Headers................................................................................................................................. 7
2.5 Commenting style..........................................................................................................................................
style.......................................................................................................................................... 7
2.6 Text Formatting.............................................................................................................................................
Formatting............................................................................................................................................. 7
2.7 Header File organization................................................................................................................................
organization................................................................................................................................ 7
2.8 Variables........................................................................................................................................................
Variables........................................................................................................................................................ 7
2.9 Naming Convention.......................................................................................................................................
Convention....................................................................................................................................... 7
3 ANNEX A : DOCUMENTATION FOR DOXYGEN.................................................................................................... 7
3.1 Special documentation blocks.......................................................................................................................
blocks....................................................................................................................... 7
3.2 Documentation after members.......................................................................................................................
members....................................................................................................................... 7
3.2.1 Documentation at other places................................................................................................................. 7
3.2.2 List:........................................................................................................................................................... 7

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 4
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

DESIGN AND CODING GUIDELINES

1 Overview
This document describes C/C++/assembly language based coding standards and guidelines for
software development work within DGB Software Engineering group. The purpose of these coding
standards is to enhance consistency, readability, maintainability, and reusability of code. The
contents of this document are a bulleted summary of each of the concepts and a brief description of
each following them. This should be used as a reference guide. An effort shall be made at code
reviews and inspections to check to make sure that the coding standards are followed.
These standards are to be followed for all new code development in DGB. For code that we inherit
from other groups, we shall adhere to the coding standards followed by the originating group. In
terms of style, it should be difficult to determine what was written by DGB and the original code. An
exception to this is that additions and modifications must be well commented, regardless of how
much commenting the original code contains.

1.1 Scope & Objectives

The Software Coding document is designed for all DGB programmers regardless of their experience
level. It does assume, however, that the reader has a good working knowledge of the relevant
programming language and its libraries. It is important to note that these standards are intended for
Functional Validation code, which is an internal consumable, not intended for sale or distribution
outside of DGB.

1.2 Document Conventions

This document uses certain words to define guidelines, which imply the following meanings:
Shall Mandatory. Guideline is mandatory to be followed.
Will Recommended. Guideline is not mandatory, but recommended to be used as per
programmer’s choice
Can Optional. Guideline is neither mandatory nor recommended, but is optional.
This provides example implementations.

2 Coding Guidelines
2.1 Code Base Maintenance
[CG01] The modules, module names, files in each module, and file names
shall be identified at design cycle. Any change in this shall be discussed with the
team lead.
To avoid any uncontrolled development of code, at the design itself the module names and file
names are decided.
[CG02] The file names shall be in mixed case format, maximum of 32 ASCII
characters and has no white spaces. File and function names follow the convention of
XyzXxxxAbcd#, where the beginning Xyz is the module prefix and XxxxAbcd is the name. An underscore or
number cannot be the first character of either the module prefix or the name.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 5
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

Example: MemcpyCommonFunctions.c
Example: ChenDCT.c, MotionEstimation.c
[CG03] The code shall be organized should be followed as per the document
Configuration Management Plan Multimedia Cell Phone (MCP) – Software.

2.2 File extension Conventions

Pick filenames carefully that are clear, concise, consistent and closely matched to the file content.
Limit file name lengths to the number of characters appropriate for the development platform (e.g. 8
for a DOS environment). The following shows the file naming conventions:
File Type Name
C++ Source File <Filename>.cpp
C++ Header File <Filename>.h
C Header File <Filename>.h
C Source File <Filename>.c
Library File <Filename>.lib
Assembly Source File <Filename>.asm
Assembly Include File <Filename>.inc
Perl scricpt file <Filename>.pl

2.3 Headers
[CG04] All files shall have the copyright notice as given below at the
beginning of the file.
/*******************************************************************************
**
** Copyright (c) 2004 2005 by DigiBee Microsystems Pvt Ltd
**
** All rights are reserved. Reproduction in whole or in part is prohibited
** without the written consent of the copyright owner.
**
** DigiBee MicroSystems reserves the right to make changes without notice
** at any time. DigiBee Microsystems makes no warranty, expressed, implied
** or statutory, including but not limited to any implied warranty of
** merchantability of fitness for any particular purpose, or that the use
** will not infringe any third party patent, copyright or trademark.
** DigiBee Microsystems must not be liable for any loss or damage arising
** from its use.
**
** This Copyright notice may not be removed or modified without prior
** written consent of DigiBee Microsystems.
**
*******************************************************************************/
[CG05] All files shall have the header immediately after the copyright notice
as per the format given below
/*!
********************************************************************************
** \file Filename
** \brief
** This describes what functions this file does. For example,
** within a module or subsystem, what are the functionalities
** provided by this file.
** \date DATE (optional)
** \author

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 6
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

** AuthorName (optional)
** \par Histoty:
** - 23-Sep-2004
** - Authors
** - Reference
** .
** - Revision history shall be given in a free flowing text format
** in a short Paragraph.
** - 20-Sep-2004
** - Author
** - Initial Draft
** \note
** Any special comment (optional)
** \bug
** Any bug report. It will generate reference in bug list
** generated by doxygen (optional)
**
********************************************************************************
*/

[CG06] The revision history in the file header field shall be written in reverse
chronological order. The description shall be in brief.
/***************************************************************************
* RCS INFORMATION:
*
* $RCSfile: Filename,v $
* $Author: AuthorName $ $Locker: $ $State: Exp $
* $Revision: Revision Number $ $Date: YYYY/MM/DD HH:MM:SS $
*
***************************************************************************/

[CG07] All function definitions shall precede with a function header as per
the format given below.
/*!
* \brief Brief description of function
*
* \fn Function name (optional if block is place just before the fuction)
* Detail description goes here. Note: by default doxygen will make brief
* description, first sentence of detail description
* \param Parameter1 Detail of it (optional)
* \param Parameter2 Detail of it (optional)
* \param ParameterN Detail of it (optional)
* \return Detail of return value (optional)
* \bug Bug report (optional)
* \note Any comment (optional)
*/
[CG08] All definitions of structures, enums, and unions shall precede with a
header as per the format given below.
/*!
* \brief brief description
* of the .. ..
*
* more description
*
*/

Variables shall have comments in the following format

tS8 s8Var; //!< brief description of variable

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 7
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

A code-documentation tool such as “doxygen” can be used to generate documentation. The

commenting style given in [CG16] and [CG17] above caters to this requirement.
[CG09] All files shall end with one new line. This is to avoid warning
messages from legacy compilers.

2.4 Assembly files Headers

[CG10] All assembly compilers do not accept C style commenting. Assembly source / include files shall
have the copyright notice as given below.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; Copyright (c) 2004 2005 by DigiBee Microsystems
;;
;; All rights are reserved. Reproduction in whole or in part is prohibited
;; without the written consent of the copyright owner.
;;
;; Digibee MicroSystems Pvt Ltd reserves the right to make changes without notice
;; at any time. DigibBee Microsystems makes no warranty, expressed, implied
;; or statutory, including but not limited to any implied warranty of
;; merchantability of fitness for any particular purpose, or that the use
;; will not infringe any third party patent, copyright or trademark.
;; DigibBee Microsystems must not be liable for any loss or damage arising
;; from its use.
;;
;; This Copyright notice may not be removed or modified without prior
;; written consent of DigiBee Microsystems.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

[CG11] All Assembly source / include files shall have the header immediately after the copyright notice as
per the format given below

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; \file Filename
;; \brief
;; This describes what functions this file does. For example,
;; within a module or subsystem, what are the functionalities
;; provided by this file.
;; \date DATE (optional)
;; \author
;; AuthorName (optional)
;; \par Histoty:
;; - 23-Sep-2004
;; - Authors
;; - Reference
;; .
;; - Revision history shall be given in a free flowing text format
;; in a short Paragraph.
;; - 20-Sep-2004
;; - Author
;; - Initial Draft
;; \note
;; Any special comment (optional)
;; \bug
;; Any bug report. It will generate reference in bug list
;; generated by doxygen (optional)
;;

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 8
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
[CG12] All Assembly source / include files revision history in the file header field shall be written in reverse
chronological order. The description shall be in brief.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; RCS INFORMATION:
;;
;; $RCSfile: Filename,v $
;; $Author: AuthorName $ $Locker: $ $State: Exp $
;; $Revision: Revision Number $ $Date: YYYY/MM/DD HH:MM:SS $
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

[CG13] Parameters are passed through registers. Register name should be written clearly.
[CG14] It is functions responsibility to save (push and pop) all the registers which function uses as scratch
registers.
[CG15] Every source file should have proper Section begin Align Details
[CG16] All Assembly source / include files function definitions shall precede with a function header as per
the format given below.
[CG17] Jump Lables should of the format XyzXxxxAbcd#, where the beginning Xyz is the module prefix and
XxxxAbcd is the name. # is the number. An underscore or number cannot be the first character of either the
module prefix or the name.
[CG18] All Assembly source / include files function definitions shall precede with a function header as per
the format given below.

;;
; \brief Brief description of function
;
; \fn Function name (optional if block is place just before the fuction)
; Detail description goes here. Note: by default doxygen will make brief
; description, first sentence of detail description
; \param Parameter1 Register name (Should)
; \param Parameter2 Register name (Should)
; \param ParameterN Register name (Should)
; \return Detail of return value Register name (Should)
; \bug Bug report (optional)
; \note Any comment (optional)
;;

2.5 Commenting style

[CG19] Comments written for a line of code on the same line shall use //
commenting style.
Example:
int x; // This is a comment written for a line of code
[CG20] Comments spanning multiple lines shall use /* */ style. First line is ‘/*’
and last line is ‘ */’. Other lines shall start with ‘ *‘ (a white space followed by an
asterisk).
Example:
/*
* This is an example comment for
* multi line commenting in code

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 9
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

*/
[CG21] No Code segment shall be placed in the lines where multiple line
comments are placed.
Eg:
int * RxedPacket ; /* address for Rxed Packet
Has the constraints …. */
is not allowed. Do the same in following way.
/*
* address for Rx’ed packet
* has the constraints …
*/
int *RxedPacket ;
[CG22] Comments shall be included to explain the execution logic of the
code.
Comments need not explain the obvious in the code, which is best understood by C code it self.
Eg: for (i = 0; i < 30; i++) // Loop 30 times
The comment above is not necessary.
At the same time comment shall be included when the code is not easy to understand.
Eg: if ((x_coordinate < 0) || (y_coor < 0) ) // Point out of the range.
The above comment explains the meaning.
References to documents are allowed if it is hard to explain in comment.
Eg: fast_dct() // Implements DCT as per design doc “MPEG-4 design.doc”
[CG23] Programs may have a VERBOSE mode optionally enabled by a
preprocessor constant. When enabled the function entry, steps in function
execution, and function exit would be logged.
[CG24] Programs may have DEBUG mode optionally enabled by a
preprocessor constant. When enabled the assumed operating conditions are
verified.
[CG25] Programs may have a DATA_DUMP mode optionally enabled by a
preprocessor constant. When enabled the data is dumped. The details of this
functionality are identified at design level.
[CG26] Programs may have a PERF_CALC mode optionally enabled by a
preprocessor constant. When enabled the performance cycles are measured and
logged. The details of this functionality are identified at design level.
Example:
1. Project level the main include file has the following definitions
#define VERBOSE
#define DEBUG
#define DATA_DUMP
#define PERF_CALC

#ifdef VERBOSE
#define MODULE1_VERBOSE // for the modules define the macros
#define MODULEn_VERBOSE // one of these can be commented if that module is not under VERBOSE
#endif

#ifdef DEBUG

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 10
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

#define MODULE1_ DEBUG

#define MODULEn_ DEBUG
#endif

#ifdef DATA_DUMP
#define MODULE1_ DATA_DUMP
#define MODULEn_ DATA_DUMP
#endif

#ifdef PERF_CALC
#define MODULE1_ PERF_CALC
#define MODULEn_ PERF_CALC
#endif

#ifdef VERBOSE
#define LOG_VERBOSE(c) log_verbose(c)
#else
#define LOG_VERBOSE(c)
#endif

#ifdef DEBUG
#define ASSERT_PRECONDITION(cond)
assert(cond); // change it as u like it
#else
#define ASSERT_PRECONDITION(cond)
#endif

#ifdef DEBUG
#define ASSERT_POSTCONDITION(cond)
assert(cond); // change it as u like it
#else
#define ASSERT_POSTCONDITION(cond)
#endif

#ifdef DATA_DUMP
#define DUMP_ALL_DATA(ptrX, sizeOfX)
data_dump(ptrX, sizeOfX);
#else
#define DUMP_ALL_DATA(ptrX, sizeOfX)
#endif

#ifdef PREF_CALC
#define LOG_TIME_STAMP(TIMESTAMP_ID)
log_time_stamp(TIMESTAMP_ID);
else
define LOG_TIME_STAMP(TIMESTAMP_ID)
endif

2. In module level include file

#ifndef MODULE1_VERBOSE
#undefine LOG_VERBOSE(c)
#define LOG_VERBOSE(c)
#endif
and so on for DEBUG, DATA_DUMP, and PERF_CALC.

3. In the source file the function definition includes the following

int // return type SUCCESS or failure code

func1(
int x) // takes …
{
LOG_VERBOSE("Entering func1");

ASSERT_PRECONDITION((x < 0) || (x>428));

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 11
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

LOG_VERBOSE("Doing this functionality");

// Code to do the functionality

DUMP_ALL_DATA(&x,sizeof(x));

LOG_TIME_STAMP(Func1_ID);

ASSERT_POSTCONDITION((y>10));

LOG_VERBOSE("Exiting the function func1");

return SUCCESS;

4. Have header files FileDebug.h, FileVerbose.h, FileDataDump.h, and FilePerfCalc.h each having

#ifdef LOG_VERBOSE(c)
#undefine LOG_VERBOSE(c)
#endif
#define LOG_VERBOSE(c) log_verbose(c)

These files can be included when only one file is under VERBOSE. Similar to the example above, the other
DEBUG, DATA_DUMP, and PERF_CALC.
In these,
► VERBOSE mode is useful to trace the working path of the program.
► DEBUG mode is useful to check the assumptions made. This can also be success of memory
allocation, success of file opening, etc. When it is switched off the performance would he
higher.
► DATA_DUMP mode is useful in debugging.
► PERF_CALC mode is useful in calculating the performance at module level.

2.6 Text Formatting

[CG27] One line shall have one C line only. If a line of code can be split into 2
basic C lines without any impact on objectives, then the split version of the code
shall be included.
Eg: b = a++; is to be avoided as it contains 2 statements b = a; a++;. These 2 statements will be written
in 2 lines. But a=b=c=0; can be viewed as improving performance cycle, but it will be written in 3
separate lines, as most compilers would optimize the 3 lines in release mode.
[CG28] A line should have maximum of 80 characters wide.
[CG29] If a statement needs more than 80 characters, it is to be broken and
the continuation lines shall start with 3 indents with reference to the previous line.
[CG30] Line would end with maximum one white space.
[CG31] No tabs character is allowed in the program. Spaces shall be used for
indenting.
[CG32] An indent shall be 2 white spaces.
[CG33] Parenthesis ’(‘ and ‘)’ embedded in text shall have 1 white space
preceding the parenthesis and 1 white space after the parenthesis respectively.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 12
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

This follows the way English is written.

Example: for (i = 0; i < 30; i++)
There is no space after ( and before ).
[CG34] The curly braces ‘{‘ and ‘}’ at start and end of a code block shall be in
a separate line as compared to the code.
Example:
for (i = 0; i < 30; i++)
{ // this is in a separate line
x = i + y + 20;
// do the functionalities.
} // this is also in a separate line
[CG35] A code block within curly braces shall be indented once and follows
further indentation for any embedded code blocks.
for (i = 0; i < 30; i++)
{
x = i + y + 20; // this line is indented once
// do the functionalities.
If (condition)
{
x = y ; // this line is indented further
}
}
[CG36] A unary operator shall have no white space between the operator and
the operand
Example: i++; //++ is an unary operator, so no space between I & ++
[CG37] A binary operator shall have 1 white space preceding the operator
and 1 white space after the operator.
Example: i = 0; //= is a binary operator, so a space in both the places.
[CG38] Functions shall have return types explicitly given in the code.
Example:
abs(int x);
The above format is not allowed, rather use the following format.
int abs(int x);
[CG39] Function definition shall follow the following format
return type as the first line with a comment describing the return type,

 function name with opening brace in the second line,
 and the each arguments listed in a line with a comment describing
each argument. Arguments shall be indented 6 spaces with reference
to function name. Last argument will end with closing braces.
Example:
RetErr // error returning SUCCESS or FAILURE code
GetPacket (
UI32 ConnectId, // Connection Identifier
UI32 *RxedPacket ); // address of received packet

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 13
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

[CG40] The code block in the constructs ‘for’, ‘if’, ‘else’, ‘do-while’ and ‘while’
shall be embedded in curly braces, even when the block contains only one line.
Example:
for (i = 0; i < 30; i++)
{ // Though only one statement, put a {
if (condition)
{ // though only one statement put a {
x=y;
}
while ( TRUE == Condition )
{
/* Do something here */
...
...
}

do
{
/* Do something here */
...
...
} while ( Condition );
}
[CG41] The code associated with ‘switch’ construct shall be embedded in
curly braces.
switch ( Value )
{
case 1:
...
break;
case 2:
...
break;
default:
break;
}
[CG42] The “goto” construct shall not be used in C.
[CG43] A zero & non-zero condition checking shall be explicit.
Examples:
if (x) //this is not allowed as it assumes checking for non-zero value

if (x != 0) // this is allowed

2.7 Header File organization

[CG43] All header files shall be protected with an appropriate sentinel
( #ifndef…#define…#endif). The sentinel identifier shall have 2 parts, first part is
name of the file in all capital letters, and second part is _INCLUDED
Example:
#ifndef CHENDCT_INCLUDED
#define CHENDCT_INCLUDED

#endif
[CG44] The user-defined files shall be included in a file using the relative
path of the included file and file name.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 14
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

Example:
#include <UserDefined.h> // this is not allowed
#include “../dir1/UserDefined1.h” // this is allowed.
[CG45] Each project shall have a header file that is named in
<project>_exports.h. Any other project that wants to include the functionality of
this project shall include only <project>_exports.h
[CG46] The standard C includes, includes from external libraries, and any
macros / typedefs, as applicable, shall be organized in a central file
project_common.h
[CG47] All files shall be organized in the following order, as applicable
#includes project common.h
#includes from external modules of this project
#includes from current module
Conditional Compiles // #define DEBUG_MODE
Preprocessor Macros // eg: #define mNEGTIVE(x) (-(x))
Preprocessor constants // eg: #define LEN 255
Typedefs of structures
Typedefs of Enums
Typedefs of Unions
Global constants
Global variables
Function declarations
Function definitions
[CG48] Each Module, identified as part of design cycle, shall have a header
file that is named in the module_exports.h. Any other program that wants to
include the functionality of this module shall include only module_exports.h
[CG49] Each module shall have a header file named module_internal.h. The
first include file in module_internal.h is module_exports.h. All .h files as part of the
module shall be included in the module_internal.h.
[CG50] The module_intenal.h shall be the only included header file in all the
files in the module.
[CG51] C file shall not be included in any programs. Only h files shall be
included.
[CG52] Preprocessor conditional compiles, constants and macros that are
identified at design level shall only be used. Developer shall discuss with tech
prime to define other preprocessor constants or macros. This includes anything to
do with #define.
[CG53] Preprocessor conditional compiles, constants shall be in all capital
letters.
[CG54] Preprocessor Macro shall start with letter M and contains all capital
letters followed by this letter. Multilane macros should use a block of their own.
Example:
#define M_MEMCPY_ENABLE_READ() ((*(volatile WORD *)MEMCPY_ENABLE) |= 0x1)

#define M_MACRO(x) \
do { \
some c statement; \
some other c statement; \
} while (0);

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 15
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

2.8 Variables
[CG55] Data types defined in C shall not be used in its original form. The
header file “common.h” defined as part of this document contains the following
data types for use in the program.

Table 1: Platform independent data types definition

Data Type for use in Description
programs

tU32 unsigned long

tS32 signed long
tS16 signed short
tU16 unsigned short
tS8 signed char
tU8 unsigned char
Void Void
Char char(This is defined for use
in strings or characters.)
Float float
double Double
The data types void, char, float and double are not modified as they are platform independent.

[CG56] User defined structures, enums, and unions shall be type defined.
[CG57] User defined Structures, enums and unions shall be identified at
design level and only those without any modifications shall be used. Developer
shall discuss with technical prime to define any new ones or any modifications.
[CG58] All global and static variables shall be explicitly initialized.
[CG59] UI32 shall be used for variables having bit-wise functionality. If it is
used for values it shall be discussed with technical prime.
This is to avoid any failure of logic when it is used for comparison. When a UI32 is compared with
SI32 variable the SI32 is upgraded to UI32. When SI32 holds a negative value the upgradation
results in a wrong huge value leading to failure of the comparison.
[CG60] Each variable shall be defined in a line separate of other variables.
Example:
tS32 x_coor, y_coor; // this is not allowed

/* Instead of the above us the following */

tS32 x_coor;
tS32 y_coor;

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 16
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

[CG61] Each variable definition shall have a comment describing the

variable.
Example:
tS32 x_coor; // x coordinate
tS32 y_coor; // y coordinate
[CG62] At the place of memory allocation a comment shall be placed
identifying memory release associated with it.
Example:
Arr = (char *) malloc( 10 * sizeof(char));
/* This variable “Arr” is used in 2 functions func1 & func2
** Mem release happens once the function completes the use
** Both functions releases this memory before return */

2.9 Naming Convention

[CG63] Names of typedefined structures, enums, and unions shall start with
prefix Ts, Te, and Tu respectively.
Example:
Typedef struct
{
tU32 *NextElemAdd; // Next element address
tS32 RollNum; // Roll number
tU8 Name[255]; //Name of the person
} TsEmployee;
[CG64] Names of functions, variables, structures, enums, and unions shall
be descriptive. It can use mixed case format.
[CG65] Variable names shall have prefixes indicating the datatype of the
variables as per the table.
Table 2: Prefixes for variables
DATA TYPE PREFIX EXAMPLE

tU32 u32 u32Number

tS32 s32 s32Number
tS16 s16 s16Number
tU16 u16 u16Number
tS8 s8 s8Number
tU8 u8 u8Number
Void v * vpVoidPointer;
Char c cCharac;
Float f fNumber;
Double d dNumber;
File pointer hfl_ *hfl_FilePointer;
Function pointer hfn_ (*hfn_s32MyCallback)(tS32);
Pointer to standard type, p *pcMyName;
structure/typedef, or a class

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 17
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

Array a as32NumberList[10];
char acAlphabet[26];
Global variable g_ G_flRandomSeed;
Static Variable s_ S16 s_s16CurrentState;
Register variable r_ S32 r_s32Count;
Constant k_ S8 k_s8InitialState;
Notes:
Combining two or more prefixes is allowed. Example: pa is pointer to an array.
A string is given with prefix ac (array of characters), which is null terminated string.
Function pointers and file pointers are treated as handles.
User defined data types and handled may be assigned with non-clashing prefixes.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 18
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

3 Annex A : Documentation for Doxygen

3.1 Special documentation blocks
For file description, function details etc we will use special documentation blocks commenting style.
These blocks will start with “/*!” and end with “*/” [Doxygen few other style for these blocks].
These blocks should be put before the member to be documented.

3.2 Documentation after members

These blocks can only be used to document members and parameters. Some examples as follows
SI08 s8Var; /*!< Detail description after member */
SI08 s8Var; //!< Detail description after member
//!<
SI08 s8Var; //!< Brief description after member

3.2.1 Documentation at other places

Above two required that documentation blocks be put near the blocks or variable to be documented.
Doxygen allows putting documentation blocks anywhere by including structural element inside the
documentation block. Some of structural elements as follows:
\class to document a class
\struct to document a C-struct.
\union to document a union.
\enum to document an enumeration type.
\fn to document a function.
\var to document a variable or typedef or enum value.
\def to document a #define.
\file to document a file.
\namespace to document a namespace.
\package to document a Java package.
\interface to document an IDL interface.
3.2.2 List:
Doxygen also support including list (unordered list and ordered list) and in side the documentation
blocks. Here is example
/*!
* - First Item
* - Second Item
* -# Numbered First Item
* -# Numbered second\n
* item
* - Third Item
*/
Here is another example
/**
* Text before the list
* - list item 1
* - sub item 1

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 19
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

* - sub sub item 1

* - sub sub item 2
* .
* The dot above ends the sub sub item list.
* More text for the first sub item
* .
* The dot above ends the first sub item.
* More text for the first list item
* - sub item 2
* - sub item 3
* - list item 2
*.
* More text in the same paragraph.
*
* More text in a new paragraph.
*/
We will use these commenting styles for including those comments into doxygen documentation.
Normal commenting should be use, for comment not to be included in doxygen-generated
documentation like comment to explain flow of codes.
Don’t use doxygen commenting style to explain the flow of code.
Some of structural commands that can be use in side the documentation.
\n Generate newline
\b word using bold face for word (word)
<b>….</b> bold face for more than one word.
\c word typewrite font for word (word)
\e or \em word for emphasizing (italic face) the word (word)
There are number of HTML commands, which can be use inside the doxygen documentation. Pl.
refer to help in doxygen for the same.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 20
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

4 Annex B : Coding Practices for FSM implementation

4.1 Directory Organization
[CG_FSM_01] The directory structure as defined in CM plan should be followed. As per the CM plan
each directory may have src, include, and build directories. The entity / module (eg: MMF) has
submodules (eg mp3player, jpegviewer, etc.) maintained in separate directories.
[CG_FSM_02] Each entity / module / submodule should have the exported .h files only in the top
level include directories. The entity / module / submodule user should not be bothered about internal
dir structure.
[CG_FSM_03] Each module or submodule should have only a static library in the build directory.
Another win32 console application should be created in the UT directory to test the static library.
This organization enables including the static libraries without any change during integration testing.

4.2 File organization

[CG_FSM_04] Every .c file should have a corresponding .h file with the same name. All exported
symbols from the .c file should be declared in the .h file. Symbols internal to a file should be defined
with "static" and declaration should be there in the .c file.
[CG_FSM_05] Entity/src should have entity.c. Entity initialization and deinitialization functions should
be placed in them.
[CG_FSM_06] Entity initialization should call all the component initialization functions.

4.3 Component Organization

[CG_FSM_07] Every Component should have a <component>_cmpid.h where the components are
defined.
[CG_FSM_08] Every component has a <cmp>_cmp_init function and a corresponding
<cmp>_cmp_deinit function. These functions should be placed in <cmp>.c file. <cmp>.c should be
placed in the entity/src directory.
[CG_FSM_09] The cmp_init function should
- create message queue
- initialize a component
- Initialize the FSMs
- Register all the FSMs
- Register the component
- Start the component
[CG_FSM_09a] Initialization and registering of FSM should be carried out individually ( without a
“for” loop).
The first argument “name” for dgb_CreateMessageQ() should be a seven lettered globally unique
symbol . This is introduced so that debugging is ARM is easy.
The last argument to dgb_CreateMessageQ() must be sizeof(tMsg).
DigiBee Microsystems Inc.
Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 21
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

The name element in component context structure should be a string representation of the
component id tag.
The name element in fsm context structure should be a string representation of the FSM id tag.

4.4 FSM Organization

[CG_FSM_10] Every Entity should have a <entity>_fsmid.h. This shall include
<entity>_<fsm>_fsmid.h files of all the FSMs defined as part of the entity.
[CG_FSM_11] Every FSM should have a <entity>_<fsm>_fsmid.h, where the fsmid is defined.
[CG_FSM_12] Every FSM should have a <fsm>_fsm_init and a <fsm>_fsm_deinit functions. These
functions should be placed in <fsm>_fsm.c. <fsm>_fsm.c should be placed in the <submodule>/src
directory.
[CG_FSM_13] The <fsm>_init function should
- initialize the FSM
- initialize the s/w module by allocate memory for the context and initialize the context.
[CG_FSM_14] State handlers for the FSM should be placed in <fsm>_fsm.c.
[CG_FSM_15] Message handlers should be placed in <fsm>_<state>.c
[CG_FSM_16] The module code should also be placed along with the associated message handlers
in <fsm>_<state>.c. Module code can also be split into multiple files having <fsm>_<state>_ as
prefix.

4.5 Message organization

[CG_FSM_17] Every entity should have a <entity>_msgid.h, which includes the
<entity>_<fsm>_msgid.h files of all the FSMs defined as part of the entity.
[CG_FSM_18] Every FSM should have a <entity>_<fsm>_msgid.h, where the message ids of the
FSMs are defined.
[CG_FSM_19] Every message should be associated with a message structure. The name of the
message structure should be ts<msg_name>
[CG_FSM_20] FSM should have a <entity>_<fsm>_msg_structs.h, where the message structures
associated with the messages external to the entity are defined.
[CG_FSM_21] FSM should have a <entity>_<fsm>_imsg_structs.h where the message structures
associates with the messages internal to the entity are defined.
[CG_FSM_22] Message structures should not have any pointers.

4.6 Handler Organization

[CG_FSM_23] State handler should be named <fsm>_<state>_hdlr.
[CG_FSM_24] Message handler should be named <fsm>_<state>_<msg >_hdlr. Message handler
should get a pointer to the message as a parameter. Ideally it should return error code.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 22
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

4.7 Memory management

[CG_FSM_25] Every fsm should have a structure within which all its global variables are collected.
The structure name should be ts<fsm>_context. This structure should be placed in a file called
<fsm>_context.h.
[CG_FSM_26] A pointer to context structure should be defined in <fsm>_context.c file. This context
should be allocated memory and initialized in the <fsm>_init function and deallocated memory in the
<fsm>_deinit function.
[CG_FSM_27] When initializing the context datastructure, Initialize every structure within the context
structure.
[CG_FSM_28] The context structure should be allocated memory statically. This will peg the
maximum memory requirements.
[CG_FSM_29] Any memory allocation and memory deallocation should be co-located within the
same block of conditional branches within the same function. Exceptions to this guideline are (a) the
memory allocated for messages which shall be deallocated by the DGBFW (b) memory allocated in
the initialization function which shall be deallocated in the deinit function and (c) Data path memory
allocations.
[CG_FSM_30] All signaling / control path memory allocation should use
mMALLOC_MMFCONTROL(), which uses MMF_CONTROL_MEMORY_TYPE as memory type.
[CG_FSM_31] All data path memory allocation should use mMALLOC_MMFDATA(), which uses
MMF_DATA_MEMORY_TYPE

4.8 Header file organization

[CG_FSM_32] Every module should have a <module>_error_codes.h which defines the error codes
exported from the module.
[CG_FSM_33] Every module should have a <module>_common.h.
[CG_FSM_34] Every module should have a <module>_exports.h, which shall include the exported
symbols form the module to the module-users.
[CG_FSM_35] Every .c file in the module/submodue should include only the <module>_common.h
file.
[CG_FSM_36] Every .h file in the module/submodule should not have #include. (Except on the
<module>_common.h file where only other files are included.)
[CG_FSM_37] The <submodule>_common.h shall include the files in the following order
 Standard C include files
 Entity Configuration files (if any)
 Common include across the entities/modules
 Exported include files from the entity/module
 Exported include files across the submodules of the entity/modules
 include files internal to the entity/modules

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 23
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

4.9 Debug Organization

[CG_FSM_38] At the entity level, there should be a <entity>_log_domains.h files, which shall include
the log domains of all the submodules.
[CG_FSM_39] Every module should have a <module>_log_domains.h file, in which the log domain
for the module is defined.
[CG_FSM_40] There should not be any active code for checking (a) debug conditions or (b) variable
bounds or (c) any non-conformant behavior of functions. Active error checking shall be done only
on errors in the input conditions and environmental conditions.

4.10 Timer Management

[CG_FSM_41] Timer expiry processing should occur in the module's own thread context.
Framework Timer callback should do very minimal activity so that the main activity can be performed
in the module's own thread context.

4.11 Test script organization

[CG_FSM_42] Test scripts are to be placed in a directory named as test_scr under the ut or it or st.
[CG_FSM_43] The initial set-up needed for starting the testing (ie before sending the first message)
should be placed in a subroutine called <FSM>_prologue.
[CG_FSM_44] The de-initialization should be placed in a subroutine called <fsm>_epilogue.
[CG_FSM_45] Sending a message should be placed in a subroutine.
[CG_FSM_46] Verifying the expected result of a message for a given state should be placed as a
subroutine for generic results. For testcase specific verification of the expected result can be placed
as part of the testcase.pl as a subroutine at the end of the test script.
[CG_FSM_47] Each test case (identified as part of the test planning) should have a separate file
with name same as test case id.pl. This should call the prologue, send message, verify expected
result, and epilogue subroutines. The .pl file can be invoked by a test master script.
The scripts should not expect any user input.
The test case execution should be written as a subroutine and should be invoked as a subroutine
call.
The test case verification should be done by a separate subroutine and should be called after the
completion of the test case subroutine.
Each test case execution should leave a trace that is examined by the validation routine to decide
whether the case passed or not.
The validation should not be done in the execution subroutine but in a seperate subroutine. This
ensures a logical separation between the execution of the test case and the validation of the
outcome.
While creating and documenting test cases as part of test plan, care should be taken to ensure that
the document format permits easy automation of test script generation.
Before starting a batch testing process the scripts should verify the environment to check for
presence of test vectors, test case scripts, syntax check of the test scripts etc.

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 24
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.
 Project: Multimedia Customer: Internal
Design and Coding Guidelines

There should be control over which test cases should be executed. It should not be assumed that
the selection is always a range of numbers. The selection of test cases to be run must be taken from
a testing-scope-selection file that is input to the master test script. If the testing-scope-selection file
is not provided then the test script should run all test cases in a predefined directory (or set of
directories).Use of hardcoded parameters in the individual script should be avoided. (For
example :the parameters are like test-vector name file name, duration/s of seek for audio files, LCD
configuration etc.) A configuration file should be used where these parameters are defined and the
values should be picked up from therein.
Guidelines for porting to ARM
If code depends upon size of enum (i.e. size in bytes); Assume it to be int (4 byte).

The enclosed function library may be used for the defined purpose

sub Turn_Off_All_Log_Domains To turn off all log domains

sub Turn_On_All_Log_Domains To turn on all log domains

sub Log_Domain_Cfg To configure a log domain

sub Log_Domain_Off To turn off a log domain

sub Log_Domain_On To turn on a log domain

sub Log_Level_Cfg To configure log level

sub ReRoute To reroute messages

sub Msg_Send To send message

sub Receive_Msg To receive message

sub Wait_For_Msg To wait for message

sub PrintWaitCR To wait for <enter> input from user

sub WaitUser To wait for user input

sub GetConsoleInp To get user input

sub WaitEvent To wait for an event

Sub_str2a_char

Sub_a_char2str

DigiBee Microsystems Inc.

Ref: DGB-QP-QPD-0010-GD-2005 Rev. 0.1 July 18, 2005 Page 25
Confidential
C o p y r i g h t DigiBee Microsystems Inc. – 2 0 0 4 , 2 0 0 5
This document CONFIDENTIAL and PROPRIOTARY and is for internal use only. Not for customer distribution.