Monday, March 21, 2016

During Software/Firmware development process, Quite often we found ourselves in a very cumbersome task called "documentation of code". Sometimes, it can be time-consuming and boring also. Fortunately, There are various tools available today, that make this process easy for developers. Doxygen is one them.

Doxygen is a very useful tool to generate documentation of source code. It supports C/C++, Objective C, C#, Java, Python, PHP and many other programming languages.

How doxygen works ?

In order to generate documentation using doxygen tool, programmers need to embed special tags in code comments that can later be extracted to create documentation of code. The comments will be recognized by doxygen tool only when it is written is specific format like below.

or or

For one-line comments use following format.
To put documentation after members use following format. Below are list of most useful tags (specifically useful for C language) that is recognized by doxygen tool. This tags are embedded inside special multi-line comments shown above.

@file <file name>

This tag make comments for a source file or header file.

@author <author name>

This tag puts name of author in documentation.

@version <version number>

This tag puts version details of file/project in documentation.

@date <date>

This tag puts date of file creation/edition in documentation.

@brief <description string>

This tag puts one-liner description of file/function/function macro in documentation.

@defgroup <group tag> <group tag string>

This tag defines new logical group (or simply a module) that is represented and referenced by <group tag> in source code and it is mentioned by <group tag string> in documentation. This tag is like opening bracket of a code block in C language. This tag must be closed by a corresponding closing bracket doxygen code.

@addtogroup <group tag>

This tag extends commenting details of the code block to already defined logical group in documentation.

@note <note string>

This tag puts note above function.

@todo <todo string>

This tag is useful to remind todo items in source code that also get mentioned in documentation.

@param <function parameter> <parameter description>

This tag puts description of function parameter in documentation.

@retval <return value description>

This tag puts description of return value of a function in documentation.

Following example will give more robust idea about how to use doxygen for code documentation.

example.c

example.h

Once you install doxygen on development machine, it provides GUI frontend for doxygen to configure and generate documentation thourgh easy to use tool called 'Doxywizard'.
The steps to generate documentation using doxywizard is highlighted in below snapshots.




Following snapshot is generated output html of document. It is interlinked and fully browsable like a website.

Happy coding and do visit again :-)

Saturday, November 7, 2015

What is a toolchain ?

Toolchain is a specific set of software development tools (with combination of pre-processor, compiler, linker, assembler, debugger, library etc) designed to run on specific host platform (often x86 & x86_64) and generates binaries/output files for specific target platform(e.g. x86, ARM, MIPS etc). A toolchain can have multiple language compilation support (C, C++, Java, Ada, Objective-C etc).

Compilation & Cross-compilation

If the host and target platform are same(i.e. normal software development) than the process of generating binaries/output files is called compilation. If host and target platforms are different e.g. host platform is x86 and target platform is ARM then the process of generating binaries/output files is called cross-compilation.

The GNU toolchain


The toolchains are provided by the manufacturer of chip(e.g. ICC) with proprietary licence with multi-choice purchase options or third-party (e.g. GCC) with open source licence for free.
The choice of toolchain depends on project goals & costs. Often GNU toolchain wins the favor among developers because of free availability, "cross-platform"ness, with multiple platform support and huge open source community support. we will focus on GNU toolchain only.
The GNU toolchain for C langauge contains following components:
  • Compiler (GCC), Debugger (GDB)
  • extra tools (binutils - assembler, linker etc)
  • C library (glibc, ulibc or newlib depending on target platform)

The name convention of GNU toolchain

The loose representation for GNU toolchain name convention is as below:

arch[-vender][-os]-abi-toolname

arch - architecture: ARM, x86, MIPS etc.
vendor - tool chain provider: nxp, unknown, mingw32
os - operation system: linux, none(bare-metal)
abi - application binary interface: eabi, gnueabi, gnueabihf
toolname - the name of perticular program or utility: gcc, gdb, ld etc

