Example of function declaration and function definition

4.2.2 Applying Prototypes

Function prototypes extend function declaration to include the formal parameters. For example, if the my_function() function, discussed in the previous section, requires two integer parameters, the declaration could be expressed as follows:

return_type my_function(int x, y);

where int x, y indicates that the function requires two parameters, both of which are integers. Note that the variable names x and y are optional, formal parameters. The actual parameter names in the function definition and subsequent calls need not be the same; only the types must match. Using meaningful formal parameter names is helpful in documenting the functionality.

Because the declaration includes parameters, the compiler can check whether calls to this function are made properly. If, for example, the following call is made:

a=my_function("hello world");

the compiler generates an error informing you that my_function was called with an incorrect number of parameters (one instead of two) and an incorrect first parameter (i.e., an integer was expected but a string was received instead).

Note that C automatically performs some forms of type conversions to ensure that actual parameters match the declared type of a function’s formal parameters. Character variables (char), for example, are automatically promoted to integer (int) for parameter passing and arithmetic.

7.1.1 Subprograms in Package Declarations

Another kind of declaration that may be included in a package declaration is a subprogram declaration—either a procedure or a function declaration. This ability allows us to write subprograms that implement useful operations and to call them from a number of different modules. An important use of this feature is to declare subprograms that operate on values of a type declared by the package. This gives us a way of conceptually extending VHDL with new types and operations, so-called abstract data types, a topic we return to in Chapter 12.

An important aspect of declaring a subprogram in a package declaration is that we only write the header of the subprogram, that is, the part that includes the name and the interface list defining the parameters (and result type for functions). We leave out the body of the subprogram. The reason for this is that the package declaration, as we mentioned earlier, provides only the external view of the items it declares, leaving the implementation of the items to the package body. For items such as types and signals, the complete definition is needed in the external view. However, for subprograms, we need only know the information contained in the header to be able to call the subprogram. As users of a subprogram, we need not be concerned with how it achieves its effect or calculates its result. This is an example of a general principle called information hiding: making an interface visible but hiding the details of implementation. To illustrate this idea, suppose we have a package declaration that defines a bit-vector subtype:

subtype word32 is bit_vector(31 downto 0);

We can include in the package a procedure to do addition on word32 values that represent signed integers. The procedure declaration in the package declaration is

procedure add ( a, b : in word32;

                result : out word32;  overflow : out boolean );

Note that we do not include the keyword is or any of the local declarations or statements needed to perform the addition. These are deferred to the package body. All we include is the description of the formal parameters of the procedure. Similarly, we might include a function to perform an arithmetic comparison of two word32 values:

function “<” ( a, b : in word32 ) return boolean;

Again, we omit the local declarations and statements, simply specifying the formal parameters and the result type of the function.

subprograms in Package Declarations

Another kind of declaration that may be included in a package declaration is a subprogram declaration—either a procedure or a function declaration. This ability allows us to write subprograms that implement useful operations and to call them from a number of different modules. An important use of this feature is to declare subprograms that operate on values of a type declared by the package. This gives us a way of conceptually extending VHDL-AMS with new types and operations, so-called abstract data types, a topic we return to in Chapter 20.

An important aspect of declaring a subprogram in a package declaration is that we only write the header of the subprogram, that is, the part that includes the name and the interface list defining the parameters (and result type for functions). We leave out the body of the subprogram. The reason for this is that the package declaration, as we mentioned earlier, provides only the external view of the items it declares, leaving the implementation of the items to the package body. For items such as types, natures, signals and terminals, the complete definition is needed in the external view. However, for subprograms, we need only know the information contained in the header to be able to call the subprogram. As users of a subprogram, we need not be concerned with how it achieves its effect or calculates its result. This is an example of a general principle called information hiding: making an interface visible but hiding the details of implementation. To illustrate this idea, suppose we have a package declaration that defines a bit-vector subtype:

We can include in the package a procedure to do addition on word32 values that represent signed integers. The procedure declaration in the package declaration is

Note that we do not include the keyword is or any of the local declarations or statements needed to perform the addition. These are deferred to the package body. All we include is the description of the formal parameters of the procedure. Similarly, we might include a function to perform an arithmetic comparison of two word32 values:

Again, we omit the local declarations and statements, simply specifying the formal parameters and the result type of the function.

5.1.1 A Little More on Libraries and Packages…

