URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [c-library-startup.html] - Blame information for rev 593

Go to most recent revision | Details | Compare with Previous | View Log


<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission is obtained from the copyright holder.               -->
<HTML
><HEAD
><TITLE
>C library startup</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="C and math library overview"
HREF="c-and-math-library-overview.html"><LINK
REL="PREVIOUS"
TITLE="Thread safety"
HREF="libc-thread-safety.html"><LINK
REL="NEXT"
TITLE="I/O Package (Device Drivers)"
HREF="io.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="libc-thread-safety.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 13. C and math library overview</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="io.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="C-LIBRARY-STARTUP">C library startup</H1
><P
>The C library includes a function declared as:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void <TT
CLASS="FUNCTION"
>cyg_iso_c_start</TT
>( void )</PRE
></TD
></TR
></TABLE
><P
>This function is used to start an environment in which an
ISO C style program can run in the most compatible way.</P
><P
>What this function does is to create a thread which will invoke <TT
CLASS="FUNCTION"
>main()</TT
> &#8212; normally
considered a program's entry point. In particular, it can
supply arguments to <TT
CLASS="FUNCTION"
>main()</TT
> using the CYGDAT_LIBC_ARGUMENTS
configuration option, and when returning from <TT
CLASS="FUNCTION"
>main()</TT
>,
or calling <TT
CLASS="FUNCTION"
>exit()</TT
>, pending stdio file output
is flushed and any functions registered with <TT
CLASS="FUNCTION"
>atexit()</TT
> are
invoked. This is all compliant with the ISO C standard in this respect. </P
><P
>This thread starts execution when the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>eCos</I
></SPAN
> scheduler
is started. If the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>eCos</I
></SPAN
> kernel package is not
available (and hence there is no scheduler), then <TT
CLASS="FUNCTION"
>cyg_iso_c_start()</TT
> will
invoke the <TT
CLASS="FUNCTION"
>main()</TT
> function directly, i.e.
it will not return until the <TT
CLASS="FUNCTION"
>main()</TT
> function
returns. </P
><P
>The <TT
CLASS="FUNCTION"
>main()</TT
> function should be defined
as the following, and if defined in a C&#0043;&#0043; file,
should have &#8220;C&#8221; linkage: </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>extern int <TT
CLASS="FUNCTION"
>main</TT
>(
  int <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>argc,</I
></SPAN
>
  char *<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>argv[] </I
></SPAN
>)</PRE
></TD
></TR
></TABLE
><P
>The thread that is started by <TT
CLASS="FUNCTION"
>cyg_iso_c_start()</TT
> can
be manipulated directly, if you wish. For example you can suspend
it. The kernel C API needs a handle to do this, which is available
by including the following in your source code.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>extern cyg_handle_t cyg_libc_main_thread;</PRE
></TD
></TR
></TABLE
><P
>Then for example, you can suspend the thread with the line:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cyg_thread_suspend( cyg_libc_main_thread );</PRE
></TD
></TR
></TABLE
><P
>If you call <TT
CLASS="FUNCTION"
>cyg_iso_c_start()</TT
> and
do not provide your own <TT
CLASS="FUNCTION"
>main()</TT
> function,
the system will provide a <TT
CLASS="FUNCTION"
>main()</TT
> for you
which will simply return immediately.</P
><P
>In the default configuration, <TT
CLASS="FUNCTION"
>cyg_iso_c_start()</TT
> is
invoked automatically by the <TT
CLASS="FUNCTION"
>cyg_package_start()</TT
> function
in the infrastructure configuration. This means that in the simplest
case, your program can indeed consist of simply:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int main( int argc, char *argv[] )
{
 printf("Hello eCos\n");
}</PRE
></TD
></TR
></TABLE
><P
>If you override <TT
CLASS="FUNCTION"
>cyg_package_start()</TT
> or <TT
CLASS="FUNCTION"
>cyg_start()</TT
>,
or disable the infrastructure configuration option CYGSEM_START_ISO_C_COMPATIBILITY
then you must ensure that you call <TT
CLASS="FUNCTION"
>cyg_iso_c_start()</TT
> yourself
if you want to be able to have your program start at the entry point
of <TT
CLASS="FUNCTION"
>main()</TT
> automatically.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libc-thread-safety.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="io.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Thread safety</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c-and-math-library-overview.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>I/O Package (Device Drivers)</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>

