doc/html/ref/io-user-api.html

   1 <!-- 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 >User API</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="I/O Package (Device Drivers)"
  23 HREF="io.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Introduction"
  26 HREF="io-package-intro.html"><LINK
  27 REL="NEXT"
  28 TITLE="Serial driver details"
  29 HREF="io-serial-driver-details.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  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="io-package-intro.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io-serial-driver-details.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="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="IO-USER-API">Chapter 15. User API</H1
  85 ><P
  86 >All functions, except <TT
  87 CLASS="FUNCTION"
  88 >cyg_io_lookup()</TT
  89 >
  90 require an I/O &#8220;handle&#8221;.</P
  91 ><P
  92 >All functions return a value of the type <SPAN
  93 CLASS="TYPE"
  94 >Cyg_ErrNo</SPAN
  95 >. If an
  96 error condition is detected, this value will be negative and the
  97 absolute value indicates the actual error, as specified in
  98 <TT
  99 CLASS="FILENAME"
 100 >cyg/error/codes.h</TT
 101 >. The only other legal return
 102 value will be <TT
 103 CLASS="VARNAME"
 104 >ENOERR</TT
 105 >. All other function arguments
 106 are pointers (references). This allows the drivers to pass information
 107 efficiently, both into and out of the driver. The most striking
 108 example of this is the &#8220;length&#8221; value passed to the read
 109 and write functions. This parameter contains the desired length of
 110 data on input to the function and the actual transferred length on
 111 return.</P
 112 ><TABLE
 113 BORDER="5"
 114 BGCOLOR="#E0E0F0"
 115 WIDTH="70%"
 116 ><TR
 117 ><TD
 118 ><PRE
 119 CLASS="PROGRAMLISTING"
 120 >// Lookup a device and return its handle
 121   Cyg_ErrNo <TT
 122 CLASS="FUNCTION"
 123 >cyg_io_lookup</TT
 124 >(
 125     const char <TT
 126 CLASS="PARAMETER"
 127 ><I
 128 >*name</I
 129 ></TT
 130 >,
 131     cyg_io_handle_t <TT
 132 CLASS="PARAMETER"
 133 ><I
 134 >*handle</I
 135 ></TT
 136 > )</PRE
 137 ></TD
 138 ></TR
 139 ></TABLE
 140 ><P
 141 >This function maps a device name onto an appropriate handle. If the
 142 named device is not in the system, then the error
 143 <TT
 144 CLASS="VARNAME"
 145 >-ENOENT</TT
 146 > is returned. If the device is found, then
 147 the handle for the device is returned by way of the handle pointer
 148 <TT
 149 CLASS="PARAMETER"
 150 ><I
 151 >*handle</I
 152 ></TT
 153 >.</P
 154 ><TABLE
 155 BORDER="5"
 156 BGCOLOR="#E0E0F0"
 157 WIDTH="70%"
 158 ><TR
 159 ><TD
 160 ><PRE
 161 CLASS="PROGRAMLISTING"
 162 >// Write data to a device
 163 Cyg_ErrNo <TT
 164 CLASS="FUNCTION"
 165 >cyg_io_write</TT
 166 >(
 167     cyg_io_handle_t <TT
 168 CLASS="PARAMETER"
 169 ><I
 170 >handle</I
 171 ></TT
 172 >,
 173     const void <TT
 174 CLASS="PARAMETER"
 175 ><I
 176 >*buf</I
 177 ></TT
 178 >,
 179     cyg_uint32 <TT
 180 CLASS="PARAMETER"
 181 ><I
 182 >*len</I
 183 ></TT
 184 > )</PRE
 185 ></TD
 186 ></TR
 187 ></TABLE
 188 ><P
 189 >This function sends data to a device. The size of data to send is
 190 contained in <TT
 191 CLASS="PARAMETER"
 192 ><I
 193 >*len</I
 194 ></TT
 195 > and the actual size sent will
 196 be returned in the same place.</P
 197 ><TABLE
 198 BORDER="5"
 199 BGCOLOR="#E0E0F0"
 200 WIDTH="70%"
 201 ><TR
 202 ><TD
 203 ><PRE
 204 CLASS="PROGRAMLISTING"
 205 >// Read data from a device
 206 Cyg_ErrNo <TT
 207 CLASS="FUNCTION"
 208 >cyg_io_read</TT
 209 >(
 210     cyg_io_handle_t <TT
 211 CLASS="PARAMETER"
 212 ><I
 213 >handle</I
 214 ></TT
 215 >,
 216     void <TT
 217 CLASS="PARAMETER"
 218 ><I
 219 >*buf</I
 220 ></TT
 221 >,
 222     cyg_uint32 <TT
 223 CLASS="PARAMETER"
 224 ><I
 225 >*len</I
 226 ></TT
 227 > )</PRE
 228 ></TD
 229 ></TR
 230 ></TABLE
 231 ><P
 232 >This function receives data from a device. The desired size of data to
 233 receive is contained in <TT
 234 CLASS="PARAMETER"
 235 ><I
 236 >*len</I
 237 ></TT
 238 > and the actual
 239 size obtained will be returned in the same place.</P
 240 ><TABLE
 241 BORDER="5"
 242 BGCOLOR="#E0E0F0"
 243 WIDTH="70%"
 244 ><TR
 245 ><TD
 246 ><PRE
 247 CLASS="PROGRAMLISTING"
 248 >// Get the configuration of a device
 249 Cyg_ErrNo <TT
 250 CLASS="FUNCTION"
 251 >cyg_io_get_config</TT
 252 >(
 253     cyg_io_handle_t <TT
 254 CLASS="PARAMETER"
 255 ><I
 256 >handle</I
 257 ></TT
 258 >,
 259     cyg_uint32 <TT
 260 CLASS="PARAMETER"
 261 ><I
 262 >key</I
 263 ></TT
 264 >,
 265     void *<TT
 266 CLASS="PARAMETER"
 267 ><I
 268 >buf</I
 269 ></TT
 270 >,
 271     cyg_uint32 *<TT
 272 CLASS="PARAMETER"
 273 ><I
 274 >len</I
 275 ></TT
 276 > )</PRE
 277 ></TD
 278 ></TR
 279 ></TABLE
 280 ><P
 281 >This function is used to obtain run-time configuration about a
 282 device. The type of information retrieved is specified by the
 283 <TT
 284 CLASS="PARAMETER"
 285 ><I
 286 >key</I
 287 ></TT
 288 >. The data will be returned in the given
 289 buffer. The value of <TT
 290 CLASS="PARAMETER"
 291 ><I
 292 >*len</I
 293 ></TT
 294 > should contain the
 295 amount of data requested, which must be at least as large as the size
 296 appropriate to the selected key. The actual size of data retrieved is
 297 placed in <TT
 298 CLASS="PARAMETER"
 299 ><I
 300 > *len</I
 301 ></TT
 302 >. The appropriate key values
 303 differ for each driver and are all listed in the file
 304 <TT
 305 CLASS="FILENAME"
 306 >&lt;cyg/io/config_keys.h&gt;</TT
 307 >.</P
 308 ><TABLE
 309 BORDER="5"
 310 BGCOLOR="#E0E0F0"
 311 WIDTH="70%"
 312 ><TR
 313 ><TD
 314 ><PRE
 315 CLASS="PROGRAMLISTING"
 316 >// Change the configuration of a device
 317 Cyg_ErrNo <TT
 318 CLASS="FUNCTION"
 319 >cyg_io_set_config</TT
 320 >(
 321     cyg_io_handle_t <TT
 322 CLASS="PARAMETER"
 323 ><I
 324 >handle</I
 325 ></TT
 326 >,
 327     cyg_uint32 <TT
 328 CLASS="PARAMETER"
 329 ><I
 330 >key</I
 331 ></TT
 332 >,
 333     const void <TT
 334 CLASS="PARAMETER"
 335 ><I
 336 >*buf</I
 337 ></TT
 338 >,
 339     cyg_uint32 <TT
 340 CLASS="PARAMETER"
 341 ><I
 342 >*len</I
 343 ></TT
 344 > )</PRE
 345 ></TD
 346 ></TR
 347 ></TABLE
 348 ><P
 349 >This function is used to manipulate or change the run-time
 350 configuration of a device. The type of information is specified by the
 351 <TT
 352 CLASS="PARAMETER"
 353 ><I
 354 >key</I
 355 ></TT
 356 >. The data will be obtained from the given
 357 buffer. The value of <TT
 358 CLASS="PARAMETER"
 359 ><I
 360 >*len</I
 361 ></TT
 362 > should contain the
 363 amount of data provided, which must match the size appropriate to the
 364 selected key.  The appropriate key values differ for each driver and
 365 are all listed in the file
 366 <TT
 367 CLASS="FILENAME"
 368 >&lt;cyg/io/config_keys.h&gt;</TT
 369 >.</P
 370 ></DIV
 371 ><DIV
 372 CLASS="NAVFOOTER"
 373 ><HR
 374 ALIGN="LEFT"
 375 WIDTH="100%"><TABLE
 376 SUMMARY="Footer navigation table"
 377 WIDTH="100%"
 378 BORDER="0"
 379 CELLPADDING="0"
 380 CELLSPACING="0"
 381 ><TR
 382 ><TD
 383 WIDTH="33%"
 384 ALIGN="left"
 385 VALIGN="top"
 386 ><A
 387 HREF="io-package-intro.html"
 388 ACCESSKEY="P"
 389 >Prev</A
 390 ></TD
 391 ><TD
 392 WIDTH="34%"
 393 ALIGN="center"
 394 VALIGN="top"
 395 ><A
 396 HREF="ecos-ref.html"
 397 ACCESSKEY="H"
 398 >Home</A
 399 ></TD
 400 ><TD
 401 WIDTH="33%"
 402 ALIGN="right"
 403 VALIGN="top"
 404 ><A
 405 HREF="io-serial-driver-details.html"
 406 ACCESSKEY="N"
 407 >Next</A
 408 ></TD
 409 ></TR
 410 ><TR
 411 ><TD
 412 WIDTH="33%"
 413 ALIGN="left"
 414 VALIGN="top"
 415 >Introduction</TD
 416 ><TD
 417 WIDTH="34%"
 418 ALIGN="center"
 419 VALIGN="top"
 420 ><A
 421 HREF="io.html"
 422 ACCESSKEY="U"
 423 >Up</A
 424 ></TD
 425 ><TD
 426 WIDTH="33%"
 427 ALIGN="right"
 428 VALIGN="top"
 429 >Serial driver details</TD
 430 ></TR
 431 ></TABLE
 432 ></DIV
 433 ></BODY
 434 ></HTML
 435 >