We've already seen some examples of libraries and packages usage introduced in the previous loops. Let's take a moment to review…

A package is a specific VHDL construct. A package may define new types and subtypes, constants, component declarations, function declarations, and procedure declarations (which

Sidebar 5.1

Reuse in “Real-Life”

Reuse is a beautiful thing, but how is it implemented in the “real-world”?

There are a number of companies which produce and sell IP. Their job is to write specific forms of IP for sale to designers that require complex and very specific forms of IP. Typically these “cores” sell for between $5,000US and up with many of the cores residing in the $20,000US –$50,000US range. Some examples of these cores include PCIe DMA controllers and root complexes, specialized video interfaces such as Display Port and DVI. Despite the seemingly large price tag on these cores, it is often less expensive to purchase such a core than it is to develop it “in-house” as it will take several months (if not years) to develop and require a group of engineers who have the detailed knowledge of the core that is to be developed. Consider: $50,000US is only 50 man-days of labor or less than 2 man-months. Factor in verification on top of coding and delay to the project delivery and one can quickly see that the price tag is “cheap” compared to internal development.

Another form of reuse is through the IEEE and other organizations. Typically, the IEEE doesn't provide IP per se, but rather provides collections of packages that support specific tasks. This book relies heavily on the std_logic_1164 and numeric_std packages from the IEEE library in order to manage multi-valued logic and the plethora of conversion and mathematical operations that can be performed on them.

Vendors typically offer their own libraries and packages to support their silicon products. Libraries such as Xilinx's UNISIM and SIMPRIM are collections of silicon “primitives” for the various Xilinx FPGA families and are provided within Xilinx's development environment.

Larger (or more formalized) companies, especially where ASIC and FPGA have been designed for many years, often implement their own internal libraries and generally place these libraries on servers where their employees can access them. These libraries and packages will often have their own test benches associated with them so that they can be verified against new versions of various tools. Formal company processes (such as including documentation and test benches) generally exist prior to a package being added to the collection to ensure consistent use and proper behavior of the packages throughout the company.

Small teams within the company may share “packages” in a more informal fashion, whether it be on an internal network or a “sneaker-net”. More often than not, these don't enjoy the formalization process which includes documentation and test benches.

Then there is you. Even if a package is not shared with others, it should still be documented and have its own test bench as you will likely be using it for years! (If you used it once – you'll use it again!)

behave as function prototypes from C/C++). Typically a package is associated with a package body. The “package body” is a secondary construct and cannot exist without a package.

The package body contains only the functions and procedures required to support those functions and procedure definitions declared in the package. The package body may also include functions and procedures, such as “function ‘D’” in Figure 5.2, used to support the functions and procedures declared in the package, but not available to the user.

A library is a collection of packages. The specific means of implementing libraries is not covered in the VHDL specification and left to the vendors to implement as they wish. As a result, the physical structure of the working directory and the libraries may be inconsistent among the various vendors. Some vendors structure libraries as directories and physically place the associated packages into that directory, while other vendors choose to keep all the packages in the same physical directory and group the packages logically into libraries. The user may impose his or her own file system structure on the libraries and convince the tools to access these libraries appropriately.

There are two steps that are required for using a library. The first step is to declare the library for use. The syntax is quite simple:

where <library name> is a legal identifier corresponding to an available library. If the library is not available in the workspace the tools will indicate an error and analysis will not continue.

Once the library is announced, the packages within that library become available with the following statement:

where:

<library name> is a legal library name that has already been made accessible with the “library” statement,

<package name> is a legal name of a package contained within the library called out in <library name>,

<content specifier> is either the keyword “all” which makes the entire contents of the package available to the design or it may be a single member within the package. A single member may be an individual constant, type, function or procedure definition, etc.

If there are multiple items within a package that are to be used, but not all items in the package, then multiple “use” statements may be utilized to enumerate each desired item. This is often done to avoid conflicts between package members or just desiring to be specific.

More commonly, the entire package is made available by using the keyword “all” as the <content specifier>. When the “all” is specified, every component definition, type and subtype definition, function and procedure declaration, and constant definition can be seen by the module in which it was specified (and ONLY the module in which it was specified). Every VHDL module where the contents of a library/package must be seen must contain the library and all the necessary use definitions.

Allowing access or visibility into a package does not cause the design to run slower or consume more resources. Items in the packages are incorporated into the design only when they are specifically used.

There are two exceptions to the library declaration and use statements. These two libraries that are always available to the designer and do not need to be explicitly declared. They are the STD library which automatically uses the STANDARD package. This package defines integers, reals, bit, bit_vectors, and other basic data types. This package does NOT include the commonly used std_logic/std_logic_vector types.

The other library is named “WORK”. This is the default library in which all codes exist when not explicitly placed into another library.

Explicitly listing the WORK and STD libraries is unnecessary, but is legal and should not pose any problems.

Resolving conflicts between packages

Sometimes packages carry duplicate definitions. Perhaps there are constants that are named the same, but have different definitions, or there might be functions and procedures that may have identical names and arguments.

The following example demonstrates a conflict between two packages containing several constants (see Snippets 5.3 and 5.4).2

Snippet 5.3. Packages with Some Overlapping Constants.

Snippet 5.4. Both Packages Loaded with “All” Cause Conflict.

Code analysis:

Line 1: the Library WORK is defined. Recall that WORK is one of the two libraries that is automatically declared. This line of code can be omitted with no ill effects.

Line 2: all of the members of Package1 are made available.

Line 3: all of the members of Package2 are made available.

Lines 5–9: describes the interface to the outside world. In this case all the signals are outputs. The integer range will be rendered as a number of wires, in this case, most likely 6 bits – 1 bit for sign, 5 bits to represent the maximum (and most negative maximum) values.

Line 13: Which K0 is used? The one from Package1 or the one from Package2? Since VHDL refuses to make any kind of assumption as to what the designer coded, the “compiler” will issue an error indicating that there is a conflict which must be resolved on this line.

One way to resolve this conflict is to call out all the members of the package that don't conflict, or more efficiently, only the members of that package which are used (see Snippet 5.5).

Once could also select the individual members from Package2 in the same fashion. This is enough to resolve the issue.

Snippet 5.5. Solution #1 - Limiting Members from Package-1.

Consider: what if there were a thousand constants in each package and most were used? This would make for an extremely tedious task!

Fortunately, we can create aliases for these items. Aliases are used to rename items for both ease of use and conflict resolution. By explicitly calling out only the non-duplicate names, this conflict can be easily resolved.

We will use the following structure for the alias:

Snippet 5.6.

In this way, the full name of the item is spelled out and this resolves the naming conflict while providing a meaningful name for ease of use and clarity (see Snippet 5.7).

Snippet 5.7. Using Aliases to Resolve Package Conflicts.

Code analysis:

Line 1: library WORK is declared. This is unnecessary as WORK is always available.

Line 2: all members of package1 are made available for use.

Line 3: all members of package2 are made available for use.

Line 12: a unique name is assigned to the full path from the library, through the package, down to the specific element. Since both packages refer to K0, the tools have no idea which K0 to use and the tools will throw an error. After this alias is defined, the K0 from package2 can be accessed by using the name the_K0_I_really_want.

Code snippets

Code snippets are incomplete pieces of logic which represent a frequently used construct. Theoretically, these could be turned into components, functions, or procedures; however, the designer either doesn't want to go through the trouble, or the snippet must be tweaked for the application and there is no easy way of making the code “generic”.

Since there is no formality to snippets, it is up to the designer to provide some type of snippet management. The easiest way is to set aside a directory and place the snippet and explanatory code into a text file and name it something recognizable. The snippet can then be cut-and-pasted into a VHDL source file.

Creating Help

You have used help with built-in functions, such as

help linspace

You can build help text into your functions as well. This is done by inserting comments on the second line, immediately under the function declaration. All comments between the function declaration and the first line of executable code are returned to the command window when the user types

help functionName

where functionName is the name of the function in the function declaration, which is the same as the name of the function’s file.

Building on the previous example:

function I = ISolveFunction(V, R)

% ISolveFunction finds current given voltage and resistance

% I = ISolveFunction(V, R)

I = V./R;% this is Ohm's Law V=I R solved for I

If this is saved as ISolveFunction.m, when the user types

help ISolveFunction

The command line window will return

ISolveFunction finds current given voltage and resistance

I = ISolveFunction(V, R)

Note the extra blank line that was added inside the program. matlab ignores blank lines, so they can help to organize your program into logical blocks, like the help and code areas in this example.

Practice Problems

Create a commented function F2C() that converts a temperature in Fahrenheit to a temperature in Celsius. It should run using the command F2C(32), for example, which will return 0. The conversion formula is C=59(F−32).©

The function should implement help; when the user types

help F2C

the following is returned to the command line:

F2C returns a temperature in Celsius given a temperature in Fahrenheit.

3.2.6 Static Variables in Functions

Normally, the variables used in functions are local to the function and they are reinitialized (usually to zero) when the function is called. There are some applications however where we may want to preserve the values of some or all of the variables inside a function declaration. This is done using the static statement. An example function code is given below. Here, variable Total is initialized to 0 using the static keyword. Notice that the variable is incremented by one before returning from the function. What happens now is that every time the function is called, variable Total will retain its previous value. Thus, on the second call, Total will be 2, and on the third call, it will be 3 and so on:

void Sum(void)

{

      static Total = 0;

      ………………

      ………………

      Total++;

}

5.4.4 Static Variables in Functions

Normally, the variables used in functions are local to the function and they are re-initialised (usually to 0) when the function is called. There are some applications, however, where we may want to preserve the values of some or all of the variables inside a function declaration. This is done using the static statement. An example function code is given below. Here, variable Total is initialised to 0 using the static keyword. Notice that the variable is incremented by 1 before returning from the function. What happens now is that every time the function is called, variable Total will retain its previous value. Thus, on the second call, Total will be 2, on the third call it will be 3, and so on:

2 Rule 8.1: Functions shall have prototype declarations and the prototype shall be visible at both the function definition and call

The MISRA informative discussion for this rule includes the sound recommendation that function prototypes for external functions be declared in a header file and then included by all source files that contain either the function definition or one of its references. It should be noted that a MISRA checker might only validate that some prototype declaration exists for calls to a function. The checker may be unable to validate that all references to a particular function are preceded by the same prototype. Mismatched prototypes can cause insidious bugs, which is worse than not having any prototype.

For example, let’s consider the following C function definition and code reference, each located in a separate source file:

File1:

void read_temp_sensor(float ∗ret)

{

 ∗ret = ∗(float ∗)0xfeff0;

}

File2:

float poll_temperature(void)

{

 extern float read_temp_sensor(void);

 return read_temp_sensor();

}

The preceding code fragments are perfectly legal ANSI/ISO C. However, this software will fail since the reference and definition of read_temp_sensor are incompatible (the former is written to retrieve the return value of the function, and the latter is written to return the value via a reference parameter).

One obviously poor coding practice illuminated in the preceding example is the use of an extern function declaration near the code containing the reference. Although strict ANSI C requires a prototype declaration, the scope of this declaration is not covered by the specification. MISRA rule 8.6, “functions shall be declared at file scope,” attempts to prevent this coding pitfall by not allowing function declarations at function code level. However, the following code fragment would pass this MISRA test yet fail in the same manner as the preceding example:

  extern float read_temp_sensor(void);

 float poll_temperature(void)

 {

  return read_temp_sensor();

 }

While MISRA does not explicitly disallow function declarations outside header files, this restriction is an advisable coding standard addition. Declaring all functions in header files certainly makes this error less likely yet still falls short: the header file containing the declaration may not be used in the source file containing the incompatible definition.

There is really only one way to guarantee that the declaration and definition prototypes match: detect incompatibilities using a program-wide analysis. This analysis could be performed by a static code analyzer or by the full program linker/loader. We describe the linker approach here for illustration of how a high-quality tool chain can be critical to enforcing coding standards. When compiling the aforementioned code fragment, the compiler can insert into its output object file some marker, such as a special symbol in the symbol table or a special relocation entry, that describes the signature of the return type and parameter types used in a function call. When the function definition is compiled, the compiler also outputs the signature for the definition. At link time, when the final executable image is being generated, the linker/loader compares the signature for same-named functions and generates an error if any incompatible signature is detected. This additional checking should add negligible overhead to the build time (the linker already must examine the references of functions to perform relocation) yet guarantees function parameter and return type compatibility and therefore improves reliability and quality of the resulting software.

One major advantage of the link-time checking approach is the ability to encompass libraries (assuming they were compiled with this feature) whose source code may not be available for static analysis.

What is function declaration with example?

What is function declaration and function definition?

What is the difference between declaration and definition of a function explain with example?

What is function explain the function definition & function declaration with relative example?