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. -->
12 > Memory pool Management Functions</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
23 HREF="compat-uitron-microitron-api.html"><LINK
25 TITLE="Interrupt management functions"
26 HREF="compat-uitron-interrupt-management-functions.html"><LINK
28 TITLE="Time Management Functions"
29 HREF="compat-uitron-time-mgmt-functions.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="compat-uitron-interrupt-management-functions.html"
65 >Chapter 32. µITRON API</TD
71 HREF="compat-uitron-time-mgmt-functions.html"
85 NAME="COMPAT-UITRON-MEMORY-POOL-MGMT-FUNCTIONS">Memory pool Management Functions</H1
87 >These functions are fully supported in this release: </P
95 CLASS="PROGRAMLISTING"
123 CLASS="PROGRAMLISTING"
151 CLASS="PROGRAMLISTING"
185 CLASS="PROGRAMLISTING"
213 CLASS="PROGRAMLISTING"
241 CLASS="PROGRAMLISTING"
275 CLASS="PROGRAMLISTING"
309 CLASS="PROGRAMLISTING"
349 CLASS="PROGRAMLISTING"
377 CLASS="PROGRAMLISTING"
399 >Note that of the memory provided for a particular pool to
400 manage in the static initialization of the memory pool objects,
401 some memory will be used to manage the pool itself. Therefore the
402 number of blocks * the blocksize will be less than the total
405 >The following functions are supported in this release, when
409 >CYGPKG_UITRON_MEMPOOLVAR_CREATE_DELETE</TT
414 >CYGPKG_UITRON_MEMPOOLFIXED_CREATE_DELETE</TT
416 as appropriate, with some restrictions: </P
424 CLASS="PROGRAMLISTING"
452 CLASS="PROGRAMLISTING"
474 CLASS="PROGRAMLISTING"
502 CLASS="PROGRAMLISTING"
518 >Because of the static initialization facilities provided for
519 system objects, a memory pool is allocated a region of memory to
520 manage statically in the configuration. So while memory pools can
521 be created and deleted, the same area of memory is used for that
522 memory pool (memory pool ID number) each time. The requested variable pool
523 size (pk_cmpl->mplsz) or the number of fixed-size
524 blocks (pk_cmpf->mpfcnt) times the block size
525 (pk_cmpf->blfsz) are checked for fitting within
526 the statically allocated memory area, so if a create call succeeds,
527 the resulting pool will be at least as large as that requested.
535 not in any sense free the memory that was managed by the deleted
536 pool for use by other pools; it may only be managed by a pool of
537 the same object id. </P
539 >For both fixed and variable memory pools, the queueing order
540 when waiting on a synchronization object depends on the underlying
541 kernel configuration. The multi-level queue scheduler is required
542 for strict µITRON conformance and
543 it queues tasks in FIFO order, so requests to create an object with
544 priority queueing of tasks (pk_cxxx->xxxatr = TA_TPRI)
545 are rejected with E_RSATR. Additional undefined bits in
546 the attributes fields must be zero. </P
548 >In general, extended information (pk_cxxx->exinf)
555 NAME="AEN13913">Error checking</H2
557 >The following conditions are only checked for, and only return
561 >CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</TT
569 >invalid object id; less than 1 or greater than
572 >CYGNUM_UITRON_MEMPOOLVAR/MEMPOOLFIXED</TT
574 as appropriate returns E_ID</P
578 >dispatching is enabled in any call which can sleep, or
583 >tmout must be positive, otherwise E_PAR</P
592 must be valid pointers, or E_PAR</P
596 >return value pointer in
601 is a valid pointer, or E_PAR</P
605 >return value pointers in get block routines is a valid
610 >blocksize request in get variable block routines is greater
611 than zero, or E_PAR</P
615 >The following conditions are checked for, and can return error
616 codes, regardless of the setting of
619 >CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</TT
626 >When create and delete functions
636 are supported, all calls which use a valid object ID number check
637 that the object exists. If not, E_NOEXS is returned.</P
641 >When create functions
646 are supported, if the object already exists, then E_OBJ</P
650 >In any call which can sleep, such as
655 : return codes E_TMOUT, E_RLWAI, E_DLT
656 or of course E_OK are returned depending on the reason
657 for terminating the sleep</P
661 >In polling functions such as
666 return codes E_TMOUT or E_OK are returned depending
667 on the state of the synchronization object</P
671 >In creation functions, the attributes must be compatible
672 with the selected underlying kernel configuration: in
680 >pk_cmpl->mplatr</TT
699 >pk_cmpf->mpfatr</TT
710 >In creation functions, the requested size of the memory
711 pool must not be larger than that statically configured for the
712 pool else E_RSATR; see the configuration option
713 “Option: Static initializers”.
722 >pk_cmpl->mplsz</TT
724 is the field of interest</P
736 >pk_cmpf->blfsz</TT
741 >pk_cmpf->mpfcnt</TT
743 must be smaller than the memory statically configured for the pool
748 >In functions which return memory to the pool
758 , if the free fails, for example because the memory did not come
759 from that pool originally, then E_PAR is returned</P
769 SUMMARY="Footer navigation table"
780 HREF="compat-uitron-interrupt-management-functions.html"
798 HREF="compat-uitron-time-mgmt-functions.html"
808 >Interrupt management functions</TD
814 HREF="compat-uitron-microitron-api.html"
822 >Time Management Functions</TD