Let take different toolchains for example to understand it better:
arm-none-eabi-<toolname> = ARM architecture, no vendor(omitted here), runs without                                                                                     OS(bare-metal), eabi type
arm-none-linux-gnueabihf-<toolname> = ARM architecture, no vendor, runs on linux,                                                                                                GNU abi with hard-floating point support

How to install GNU toolchain

The GNU toolchain required for any project can be downloaded from various websites and installed. Often, The first step is to figure out "which" toolchain you actually need. there are various vendors providing toolchains. GNU (official), codesourcery, linaro to name a few. So, for example you want to cross-compile a C program for beagle-bone black development board (it has ARM Cortex-A8 microprocessor) running linux OS, you will need arm-linux-gnueabihf/arm-none-linux-gnueabihf (assuming the linux kernel and other components on BBB are cross-compiled with hard floating support).

Assumptions:
  • The target board is BBB (i.e. architecture is Cortax-A8)
  • host OS is linux
Steps to install GNU toolchain (from linaro):

  • Go to https://www.linaro.org/downloads/
  • Go to section "Linaro toolchain for Cortax-A"
  • Download linaro toolchain binaries (Little-endian) Linux, you will have gcc-linaro-X.X-XXXX.XX-x86_64_arm-linux-gnueabihf.tar.xz file
  • Open terminal and type
  • To add toolchain in path, type
  • Test the toolchain (the output may differ depending on your toolchain version)
Happy coding !!!

Monday, June 1, 2015

When dealing with any Microprocessor or Microcontroller datasheet, we often encounter "register" word. So, what is it exactly ?

Let's get started.

Register is a form of temporary memory available inside Microprocessor/Microcontroller to store/hold values. The register can be found similar to other memory types available i.e. RAM or cache. But, registers are used for many different purposes and A register read/write access is a lot faster because registers are tightly coupled with CPU. Width of these registers (8-bits/16-bits/32-bits) is Dependant on the architecture of Microprocessor/Microcontroller.

Further more, These registers are combined in different categories based on their purpose/usage. Although all architectures(Microcontrollers/Microprocessors) are different, Many categories are commonly found inside them. Thus, Registers can be roughly categorized as follows.


  1. General Purpose Registers(GPR) - These registers can be used to read/write data/addresses. They mostly come with read/write access. They are frequently used to hold temporary values and results. e.g. In a C program for Microcontroller, Declaring a variable with "register" storage class specifier will tell the compiler to put the variable inside one of many GPRs. Although this is not guaranteed by compiler that it will put in variable in GPR only, it can place it in RAM also.
  2. Addess Registers (AR) - These registers are used to access indirect memory e.g.In a C program for Microcontroller, A variable declared with "const" storage class specifier is mostly stored in non-volatile memory. i.e. Flash memory. So, To access the data from the address inside flash memory, these register can be used.
  3. Floating Point Registers(FPR) - These registers may not be found in all Microprocessors/Microcontroller architectures. These registers are used to carry out floating point operations.
  4. Conditional Registers(CR) - These registers holds many valuable conditions in bit forms(e.g. Zero flag, Carry flag, Overflow flag etc.). These bits are used to create decision to whether execute certain operations or not.
  5. Special Purpose Registers (SPR) - As the name suggests, these registers are build to serve special purposes. and often come with Read-only/Write-only or Read-Write configurations. e.g. The Microcontroller has specific registers to operate its USART peripheral like Status register, Data transmit register, Data receive register, Configuration register etc.

Hope you enjoyed the article :-)

Thursday, May 28, 2015

Anyone who is interested in Embedded field, had worked with one Microcontroller at least. Whether it be a AVR, PIC, 8051 or ARM based. These all Microcontrollers have one thing in common : GPIO Pins

GPIO simply means General Purpose Input Output.

Now, The GPIO can be used to turn ON/OFF LED or reading proximity sensor etc. GPIO can be used as either 'Output' or 'Input' pin.

Below are the typical Modes and their sub-types for a Microcontroller GPIO Pin.

Input Mode

GPIO Input mode can be basically two types:
  1. Pull up/Pull down - In pull up configuration, the pin will remain high, until it is driven low externally. In pull down configuration, the pin will remain low, until it is driven high externally.
  2. High Impedence/Tri-State/Floating - In this mode, The pin state is indeterministic unless it is driven high or low externally.

