x-coding3.html

vxworks相关论文

<ul class="Bullet" type="disc"><li><a name="84603"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Passing and Returning Structures:</b></font>&nbsp;&nbsp;Always pass and return pointers to structures. Never pass or return structures directly.</li></ul>
</p>
<p class="listspace">
<ul class="Bullet" type="disc"><li><a name="84604"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Return Status Values:</b></font>&nbsp;&nbsp;Routines that return status values should return either <b class="symbol_UC">OK</b> or <b class="symbol_UC">ERROR</b> (defined in <b class="file">vxWorks.h</b>). The specific type of error is identified by setting <b class="symbol_lc">errno</b>. Routines that do not return any values should return <b class="keyword">void</b>.</li></ul>
</p>
<p class="listspace">
<ul class="Bullet" type="disc"><li><a name="84605"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Use Defined Names:</b></font>&nbsp;&nbsp;Use the names defined in <b class="file">vxWorks.h</b> wherever possible. In particular, note the following definitions:</li></ul>
</p>
<dl class="margin">

<ul class="DashSingle2" type="circle"><li><a name="84606"> </a>Use <b class="symbol_UC">TRUE</b> and <b class="symbol_UC">FALSE</b> for boolean assignment.</li></ul>
<ul class="DashSingle2" type="circle"><li><a name="84607"> </a>Use <b class="symbol_UC">EOS</b> for end-of-string tests.</li></ul>
<ul class="DashSingle2" type="circle"><li><a name="84608"> </a>Use <b class="symbol_UC">NULL</b> for zero pointer tests.</li></ul>
<ul class="DashSingle2" type="circle"><li><a name="84609"> </a>Use <b class="symbol_UC">IMPORT</b> for <b class="keyword">extern</b> variables.</li></ul>
<ul class="DashSingle2" type="circle"><li><a name="84610"> </a>Use <b class="symbol_UC">LOCAL</b> for <b class="keyword">static</b> variables.</li></ul>
<ul class="DashSingle2" type="circle"><li><a name="84612"> </a>Use <b class="symbol_UC">FUNCPTR</b> or <b class="symbol_UC">VOIDFUNCPTR</b> for pointer-to-function types.</li></ul>
</dl>

</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="84613">I.3.7  &nbsp;&nbsp;C Header File Layout</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84615"> </a>Header files, denoted by a <b class="file">.h</b> extension, contain definitions of status codes, type definitions, function prototypes, and other declarations that are to be used (through <b class="keyword">#include</b>) by one or more modules. In common with other files, header files must have a <i class="emphasis">standard file heading</i> at the top. The conventions in this section define the header file contents that follow the standard file heading.</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H4"><i><a name="84616">Structural</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84617"> </a>The following structural conventions ensure that generic header files can be used in as wide a range of circumstances as possible, without running into problems associated with multiple inclusion or differences between ANSI C and C++.</p>
</dl>

<dl class="margin">

<p class="listspace">
<ul class="Bullet" type="disc"><li><a name="84618"> </a>To ensure that a header file is not included more than once, the following must bracket all code in the header file. This follows the standard file heading, with the <b class="keyword">#endif</b> appearing on the last line in the file.</li></ul>
</p>
<dl class="margin">

<dd><pre class="Code2"><b><a name="84619">#ifndef __INCfooLibh 
#define __INCfooLibh 
    ... 
#endif /* __INCfooLibh */</a></b></pre>
</dl>

<dl class="margin">

<dd><div class="Indent"><a name="84623"> </a>See <a href="x-coding3.html#84537"><i class="title">I.3.5&nbsp;C Naming Conventions</i></a>, for the convention for naming preprocessor symbols used to prevent multiple inclusion.</div>
<br>
</dl>

<p class="listspace">
<ul class="Bullet" type="disc"><li><a name="84624"> </a>To ensure C++ compatibility, header files that are compiled in both a C and C++ environment must use the following code as a nested bracket structure, subordinate to the statements defined above:</li></ul>
</p>
<dl class="margin">

<dd><pre class="Code2"><b><a name="84625">#ifdef __cplusplus 
extern "C" { 
#endif /* __cplusplus */ 
    ... 
#ifdef __cplusplus 
} 
#endif /* __cplusplus */</a></b></pre>
</dl>

</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H4"><i><a name="84626">Order of Declaration</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84627"> </a>The following order is recommended for declarations within a header file:</p>
</dl>

<dl class="margin">

<p><ol class="List"><li value="1)"><a name="84628"> </a>Statements that include other header files.</li></ol></p>
<p><ol class="List"><li value="2)"><a name="84629"> </a>Simple defines of such items as error status codes and macro definitions.</li></ol></p>
<p><ol class="List"><li value="3)"><a name="84630"> </a>Type definitions.</li></ol></p>
<p><ol class="List"><li value="4)"><a name="84631"> </a>Function prototype declarations.</li></ol></p>
</dl>