Line No.	Rev	Author	Line
1	28	unneback	`<!-- Copyright (C) 2003 Red Hat, Inc. -->`
2			`<!-- This material may be distributed only subject to the terms -->`
3			`<!-- and conditions set forth in the Open Publication License, v1.0 -->`
4			`<!-- or later (the latest version is presently available at -->`
5			`<!-- http://www.opencontent.org/openpub/). -->`
6			`<!-- Distribution of the work or derivative of the work in any -->`
7			`<!-- standard (paper) book form is prohibited unless prior -->`
8			`<!-- permission is obtained from the copyright holder. -->`
9			`<HTML`
10			`><HEAD`
11			`><TITLE`
12			`>C library startup</TITLE`
13			`><meta name="MSSmartTagsPreventParsing" content="TRUE">`
14			`<META`
15			`NAME="GENERATOR"`
16			`CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+`
17			`"><LINK`
18			`REL="HOME"`
19			`TITLE="eCos Reference Manual"`
20			`HREF="ecos-ref.html"><LINK`
21			`REL="UP"`
22			`TITLE="C and math library overview"`
23			`HREF="c-and-math-library-overview.html"><LINK`
24			`REL="PREVIOUS"`
25			`TITLE="Thread safety"`
26			`HREF="libc-thread-safety.html"><LINK`
27			`REL="NEXT"`
28			`TITLE="I/O Package (Device Drivers)"`
29			`HREF="io.html"></HEAD`
30			`><BODY`
31			`CLASS="SECT1"`
32			`BGCOLOR="#FFFFFF"`
33			`TEXT="#000000"`
34			`LINK="#0000FF"`
35			`VLINK="#840084"`
36			`ALINK="#0000FF"`
37			`><DIV`
38			`CLASS="NAVHEADER"`
39			`><TABLE`
40			`SUMMARY="Header navigation table"`
41			`WIDTH="100%"`
42			`BORDER="0"`
43			`CELLPADDING="0"`
44			`CELLSPACING="0"`
45			`><TR`
46			`><TH`
47			`COLSPAN="3"`
48			`ALIGN="center"`
49			`>eCos Reference Manual</TH`
50			`></TR`
51			`><TR`
52			`><TD`
53			`WIDTH="10%"`
54			`ALIGN="left"`
55			`VALIGN="bottom"`
56			`><A`
57			`HREF="libc-thread-safety.html"`
58			`ACCESSKEY="P"`
59			`>Prev</A`
60			`></TD`
61			`><TD`
62			`WIDTH="80%"`
63			`ALIGN="center"`
64			`VALIGN="bottom"`
65			`>Chapter 13. C and math library overview</TD`
66			`><TD`
67			`WIDTH="10%"`
68			`ALIGN="right"`
69			`VALIGN="bottom"`
70			`><A`
71			`HREF="io.html"`
72			`ACCESSKEY="N"`
73			`>Next</A`
74			`></TD`
75			`></TR`
76			`></TABLE`
77			`><HR`
78			`ALIGN="LEFT"`
79			`WIDTH="100%"></DIV`
80			`><DIV`
81			`CLASS="SECT1"`
82			`><H1`
83			`CLASS="SECT1"`
84			`><A`
85			`NAME="C-LIBRARY-STARTUP">C library startup</H1`
86			`><P`
87			`>The C library includes a function declared as:</P`
88			`><TABLE`
89			`BORDER="5"`
90			`BGCOLOR="#E0E0F0"`
91			`WIDTH="70%"`
92			`><TR`
93			`><TD`
94			`><PRE`
95			`CLASS="PROGRAMLISTING"`
96			`>void <TT`
97			`CLASS="FUNCTION"`
98			`>cyg_iso_c_start</TT`
99			`>( void )</PRE`
100			`></TD`
101			`></TR`
102			`></TABLE`
103			`><P`
104			`>This function is used to start an environment in which an`
105			`ISO C style program can run in the most compatible way.</P`
106			`><P`
107			`>What this function does is to create a thread which will invoke <TT`
108			`CLASS="FUNCTION"`
109			`>main()</TT`
110			`> — normally`
111			`considered a program's entry point. In particular, it can`
112			`supply arguments to <TT`
113			`CLASS="FUNCTION"`
114			`>main()</TT`
115			`> using the CYGDAT_LIBC_ARGUMENTS`
116			`configuration option, and when returning from <TT`
117			`CLASS="FUNCTION"`
118			`>main()</TT`
119			`>,`
120			`or calling <TT`
121			`CLASS="FUNCTION"`
122			`>exit()</TT`
123			`>, pending stdio file output`
124			`is flushed and any functions registered with <TT`
125			`CLASS="FUNCTION"`
126			`>atexit()</TT`
127			`> are`
128			`invoked. This is all compliant with the ISO C standard in this respect. </P`
129			`><P`
130			`>This thread starts execution when the <SPAN`
131			`CLASS="emphasis"`
132			`><I`
133			`CLASS="EMPHASIS"`
134			`>eCos</I`
135			`></SPAN`
136			`> scheduler`
137			`is started. If the <SPAN`
138			`CLASS="emphasis"`
139			`><I`
140			`CLASS="EMPHASIS"`
141			`>eCos</I`
142			`></SPAN`
143			`> kernel package is not`
144			`available (and hence there is no scheduler), then <TT`
145			`CLASS="FUNCTION"`
146			`>cyg_iso_c_start()</TT`
147			`> will`
148			`invoke the <TT`
149			`CLASS="FUNCTION"`
150			`>main()</TT`
151			`> function directly, i.e.`
152			`it will not return until the <TT`
153			`CLASS="FUNCTION"`
154			`>main()</TT`
155			`> function`
156			`returns. </P`
157			`><P`
158			`>The <TT`
159			`CLASS="FUNCTION"`
160			`>main()</TT`
161			`> function should be defined`
162			`as the following, and if defined in a C++ file,`
163			`should have “C” linkage: </P`
164			`><TABLE`
165			`BORDER="5"`
166			`BGCOLOR="#E0E0F0"`
167			`WIDTH="70%"`
168			`><TR`
169			`><TD`
170			`><PRE`
171			`CLASS="PROGRAMLISTING"`
172			`>extern int <TT`
173			`CLASS="FUNCTION"`
174			`>main</TT`
175			`>(`
176			`int <SPAN`
177			`CLASS="emphasis"`
178			`><I`
179			`CLASS="EMPHASIS"`
180			`>argc,</I`
181			`></SPAN`
182			`>`
183			`char *<SPAN`
184			`CLASS="emphasis"`
185			`><I`
186			`CLASS="EMPHASIS"`
187			`>argv[] </I`
188			`></SPAN`
189			`>)</PRE`
190			`></TD`
191			`></TR`
192			`></TABLE`
193			`><P`
194			`>The thread that is started by <TT`
195			`CLASS="FUNCTION"`
196			`>cyg_iso_c_start()</TT`
197			`> can`
198			`be manipulated directly, if you wish. For example you can suspend`
199			`it. The kernel C API needs a handle to do this, which is available`
200			`by including the following in your source code.</P`
201			`><TABLE`
202			`BORDER="5"`
203			`BGCOLOR="#E0E0F0"`
204			`WIDTH="70%"`
205			`><TR`
206			`><TD`
207			`><PRE`
208			`CLASS="PROGRAMLISTING"`
209			`>extern cyg_handle_t cyg_libc_main_thread;</PRE`
210			`></TD`
211			`></TR`
212			`></TABLE`
213			`><P`
214			`>Then for example, you can suspend the thread with the line:</P`
215			`><TABLE`
216			`BORDER="5"`
217			`BGCOLOR="#E0E0F0"`
218			`WIDTH="70%"`
219			`><TR`
220			`><TD`
221			`><PRE`
222			`CLASS="PROGRAMLISTING"`
223			`>cyg_thread_suspend( cyg_libc_main_thread );</PRE`
224			`></TD`
225			`></TR`
226			`></TABLE`
227			`><P`
228			`>If you call <TT`
229			`CLASS="FUNCTION"`
230			`>cyg_iso_c_start()</TT`
231			`> and`
232			`do not provide your own <TT`
233			`CLASS="FUNCTION"`
234			`>main()</TT`
235			`> function,`
236			`the system will provide a <TT`
237			`CLASS="FUNCTION"`
238			`>main()</TT`
239			`> for you`
240			`which will simply return immediately.</P`
241			`><P`
242			`>In the default configuration, <TT`
243			`CLASS="FUNCTION"`
244			`>cyg_iso_c_start()</TT`
245			`> is`
246			`invoked automatically by the <TT`
247			`CLASS="FUNCTION"`
248			`>cyg_package_start()</TT`
249			`> function`
250			`in the infrastructure configuration. This means that in the simplest`
251			`case, your program can indeed consist of simply:</P`
252			`><TABLE`
253			`BORDER="5"`
254			`BGCOLOR="#E0E0F0"`
255			`WIDTH="70%"`
256			`><TR`
257			`><TD`
258			`><PRE`
259			`CLASS="PROGRAMLISTING"`
260			`>int main( int argc, char *argv[] )`
261			`{`
262			`printf("Hello eCos\n");`
263			`}</PRE`
264			`></TD`
265			`></TR`
266			`></TABLE`
267			`><P`
268			`>If you override <TT`
269			`CLASS="FUNCTION"`
270			`>cyg_package_start()</TT`
271			`> or <TT`
272			`CLASS="FUNCTION"`
273			`>cyg_start()</TT`
274			`>,`
275			`or disable the infrastructure configuration option CYGSEM_START_ISO_C_COMPATIBILITY`
276			`then you must ensure that you call <TT`
277			`CLASS="FUNCTION"`
278			`>cyg_iso_c_start()</TT`
279			`> yourself`
280			`if you want to be able to have your program start at the entry point`
281			`of <TT`
282			`CLASS="FUNCTION"`
283			`>main()</TT`
284			`> automatically.</P`
285			`></DIV`
286			`><DIV`
287			`CLASS="NAVFOOTER"`
288			`><HR`
289			`ALIGN="LEFT"`
290			`WIDTH="100%"><TABLE`
291			`SUMMARY="Footer navigation table"`
292			`WIDTH="100%"`
293			`BORDER="0"`
294			`CELLPADDING="0"`
295			`CELLSPACING="0"`
296			`><TR`
297			`><TD`
298			`WIDTH="33%"`
299			`ALIGN="left"`
300			`VALIGN="top"`
301			`><A`
302			`HREF="libc-thread-safety.html"`
303			`ACCESSKEY="P"`
304			`>Prev</A`
305			`></TD`
306			`><TD`
307			`WIDTH="34%"`
308			`ALIGN="center"`
309			`VALIGN="top"`
310			`><A`
311			`HREF="ecos-ref.html"`
312			`ACCESSKEY="H"`
313			`>Home</A`
314			`></TD`
315			`><TD`
316			`WIDTH="33%"`
317			`ALIGN="right"`
318			`VALIGN="top"`
319			`><A`
320			`HREF="io.html"`
321			`ACCESSKEY="N"`
322			`>Next</A`
323			`></TD`
324			`></TR`
325			`><TR`
326			`><TD`
327			`WIDTH="33%"`
328			`ALIGN="left"`
329			`VALIGN="top"`
330			`>Thread safety</TD`
331			`><TD`
332			`WIDTH="34%"`
333			`ALIGN="center"`
334			`VALIGN="top"`
335			`><A`
336			`HREF="c-and-math-library-overview.html"`
337			`ACCESSKEY="U"`
338			`>Up</A`
339			`></TD`
340			`><TD`
341			`WIDTH="33%"`
342			`ALIGN="right"`
343			`VALIGN="top"`
344			`>I/O Package (Device Drivers)</TD`
345			`></TR`
346			`></TABLE`
347			`></DIV`
348			`></BODY`
349			`></HTML`
350			`>`

Browse

Tools

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [c-library-startup.html] - Blame information for rev 593