Output Mode

GPIO Output mode can be basically two types:
  1. Open-Drain - The name of this mode has its roots to MOSFET. They are used inside the Microcontroller to implement GPIO pin. In this mode, the physical GPIO pin behaves same way as drain of MOSFET. The drain is open to connect it to any external element. The source is grounded and gate of internally driven. It has two states: either High-impedance or Low. The output pin is driven low by firmware, The voltage at pin is zero. When the output pin is driven high by firmware, The voltage can be either high or low. It is mostly used for I2C bus where external pull-up resisters are used widely. It can be also used in Interrupt line where it is connected to multiple interrupt sources.
  2. Push-Pull - In this mode, The voltage of pin is deterministic. When the output pin is driven low by firmware, The voltage is zero. When the output pin is driven high, The voltage is 3.3/5V (based on which technology microcontroller build upon i.e. CMOS/TTL)

Sunday, November 24, 2013


Introduction

Often, there are times when you got stuck with some C source code trying to find out bug inside, inefficient code, or simply want to understand how program works.
In this situations, having a function call graph for source code may be very helpful to solve the problem.

Function call graph

Function call graph is graph or structural representation that shows how functions call each other. It can be dynamic or static.

Dynamic function call graph

The Dynamic function call graph describes the execution of the program. So, it depends on run-time conditions, events, inputs and so on. To sum up, dynamic graph can be different for each run(execution of program) and useful to study run-time behavior of a program. Dynamic function call graph be only generated after execution or simulation of program.

Static function call graph

The other type is static function call graph. As oppose to dynamic type, which depends on various run-time conditions, static function call graph covers all possible the situations that can occur. This can be generated without execution or simulation of program.

Below procedure describes how to generate static function call graph. Following things are needed prior to begin.
  • The C source code of program
  • Development PC with Linux (Preferably Ubuntu)
  • GCC compiler or Cross-compiler based on GCC
  • Egypt
  • Graphviz


How it Works?

All the C source code files are given to the GCC compiler or GCC based cross-compiler as input. The compilation is done with "-fdump-rtl-expand" flag which tells compiler to generate dump file in form of Register Transfer Language (RTL). RTL is one of the internal representation of C source code used by GCC during compilation process of program.
Compiling with above flag generates ".expand" file for every corresponding C file. This .expand file is then fed into Egypt. Egypt is a Perl script that generates .dot file with DOT language(Graph Description Language) for given .expand file.
Finally, This .dot file is given to dot program (a component of Graphviz) to generate the graph in visual image format.

Procedure

I have created small bash program called "gengraph". which does all above described work in quiet manner.

You can download it from here. or get it by following procedure on terminal as below.
If all goes right then, you can see below output by typing 'gengraph' in terminal.
Now, installation is completed successfully. The temp-directory contains gengraph, other files and example directory. This example directory contains following files which are used to show output of gengraph here.
main.c file1.c file1.h file2.c file2.h
Now, To use gengraph program, open a terminal and type.
This will generate a image file final.png in same directory as shown below.

gengraph can generate image file type as ".png", ".jpg", ".ps", ".pdf" or ".svg". You can get help by typing 'gengraph -h' command.
Note that gengraph assumes that your source code compiles well without any error. So, you might consider using gengraph after successful compilation of code.

I hope this article helps you to understand generation and usage of function call graph. The next time, I will come up with some more interesting topic. Till then, Happy codding !!!


Sunday, November 10, 2013


TIA-232-F commonly reffed as RS232, is a serial protocol which found many personal computers, networking equipments or in industrial machines. It is a full-duplex (Data can be sent bidirectionally any time) communication protocol and point-to-point interface, at speed up to 115.2 Kbps with proper grounding and short distance between devices.

An RS232 is asynchronous bus. That means the data can be sent any time without any timing restriction. Thus, it does not contain any clock signal. But, To communicate without any errors, two devices must have some set of rules to follow. RS232 facilitates the communicates with use of bits and baud rate. There are start bit, data bits, parity bit and stop bit. This bits and baud rate must be same for two devices.