</dl>

<h4 class="EntityTitle"><a name="84632"><font face="Helvetica, sans-serif" size="-1" class="sans">Example I-4:&nbsp;&nbsp;Sample C Header File</font></a></h4>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84633"> </a>The following header file demonstrates the conventions described above:</p>
</dl>

<dl class="margin">

<dd><pre class="Code"><b><a name="84634">/* bootLib.h - boot support subroutine library */ 
 
/* Copyright 1984-1993 Wind River Systems, Inc. */ 
 
/* 
modification history 
-------------------- 
01g,22sep92,rrr&nbsp;&nbsp;added support for c++. 
01f,04jul92,jcf&nbsp;&nbsp;cleaned up. 
01e,26may92,rrr&nbsp;&nbsp;the tree shuffle. 
01d,04oct91,rrr&nbsp;&nbsp;passed through the ansification filter, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-changed VOID to void 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-changed copyright notice 
01c,05oct90,shl&nbsp;&nbsp;added ANSI function prototypes; 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;added copyright notice. 
01b,10aug90,dnw&nbsp;&nbsp;added declaration of bootParamsErrorPrint(). 
01a,18jul90,dnw&nbsp;&nbsp;written. 
*/ 
 
#ifndef __INCbootLibh 
#define __INCbootLibh 
#ifdef __cplusplus 
extern "C" { 
#endif /* __cplusplus */ 
 
/*  
 * BOOT_PARAMS is a structure containing all the fields of the  
 * VxWorks boot line. The routines in bootLib convert this structure 
 * to and from the boot line ASCII string. 
 */ 
 
/* defines */ 
 
#define BOOT_DEV_LEN            20      /* max chars in device name */ 
#define BOOT_HOST_LEN           20      /* max chars in host name */ 
#define BOOT_ADDR_LEN           30      /* max chars in net addr */ 
#define BOOT_FILE_LEN           80      /* max chars in file name */ 
#define BOOT_USR_LEN            20      /* max chars in user name */ 
#define BOOT_PASSWORD_LEN       20      /* max chars in password */ 
#define BOOT_OTHER_LEN          80      /* max chars in "other" field */ 
#define BOOT_FIELD_LEN          80      /* max chars in boot field */ 
 
/* typedefs */ 
 
typedef struct bootParams&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* BOOT_PARAMS */ 
    { 
    char bootDev [BOOT_DEV_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* boot device code */ 
    char hostName [BOOT_HOST_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* name of host */ 
    char targetName [BOOT_HOST_LEN];&nbsp;&nbsp;&nbsp;&nbsp;/* name of target */ 
    char ead [BOOT_ADDR_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* ethernet internet addr */ 
    char bad [BOOT_ADDR_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* backplane internet addr */ 
    char had [BOOT_ADDR_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* host internet addr */ 
    char gad [BOOT_ADDR_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* gateway internet addr */ 
    char bootFile [BOOT_FILE_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* name of boot file */ 
    char startupScript [BOOT_FILE_LEN];&nbsp;/* name of startup script */ 
    char usr [BOOT_USR_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* user name */ 
    char passwd [BOOT_PASSWORD_LEN];&nbsp;&nbsp;&nbsp;&nbsp;/* password */ 
    char&nbsp;other&nbsp;[BOOT_OTHER_LEN];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* avail to application */ 
    int&nbsp;&nbsp;procNum;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* processor number */ 
    int&nbsp;&nbsp;flags;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* configuration flags */ 
    } BOOT_PARAMS; 
 
/* function declarations */ 
 
extern&nbsp;STATUS&nbsp;bootBpAnchorExtract (char * string, char ** pAnchorAdrs); 
extern&nbsp;STATUS&nbsp;bootNetmaskExtract (char * string, int * pNetmask); 
extern&nbsp;STATUS&nbsp;bootScanNum (char ** ppString, int * pValue, BOOL hex); 
extern&nbsp;STATUS&nbsp;bootStructToString (char * paramString, BOOT_PARAMS * 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pBootParams); 
extern&nbsp;char&nbsp;*&nbsp;bootStringToStruct (char * bootString, BOOT_PARAMS * 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pBootParams); 
extern&nbsp;void&nbsp;&nbsp;&nbsp;bootParamsErrorPrint (char * bootString, char * pError); 
extern&nbsp;void&nbsp;&nbsp;&nbsp;bootParamsPrompt (char * string); 
extern&nbsp;void&nbsp;&nbsp;&nbsp;bootParamsShow (char * paramString); 
 
#ifdef __cplusplus 
} 
#endif /* __cplusplus */ 
 
#endif /* __INCbootLibh */</a></b></pre>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="84636">I.3.8  &nbsp;&nbsp;Documentation Format Conventions for C</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84638"> </a>This section specifies the text-formatting conventions for source-code derived documentation. The WRS tool <b class="command">refgen</b> is used to generate reference entries (in HTML format) for every module automatically. All modules must be able to generate valid reference entries.  This section is a summary of basic documentation format issues; for a more detailed discussion, see the <i class="title">Tornado BSP Developer's Kit User's Guide: Documentation Guidelines</i>. </p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H4"><i><a name="84642">Layout</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84643"> </a>To work with <b class="command">refgen</b>, the documentation in source modules must be laid out following a few simple principles. The file <b class="file">sample.c</b> in <i class="textVariable">installDir</i><b class="file">/target/unsupported/tools/mangen</b> provides an example and more information. </p>
<dd><p class="Body"><a name="84644"> </a>Lines of text should fill out the full line length (assume about 75 characters); do not start every sentence on a new line.</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H4"><i><a name="84645">Format Commands</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="84646"> </a>Documentation in source modules can be formatted with UNIX <b class="command">nroff</b>/<b class="command">troff</b> formatting commands, including the standard <b class="command">man</b> macros and several WRS extensions to the <b class="command">man</b> macros. Some examples are described in the sections below. Such commands should be used sparingly.</p>
<dd><p class="Body"><a name="84647"> </a>Any macro (or "dot command") must appear on a line by itself, and the dot (&nbsp;<b>.</b>&nbsp;) must be the first character on the logical line (in the case of subroutines, this is column 3, because subroutine comment sections begin each line with an asterisk plus a space character).</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H4"><i><a name="84649">Special Elements</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<p class="listspace">
<ul class="Bullet" type="disc"><li><a name="84650"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Parameters:</b></font>&nbsp;&nbsp;When referring to a parameter in text, surround the name with the angle brackets, <b>&lt;</b> and <b>&gt;</b>. For example, if the routine <b class="routine"><i class="routine">getName</i></b><b>(&nbsp;)</b> had the following declaration:</li></ul>
</p>
<dl class="margin">

<dd><pre class="Code2"><b><a name="84651">void getName 
    ( 
    int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tid,&nbsp;&nbsp;&nbsp;&nbsp;/* task ID */ 
    char *&nbsp;&nbsp;pTname&nbsp;&nbsp;/* task name */ 
    )</a></b></pre>
</dl>

<dl class="margin">

<dd><div class="Indent"><a name="84652"> </a>You might write something like the following:</div>
<br>
</dl>

<dl class="margin">

<dd><pre class="Code2"><b><a name="84653">This routine gets the name associated with a specified task ID and copies it to &lt;pTname&gt;.</a></b></pre>
</dl>

<p class="listspace">
<ul class="Bullet" type="disc"><li><a name="84861"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Subroutines:</b></font>&nbsp;&nbsp;Include parentheses with all subroutine names, even those generally construed as shell commands. Do not put a space between the parentheses or after the name (unlike the WRS convention for code):<p class="table">

<table border="0" cellpadding="0" cellspacing="0">
<tr>
<td colspan="20">
<hr class="tablerule">
</td>
</tr>
<tr valign="top">
<td colspan=1 rowspan=1>
<p class="BodyLeft"><a name="84900"> </a>CORRECT: </p>

</td>
<td colspan=1 rowspan=1>
<pre class="CodeLeft"><b><a name="84919">taskSpawn() </a></b></pre>

</td>

</tr>
<tr valign="top">
<td colspan=1 rowspan=1>
<p class="BodyLeft"><a name="84908"> </a>INCORRECT: </p>

</td>
<td colspan=1 rowspan=1>
<pre class="CodeLeft"><b><a name="84926">taskSpawn (), taskSpawn( ), taskSpawn </a></b></pre>

</td>

</tr>

<tr>
<td colspan="20">
<hr class="tablerule">
</td>
</tr>
<tr valign="middle">
<td colspan="20">

</td>
</tr>
</table>
</p>
</li></ul>
</p>
<dl class="margin">

<dd><div class="Indent"><a name="84660"> </a>Note that there is one major exception to this rule. In the subroutine title, do not include the parentheses in the name of the subroutine being defined:<p class="table">

<table border="0" cellpadding="0" cellspacing="0">
<tr>
<td colspan="20">
<hr class="tablerule">
</td>
</tr>
<tr valign="top">
<td colspan=1 rowspan=1>
<p class="BodyLeft"><a name="85012"> </a>CORRECT:</p>

</td>
<td colspan=1 rowspan=1>