 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| rx4000 ( itron 4.0) real-time operating system basics user?s manual target devices v r 4100 series tm v r 5000 series tm target real-time os RX4000V4 ver. 4.10 printed in japan document no. u14833ej2v0um00 (2nd edition) date published february 2003 n cp(k) ?
user?s manual u14833ej2v0um 2 [memo] user?s manual u14833ej2v0um 3 v r series, v r 4100 series, v r 5000 series, v r 4100, v r 4121, v r 4122, v r 4131, v r 4181, v r 4181a, v r 5000, v r 5000a, v r 5432, v r 5500, and v r 10000 are trademarks of nec electronics corporation. green hills software is a trademark of green hills software, inc. tron is the abbreviation for the real-time operating system nucleus. itron is the abbreviation for industrial tron. itron is the abbreviation for micro industrial tron. tron, itron, and itron are not the names of specific products or a product group. the itron4.0 specification is an open real-time kernel specification that was mainly established by the itron sectional meeting of the tron association. the itron4.0 specification is available from the itron project home page (http://www.itron.gr.jp/). user?s manual u14833ej2v0um 4 the information in this document is current as of february, 2002. the information is subject to change without notice. for actual design-in, refer to the latest publications of nec electronics data sheets or data books, etc., for the most up-to-date specifications of nec electronics products. not all products and/or types are available in every country. please check with an nec electronics sales representative for availability and additional information. no part of this document may be copied or reproduced in any form or by any means without the prior written consent of nec electronics. nec electronics assumes no responsibility for any errors that may appear in this document. nec electronics does not assume any liability for infringement of patents, copyrights or other intellectual property rights of third parties by or arising from the use of nec electronics products listed in this document or any other liability arising from the use of such products. no license, express, implied or otherwise, is granted under any patents, copyrights or other intellectual property rights of nec electronics or others. descriptions of circuits, software and other related information in this document are provided for illustrative purposes in semiconductor product operation and application examples. the incorporation of these circuits, software and information in the design of a customer's equipment shall be done under the full responsibility of the customer. nec electronics assumes no responsibility for any losses incurred by customers or third parties arising from the use of these circuits, software and information. while nec electronics endeavors to enhance the quality, reliability and safety of nec electronics products, customers agree and acknowledge that the possibility of defects thereof cannot be eliminated entirely. to minimize risks of damage to property or injury (including death) to persons arising from defects in nec electronics products, customers must incorporate sufficient safety measures in their design, such as redundancy, fire-containment and anti-failure features. nec electronics products are classified into the following three quality grades: "standard", "special" and "specific". the "specific" quality grade applies only to nec electronics products developed based on a customer- designated "quality assurance program" for a specific application. the recommended applications of an nec electronics product depend on its quality grade, as indicated below. customers must check the quality grade of each nec electronics product before using it in a particular application. the quality grade of nec electronics products is "standard" unless otherwise expressly specified in nec electronics data sheets or data books, etc. if customers wish to use nec electronics products in applications not intended by nec electronics, they must contact an nec electronics sales representative in advance to determine nec electronics' willingness to support a given application. (note) ? ? ? ? ? ? m8e 02. 11-1 (1) (2) "nec electronics" as used in this statement means nec electronics corporation and also includes its majority-owned subsidiaries. "nec electronics products" means any product developed or manufactured by or for nec electronics (as defined above). computers, office equipment, communications equipment, test and measurement equipment, audio and visual equipment, home electronic appliances, machine tools, personal electronic equipment and industrial robots. transportation equipment (automobiles, trains, ships, etc.), traffic control systems, anti-disaster systems, anti-crime systems, safety equipment and medical equipment (not specifically designed for life support). aircraft, aerospace equipment, submersible repeaters, nuclear reactor control systems, life support systems and medical equipment for life support, etc. "standard": "special": "specific": user ? s manual u14833ej2v0um 5 regional information ? device availability ? ordering information ? product release schedule ? availability of related technical literature ? development environment specifications (for example, specifications for third-party tools and components, host computers, power plugs, ac supply voltages, and so forth) ? network requirements in addition, trademarks, registered trademarks, export restrictions, and other legal issues may also vary from country to country. nec electronics america, inc. (u.s.) santa clara, california tel: 408-588-6000 800-366-9782 fax: 408-588-6130 800-729-9288 nec electronics hong kong ltd. hong kong tel: 2886-9318 fax: 2886-9022/9044 nec electronics hong kong ltd. seoul branch seoul, korea tel: 02-528-0303 fax: 02-528-4411 nec electronics shanghai, ltd. shanghai, p.r. china tel: 021-6841-1138 fax: 021-6841-1137 nec electronics taiwan ltd. taipei, taiwan tel: 02-2719-2377 fax: 02-2719-5951 nec electronics singapore pte. ltd. novena square, singapore tel: 6253-8311 fax: 6250-3583 j02.11 nec electronics (europe) gmbh duesseldorf, germany tel: 0211-65 03 01 fax: 0211-65 03 327 sucursal en espa ? a madrid, spain tel: 091-504 27 87 fax: 091-504 28 60 v lizy-villacoublay, france tel: 01-30-67 58 00 fax: 01-30-67 58 99 succursale fran ? aise filiale italiana milano, italy tel: 02-66 75 41 fax: 02-66 75 42 99 branch the netherlands eindhoven, the netherlands tel: 040-244 58 45 fax: 040-244 45 80 tyskland filial taeby, sweden tel: 08-63 80 820 fax: 08-63 80 388 united kingdom branch milton keynes, uk tel: 01908-691-133 fax: 01908-670-290 some information contained in this document may vary from country to country. before using any nec electronics product in your application, piease contact the nec electronics office in your country to obtain a list of authorized representatives and distributors. they will verify: user?s manual u14833ej2v0um 6 preface target readers this manual is aimed at users engaged in the design or development of v r 4100 series or v r 5000 series application systems. purpose the purpose of this manual is to give users an understanding of the functions of the rx4000 shown under organization below. organization this manual is broadly divided into the following sections. ? overview ? kernel ? scheduler ? task management ? synchronous communication management ? memory management ? time management ? interrupt management ? system configuration management ? service call management ? initialization management ? interface library ? service calls how to read this manual readers need to have general knowledge of electricity, logic circuits, microcontrollers, and c and assembly languages. to learn about the hardware or instruction functions of the v r 4100 series or v r 5000 series, refer to the user?s manual for the relevant product. conventions note : footnote for item marked with note in the text caution : information requiring particular attention remark : supplementary information numerical representation: binary ... xxxx or b?xxxx decimal ... xxxx hexadecimal ... 0xxxxx or h?xxxx prefixes indicating powers of 2 (address space and memory capacity): k (kilo): 2 10 = 1,024 m (mega): 2 20 = 1,024 2 user?s manual u14833ej2v0um 7 related documents the related documents indicated in this publication may include preliminary versions. however, preliminary versions are not marked as such. documents related to v r 4100 series document name document no. v r 4100 series architecture user?s manual u15509e v r 4121 tm user?s manual u13569e pd30121 (v r 4121) data sheet u14691e v r 4122 tm user?s manual u14327e pd30122 (v r 4122) data sheet u15585e v r 4131 tm hardware user?s manual u15350e pd30131 (v r 4131) data sheet u16219e v r 4181 tm hardware user?s manual u14272e pd30181 (v r 4181) data sheet u14273e v r 4181a tm hardware user?s manual u16049e pd30181a, 30181ay (v r 4181a) data sheet u16277e documents related to v r 5000 series document name document no. v r 5000 tm , v r 5000a tm user?s manual u11761e pd30500, 30500a data sheet u12031e v r 5432 tm user?s manual u13751e pd30541 data sheet u13504e v r 5500 tm user?s manual u16044e pd30550 data sheet u15700e v r 5000, v r 10000 tm instruction user?s manual u12754e documents related to development tools (user?s manuals) document name document no. basics this manual installation u14834e rx4000 ( itron4.0) (real-time os) technical u14835e az4000 ver. 4.0 system performance analyzer u15031e user?s manual u14833ej2v0um 8 contents chapter 1 overview .......................................................................................................... ..............16 1.1 real-time os ................................................................................................................ .............16 1.2 multitask os............................................................................................................... ................16 1.3 features................................................................................................................... ...................17 1.4 configuration .............................................................................................................. ...............18 1.5 applications ............................................................................................................... ................18 1.6 execution environment ...................................................................................................... ......19 1.7 development environment.................................................................................................... ...19 chapter 2 kernel............................................................................................................ .................20 2.1 overview.................................................................................................................... .................20 2.2 configuration .............................................................................................................. ...............20 2.3 functions .................................................................................................................. .................21 2.4 objects .................................................................................................................... ...................23 2.4.1 object control blocks .................................................................................................... ................23 2.4.2 object identification number............................................................................................. ............23 2.4.3 creating and deleting objects............................................................................................ ...........24 2.4.4 automatic assignment of id number ........................................................................................ ....24 chapter 3 scheduler ......................................................................................................... ............25 3.1 overview................................................................................................................... ..................25 3.2 drive method............................................................................................................... ...............25 3.3 scheduling methods ......................................................................................................... ........25 3.3.1 priority method .......................................................................................................... ...................25 3.3.2 fcfs method.............................................................................................................. .................25 3.4 ready queue ................................................................................................................ .............26 3.5 implementing a round robin method ....................................................................................27 3.6 scheduling delay ............................................................................................................ ..........30 3.7 enabling/disabling scheduling ............................................................................................... 31 3.8 idle routines ............................................................................................................... ...............32 3.8.1 registering idle routines................................................................................................. ..............32 3.8.2 executing and terminating idle routines................................................................................... .....32 3.8.3 pid ....................................................................................................................... ........................32 3.8.4 coprocessor............................................................................................................... ..................32 3.8.5 stack ..................................................................................................................... .......................32 chapter 4 task management .................................................................................................. ...33 4.1 overview................................................................................................................... ..................33 4.2 creating tasks.............................................................................................................. .............34 4.3 deleting tasks .............................................................................................................. .............34 4.4 activating tasks............................................................................................................ ............34 4.4.1 activation with activation request retained ............................................................................... ....34 4.4.2 activation with activation request not retained ........................................................................... ..34 4.5 terminating tasks........................................................................................................... ..........35 user?s manual u14833ej2v0um 9 4.5.1 normal termination........................................................................................................ ...............35 4.5.2 forcible termination ...................................................................................................... ...............35 4.5.3 reactivating terminated tasks ............................................................................................. .........35 4.6 task states ................................................................................................................ ................36 4.7 task state transition...................................................................................................... ..........38 4.8 task delay and timeout ..................................................................................................... ......39 4.9 task priority order........................................................................................................ ............39 4.10 task context.............................................................................................................. ................40 4.11 pid ....................................................................................................................... .......................40 4.12 obtaining task information ................................................................................................. ....40 4.13 coprocessor ............................................................................................................... ...............40 4.14 task exceptions........................................................................................................... .............41 4.14.1 task exception processing routines...................................................................................... .......41 4.14.2 defining task exception processing routines............................................................................. ...41 4.14.3 canceling task exception processing routine definitions..............................................................41 4.14.4 task exception enabled/disabled states .................................................................................. ....42 4.14.5 task exception processing requests...................................................................................... ......42 4.14.6 activating task exception processing routines ........................................................................... ..43 4.14.7 terminating task exception processing routines ..........................................................................4 4 4.14.8 issuing service calls from task exception processing routines .....................................................45 4.14.9 obtaining task exception processing routine information.............................................................45 chapter 5 synchronous communication management.................................................46 5.1 overview ................................................................................................................... .................46 5.2 semaphores................................................................................................................. ..............46 5.2.1 creating semaphores...................................................................................................... .............46 5.2.2 deleting semaphores ...................................................................................................... .............47 5.2.3 acquiring resources ....................................................................................................... ..............47 5.2.4 returning resources...................................................................................................... ...............47 5.2.5 obtaining semaphore information ........................................................................................... .....47 5.2.6 examples of exclusive control using semaphores........................................................................48 5.3 event flags ................................................................................................................. ...............50 5.3.1 creating event flags ..................................................................................................... ................50 5.3.2 deleting event flags ..................................................................................................... ................50 5.3.3 waiting for events ........................................................................................................ ................50 5.3.4 setting event flags ....................................................................................................... ................51 5.3.5 wait conditions........................................................................................................... ..................51 5.3.6 event flag clear attribute ................................................................................................ ..............51 5.3.7 obtaining event flag information .......................................................................................... ........51 5.3.8 examples of wait function using event flags ............................................................................... .52 5.4 data queues ................................................................................................................. .............54 5.4.1 creating data queues..................................................................................................... ..............54 5.4.2 deleting data queues ..................................................................................................... ..............54 5.4.3 receiving data ............................................................................................................ .................55 5.4.4 obtaining data queue information .......................................................................................... ......55 5.4.5 transmitting data ......................................................................................................... ................55 5.4.6 examples of communication using data queues ..........................................................................56 5.5 mailboxes................................................................................................................... ................60 user?s manual u14833ej2v0um 10 5.5.1 creating mailboxes ....................................................................................................... ...............60 5.5.2 deleting mailboxes....................................................................................................... ................60 5.5.3 messages.................................................................................................................. ...................61 5.5.4 transmitting messages ..................................................................................................... ...........61 5.5.5 receiving messages ........................................................................................................ ............62 5.5.6 obtaining mailbox information............................................................................................. .........62 5.5.7 examples of message communication using mailboxes ..............................................................62 5.6 mutexes ..................................................................................................................... .................65 5.6.1 creating mutexes ......................................................................................................... ................65 5.6.2 deleting mutexes .......................................................................................................... ...............65 5.6.3 priority inheritance protocol............................................................................................. .............65 5.6.4 priority ceiling protocol ................................................................................................. ................65 5.6.5 simplified priority order control rules ................................................................................... .........66 5.6.6 locking mutexes ........................................................................................................... ...............66 5.6.7 releasing mutex locks ..................................................................................................... ............66 5.6.8 obtaining mutex information ............................................................................................... .........66 5.6.9 examples of synchronization using mutexes................................................................................6 7 chapter 6 memory management...............................................................................................6 9 6.1 overview................................................................................................................... ..................69 6.2 system pool ................................................................................................................. ..............69 6.3 stack pool .................................................................................................................. ................70 6.4 user pool................................................................................................................... .................70 6.5 fixed-length memory pools .................................................................................................. ..70 6.5.1 creating fixed-length memory pools....................................................................................... ......70 6.5.2 deleting fixed-length memory pools ....................................................................................... ......70 6.5.3 fixed-length memory blocks ................................................................................................ ........71 6.5.4 structure of fixed-length memory pool ..................................................................................... ....71 6.5.5 acquiring fixed-length memory blocks...................................................................................... ....72 6.5.6 returning fixed-length memory blocks .................................................................................... .....72 6.5.7 obtaining fixed-length memory pool information ..........................................................................72 6.5.8 examples of acquiring memory blocks from fixed-length memory pools ......................................73 6.6 variable-length memory pools ...............................................................................................7 5 6.6.1 creating variable-length memory pools.................................................................................... ....75 6.6.2 deleting variable-length memory pools .................................................................................... ....75 6.6.3 variable-length memory blocks ............................................................................................. .......75 6.6.4 structure of variable-length memory pool................................................................................. ...76 6.6.5 acquiring variable-length memory blocks................................................................................... ..77 6.6.6 returning variable-length memory blocks .................................................................................. ..79 6.6.7 obtaining variable-length memory pool information .....................................................................80 6.6.8 examples of acquiring memory blocks from variable-length memory pools .................................81 chapter 7 time management .................................................................................................. ....84 7.1 overview.................................................................................................................... .................84 7.2 system clock................................................................................................................ .............84 7.2.1 setting the system clock.................................................................................................. .............84 user?s manual u14833ej2v0um 11 7.2.2 reading the system clock .................................................................................................. ..........84 7.2.3 updating the system clock ................................................................................................. ..........84 7.3 delaying tasks .............................................................................................................. ............85 7.4 timeout ..................................................................................................................... .................85 7.5 cyclic handlers ............................................................................................................ .............86 7.5.1 creating cyclic handlers.................................................................................................. .............86 7.5.2 deleting cyclic handlers .................................................................................................. .............86 7.5.3 cyclic handler states..................................................................................................... ...............86 7.5.4 activating a cyclic handler............................................................................................... .............87 7.5.5 terminating cyclic handlers ............................................................................................... ..........87 7.5.6 cyclic handler phase...................................................................................................... ..............87 7.5.7 interrupts during cyclic handler execution............................................................................... .....88 7.5.8 pid...................................................................................................................... .........................89 7.5.9 use of coprocessor in cyclic handler...................................................................................... ......89 7.5.10 issuance of service calls from cyclic handler ............................................................................ ...89 7.5.11 obtaining cyclic handler information ..................................................................................... .......89 chapter 8 interrupt management ..........................................................................................90 8.1 overview ................................................................................................................... .................90 8.2 interrupt management ....................................................................................................... .......90 8.2.1 interrupt control........................................................................................................ ....................90 8.2.2 interrupt processing management ........................................................................................... ....91 8.3 saving/restoring registers .................................................................................................. ...93 8.4 interrupt generation notification .......................................................................................... ..93 8.5 interrupt service routines ................................................................................................. ......94 8.5.1 interrupt service routine id number and interrupt number ...........................................................94 8.5.2 creating interrupt service routines ....................................................................................... ........94 8.5.3 deleting interrupt service routines....................................................................................... .........94 8.5.4 activating interrupt service routines .................................................................................... .........94 8.5.5 terminating interrupt service routines................................................................................... .......95 8.5.6 pid...................................................................................................................... .........................95 8.5.7 use of coprocessor in interrupt service routine .......................................................................... ..95 8.5.8 issuance of service calls from interrupt service routines..............................................................95 chapter 9 system configuration management ...............................................................96 9.1 overview ................................................................................................................... .................96 9.2 exception processing ........................................................................................................ ......96 9.2.1 exception processing flow ................................................................................................. ..........96 9.2.2 saving/restoring registers ................................................................................................ ............99 9.2.3 exception occurrence notification ........................................................................................ ........99 9.2.4 cpu exception handlers ................................................................................................... ...........99 9.3 initialization routines ..................................................................................................... ........101 9.3.1 defining initialization routines.......................................................................................... ...........101 9.3.2 activating initialization routines ........................................................................................ ..........101 9.3.3 terminating initialization routines....................................................................................... ........101 chapter 10 service call management ...............................................................................102 user?s manual u14833ej2v0um 12 10.1 overview................................................................................................................... ................102 10.2 extended service call routines............................................................................................. 102 10.2.1 defining extended service call routines .................................................................................. ....102 10.2.2 activating and terminating extended service call routines ..........................................................102 10.2.3 pid ..................................................................................................................... ........................103 10.2.4 use of coprocessor in extended service call routine ..................................................................103 chapter 11 initialization processing ..................................................................................104 11.1 overview................................................................................................................... ................104 11.2 boot processing block ...................................................................................................... .....104 11.3 kernel initialization block................................................................................................ .......105 11.3.1 interrupt initialization ................................................................................................. .................105 11.3.2 pool creation and initialization......................................................................................... ...........105 11.3.3 management object creation and initialization............................................................................ 105 11.4 initialization routines .................................................................................................... .........105 chapter 12 interface library............................................................................................... ..106 12.1 overview................................................................................................................... ................106 12.2 function and position of interface library...........................................................................106 chapter 13 service calls ................................................................................................... ......107 13.1 overview.................................................................................................................. .................107 13.2 types of functions ........................................................................................................ .........107 13.3 return values (error codes) ............................................................................................... ...109 13.4 data types ................................................................................................................ ...............110 13.4.1 general data types...................................................................................................... ...............110 13.4.2 rx4000 data types....................................................................................................... ..............111 13.5 macros .................................................................................................................... ..................112 13.6 parameter value range ..................................................................................................... .....113 13.7 context from which service calls can be issued ..............................................................114 13.8 explanation of service calls.............................................................................................. .....115 13.8.1 task management function service calls.................................................................................. ..117 13.8.2 task-associated synchronization function service calls .............................................................138 13.8.3 task exception processing function service calls.......................................................................15 1 13.8.4 synchronization/communication management function service calls.........................................161 13.8.5 memory pool management function service calls.......................................................................231 13.8.6 time management function service calls .................................................................................. .259 13.8.7 system status management function service calls.....................................................................272 13.8.8 interrupt management function service calls ............................................................................. .283 13.8.9 system configuration management function service calls ..........................................................292 13.8.10 service call management function service calls .........................................................................2 97 appendix index ............................................................................................................... ..................301 user?s manual u14833ej2v0um 13 list of figures (1/2) figure no. title page 2-1 kernel configuration........................................................................................................ ...............................20 3-1 ready queue ................................................................................................................. ................................26 3-2 state 1 of ready queue during round robin processing ........................................................................ .....27 3-3 state 2 of ready queue during round robin processing ........................................................................ .....28 3-4 state 3 of ready queue during round robin processing ........................................................................ .....28 3-5 processing flow of round robin scheduling................................................................................... ..............29 3-6 scheduling delay............................................................................................................ ................................30 3-7 disabling dispatch.......................................................................................................... ................................31 4-1 task state transition....................................................................................................... ...............................38 4-2 example of task exception processing routine activation (1) ................................................................. .....43 4-3 example of task exception processing routine activation (2) ................................................................. .....43 4-4 example of task exception processing routine activation (3) ................................................................. .....44 4-5 example of task exception processing routine activation (4) ................................................................. .....44 6-1 fixed-length memory block................................................................................................... ........................71 6-2 fixed-length memory pool .................................................................................................... ........................71 6-3 variable-length memory block ................................................................................................ ......................75 6-4 variable-length memory pool structure (immediately after creation) .......................................................... .76 6-5 variable-length memory pool structure (after memory block acquisition)....................................................76 6-6 variable-length memory pool structure (when area divided into islands) ...................................................77 6-7 memory block acquisition .................................................................................................... ..........................77 6-8 case when task is waiting even though sufficient area is available.......................................................... 78 6-9 memory block linking 1 ...................................................................................................... ...........................79 6-10 memory block linking 2 ..................................................................................................... ............................79 6-11 memory block linking 3 ..................................................................................................... ............................80 7-1 cyclic handler phase ........................................................................................................ .............................87 7-2 phase saving ................................................................................................................ .................................88 7-3 no phase saving............................................................................................................. ...............................88 8-1 interrupt processing flow................................................................................................... ............................92 9-1 exception processing flow ................................................................................................... .........................98 11-1 initialization processing flow ............................................................................................. ..........................104 12-1 position of interface library.............................................................................................. ............................106 13-1 service call description format ............................................................................................ ........................115 13-2 task attributes............................................................................................................ ..................................119 13-3 task exception processing routine attribute................................................................................ ...............153 13-4 semaphore attribute........................................................................................................ .............................164 user?s manual u14833ej2v0um 14 list of figures (2/2) figure no. title page 13-5 event flag attribute ....................................................................................................... ...............................175 13-6 data queue attribute ....................................................................................................... .............................189 13-7 mailbox attribute .......................................................................................................... .................................206 13-8 mutex attribute............................................................................................................ ..................................219 13-9 fixed-length memory pool attribute ......................................................................................... ...................233 13-10 variable-length memory pool attribute ..................................................................................... ...................246 13-11 cyclic handler attribute .................................................................................................. ..............................264 13-12 interrupt service routine attribute....................................................................................... .........................284 13-13 exception handler attribute ............................................................................................... ...........................294 13-14 exception handler attribute ............................................................................................... ...........................296 13-15 extended service call routine attribute................................................................................... .....................299 user?s manual u14833ej2v0um 15 list of tables table no. title page 1-1 development environment ..................................................................................................... ........................19 2-1 synchronous communication function .......................................................................................... ................21 6-1 memory area ................................................................................................................. .................................69 7-1 service calls that can specify timeout ...................................................................................... ...................85 7-2 cyclic handler terminology correspondence table ............................................................................. .........86 13-1 error code list ............................................................................................................ .................................109 13-2 macro list................................................................................................................. ....................................112 13-3 parameter value ranges ..................................................................................................... ........................113 13-4 context that can issue service calls....................................................................................... ....................114 13-5 context from which service calls can be issued ............................................................................. ..........114 13-6 task management function service calls ..................................................................................... ...............117 13-7 task status ................................................................................................................ ..................................134 13-8 wait source ................................................................................................................ ..................................134 13-9 task-associated synchronization function service calls..................................................................... ........138 13-10 task exception processing function service calls.......................................................................... .............151 13-11 synchronization/communication management function service calls ........................................................16 1 13-12 memory pool management function service calls............................................................................. ..........231 13-13 time management function service calls.................................................................................... ................259 13-14 system status management function service calls........................................................................... ..........272 13-15 interrupt management function service calls ............................................................................... ...............283 13-16 system configuration management function service calls.................................................................... ......292 13-17 service call management function service calls............................................................................ ..............297 user?s manual u14833ej2v0um 16 chapter 1 overview the rx4000 ( itron4.0) is an embedded real-time, multitask control os that provides a highly efficient real-time, multitasking environment to increase the application range of processor control units. this product is a high-speed, compact os capable of being stored in and run from the rom of a target system. 1.1 real-time os control equipment demands systems that can rapidly respond to events occurring both internal and external to the equipment. conventional systems have utilized simple interrupt processing as a means of satisfying this demand. with the recent improvements in the performance and functionality of control equipment, however, it has proved difficult for systems to satisfy these requirements by means of simple interrupt processing alone. in other words, the task of managing the order in which internal and external events are processed has become increasingly difficult as systems have increased in complexity and programs have become ever larger. real-time operating systems have been designed to overcome this problem. the main goals of a real-time os are to respond to internal and external events rapidly and execute programs in the optimum order. 1.2 multitask os a ?task? is the minimum unit in which a program can be executed by an os. ?multitasking? is the name given to the mode of operation in which a single processor processes multiple tasks concurrently. actually, the processor can handle no more than one program (instruction) at a time. but, by switching the processor?s attention to individual tasks on a regular basis (at a certain timing), it appears that the tasks are being processed simultaneously. a multitask os therefore enables the parallel processing of tasks by switching the tasks to be executed as determined by the system. a major goal of a multitask os is to improve the processing capability of the overall system through the parallel processing of multiple tasks. chapter 1 overview user?s manual u14833ej2v0um 17 1.3 features the rx4000 has the following features. 1. conformity with itron4.0 specification as a representative embedded type control os architecture, the rx4000 is used to perform design that is compliant with the itron4.0 specification. thus, by constructing software in accordance with the itron4.0 specification, users can improve the software?s portability and capitalization. because the itron4.0 specification enables selection of an incorporation range in extended areas outside the standard profile, the following functions have been realized in the rx4000. ? all functions specified in the standard profile ? function to dynamically create and delete resources ? extended synchronous communication function (mutex) ? memory pool management function (fixed-length memory pool, variable-length memory pool) ? interrupt processing function ? service call management function (extended service call routine) ? system configuration management function ? state-referencing service calls (service calls prefixed with ?ref_?) 2. customization because processing that supports interrupts and cpu exceptions must have an exceptionally fast response time, by supplying the source code of these functions as a sample, users are able to customize the rx4000 to create the most suitable os for their peripheral hardware and other environments. 3. romization the rx4000 is a real-time, multitask os that has been designed on the assumption that it will be incorporated into the target system; it has been made as compact as possible to enable it to be loaded into a system?s rom. 4. utilities supporting system construction the rx4000 provides the following utilities to aid in system construction: ? cf4000 (system configurator) ? rd4000 (task d ebugger) 5. cross tools the rx4000 supports the following cross tools for the v r series?: ? ccmipe (green hills software?, inc.) chapter 1 overview user?s manual u14833ej2v0um 18 1.4 configuration the rx4000 consists of four subsystems: a kernel, an interface library, a system configurator, and a task debugger. these subsystems are outlined below. 1. kernel the center or nucleus of the rx4000 is called the kernel. the kernel is embedded in the target system along with the processing program (task/non-task), and provides real-time multitask processing such as task switching, as well as the various services requested via service calls. 2. interface library when a processing program (task/non-task) is written in a high-level language such as c and a service call is issued, an external function format is used as the service call issuance format. the input format that can be understood by the kernel, however, differs from the external function format. the interface library is therefore used to translate a service call issued in an external function format into the kernel input format. the interface library thus acts as an agent between processing programs and the kernel. the interface library provided by the rx4000 supports the c cross compiler shown in the tools in 1.7 development environment . 3. system configurator the system configurator is a tool that operates on the development machine and is used to output the tables (system information tables) in which the data required by the kernel during initialization (such as the number of tasks or semaphores, and the memory allocation) is stored. 4. task debugger the task debugger is a tool that operates on the development machine and is used to improve debugging at the software development stage by displaying via a gui information managed by the os, such as the state of a task or the number of semaphores. 1.5 applications the rx4000 can be used in the following application fields. ? control systems such as in automobiles and robots ? measuring instruments ? control devices such as exchangers, numerical controls, communication controls, and plant controls ? oa machines such as facsimiles and photocopiers ? data collection and data calculation systems such as medical treatment devices and space monitoring devices chapter 1 overview user?s manual u14833ej2v0um 19 1.6 execution environment the rx4000 is operated in target systems equipped with the following hardware. 1. processor v r 4100 series v r 5000 series 2. peripheral hardware in order to enable support of a wide variety of hardware environments, the hardware-dependant section of the kernel in the rx4000 is supplied as a separate source file, which can be used to rewrite this section to accord with the system used, thereby eliminating the need for specific peripheral hardware. 1.7 development environment the hardware and software environments required to develop an application system in which the rx4000 is embedded are shown below. table 1-1. development environment type name remarks host os windows 98/nt 4.0 windows 2000/me/xp solaris 2.5.x or later cross tools ccmipe v1.8.9 r400 (green hills software) debuggers partner-et ii/win multi v2.0 (kmc: kyoto microcomputer corporation) v1.8.9 r4.0.2 evaluation boards cmb-v r 4131 ostrich v r 4181a rte-v r 5500-cb partner-et ii v r 4131 evaluation board [solutiongear ii] (nec eloctronics) v r 4181a evaluation board (nec electronics) v r 5500 evaluation board (midas lab co., ltd.) rom emulator for board connection (kmc) user?s manual u14833ej2v0um 20 chapter 2 kernel this chapter describes the kernel, which is the core of the rx4000. 2.1 overview the kernel forms the heart of the rx4000 and is the main body of the os embedded in the target system together with the application program (tasks, handlers, etc.). the kernel provides the following two major functions. note that the module that controls the former is usually known as the scheduler. ? switching execution to the task selected as the most suitable task to be executed next, according to an event that occurs internal or external to the target system ? provision of functions corresponding to the service calls (system calls) issued from the tasks or handlers 2.2 configuration the kernel consists of a scheduler and management modules that exist in each function. these functions can be used by issuing the service calls provided by the rx4000. the configuration of the rx4000 kernel is shown below. figure 2-1. kernel configuration system status management time management memory pool management other interrupt management synchronous communication task management task exception processing task-associated synchronization scheduler (extended synchronous communication) system configuration management service call management chapter 2 kernel user?s manual u14833ej2v0um 21 2.3 functions this section overviews the functions of the scheduler and management modules. refer to chapter 3 scheduler to chapter 5 synchronous communication management for details of the individual management modules. 1. scheduler the scheduler manages and determines the order in which tasks are executed and assigns tasks the right to use the cpu. in the rx4000, the task execution order is determined according to an assigned priority and by applying the fcfs (first come first served) system. when activated, the scheduler determines the priorities assigned to the tasks, selects an optimum task from those ready to be executed (running or ready state) (by assessing which task has the highest priority and entered the ready state the earliest) and assigns that task the right to use the cpu. 2. task management this module manipulates and manages the states of a task, the minimum unit in which processing is performed by the rx4000. the module can, for example, create, activate, execute, stop, terminate, and delete a task. 3. task-associated synchronization this module is used to perform synchronization that is not reliant on objects other than tasks, such as semaphores. this module can, for example, put a task unconditionally into a self-imposed waiting state, interrupt execution of another task, or release another task from a waiting state. for further details of this module, refer to the explanation in chapter 4 task management . 4. task exception management this module is newly added for itron4.0 and is used to enable the writing of not only the routine for normal execution of the main body of tasks (task main processing routine), but also a task exception processing routine that is activated by the occurrence of an event exceptional to a task. a more detailed explanation of the task exception management function can be found in chapter 4 task management . 5. synchronous communication management this module provides the following five functions related to exclusive control, wait, and communication, which comprise the three types of synchronous communication between tasks. note that in accordance with itron4.0, the correct categorization of a mutex is as an extended synchronous communication function. table 2-1. synchronous communication function type provided function exclusion semaphores, mutexes wait event flags communication data queues, mailboxes chapter 2 kernel user?s manual u14833ej2v0um 22 6. memory management the memory area is managed by the rx4000 as two types of areas: memory pools and memory blocks. a memory pool consists of memory blocks grouped together in one large chunk. when memory is necessary to execute applications such as tasks or handlers, memory blocks can be acquired from a memory pool, and then returned to the memory pool when no longer required. performing this kind of dynamic memory manipulation allows users to make efficient use of a limited memory area. 7. time management the rx4000 manages a software clock to enable specific operations at a fixed interval or at a specified time, providing functions such as system clock management, task timeout (wait time upper limit setting), and cyclic handlers. 8. system status management system management functions provided in this module include enabling/disabling dispatch (task switching) and referencing the status of the system. note that this category appears for the first time in itron4.0; the majority of its associated service calls are classified into other categories in itron3.0. 9. interrupt management the two kinds of interrupt management functions provided in this module are interrupt control functions for processing such as enabling/disabling interrupts, and interrupt processing management functions for activating interrupt service routines corresponding to interrupt sources. note that because interrupt management is heavily dependent on the hardware operated by the application, a source file has been provided as a sample, allowing users to customize these functions. 10. service call management this module provides a function that can be used to register functions described by users as service calls. 11. system configuration management this module provides a function to allow users to register handlers that are used to process exceptions detected by the cpu, and a function to define the initialization routines called when the system is initialized. 12. initialization processing this module is used for processing such as initializing the hardware required for the rx4000 to operate and initializing the kernel itself. note that whereas the classifications of the functions in 1 to 11 above are specified by itron4.0, initialization processing is not subject to this specification. chapter 2 kernel user?s manual u14833ej2v0um 23 2.4 objects the tasks (task main processing routine, task exception processing routine), semaphores, event flags, data queues, mailboxes, mutexes, fixed-length memory pools, variable-length memory pools, memory blocks, cyclic handlers, interrupt service routines, extended service call routines, and cpu exception handlers, which are created or defined by the kernel and are under its management, are known as objects or kernel objects. (note that these are also sometimes called resources.) 2.4.1 object control blocks the rx4000 is equipped with data structures known as control blocks to manage the objects listed above. the control block saves information such as the status of the object, and is therefore the (logical) substance of the object to be processed by the kernel. control blocks and objects exist on a one-to-one basis. 2.4.2 object identification number to uniquely identify the objects or control blocks in the rx4000, a number specific to each resource type is used. the way this number is called and the range of its values differs depending on the resource. these numbers are classified as follows. 1. id number in the rx4000, each object (task, semaphore, event flag, data queue, mailbox, mutex, fixed-length memory pool, variable-length memory pool, cyclic handler, or interrupt service routine) is accessed using an id number. the id numbers are used as an index of the control block array when an object is accessed, and each object (task, semaphore, etc.) is assigned an id number with a unique value of 1 or higher. the maximum value (or range of usable id numbers) is that specified for each object in the system information table. 2. interrupt number interrupt service routines have an interrupt (source) number for specifying the interrupt source, which differs from the id number described above. the interrupt (source) number is a number that uniquely identifies each interrupt source, and must be assigned by the user. 3. extended function code extended function codes are used to access extended function routines. like an id number, an extended function code consists of a unique value of 1 or higher and is used as an index of the control block array. the maximum value of the extended function code is that specified in the system information table. 4. handler number when a cpu exception handler is defined, the cpu exception handler is assigned a unique value of 1 or higher known as its handler number, which like an id number is used as an index of the control block array. the maximum value of this number is also specified in the system information table. note that although the handler number accords with the id number in the kernel, it is necessary not only to identify the cpu exception handler, but also to clarify its correspondence with the exception source. 5. address the memory block is identified by its top address. chapter 2 kernel user?s manual u14833ej2v0um 24 2.4.3 creating and deleting objects when an object is created by issuing a service call such as cre_tsk, the index block specified from the control block array in the system pool is secured and initialized. the control block array is fixed when the kernel is initialized, based on the maximum value of each object as defined in the system information table. object creation therefore means the occupation of the relevant control block, and object deletion means the invalidation of the control block that was occupied, thereby putting it in a state whereby it can be occupied again when a new object is created. the size of the system pool is thus not affected by the creation or deletion of objects. 2.4.4 automatic assignment of id number an object can be created without specifying an id number by issuing a service call beginning with acre_, such as acre_tsk. when acre_xxx is issued, the kernel searches for an unoccupied control block in the non-existent state from the control block array for the object to be created. if the search is successful, the id number of that object is returned as the return value of the service call when creation processing is complete. an unsuccessful search results in the return of the error code e_noid, which indicates that id assignment failed. note that the id numbers that can be used by objects created by automatic assignment can be specified from the range assignable to each resource type. therefore, because a control block indexed with an id number that falls outside this range will not be subject to the aforementioned search processing, if automatic assignment fails, it does not necessarily mean that the maximum number of creatable objects already exists. user?s manual u14833ej2v0um 25 chapter 3 scheduler this chapter explains the scheduling performed by the rx4000. 3.1 overview the module that manages the sequence in which tasks are executed and performs task switching is known as the scheduler. the scheduler is activated each time a service call issued or an interrupt is generated. this chapter describes the functions of the scheduler and outlines the processing performed by it. 3.2 drive method the rx4000 scheduler uses an event-driven technique in which the scheduler activates driving in response to the occurrence of some kind of event, such as the issuance of a service call that may cause a task state to change from a processing program such as a task or a handler, or the generation of an interrupt (or more precisely, restoration from an interrupt). 3.3 scheduling methods when driven, the scheduler selects the task to be executed next according to predetermined methods, which in the rx4000 are priority order and fcfs (first come first served). 3.3.1 priority method each task is assigned a priority, which determines the sequence in which it will be executed. the scheduler checks the priority of each task that can be executed (in the running or ready state), selects the task with the highest priority, and assigns that task the right to use the cpu. 3.3.2 fcfs method the rx4000 can assign the same priority to more than one task. because the priority method is used for task scheduling, there is a possibility that more than one task with the same (highest) priority will be selected. in this case, the scheduler selects the task that first became executable from this group of tasks (i.e., the task that has been in an executable state for the longest time) and assigns it the right to use the cpu. this is known as the fcfs (first come first served) system. chapter 3 scheduler user?s manual u14833ej2v0um 26 3.4 ready queue in the rx4000, tasks in the executable (ready) or execution (running) states are queued by the fifo method in a hash table (ready queue) arranged according to priority order. the scheduler searches the ready queue activation from the top priority and assigns the task with the highest priority in the queue the right to use the cpu. in other words, the priority and fcfs methods are implemented in the running state. figure 3-1. ready queue : : ready queue priority high low task b task c task d task e task a task being executed chapter 3 scheduler user?s manual u14833ej2v0um 27 3.5 implementing a round robin method in scheduling based on the priority and fcfs methods, even if a task has the same priority as that currently running, it cannot be executed unless the task to which the right to use the cpu was assigned first enters another state or relinquishes control of the processor. the scheduling method generally used to avoid the above drawback is known as a round robin method. although the rx4000 does not include a round robin function itself, it does provide a service call, (i)rot_rdq, which can be issued periodically to enable this scheduling method. the round robin method is realized in the following way. (assumed conditions) ? task priority task a = task b = task c ? state of tasks task a: running state task b: ready state task c: ready state ? cyclic handler x is periodically activated and issues the irot_rdq service call 1. task a is currently being executed. the other tasks (b and c) have the same priority as task a but cannot be executed because task a has control of the cpu (see figure 3-2 ). figure 3-2. state 1 of ready queue during round robin processing low high cyclic handler x task c task b task a ready state ready state running state ready queue priority chapter 3 scheduler user?s manual u14833ej2v0um 28 2. cyclic startup handler x is activated when a predetermined period of time has passed, specifies the priority held by task a, and issues the service call irot_rdq. task a then shifts to the bottom of the ready queue and task b moves to the top (see figure 3-3 ). figure 3-3. state 2 of ready queue during round robin processing low high cyclic handler x task c task b task a ready state ready state in processing ready queue priority running state irot_rdq 3. cyclic startup handler x finishes processing and the scheduler is activated. because task a was shifted to the bottom of the ready queue and is therefore in the ready state, the scheduler searches for the task to execute next. because there are no tasks with a higher priority than tasks a, b, and c, task b, which is currently at the head of the queue, is executed (see figure 3-4 ). figure 3-4. state 3 of ready queue during round robin processing low high cyclic handler x task a task c task b ready state ready state running state ready queue priority repeating the processing described above realizes a round robin system. figure 3-5 shows the processing flow when round robin scheduling, in which 1 to 3 above are repeated, is performed. chapter 3 scheduler user?s manual u14833ej2v0um 29 figure 3-5. processing flow of round robin scheduling handler x task a task c task b priority: low priority: low ? t return irot_rdq (priority: low) irot_rdq (priority: low) priority: low irot_rdq (priority: low) ? t ? t return return chapter 3 scheduler user?s manual u14833ej2v0um 30 3.6 scheduling delay the execution order among processing units in the rx4000 such as tasks, interrupt service routines, and the scheduler is set as follows, based on the itron4.0 specification. cpu exception handler = interrupt service routine > cyclic handler > scheduler > task exception processing routine > task (task main processing routine) > idle routine in other words, even if scheduling is required such as releasing the waiting state of a task while a cpu exception handler, interrupt service routine, or cyclic handler is being executed, the scheduler cannot be driven because the processing under execution has a higher priority than the scheduler. this is because the processing performed by cpu exception handlers, interrupt service routines, and cyclic handlers is generally highly urgent and indivisible, and must therefore be carried out quickly. consequently, because scheduling will not occur while the above are being processed, there may be a delay between when a service call that requires scheduling is issued and when the scheduling actually takes place (see figure 3-6 ). figure 3-6. scheduling delay task a task b interrupt service routine delay period isig_sem return wai_sem interrupt generation priority: high priority: low waiting release chapter 3 scheduler user?s manual u14833ej2v0um 31 3.7 enabling/disabling scheduling in the rx4000, dispatch, or scheduler activation, can be explicitly enabled or disabled by the issuance of a service call from a task. if dispatch is disabled by a service call, scheduling processing is suspended and does not resume until a service call is issued to enable dispatch. the service calls used to enable and disable dispatch are as follows. dis_dsp: disables dispatch ena_dsp: enables dispatch loc_cpu: puts the system in a cpu-locked state unl_cpu: releases the system from the cpu-locked state the processing flow when enabling and disabling dispatch is shown below. figure 3-7. disabling dispatch task a task b priority: low delay period dis_dsp sig_sem ena_dsp wai_sem priority: high waiting release chapter 3 scheduler user?s manual u14833ej2v0um 32 3.8 idle routines an idle routine is a processing routine that is activated from the scheduler if all the tasks are either complete or in a waiting state, meaning that there are no longer any tasks in the ready state and therefore subject to scheduling (idle state). idle routines can be described by users to accord with the configuration of their system, enabling capitalization of the low power consumption mode functions provided by the target v r series processor. note that an idle routine is described as a void type function without an argument. example) void idle_routine(void) { standby(); return; } a service call must not be issued in an idle routine. nor can mips16 instructions be used. 3.8.1 registering idle routines idle routines are registered by specifying the static api vatt_idl or via the service call vatt_idl. one idle routine must always be registered in the system, so if the above processing is not performed, the kernel will register a default idle routine. a new idle routine can be registered when another idle routine is already registered (the previously registered data will be discarded), but idle routine registration cannot be canceled. the default idle routine simply performs unlimited loop processing. 3.8.2 executing and terminating idle routines if the scheduler is activated and judges that there are no executable tasks available, the kernel immediately executes an idle routine. when the idle routine has completed c language return or equivalent processing, it is executed again. return from an idle state to the normal state occurs when the scheduler is activated after the processing returns from servicing an interrupt that was generated in the idle routine, following which a task became executable. in this case, the processing does not return to where the interrupt was generated and the next processing of the idle routine is discarded. 3.8.3 pid if the idle routine registered by the user references pid (position independent data), the value of the gp register that should be set as the pid parameter must be set when the idle routine is registered. the assigned address is set in the gp register when the idle routine is activated. 3.8.4 coprocessor the fpu (coprocessor 1) cannot be used in an idle routine. 3.8.5 stack an idle routine uses the stack that is used by the system (syssp of the system base table). user?s manual u14833ej2v0um 33 chapter 4 task management this chapter describes the task management performed by the rx4000. 4.1 overview the processing program managed by the kernel is made up of units such as tasks, interrupt service routines, and cyclic handlers. unlike interrupt service routines, which are activated by interrupt generation, or cyclic handlers, which are activated after a certain time has elapsed, tasks, which are the basic processing units of the system, are not activated unless expressly manipulated by service calls. in the rx4000, tasks are managed using data structures that correspond to tasks on a one-to-one basis. these data structures are known as task control blocks. the task control block secures all the data required for task management when tasks are created, and discards this data when tasks are deleted. for further details of task control blocks, refer to the rx4000 ( itron4.0) technical user?s manual (u14835e) . the major items included in a task control block are shown below. ? task address ? priority ? current status ? id number of management object for which task is waiting ? stack pointer, etc. note that tasks are divided into task main processing routine and task exception processing routine blocks. since the task main processing routine is what is usually executed, unless specified otherwise, it is described in this document simply as a ?task?. tasks are described as void type functions with one vp_int type argument. the extended data exinf (activated by act_tsk) or the task activation code stacd (activated by sta_tsk) is passed for this argument. example) void task(vp_int exinf) { ... ext_tsk(); } chapter 4 task management user?s manual u14833ej2v0um 34 4.2 creating tasks tasks are created by issuing the service calls cre_tsk and acre_tsk. with acre_tsk, assignment of the id number can be performed by the kernel. specifying the static api cre_tsk enables processing equivalent to cre_tsk to be performed at system initialization. cre_tsk also allows activation processing to be performed at the same time as task creation. in task creation processing, the kernel recognizes data (text) expanded in the memory as a task and places that task under its management. task creation processing involves securing and initializing the index (id) block specified from the task control block array in the system pool, and securing the stack area from the stack pool. each created task has a unique id number. the id number must be an integer in a range of 1 to 0x7fff, and the maximum number that can be assigned is the number specified in the cf definition file. note that the size of the stack used by a task must be specified when the task is created. for how to calculate this size, refer to the rx4000 ( itron4.0) installation user?s manual (u14834e) . 4.3 deleting tasks in cases such as when a task has completed processing and restarting that task is no longer necessary, the task can be put into a non-existent state by issuing del_tsk; a process known as task deletion. it is also possible to perform task termination and deletion together using the service call exd_tsk. when a task is deleted, its task control block is invalidated, and can be used for a newly created task. note that when a task is deleted, its stack area is also released. 4.4 activating tasks two service calls are supplied in the rx4000 for activating tasks: (i)act_tsk and (i)sta_tsk. (i)act_tsk is used to retain an activation request. 4.4.1 activation with activation request retained when (i)act_tsk is issued, if the target task is in the dormant state, it shifts from the dormant state to the ready state, becoming subject to scheduling by the kernel. if the target task is in a state other than the dormant (or non- existent) state, when (i)act_tsk is issued, the activation request is retained, causing the target task to be reactivated as soon as it has terminated. the extended data exinf specified when a task is created is passed as the activation parameter for tasks activated by (i)act_tsk. note that if ta_act is assigned as the attribute of a task created by the static api cre_tsk, the activation processing of that task is equivalent to that of act_tsk. 4.4.2 activation with activation request not retained (i)sta_tsk is provided in the rx4000 as a task activation method compatible with the itron3.0 specification, in which tasks are activated without retention of the activation request. if (i)sta_tsk is issued for a task in the dormant state, the task shifts from the dormant state to the ready state, becoming subject to scheduling by the kernel. if (i)sta_tsk is issued for a task that is in a state other than dormant, an error occurs, and the activation request is not retained. for tasks activated by (i)sta_tsk, the vp_int type data (4 bytes), which was specified as the (i)sta_tsk parameter, can be received as the task activation code instead of the extended data exinf. chapter 4 task management user?s manual u14833ej2v0um 35 4.5 terminating tasks task termination occurs when a task that was activated and executing processing shifts back into the dormant state. tasks can be terminated either normally or forcibly, as defined by the service call that terminates the task. note that a terminated task?s priority, wakeup request number, and suspend request number are initialized to the values set when the task was created. 4.5.1 normal termination when a task has completed processing and no longer needs to be subject to scheduling, it issues the service call ext_tsk or exd_tsk and self-terminates. task termination via ext_tsk or exd_tsk is commonly known as normal termination. note that ext_tsk effects termination only, whereas exd_tsk both terminates and deletes the task. if the task is locking any mutexes, these locks are released when the task terminates. 4.5.2 forcible termination if necessary, a task can be urgently terminated by issuing the service call ter_tsk. a task that receives this service call shifts into the dormant state and terminates, regardless of the state it was in at that time. this processing is known as forcible termination. if the task is locking any mutexes, these locks are released when the task is forcibly terminated. 4.5.3 reactivating terminated tasks in itron4.0, the activation request for a task can be retained, and that task can be reactivated as soon as it terminates (whether normally or forcibly). in other words, the task is shifted immediately from the dormant state back to the ready state upon termination. note, however, that the activation request for a task that was terminated by exd_tsk is ignored, and the task is shifted to the non-existent state. chapter 4 task management user?s manual u14833ej2v0um 36 4.6 task states the task changes its state according to how resources required to execute the processing are acquired, whether an event occurs, and so on. task states are always managed by the kernel, which performs the processing required according to that state. the seven states applicable to tasks are described below. (1) non-existent a task in this state has not been created or has been deleted, and is not registered in the kernel. a task in the non-existent state is therefore not managed by kernel even though its code is located in memory. (2) dormant a task in this state has just been created or has already completed its processing. a task in the dormant state is not subject to scheduling by the kernel, even though it is under the kernel?s management. (3) ready a task in this state is ready to perform its processing, but has been waiting to be assigned the right to use the cpu (execution right) because another task with the same or higher priority is being executed. a task in the ready state is subject to scheduling by the kernel, and can be shifted to the running state as soon as it receives the execution right. (4) running a task in this state has been assigned the execution right and is either currently performing its processing or has had its processing interrupted while an interrupt service routine or handler is being executed. within the entire system, only a single task can be in the running state at any one time. (5) waiting a task in this state has been stopped because the requirements for performing its processing, such as the acquisition of a semaphore or memory block, have not been satisfied. the processing of this task is resumed from the point at which it was stopped. at this time, the data (context) required to execute the program is restored to the state it was in immediately before the stoppage. the acquisition status, etc., of resources that are unrelated to the wait are not affected by the stoppage/resumption of execution. the waiting state is further divided into the following types of states, according to the wait source. for further details of these states, refer to the next and subsequent chapters. type waiting for: service call causing wait wake-up wait reception of wake-up request (t)slp_tsk time elapse wait lapse of time dly_tsk semaphore wait acquisition of resource from semaphore (t)wai_sem event flag wait establishment of event flag condition (t)wai_flg data transmission wait completion of data write to buffer (t)snd_dtq data reception wait reception of data (t)rcv_dtq message reception wait reception of a message (t)rcv_mbx mutex wait locking a mutex (t)loc_mtx fixed-length memory block wait acquisition of fixed-length memory block (t)get_mpf variable-length memory block wait acquisition of variable-length memory block (t)get_mpl chapter 4 task management user?s manual u14833ej2v0um 37 (6) suspended a task in this state has been forcibly stopped by the issuance of the service call (i)sus_tsk. in itron3.0, (i)sus_tsk was only recognized if issued by another task or handler, but in itron4.0, a task can issue sus_tsk to itself. because the suspended state can be nested by issuing (i)sus_tsk in multiple (i.e., more than once for the same task), it is necessary to issue the same number of (i)rsm_tsk service calls, or issue (i)frsm_tsk, to release the suspended state. the processing of this task is resumed from the point at which it was stopped; i.e., the point at which it was preempted by the task or handler that issued (i)sus_tsk. at this time, the data required to execute the program, such as the register values, is restored to the state it was in immediately before the stoppage. the acquisition status, etc., of task resources that are unrelated to the wait are not affected by the stoppage/resumption of execution. (7) waiting-suspended this state is a combination of the waiting and suspended states described in (5) and (6) above. a task in this state has entered the waiting state upon exiting the suspended state, or has entered the suspended state upon exiting the waiting state. like the suspended state, the waiting-suspended state enables nesting of states through the multiple issuance of (i)sus_tsk. it is therefore necessary to issue the wait release service call (rel_wai, sig_sem, etc.) and the same number of (i)rsm_tsk service calls as (i)sus_tsk calls or (i)fsm_tsk to shift a task in the waiting- suspended state to the ready state (or in some cases, immediately to the running state). chapter 4 task management user?s manual u14833ej2v0um 38 4.7 task state transition tasks are repeatedly shifted between the states described in 4.6 task states by means of service call issuance. task states and state transitions are shown in figure 4-1 below. figure 4-1. task state transition running ready waiting waiting- suspended dispatch preempt resume suspend release wait wait suspended release wait dormant non-existent create delete activate/resume forcibly terminate forcibly terminate suspend terminate/delete terminate resume chapter 4 task management user?s manual u14833ej2v0um 39 4.8 task delay and timeout tasks in the waiting state described in 4.6 (5) waiting above can be released after an arbitrary period of time has elapsed. it is also possible to delay the execution of a task for a specified amount of time using the service call dly_tsk. this kind of processing is known as timer operation. for details of timer operation, refer to chapter 7 time management . timer operation as related to tasks is summarized below. (1) timeout when a task is shifted to the waiting state, the maximum time that task is to stay in the waiting state can be set by specifying a timeout time. in other words, if the wait release conditions are not met before the specified time elapses after a service call was issued, the task is forcibly released from the waiting state. this is known as timeout. the error code e_tmout indicating a timeout is returned as the return value of a service call for tasks in a timeout state. (2) time elapse wait a task can be made to stay in the waiting state for only a specified time by issuing the service call dly_tsk. in other words, a task is subject to waiting for a specified time, after the elapse of which the task is released. 4.9 task priority order a task has three values related to its priority: its initial priority, its current priority, and its base priority. in the rx4000, the lower the value of the priority assigned to a task, the higher the priority. (1) initial priority this is the priority of a task immediately after activation. this value can only be specified when the task is created, and cannot be subsequently changed. when a task terminates and is reactivated, its priority is initialized to this value. (2) current priority this value indicates the priority of the task after it has been activated. the task execution order or the place of a task in the task queue is determined by its current priority value. the current priorities of tasks can be dynamically changed by the service call chg_pri (ichg_pri) and can be obtained by the service call get_pri (iget_pri). (3) base priority when a task is not participating in mutex-based synchronization, the base priority is always the same as the current priority. when the task is synchronized using a mutex, the current priority of the task may change, depending on the priority control protocol of the target mutex. at this time, the priority order to which the task returns after releasing the mutex lock is known as the base priority. chapter 4 task management user?s manual u14833ej2v0um 40 4.10 task context the environment in which the program operates is generally known as the context. in other words, the context indicates the stack area (space) used by the cpu operation mode or program and the statuses (registers) saved to the stack during program execution. in the same way, the environment in which tasks operate is known as the task context. therefore, when processing such as service call issuance from a task is performed, it is sometimes called ?performing processing from a task context?. moreover, when task switching, such as shifting a task to the waiting state, occurs, the value of the register of when the task was being executed is saved to (or restored from) the stack area. this register value saved in the stack area is called the task context. for details of the types of registers that include task contexts and the structures used when contexts are written to the memory, refer to the rx4000 ( itron4.0) technical user?s manual (u14835e) . 4.11 pid if pid (position independent data) is used for the code created when the task program is compiled or assembled, the address that is to be the base of a task when it is created must be assigned as a parameter (gp of the task creation packet t_ctsk). the assigned address is set in the gp register when the task is activated and saved to or restored from the context when the task is switched. note that this base address is unconditionally set in the gp register regardless of its attribute, etc., and therefore must be set for programs that reference the gp register. if the gp register is not referenced, set null = 0. 4.12 obtaining task information task information such as the task status can be obtained by using the service calls ref_tsk, iref_tsk, ref_tst, and iref_tst. for details of each service call, refer to chapter 13 . 4.13 coprocessor when a task is assigned the attribute ta_cop at creation, thus specifying use of the fpu (coprocessor 1), fcr31 (control/status register of fpu) at activation has the same value as fcr31 of the task executed immediately before this task is activated. if it is necessary to use fcr31 of the task to be activated, to generalize the processing and reduce the overhead, instead of using the kernel to perform the processing that sets fcr31, this processing must be described in the prolog section of the function described as a task. also, the number of fpu registers that can be used by tasks with the attribute ta_cop is determined uniformly for the entire system, and therefore specified according to the configuration of the system (cf definition file). the status registers required for task execution (cu, fr) are set by the kernel according to the ta_cop attribute and configuration specifications. in addition, the fcr31 and fpu registers are included in the context of tasks to which the ta_cop attribute has been assigned, and are saved/restored when those tasks are switched. chapter 4 task management user?s manual u14833ej2v0um 41 4.14 task exceptions 4.14.1 task exception processing routines a task exception processing routine is a routine that is activated when an event exceptional to a task occurs. because tasks can be divided into task main processing and task exception processing routines, the task exception processing routine is actually a part of a task and therefore operates on the same context as the task main processing routine. in other words, when a task exception processing routine is activated, the applied parameters, such as the stack to be used, the priority order, the status of interrupts (enabled/disabled), and the use of the coprocessor, are identical to those of the task, or task main processing routine with which the exception processing routine is paired. note that task exception processing routines are described as void type functions with flgptn and vp_int type arguments. the bit pattern of the exception source that triggers activation of the task exception processing routine (described later) and the extended data held by the tasks are passed for these arguments. example) void task_exception(flgptn texptn, vp_int exinf) { ... return; } 4.14.2 defining task exception processing routines a task exception processing routine is defined by issuing def_tex. equivalent processing to def_tex can also be realized by specifying the static api def_tex when the system is activated up. def_tex specifies a task id number (or the id number of the task (task main processing routine) with which it is paired) as its parameter. note that if def_tex is issued for a task for which a task exception processing routine has already been defined, the previous definition is deleted, and the new exception processing routine definition becomes valid. 4.14.3 canceling task exception processing routine definitions a task exception processing routine definition is canceled by issuing def_tex with null specified in the definition packet address of the exception processing routine. chapter 4 task management user?s manual u14833ej2v0um 42 4.14.4 task exception enabled/disabled states tasks have two states related to task exception processing: a task exception enabled state and a task exception disabled state. in the latter state, task exception processing requests are held pending, and the task exception processing routine is not activated. the conditions under which the enabled/disabled state changes are summarized below. task exceptions become disabled when: ? a task is activated ? def_tex is issued and a new exception processing routine is defined ? def_tex is issued and an exception processing routine is redefined in the task exception disabled state (continuance of disabled state) ? def_tex is issued and an exception processing routine is canceled ? dis_tex is issued ? a task exception processing routine is activated task exceptions become enabled when: ? ena_tex is issued ? processing shifts from a task exception processing routine to a task (except when dis_tex is issued in an exception processing routine) ? def_tex is issued and an exception processing routine is redefined in the task exception enabled state (continuance of enabled state) 4.14.5 task exception processing requests when some kind of event exceptional to a task occurs, (i)ras_tex is issued and a task exception processing execution request is sent to that task. to issue (i)ras_tex, a 32-bit bit string (texptn type), which is held as the exception source when the exception processing routine is activated (pending exception source), is specified. if (i)ras_tex is issued more than once before the task exception processing routine is actually activated, the activation source is updated with the logical sum of the values specified by the multiple (i)ras_tex service calls. when a task exception processing routine is activated, the pending exception source is passed as the parameter of the task exception processing routine, and then cleared to 0. although it is possible to request exception processing for the same task by issuing iras_tex from an interrupt servicing routine or cyclic handler activated while the task exception processing routine is being executed, in this case, the pending exception source will only be updated, and there will be no effect on the exception source of the task exception processing routine being processed. chapter 4 task management user?s manual u14833ej2v0um 43 4.14.6 activating task exception processing routines a task exception processing routine is activated by the kernel when all of the following four conditions are met. ? task exceptions are in the enabled state ? the pending exception source is not 0 ? the task is in the running state ? the non task context of an interrupt service routine or a cyclic handler is not under execution in other words, the conditions for tasks when task exceptions are enabled are: (1) the task has been put in the running state by the issuance of a dispatch and the pending exception source is not 0 at that time (2) the pending interrupt source is not 0 when interrupt processing has finished and processing returns to the task (3) ras_tex has been issued by a task to itself (4) the pending interrupt source is not 0 when the task exception processing routine has finished in the above cases, the task exception processing routine is activated immediately before control is shifted to the task (main processing routine). the processing flow when a task exception processing routine is activated is shown below. figure 4-2. example of task exception processing routine activation (1) time task b task a task a? (exception processing routine) pending exception source of task a other than 0 0 figure 4-3. example of task exception processing routine activation (2) time task a task a? (exception processing routine) pending exception source of task a other than 0 0 interrupt service routine iras_tex 0 chapter 4 task management user?s manual u14833ej2v0um 44 figure 4-4. example of task exception processing routine activation (3) time task a task a? (exception processing routine) pending exception source of task a 0 ras_tex 0 figure 4-5. example of task exception processing routine activation (4) time task a task a? (exception processing routine) pending exception source of task a other than 0 0 interrupt service routine iras_tex 0 end note that in case (3), ?the task itself? includes tasks undergoing task exception processing. in other words, if task exceptions have been enabled by the issuance of ena_tex during task exception processing, multiple task exception processing routines may be activated by the exception request issued from interrupt processing, etc. however, be aware that in this case, an unlimited number of task exception processing routines may be inadvertently activated. the exception source and extended data held by the task can be received as parameters for activated task exception processing routines. 4.14.7 terminating task exception processing routines c language return or equivalent processing is carried out to terminate a task exception processing routine. once a task exception processing routine is terminated, the kernel rechecks the pending exception source, and if it is not 0, reactivates the task exception processing routine. if the pending exception source is 0, the task exception disabled state of the task is released (except for cases when dis_tex has been issued during task exception processing), and control is returned to the task main processing routine. chapter 4 task management user?s manual u14833ej2v0um 45 4.14.8 issuing service calls from task exception processing routines all the service calls that can be issued from a task can be issued from a task exception processing routine. in other words, there is no difference between the service calls that can be issued from the task?s main processing and exception processing routines. therefore, if a service call that transfers a task to a waiting state, such as slp_tsk, or a service call that terminates a task, such as ext_tsk or exd_tsk, is issued from a task exception processing routine, the processing that is subsequently carried out is the same as if the service call was issued from the task main processing routine. 4.14.9 obtaining task exception processing routine information information on the task exception processing routine can be obtained by using the service calls sns_tex, ref_tex, and iref_tex. for details of each service call, refer to chapter 13 . user?s manual u14833ej2v0um 46 chapter 5 synchronous communication management this chapter describes the synchronous communication management performed by the rx4000. 5.1 overview in an environment where multiple tasks are executed concurrently (multitasking), the result produced by a certain task may determine the next task to be executed or affect the processing performed by the subsequent task. in other words, it may happen that some task execution conditions vary with the processing performed by another task, or that the processing performed by some tasks is related. liaison functions are therefore required between tasks so that task execution will be suspended to await the result output by another task. these functions are known as synchronization and communication functions, and in the rx4000 the synchronization and communication functions provided include semaphores, event flags, data queues, mailboxes, and mutexes. these functions are described in the following sections. 5.2 semaphores the elements required to execute tasks are known as resources, which include all the hardware components, such as the processor, memory, and i/o devices, and software components, such as the files and programs. because it is often impossible for multiple tasks to simultaneously use the same resource, a multitasking environment requires a function to prevent possible resource contention. as a means of realizing the exclusive control of resources that would prevent this kind of contention, the rx4000 provides non-negative counter-type semaphores. semaphores contain counters for controlling the number of resources, and by treating semaphores as abstract resources, it becomes possible to perform exclusive control between tasks. 5.2.1 creating semaphores semaphores can be created either by issuing the service call (a)cre_sem, or by specifying the static apicre_sem, which performs equivalent processing to (a)cre_sem when the system is initialized. if (a)cre_sem is issued, the attribute, initial counter value, and maximum counter value (etc.) are stored in the block corresponding to the id number that specifies the semaphore control block area secured as an array, and that control block is then initialized. the semaphore id number consists of a unique number of a value 1 or higher. the maximum value that can be specified is the one defined in the system information table, up to a maximum of 0x7fff numbers. any value of 0 or higher can be specified for a semaphore?s initial counter value, and any value of 1 or higher for the maximum counter value, but the former cannot exceed the latter. the maximum specifiable value is 0x7ffffff. chapter 5 synchronous communication management user?s manual u14833ej2v0um 47 5.2.2 deleting semaphores a semaphore is deleted by issuing the del_sem service call. in other words, once del_sem is issued, the kernel invalidates the specified semaphore control block and puts the target semaphore in the non-existent state. even if a task exists that has acquired a resource for the deleted semaphore, that semaphore will still be deleted. in this case, all the waiting tasks are released from the waiting state and the error code e_dlt indicating that the semaphore has been deleted is returned as the return value of the service calls wai_sem and twai_sem. note, however, that tasks that have already acquired a semaphore will not be notified of that semaphore?s deletion. after a semaphore is deleted, a semaphore with the same id number as the deleted semaphore can be newly created. 5.2.3 acquiring resources resources are acquired from semaphores by issuing one of the service calls wai_sem, twai_sem, or pol_sem. if there is a request to acquire a resource, the kernel checks the value of the resource counter of the target semaphore and assigns the resource to the task if the counter is 1 or higher (decrementing the counter by 1), or carries out the processing corresponding to the issued service call if the counter is 0. in other words, a task is put in the resource acquisition waiting state by the service calls wai_sem and twai_sem, and waits until the resource has been acquired, in the case of wai_sem, or until either the resource has been acquired or a specified time has elapsed, in the case of twai_sem. the issuance of pol_sem results in a service call error, and the task is informed that resource acquisition failed. tasks in the resource acquisition waiting state are registered in the waiting task queue of the specified semaphore. it is therefore possible to have multiple tasks waiting for the same semaphore, in which case a request for resource acquisition sent to a semaphore for which tasks are already waiting will not result in an error; the task will simply be put in the resource acquisition waiting state. tasks can be registered in the waiting task queue of a semaphore by two methods, depending on the attribute specified when the semaphore was created. one method is registering tasks in the queue in the order of their priorities, which is used for semaphores with the attribute ta_tpri. the other method is registering tasks in the queue in the order in which they requested resources, which is used for semaphores with the attribute ta_tfifo. if waiting tasks are released by the issuance of the service call (i)sig_sem, the tasks are always released in order from the top of the queue. 5.2.4 returning resources a resource is returned to a semaphore by issuing the service call (i)sig_sem. when (i)sig_sem is issued, the kernel checks the waiting queue of the target semaphore and if there are tasks registered in the queue, it immediately assigns the task at the top of the queue the resource and releases it from the waiting state. at this time, the value of the resource counter remains unchanged. if there are no tasks registered in the waiting queue, the resource counter value is incremented by 1. note that because only one resource can be manipulated per service call, multiple tasks are never released simultaneously by one issuance of (i)sig_sem. 5.2.5 obtaining semaphore information semaphore information such as the number of resources can be obtained by using the service calls ref_sem and iref_sem. for details of each service call, refer to chapter 13 . chapter 5 synchronous communication management user?s manual u14833ej2v0um 48 5.2.6 examples of exclusive control using semaphores some examples of exclusive control using semaphores are shown below. (1) cre_sem is issued creating a semaphore. the value of the initial counter is 1. (2) for task a to use a resource, wai_sem is issued and a resource is acquired from the semaphore. count = 1 semaphore x task a request for resource acquisition successful count = 0 semaphore x task a running state running state sem wai_sem (3) for task b to use a resource, wai_sem is issued and an attempt is made to acquire a resource from a semaphore. however, because the value of the semaphore resource counter is 0, task b is put in the waiting state and is registered in the semaphore?s waiting task queue. task b request for resource acquisition impossible count = 0 semaphore x task b running state waiting state count = 0 semaphore x registration wai_sem chapter 5 synchronous communication management user?s manual u14833ej2v0um 49 (4) when task a has finished using the resource, sig_sem is issued and the resource is returned to the semaphore. task b acquires the resource and is subsequently released from the resource acquisition waiting state, and removed from the semaphore?s waiting task queue. task a return of resource resource returned count = 0 semaphore x running state waiting state count = 0 semaphore x registration task b sem ready state task b task a running state sem sig_sem (5) when task b has finished using the resource, sig_sem is issued and the resource is returned to the semaphore. the semaphore?s resource counter is subsequently incremented by 1. task b return of resource resource returned count = 1 semaphore x running state running state count = 0 semaphore x task b sem sig_sem chapter 5 synchronous communication management user?s manual u14833ej2v0um 50 5.3 event flags in multitask processing, an intertask wait function is required in which other tasks wait to resume execution of processing until execution of a given task is complete. to support this function, event flags are provided in the rx4000 to allow other tasks to judge whether or not the ?processing complete? event has occurred. an event flag is a set of data consisting of 1-bit flags that indicate whether a particular event has occurred. the event flags used in the rx4000 are 32 bits, which are handled as a set of information with each bit or a combination of bits having a specific meaning. 5.3.1 creating event flags event flags can be created either by issuing the service call (a)cre_flg, or by specifying the static api cre_flg, which performs equivalent processing to (a)cre_flg when the system is initialized. if (a)cre_flg is issued, the attribute, initial counter value, and maximum counter value (etc.) are stored in the block corresponding to the id number that specifies the event flag control block area secured as an array, and that control block is then initialized. the event flag id number consists of a unique number of a value 1 or higher. the maximum value that can be specified is the one defined in the system information table, up to a maximum of 0x7fff numbers. any 32-bit value can be specified for an event flag?s initial bit pattern. 5.3.2 deleting event flags an event flag is deleted by issuing the service call del_flg. when del_flg is issued, the kernel invalidates the specified event flag control block and puts the target event flag in the non-existent state. even if a task exists that has satisfied the wait release conditions for the deleted event flag, that event flag will still be deleted. in this case, all the waiting tasks are released from the waiting state and the error code e_dlt indicating that the event flag has been deleted is returned as the return value of the service calls wai_flg and twai_flg. after an event flag is deleted, an event flag with the same id number as the deleted event flag can be newly created. 5.3.3 waiting for events to wait for the establishment of an event using an event flag, the required bit pattern is specified for either wai_flg, twai_flg, or (i)pol_flg, which is then issued. when one of these service calls is issued, the kernel compares the bit pattern of the event flag when the service call was issued with the specified bit pattern, and determines whether an event has been established based on the wait conditions described later. if an event has already been established, the service call is immediately terminated normally, allowing task processing to continue. if an event is not established, wai_flg and twai_flg make the task wait: until the event flag satisfies the wait release conditions in the case of the former, and until either the event flag satisfies the wait release conditions or a specified time has elapsed in the case of the latter. the issuance of (i)pol_flg results in a service call error, and the task is informed that an event was not established. note that event flags have two attributes: ta_wsgl and ta_wmul, and those with the former attribute cannot be simultaneously held by multiple tasks (whereas those with the latter attribute can). accordingly, if wai_flg, twai_flg, or (i)pol_flg is issued for an event flag with the attribute ta_wsgl already being held by a waiting task, an error occurs unconditionally, regardless of whether an event was established or not, and the error code e_obj is returned. because event flags with the attribute ta_wmul can be held by multiple tasks, waiting tasks with event flags are registered in the waiting task queue, either in fifo or priority order (ta_tfifo and ta_tpri attribute respectively). if (i)set_flg is issued, the kernel determines the wait release conditions of the tasks in the order of this waiting task queue. chapter 5 synchronous communication management user?s manual u14833ej2v0um 51 5.3.4 setting event flags the value of an event flag is set by issuing either (i)set_flg or (i)clr_flg. (i)set_flg is issued when any bit of the event flag is set to 1. when (i)set_flg is issued, the bit pattern of the event flag when the service call was issued is ored with the specified bit pattern and set to the event flag as a new bit pattern. (i)clr_flg is issued when any bit of the event flag is set to 0. when (i)clr_flg is issued, the bit pattern of the event flag when the service call was issued is anded with the specified bit pattern and set to the event flag as a new bit pattern. when there is a task waiting for an event flag, if (i)set_flg is issued and the event flag is updated, wait release condition judgement processing is carried out. this judgement processing is carried out either until a wait release condition is first satisfied (for event flags with the attribute ta_clr), or for all the event flags. when (i)clr_flg is issue d, only event flag update processing is carried out. this is because the judgement concerning the establishment of an event is made by checking whether all or any one of the specified bits are 1, as described in 5.3.5 wait conditions, making it impossible for a condition to be established by issuing (i)clr_flg. 5.3.5 wait conditions one of the following judgement methods can be specified as a wait condition for wai_flg, twai_flg, and (i)pol_flg when determining whether an event has been established. (1) and wait (twf_andw) the waiting state continues until all bits to be set to 1 in the required bit pattern have been set in the relevant event flag. in other words, if the specified bit pattern is waiptn and the bit pattern of the event flag is curptn, the event establishment condition is as follows. curptn & waiptn == waiptn (2) or wait (twf_orw) the wait state continues until any bit to be set to 1 in the required bit pattern has been set in the relevant event flag. the event establishment condition is therefore as follows. curptn & waiptn != 0 5.3.6 event flag clear attribute if an event flag has the attribute ta_clr, it is cleared to 0 when the required condition is satisfied. an event flag with the attribute ta_wmul held by multiple waiting tasks is cleared to 0 as soon as the first task is released from the waiting state. accordingly, because the bit pattern subject to condition judgement is 0, wait release condition judgement is not performed for tasks registered behind this task in the waiting task queue. 5.3.7 obtaining event flag information task information such as the bit pattern of an event flag can be obtained by using the service calls ref_flg and iref_flg. for details of each service call, refer to chapter 13 . chapter 5 synchronous communication management user?s manual u14833ej2v0um 52 5.3.8 examples of wait function using event flags some examples of wait processing using event flags are shown below. the numbers in the diagrams indicate the current bit pattern of the event flag and the bit pattern required by the task. all these numbers are in binary. note that although the bit width of event flags is usually 32 bits, for simplification purposes, this has been reduced to 8 bits in the examples. (1) cre_flg is issued creating an event flag. ta_clr is specified for the event flag attribute and the initial bit pattern is 00000000. (2) wai_flg is issued to make task a wait. at this time, the required bit pattern is 00000011 and the wait mode is twf_andw. because the current bit pattern of the event flag is 0, the condition is not established, and task a enters the waiting state and is registered in the event flag?s waiting task queue. 00000000 event flag x task a 00000011 waiting condition not established task a 00000011 running state waiting state event flag x 00000000 registration wai_flg (3) set_flg is issued to make task b wait for task a and the value of event flag x is updated to 00000001. however, because the bit pattern required by task a is 00000011 and the wait mode is twf_andw, not all the required bits have been set in event flag x, so task a continues waiting. condition not established task a 00000011 waiting state event flag x 00000000 registration task b running state setting 00000001 task a 00000011 waiting state event flag x 00000001 registration set_flg chapter 5 synchronous communication management user?s manual u14833ej2v0um 53 (4) set_flg is issued to make task c wait for task a and the value of event flag x is set to 00000110. the value of the flag before set_flg was issued, 00000001, and the newly set value, 00000110, are ored, and event flag x is updated with the resulting value, 00000111, which satisfies the wait release condition of task a. task a is therefore released from the waiting state and the bit pattern of when task a was released from waiting, 00000111, is passed to task a as the return parameter. also, because event flag x has the attribute ta_clr, it is cleared to 0 after task a is released from waiting. condition established task a 00000011 waiting state event flag x 00000001 registration task c running state setting 00000110 task a ready state event flag x 00000000 task c running state 00000111 bit pattern when condition established set_flg chapter 5 synchronous communication management user?s manual u14833ej2v0um 54 5.4 data queues in a multitasking environment, when multiple tasks operate together to perform a specified processing, an intertask communication function is required to inform other tasks of the execution results of a certain task. in the rx4000, data queues and mailboxes are provided as a means of realizing this function. for a data queue, transmit data is fixed to 4 bytes and there is a limit to the total amount of data that can be stored. for a mailbox on the other hand, data of any format can be transmitted, and there is no limit to the total amount of storable data. users can therefore select and use whichever of these has the features that accord with their system configuration. this section describes data queues, which consist of a ring buffer in which the data to be communicated is stored and a waiting task queue in which waiting tasks are registered. data queues not only enable communication between tasks, but also make it possible to have tasks wait in response to data. 5.4.1 creating data queues data queues can be created either by issuing the service call (a)cre_dtq, or by specifying the static api cre_dtq, which performs equivalent processing to (a)cre_dtq when the system is initialized. when (a)cre_dtq is issued, firstly the area of the ring buffer to be used by the data queue is secured from the user pool. after that, the attribute, buffer address, and buffer size (etc.) are stored in the block corresponding to the id number that specifies the data queue control block area, and that control block is then initialized. the data queue id number consists of a unique number of a value 1 or higher. the maximum value that can be specified is the one defined in the system information table, up to a maximum of 0x7fff numbers. note that data queues without buffers can also be created. 5.4.2 deleting data queues a data queue is deleted by issuing the del_dtq service call. when del_dtq is issued, the kernel returns the area of the ring buffer being used by the specified data queue to the user pool and then invalidates the control block and puts the target data queue in the non-existent state. even if a task exists that has transmit/receive data for the deleted data queue, that data queue will still be deleted. in this case, all the waiting tasks are released from the waiting state and the error code e_dlt indicating that the data queue has been deleted is returned as the return value of the service call. after a data queue is deleted, a data queue with the same id number as the deleted data queue can be newly created. chapter 5 synchronous communication management user?s manual u14833ej2v0um 55 5.4.3 receiving data data is received from the data queue by issuing one of the service calls rcv_dtq, trcv_dtq, or (i)prcv_dtq. if there is a data reception request, the kernel checks whether there is unreceived data in the ring buffer being used by the data queue. if unreceived data exists, the task receives the data at the top of the ring buffer and continues processing. the kernel then checks the transmission waiting task queue of the data queue, and if there is a task waiting in this queue, it stores the transmit data of the waiting task in the space in the ring buffer area made available by the previous data reception processing, at which point the task is released from the waiting state. accordingly, a dispatch occurs when the task that was in the waiting state has a higher priority than the task currently running. if there is no data stored in the ring buffer, the service calls rcv_dtq and trcv_dtq put the task into a data reception waiting state: until data is received in the case of the former, and until either data is received or a specified time has elapsed in the case of the latter. the issuance of (i)prcv_dtq results in a service call error, and the error code e_tmout is returned, indicating that polling failed. tasks waiting to receive data are registered in the waiting task queue of the data queue. because multiple tasks can be waiting in the waiting task queue of the same data queue, a request for data reception sent to a data queue in whose waiting task queue tasks are already waiting will not result in an error; the task will simply be put in the data reception waiting state. tasks can only be registered in the waiting task queue in fifo order. waiting tasks are therefore registered in the queue in the order in which data reception requests were sent, and released in that order when data is transmitted by a service call such as snd_dtq. 5.4.4 obtaining data queue information data queue information such as the number of data not received can be obtained by using the service calls ref_dtq and iref_dtq. for details of each service call, refer to chapter 13 . 5.4.5 transmitting data data is transmitted to the data queue by issuing one of the service calls snd_dtq, (i)psnd_dtq, tsnd_dtq, or (i)fsnd_dtq. if there is a data transmission request, the kernel checks the reception waiting task queue of the data queue, and if there is a task waiting in this queue, it assigns data to the task at the top of the queue and releases that task from the waiting state. although it is possible for the task that transmitted the data to continue processing, if the task just released from the waiting state has a higher priority, then the task currently running is dispatched. if there are no tasks waiting for reception, the kernel checks the ring buffer of the data queue to see if there is any free space. if there is free space, the transmit data is copied to the buffer and the task continues processing. if there is no free space, the service calls snd_dtq and tsnd_dtq put the task into a data transmission waiting state and that task is registered in the waiting task queue of the data queue until the buffer can be written to. at this time, tasks are registered in the waiting task queue in the order (fifo or priority order) specified by the attribute assigned when that data queue was created. in the case of tsnd_dtq, the task is also released when a specified time has elapsed. if (i)fsnd_dtq is issued, the oldest data in the ring buffer is discarded and transmission is forcibly carried out. the issuance of (i)psnd_dtq results in an error if the buffer is not empty, and the error code e_tmout is returned, indicating that polling failed. chapter 5 synchronous communication management user?s manual u14833ej2v0um 56 5.4.6 examples of communication using data queues some examples of intertask communication and synchronization using data queues are shown below. (1) cre_dtq is issued creating a data queue. there are 4 buffers. (2) task a sends a data reception request to data queue x. however, because there is no data stored in the buffers of data queue x, task a is put in the data reception waiting state. task a data request data reception failed task a running state waiting state data queue x registration data queue x rcv_dtq (reception wait) chapter 5 synchronous communication management user?s manual u14833ej2v0um 57 (3) task b transmits data to data queue x. task a therefore receives this data and is released from the waiting state. data reception successful task a waiting state registration data queue x task b running state data transmission task a ready state data queue x task b running state data snd_dtq (reception wait) chapter 5 synchronous communication management user?s manual u14833ej2v0um 58 (4) following this, task b transmits five items of data in succession. however, because the data queue can only store up to four data items in its buffers, task b fails to transmit the fifth data item and is put in the data transmission waiting state. transmission failed data queue x task b running state data1 transmission data queue x task b waiting state data4 data3 data2 data1 data4 data3 data2 data5 data5 registration snd_dtq (transmission wait) chapter 5 synchronous communication management user?s manual u14833ej2v0um 59 (5) here, task c sends a data reception request, receives the data ?data1? from the top buffer, and continues processing. task b, which is waiting to transmit data, then completes data transmission, and data5 is stored in the ring buffer. task c data reception/transmission successful data queue x task b ready state data1 data4 data3 data2 data5 data queue x task b waiting state data1 data4 data3 data2 data5 registration task c running state reception request running state rcv_dtq (transmission wait) chapter 5 synchronous communication management user?s manual u14833ej2v0um 60 5.5 mailboxes in the rx4000, data queues and mailboxes are provided as a means of realizing an intertask communication function. for a data queue, transmit data is fixed to 4 bytes and there is a limit to the total amount of data that can be stored. for a mailbox on the other hand, data of any format can be transmitted, and there is no limit to the total amount of storable data. users can therefore select and use whichever of these has the features that best suit their system configuration. this section describes mailboxes, which consist of a receive task waiting queue and a transmit message mail queue. mailboxes not only enable communication between tasks, but also make it possible to have tasks wait in response to messages. 5.5.1 creating mailboxes mailboxes can be created either by issuing the service call (a)cre_mbx, or by specifying the static api cre_mbx, which performs equivalent processing to (a)cre_mbx when the system is initialized. when (a)cre_mbx is issued, the attribute, etc., is stored in the block corresponding to the id number that specifies the mailbox control block array, and that control block is then initialized. the mailbox id number consists of a unique number of a value 1 or higher. the maximum value that can be specified is the one defined in the system information table, up to a maximum of 0x7fff numbers. 5.5.2 deleting mailboxes a mailbox is deleted by issuing the del_mbx service call. when del_mbx is issued, the kernel invalidates the specified mailbox control block and puts the target mailbox in the non-existent state. even if a task exists that has a receive message for the deleted mailbox, that mailbox will still be deleted. in this case, all the waiting tasks are released from the waiting state and the error code e_dlt indicating that the mailbox has been deleted is returned as the return value of the service call. similarly, even if there is a message that has been registered as waiting for reception, the mailbox will still be deleted. however, in this case, even if the message is a memory block acquired from the memory pool, it will not be returned to the memory pool. chapter 5 synchronous communication management user?s manual u14833ej2v0um 61 5.5.3 messages all items of data (memory) exchanged between tasks via mailboxes are called ?messages.? using a mailbox, an arbitrary task, handler, or processing routine can access the data, or messages, stored in the memory. in the rx4000, however, the address of a message is only passed to the receiving side; the contents of the message are not copied to any other area. (1) allocating message areas any memory area, such as a variable-length memory block, a fixed-length memory block, or a statically secured area, can be used for messages. however, to transmit messages, an area is required for the kernel to perform message management (message header), for which the top 4 bytes of the area is used (or the top 6 bytes in the case of messages with a specified priority). accordingly, an area larger than 4 (or 6) bytes must be secured for the message area. the top address of the message area is passed to the mailbox when a message is transmitted. this address must be a value that is an integral multiple of 4 (an integral multiple of 8 is recommended); otherwise operation cannot be guaranteed. for further details of the structure of the message header, refer to the rx4000 ( itron4.0) technical user?s manual (u14835e) . (2) contents of messages the length and composition of messages to be transmitted to mailboxes are not prescribed in the rx4000; rather they are determined by the tasks, handlers, and processing routines that communicate with each other (i.e., by protocols). (3) message priority order in the rx4000, if there are no tasks waiting for message reception when a message is transmitted, the transmitted message is registered in the message queue of the mailbox. the order in which messages are registered can be specified by the attribute of the mailbox, so for mailboxes with the attribute ta_mpri, messages are registered in order of priority. values from 1 to 255 can be used to assign priority: the smaller the value the higher the priority. the priority of a message is stored in the 2 bytes following the 4th byte from the top of the message area. therefore when messages are communicated via a mailbox with the attribute ta_mpri, the essence of the message activates after the 6th byte from the top of the message area. 5.5.4 transmitting messages messages are transmitted by issuing the service call snd_mbx. if there is a message transmission request, the kernel checks the message reception waiting task queue of the mailbox, and if there is a task waiting in this queue, it releases that task from the waiting state, at which point the task receives the message. if there are no tasks waiting, messages are registered in the message queue of the mailbox in the order specified by the attribute assigned when that mailbox was created (fifo or priority order), and are saved for the next message reception request. chapter 5 synchronous communication management user?s manual u14833ej2v0um 62 5.5.5 receiving messages messages are received by issuing one of the service calls rcv_mbx, trcv_mbx, or (i)prcv_mbx. if there is a message reception request, the kernel checks the message queue of the mailbox. if there are unreceived messages registered in the queue, the message at the top of the queue is released and passed to the task with that address. if there are no messages registered in the queue, when the service calls rcv_mbx and trcv_mbx are issued, the task is put into a mail reception waiting state: until mail is received in the case of the former, and until either mail is received or a specified time has elapsed in the case of the latter. the issuance of (i)prcv_mbx results in message reception failure, and the error code e_tmout is returned, indicating that polling failed. tasks waiting to receive messages are registered in the waiting task queue of the mailbox. because multiple tasks can be waiting in the waiting task queue of the same mailbox, a request for message reception sent to a mailbox in whose waiting task queue tasks are already waiting will not result in an error; the task will simply be put in the message reception waiting state. tasks can be registered in the waiting task queue of the mailbox in two ways. in the case of mailboxes with an attribute of ta_tpri, tasks are registered in the queue in order of their respective priorities, and in the case of mailboxes with an attribute of ta_tfifo, tasks are registered in the order in which message reception requests were sent. tasks are released from waiting in order activation from the top of the queue. 5.5.6 obtaining mailbox information mailbox information such as the presence or absence of a waiting task can be obtained by using the service calls ref_mbx and iref_mbx. for details of each service call, refer to chapter 13 . 5.5.7 examples of message communication using mailboxes some examples of communication using mailboxes are shown below. (1) cre_mbx is issued creating a mailbox. (2) task a issues rcv_mbx to receive a message and a message reception request is sent to mailbox x. however, because no messages have been sent to mailbox x, task a is put in the message reception waiting state. task a reception request message reception impossible task a running state waiting state mailbox x registration mailbox x rcv_mbx chapter 5 synchronous communication management user?s manual u14833ej2v0um 63 (3) task b prepares a message for transmission. a memory block or any memory area is used for the message. the first 4 bytes of the message area are reserved for kernel management and therefore cannot store message contents. the following 2 bytes store the message?s priority. however, if the destination of the message is a mailbox with the attribute ta_mfifo, these 2 bytes can be used as message area. users can store data in any format from the 6th byte of the message area. for further details, refer to the rx4000 ( itron4.0) technical user?s manual (u14835e) . (4) task b transmits a message to mailbox x, at which point task a receives the message and is released from the waiting state. task b transmission message reception (task a) task a running state waiting state mailbox x registration mailbox x task a ready state task b running state snd_mbx message message chapter 5 synchronous communication management user?s manual u14833ej2v0um 64 (5) following this, task b transmits another message to mailbox x. however, because there are no longer any tasks in mailbox x waiting to receive messages, the message is registered in the mailbox and waits to be received. task b transmission transmission running state mailbox x mailbox x task b running state registration snd_mbx message message (6) here, task a sends another reception request to mailbox x. because there is a receivable message registered in mailbox x, task a immediately receives that message and continues processing. task a reception (task a) running state mailbox x mailbox x task a running state registration rcv_mbx message reception request message chapter 5 synchronous communication management user?s manual u14833ej2v0um 65 5.6 mutexes mutexes are objects used to perform exclusive control between tasks when common resources are used, and support the priority inheritance and priority ceiling protocols as mechanisms for preventing the inversion of an unlimited priority order that accompanies exclusive control. 5.6.1 creating mutexes mutexes can be created either by issuing the service call (a)cre_mtx, or by specifying the static api cre_mtx, which performs equivalent processing to (a)cre_mtx when the system is initialized. when (a)cre_mtx is issued, the attribute, priority order limit, etc., is stored in the block corresponding to the id number that specifies the mutex control block array, and that control block is then initialized. the mutex id number consists of a unique number of a value 1 or higher. the maximum value that can be specified is the one defined in the system information table, up to a maximum of 0x7fff numbers. 5.6.2 deleting mutexes a mutex is deleted by issuing the service call del_mtx. when del_mtx is issued, the kernel invalidates the specified mutex control block and puts the target mutex in the non-existent state. even if a task exists that is waiting to lock the mutex to be deleted, that mutex will still be deleted. in this case, all the waiting tasks are released from the waiting state and the error code e_dlt indicating that the mutex has been deleted is returned as the return value of the service call (loc_mtx, tloc_mtx). also, even if the target mutex has been locked by a task, the mutex will still be deleted. however, the task locking the mutex will not be informed of its deletion. it is therefore necessary to inform this task of the mutex deletion by performing processing such as issuing the service call unl_mtx to check for the return of the error code e_noexs or e_iluse. note also that if the current priority of the task locking the mutex has been raised via the priority inheritance or priority ceiling protocol, the priority may be returned to the base priority by deletion of the locked mutex. 5.6.3 priority inheritance protocol the priority inheritance protocol is a mutex priority control protocol used to prevent the inversion of an unlimited priority order. when processing related to a mutex with the ta_inherit attribute occurs, this protocol changes the current priority value of the task locking the mutex to whichever is the highest of the following. ? the task?s base priority value ? the same priority value as the task with the highest priority among tasks waiting to lock a mutex with the attribute ta_inherit 5.6.4 priority ceiling protocol the priority ceiling protocol is a mutex priority control protocol used to prevent the inversion of an unlimited priority order. when a task locks a mutex with the attribute ta_ceiling, the priority of that task is changed to the top priority value of the mutexes. note that a task with a priority higher than this top priority cannot lock a mutex with the attribute ta_ceiling. chapter 5 synchronous communication management user?s manual u14833ej2v0um 66 5.6.5 simplified priority order control rules in the itron4.0 specification, two kinds of priority control rules related to mutexes are prescribed: detailed rules and simplified rules, of which the latter are used in the rx4000. the priority order of tasks that use mutexes to perform synchronization is therefore as follows. (when mutex is locked) whichever has the highest priority among the following. ? the task?s base priority value ? the same priority value as the task with the highest priority among tasks waiting to lock a locked mutex with the attribute ta_inherit ? the highest top priority among locked mutexes with the attribute ta_ceiling. (after mutex lock is released) when all the locked mutexes are released, a task?s current priority changes to its base priority. 5.6.6 locking mutexes a mutex is locked by issuing one of the service calls loc_mtx, tloc_mtx, or ploc_mtx. if there is a mutex lock request, the kernel checks whether that mutex is already locked by another task. if the mutex is not locked by another task, the mutex can be locked by the requesting task. at this time, if the target mutex has the attribute ta_ceiling, the current priority value of the task is raised to the top priority value of the mutexes. if the mutex is locked by another task, the requesting task is put in the waiting state and registered in the waiting task queue of the mutex. the order in which tasks are registered in this queue is fifo order if the target mutex has the attribute ta_tfifo, and priority order if the mutex has one of the other attributes ta_tpri, ta_inherit, or ta_ceiling. also, if the mutex has the attribute ta_inherit and the current priority of the waiting task is higher than that of the task locking the mutex, the latter task?s priority is changed. note that when tloc_mtx is issued, the is released from waiting if the mutex cannot be locked within a specified time. note also that a mutex cannot be locked by processing units other than tasks. 5.6.7 releasing mutex locks a mutex lock is released by issuing the service call unl_mtx. if a mutex lock is released when there are tasks waiting, the task at the top of the waiting task queue locks that mutex. at this time, if the mutex has the attribute ta_ceiling, the priority value of the task newly locking the mutex is changed to the top priority value of the mutexes. if the mutex has the attribute ta_inherit, because the task queue has already been sorted into priority order, the priority of the task newly locking the mutex remains unchanged. note that if all mutexes being locked by a task are released, the task?s priority changes to its base priority. 5.6.8 obtaining mutex information mutex information such as the id number of a locked task can be obtained by using the service calls ref_mtx and iref_mtx. for details of each service call, refer to chapter 13 . chapter 5 synchronous communication management user?s manual u14833ej2v0um 67 5.6.9 examples of synchronization using mutexes some examples of mutex priority control using a mutex with the attribute ta_inherit are shown below. (1) cre_mtx is issued creating a mutex. (2) in order to use a resource that needs to be exclusively controlled by a mutex, task c locks mutex x. time higher priority task c task a task b locks mutex x (3) task c activates task a, which has a higher priority. task a then activates task b, which has a priority lower than task a but higher than task c. time higher priority task c task a task b activates task a activates task b chapter 5 synchronous communication management user?s manual u14833ej2v0um 68 (4) in order to use a resource, task a attempts to lock mutex x. at this time, if the mutex does not support the priority inheritance protocol, task a will fail to lock the mutex, and enter the waiting state, at which point processing will shift to task b. because task c cannot be executed until the processing of task b is complete, task a must wait for task b, which has a lower priority than itself, to be executed (despite the fact task b is not locking a mutex). time higher priority task c task a task b locks mutex x enters the waiting state resumption of task a execution occurs at impossible to predict priority inversion period in actual fact, however, as soon as task a enters the waiting state after failing to lock the mutex, priority inheritance occurs and task c?s priority is raised to that of task a. consequently, because the processing of task c, which is locking the mutex, now has a higher priority than that of task b, the period in which a task with a lower priority than task a is being executed is minimized. time higher priority task c task a task b locks mutex x enters the waiting state mutex lock released inherits the priority of task a end of inheritance user?s manual u14833ej2v0um 69 chapter 6 memory management this chapter describes memory management in the rx4000. 6.1 overview the rx4000 does not support the virtual memory function provided in the target v r series processors. the kernel must therefore assume that all the programs included in the kernel are operating in 32-bit kernel mode. also, because tlb-related processing is not performed, the entire program and data area is expected to be located in the range of physical addresses 0x00000000 to 0x1fffffff. the kernel divides the memory into heap areas known as pools, which it controls, and other areas. the types of pools and types of objects located in pools are shown in the table below. note that the size and address of a pool is determined at configuration, and that area is initialized at system initialization. table 6-1. memory area area located objects system pool system base table ready queue object control block stack pool stack area for tasks stack area for interrupts user pool main body of fixed-length memory pool main body of variable-length memory pool ring buffer for data queue other than above program code area for global variables heap area controlled by user, etc. 6.2 system pool the system base table, ready queue, and object control blocks are located in the system pool. the size of this area is determined by the maximum size data of the objects assigned from the configurator based on the cf definition file. the system pool is created as an area in which dynamic addition and deletion does not occur at system initialization. a large part of the data directly related to kernel operations is stored in the system pool. consequently, if the system pool is illegally overwritten and made impossible to reference, the kernel will no longer be able to operate. chapter 6 memory management user?s manual u14833ej2v0um 70 6.3 stack pool the stack pool is used to secure the interrupt stack area used by interrupt service routines, etc., and the task stack area provided for each task. dynamic creation/deletion of the interrupt stack is assumed not to occur during system operation, and because the stack size is determined according to a description in the cf definition file, the interrupt stack area is statically secured as an undeletable area at kernel initialization. sections from the stack pool other than the area for the interrupt stack are initialized as a single large variable- length memory pool controlled by the kernel. when a task is created, a memory block secured from this memory pool is assigned to the task as a stack. when a task is deleted, the stack area is returned to this memory pool. note that this memory pool cannot be directly accessed from a task or handler processing program via a service call. 6.4 user pool the user pool is used to secure the main body of the fixed-length and variable-length memory pools and the ring buffer area used for the data queue. the user pool is initialized as a single large variable-length memory pool from which memory blocks are secured in memory pool or ring buffer sized portions when a fixed-length memory pool, variable-length memory pool, or data queue is created. the secured memory blocks are assigned to objects created as the main body of a fixed-length memory pool. note that this memory pool (user pool) cannot be directly accessed from a task or handler processing program via a service call. 6.5 fixed-length memory pools these are memory pools from which memory blocks can be repeatedly acquired and returned by a task or handler processing program via a service call. unlike a variable-length memory pool, the size of the memory blocks that can be acquired is fixed for each memory pool, enabling more simple and faster access by the processing. 6.5.1 creating fixed-length memory pools a fixed-length memory pool is created by issuing the service call (a)cre_mpf. when acre_mpf is issued, the id number of the memory pool can be assigned by the kernel. also, specifying the static api cre_mpf allows processing equivalent to cre_mpf to be carried out at kernel initialization. when (a)cre_mpf is issued, an area of the specified size is secured from the user pool and becomes the memory pool main body. if this area is successfully secured, data such as the attribute and the address of the memory pool main body area is stored in the fixed-length memory control block corresponding to the specified id number, and the area is initialized. 6.5.2 deleting fixed-length memory pools a fixed-length memory pool is deleted by issuing the service call del_mpf. when del_mpf is issued, the kernel returns the area of the memory pool main body to the user pool and then invalidates the control block. at this time, if there is a task waiting to acquire a memory block from the fixed-length memory pool to be deleted, all tasks are released from the waiting state. for tasks released from waiting, the error code e_dlt is returned indicating that the memory pool was deleted. note that even if there are parts of memory blocks in the target fixed-length memory pool that have not been returned, the fixed-length memory pool will still be deleted. care is required at this time because the task or handler that had acquired that memory block is not informed of the deletion of the memory pool. chapter 6 memory management user?s manual u14833ej2v0um 71 6.5.3 fixed-length memory blocks a fixed-length memory pool is made up of memory blocks all with the same size. the size of the memory blocks in a particular memory pool is specified by the user, and does not include a header area for managing the block. note that the memory block size must be an integral multiple of 8. if a value that is not an integral multiple of 8 is assigned as the memory block size parameter when a fixed-length memory pool is created, the kernel will automatically round the size to an integral multiple of 8. the structure of a fixed-length memory block is shown below. figure 6-1. fixed-length memory block memory block address passed as memory block address requested ac q uisition size 6.5.4 structure of fixed-length memory pool a fixed-length memory pool has a structure in which fixed-size memory blocks are joined together in a queue. if there is a request to acquire a memory block, memory blocks are distributed from the top of the queue, and when returned are placed at the bottom of the queue. therefore memory blocks are not necessarily queued in the order of their addresses, as shown in the figure below. figure 6-2. fixed-length memory pool fixed-length memory pool control block : : system pool user pool mpf top of queue size per specified memory block the specified number of memory blocks are queued together immediately after memory pool creation ( ? 1) memory block acquired next by get_mpf, (i)pget_mpf, tget_mpf bottom of queue the returned memory block is queued after this block chapter 6 memory management user?s manual u14833ej2v0um 72 6.5.5 acquiring fixed-length memory blocks a memory block is acquired from a fixed-length memory pool by issuing one of the service calls get_mpf, (i)pget_mpf, or tget_mpf. if there is a request to acquire a memory block, the kernel checks the memory block queue of the target memory pool. if the queue has memory blocks queued in it, the task is assigned the memory block at the top of the queue. if there are no queued memory blocks, the task is put in the memory block acquisition waiting state, and waits until a memory block has been acquired, in the case of get_mpf, or until either a memory block has been acquired or a specified time has elapsed, in the case of tget_mpf. the issuance of (i)pget_mpf results in an error, and the error code e_tmout is returned, indicating that polling failed. tasks in the memory block acquisition waiting state are registered in the waiting task queue of the memory pool. the waiting order at this time depends on the attribute of the memory pool: in fifo order if the attribute is ta_tfifo or in priority order if the attribute is ta_tpri, and if (i)rel_mpf is issued, memory blocks are acquired in the order they are queued, and the task is released from waiting. note that because 0 is stored in the top four bytes of the acquired memory block, when this memory block is transmitted to a mailbox as a message, because no value other than 0 is stored in this area (which is used by the kernel to manage the message), it is possible to check whether a memory block has been registered in the mailbox by checking the top four bytes. 6.5.6 returning fixed-length memory blocks a memory block is returned to a fixed-length memory pool by issuing the service call (i)rel_mpf. if there is a request to return a memory block, the kernel checks the waiting task queue of the target memory pool, and if there are tasks registered in the queue, it immediately assigns the task at the top of the queue the returned memory block and releases it from the waiting state. if there are no tasks registered in the waiting queue, the memory block is returned to the bottom of the memory pool?s free memory block queue. note that memory blocks must be returned to the same memory pool from which they were acquired. if a different memory pool is specified and (i)rel_mpf is issued, operation cannot be guaranteed. neither can operation be guaranteed if areas other than fixed-length memory blocks, such as variable-length memory blocks or statically secured areas, are registered together in a mailbox as messages and (i)rel_mpf is issued. 6.5.7 obtaining fixed-length memory pool information fixed-length memory pool information such as the presence or absence of a waiting task can be obtained by using the service calls ref_mpf and iref_mpf. for details of each service call, refer to chapter 13 . chapter 6 memory management user?s manual u14833ej2v0um 73 6.5.8 examples of acquiring memory blocks from fixed-length memory pools some examples of what occurs when memory blocks are acquired from fixed-length memory pools are shown below. (1) cre_mpf is issued creating a fixed-length memory pool. this pool contains 4 memory blocks. (2) task a issues get_mpf and requests acquisition of a memory block from mpf. because there are memory blocks queued in mpf?s memory block queue, task a immediately acquires one memory block. mpf task a acquisition request acquisition successful mpf task a running running get_mpf (3) task b issues get_mpf and requests acquisition of a memory block from mpf. however, because other tasks have in the meantime acquired memory blocks from mpf leaving no available memory blocks, task b fails to acquire a memory block and is put is the waiting state. mpf task b acquisition request acquisition failed task b mpf registered in waiting task queue running waiting get_mpf chapter 6 memory management user?s manual u14833ej2v0um 74 (4) task a returns a memory block to mpf. the returned memory block is immediately acquired by task b, which is then released from the waiting state. return/acquisition successful task b mpf task a memory block returned mpf task b task a wait released waiting running running ready rel_mpf (5) task b has finished using the memory block, issues rel_mpf and returns the memory block to mpf. because there are no tasks waiting for a memory block in mpf, the memory block joins the mpf?s memory block queue. return successful mpf task b memory block returned mpf task b running running chapter 6 memory management user?s manual u14833ej2v0um 75 6.6 variable-length memory pools like fixed-length memory pools, these are memory pools from which memory blocks can be repeatedly acquired and returned by a task or handler processing program via a service call. unlike a fixed-length memory pool, however, the size of the memory blocks that can be acquired can be specified when an acquisition request is sent. 6.6.1 creating variable-length memory pools a variable-length memory pool is created by issuing the service call (a)cre_mpl. when acre_mpl is issued, the id number of the memory pool can be assigned by the kernel. also, specifying the static api cre_mpl allows processing equivalent to cre_mpl to be carried out at kernel initialization. when (a)cre_mpl is issued, the kernel secures an area of the specified size from the user pool and makes it the memory pool main body. if this area is successfully secured, data such as the attribute and the address of the memory pool main body area is stored in the variable-length memory control block corresponding to the specified id number, and the control block is initialized. 6.6.2 deleting variable-length memory pools a variable-length memory pool is deleted by issuing the service call del_mpl. when del_mpl is issued, the kernel returns the area of the memory pool main body to the user pool and then invalidates the control block. at this time, if there is a task waiting to acquire a memory block from the variable-length memory pool to be deleted, all tasks are released from the waiting state. for tasks released from waiting, the error code e_dlt is returned indicating that the memory pool was deleted. note that even if there are parts of memory blocks in the target variable-length memory pool that have not been returned, the variable-length memory pool will still be deleted. care is required at this time because the task or handler that had acquired that memory block is not informed of the deletion of the memory pool. 6.6.3 variable-length memory blocks a variable-length memory pool is made up of memory blocks without fixed sizes. also, to maintain a state in which the largest possible blocks can be acquired, processing is performed to join together memory blocks to form connected areas upon return. a header for block management (16 bytes) is therefore included in the memory block, making the size of the area actually removed from memory pool when a memory block is acquired larger than the specified size. note that the specified memory block size must be an integral multiple of 8. if a value that is not an integral multiple of 8 is specified when a memory block is acquired, the kernel will automatically round the size to an integral multiple of 8. the structure of a variable-length memory block is shown below. figure 6-3. variable-length memory block memory block address passed as memory block address requested acquisition size header 16 bytes chapter 6 memory management user?s manual u14833ej2v0um 76 6.6.4 structure of variable-length memory pool immediately after creation, a variable-length memory pool consists of a single large memory block. if memory blocks are repeatedly acquired, this block becomes gradually smaller, and if acquisition and return repeatedly occur, the area of the memory pool may become divided into islands. for further details, refer to the rx4000 ( itron4.0) technical user?s manual (u14835e) . figure 6-4. variable-length memory pool structure (immediately after creation) size variable-length memory pool control block system pool user pool mpl ( ? 1) header memory pool size specified at creation figure 6-5. variable-length memory pool structure (after memory block acquisition) size variable-length memory pool control block mpl ( ? 1) acqui- sition acqui- sition chapter 6 memory management user?s manual u14833ej2v0um 77 figure 6-6. variable-length memory pool structure (when area divided into islands) variable-length memory pool control block mpl ( ? 1) return acqui- sition 6.6.5 acquiring variable-length memory blocks a memory block is acquired from a variable-length memory pool by issuing one of the service calls get_mpl, (i)pget_mpl, or tget_mpl. if there is a request to acquire a memory block, the kernel checks the memory block queue of the target memory pool. if the queue contains a memory space large enough for acquisition, a memory block of the requested size is removed from the memory pool and assigned to the task. note, however, that because a header for block management is added to the memory block, the size of the area actually removed from memory pool when a memory block is acquired is larger than the requested size (see figure 6-7 ). figure 6-7. memory block acquisition header header requested size acquisition 16 bytes chapter 6 memory management user?s manual u14833ej2v0um 78 if the queue does not contain a memory space large enough for acquisition, the task is put in the memory block acquisition waiting state, and waits until a memory block has been acquired, in the case of get_mpl or until either a memory block has been acquired or a specified time has elapsed, in the case of tget_mpl. the issuance of (i)pget_mpl results in an error, and the error code e_tmout is returned, indicating that polling failed. tasks in the memory block acquisition waiting state are registered in the waiting task queue of the memory pool. the waiting order at this time depends on the attribute of the memory pool: in fifo order if the attribute is ta_tfifo or in priority order if the attribute is ta_tpri, and if (i)rel_mpl is issued and there is sufficient memory space in the memory pool, memory blocks are acquired in the order they are queued, and the task is released from waiting. note that because 0 is stored in the top four bytes of the acquired memory block, when this memory block is transmitted to a mailbox as a message, because no value other than 0 is stored in this area (which is used by the kernel to manage the message), it is possible to check whether a memory block has been registered in the mailbox by checking the top four bytes. note also that when there are multiple tasks simultaneously waiting to acquire a memory block from the same memory pool, if one of those tasks has requested a large-sized memory block, because the memory block acquisition feasibility check is performed in the order in which the tasks are waiting in the queue, a later task may be blocked and forced to wait even if there is sufficient memory space for it to acquire the requested memory block (see figure 6-8 ). in other words, if the memory pool has the attribute ta_tfifo and there are tasks already waiting, a task coming later will be unable to acquire a memory block, regardless of the requested size, and will be forced to wait, or polling will fail. if there are tasks waiting in the queue of a memory pool with the attribute ta_tpri, memory block acquisition will only be possible if a memory block of the requested size is available and if the priority of the requesting task is higher than that of the task at the top of the queue. if ipget_mpl is issued for a memory pool with the attribute ta_tpri from an interrupt servicing routine, because the interrupt processing has a higher priority than the task processing, only the check to ascertain whether an acquirable block is available will be made. figure 6-8. case when task is waiting even though sufficient area is available header total memory pool size acquisition complete header task a task b waiting task queue size requested by task a size requested by task b enough space is available, but task b is blocked by task a and cannot acquire a memory block chapter 6 memory management user?s manual u14833ej2v0um 79 6.6.6 returning variable-length memory blocks memory blocks are returned to variable-length memory pools by issuing the service call (i)rel_mpl. if (i)rel_mpl is issued, the memory block is immediately returned to the memory pool, regardless of the existence of waiting tasks. when a memory block is returned, the kernel checks whether there are any free memory blocks in the area to which the returned memory block is connected, and if there are, performs processing to link two or three memory blocks together to form a single large block (see figures 6-9 , 6-10 , and 6-11 ). figure 6-9. memory block linking 1 returned free free in use free free in use linked figure 6-10. memory block linking 2 returned free free in use free free in use linked chapter 6 memory management user?s manual u14833ej2v0um 80 figure 6-11. memory block linking 3 returned free free linked free when the memory block return processing has finished, the memory pool?s waiting task queue is checked. if there are tasks waiting, a check is made whether a memory block of the size requested by the task at the top of the queue can be acquired. if it can, an appropriate memory block is assigned to the task and the task is removed from the waiting queue and released from the waiting state. this processing is then repeated until the bottom of the queue is reached or a task is unable to acquire a memory block. 6.6.7 obtaining variable-length memory pool information variable-length memory pool information such as the presence or absence of a waiting task can be obtained by using the service calls ref_mpl and iref_mpl. for details of each service call, refer to chapter 13 . chapter 6 memory management user?s manual u14833ej2v0um 81 6.6.8 examples of acquiring memory blocks from variable-length memory pools some examples of what occurs when memory blocks are acquired from variable-length memory pools are shown below. (1) task a issues get_mpl and acquires a memory block of size a from the memory pool. task a running state free area free area acquisition request memory pool x memory pool x task a running state control block control block control block free size free size a acquisition successful get_mpl (2) task b issues get_mpl and acquires a memory block of size b from the memory pool. control block control block task b running state free area free area acquisition request memory pool x memory pool x task b running state control block control block control block free size free size b a a acquisition successful get_mpl chapter 6 memory management user?s manual u14833ej2v0um 82 (3) task c issues get_mpl and requests acquisition of a memory block of size c from the memory pool. however, because the free area is smaller than size c, task c is unable to acquire the requested memory block and is put into the waiting state. control block task c running state free block acquisition request memory pool x memory pool x task c waiting state control block control block free size registration b a acquisition impossible control block free block control block control block free size b a (4) task a issues rel_mpl and returns a memory block (of size a) to the memory pool. the total free size of the memory pool increases accordingly, but because it is divided into two small memory blocks, the connected area requested by task c cannot be secured. task c is therefore put into the waiting state. control block task a running state free area free area returned memory pool x memory pool x task c waiting state control block control block a free size b control block free area control block control block free size b a task c waiting state task a running state rel_mpl chapter 6 memory management user?s manual u14833ej2v0um 83 (5) task b issues rel_mpl and returns a memory block (of size b) to the memory pool. accordingly, small free memory blocks are linked together to form a single large memory block. the connected area requested by task c can therefore be secured, so task c is assigned the requested memory block and released from the waiting state. task b running state free area free area returned memory pool x memory pool x task c ready state control block control block free size free size control block free area control block control block free size c b task c waiting state task b running state rel_mpl (6) task c issues rel_mpl and returns a memory block (of size c) to the memory pool. accordingly, all the memory blocks have been returned, and the memory pool returns to the state it was in at creation. task c running state free area returned memory pool x memory pool x control block control block free size rel_mpl free area control block free size c task c running state user?s manual u14833ej2v0um 84 chapter 7 time management this chapter describes time management in the rx4000. 7.1 overview in a real-time system, time-synchronization processing is often used when processing tasks and handlers. in the rx4000, a software timer is used to trigger timer interrupts issued at periodic intervals, and system clock, task delay and timeout, and cyclic handler functions are provided. 7.2 system clock the system clock indicates the time (system time) upon which systems that incorporate the rx4000 are based. the system clock consists of a 64-bit counter and is set to 0 as soon as the kernel has completed initialization. the system clock is reset to 0 when the passage of time causes the 64-bit range of its counter to be exceeded (overflow is ignored). the system clock operates in units of milliseconds. 7.2.1 setting the system clock the system clock can be set to any value during system operation by issuing the service call (i)set_tim. note, however, that the difference in time between the previous and new system clock values will not be treated has having elapsed, leaving task timeouts or cyclic handler activation unaffected by a new system clock setting. 7.2.2 reading the system clock the system clock can be read by issuing the service call (i)get_tim. the system clock reading is stored in the structure systim expressed by a 64-bit value. 7.2.3 updating the system clock the system clock can be updated by issuing the service call isig_tim. if isig_tim is issued, the kernel recognizes that the unit time defined in the cf definition file has elapsed. in other words, isig_tim must be issued each time the unit time defined in the cf files elapses, making it necessary to describe an interrupt service routine that will input the cp0 timer interrupts, etc., of the processor, from which isig_tim is issued. processing such as for task timeout or cyclic handler activation is not activated by the issuance of isig_tim; it is activated when the aforementioned interrupt service routine finishes processing. note that if the interval at which isig_tim is issued is undefined, the accuracy of the time until task timeout or the cyclic handler?s activation interval cannot be guaranteed. chapter 7 time management user?s manual u14833ej2v0um 85 7.3 delaying tasks the execution of a task can be delayed by issuing the service call dly_tsk. if dly_tsk is issued, the task is put in the waiting state and waits until the specified time has elapsed. it is therefore possible to delay the execution of a task for a specified time. the delay time is specified in units of milliseconds, not in number of interrupt ticks. 7.4 timeout when a service call is issued that might put a task into a waiting state, such as waiting for wakeup or to acquire a resource, it is possible to set the upper limit of this waiting time. the upper limit is known as the timeout time, and when a task is released from waiting following the elapse of the timeout time, the task is said to have ?timed out?. when a task has timed out, the error code e_tmout is returned as the return value of the service call that caused the task to wait, indicating that a timeout occurred. the timeout time is specified in units of milliseconds, not in number of interrupt ticks. note that the relationship between the timeout time and the time until the task actually times out differs from that specified in itron3.0. that is, because the kernel?s time management involves causing (discrete) interrupts to be input at a fixed interval, there is a slight difference between the timeout time and the time that actually elapses. unlike itron3.0 (rx4000 ver3.0), in which control was performed to prevent the time that actually elapses exceeding the specified timeout time, in itron4.0, because the timeout time is taken as the ?minimum time that should elapse?, timeout-specified tasks in the waiting state are timed out at the occurrence of the first time event (isig_tim) following the elapse of the specified time, so that the time that actually elapses is never less than the timeout time. the service calls that can make a timeout specification are shown in the table below. table 7-1. service calls that can specify timeout service call function tslp_tsk waiting for reception of wakeup request twai_sem acquiring a resource from a semaphore twai_flg waiting for establishment of an event flag condition tsnd_dtq transmitting data to a data queue trcv_dtq receiving data from a data queue trcv_mbx receiving mail from a mailbox tloc_mtx locking a mutex tget_mpf acquiring a memory block from a fixed-length memory pool tget_mpl acquiring a memory block from a variable-length memory pool chapter 7 time management user?s manual u14833ej2v0um 86 7.5 cyclic handlers cyclic handlers are handlers used to execute specific processing at a fixed time interval. note that this type of handler was known as a cyclically activated handler in itron3.0. the following names and terminology have accordingly been changed in the itron4.0. table 7-2. cyclic handler terminology correspondence table itron3.0 itron4.0 cyclically activated handler cyclic handler define a cyclically activated handler create a cyclic handler activity state state tcy_on (on) tcyc_sta (sta) tcy_off (off) tcyc_stp (stp) def_cyc cre_cyc note that a cyclic handler is described as a void type function with a vp_int type argument. the extended data exinf of an activated cyclic handler is passed for this argument. example) void cyclic(vp_int exinf) { ... return; } 7.5.1 creating cyclic handlers cyclic handlers are created by issuing the service call (a)cre_cyc. when acre_cyc is issued, the id number of the cyclic handler can be assigned by the kernel. also, specifying the static api cre_cyc allows processing equivalent to cre_cyc to be carried out at kernel initialization. when cre_cyc is issued, the cyclic handler control block in the system pool is secured, and initialized based on the cyclic handler creation data passed as a parameter. the cyclic handler id number consists of a unique number of a value 1 or higher. the maximum value that can be specified is the one defined in the system information table. 7.5.2 deleting cyclic handlers cyclic handlers are deleted by issuing the service call del_cyc. if del_cyc is issued, the control block of the target cyclic handler is invalidated, and a cyclic handler with the same id number as the deleted cyclic handler can be newly created. 7.5.3 cyclic handler states cyclic handlers have two states: operating (tcyc_sta) and stopped (tcyc_stp). in the former state, the cyclic handler is activated after the time that passes when the system clock is updated is counted and the specified activation interval time has elapsed. in the latter state, only the time is counted, and the handler is not activated, even after the specified activation interval time has elapsed. the initial state following creation of a cyclic handler depends on the specification of the attribute ta_sta (when specified, the handler is created in the operating state). the state of a cyclic handler can be changed after creation by issuing the service call (i)sta_cyc or (i)stp_cyc. chapter 7 time management user?s manual u14833ej2v0um 87 7.5.4 activating a cyclic handler a cyclic handler is activated as a subroutine called from the kernel when it performs interrupt end processing at the completion of an interrupt service routine for which isig_tim was issued. the stack when the cyclic handler is executed is therefore used as the interrupt stack. note that if the next cycle time elapses while a cyclic handler is being executed, the cyclic handler is reactivated once the current processing has finished. however, because this kind of state raises the cyclic handler?s cpu occupancy rate to an extremely high level, it is known as an abnormal state. 7.5.5 terminating cyclic handlers a cyclic handler is terminated by c language return or equivalent processing. as soon as a cyclic handler is terminated, the next cyclic handler for which the activation cycle time has elapsed is activated, or processing is returned from interrupt processing. 7.5.6 cyclic handler phase a cyclic handler can be made to have a phase as a means of regulating its activation timing. the cyclic handler phase is the time from cyclic handler creation to first activation, and is specified independently of the cyclic handler?s activation interval. figure 7-1. cyclic handler phase system time 0 p: cycphs c: cyctim p cre_cyc issuance cyclic handler activation c c chapter 7 time management user?s manual u14833ej2v0um 88 it is also possible to save this phase using the cyclic handler attribute ta_phs. saving a phase involves reckoning the time from when a cyclic handler is created to when the next cyclic handler is activated [phase + (activation cycle n)] when a cyclic handler is operating due to the issuance of the service call (i)sta_cyc. if phase saving is not performed, the elapse of one cycle time reckoned from the issuance of (i)sta_cyc becomes the next activation time. figure 7-2. phase saving system time 0 p: cycphs c: cyctim p cre_cyc issuance (no ta_sta specification) cyclic handler activation c c c sta_cyc issuance with phase saving figure 7-3. no phase saving system time 0 p: cycphs c: cyctim p cre_cyc issuance (no ta_sta specification) cyclic handler activation c c c sta_cyc issuance without phase saving c c 7.5.7 interrupts during cyclic handler execution the cyclic handler operates with interrupts managed by the kernel (interrupts for which it is possible to perform processing in which a kernel service is received, such as interrupt service routine activation) masked. therefore, to enable these interrupts during cyclic handler execution, the user must explicitly set interrupts to enabled (by setting the im bit of the status register). note that because the cyclic handler processing and timer interrupt processing are independent of each other, it is possible to acknowledge timer interrupts even during cyclic handler execution by enabling interrupts. chapter 7 time management user?s manual u14833ej2v0um 89 7.5.8 pid if the code created when the cyclic handler program was compiled or assembled uses pid (position independent data), the address that is to be the base of a cyclic handler when it is activated must be assigned as a parameter (gp of the cyclic handler creation packet t_ccyc). the assigned address is set in the gp register when the cyclic handler is activated. note that this base address is unconditionally set in the gp register regardless of its attribute, etc., and therefore must be set for programs that reference the gp register. if the gp register is not referenced, set null = 0. 7.5.9 use of coprocessor in cyclic handler to use the coprocessor in a cyclic handler, the save and restore processing for the registers related to the coprocessor (fpr0 to fpr31, fcr31) must be described in the cyclic handler?s activate and end sections, respectively. furthermore, to assign fcr31 (control/status register) uniquely to the cyclic handler, describe processing to set this register in the activate section of the cyclic handler. 7.5.10 issuance of service calls from cyclic handler the service calls that can be issued from the cyclic handler are the same as those calls that can be issued from interrupt processing. therefore, service calls in the form of ixxx_yyy starting with i and service calls in the form of sns_yyy can be issued. service calls in the form of xxx_yyy without i can also be issued from the cyclic handler. for example, even if act_tsk, from which the i of iact_tsk is omitted, is issued, an error does not occur, and the same processing as that of iact_tsk is performed. for details, refer to 13.8 . 7.5.11 obtaining cyclic handler information cyclic handler information such as the activation interval can be obtained by using the service calls ref_cyc and iref_cyc. for details of each service call, refer to chapter 13 . user?s manual u14833ej2v0um 90 chapter 8 interrupt management this chapter describes interrupt management in the rx4000. 8.1 overview processing in response to interrupt sources and cpu exceptions can be said to be one of the most important functions in a system using a real-time os. this is because, assuming the rx4000 is used embedded in a control device, the os can improve the performance of the system as a whole by responding quickly to peripheral devices such as sensors. one of the features of a general-purpose os such as windows or unix is that processing dependent on the device, such as interrupt processing, is concealed, enabling use of an interface common to multiple applications. it could be argued, however, that in order to maximize the performance of the cpu or peripheral device, processing dependent on the device such as interrupt and exception processing should not be concealed, which is why with the rx4000, users are supplied with a source file as a sample, which can be rewritten to accord with the user?s application system. this chapter should be read assuming that the source file is in an unmodified state. 8.2 interrupt management the interrupt management performed by the kernel can be divided depending on the contents into interrupt control and interrupt processing management. interrupt control refers to interrupt enable/disable processing, which includes not only an explicit enable/disable function via service calls, but also a function whereby the kernel enables or disables interrupts in order to preserve the integrity of the data while it is performing processing. interrupt processing management refers to the function of registering and executing processing routines in order to carry out processing in response to an acknowledged interrupt. 8.2.1 interrupt control the rx4000 disables interrupts in the target processor (v r 4100 series or v r 5000 series) by manipulating the ie or im bit of the status register. interrupts can also be enabled/disabled via control from an external interrupt controller. the service calls provided by the rx4000 to control interrupts are (i)loc_cpu, (i)unl_cpu, which enable/disable interrupts by manipulating the ie bit, (i)chg_ims, which uses the im bit, and dis_int, ena_int, which use an external interrupt controller. dis_int and ena_int also set the variable cpusts, which determines whether interrupts are enabled or disabled in the os. the kernel also uses the im bit of the status register to disable interrupts while it is performing processing. in this way interrupts can always be acknowledged in interrupt processing in which service calls provided by the kernel are not used. chapter 8 interrupt management user?s manual u14833ej2v0um 91 8.2.2 interrupt processing management when using the source file provided as a sample without modification, the interrupt processing flow is as shown below. this flow is also shown in diagram form in figure 8-1. (1) an interrupt is generated and control shifts to a cpu interrupt/exception vector. (2) at the interrupt/exception vector, in the sample, processing only branches to the interrupt/exception processing main body. (3) because control shifts to a single vector for all (general) exceptions/interrupts in the v r 4100 series or v r 5000 series, the exception source is determined by the initial section of the interrupt/exception processing, which then divides. cpu and service call exceptions are not taken into consideration here. (4) registers that may be corrupted by interrupt processing, such as temporary registers set up by the c compiler, are saved in the initial section of the interrupt processing. (v0 to v1, a0 to a3, t0 to t9, ra, epc, sr) (5) after these registers have been saved, the kernel?s internal function ?_kernel_int_handle? is called, which notifies the kernel of the activation of interrupt processing. note that in order to call the above function, the values of the epc, cause, and status registers must be assigned as parameters when an interrupt is generated. (6) once the kernel has received notification of the activation of interrupt processing, the interrupt service routine enters a state in which it can be activated (service calls can be issued). after the state has shifted, the kernel calls back the function ?_user_int_handle? described by the user (function name fixed). before calling the function ?_user_int_handle?, the kernel switches the stack to the interrupt stack so that all the subsequent processing is performed on the interrupt stack. it is therefore necessary to add the size of the stack consumed by interrupt processing to the stack of each task. (7) after the interrupt source has been determined by ?_user_int_handle?, ivsta_isr is issued, activating an interrupt service routine in response to the generated interrupt source. (8) the required interrupt processing is performed by the interrupt servicing routine. (9) ?_user_int_handle? is then terminated by c language return or equivalent processing. at this time, if an event in generated in the interrupt processing that requires scheduling, the kernel activates the scheduler and switches tasks. (10) if scheduling is not required in (9) above, or if the interrupted task is re-dispatched after scheduling, control returns to the point at which ?_kernel_int_handle? was called. (11) the registers saved in (4) are restored, via the eret instruction, to the point where the interrupt was generated. chapter 8 interrupt management user?s manual u14833ej2v0um 92 figure 8-1. interrupt processing flow task, etc. interrupt generation interrupt/exception vector interrupt/exception main processing exception source determination exception processing/service call entry cpu exception/syscall exception interrupt generation notification interrupt exception registers saved registers restored restoration from interrupt kernel _user_int_handle _kernel_int_handle ivsta_isr preprocessing isr postprocessing scheduler chapter 8 interrupt management user?s manual u14833ej2v0um 93 8.3 saving/restoring registers registers are saved in the initial section of the interrupt processing in accordance with the function call conventions of the v r series c compiler from either green hills software, inc. or metrowerks corp. when the interrupt processing involves the execution of processing described in c language, because the function call conventions stipulate that the preprocessing and postprocessing values stored in the save register (s0 to s7) must be the same, there is no particular need to save this register. the kernel will save and restore the gp, fp, and sp registers as required. for other registers (at, v0 to v1, t0 to t9, ra, epc, status), operation after being restored from an interrupt is not guaranteed unless their values are saved when the interrupt is generated and then returned to their original values when restored from interrupt processing. note that the size of stack consumed when these registers are saved is not included in the size of the stack automatically augmented by the kernel when a task is created. 8.4 interrupt generation notification in order to utilize the services provided by the kernel, such as issuing service calls via interrupt processing carried out when an interrupt is generated, the kernel must be notified of the activation of interrupt processing. however, there may also be cases when it is desirable to terminate interrupt processing without receiving services from the kernel in order to speed up the processing. cautions to be observed when using these two types of processing are outlined below. (1) terminating interrupt processing without using kernel?s services in this case, it is unnecessary to inform the kernel of the activation of interrupt processing. however, the user must describe the entire processing, from activate to finish. because the kernel cannot participate at all, service call issuance and multiple interrupt acknowledgement are completely disabled in the processing. note also that if the interrupt processing consumes the stack, unless stack switching is specified, operations will be carried out on the task stack, making it imperative that the entire task stack be augmented by the size of the stack consumed by this processing. it is therefore recommended to employ this type of processing only for very light processing, such as simple reading and writing data from/to i/o. (2) using kernel?s services in interrupt processing the kernel can be notified of the activation of interrupt processing by describing the kernel?s internal function ?_kernel_int_handle? in the initial section of the interrupt processing. once notified, the kernel performs processing such as switching the stack to the interrupt stack, and putting the service calls described later into an activation enabled state. interrupt processing performed by the user is enabled when the function ?_user_int_handle? is called back from the kernel. in this function, issuance of service calls activation with i and multiple interrupt acknowledgement are enabled, allowing execution of the main body of interrupt processing that uses the kernel?s services (without necessarily having to activate an interrupt service routine). chapter 8 interrupt management user?s manual u14833ej2v0um 94 8.5 interrupt service routines the routine that is activated when an interrupt is generated and performs processing in response to the interrupt source is known as an interrupt service routine (isr). an interrupt service routine is described as a void type function with one vp_int type argument. the extended data exinf of the activated interrupt service routine is passed for this argument. example) void int_serial(vp_int exinf) { ... return; } 8.5.1 interrupt service routine id number and interrupt number as with other objects, an interrupt service routine has a unique id number to identify its routine. however, with interrupt service routines, it is also necessary to specify an interrupt number in order to identify the interrupt source corresponding to a particular service routine. the same interrupt number can be specified for more than one interrupt service routine. 8.5.2 creating interrupt service routines interrupt service routines can be created either by issuing the service call (a)cre_isr, or by specifying the static api cre_isr, which performs equivalent processing to acre_isr when the system is initialized. if (a)cre_isr is issued, the kernel stores data such as the attribute and the interrupt number in the interrupt service routine control block corresponding to the specified id number and then initializes that block. a queue for managing routines with the same interrupt number (interrupt table) is also controlled from the system base table, where processing is performed to register control blocks in a queue corresponding to the number held by the routine. 8.5.3 deleting interrupt service routines an interrupt service routine is deleted by issuing the del_isr service call. when del_isr is issued, the kernel invalidates the specified interrupt servicing routine control block and deletes the control block from the interrupt table controlled by the system base table. after an interrupt service routine is deleted, an interrupt service routine with the same id number as the deleted routine can be newly created. 8.5.4 activating interrupt service routines an interrupt service routine is activated after an interrupt has been acknowledged and the source of the interrupt determined. the interrupt service routine is activated by specifying the interrupt source number for ivsta_isr (ivsta_isr does not cause a service call exception). if there is more than one routine for the same interrupt source number, ivsta_isr causes all the interrupt service routines to be activated. the order of activation at this time is the order in which the routines were created. chapter 8 interrupt management user?s manual u14833ej2v0um 95 8.5.5 terminating interrupt service routines an interrupt service routine is terminated by c language return or equivalent processing. a return value is not required. control therefore returns to either the next interrupt service routine to be activated or to the point at which ivsta_isr was issued. 8.5.6 pid if pid (position independent data) is used for the code created when the interrupt service routine program is compiled or assembled, the address that is to be the base of an interrupt service routine when it is created must be assigned as a parameter (gp of the interrupt service routine creation packet t_cisr). the assigned address is set in the gp register when the interrupt service routine is activated. note that this base address is unconditionally set in the gp register regardless of its attribute, etc., and therefore must be set for programs that reference the gp register. if the gp register is not referenced, set null = 0. 8.5.7 use of coprocessor in interrupt service routine to use the coprocessor in an interrupt service routine, the save and restore processing for the registers related to the coprocessor (fpr0 to fpr31, frc31) must be described in the interrupt service routine?s activate and end sections, respectively. furthermore, to assign fcr31 (control/status register) uniquely to the interrupt service routine, describe processing to set this register in the activate section of the interrupt service routine. 8.5.8 issuance of service calls from interrupt service routines service calls in the form of ixxx_yyy starting with i and service calls in the form of sns_yyy can be issued from an interrupt service routine. service calls in the form of xxx_yyy without i can also be issued from an interrupt service routine. for example, even if act_tsk, from which the i of iact_tsk is omitted, is issued, an error does not occur, and the same processing as that of iact_tsk is performed. for details, refer to 13.8 . user?s manual u14833ej2v0um 96 chapter 9 system configuration management this chapter describes system configuration management in the rx4000. 9.1 overview system configuration management includes the following functions. ? defining and activating a cpu exception handler to be called when the cpu detects an exception ? defining and activating an initialization routine to be called at system initialization ? defining and activating an idle routine for when there are no tasks in the running or ready states (refer to chapter 1 for details of idle routines) 9.2 exception processing if the cpu detects an exception such as 0 remainder, the kernel activates a corresponding exception handler. the exception processing and cpu exception handlers provided in the rx4000 are described below. note that as with interrupt processing, a source file is also provided as a sample, allowing users to describe exception processing that best suits their system. 9.2.1 exception processing flow the assumed exception processing flow of the rx4000 is shown below. this flow is also shown in diagram form in figure 9-1. (1) an exception occurs and control shifts to a cpu interrupt/exception vector. (2) at the interrupt/exception vector, in the sample, processing only branches to the exception processing main body. (3) because control shifts to a single vector for all exceptions/interrupts in the v r 4100 series or v r 5000 series, the exception source is determined by the initial section of the interrupt/exception processing, which then divides. (4) if the exception that occurred is a service call exception, control shifts to the initial processing section of the service call. also, if a device such as a monitor for debugging is being used, be aware that control may have to be passed to the debug side, depending on the type of exception. (5) all registers used are saved to the stack in the initial section of the exception processing. (6) after these registers have been saved, the kernel?s internal function ?_kernel_exc_handle? is called, which notifies the kernel of the activation of exception processing. note that in order to call the above function, the values of the epc, cause, and status registers and the top address of the register save area must be assigned as parameters when an exception occurs. chapter 9 system configuration management user?s manual u14833ej2v0um 97 (7) once the kernel has received notification of the activation of exception processing, the cpu exception handlers enter a state in which they can be activated (service calls can be issued). after the state has shifted, the kernel calls back the function ?_user_exc_handle? described by the user (function name fixed). (8) after the exception source has been determined by ?_user_exc_handle?, ivsta_exc is issued, activating a cpu exception handler corresponding to source of the exception that occurred. (9) the required exception processing is performed by the cpu exception handler. (10) ?_user_exc_handle? is then terminated by c language return or equivalent processing. at this time, if an event in generated in the exception processing that requires scheduling, the kernel activates the scheduler and switches tasks. (11) if scheduling is not required in (10) above, or if the task that caused the exception is re-dispatched after scheduling, control returns to the point at which ?_kernel_exc_handle? was called. (12) the registers saved in (5) are restored, via the eret instruction, to the point where the exception occurred. note that in cases when restoring the saved epc register to its indicated address inadvertently causes the reoccurrence of an exception, the value of epc must be changed to an appropriate value. chapter 9 system configuration management user?s manual u14833ej2v0um 98 figure 9-1. exception processing flow task, etc. exception occurrence interrupt/exception vector interrupt/exception main processing exception source determination interrupt servicing/service call entry exception occurrence notification registers saved registers restored restoration from exception kernel _user_exc_handle _kernel_exc_handle ivsta_exc preprocessing cpu exception handler postprocessing scheduler chapter 9 system configuration management user?s manual u14833ej2v0um 99 9.2.2 saving/restoring registers all registers including fpu registers are saved in the initial section of the exception processing. this is because by informing the exception main processing of the address of this save area, the state in which an exception occurs can be ascertained during exception processing. when it is not necessary to save all the registers, registers can be saved in accordance with the function call conventions of the v r series c compiler from green hills software, inc. when the exception processing involves the execution of processing described in c language, because the function call conventions stipulate that the preprocessing and postprocessing values stored in the save register (s0 to s7) must be the same, there is no particular need to save this register. the kernel will save and restore the gp, fp, sp, and fpu registers as required. in either case, for other registers (at, v0 to v1, t0 to t9, ra, epc, status), operation after being restored from an exception is not guaranteed unless their values are saved when the exception occurred and then returned to their original values when restored from exception processing. note that the size of stack consumed when these registers are saved is not included in the size of the stack automatically augmented by the kernel when a task is created. 9.2.3 exception occurrence notification in order to utilize the services provided by the kernel, such as issuing service calls via exception processing carried out when an exception occurs, the kernel must be notified of the activation of exception processing. however, there may also be cases when it is desirable to terminate exception processing without receiving services from the kernel in order to speed up the processing. cautions to be observed when using these two types of processing are outlined below. (1) terminating exception processing without using kernel?s services in this case, it is unnecessary to inform the kernel of the activation of exception processing. however, the user must describe the entire processing, from activate to finish. because the kernel cannot participate at all, service call issuance is completely disabled in the processing. (2) using kernel?s services in exception processing the kernel can be notified of the activation of exception processing by describing the kernel?s internal function ?_kernel_exc_handle? in the initial section of the exception processing. once notified, the kernel puts the cpu exception handlers into an activation-enabled state. exception processing performed by the user is enabled when the function ?_user_exc_handle? is called back from the kernel. in this function, issuance of service calls activation with i is enabled, allowing the kernel?s services to be received (without necessarily having to activate a cpu exception handler). 9.2.4 cpu exception handlers a cpu exception handler is a handler that is activated when an exception occurs. a cpu exception handler operates using the identical context (stack) to the location of the exception. the service calls that can be issued are the same as those that can be issued for an interrupt service routine. the description format of a cpu handler is shown below. note, however, that this format can be changed arbitrarily by the user by changing the source file. the address where the data of registers saved when an exception occurred is stored is passed as a parameter for the source file provided as a sample. example) void exchdr(vp fp) { ... return; } chapter 9 system configuration management user?s manual u14833ej2v0um 100 (1) exception handler number a number known as the exception handler number is used to identify the cpu exception handler. any number 0 or greater but less than the maximum number of exception handlers can be used. however, the relationship between the exception handler number and the exception source must be determined by the user (by the type of processing performed by the cpu exception handler). it is assumed that the value of the exccode field of the cause register in the source file provided as a sample will be used for the exception handler number. (2) defining/deleting cpu exception handlers cpu exception handlers can be defined either by issuing the service call def_exc, or by specifying the static api def_exc, which performs equivalent processing to def_exc when the system is initialized. if def_exc is issued, the kernel secures a control block in which it stores data such as the attribute and activation address of the cpu exception handler, and then initializes that block. a cpu exception handler definition is deleted by issuing the def_exc service call with the address of the cpu exception handler definition packet set as null. (3) activating/terminating cpu exception handlers a cpu exception handler is activated after an exception has occurred and the source of the exception determined. a cpu exception handler is activated by specifying the exception handler number for vsta_exc, and terminated by c language return or equivalent processing. (4) pid if pid (position independent data) is used for the code created when the cpu exception handler program is compiled or assembled, the address that is to be the base of a cpu exception handler when it is defined must be assigned as a parameter (gp of the cpu exception handler definition packet t_dexc). the assigned address is set in the gp register when the cpu exception handler is activated. note that this base address is unconditionally set in the gp register regardless of its attribute, etc., and therefore must be set for programs that reference the gp register. if the gp register is not referenced, set null = 0. (5) use of coprocessor in cpu exception handler to use the coprocessor in a cpu exception handler, the save and restore processing for the registers related to the coprocessor (fpr0 to fpr31, frc31) must be described in the cpu exception handler?s activate and end sections, respectively. furthermore, to assign fcr31 (control/status register) uniquely to the cpu exception handler, describe processing to set this register in the activate section of the cpu exception handler. (6) issuance of service calls from cpu exception handler the service calls that can be issued from a cpu exception handler are the same as those that can be issued from an interrupt service routine: all service calls activation with i in the ixxx_yyy format. chapter 9 system configuration management user?s manual u14833ej2v0um 101 9.3 initialization routines an initialization routine is a processing routine for initialization called between kernel activation and when the first task is executed (scheduler activated). an initialization routine is only activated at system initialization and unlike other objects does not have a control block. service calls can be issued from an initialization routine. these service calls include all those that can be issued from tasks, except ext_tsk and exd_tsk. note that depending on the service call, the result of the processing may be meaningless (i.e., in the case of the service call sns_ctx). the description format of an initialization routine is shown below. extended data is passed as the parameter. example) void inirtn(vp_int exinf) { ... return; } 9.3.1 defining initialization routines an initialization routine is defined using the static api att_ini in the cf definition file; it cannot be defined via a service call while the system is operating. 9.3.2 activating initialization routines an initialization routine is incorporated as a subroutine called by the kernel after the kernel is initialized. note that all processing corresponding to static api is carried out as an initialization routine created by the configurator. 9.3.3 terminating initialization routines an initialization routine is terminated by c language return or equivalent processing. control then shifts to either the next initialization routine to be activated, or to the scheduler. note that if the state of the system is changed due to the issuance of loc_cpu or dis_dsp, these service calls will be forcibly cancelled when the initialization routine is complete. user?s manual u14833ej2v0um 102 chapter 10 service call management 10.1 overview service call management is a function used to register functions described by users in the system as service calls. the registered service calls are known as extended service call routines. 10.2 extended service call routines user-described functions that are registered in the system as service calls are known as extended service call routines. extended service call routines each have a number, or extended function code, that identifies the routine, the specification of which together with the issuance of the service call (i)cal_svc calls the corresponding routine. an extended service call routine operates as the extension of the task or handler that issued (i)cal_svc. therefore, although standard service calls can be issued from a service call routine, the service calls that can be issued and the processing after issuance depend on the place (context) where (i)cal_svc was issued. also, if a task exception processing request is sent to a task that issued an extended service call routine from interrupt processing that occurred while the extended service call routine was being executed, because the extended service call routine is assumed to be task processing, the task exception processing routine will be activated before the extended service call routine resumes processing. the description format of an extended service call routine is shown below. note, however, that the parameter types and names are defined by the user. in the example below, arg1 corresponds to the (i)cal_svc parameter arg 1. example) er svcrtn(vw arg1, vw arg2, vw arg3) { ... return e_ok; } 10.2.1 defining extended service call routines extended service call routines are defined and deleted by issuing the service call def_svc. items such as the routine?s address and extended function code are specified as the parameters when defining the routine. 10.2.2 activating and terminating extended service call routines an extended service call routine is activated by specifying the extended function code and parameters passed to the service call for (i)cal_svc and then issuing this service call. an extended service call routine is terminated by c language return or equivalent processing. at this time, an error code corresponding to the processing contents of the service call is returned as the return value. when starting an extended service call routine using (i)cal_svc, only up to three parameters can be passed. to pass four or more parameters, the user must describe an interface library for the extended service call routine. for describing an interface library for the extended service call routine, refer to rx4000 ( itron4.0) installation system specification . chapter 10 service call management user?s manual u14833ej2v0um 103 10.2.3 pid if pid (position independent data) is used for the code created when the extended service call routine program is compiled or assembled, the address that is to be the base of an extended service call routine when it is defined must be assigned as a parameter (gp of the extended service call routine definition packet t_dsvc). the assigned address is set in the gp register when the extended service call routine is activated. note that this base address is unconditionally set in the gp register regardless of its attribute, etc., and therefore must be set for programs that reference the gp register. if the gp register is not referenced, set null = 0. 10.2.4 use of coprocessor in extended service call routine to use the coprocessor in an extended service call routine, the coprocessor must be in a state whereby it can be used by the task or interrupt service routine that called the extended service call routine. in other words, only tasks with the attribute ta_cop can call an extended service call routine in which the coprocessor is used. when issuing an extended service call routine from an interrupt service routine, the save and restore processing for the registers related to the coprocessor (fpr20 to fpr31) must be described in the extended service call routine to be issued. user?s manual u14833ej2v0um 104 chapter 11 initialization processing this chapter describes the initialization processing that is carried out by the kernel when the system is activated. for further details, refer to the rx4000 ( itron4.0) installation user?s manual (u14834e) . 11.1 overview initialization processing consists of initializing the hardware operated by the rx4000, initializing the kernel, and initializing the software. figure 11-1 shows the initialization processing flow. figure 11-1. initialization processing flow kernel boot processing block v r series reset entry scheduler initialization routine kernel initialization block tasks 11.2 boot processing block the boot processing block performs the initialization processing that must be complete before the kernel is activated. this processing involves initializing the peripheral hardware and copying data from rom to ram. chapter 11 initialization processing user?s manual u14833ej2v0um 105 11.3 kernel initialization block in the kernel initialization block, the system information table that is based on the cf definition file and is output by the configurator is referenced, and the kernel itself is initialized. the system can receive no service calls from the kernel until this processing is complete. processing in the kernel initialization block involves the following. ? interrupt initialization ? pool creation and initialization ? management object creation and initialization 11.3.1 interrupt initialization this processing includes initializing interrupts and setting the values of interrupt masks for operation when the kernel has disabled interrupts. because interrupt processing is dependent upon the execution environment of the user, a user own coding block (such as _kernel_ini_custom) is used. for details, refer to rx4000 ( itron4.0) installation system specification . 11.3.2 pool creation and initialization this processing involves creating and initializing the system, user, and stack pools based on the memory data specified in the cf definition file. 11.3.3 management object creation and initialization (1) creation of system base table this processing involves creating and initializing the system base table based on the system data specified in the cf definition file. (2) creation of ready queue this processing involves creating and initializing the ready queue based on the system data specified in the cf definition file. (3) creation of objects objects are created by static api described in the cf definition file based on object creation data. also, if specified, activation processing (for tasks) and operation state shift processing (for cyclic handlers) is also carried out. 11.4 initialization routines initialization routines are processing routines used to perform initialization called between when kernel initialization is complete and when the first task is executed. initialization routines are registered by describing att_ini in the cf definition file. additional modules may also be added implicitly as initialization routines using the configurator in case of future kernel function expansion. initialization routines are used to perform initialization after the kernel is activated, such as setting the initial status of tasks. refer to chapter 1 for further details. user?s manual u14833ej2v0um 106 chapter 12 interface library this chapter describes the interface library function. for further details, refer to the rx4000 ( itron4.0) installation user?s manual (u14834e) . 12.1 overview when an application program is written in c, and a service call is issued, the service call is described in an external function format. the format in which the service call is actually issued, however, differs from the external function format. an interface library is therefore required to translate a service call issued in external function format into the kernel issuance format and thus act as an agent between application programs and the kernel. the interface library provided in the rx4000 supports the c compiler package for the v r series from green hills software, inc. there are two types of interface libraries: one is for service calls and the other is for extended service calls that must be described by the user. for the interface library for extended service calls, refer to 10.2 . 12.2 function and position of interface library the interface library is an interface program used to translate service calls issued from the application program in an external function format into the issuance format of the kernel, and is thus positioned between the application program and the kernel. the interface library contains a function to shift control to the kernel once it has made the parameter and other settings required by the kernel to perform processing. the position of the interface library is shown below. figure 12-1. position of interface library kernel external function format kernel issuance format service call issuance interface processing service call processing interface library task user?s manual u14833ej2v0um 107 chapter 13 service calls this chapter describes the service calls provided in the rx4000. 13.1 overview service calls are provided to enable manipulation of a variety of objects from the user?s processing program (task, interrupt handler, etc.), and operate by calling the service routines of the kernel. by issuing service calls, users can indirectly manipulate objects managed by the kernel via synchronous communication or interrupt servicing. 13.2 types of functions the service call (vatt_idl) provided in the rx4000 include those that comply with the itron4.0 specification (165 types), and those that are unique to the rx4000 (3 types). these service calls are further divided into 10 groups, according to their function, as shown below. (1) task management function service calls (20 types) these service calls are used for functions such as direct manipulation of task states and referencing. cre_tsk acre_tsk del_tsk act_tsk iact_tsk can_act ican_act sta_tsk ista_tsk ext_tsk exd_tsk ter_tsk chg_pri ichg_pri get_pri iget_pri ref_tsk iref_tsk ref_tst iref_tst (2) task-associated synchronization function service calls (15 types) these service calls are used for synchronization functions associated with tasks that are not dependent on other resources such as semaphores. slp_tsk tslp_tsk wup_tsk iwup_tsk can_wup ican_wup rel_wai irel_wai sus_tsk isus_tsk rsm_tsk irsm_tsk frsm_tsk ifrsm_tsk dly_tsk (3) task exception processing function service calls (8 types) these service calls are used for functions related to task exception processing. def_tex ras_tex iras_tex dis_tex ena_tex sns_tex ref_tex iref_tex chapter 13 service calls user?s manual u14833ej2v0um 108 (4) synchronous communication management function service calls (59 types) these service calls are used for synchronous communication functions that are independent of tasks, i.e., functions related to semaphores, event flags, data queues, mailboxes, and mutex. cre_sem acre_sem del_sem sig_sem isig_sem wai_sem pol_sem ipol_sem twai_sem ref_sem iref_sem cre_flg acre_flg del_flg set_flg iset_flg clr_flg iclr_flg wai_flg pol_flg ipol_flg twai_flg ref_flg iref_flg cre_dtq acre_dtq del_dtq snd_dtq psnd_dtq ipsnd_dtq tsnd_dtq fsnd_dtq ifsnd_dtq rcv_dtq prcv_dtq iprcv_dtq trcv_dtq ref_dtq iref_dtq cre_mbx acre_mbx del_mbx snd_mbx isnd_mbx rcv_mbx prcv_mbx iprcv_mbx trcv_mbx ref_mbx iref_mbx cre_mtx acre_mtx del_mtx loc_mtx ploc_mtx tloc_mtx unl_mtx ref_mtx iref_mtx (5) memory pool management function service calls (22 types) these service calls are used for functions related to fixed- and variable-length memory pools. cre_mpf acre_mpf del_mpf get_mpf pget_mpf ipget_mpf tget_mpf rel_mpf irel_mpf ref_mpf iref_mpf cre_mpl acre_mpl del_mpl get_mpl pget_mpl ipget_mpl tget_mpl rel_mpl irel_mpl ref_mpl iref_mpl (6) time management function service calls (14 types) these service calls are used to perform processing related to time. set_tim iset_tim get_tim iget_tim isig_tim cre_cyc acre_cyc del_cyc sta_cyc ista_cyc stp_cyc istp_cyc ref_cyc iref_cyc (7) system status management function service calls (14 types) these service calls are used for functions related to the status of the entire system, such as disabling dispatch. rot_rdq irot_rdq get_tid iget_tid loc_cpu iloc_cpu unl_cpu iunl_cpu dis_dsp ena_dsp sns_ctx sns_loc sns_dsp sns_dpn (8) interrupt management function service calls (10 types) these service calls are used for functions related to interrupt servicing. cre_isr acre_isr del_isr dis_int ena_int chg_ims ichg_ims get_ims iget_ims (9) system configuration management function service calls (3 types) these include service calls related to cpu exception handlers and initialization routines. def_exc vatt_idl (10) service call management function service calls (3 types) these service calls are used for functions related to extended service call routines. def_svc cal_svc ical_svc chapter 13 service calls user?s manual u14833ej2v0um 109 13.3 return values (error codes) the service calls provided in the rx4000 return error codes or return values that are prescribed in the itron4.0 specification. the names of symbols used for error codes can be used by including the header file kernel.h. the return values that can be returned by service calls are listed below. table 13-1. error code list symbol value meaning e_ok 0 normal termination e_nospt ? 9 reserved function code e_rsfn ? 10 unsupported function e_rsatr ? 11 illegal attribute e_par ? 17 illegal parameter e_id ? 18 specified id number exceeds range e_ctx ? 25 context error e_iluse ? 28 illegal use of service call e_nomem ? 33 insufficient memory e_noid ? 34 id number cannot be assigned e_obj ? 41 target object in illegal state e_noexs ? 42 target object does not exist e_qovr ? 43 queuing overflow e_rlwai ? 49 waiting forcibly released by (i)rel_wai e_tmout ? 50 timeout, polling failure e_dlt ? 51 target resource deleted while being waited for chapter 13 service calls user?s manual u14833ej2v0um 110 13.4 data types the parameters or error codes of the service calls provided in the rx4000 are defined and declared based on data types that conform to the itron4.0 specification. the data types used in the rx4000 are shown below. note that these data types can be used by including the header file kernel.h. 13.4.1 general data types the data types listed below are general data types prescribed by itron4.0. typedef char b; ? signed 8-bit integer typedef short h; ? signed 16-bit integer typedef long w; ? signed 32-bit integer typedef unsigned char ub; ? unsigned 8-bit integer typedef unsigned short uh; ? unsigned 16-bit integer typedef unsigned long uw; ? unsigned 32-bit integer typedef char vb; ? variable data type value (8 bits) typedef short vh; ? variable data type value (16 bits) typedef long vw; ? variable data type value (32 bits) typedef void *vp; ? variable data type value (pointer) typedef void (*fp) (); ? program activate address typedef int int; ? signed integer (processor width) typedef unsigned int uint; ? unsigned integer (processor width) typedef int vp_int ? variable data type value (pointer) or signed integer (processor width) chapter 13 service calls user?s manual u14833ej2v0um 111 13.4.2 rx4000 data types based on the general data types, dedicated types for data that has a special meaning, such as an id number, are declared for the parameters of the service calls provided in the rx4000. typedef h fn; ? function code typedef h id; ? object id number typedef w bool; ? bool value typedef uh intno; ? interrupt number typedef h excno; ? exception handler number typedef uh atr; ? object attribute typedef uh stat; ? object state typedef w er; ? error code typedef w er_id; ? error code or object id number typedef w er_bool; ? error code or boolean value typedef int er_unit; ? error code or unsigned integer (signed integer with the same bit width as er or unit, whichever is greater. the valid number of bits of an unsigned integer is 1 bit shorter than unit.) typedef h pri; ? priority order typedef uint texptn; ? task exception source typedef uint flgptn; ? event flag bit pattern typedef uh mode; ? service call operating mode typedef uw size; ? memory size typedef w tmo; ? timeout time typedef uw reltim; ? relative time typedef struct t_systim { uw ltime; uw utime; } systim; ? system time typedef struct t_c xxx { reference of each service call page } t_c xxx ? object creation packet typedef struct t_d xxx { reference of each service call page } t_d xxx ? object definition packet typedef struct t_r xxx { reference of each service call page } t_r xxx ? object data packet chapter 13 service calls user?s manual u14833ej2v0um 112 13.5 macros when describing application programs such as tasks or interrupt handlers, the following macros can be treated as defined constants, and therefore cannot be redefined by the user. these definitions are made in the header file kernel.h. for items whose value column is blank, refer to the page on which that service call is defined. cf in the value column indicates that the value is determined by the configurator. table 13-2. macro list (1/2) macro name value meaning ta _ xxx object attribute twf_ xxx service call operating mode tts_ xxx object state tsk_self 0 self task specification tsk_none 0 no corresponding task exists tpri_self 0 self task base priority specification tpri_ini 0 specification of task priority at activation mercd(er ercd) ? return main error code section of the error code ercd (currently always ?1) sercd(er ercd) ? return sub error code section of the error code ercd (value indicated in error code list) ercd(er mercd, er sercd) ? generates and returns an error code from main error code mercd and sub- error code sercd. tmin_tpri 1 minimum value of task priority order (highest priority) tmax_tpri cf maximum value of task priority order (lowest priority) tmin_mpri 1 minimum value of message priority order (highest priority) tmax_mpri 0x7fff maximum value of message priority order (lowest priority) tkernel_maker 0x000d kernel manufacturer code (nec electronics) tkernel_prid 0x0000 kernel identification number tkernel_spver 0x0400 version number of itron specification tkernel_prver 0x0400 version number of kernel tmax_actcnt 127 maximum queue limit for activation requests tmax_wupcnt 127 maximum queue limit for wakeup requests tmax_suscnt 127 maximum queue limit for suspend requests tbit_texptn 32 number of bits in task exception source tbit_flgptn 32 number of bits in event flag ttic_nume cf numerator of time tick cycle ttic_deno 1 denominator of time tick cycle tsz_dtq(uint dtqcnt) cre_dtq page reference tsz_mprihd cre_mbx page reference tsz_mpf cre_mpf page reference tsz_mpl cre_mpl page reference tmax_maxsem 0x7fffffff maximum value of maximum number of semaphores chapter 13 service calls user?s manual u14833ej2v0um 113 table 13-2. macro list (2/2) macro name value meaning e_ xxx error code null 0 invalid pointer true 1 true false 0 false 13.6 parameter value range some of the service call parameters supported by the rx4000 have a range of permissible values, while others allow the use of only specific values reserved by the system. the ranges of parameter values are shown below. table 13-3. parameter value ranges parameter type range task id no. 1 to notes 1,2 semaphore id no. 1 to note 2 event flag id no. 1 to note 2 data queue id no. 1 to note 2 mailbox id no. 1 to note 2 mutex id no. 1 to note 2 fixed-length memory pool id no. 1 to note 2 variable-length memory pool id no. 1 to note 2 cyclic handler id no. 1 to note 2 interrupt id no. 0 to note 2 exception handler id no. 0 to note 2 extended function code 1 to note 2 task priority 1 to note 3 message priority 1 to 0x7fff timeout time 1 to 0x7fffffff note 4 cycle time 1 to 0xffffffff delay time 1 to 0xffffffff system time 0 to 0xfffffffffffff user stack size 0 to 0x7fffffff memory block size 1 to 0x7fffffff gp value 0 to 0xffffffff note 5 notes 1. 0 is reserved by the system 2. value specified in the cf definition file (maximum value: 0x7fff) 3. value specified in the cf definition file (maximum value: 255) 4. 0 and ? 1 are reserved by the system 5. the operation is not guaranteed if a value other than a multiple of 4 is specified. chapter 13 service calls user?s manual u14833ej2v0um 114 13.7 context from which service calls can be issued a context that can be regarded as a part of task processing is called a task context, and a context that cannot is called a non-task context. the context in which a cpu exception handler and extended service call routine are issued is dependent upon the original context that calls these routines. the following table shows to which context each routine belongs. table 13-4. context that can issue service calls routine name context ta s k ta s k task exception processing routine task interrupt service routine non-task cyclic handler non-task initialization routine non-task cpu exception handler task/non-task extended service call routine task/non-task idle routine non-task service calls that start with ?i? are issued from a non-task context, and the other service calls are issued from a task context. however, service calls for a non-task context in the form of ixxx_yyy can be issued from a task context and service calls without ?i? in the form of xxx_yyy can be issued from a non-task context. this is to improve the ease of using service calls. note, however, that not all service calls in the form of xxx_yyy can be issued from a non- task context. service calls in the form of sns_yyy can be issued from any context. although an idle routine is regarded as a non-task context, all service calls can be issued from an idle routine. the contexts from which service calls can be issued are listed below. table 13-5. context from which service calls can be issued service call form task context non-task context xxx_yyy ? (some service calls can be issued.) vxxx_yyy ? ixxx_yyy ? ivxxx_yyy ? sns_yyy ? chapter 13 service calls user?s manual u14833ej2v0um 115 13.8 explanation of service calls this section explains the service calls provided in the rx4000 in accordance with the following format. figure 13-1. service call description format () 1 9 8 7 6 5 4 3 2 [overview] [parameter(s)] description parameter i/o [explanation] [return value(s)] [c format] [differences from itron3.0] chapter 13 service calls user?s manual u14833ej2v0um 116 (1) name indicates the name of the service call. (2) semantics indicates the source of the name of the service call. (3) overview outlines the functions of the service call. (4) c format indicates the format to be used when describing a service call to be issued in c. (5) parameter(s) service call parameters are explained in the following format. i/o parameter description ab c a. parameter classification i ... input parameter o ... output parameter b. parameter type and name c. description of parameter (6) explanation explains the function of a service call. (7) differences from itron3.0 explains points that differ from the itron3.0 specification or the rx4000 ver3.x (which complies with the itron3.0 specification). (8) return value explains the service call?s return value. chapter 13 service calls user?s manual u14833ej2v0um 117 13.8.1 task management function service calls this section describes the task management function service calls listed in the following table. table 13-6. task management function service calls name function cre_tsk creates a task acre_tsk creates a task (automatic assignment of id no.) del_tsk deletes a task act_tsk/iact_tsk activates a task can_act/ican_act invalidates an activation request sta_tsk/ista_tsk activates a task (activation request not retained) ext_tsk terminates this task exd_tsk terminates and deletes this task ter_tsk forcibly terminates another task chg_pri/ichg_pri changes the priority level of a task get_pri/iget_pri obtains the priority level of a task ref_tsk/iref_tsk references the state of a task ref_tst/iref_tst references the state of a task (simple version) chapter 13 service calls user?s manual u14833ej2v0um 118 create task cre_tsk [overview] creates a task. [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 119 the task creation packet t_ctsk is described in detail below. ? tskatr specifies data such as whether the coprocessor is used or not and whether interrupts are enabled or disabled at activation as task attributes. values that can be specified as task attributes are shown below. figure 13-2. task attributes tskatr 15 8 7 0 ta_asm (1): described in assembly language ta_hlng (0): described in c language ta_cop (1): use coprocessor ta_disint (1): activate task in interrupt disabled state ta_enaint (0): activate task in interrupt enabled state ta_act (1): activate immediately after the task creation bit 0 is used to specify the task?s description language. ta_hlng is specified if the task is described in c language and ta_asm if assembly language is used. in this version, however, there are no differences in the processing for these two attributes. bit 1 is used to specify whether a task is to be activated after creation. if the attribute ta_sta is assigned to a task, act_tsk or equivalent processing is performed for that task after it is created. bit 12 is used to specify whether interrupts are enabled or disabled immediately after a created task is activated. if ta_disint is set, the task is activated in the interrupt disabled state. if ta_enaint is set, the task is activated in the interrupt enabled state. note that disabling interrupts means that interrupts that can initiate interrupt processing in which kernel services are received are masked. bit 14 is used to specify whether the created task will use the coprocessor (fpu). if ta_cop is set, the preprocessing and postprocessing required when the coprocessor is used is performed. note that when a combination of these attributes is set, the logical sum of the above values is set for tskatr. ? exinf stores user-specific information regarding the creation of tasks. this information can be referenced as parameters for tasks activated by (i)act_tsk. ? task sets the activation address of the task to be created. ? itskpri sets the initial priority (task initial priority) of the task to be created. when a task that has been terminated is reactivated, the priority of that task is determined by the value set in itskpri and not by the value at termination. the range of the values that can be specified for itskpri is from 0x1 to the maximum priority (specified by the cf definition file). chapter 13 service calls user?s manual u14833ej2v0um 120 ? stksz specifies the size of the stack area used by the task. when task creation processing is performed, the kernel secures a stack area from the stack pool based on this size specification. failure to secure this area results in an error, and the error code e_nomem is returned. note that because the kernel augments this area with items such as context size, the size of the area actually secured from the stack pool is larger than the specified value. for further details, refer to the rx4000 ( itron4.0) instruction user?s manual (u14834e) . ? stk this field specifies the top address of the stack area used by the task to be created. however, because this function is not supported in the rx4000, stk should always be set to null. settings other than null are ignored. ? gp sets the base address (gp) of the pid (position independent data) used by the task to be created. if pid is not used by the task, set gp to null. ? tp reserved area. tp should always be set to null. settings other than null are ignored. [differences from itron3.0] 1. the values of the macros ta_asm and ta_hlng used when specifying the task attribute have been reversed (ta_asm 0 1, ta_hlng 1 0). caution is therefore required when porting task programs in which values are directly specified without using a macro from itron3.0 to itron4.0. 2. ta_act has been added to the task attributes. 3. it is no longer necessary to use an attribute to specify the use of pid by a task. 4. stk has been added to the task creation packet (t_ctsk) members. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_tsk is not included in the system e_rsatr ? 11 the task attribute is illegal ? ta_cop was specified in the fpu disabled mode ? an attribute that does not exist in the specifications was specified e_par ? 17 the parameter is illegal ? the initial priority is outside the range (itskpri 0, maximum priority value < itskpri) e_id ? 18 the task id number is outside the range (tskid 0, maximum task count < tskid) e_ctx ? 25 cre_tsk was issued from a non-task context cre_tsk was issued in the cpu lock state e_nomem ? 33 a stack of the requested size cannot be secured e_obj ? 41 a task with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 121 create task with automatic id assignment acre_tsk [overview] creates a task (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 122 delete task del_tsk [overview] deletes a task. [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 123 activate task act_tsk/iact_tsk [overview] activates a task (activation request retained) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 124 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 act_tsk/iact_tsk is not included in the system e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 act_tsk/iact_tsk was issued in the cpu lock state e_noexs ? 42 the target task does not exist e_qovr ? 43 the number of times the activation request was retained exceeded 127 chapter 13 service calls user?s manual u14833ej2v0um 125 cancel activation can_act/ican_act [overview] invalidates task activation requests [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 126 start task sta_tsk/ista_tsk [overview] activates a task (activation request not retained) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 127 exit task ext_tsk [overview] terminates a task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 128 exit and delete task exd_tsk [overview] terminates and deletes a task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 129 terminate task ter_tsk [overview] forcibly terminates another task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 130 change task priority chg_pri/ichg_pri [overview] changes the priority of a task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 131 if the target task is queuing in a waiting task queue in priority order, issuing chg_pri may change the order of that queue (or the order in which the tasks are released from waiting). especially, if chg_pri is issued and changes the task at the top of a queue for tasks waiting to acquire a memory block from a variable-length memory pool, the task may acquire a memory block and be released from waiting. also, if the target task is waiting to lock a mutex with the attribute ta_inherit, priority inheritance processing may occur as a result of the change in the order of the ready queue. ichg_pri is intended to be issued from a non-task context but it can also be issued from a task context. chg_pri can be issued from a non-task context. [differences from itron3.0] processing related to mutex has been added. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 chg_pri/ichg_pri is not included in the system e_par ? 17 the priority is outside the range (tskpri < 0, maximum priority < tskpri) e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 chg_pri/ichg_pri was issued in the cpu lock state e_iluse ? 28 the priority after the change is higher than the maximum priority of the mutex e_obj ? 41 the target task is in the dormant state e_noexs ? 42 the target task does not exist chapter 13 service calls user?s manual u14833ej2v0um 132 get task priority get_pri/iget_pri [overview] obtains the priority of a task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 133 refer task status ref_tsk /i ref_tsk [overview] obtains task information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 134 [explanation] information related to the task specified by tskid is stored in the packet specified by pk_rtsk. if tsk_self = 0 is set for tskid, the task itself is the target of the service call. the task information packet t_rtsk is described in detail below. ? tskstat the value indicating the current state of the task is stored. the corresponding values are as follows. table 13-7. task status symbol value meaning tts_run 0x0001 running state tts_rdy 0x0002 ready state tts_wai 0x0004 waiting state tts_sus 0x0008 suspended state tts_was 0x000c waiting-suspended state tts_dmt 0x0010 dormant state ? tskpri the current priority of the target task is stored. ? tskbpri the base priority of the target task is stored. ? tskwait when the target task is in the waiting state, the value indicating the wait source is stored. the corresponding values are as follows. table 13-8. wait source symbol value meaning ttw_none 0x0000 not in waiting state ttw_slp 0x0001 waiting due to slp_tsk/tslp_tsk ttw_dly 0x0002 waiting due to dly_tsk ttw_sem 0x0004 waiting due to wai_sem/twai_sem ttw_flg 0x0008 waiting due to wai_flg/twai_flg ttw_sdtq 0x0010 waiting due to snd_dtq/tsnd_dtq ttw_rdtq 0x0020 waiting due to rcv_dtq/trcv_dtq ttw_mbx 0x0040 waiting due to rcv_mbx/trcv_mbx ttw_mtx 0x0080 waiting due to loc_mtx/tloc_mtx ttw_mpf 0x2000 waiting due to get_mpf/tget_mpf ttw_mpl 0x4000 waiting due to get_mpl/tget_mpl chapter 13 service calls user?s manual u14833ej2v0um 135 ? wobjid when the target task is in the waiting state, the id number of the target object is stored. ? lefttmo when the target task has a timeout function and is in the waiting state, the time left before the timeout is stored. ? actcnt the number of activation requests retained by the target task is stored. ? wupcnt the number of wakeup requests retained by the target task is stored. ? suscnt the number of suspend requests retained by the target task is stored. ? tskatr the target task attributes are stored. the values stored have the meanings described in cre_tsk. ? itskpri the initial priority of the target task is stored. iref_tsk is intended to be issued from a non-task context but it can also be issued from a task context. ref_tsk can be issued from a non-task context. [differences from itron3.0] 1. the order of the parameters has changed. ref_tsk (t_rtsk *pk_rtsk, id tskid); ref_tsk (id tskid, t_rtsk *pk_rtsk); 2. the members of the task information packet t_rtsk have changed. (deleted) extended data exinf (added) base priority tskbpri, time left before timeout lefttmo, number of activation requests actcnt, task attributes tskatr, initial priority of task itskpri 3. the values for a task?s wait sources have changed due to the addition of functions such as data queues. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_tsk/iref_tsk is not included in the system e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 ref_tsk/iref_tsk was issued in the cpu lock state e_noexs ? 42 the target task does not exist chapter 13 service calls user?s manual u14833ej2v0um 136 refer task status ref_tst/iref_tst [overview] obtains task information (simplified version) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 137 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_tst/iref_tst is not included in the system e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 ref_tst/iref_tst was issued in the cpu lock state e_noexs ? 42 the target task does not exist chapter 13 service calls user?s manual u14833ej2v0um 138 13.8.2 task-associated synchronization function service calls this section describes the task-associated synchronization function service calls listed in the following table. table 13-9. task-associated synchronization function service calls name function slp_tsk places a task in the wakeup waiting state tslp_tsk places a task in wakeup waiting state (with timeout) wup_tsk/iwup_tsk wakes up a task can_wup/ican_wup invalidates a wakeup request rel_wai/irel_wai forcibly releases a task from waiting sus_tsk/isus_tsk forcibly places a task in the waiting state rsm_tsk/irsm_tsk releases the forcible waiting state of a task frsm_tsk/ifrsm_tsk releases the forcible waiting states of all tasks dly_tsk places the task in the time lapse waiting state chapter 13 service calls user?s manual u14833ej2v0um 139 sleep task slp_tsk [overview] places a task in the wakeup waiting state [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 140 sleep task with timeout tslp_tsk [overview] places a task in the wakeup waiting state (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 141 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 tslp_tsk is not included in the system e_par ? 17 the timeout time is illegal (tmout < tmo_fevr) e_ctx ? 25 tslp_tsk was issued from a non-task context tslp_tsk was issued in the cpu lock state tslp_tsk was issued in the dispatch disabled state e_rlwai ? 49 the waiting state was forcibly released by (i)rel_wai e_tmout ? 50 timeout chapter 13 service calls user?s manual u14833ej2v0um 142 wakeup task wup_tsk/iwup_tsk [overview] wakes up a task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 143 cancel wakeup task can_wup/ican_wup [overview] invalidates wakeup requests [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 144 release wait rel_wai/ i rel_wai [overview] forcibly releases the waiting state of another task [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 145 suspend task sus_tsk/isus_tsk [overview] forcibly places a task in a waiting state [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 146 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 sus_tsk/isus_tsk is not included in the system e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 sus_tsk/isus_tsk was issued in the cpu lock state self-issuance was specified in the dispatch disabled state e_obj ? 41 the target task is in the dormant state e_noexs ? 42 the target task does not exist e_qovr ? 43 the number of nested suspend requests exceeds 127 chapter 13 service calls user?s manual u14833ej2v0um 147 resume task rsm_tsk/irsm_tsk [overview] resumes operation of a task in the suspended state [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 148 force resume task frsm_tsk/ifrsm_tsk [overview] forcibly resumes operation of a task in the suspended state [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 149 delay task dly_tsk [overview] places a task in the time lapse waiting state [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 150 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 dly_tsk is not included in the system e_ctx ? 25 dly_tsk/idly_tsk was issued from a non-task context dly_tsk/idly_tsk was issued in the cpu lock state dly_tsk/idly_tsk was issued in the dispatch disabled state e_rlwai ? 49 the waiting state was forcibly released by (i)rel_wai chapter 13 service calls user?s manual u14833ej2v0um 151 13.8.3 task exception processing function service calls this section describes the task exception processing function service calls listed in the following table. table 13-10. task exception processing function service calls name function def_tex defines a task exception processing routine ras_tex/iras_tex requests a task exception processing routine dis_tex disables task exception processing ena_tex enables task exception processing sns_tex references the task exception processing disabled status ref_tex/iref_tex obtains the task exception processing routine status chapter 13 service calls user?s manual u14833ej2v0um 152 define task exception routine def_tex [overview] defines a task exception processing routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 153 the task exception processing routine definition information is explained in detail below. ? texatr this is the attribute of a task exception processing routine that specifies a language in which the task exception processing routine is described. if the routine is described in c, specify ta_hlng. if it is described in an assembly language, specify ta_asm. regardless of which of these two is described, there are no differences in the processing of the kernel of the current version. figure 13-3. task exception processing routine attribute texatr 15 8 7 0 ta_asm (1): described in assembly language ta_hlng (0): described in c language ? texrtn this is the activate address of the task exception processing routine to be defined. if the task exception processing routine uses pid (position independent data), it is assumed that its base address gp is the same as that of the task. the exception processing routine takes over the value of the gp register of the task. the same execution context (stack) of the task exception processing routine as the task is used. [differences from itron3.0] def_tex is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 def_tex is not included in the system e_rsatr ? 11 the task exception processing routine attribute is illegal e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) e_ctx ? 25 def_tex was issued from a non-task context def_tex was issued in the cpu lock state e_noexs ? 42 the target task does not exist chapter 13 service calls user?s manual u14833ej2v0um 154 raise task exception routine ras_tex/iras_tex [overview] issues a task exception processing request [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 155 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ras_tex/iras_tex is not included in the system e_par ? 17 the activation source is 0 (rasptn = 0) e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 ras_tex/iras_tex was issued in the cpu lock state e_obj ? 41 the target task is in the dormant state no exception processing routine is defined for the target task e_noexs ? 42 the target task does not exist chapter 13 service calls user?s manual u14833ej2v0um 156 disable task exception dis_tex [overview] disables activation of a task exception processing routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 157 enable task exception ena_tex [overview] enables activation of a task exception processing routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 158 sense task exception routine status sns_tex [overview] references the status of a task exception processing routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 159 refer task exception routine status ref_tex/iref_tex [overview] obtains task exception processing routine information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 160 [differences from itron3.0] ref_tex/iref_tex is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_tex/iref_tex is not included in the system e_id ? 18 the task id number is outside the range (tskid < 0, maximum task count < tskid) tsk_self is specified and issued from a non-task context. e_ctx ? 25 ref_tex/iref_tex was issued in the cpu lock state e_obj ? 41 the target task is in the dormant state no exception processing routine is defined for the target task e_noexs ? 42 the target task does not exist chapter 13 service calls user?s manual u14833ej2v0um 161 13.8.4 synchronization/communication management function service calls this section describes the synchronization/communication management function service calls listed in the following table. table 13-11. synchronization/communication management function service calls (1/2) name function cre_sem creates a semaphore acre_sem creates a semaphore (automatic assignment of id no.) del_sem deletes a semaphore sig_sem/isig_sem returns resources wai_sem acquires resources pol_sem/ipol_sem acquires resources (polling) twai_sem acquires resources from a semaphore (with timeout) ref_sem/iref_sem obtains semaphore information cre_flg creates an event flag acre_flg creates an event flag (automatic assignment of id no.) del_flg deletes an event flag set_flg/iset_flg sets an event flag clr_flg/iclr_flg clears an event flag wai_flg waits for satisfaction of condition pol_flg/ipol_flg waits for satisfaction of condition (polling) twai_flg waits for satisfaction of condition (with timeout) ref_flg/iref_flg obtains event flag information cre_dtq creates a data queue acre_dtq creates a data queue (automatic assignment of id no.) del_dtq deletes a data queue snd_dtq sends data psnd_dtq/ipsnd_dtq sends data (polling) tsnd_dtq sends data (with timeout) fsnd_dtq/ifsnd_dtq forcibly sends data rcv_dtq receives data prcv_dtq/iprcv_dtq receives data (polling) trcv_dtq receives data (with timeout) ref_dtq/iref_dtq obtains data queue information cre_mbx creates a mailbox acre_mbx creates a mailbox (automatic assignment of id no.) del_mbx deletes a mailbox snd_mbx/isnd_mbx sends mail rcv_mbx receives mail chapter 13 service calls user?s manual u14833ej2v0um 162 table 13-11. synchronization/communication management function service calls (2/2) name function prcv_mbx/iprcv_mbx receives mail (polling) trcv_mbx receives mail (with timeout) ref_mbx/iref_mbx obtains mailbox information cre_mtx creates a mutex acre_mtx creates a mutex (automatic assignment of id no.) del_mtx deletes a mutex loc_mtx locks a mutex ploc_mtx locks a mutex (polling) tloc_mtx locks a mutex (with timeout) unl_mtx unlocks a mutex ref_mtx/iref_mtx obtains mutex information chapter 13 service calls user?s manual u14833ej2v0um 163 create semaphore cre_sem [overview] creates a semaphore [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 164 figure 13-4. semaphore attribute sematr 15 8 7 0 ta_tfifo (0): task is waiting on fifo basis ta_tpri (1): task is waiting in priority order to bit 0 of sematr, specify the order in which a task waits for the resources from the semaphore to be created. if ta_tfifo is specified, the task waits on an fifo basis. if ta_tpri is specified, the task waits in the order of priority. ? isemcnt specifies the default value of the resource counter of the semaphore as an integer of 0 or more. the maximum value that can be specified is tmax_maxsem (0x7fffffff). however, the value of maxsem explained below must not be exceeded. if a value greater than maxsem is specified, an error occurs and the error code e_par is returned. ? maxsem specifies the maximum value of the resource counter of the semaphore as an integer of 1 or more. the maximum value that can be specified is tmax_maxsem (0x7fffffff). if the resource counter issues (i)sig_sem that exceeds this value, an error occurs. [differences from itron3.0] 1. the extended data exinf has been deleted from the members of the semaphore creation packet t_csem. 2. the type of the default value of the resource counter, isemcnt, and the maximum value of the resource counter, maxsem, has been changed from int to uint. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_sem is not included in the system e_rsatr ? 11 the semaphore attribute is illegal e_par ? 17 the parameter is illegal ? the default value of the semaphore is outside the range (maxsem < isemcnt) ? the maximum value of the semaphore is outside the range (maxsem = 0) e_id ? 18 the semaphore id number is outside the range (semid maximum semaphore count < semid) e_ctx ? 25 cre_sem was issued from a non-task context cre_sem was issued in the cpu lock state e_obj ? 41 a semaphore with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 165 create semaphore with automatic id assignment acre_sem [overview] creates a semaphore (automatic assignment of id number). [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 166 delete semaphore del_sem [overview] deletes a semaphore [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 167 signal semaphore sig_sem/isig_sem [overview] returns a resource to a semaphore [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 168 wait on semaphore wai_sem [overview] acquires a resource from a semaphore [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 169 poll semaphore pol_sem/ipol_sem [overview] acquires a resource from a semaphore (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 170 wait on semaphore with timeout twai_sem [overview] acquires a resource from a semaphore (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 171 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 twai_sem is not included in the system e_par ? 17 the timeout time is outside the range (tmout < tmo_fevr = ? 1) e_id ? 18 the semaphore id number is outside the range (semid 0, maximum semaphore count < semid) e_ctx ? 25 twai_sem was issued from a non-task context twai_sem was issued in the cpu lock state twai_sem was issued in the dispatch disabled state e_noexs ? 42 the target semaphore does not exist e_rlwai ? 49 the task has been released from the waiting state by (i)rel_wai e_tmout ? 50 the specified time has elapsed e_dlt ? 51 the semaphore is deleted while a task is waiting for it chapter 13 service calls user?s manual u14833ej2v0um 172 refer semaphore status ref_sem/iref_sem [overview] obtains semaphore information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 173 [differences from itron3.0] 1. the order of the parameters has been changed. 2. the extended data exinf has been deleted from the members of the semaphore information packet t_rsem. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_sem/iref_sem is not included in the system e_id ? 18 the semaphore id number is outside the range (semid 0, maximum semaphore count < semid) e_ctx ? 25 ref_sem/iref_sem was issued from a non-task context ref_sem/iref_sem was issued in the cpu lock state e_noexs ? 42 the target semaphore does not exist chapter 13 service calls user?s manual u14833ej2v0um 174 create eventflag cre_flg [overview] creates an event flag [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 175 figure 13-5. event flag attribute flgatr 15 8 7 0 ta_wmul (1): permits two or more tasks to wait ta_wsgl (0): does not permit two or more tasks to wait ta_tfifo (0): task is waiting on fifo basis ta_tpri (1): task is waiting in priority order ta_clr (1): clears the event flag when the condition is satisfied to bit 0 of flgatr, specify the order in which a task waits. if ta_tfifo is specified, the task waits on an fifo basis. if ta_tpri is specified, the task waits in the order of priority. these attributes, however, are meaningless if the attribute of the event flag is ta_wsgl, which is explained below. bit 1 specifies whether two or more tasks are permitted to wait for the event flag. if ta_wmul is specified, two or more tasks can wait for the event flag. if ta_wsgl is specified, two or more tasks cannot wait. bit 2 specifies whether the bit pattern is created when the condition of the event flag is satisfied. if attribute ta_clr is given, the event flag is cleared to 0 when the condition of the event flag has been satisfied and the task has been released from the waiting state. ? iflgptn stores the default value of the event flag to be created. [differences from itron3.0] 1. the extended data exinf has been deleted from the members of the event flag creation packet t_cflg. 2. the type of the default value of the event flag iflgptn has been changed from int to flgptn. flgptn is a type newly defined for itron4.0. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_flg is not included in the system e_rsatr ? 11 the event flag attribute is illegal e_id ? 18 the event flag id number is outside the range (flgid 0, maximum event flag count < flgid) e_ctx ? 25 cre_flg was issued from a non-task context cre_flg was issued in the cpu lock state e_obj ? 41 an event flag with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 176 create eventflag with automatic id assignment acre_flg [overview] creates an event flag (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 177 delete eventflag del_flg [overview] deletes an event flag [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 178 set eventflag set_flg/iset_flg [overview] sets an event flag [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 179 clear eventflag clr_flg/iclr_flg [overview] clears an event flag [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 180 wait eventflag wai_flg [overview] waits until the condition of an event flag is satisfied [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 181 for an event flag with the ta_wmul attribute, the order in which waiting tasks are registered to the queue is determined by the attribute of the event flag. if the attribute is ta_tfifo, the tasks wait on an fifo basis. if the attribute is ta_tpri, the tasks wait according to their priorities. when set_flg is issued, however, two or more tasks may be released from the waiting state all at once because it is checked whether the condition under which the task is released from the waiting state is satisfied or not. therefore, the first task in the queue is not always released from the waiting state first. if two or more tasks are released from the waiting state and if the event flag has the attribute ta_clr, the event flag is cleared as soon as the first task has been released from the waiting state. consequently, the bit pattern (0) is compared with the waiting bit pattern, and the processing to release the task from the waiting state is completed as soon as the bit pattern has been compared. tasks placed in the waiting state due to wai_flg are released from waiting by one of the following occurrences. 1. (i)set_flg is issued and the event flag satisfies the condition (e_ok). 2. (i)rel_wai is issued and the task is forcibly released from the waiting state (e_rlwai). 3. del_flg is issued and the event flag is deleted (e_dlt). [differences from itron3.0] 1. the order of the parameters has been changed. 2. the type of the bit pattern of the event flag has been changed from uint to flgptn. 3. the type of the waiting mode wfmode has been changed from uint to mode. flgptn and mode are types newly defined for itron4.0. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 wai_flg is not included in the system e_par ? 17 the parameter is illegal ? the waiting bit pattern is 0 (waiptn = 0) ? the waiting mode specification is illegal e_id ? 18 the event flag id number is outside the range (flgid 0, maximum event flag count < flgid) e_ctx ? 25 wai_flg was issued from a non-task context wai_flg was issued in the cpu lock state wai_flg was issued in the dispatch disabled state e_obj ? 41 a waiting task already exists (when the attribute is ta_wsgl) e_noexs ? 42 the target event flag does not exist e_rlwai ? 49 the task has been forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the event flag is deleted while the task is waiting chapter 13 service calls user?s manual u14833ej2v0um 182 poll eventflag pol_flg/ipol_flg [overview] waits until the condition of an event flag is satisfied (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 183 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 pol_flg/ipol_flg is not included in the system e_par ? 17 the parameter is illegal ? the waiting bit pattern is 0 (waiptn = 0) ? the waiting mode specification is illegal e_id ? 18 the event flag id number is outside the range (flgid 0, maximum event flag count < flgid) e_ctx ? 25 pol_flg/ipol_flg was issued in the cpu lock state e_obj ? 41 a waiting task already exists (when the attribute is ta_wsgl) e_noexs ? 42 the target event flag does not exist e_tmout ? 50 polling has failed chapter 13 service calls user?s manual u14833ej2v0um 184 wait eventflag with timeout twai_flg [overview] waits until the condition of an event flag is satisfied (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 185 [differences from itron3.0] 1. the order of the parameters has been changed. 2. the type of the bit pattern of the event flag has been changed from uint to flgptn. 3. the type of the waiting mode wfmode has been changed from uint to mode. flgptn and mode are types newly defined for itron4.0. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 twai_flg is not included in the system e_par ? 17 the parameter is illegal ? the waiting bit pattern is 0 (waiptn = 0) ? the waiting mode specification is illegal ? the timeout time is illegal (tmout < tmo_fevr) e_id ? 18 the event flag id number is outside the range (flgid 0, maximum event flag count < flgid) e_ctx ? 25 twai_flg was issued from a non-task context twai_flg was issued in the cpu lock state twai_flg was issued in the dispatch disabled state e_obj ? 41 a waiting task already exists (when the attribute is ta_wsgl) e_noexs ? 42 the target event flag does not exist e_rlwai ? 49 the task has been forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the event flag is deleted while the task is waiting chapter 13 service calls user?s manual u14833ej2v0um 186 refer eventflag status ref_flg/iref_flg [overview] obtains event flag information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 187 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_flg/iref_flg is not included in the system e_id ? 18 the event flag id number is outside the range (flgid 0, maximum event flag count < flgid) e_ctx ? 25 ref_flg/iref_flg was issued from a non-task context ref_flg/iref_flg was issued in the cpu lock state e_noexs ? 42 the target event flag does not exist chapter 13 service calls user?s manual u14833ej2v0um 188 create data queue cre_dtq [overview] creates a data queue [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 189 figure 13-6. data queue attribute dtqatr 15 8 7 0 ta_tfifo (0): the task waits on an fifo basis ta_tpri (1): the task waits according to the priority bit 0 specifies how the task waits in the data queue for data transmission. if ta_tfifo is specified, the task waits on an fifo basis. if ta_tpri is specified, it waits according to the priority. the waiting mode of the task when it waits for data reception is fixed to the fifo basis, regardless of the data queue attribute. ? dtqcnt specifies the size of the ring buffer used by the data queue to be created by the number of buffers. the size of one buffer is sizeof (vp_int), and the size of the area actually reserved from the user pool, including the size of the header for management, is calculated by the macro tsz_dtq (dtqcnt). by setting dtqcnt to 0, a data queue that executes communication without buffers and by using only task waiting can be created. ? dtq this is a reserved area and must be always set to null. even if this is set to other than null, it is ignored. [differences from itron3.0] cre_dtq is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_dtq is not included in the system e_rsatr ? 11 the data queue attribute is illegal e_id ? 18 the data queue id number is outside the range (dtqid 0, maximum data queue count < dtqid) e_ctx ? 25 cre_dtq was issued from a non-task context cre_dtq was issued in the cpu lock state e_nomem ? 33 the area of the ring buffer cannot be reserved e_obj ? 41 a data queue with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 190 create data queue with automatic id assignment acre_dtq [overview] creates a data queue (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 191 delete data queue del_dtq [overview] deletes a data queue [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 192 send data to data queue snd_dtq [overview] transmits data to a data queue [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 193 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 snd_dtq is not included in the system e_id ? 18 the data queue id number is outside the range (dtqid 0, maximum data queue count < dtqid) e_ctx ? 25 snd_dtq was issued from a non-task context snd_dtq was issued in the cpu lock state snd_dtq was issued in the dispatch disabled state e_noexs ? 42 the target data queue does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the data queue is deleted while the task is waiting chapter 13 service calls user?s manual u14833ej2v0um 194 poll and send data to data queue psnd_dtq/ipsnd_dtq [overview] transmits data to a data queue (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 195 send data to data queue with timeout tsnd_dtq [overview] transmits data to a data queue (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 196 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 tsnd_dtq is not included in the system e_par ? 17 the parameter is illegal ? the timeout time is illegal (tmout < tmo_fevr = ? 1) e_id ? 18 the data queue id number is outside the range (dtqid 0, maximum data queue count < dtqid) e_ctx ? 25 tsnd_dtq wad issued from a non-task context tsnd_dtq wad issued in the cpu lock state tsnd_dtq wad issued in the dispatch disabled state e_noexs ? 42 the target data queue does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the data queue is deleted while the task is waiting chapter 13 service calls user?s manual u14833ej2v0um 197 force send data to data queue fsnd_dtq/ifsnd_dtq [overview] transmits data to a data queue (overwriting data) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 198 receive data from data queue rcv_dtq [overview] receives data from a data queue [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 199 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 rcv_dtq is not included in the system e_id ? 18 the data queue id number is outside the range (dtqid 0, maximum data queue count < dtqid) e_ctx ? 25 rcv_dtq was issued from a non-task context rcv_dtq was issued in the cpu lock state rcv_dtq was issued in the dispatch disabled state e_noexs ? 42 the target data queue does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the target data queue does not exist chapter 13 service calls user?s manual u14833ej2v0um 200 poll and receive data from data queue prcv_dtq/iprcv_dtq [overview] receives data from a data queue (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 201 receive data from data queue with timeout trcv_dtq [overview] receives data from a data queue (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 202 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 trcv_dtq is not included in the system e_par ? 17 the parameter is illegal ? the timeout time is illegal (tmout < tmo_fevr = ? 1) e_id ? 18 the data queue id number is outside the range (dtqid 0, maximum data queue count < dtqid) e_ctx ? 25 trcv_dtq was issued from a non-task context trcv_dtq was issued in the cpu lock state trcv_dtq was issued in the dispatch disabled state e_noexs ? 42 the target data queue does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the data queue is deleted while the task is waiting chapter 13 service calls user?s manual u14833ej2v0um 203 refer data queue status ref_dtq/iref_dtq [overview] obtains data queue information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 204 ? dtqcnt indicates the size of the ring buffer used by the target data queue as the number of ring buffers. ? dtq this is a reserved area and always stores null. iref_dtg is intended to be issued from a non-task context but it can also be issued from a task context. ref_dtg can be issued from a non-task context. [differences from itron3.0] ref_dtq/iref_dtq is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_dtq/iref_dtq is not included in the system e_id ? 18 the data queue id number is outside the range (dtqid 0, maximum data queue count < dtqid) e_ctx ? 25 ref_dtq/iref_dtq was issued in the cpu lock state e_noexs ? 42 the target data queue does not exist chapter 13 service calls user?s manual u14833ej2v0um 205 create mailbox cre_mbx [overview] creates a mailbox [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 206 figure 13-7. mailbox attribute mbxatr 15 8 7 0 ta_tfifo (0): the task waits on an fifo basis ta_tpri (1): the task waits according to the priority ta_mfifo (0): mail is registered on an fifo basis ta_mpri (1): mail is registered according to the priority bit 0 specifies how the task waiting for mail reception is registered to the waiting task queue if no mail is registered to the mailbox. if ta_tfifo is specified, the task waits on an fifo basis. if ta_tpri is specified, it waits according to the priority. bit 1 specifies how mail is registered in the mailbox when it is transmitted, if there is no task waiting for mail reception. if ta_mfifo is specified, the mail is registered on an fifo basis. if ta_mpri is specified, the priority of the mail is referenced and the mail is registered according to its priority. ? maxmpri specifies the range (maximum value) of the priority of the mail if ta_mpri is specified as the mailbox attribute. an integer of 1 or greater and 0x7fff or less can be specified. the lower the value, the higher the priority of the mail. this value is ignored if ta_mfifo is specified. ? mprihd this is a reserved area. always specify null. anything other than null is ignored even if specified. [differences from itron3.0] the extended data exinf has been deleted from the members of the mailbox creation packet t_cmbx, and maxmpri and mprihd have been added. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_mbx is not included in the system e_rsatr ? 11 the mailbox attribute is illegal e_par ? 17 the parameter is illegal ? the priority of the mail is outside the range (maxmpri 0, 0x7fff < maxmpri) e_id ? 18 the mailbox id number is outside the range (mbxid 0, maximum mailbox count < mbxid) e_ctx ? 25 cre_mbx was issued from a non-task context cre_mbx was issued in the cpu lock state e_obj ? 41 a mailbox with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 207 create mailbox with automatic id assignment acre_mbx [overview] creates a mailbox (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 208 delete mailbox del_mbx [overview] deletes a mailbox [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 209 send mail to mailbox snd_mbx/isnd_mbx [overview] transmits a message to a mailbox [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 210 [differences from itron3.0] the name of snd_msg has been changed to snd_mbx. with the rx4000 v3.x, an error occurred if snd_msg was issued with a message already registered to the mailbox specified. with the rx4000 v4.0, however, no error occurs. multiple transmission must be checked by the user. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 snd_mbx/isnd_mbx is not included in the system e_par ? 17 the parameter is illegal ? the priority of the message is outside the range (msgpri 0, maximum priority value < msgpri) e_id ? 18 the mailbox id number is outside the range (mbxid 0, maximum mailbox count < mbxid) e_ctx ? 25 snd_mbx/isnd_mbx was issued in the cpu lock state e_noexs ? 42 the target mailbox does not exist chapter 13 service calls user?s manual u14833ej2v0um 211 receive mail from mailbox rcv_mbx [overview] receives a message from a mailbox [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 212 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 rcv_mbx is not included in the system e_id ? 18 the mailbox id number is outside the range (mbxid 0, maximum mailbox count < mbxid) e_ctx ? 25 rcv_mbx was issued from a non-task context rcv_mbx was issued in the cpu lock state rcv_mbx was issued in the dispatch disabled state e_noexs ? 42 the target mailbox does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the mailbox is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 213 poll and receive mail from mailbox prcv_mbx/iprcv_mbx [overview] receives a message from a mailbox (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 214 receive mail from mailbox with timeout trcv_mbx [overview] receives a message from a mailbox (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 215 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 trcv_mbx is not included in the system e_par ? 17 the timeout time is illegal (tmout < tmo_fevr = ? 1) e_id ? 18 the mailbox id number is outside the range (mbxid 0, maximum mailbox count < mbxid) e_ctx ? 25 trcv_mbx was issued from a non-task context trcv_mbx was issued in the cpu lock state trcv_mbx was issued in the dispatch disabled state e_noexs ? 42 the target mailbox does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the mailbox is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 216 refer mailbox status ref_mbx/iref_mbx [overview] obtains mailbox information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 217 [differences from itron3.0] the extended data exinf has been deleted from the mailbox information and mailbox attribute mbxatr has been added. the type of wtskid indicating the presence or absence of a waiting task has been changed from bool_id to id. in addition, the order of the parameters has also been changed. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_mbx/iref_mbx is not included in the system e_id ? 18 the mailbox id number is outside the range (mbxid 0, maximum mailbox count < mbxid) e_ctx ? 25 ref_mbx/iref_mbx was issued in the cpu lock state e_noexs ? 42 the target mailbox does not exist chapter 13 service calls user?s manual u14833ej2v0um 218 create mutex cre_mtx [overview] creates a mutex [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 219 figure 13-8. mutex attribute mtxatr 15 8 7 0 ta_tfifo (00): the task waits on an fifo basis ta_tpri (01): the task waits according to priority ta_inherit (10): the task waits according to priority and priority inheritance protocol ta_ceiling (11): the task waits according to priority and priority ceiling protocol bits 0 and 1 of mtxatr specify the order in which tasks are registered to the waiting task queue, and a priority control protocol if tasks wait for a mutex. the tasks wait on an fifo basis if ta_tfifo is specified; if any other attribute is specified, they wait according to priority. no priority control is performed if the ta_tfifo and ta_tpri attributes are specified. if the ta_inherit attribute is specified, a priority inheritance protocol is employed. if ta_ceiling attribute is specified, a priority ceiling protocol is employed. ? ceilpri specifies the ceiling value of the priority if ta_ceiling is specified as the mutex attribute. if a task waits for a mutex with the priority ceiling protocol selected, and if the priority of the task that locks the mutex is lower than that specified by ceilpri, the priority of the task is changed to that specified by ceilpri. if an attribute other than ta_ceiling is specified as the mutex attribute, the value of ceilpri is meaningless. [differences from itron3.0] cre_mtx is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_mtx is not included in the system e_rsatr ? 11 the mutex attribute is illegal e_par ? 17 the parameter is illegal ? the priority ceiling value is outside the range (ceilpri 0, maximum priority value < cilpri) e_id ? 18 the mutex id number is outside the range (mtxid 0, maximum mutex count < mtxid) e_ctx ? 25 cre_mtx was issued from a non-task context cre_mtx was issued in the cpu lock state e_obj ? 41 a mutex with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 220 create mutex with automatic id assignment acre_mtx [overview] creates a mutex (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 221 delete mutex del_mtx [overview] deletes a mutex [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 222 lock mutex loc_mtx [overview] locks a mutex [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 223 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 loc_mtx is not included in the system e_id ? 18 the mutex id number is outside the range (mtxid 0, maximum mutex count < mtxid) e_ctx ? 25 loc_mtx was issued from a non-task context loc_mtx was issued in the cpu lock state loc_mtx was issued in the dispatch disabled state e_iluse ? 28 the base priority is higher than the priority ceiling value (when ta_ceiling attribute is specified) e_noexs ? 42 the target mutex does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the mutex is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 224 poll and lock mutex ploc_mtx [overview] locks a mutex (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 225 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ploc_mtx is not included in the system e_id ? 18 the mutex id number is outside the range (mtxid 0, maximum mutex count < mtxid) e_ctx ? 25 ploc_mtx was issued from a non-task context ploc_mtx was issued in the cpu lock state e_iluse ? 28 the base priority is higher than the priority ceiling value (when ta_ceiling attribute is specified) e_noexs ? 42 the target mutex does not exist e_tmout ? 50 polling has failed chapter 13 service calls user?s manual u14833ej2v0um 226 lock mutex with timeout tloc_mtx [overview] locks a mutex (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 227 [differences from itron3.0] tloc_mtx is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 tloc_mtx is not included in the system e_par ? 17 the parameter is illegal ? the timeout time is illegal (tmout < tmo_fevr = ? 1) e_id ? 18 the mutex id number is outside the range (mtxid 0, maximum mutex count < mtxid) e_ctx ? 25 tloc_mtx was issued from a non-task context tloc_mtx was issued in the cpu lock state tloc_mtx was issued in the dispatch disabled state e_iluse ? 28 the base priority is higher than the priority ceiling value (when ta_ceiling attribute is specified) e_noexs ? 42 the target mutex does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the mutex is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 228 unlock mutex unl_mtx [overview] releases lock of a mutex [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 229 refer mutex status ref_mtx /i ref_mtx [overview] obtains mutex information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 230 [differences from itron3.0] ref_mtx is a newly created service call. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_mtx/iref_mtx is not included in the system e_id ? 18 the mutex id number is outside the range (mtxid 0, maximum mutex count < mtxid). e_ctx ? 25 ref_mtx/iref_mtx was issued in the cpu lock state e_noexs ? 42 the target mutex does not exist chapter 13 service calls user?s manual u14833ej2v0um 231 13.8.5 memory pool management function service calls this section describes the memory pool management function service calls listed in the following table. table 13-12. memory pool management function service calls name function cre_mpf creates a fixed-length memory pool acre_mpf creates a fixed-length memory pool (automatic assignment of id no.) del_mpf deletes a fixed-length memory pool rel_mpf/irel_mpf returns a memory block get_mpf acquires a memory block pget_mpf/ipget_mpf acquires a memory block (polling) tget_mpf acquires a memory block (with timeout) ref_mpf/iref_mpf obtains fixed-length memory pool information cre_mpl creates a variable-length memory pool acre_mpl creates a variable-length memory pool (automatic assignment of id no.) del_mpl deletes a variable-length memory pool rel_mpl/irel_mpl returns a memory block get_mpl acquires a memory block pget_mpl/ipget_mpl acquires a memory block (polling) tget_mpl acquires a memory block (with timeout) ref_mpl/iref_mpl obtains variable-length memory pool information chapter 13 service calls user?s manual u14833ej2v0um 232 create fixed-size memory pool cre_mpf [overview] creates a fixed-length memory pool [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 233 figure 13-9. fixed-length memory pool attribute mpfatr 15 8 7 0 ta_tfifo (0): the task waits on an fifo basis ta_tpri (1): the task waits according to priority if ta_tfifo is specified by mpfatr, the task waits on an fifo basis. if ta_tpri is specified, the task waits according to the priority. ? blkcnt specifies the number of memory blocks constituting the fixed-length memory pool to be created. ? blksz specifies the size of one memory block constituting the fixed-length memory pool to be created in bytes. this value must be an integral multiple of 8. if any other value is specified, a size that is the lowest integral multiple of 8 greater than the specified size is assumed. therefore, the total of the area that can be used for memory blocks is (blksz blkcnt). the size of the area that is extracted from the user pool, however, is greater than this value because a header that manages the area of the entire memory pool is appended. ? mpf this is a reserved area. always specify null. anything other than null is ignored even if specified. [differences from itron3.0] the extended data exinf has been deleted from the members of the fixed-length memory pool creation information and the reserved area mpf has been added. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_mpf is not included in the system e_rsatr ? 11 the fixed-length memory pool attribute is illegal e_par ? 17 the parameter is illegal ? the number of memory blocks is 0 (blkcnt = 0) ? the size of the memory block is 0 (blksz = 0) e_id ? 18 the fixed-length memory pool id number is outside the range (mpfid 0, maximum fixed-length memory pool count < mpfid) e_ctx ? 25 cre_mpf was issued from a non-task context cre_mpf was issued in the cpu lock state e_nomem ? 33 the area for the memory pool cannot be reserved e_obj ? 41 a fixed-length memory pool having the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 234 create fixed-size memory pool with automatic id assignment acre_mpf [overview] creates a fixed-length memory pool (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 235 delete fixed-size memory pool del_mpf [overview] deletes a fixed-length memory pool [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 236 release memory block to fixed-size memory pool rel_mpf/irel_mpf [overview] returns a memory block [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 237 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 rel_mpf/irel_mpf is not included in the system e_id ? 18 the fixed-length memory pool id number is outside the range (mpfid 0, maximum fixed-length memory pool count < mpfid) e_ctx ? 25 rel_mpf/irel_mpf was issued in the cpu lock state e_noexs ? 42 the target fixed-length memory pool does not exist chapter 13 service calls user?s manual u14833ej2v0um 238 get memory block from fixed-size memory pool get_mpf [overview] acquires a memory block [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 239 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 get_mpf is not included in the system e_id ? 18 the fixed-length memory pool id number is outside the range (mpfid 0, maximum fixed-length memory pool count < mpfid) e_ctx ? 25 get_mpf was issued from a non-task context get_mpf was issued in the cpu lock state get_mpf was issued in the dispatch disabled state e_noexs ? 42 the target fixed-length memory pool does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the fixed-length memory pool is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 240 poll and get memory block from fixed-size memory pool pget_mpf/ipget_mpf [overview] acquires a memory block (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 241 get memory block from fixed-size memory pool with timeout tget_mpf [overview] acquires a memory block (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 242 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 tget_mpf is not included in the system e_par ? 17 the parameter is illegal ? the timeout time is illegal (tmout < tmo_fevr = ? 1) e_id ? 18 the fixed-length memory pool id number is outside the range (mpfid 0, maximum fixed-length memory pool count < mpfid) e_ctx ? 25 tget_mpf was issued from a non-task context tget_mpf was issued in the cpu lock state tget_mpf was issued in the dispatch disabled state e_noexs ? 42 the target fixed-length memory pool does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the fixed-length memory pool is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 243 refer fixed-size memory pool status ref_mpf/iref_mpf [overview] obtains fixed-length memory pool information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 244 [differences from itron3.0] the extended data exinf has been deleted from the members of the fixed-length memory pool information and the fixed-length memory pool attribute mpfatr has been added. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_mpf/iref_mpf is not included in the system e_id ? 18 the fixed-length memory pool id number is outside the range (mpfid 0, maximum fixed-length memory pool count < mpfid) e_ctx ? 25 ref_mpf/iref_mpf was issued in the cpu lock state e_noexs ? 42 the target fixed-length memory pool does not exist chapter 13 service calls user?s manual u14833ej2v0um 245 create variable-size memory pool cre_mpl [overview] creates a variable-length memory pool [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 246 figure 13-10. variable-length memory pool attribute mplatr 15 8 7 0 ta_tfifo (0): the task waits on an fifo basis ta_tpri (1): the task waits according to priority bit 0 specifies the order in which tasks wait for a memory block from the memory pool to be created. if ta_tfifo is specified by mplatr, the task waits on an fifo basis. if ta_tpri is specified, the task waits according to the priority. ? mplsz specifies the size (in bytes) of the variable-length memory pool to be created. this value must be an integral multiple of 8. if any other value is specified, a size that is the lowest integral multiple of 8 greater than the specified size is assumed. when a memory pool is actually created, it is greater than the value specified by mplsz because a header area that manages all the memory pools is necessary in addition to the area of the main body of the memory pool. ? mpl this is a reserved area. always specify null. anything other than null is ignored even if specified. [differences from itron3.0] the extended data exinf has been deleted from the members of the variable-length memory pool creation packet t_cmpl, and the reserved area mpl has been added. in addition, the type of the memory pool size mplsz has been changed from int to size. size is a type newly defined for itron4.0. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_mpl is not included in the system e_rsatr ? 11 the variable-length memory pool attribute is illegal e_par ? 17 the parameter is illegal ? the size of the memory pool is illegal (mplsz = 0) e_id ? 18 the variable-length memory pool id number is outside the range (mplid 0, maximum variable-length memory pool count < mplid) e_ctx ? 25 cre_mpl was issued from a non-task context cre_mpl was issued in the cpu lock state e_nomem ? 33 the area for the memory pool cannot be reserved e_obj ? 41 a variable-length memory pool with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 247 create variable-size memory pool with automatic id assignment acre_mpl [overview] creates a variable-length memory pool (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 248 delete variable-size memory pool del_mpl [overview] deletes a variable-length memory pool [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 249 release memory block to variable-size memory pool rel_mpl /irel_mpl [overview] returns a memory block [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 250 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 rel_mpl/irel_mpl is not included in the system e_par ? 17 the parameter is illegal ? the source and return destination of the memory block are different e_id ? 18 the variable-length memory pool id number is outside the range (mplid 0, maximum variable-length memory pool count < mplid) e_ctx ? 25 rel_mpl/irel_mpl was issued in the cpu lock state e_noexs ? 42 the target variable-length memory pool does not exist chapter 13 service calls user?s manual u14833ej2v0um 251 get memory block from variable-size memory pool get_mpl [overview] acquires a memory block [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 252 [differences from itron3.0] the name of get_blk has been changed to get_mpl. in addition, the order of the parameters has also been changed. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 get_mpl is not included in the system e_par ? 17 the parameter is illegal ? the memory block size is illegal (blksz = 0) e_id ? 18 the variable-length memory pool id number is outside the range (mplid 0, maximum variable-length memory pool count < mplid) e_ctx ? 25 get_mpl was issued from a non-task context get_mpl was issued in the cpu lock state get_mpl was issued in the dispatch disabled state e_noexs ? 42 the target variable-length memory pool does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_dlt ? 51 the variable-length memory pool is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 253 poll and get memory block from variable-size memory pool pget_mpl/ipget_mpl [overview] acquires a memory block (polling) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 254 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 pget_mpl/ipget_mpl is not included in the system e_par ? 17 the parameter is illegal ? the memory block size is illegal (blksz = 0) e_id ? 18 the variable-length memory pool id number is outside the range (mplid 0, maximum variable-length memory pool count < mplid) e_ctx ? 25 pget_mpl/ipget_mpl was issued in the cpu lock state e_noexs ? 42 the target variable-length memory pool does not exist e_tmout ? 50 polling has failed chapter 13 service calls user?s manual u14833ej2v0um 255 get memory block from variable-size memory pool with timeout tget_mpl [overview] acquires a memory block (with timeout) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 256 tasks placed in the waiting state due to tget_mpl are released from waiting by one of the following occurrences. 1. (i)rel_mpl is issued and the task acquires a memory block (e_ok). 2. the blocking task is released from the waiting task queue and acquires a memory block (e_ok). 3. the specified time elapses and timeout occurs (e_tmout). 4. (i)rel_wai is issued and the task is forcibly released from the waiting state (e_rlwai). 5. del_mpl is issued and the memory pool is deleted (e_dlt). [differences from itron3.0] the name of tget_blf has been changed to tget_mpl. in addition, the order of the parameters has also been changed. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 tget_mpl is not included in the system e_par ? 17 the parameter is illegal ? the memory block size is illegal (blksz = 0) ? the timeout time is illegal (tmout < tmo_fevr = ? 1) e_id ? 18 the variable-length memory pool id number is outside the range (mplid 0, maximum variable-length memory pool count < mplid) e_ctx ? 25 tget_mpl was issued from a non-task context tget_mpl was issued in the cpu lock state tget_mpl was issued in the dispatch disabled state e_noexs ? 42 the target variable-length memory pool does not exist e_rlwai ? 49 the task is forcibly released from the waiting state by (i)rel_wai e_tmout ? 50 timeout e_dlt ? 51 the variable-length memory pool is deleted while a task is waiting chapter 13 service calls user?s manual u14833ej2v0um 257 refer variable-size memory pool status ref_mpl /i ref_mpl [overview] obtains memory pool information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 258 iref_mpl is intended to be issued from a non-task context but it can also be issued from a task context. ref_mpl can be issued from a non-task context. [differences from itron3.0] the extended data exinf has been deleted from the members of the variable-length memory pool information. in addition, the type of wtskid indicating the presence or absence of a waiting task has been changed from bool_id to id, and the type of the total size of available area fmplsz and the maximum size of the available block fblksz has been changed from int to size and unit. size is a type newly defined for itron4.0. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_mpl/iref_mpl is not included in the system e_id ? 18 the variable-length memory pool id number is outside the range (mplid 0, maximum variable-length memory pool count < mplid) e_ctx ? 25 ref_mpl/iref_mpl was issued in the cpu lock state e_noexs ? 42 the target variable-length memory pool does not exist chapter 13 service calls user?s manual u14833ej2v0um 259 13.8.6 time management function service calls this section explains the time management function service calls listed in the following table. table 13-13. time management function service calls name function set_tim/iset_tim sets the system time get_tim/iget_tim obtains the system time isig_tim supplies the time tick (issued from isr) cre_cyc creates a cyclic handler acre_cyc creates a cyclic handler (automatic assignment of id no.) del_cyc deletes a cyclic handler sta_cyc/ista_cyc activates a cyclic handler stp_cyc/istp_cyc stops a cyclic handler ref_cyc/iref_cyc obtains cyclic handler information isr: interrupt service routine chapter 13 service calls user?s manual u14833ej2v0um 260 set system time set_tim/iset_tim [overview] sets the time of the system [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 261 get system time get_tim/iget_tim [overview] obtains the time of the system [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 262 signal clock tick isig_tim [overview] supplies a time tick (issued from an interrupt service routine) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 263 create cyclic handler cre_cyc [overview] creates a cyclic handler [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 264 bit 2 specifies whether the created cyclic handler saves the phase cycphs to be explained below. if ta_phs is specified, the phase is saved. by issuing sta_cyc after the handler has been created, the phase cycphs becomes valid when the handler is activated. if two or more attributes are specified at the same time, set the logical sum of the attribute values to cycatr. figure 13-11. cyclic handler attribute cycatr 15 8 7 0 ta_asm (1): described in assembly language ta_hlng (0): described in c language ta_sta (1): handler is created in operating status ta_phs (1): phase cycphs is saved ? exinf sets user-defined information on the cyclic handler to be created. this value is passed to the cyclic handler when it has been created. ? cychdr specifies the activation address of the cyclic handler to be created. ? cyctim specifies the interval in milliseconds at which the created cyclic handler is to be activated. ? cycphs specifies the phase of the cyclic handler to be created in milliseconds. this means that the created cyclic handler is activated cycphs [milliseconds] after cre_cyc has been issued. this phase can be saved by specifying ta_phs as the cyclic handler attribute. in other words, the activation timing of the cyclic handler can be fixed, regardless of changes in status after the cyclic handler has been created. cycphs is meaningless if neither ta_sta nor ta_phs is given as a handler attribute. ? gp specifies the base address (gp) of pid (position independent data) used by the cyclic handler to be created. set null if the cyclic handler does not use pid. ? tp this is a reserved area. always set null to this area. however, a value other than null is ignored even if set. [differences from itron3.0] 1. change of terminology and service call name ?defining cyclic handler? ?creating cyclic handler? ?cyclically activated handler definition number? ?cyclic handler id number? def_cyc cre_cyc ?activated status? ?cyclic handler status? or ?status? contents of status: ?on status? ?operating (sta) status? ?off status? ?stop (stp) status? 2. an activation phase can be specified for the cyclic handler. 3. explicit specification by an attribute is not necessary even when the cyclic handler uses pid. chapter 13 service calls user?s manual u14833ej2v0um 265 [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_cyc is not included in the system e_rsatr ? 11 the cyclic handler attribute is illegal e_par ? 17 the parameter is illegal ? the activation phase is illegal (cyctim = 0) ? the activation phase is outside the range (cycphs = 0) e_id ? 18 the id number of the cyclic handler is outside the range (cycid 0, maximum cyclic handler count < 0) e_ctx ? 25 cre_cyc was issued from a non-task context cre_cyc was issued in the cpu lock state e_obj ? 41 a cyclic handler with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 266 create cyclic handler with automatic id assignment acre_cyc [overview] creates a cyclic handler (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 267 delete cyclic handler del_cyc [overview] deletes a cyclic handler [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 268 start cyclic handler sta_cyc/ista_cyc [overview] activates a cyclic handler [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 269 stop cyclic handler stp_cyc/istp_cyc [overview] stops a cyclic handler [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 270 refer cyclic handler status ref_cyc/iref_cyc [overview] obtains cyclic handler information [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 271 ? cyctim stores the activation interval of the specified cyclic handler (in milliseconds). ? cycphs stores the activation phase of the specified cyclic handler (in milliseconds). iref_cyc is intended to be issued from a non-task context but it can also be issued from a task context. ref_cyc can be issued from a non-task context. [differences from itron3.0] 1. the specification order of the parameters has been changed. 2. the cyclic handler specification number is called a cyclic handler id number, and its type has been changed from hno to id. 3. in connection with the above, the error code e_id that may be returned has been added. 4. ?activated status? is called cyclic handler status or just status. each status has been also changed from on to sta and from off to stp. 5. extended data exinf has been deleted from the members of the cyclic handler information packet t_rcyc, and cyclic handler attribute cycatr and phase cycphs have been added. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 ref_cyc/iref_cyc is not included in the system e_id ? 18 the id number of the cyclic handler is outside the range (cycid 0, maximum cyclic handler count < cycid) e_ctx ? 25 ref_cyc/iref_cyc was issued from a non-task context ref_cyc/iref_cyc was issued in the cpu lock state e_noexs ? 42 the target handler does not exist chapter 13 service calls user?s manual u14833ej2v0um 272 13.8.7 system status management function service calls this section explains the system status management function service calls listed in the following table. table 13-14. system status management function service calls name function rot_rdq/irot_rdq rotates a ready queue get_tid/iget_tid obtains the id number of a task in the running state loc_cpu/iloc_cpu locks the cpu of the system unl_cpu/iunl_cpu releases the cpu lock of the system dis_dsp disables dispatch ena_dsp enables dispatch sns_ctx references the execution context sns_loc checks whether the cpu is locked sns_dsp checks whether dispatch is disabled sns_dpn checks whether dispatch is pending chapter 13 service calls user?s manual u14833ej2v0um 273 rotate ready queue rot_rdq/irot_rdq [overview] rotates a ready queue [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 274 get task identifier get_tid/iget_tid [overview] obtains the id number of the task in the running state [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 275 lock cpu loc_cpu/iloc_cpu [overview] locks the cpu of the system [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 276 unlock cpu unl_cpu/iunl_cpu [overview] releases the cpu lock of the system [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 277 disable dispatch dis_dsp [overview] disables dispatch [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 278 enable dispatch ena_dsp [overview] enables dispatch [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 279 sense context sns_ctx [overview] references a context [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 280 sense cpu locked or not sns_loc [overview] checks whether the cpu is locked [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 281 sense dispatch enabled or not sns_dsp [overview] checks whether dispatch is disabled [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 282 sense dispatch pending sns_dpn [overview] checks whether dispatch is pending [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 283 13.8.8 interrupt management function service calls this section explains the interrupt management function service calls. note that the descriptions in this section apply if the source file supplied as a sample is used without modification. the user can change the functions of the source file as necessary. table 13-15. interrupt management function service calls name function cre_isr creates an isr acre_isr creates an isr (automatic assignment of id no.) del_isr deletes an isr dis_int disables interrupts ena_int enables interrupts chg_ims/ichg_ims changes the interrupt mask get_imsi/get_ims references the interrupt mask chapter 13 service calls user?s manual u14833ej2v0um 284 create interrupt service routine cre_isr [overview] creates an interrupt service routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 285 bit 0 specifies the language in which the interrupt service routine is described. ta_asm means that the routine is described in an assembly language. ta_hlng means the c language. with the current version, however, these two attributes are not differentiated in the kernel processing. ? exinf stores user-defined information on the interrupt service routine to be created. this extended data is passed to the interrupt service routine as a parameter when the routine is activated. ? intno specifies a number that uniformly identifies the interrupt corresponding to the interrupt service routine to be created. interrupt numbers can be arbitrarily defined by the user. however, ? 1 must not be used as it is reserved for the system. ? isr specifies the activation address of the interrupt service routine. ? gp specifies the base address (gp) of pid (position independent data) used by the interrupt service routine to be created. set null if the routine does not use pid. ? tp this is a reserved area. always set null to this area. however, a value other than null is ignored even if set. [differences from itron3.0] it is defined that processing corresponding to an interrupt vector is performed by an ?interrupt handler? and the processing corresponding to an interrupt source is performed by an ?interrupt service routine?. because the rx4000 has only one interrupt vector for the v r 4100 series and v r 5000 series, it does not supply a function to define interrupt handlers but supplies a function to create interrupt service routines. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 cre_isr is not included in the system e_rsatr ? 11 the interrupt service routine attribute is illegal e_par ? 17 the parameter is illegal ? the interrupt number is illegal (intno > maximum interrupt number) e_id ? 18 the interrupt service routine id number is outside the range (isrid 0, maximum interrupt service routine count < isrid) e_ctx ? 25 cre_isr was issued from a non-task context cre_isr was issued in the cpu lock state e_obj ? 41 an interrupt service routine with the same id number already exists chapter 13 service calls user?s manual u14833ej2v0um 286 create interrupt service routine with automatic id assignment acre_isr [overview] creates an interrupt service routine (automatic assignment of id number) [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 287 delete interrupt service routine del_isr [overview] deletes an interrupt service routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 288 disable interrupt dis_int [overview] disables interrupts. [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 289 disable interrupt ena_int [overview] enables interrupts [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 290 change interrupt mask chg_ims/ichg_ims [overview] changes the interrupt mask [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 291 get interrupt mask get_ims/iget_ims [overview] obtains the interrupt mask [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 292 13.8.9 system configuration management function service calls this section explains the system configuration management function service calls listed in the following table. table 13-16. system configuration management function service calls name function def_exc defines a cpu exception handler ivsta_exc activates a cpu exception handler chapter 13 service calls user?s manual u14833ej2v0um 293 define exception handler def_exc [overview] defines a cpu exception handler [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 294 figure 13-13. exception handler attribute excatr 15 8 7 0 ta_asm (1): described in an assembly language ta_hlng (0): described in c language ? exchdr specifies the activation address of the cpu exception handler to be defined. ? gp specifies the base address of pid used by the cpu exception handler to be defined. set null if the handler does not use pid. ? tp this is a reserved area. always set null to this area. however, a value other than null is ignored even if set. [differences from itron3.0] the rx4000 v3.x allows only one cpu exception handler to exist in the system. the rx4000 ( itron4.0) allows two or more cpu exception handlers to be defined. however, the user must describe what processing the hander should perform depending on the source of the exception, and how the handler is activated. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 def_exc is not included in the system e_rsatr ? 11 the cpu exception handler attribute is illegal e_par ? 17 the cpu exception handler definition number is outside the range (excno < 0, maximum cpu exception handler count dexcno) e_ctx ? 25 def_exc was issued from a non-task context def_exc was issued in the cpu lock state chapter 13 service calls user?s manual u14833ej2v0um 295 attach idle routine vatt_idl [overview] defines an idle routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 296 figure 13-14. exception handler attribute idlatr 15 8 7 0 ta_asm (1): described in an assembly language ta_hlng (0): described in c language ? idlrtn specifies the activation address of the idle routine to be defined. ? gp specifies the base address of pid used by the idle routine to be defined. set null if the routine does not use pid. ? tp this is a reserved area. always set null to this area. however, a value other than null is ignored even if set. [differences from itron3.0] the rx4000 v3.x calls the idle routine an idle handler. definition of the idle routine by a service call is not supported. by adding the new service call vatt_idl, the idle routine can be now defined by a service call. vatt_idl is the original extended function of the rx4000 and is not defined in the itron4.0 specification. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 vatt_idl is not included in the system e_rsatr ? 11 the idle routine attribute is illegal e_ctx ? 25 vatt_idl was issued from a non-task context vatt_idl was issued in the cpu lock state chapter 13 service calls user?s manual u14833ej2v0um 297 13.8.10 service call management function service calls this section explains the service call management function service calls listed in the following table. table 13-17. service call management function service calls name function def_svc defines an extended service call routine cal_svc/ical_svc activates an extended service call routine chapter 13 service calls user?s manual u14833ej2v0um 298 define extended service call routine def_svc [overview] defines an extended service call routine [c format] #include chapter 13 service calls user?s manual u14833ej2v0um 299 figure 13-15. extended service call routine attribute svcatr 15 8 7 0 ta_asm (1): described in an assembly language ta_hlng (0): described in c language ? svcrtn specifies the activation address of the extended service call routine to be defined. ? gp specifies the base address of pid used by the extended service call routine to be defined. set null if the routine does not use pid. ? tp this is a reserved area. always set null to this area. however, a value other than null is ignored even if set. [differences from itron3.0] the extended svc handler is now called an extended service call routine. [return values] symbol value meaning e_ok 0 normal termination e_rsfn ? 10 def_svc is not included in the system e_par ? 10 the function code is outside the range (fncd 0, maximum extended service call routine count < fncd) e_rsatr ? 11 the extended service call routine attribute is illegal e_ctx ? 25 def_svc was issued from a non-task context def_svc was issued in the cpu lock state chapter 13 service calls user?s manual u14833ej2v0um 300 call extended service call routine cal_svc/ical_svc [overview] calls a service call [c format] #include user?s manual u14833ej2v0um 301 appendix index [symbol] itron4.0 specification .......................................... 17 [a] acre_cyc ................................................................ 266 acre_dtq................................................................. 190 acre_flg .................................................................. 176 acre_isr .................................................................. 286 acre_mbx ............................................................... 207 acre_mpf................................................................ 234 acre_mpl ................................................................ 247 acre_mtx ................................................................ 220 acre_sem ............................................................... 165 acre_tsk ................................................................. 121 act_tsk ................................................................... 123 activation request .................................................... 34 address.................................................................... 23 and wait .................................................................. 51 another task forcibly terminating ............................................ 129 releasing waiting state ...................................... 144 [b] base priority............................................................. 39 boot processing block ............................................ 104 [c] cal_svc................................................................... 300 can_act .................................................................. 125 can_wup ................................................................ 143 chg_ims ................................................................. 290 chg_pri ................................................................... 130 clr_flg ..................................................................... 179 coprocessor .................................. 32, 40, 89, 95, 103 cpu exception handler ............................................ 99 activating/terminating ......................................... 100 defining .............................................................. 100 exception handler number ................................. 100 issuance of service calls .................................... 100 pid ..................................................................... 100 use of coprocessor ............................................ 100 cpu lock state ............................................... 275, 280 cre_cyc .................................................................. 263 cre_dtq................................................................... 188 cre_flg .................................................................... 174 cre_isr.....................................................................284 cre_mbx..................................................................205 cre_mpf ..................................................................232 cre_mpl...................................................................245 cre_mtx...................................................................218 cre_sem..................................................................163 cre_tsk....................................................................118 cross tool ...........................................................17, 19 current priority..........................................................39 cyclic handler...........................................................86 activating ..............................................................87 creating ................................................86, 263, 266 deleting.........................................................86, 267 interrupts...............................................................88 issuance of service calls .......................................89 obtaining information..........................................270 operable status...................................................268 phase....................................................................87 state .....................................................................86 stopped status ....................................................269 terminating ...........................................................87 use of coprocessor ...............................................89 [d] data queue...............................................................54 communication .....................................................56 creating ................................................54, 188, 190 deleting.........................................................54, 191 obtaining information..........................................203 receiving data ..............................55, 198, 200, 201 transmitting data...................55, 192, 194, 195, 197 data reception wait...................................................36 data transmission wait .............................................36 data type ................................................................110 general data type ...............................................110 rx4000 data type ...............................................111 debugger..................................................................19 def_exc ...................................................................293 def_svc ...................................................................298 def_tex....................................................................152 del_cyc ...................................................................267 del_dtq....................................................................191 del_flg.....................................................................177 del_isr.....................................................................287 del_mbx..................................................................208 appendix index user?s manual u14833ej2v0um 302 del_mpf .................................................................. 235 del_mpl .................................................................. 248 del_mtx .................................................................. 221 del_sem.................................................................. 166 del_tsk.................................................................... 122 development environment........................................ 19 dis_dsp................................................................... 277 dis_int..................................................................... 288 dis_tex.................................................................... 156 dispatch disable........................................................ 277, 281 enable ................................................................ 278 pending............................................................... 282 dly_tsk .................................................................... 149 dormant ................................................................... 36 drive method............................................................ 25 [e] ena_dsp ................................................................. 278 ena_int ................................................................... 289 ena_tex .................................................................. 157 error code .............................................................. 109 evaluation board ...................................................... 19 event flag ................................................................. 50 clear ............................................................. 51, 179 creating ................................................ 50, 174, 176 deleting ........................................................ 50, 177 obtaining information.......................................... 186 satisfying condition............................. 180, 182, 184 setting ................................................................ 178 wait ...................................................................... 52 wait condition ....................................................... 51 event flag wait .......................................................... 36 exception handler cpu exception handler......................................... 99 exception processing ............................................... 96 occurrence notification ......................................... 99 processing flow .................................................... 96 exd_tsk................................................................... 128 ext_tsk.................................................................... 127 extended function code............................................ 23 extended service call routine ................................. 102 activating and terminating .................................. 102 defining ...................................................... 102, 298 use of coprocessor............................................. 103 [f] fcfs method........................................................... 25 fixed-length memory block...................................... 71 acquiring .......................................72, 238, 240, 241 returning ..................................................... 72, 236 fixed-length memory block wait............................... 36 fixed-length memory pool ....................................... 70 acquiring memory blocks ..................................... 73 creating ................................................70, 232, 234 deleting........................................................ 70, 235 obtaining information ................................... 72, 243 structure .............................................................. 71 forcible termination ................................................. 35 frsm_tsk ................................................................. 148 fsnd_dtq................................................................. 197 [g] get_ims .................................................................. 291 get_mpf.................................................................. 238 get_mpl.................................................................. 251 get_pri.................................................................... 132 get_tid.................................................................... 274 get_tim................................................................... 261 [h] handler number ....................................................... 23 host os ................................................................... 19 [i] iact_tsk .................................................................. 123 ical_svc.................................................................. 300 ican_act ................................................................. 125 ican_wup ............................................................... 143 ichg_ims ................................................................ 290 ichg_pri .................................................................. 130 iclr_flg .................................................................... 179 id number ................................................................ 23 idle routine............................................................... 32 defining.............................................................. 295 executing and terminating.................................... 32 registering........................................................... 32 ifrsm_tsk ................................................................ 148 ifsnd_dtq ................................................................ 197 iget_ims ................................................................. 291 iget_pri................................................................... 132 iget_tid ................................................................... 274 iget_tim .................................................................. 261 iloc_cpu ................................................................. 275 initial priority ............................................................ 39 initialization processing.................................... 22, 104 appendix index user?s manual u14833ej2v0um 303 initialization routine ........................................ 101, 105 activating............................................................ 101 defining .............................................................. 101 terminating......................................................... 101 interface library ................................................ 18, 106 function and position ......................................... 106 interrupt disable ............................................................... 288 enable ................................................................ 289 management .................................................. 22, 90 interrupt control........................................................ 90 interrupt initialization .............................................. 105 interrupt management function service call ... 108, 283 acre_isr .............................................................. 286 chg_ims.............................................................. 290 cre_isr ................................................................ 284 del_isr................................................................. 287 dis_int................................................................. 288 ena_int ............................................................... 289 get_ims............................................................... 291 ichg_ims ............................................................. 290 iget_ims.............................................................. 291 interrupt mask changing............................................................ 290 obtaining............................................................ 291 interrupt number ...................................................... 23 interrupt processing management ........................... 91 interrupt service routine ........................................... 94 activating.............................................................. 94 creating................................................ 94, 284, 286 deleting ........................................................ 94, 287 id number and interrupt number .......................... 94 issuance of service calls ...................................... 95 terminating........................................................... 95 use of coprocessor .............................................. 95 ipget_mpf ............................................................... 240 ipget_mpl ............................................................... 253 ipol_flg ................................................................... 182 ipol_sem ................................................................ 169 iprcv_dtq ................................................................ 200 iprcv_mbx .............................................................. 213 ipsnd_dtq ............................................................... 194 iras_tex .................................................................. 154 iref_cyc .................................................................. 270 iref_dtq................................................................... 203 iref_flg .................................................................... 186 iref_mbx ................................................................. 216 iref_mpf.................................................................. 243 iref_mpl...................................................................257 iref_mtx...................................................................229 iref_sem..................................................................172 iref_tex....................................................................159 iref_tsk....................................................................133 iref_tst.....................................................................136 irel_mpf...................................................................236 irel_mpl...................................................................249 irel_wai ...................................................................144 irot_rdq ...................................................................273 irsm_tsk ..................................................................147 iset_flg ....................................................................178 iset_tim ...................................................................260 isig_sem .................................................................167 isig_tim ...................................................................262 isnd_mbx ................................................................209 ista_cyc ..................................................................268 ista_tsk ...................................................................126 istp_cyc ..................................................................269 isus_tsk ..................................................................145 iunl_cpu ..................................................................276 iwup_tsk .................................................................142 [k] kernel .................................................................18, 20 kernel initialization block ........................................105 [l] loc_cpu ...................................................................275 loc_mtx ...................................................................222 locking .....................................................................66 [m] macro .....................................................................112 mailbox .....................................................................60 communication .....................................................62 creating ................................................60, 205, 207 deleting.........................................................60, 208 obtaining information..........................................216 receiving messages.....................62, 211, 213, 214 transmitting messages .................................61, 209 management object creation and initialization....................................105 memory block acquiring..................... 238, 240, 241, 251, 253, 255 returning ....................................................236, 249 memory management ........................................22, 69 memory pool appendix index user?s manual u14833ej2v0um 304 obtaining information...................... 72, 80, 243, 257 memory pool management function system call.................................................................. 108, 231 acre_mpf............................................................. 234 acre_mpl............................................................. 247 cre_mpf............................................................... 232 cre_mpl............................................................... 245 del_mpf............................................................... 235 del_mpl ............................................................... 248 get_mpf............................................................... 238 get_mpl............................................................... 251 ipget_mpf............................................................ 240 ipget_mpl ............................................................ 253 iref_mpf............................................................... 243 iref_mpl............................................................... 257 irel_mpf............................................................... 236 irel_mpl ............................................................... 249 pget_mpf............................................................. 240 pget_mpl............................................................. 253 ref_mpf ............................................................... 243 ref_mpl................................................................ 257 rel_mpf................................................................ 236 rel_mpl................................................................ 249 tget_mpf.............................................................. 241 tget_mpl.............................................................. 255 message................................................................... 61 allocating area...................................................... 61 contents ............................................................... 61 priority .................................................................. 61 message reception wait............................................ 36 multitask os............................................................. 16 multitasking .............................................................. 16 mutex ....................................................................... 65 creating ................................................ 65, 218, 220 deleting ........................................................ 65, 221 locking ......................................... 66, 222, 224, 226 obtaining information.......................................... 229 priority ceiling protocol ......................................... 65 priority control rules.............................................. 66 priority inheritance protocol .................................. 65 releasing locks ............................................ 66, 228 synchronization .................................................... 67 mutex wait ................................................................ 36 [n] non-existent ............................................................. 36 normal termination................................................... 35 [o] object ...................................................................... 23 creation ............................................................. 105 object control block ................................................. 23 automatic assignment of id number .................... 24 creating and deleting ........................................... 24 identification number............................................ 23 or wait .................................................................... 51 [p] parameter value range........................................... 113 peripheral hardware................................................. 19 pget_mpf................................................................ 240 pget_mpl................................................................ 253 pid..........................................32, 40, 89, 95, 100, 103 ploc_mtx ................................................................ 224 pol_flg .................................................................... 182 pol_sem ................................................................. 169 pool creation and initialization ............................... 105 prcv_dtq................................................................. 200 prcv_mbx ............................................................... 213 priority ceiling protocol ............................................ 65 priority control rules................................................. 66 priority inheritance protocol ..................................... 65 priority method ........................................................ 25 processor ................................................................ 19 psnd_dtq................................................................ 194 [r] ras_tex ................................................................... 154 rcv_dtq................................................................... 198 rcv_mbx ................................................................. 211 ready ...................................................................... 36 ready queue ........................................................... 26 creation ............................................................. 105 rotation.............................................................. 273 real-time os ........................................................... 16 ref_cyc ................................................................... 270 ref_dtq ................................................................... 203 ref_flg..................................................................... 186 ref_mbx.................................................................. 216 ref_mpf .................................................................. 243 ref_mpl................................................................... 257 ref_mtx................................................................... 229 ref_sem.................................................................. 172 ref_tex.................................................................... 159 ref_tsk.................................................................... 133 ref_tst..................................................................... 136 appendix index user?s manual u14833ej2v0um 305 rel_mpf................................................................... 236 rel_mpl ................................................................... 249 rel_wai ................................................................... 144 releasing cpu lock state ...................................... 276 resource acquiring ...................................... 47, 168, 169, 170 returning...................................................... 47, 167 return value .......................................................... 109 romization .............................................................. 17 rot_rdq ................................................................... 273 round robin method ................................................ 27 rsm_tsk .................................................................. 147 running ................................................................... 36 [s] saving/restoring registers .................................. 93, 99 cpu exception handler......................................... 99 scheduler........................................................... 21, 25 scheduling ............................................................... 25 delay .................................................................... 30 enabling/disabling ................................................ 31 scheduling method .................................................. 25 semaphore .............................................................. 46 acquiring resource ............................. 168, 169, 170 creating................................................ 46, 163, 165 deleting ........................................................ 47, 166 exclusive control .................................................. 48 obtaining information ......................................... 172 returning resource............................................. 167 semaphore wait ....................................................... 36 set_flg .................................................................... 178 set_tim ................................................................... 260 sig_sem ................................................................. 167 slp_tsk.................................................................... 139 snd_dtq .................................................................. 192 snd_mbx ................................................................ 209 sns_ctx................................................................... 279 sns_dpn ................................................................. 282 sns_dsp ................................................................. 281 sns_loc................................................................... 280 sns_tex................................................................... 158 sta_cyc................................................................... 268 sta_tsk ................................................................... 126 stack pool .......................................................... 69, 70 stp_cyc................................................................... 269 sus_tsk................................................................... 145 suspended............................................................... 37 synchronous communication management ....... 21, 46 synchronous communication management function service call ........................................108, 161 acre_dtq..............................................................190 acre_flg ...............................................................176 acre_mbx ............................................................207 acre_mtx .............................................................220 acre_sem ............................................................165 clr_flg ..................................................................179 cre_dtq................................................................188 cre_flg .................................................................174 cre_mbx ..............................................................205 cre_mtx ...............................................................218 cre_sem ..............................................................163 del_dtq ................................................................191 del_flg .................................................................177 del_mbx ..............................................................208 del_mtx ...............................................................221 del_sem ..............................................................166 fsnd_dtq ..............................................................197 iclr_flg .................................................................179 ifsnd_dtq .............................................................197 ipol_flg ................................................................182 ipol_sem .............................................................169 iprcv_dtq .............................................................200 iprcv_mbx ...........................................................213 ipsnd_dtq ............................................................194 iref_dtq................................................................203 iref_flg .................................................................186 iref_mbx ..............................................................216 iref_mtx ...............................................................229 iref_sem ..............................................................172 iset_flg ................................................................178 isig_sem..............................................................167 isnd_mbx ............................................................209 loc_mtx ...............................................................222 ploc_mtx .............................................................224 pol_flg .................................................................182 pol_sem ..............................................................169 prcv_dtq ..............................................................200 prcv_mbx ............................................................213 psnd_dtq .............................................................194 rcv_dtq ................................................................198 rcv_mbx ..............................................................211 ref_dtq.................................................................203 ref_flg..................................................................186 ref_mbx...............................................................216 ref_mtx................................................................229 ref_sem...............................................................172 appendix index user?s manual u14833ej2v0um 306 set_flg ................................................................. 178 sig_sem .............................................................. 167 snd_dtq............................................................... 192 snd_mbx ............................................................. 209 tloc_mtx .............................................................. 226 trcv_dtq............................................................... 201 trcv_mbx ............................................................. 214 tsnd_dtq.............................................................. 195 twai_flg ............................................................... 184 twai_sem ............................................................ 170 unl_mtx ............................................................... 228 wai_flg ................................................................ 180 wai_sem ............................................................. 168 system base table creation .............................................................. 105 service call............................................................. 107 acre_cyc ............................................................. 266 acre_dtq.............................................................. 190 acre_flg............................................................... 176 acre_isr............................................................... 286 acre_mbx............................................................ 207 acre_mpf............................................................. 234 acre_mpl............................................................. 247 acre_mtx............................................................. 220 acre_sem............................................................ 165 acre_tsk .............................................................. 121 act_tsk ................................................................ 123 cal_svc................................................................ 300 can_act ............................................................... 125 can_wup ............................................................. 143 chg_ims .............................................................. 290 chg_pri................................................................ 130 clr_flg .................................................................. 179 cre_cyc ............................................................... 263 cre_dtq................................................................ 188 cre_flg................................................................. 174 cre_isr................................................................. 284 cre_mbx.............................................................. 205 cre_mpf............................................................... 232 cre_mpl............................................................... 245 cre_mtx............................................................... 218 cre_sem.............................................................. 163 cre_tsk ................................................................ 118 def_exc ............................................................... 293 def_svc ............................................................... 298 def_tex................................................................ 152 del_cyc ............................................................... 267 del_dtq................................................................ 191 del_flg ................................................................ 177 del_isr ................................................................ 287 del_mbx ............................................................. 208 del_mpf .............................................................. 235 del_mpl .............................................................. 248 del_mtx .............................................................. 221 del_sem ............................................................. 166 del_tsk................................................................ 122 dis_dsp............................................................... 277 dis_int................................................................. 288 dis_tex................................................................ 156 dly_tsk................................................................ 149 ena_dsp ............................................................. 278 ena_int ............................................................... 289 ena_tex .............................................................. 157 exd_tsk............................................................... 128 ext_tsk................................................................ 127 frsm_tsk ............................................................. 148 fsnd_dtq ............................................................. 197 get_ims .............................................................. 291 get_mpf .............................................................. 238 get_mpl .............................................................. 251 get_pri ................................................................ 132 get_tid ................................................................ 274 get_tim ............................................................... 261 iact_tsk............................................................... 123 ical_svc .............................................................. 300 ican_act.............................................................. 125 ican_wup............................................................ 143 ichg_ims............................................................. 290 ichg_pri .............................................................. 130 iclr_flg................................................................. 179 ifrsm_tsk............................................................. 148 ifsnd_dtq ............................................................ 197 iget_ims.............................................................. 291 iget_pri ............................................................... 132 iget_tid ............................................................... 274 iget_tim .............................................................. 261 iloc_cpu.............................................................. 275 interrupt management function system call.............................................................. 108, 283 ipget_mpf ........................................................... 240 ipget_mpl ........................................................... 253 ipol_flg................................................................ 182 ipol_sem............................................................. 169 iprcv_dtq ............................................................ 200 iprcv_mbx........................................................... 213 ipsnd_dtq ........................................................... 194 appendix index user?s manual u14833ej2v0um 307 iras_tex............................................................... 154 iref_cyc............................................................... 270 iref_dtq ............................................................... 203 iref_flg ................................................................ 186 iref_mbx ............................................................. 216 iref_mpf .............................................................. 243 iref_mpl .............................................................. 257 iref_mtx .............................................................. 229 iref_sem ............................................................. 172 iref_tex................................................................ 159 iref_tsk................................................................ 133 iref_tst ................................................................ 136 irel_mpf .............................................................. 236 irel_mpl............................................................... 249 irel_wai ............................................................... 144 irot_rdq ............................................................... 273 irsm_tsk.............................................................. 147 iset_flg................................................................ 178 iset_tim............................................................... 260 isig_sem ............................................................. 167 isig_tim ............................................................... 262 isnd_mbx............................................................ 209 ista_cyc .............................................................. 268 ista_tsk ............................................................... 126 istp_cyc .............................................................. 269 isus_tsk .............................................................. 145 iunl_cpu.............................................................. 276 iwup_tsk ............................................................. 142 loc_cpu............................................................... 275 loc_mtx............................................................... 222 memory pool management function system call.............................................................. 108, 231 pget_mpf ............................................................ 240 pget_mpl ............................................................ 253 ploc_mtx............................................................. 224 pol_flg................................................................. 182 pol_sem.............................................................. 169 prcv_dtq ............................................................. 200 prcv_mbx............................................................ 213 psnd_dtq ............................................................ 194 ras_tex................................................................ 154 rcv_dtq ............................................................... 198 rcv_mbx.............................................................. 211 ref_cyc................................................................ 270 ref_dtq ................................................................ 203 ref_flg ................................................................. 186 ref_mbx .............................................................. 216 ref_mpf ............................................................... 243 ref_mpl................................................................257 ref_mtx................................................................229 ref_sem...............................................................172 ref_tex .................................................................159 ref_tsk .................................................................133 ref_tst..................................................................136 rel_mpf................................................................236 rel_mpl ................................................................249 rel_wai ................................................................144 rot_rdq ................................................................273 rsm_tsk ...............................................................147 set_flg .................................................................178 set_tim ................................................................260 sig_sem ..............................................................167 slp_tsk.................................................................139 snd_dtq ...............................................................192 snd_mbx .............................................................209 sns_ctx................................................................279 sns_dpn ..............................................................282 sns_dsp ..............................................................281 sns_loc................................................................280 sns_tex................................................................158 sta_cyc................................................................268 sta_tsk ................................................................126 stp_cyc................................................................269 sus_tsk................................................................145 synchronous communication management function service call ....................................108, 161 service call management function system call ..............................................................108, 297 system configuration management function service call ..................................................108, 292 system status management function system call ..............................................................108, 272 task exception processing function system call ..............................................................107, 151 task management function service call ......107, 117 task-associated synchronization function service call ..................................................107, 138 ter_tsk .................................................................129 tget_mpf..............................................................241 tget_mpl ..............................................................255 time management function service call......108, 259 tloc_mtx ..............................................................226 trcv_dtq ...............................................................201 trcv_mbx .............................................................214 tslp_tsk................................................................140 tsnd_dtq ..............................................................195 appendix index user?s manual u14833ej2v0um 308 twai_flg ............................................................... 184 twai_sem ............................................................ 170 unl_cpu ............................................................... 276 unl_mtx ............................................................... 228 vatt_idl ................................................................ 295 wai_flg ................................................................ 180 wai_sem ............................................................. 168 wup_tsk .............................................................. 142 service call management......................................... 22 service call management function system call.................................................................. 108, 297 cal_svc................................................................ 300 def_svc ............................................................... 298 ical_svc............................................................... 300 system clock ............................................................ 84 reading ................................................................ 84 setting .................................................................. 84 updating ............................................................... 84 system configuration management.................... 22, 96 system configuration management function service call ..................................................... 108, 292 def_exc ............................................................... 293 vatt_idl ................................................................ 295 system configurator ........................................... 17, 18 system pool ............................................................. 69 system status management..................................... 22 system status management function system call.................................................................. 108, 272 dis_dsp ............................................................... 277 ena_dsp.............................................................. 278 get_tid................................................................. 274 iget_tid ................................................................ 274 iloc_cpu .............................................................. 275 irot_rdq ............................................................... 273 iunl_cpu .............................................................. 276 loc_cpu ............................................................... 275 rot_rdq ................................................................ 273 sns_ctx ............................................................... 279 sns_dpn .............................................................. 282 sns_dsp .............................................................. 281 sns_loc ............................................................... 280 unl_cpu ............................................................... 276 [t] task.......................................................................... 16 activating .............................................. 34, 123, 126 creating ................................................ 34, 118, 121 delay .............................................................. 39, 85 deleting.................................................34, 122, 128 invalidating wakeup requests ..................... 125, 143 issuance of wakeup requests............................. 142 obtaining id number .......................................... 274 obtaining task information ......................... 133, 136 priority...................................................39, 130, 132 reactivating ......................................................... 35 releasing suspend state............................ 147, 148 state..................................................................... 36 state transition ..................................................... 38 terminating ...........................................35, 127, 128 time lapse waiting state..................................... 149 timeout .......................................................... 39, 85 waiting state ...................................................... 145 wakeup waiting state ................................. 139, 140 task context............................................................. 40 task debugger ................................................... 17, 18 task exception ......................................................... 41 enabled/disabled states ........................42, 156, 157 processing ........................................................... 21 request........................................................ 42, 154 task exception processing function system call ................................................................. 107, 151 def_tex ............................................................... 152 dis_tex................................................................ 156 ena_tex .............................................................. 157 iras_tex............................................................... 154 iref_tex ............................................................... 159 ras_tex ............................................................... 154 ref_tex ................................................................ 159 sns_tex............................................................... 158 task exception processing routine........................... 41 activating.............................................................. 43 defining........................................................ 41, 152 issuance of service calls ...................................... 45 obtaining information ......................................... 159 state................................................................... 158 terminating .......................................................... 44 task management ............................................. 21, 33 task management function service call ......... 107, 117 acre_tsk ............................................................. 121 act_tsk................................................................ 123 can_act .............................................................. 125 chg_pri ............................................................... 130 cre_tsk ............................................................... 118 del_tsk................................................................ 122 exd_tsk............................................................... 128 ext_tsk................................................................ 127 appendix index user?s manual u14833ej2v0um 309 get_pri ................................................................ 132 iact_tsk ............................................................... 123 ican_act.............................................................. 125 ichg_pri............................................................... 130 iget_pri ............................................................... 132 iref_tsk................................................................ 133 iref_tst ................................................................ 136 ista_tsk ............................................................... 126 ref_tsk ................................................................ 133 ref_tst ................................................................. 136 sta_tsk................................................................ 126 ter_tsk ................................................................ 129 task-associated synchronization ............................. 21 task-associated synchronization function service call ..................................................... 107, 138 can_wup............................................................. 143 dly_tsk ................................................................ 149 frsm_tsk.............................................................. 148 ican_wup ............................................................ 143 ifrsm_tsk............................................................. 148 irel_wai ............................................................... 144 irsm_tsk.............................................................. 147 isus_tsk .............................................................. 145 iwup_tsk ............................................................. 142 rel_wai ................................................................ 144 rsm_tsk............................................................... 147 slp_tsk ................................................................ 139 sus_tsk ............................................................... 145 tslp_tsk ............................................................... 140 wup_tsk .............................................................. 142 ter_tsk .................................................................... 129 tget_mpf................................................................. 241 tget_mpl ................................................................. 255 time obtaining............................................................ 261 setting ................................................................ 260 time elapse wait ................................................ 36, 39 time management ............................................. 22, 84 time management function service call......... 108, 259 acre_cyc............................................................. 266 cre_cyc............................................................... 263 del_cyc ............................................................... 267 get_tim ............................................................... 261 iget_tim............................................................... 261 iref_cyc............................................................... 270 iset_tim ...............................................................260 isig_tim................................................................262 ista_cyc...............................................................268 istp_cyc...............................................................269 ref_cyc ................................................................270 set_tim ................................................................260 sta_cyc................................................................268 stp_cyc................................................................269 time tick .................................................................262 timeout ....................................................................39 tloc_mtx ..................................................................226 trcv_dtq...................................................................201 trcv_mbx.................................................................214 tslp_tsk ...................................................................140 tsnd_dtq..................................................................195 twai_flg ...................................................................184 twai_sem ................................................................170 [u] unl_cpu...................................................................276 unl_mtx...................................................................228 user pool ............................................................69, 70 utility.........................................................................17 system configurator ........................................17, 18 task debugger ................................................17, 18 [v] variable-length memory block ..................................75 acquiring...............................................................77 returning ..............................................................79 variable-length memory block wait ...........................36 variable-length memory pool....................................75 acquiring memory blocks......................................81 creating ................................................75, 245, 247 deleting.........................................................75, 248 structure ...............................................................76 vatt_idl ....................................................................295 [w] wai_flg ....................................................................180 wai_sem .................................................................168 waiting......................................................................36 waiting-suspended...................................................37 wake-up wait ............................................................36 wup_tsk ..................................................................142 |
Price & Availability of RX4000V4
 |
|
|
|
|
All Rights Reserved © IC-ON-LINE 2003 - 2022 |
| [Add Bookmark] [Contact Us] [Link exchange] [Privacy policy] |
|
Mirror Sites : [www.datasheet.hk]
[www.maxim4u.com] [www.ic-on-line.cn]
[www.ic-on-line.com] [www.ic-on-line.net]
[www.alldatasheet.com.cn]
[www.gdcy.com]
[www.gdcy.net] |