Valid values are here below:

 
Data Bit 5 to 9
Parity Bit NONE/EVEN/ODD/MARK/SPACE
Stop Bit 1/1.5/2
Baud Rate 50 to 1000000

In RS232, a signal below -3V is considered as logical 1 and above +3V is considered as logical 0. and signal between +3V to -3V is considered as undefined.

Sender send data with start bit which is always logical 0, then followed by data bits and at last stop bits which is always logical 1. Below is the typical example for sending data with 8 data bits, No parity bit and 1 stop bit (Commonly known as "8N1").

Signals for data 0xCB (11001011)

The 8N1 configuration is most commonly used in today's devices. Older devices operates on low baud rate and stop bit used are 1.5/2. parity bit is used some times, as it provides error indication. If parity bit is in use then the parity bit is inserted between end of data bit (bit 7) and stop bit. For even parity, if numbers of logical 1 bit in data is a even value then even parity bit will be 0, other wise 1. For odd parity if numbers of logical 1 bit in data is a odd value then odd parity bit will be 0, other wise 1. although parity provides error detection when any one bit is changed in data, this method fails if even numbers of bit changed. So, they are rarely used. and Mark/space parity type also does not help in error detection thus, never used.

The RS232 protocol defines complete specification for standard, this includes electrical, physical and mechanical specification. Although standard defines DB-25 connector and 25 signals for RS232 protocol, the non-standard version with DB-9 connector having 9 signals is most commonly used today.


DB-9 connectors (Male & Female) 

Pin Description and functioning for both connectors are listed below:


Pin No. Description Function
1 Data Carrier Detect (DCD) DTE input, data link established, also
known as Receive Line Signal Detect (RLSD)
2 Received Data (RD) DTE input data
3 Transmitted Data (TD) DTE output data
4 Data Terminal Ready (DTR) DTE output, device ready
5 Ground provides a Zero reference voltage
6 Data Set Ready (DSR) DTE input, DCE is ready to communicate
7 Request to Send (RTS) DTE output, DTE would like to transmit
8 Clear to Send (CTS) DTE input, DCE is ready to transmit
9 Ringing Indicator (RI) DTE input, announces incoming call


What is DTE and DCE ?

Data Terminal Equipment (DTE) is typically either a dumb terminal or the serial port on a computer/workstation.
Data Communications Equipment (DCE) is typically a modem, DSU/CSU, or other piece of data communications equipment.

How connections are established between a DTE and DCE ?

The pin specifications of RS232 are written from the perspective of DTE end of link. so, the output from DTE becomes a input to DCE. Thus, Transmitted Data (TD) is a output signal for DTE, but it becomes a input signal for a DCE.
To connect a DTE and DCE, we just need a straight (pin-to-pin) cable. If we want to connect two DTE with each other then, a cross-over cable is required. this just makes each DTE feel that it is connected to a DCE at other end.

I hope this article helps you in better understanding of RS232 protocol. Keep visiting !!!

Thursday, September 12, 2013


 "Wire", "Bus" or "Port", this are the words we often encounter when reading any technical book or manual related to computer architecture.

So, Let us discuss how they differ each other and what exactly they mean.

Wire - It is just a passive physical connection with least resistance. it can be a copper wire or a PCB track connecting two different nodes. it provides a physical path for current to flow, thus making a connection between two nodes.

Bus - A group of signals (such as data, address etc). It may be augmented with buffers latches etc. A bus has standard specification such as number of bits, clock speed etc. Bus can be viewed as a set of different signals that provides unique logical functionality. example of bus are SPI (Serial Peripheral Interface Bus)  which is a serial bus with 4 signals namely CLK, MOSI, MISO and SS'. other example for Bus are I2C, PCI, ISA etc.

Ports - Port is a set of physical wires available so that any device which meets the specified standard can be directly plugged in. Examples are serial, parallel and USB port on personal computers.

I hope reading this article has been helpful to you. Keep visiting !