 |
|
| 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: |
| hitachi vehicle operating system for SH-2 communication manual
2 please read the following carefully before you use this product . 1. if you use the enclosed software product and any related software products (hereafter referred to as product), before exporting or taking such product to other countries or states, you must comply with applicable export control laws and regulations of japan and other countries with jurisdiction and the applicable states and provinces within japan and such other countries. 2. please be advised that hitachi neither warrants nor grants licenses of any rights to the patents, copyrights, trademarks, or other intellectual property rights owned by hitachi or any third party for the use of the product, unless otherwise expressly granted to you by hitachi in a contract or other document including without limitation any warranty or license included in the users manual for the product (hereinafter referred to as contracts). please be further advised that hitachi bears no responsibility for problems that may arise with third partys rights, including intellectual property rights, in connection with the use of the product. 3. the product, its specifications and/or its description in the users manual are subject to change in the future without any prior notice. confirm that you have received the latest standards and/or specification for the product (including the users manual) before you make your final design, purchase or use. 4. please be advised that hitachi will not have any liability whatsoever for damages, including indirect or consequential damages, arising out of your use of the product (including the use based on the descriptions of the users manual). hitachi shall not be liable for any damages caused by any equipment or media used for delivery of the product. 5. the product is not designed for, and you may not use the product for, applications that demand especially high quality and reliability, or where its failure or malfunction may directly threaten human life or cause risk of bodily injury, such as equipment used for aerospace, aeronautics, nuclear power, combustion control, transportation, traffic, safety equipment or medical equipment for life support. if you have any questions regarding whether or not your intended use of the product is permitted by hitachi,, please contact your local hitachis sales office. 6. at the time of designing or planning your system using the product, please consider normally foreseeable failure rates or failure modes and employ sufficient systematic measures such as fail-safe systems so that the equipment incorporating the product does not cause any accident or other consequential damage due to operation of the product. 7. this manual and the product are copyrighted by hitachi. under any circumstances, you may not copy, analyze, reverse engineer, and/or modify, in whole or in part, the product, except to the extent expressly provided in the contracts. 8. you may not use or copy, in whole or in part, the users manual for the product without the prior written consent of hitachi, except to the extent expressly provided in the contracts. cautions 3 9. you may use the product on just one (1) computer. you may not transfer, lease or otherwise assign the product to any third party or parties, except to the extent expressly provided in the contracts. 10. please contact your local hitachis sales office for any questions regarding the product, any hitachi semiconductor products or any related products. 4 select the items you want to know from the following flowchart before reading this manual. overview chapter 1 introduction ye s no operating environments chapter 2 operating environments ye s no function ye s no system configuration ye s no message function no ye s section 3.2 messages network settings no ye s section 3.3 networks com architecture no ye s section 3.4 com architecture com operation ye s section 3.5 com control chapter 4 system configuration programming ye s no system services ye s api no ye s chapter 6 api descriptio n chapter 5 programming section 7.1 communication service return codes section 7.2 return code ids section 7.6 stack requirements 5 table of contents 1 introduction ..................................................................................................... 7 1.1 document overview ........................................................................................................... ...............................7 1.2 definitions and acronyms .................................................................................................... .............................7 1.3 com overview ................................................................................................................ ..................................7 1.4 features of this product .................................................................................................... ...............................9 2 operating environments............................................................................ 11 2.1 conformity version .......................................................................................................... ...............................11 2.2 conformance class ........................................................................................................... ...............................11 2.3 communication bus........................................................................................................... ..............................11 2.4 operating system............................................................................................................ .................................12 2.5 notes....................................................................................................................... ...........................................12 3 functions.......................................................................................................... 13 3.1 function overview........................................................................................................... ................................13 3.2 messages .................................................................................................................... .......................................13 3.2.1 message types ............................................................................................................. ............................13 3.2.2 message operations ........................................................................................................ .........................14 3.2.3 notification to application............................................................................................... ........................15 3.2.4 transmission modes........................................................................................................ .........................16 3.2.5 deadline monitoring ....................................................................................................... .........................20 3.2.6 message attributes ........................................................................................................ ...........................21 3.3 networks .................................................................................................................... .......................................22 3.3.1 hcan related parameters................................................................................................... ....................22 3.3.2 channel................................................................................................................... ..................................22 3.4 com architecture............................................................................................................ ...............................24 3.5 com control ................................................................................................................. ..................................25 3.5.1 start up .................................................................................................................. ..................................26 3.5.2 normal operation.......................................................................................................... ...........................26 3.5.3 shut down................................................................................................................. ...............................26 3.5.4 error handling............................................................................................................ ..............................27 4 system configuration................................................................................. 29 4.1 com application building .................................................................................................... .........................29 4.2 com configuration files..................................................................................................... ...........................30 4.2.1 evb ....................................................................................................................... ....................................31 4.2.2 hcan ...................................................................................................................... ...................................31 4.2.3 mcs....................................................................................................................... ....................................32 4.2.4 msg....................................................................................................................... ....................................32 5 programming................................................................................................... 33 6 5.1 com initialisation.......................................................................................................... .................................33 5.2 include files............................................................................................................... .......................................33 5.3 interrupts.................................................................................................................. ........................................34 5.3.1 hcan interrupts ........................................................................................................... ...........................34 5.3.2 interrupt priority levels ................................................................................................. ..........................34 5.4 user code................................................................................................................... .......................................35 5.4.1 initialisation processing................................................................................................. ...........................35 5.4.2 call-back functions ....................................................................................................... ..........................35 5.4.3 hcan isr .................................................................................................................. .............................36 5.5 interface to os ............................................................................................................. ....................................37 5.5.1 interrupt................................................................................................................. ...................................37 5.5.2 alarm and task ............................................................................................................ ............................37 5.6 registers................................................................................................................... .........................................37 5.7 stack....................................................................................................................... ...........................................37 5.8 calling a communication service from an assembler routine .................................................................38 5.9 notes on assembler use...................................................................................................... .............................38 6 api description ............................................................................................... 39 6.1 standard interface .......................................................................................................... .................................39 6.1.1 startcom .................................................................................................................. ...............................39 6.1.2 messageinit ............................................................................................................... ...............................40 6.1.3 sendmessage ............................................................................................................... .............................41 6.1.4 receivemessage ............................................................................................................ ...........................42 6.1.5 getmessagestatus .......................................................................................................... ..........................42 6.2 original interface functions................................................................................................ ...........................43 6.2.1 oc_sendmsgtonetper........................................................................................................ ....................43 6.2.2 oc_mixedtxeval ............................................................................................................ ........................44 7 appendix ............................................................................................................ 45 7.1 communication service return codes .......................................................................................... ................45 7.2 return code ids ............................................................................................................. .................................46 7.3 communication service calls ................................................................................................. ........................47 7.4 data types .................................................................................................................. ......................................47 7.5 maximum parameters .......................................................................................................... ...........................47 7.6 stack requirements .......................................................................................................... ...............................48 7 1 introduction 1.1 document overview this document defines the operation of the hitachi vehicle operating system communication v2.1 (hereafter referred to as com) which conforms to the osek/vdx (hereafter referred to as osek) open standard for communication, specification version 2.0a. this document is described on the assumption that osek specification is understood. read this document carefully and understand the contents of the following documents before using this product. - osek/vdx operating system, version 2.0 revision 1 (osek/vdx steering committee) - osek/vdx communication, version 2.0a (osek/vdx steering committee) - osek/vdx communication, version 2.1 revision 1 (osek/vdx steering committee) - release notes of this product - superh risc engine c/c++ compiler package manual - programming manual and hardware manual of the target sh microprocessor 1.2 definitions and acronyms api application program interface can controller area network ccc communication conformance class com communication for hitachi vehicle operating system dll data link layer ecu electronic control unit hcan hitachi controller area network hw hardware nm network management os operating system osek open systems and the corresponding interfaces for automotive electronics sw software vdx vehicle distributed executive 1.3 com overview the osek com is one of sw components specified by the osek standard. the other components are the operating system (os) and the network management module (nm). all three components provide functionality common to automotive applications. 8 figure 1.1 shows a system concept for automotive applications. in a car, there are a number of ecus exchanging information over a can network. each ecu is dedicated to the control of a certain mechanical component or subsystem in the car. for instance, ecu #1 may be the engine management controller, ecu #2 the gearbox controller, etc. higher level functionality in the car may be distributed over several ecus. figure 1.1 system concept for automotive applications ecu #1 hw sw ecu #2 hw sw ecu #n hw sw network 9 the internal structure of an ecu is shown in figure 1.2. figure 1.2 internal sw structure of an ecu the com controls the communication, both within the ecu, and between ecus. it provides the application with services for sending and receiving messages. the api is uniform for services exchanging messages within a node and between nodes. the com component can be implemented with compatibility, which is reflected by its communication conformance class (ccc). with this product, the ccc0 and ccc1 conformance classes are supported. ccc0 is the least resource demanding class and may be implemented without any os support. ccc1 requires the os. the cccs are provided in order to allow the communication component capabilities to be adapted to the communication need of the application. in order to gain access to the communication hw, the com makes use of the device drivers provided by the com-driver interface. this interface is not specified by the osek standard, and is thus be specific to each particular implementation. the can device is used in this product. 1.4 features of this product the features of this product are shown below: the com supports portability of application by providing a standardised application program interface that is defined according to the ansi c standard. an osek com implementation provides the following features for message exchange in applications. - task C task communication ecu communication hw application other peripheral hw communication hw drivers hw drivers other peripheral hw hw drivers os-com if os-nm if osek os os api osek com osek nm nm api com api nm-com if com-driver if network hw sw 10 - ecu C ecu communication - different transmission concepts: direct/periodical/mixed - communication deadline monitoring - notification by event setting and task activation note: periodical transmission and mixed transmission is provided by an original interface. please refer to section 3.2.4 for details. 11 2 operating environments 2.1 conformity version the com conforms to version 2.0a of the osek/vdx communication specification and version 2.1 revision 1 of the osek/vdx message transmission modes and deadline monitoring. 2.2 conformance class the function corresponding to the conformance class of osek communication specification is shown by 4 . table 2.1 conformance classes functions and services conformance classes ccc0 ccc1 transmission direct 4 4 concept periodical 4 mixed 4 communication deadline monitoring 4 messages unqueued 4 4 protocols uudt (undivided message) 4 4 services sendmessage 4 4 receivemessage 4 4 getmessagestatus 4 4 notification task activation 4 event setting 4 ccc0 provides the minimum services and functions to ecu-internal and inter-ecu communication. the os is not indispensable. ccc1 provides periodical transmission, mixed transmission, deadline monitoring, and notification mechanism. the os is indispensable. 2.3 communication bus the com is implemented for a communication bus of can (hereafter referred to as a bus). the com uses hcan as communication hw. the com does not operate on other communication hw and buses. 12 2.4 operating system the com can be used with the os of hitachi vehicle operating system. the com cannot be used by combining with other oss. 2.5 notes (1) the com includes drivers for the hcan devices that are built in the cpu. the drivers are not parts of the osek com standard, but do not remove them because they are required for the com operation. (2) refer to the help file of the com configurator for details on com configuration. (3) cannot be used in little endian. the com must be used in big endian. 13 3 functions 3.1 function overview the overview of the com function is shown in figure 3.1. figure 3.1 com function overview 3.2 messages 3.2.1 message types there are three types of messages as follows: local messages to net messages from net messages ecu task network task to net message (transmission) direct, condition, periodical deadline monitoring transmission completion com from net message (reception) notification (activatetask, setevent) deadline monitoring notification (activatetask, setevent) notification (activatetask,setevent) local message (transmission and reception) 14 3.2.1.1 local the local messages are sent and received within a single ecu, without being transmitted over the network. they are used to exchange information between different parts of a single application. 3.2.1.2 to net the to net messages are transmitted from the ecu to the network. they are received from the network by other ecus. these messages may be received locally by the sending the ecu. 3.2.1.3 from net the from net messages are received in the ecu from the network. they are transmitted from another ecu. 3.2.2 message operations the following message operations are possible: sending a message receiving a message reading the status of a message 3.2.2.1 send a message is transmitted via the sendmessage communication service. the transmission operation differs depending on the message types. local for local messages, transmission means copying message data from the application to a data area within the com. to net for to net messages, message data is copied from the application, as for local messages. in addition, the message data is sent to the network. the above description is relevant for a message that is transmitted in direct mode. please see section 3.2.4 for details on other transmission modes. 3.2.2.2 receive local this service copies the message data from a data stored within com message data area to the application. from net when receiving a message from a bus, the message data domain in com is immediately updated at the time. message data is copied to application from the message data in com at the time of receivemessage communication service call. reception from a bus is asynchronously processed with receivemessage communication service call. 15 3.2.2.3 get status the status of a message is obtained via the communication service getmessagestatus. the operation is applicable to messages of all types. the status expresses the following conditions of the message: in use status: locked (in use) or unlocked (not used) data value status: updated at least once or never updated in use the status is locked if com is using the message. the application cannot access the message when the status is locked. if the application calls a communication service, no action that alters the message will be performed and an error code indicating locked will be returned. when the message can be used, the status is unlocked. data value at com start-up, the status of all messages is never updated . as soon as a message has been sent from the application or received from the network, the status is changed into updated at least once. henceforth, it does not become never updated. 3.2.3 notification to application this function can use only ccc1. operations on messages are performed asynchronous to the application. a transmission to the network is requested by the application, but the transmission operation is not finished before the communication service returns to the application. in ccc1, the notification mechanism makes it possible for the com to inform the application when the transmission has been completed. a reception from the network is performed entirely without intervention of the application. the com receives a new message from the communication bus and stores it internally. these operations are: table 3.1 notification timing operation timing applies to message of type when issuing sendmessage local transmission of message when transmission of the message to a bus is completed to net reception of message when the reception of a message from bus is completed from net there are two kinds of notification methods. com sets an event when the operation is finished com activates a task when the operation is finished 16 3.2.4 transmission modes the com offers the following transmission modes: direct periodical (only ccc1) mixed (only ccc1) table 3.2 message transmission modes direct message transmission is requested by each call by issuing sendmessage. periodical (only ccc1) message transmission is requested by a dedicated task activated by a cyclic alarm. mixed (only ccc1) message transmission is requested by a dedicated task activated by a cyclic alarm. in addition, message transmission is conditionally. the condition is user-defined. 3.2.4.1 direct a transmitted message is unconditionally transmitted by issuing sendmessage. direct transmission is available for messages of types local and to net . 3.2.4.2 periodical when ccc1 is used, periodic transmission using alarm can be performed by combining with os. a transmission message is transmitted periodically. in this mode, the communication service sendmessage does not initiate the transmission to the net. it only updates the message data. the transmission to net is initiated by a periodically activated task. the task and the alarm must be defined by the user. the periodic task initiates transmission through a special send service that is not a formal part of the com api. this service is named oc_sendmsgtonetper. the user must add a call to this service in the periodic task. see chapter 6 for details. do not start periodical transmission until com initialisation is complete. this means that the earliest point in time to start the alarm is from the messageinit() function. periodical transmission is available for messages of type to net . 17 figure 3.2 periodical transmission the task a runs independently from the periodic task b. the latter requests a transmission to the network, each time it is activated. the message named foo is configured for periodical transmission mode. task a oc_sendmsgtonetper(foo) application com sendmessage(foo) periodic task b net tx request periodic message registration 18 3.2.4.3 mixed when ccc1 is used, mixed transmission using alarm can be performed by combining with os. a transmission message is transmitted periodically. in addition, sendmessage conditionally initiates a transmission to the network. a condition is evaluated each time sendmessage is called. if the condition evaluates to send, a transmission is initiated; otherwise not. in this mode, the communication service sendmessage 1. updates the message data 2. calls the evaluation original function oc_mixedtxeval() 3. requests a transmission to network if the evaluation function returned send. the evaluation performed in oc_mixedtxeval() is defined by application. the function must return a value that tells com whether to send the message or not. see section 6 for details. transmissions to net are initiated by a periodically activated task. the task and the alarm must be defined by the user. the periodic task initiates transmission through a special send service that is not a formal part of the com api. this service is named oc_sendmsgtonetper. the user must add a call to this service in the periodic task. do not start periodical transmission until com initialisation is complete. this means that the earliest point in time to start the alarm is from the messageinit() function. mixed transmission is available for messages of type to net . 19 figure 3.3 mixed transmission task a oc_sendmsgtonetper(foo) application com sendmessage(foo) periodic task b net tx re q uest perio- dical ? yes oc_mixedtxeval(foo) user processing return value (transmission request flag) no net tx re q uest no tx mix- ed? send ? no no yes yes register p eriodic 20 task a runs independently from the periodic task b. task a calls sendmessage that conditionally requests a transmission to the network. task b requests a transmission to the network, each time it is activated. the message named foo is configured for mixed transmission mode. 3.2.5 deadline monitoring when ccc1 is used, the deadline monitoring using alarm can be performed by combining with os. deadline monitoring means that a deadline is monitored. it can be applied regardless of whether the message is configured for transmission or reception. for transmission, this means that an initiated transmission to the net must be completed within a certain time frame. if not, an alarm expires and as a consequence, a task is activated or an event is set. for reception, a message must be received within a certain time frame. the start of this time frame is the point in time when the previous message was received. if the deadline is broken, an alarm expires and as a consequence, a task is activated or an event is set. user must define the alarm, the task, and the event. deadline monitoring is applicable to messages of type to net or from net . (1) transmission an alarm is started just before com issues a transmission request to the network. depending on the transmission mode, this is done in either of sendmessage oc_sendmsgtonetper the alarm is cancelled automatically when com receives a transmission confirmation from the network. if a confirmation does not occur within the alarm time, the alarm will expire. deadline monitoring may be used in both direct, periodical and mixed transmission modes. (2) reception start of the deadline monitoring of reception is possible by starting the alarm from a task or by receiving the message that had once specified deadline monitoring. in reception monitoring, the alarm is never cancelled; only restarted automatically. do not start reception monitoring until com initialisation is complete. this means that the earliest point in time to start the alarm is from the messageinit() function. the alarm is restarted each time com receives a reception indication from the network. if an indication does not occur within the alarm time, the alarm will expire. 21 3.2.6 message attributes the following attributes must be configured for each message. all configurations are done with the com configurator. please see the com configurator help file for details. message name (the character string which starts with an alphabetic character or an underline, followed by zero or more alphabetic characters, underlines, or numbers. a maximum of 32 characters.) data length (a maximum of 8 bytes) message type - local - to net - from net notification function - none - event mask (event setting) - task id (task id for task activation or event setting) transmission mode - direct - periodic (only ccc1) - mixed (only ccc1) deadline monitoring - alarm id - expiration time hcan - mailbox number (0 to 15) - bit length of can id (11 or 29 bits) - can id please note the following. (1) do not set up multiple messages of the same name. (2) do not set up multiple same can ids. 22 3.3 networks 3.3.1 hcan related parameters each net message has the following settings related to the hcan: mailbox can id (1) mailbox data exchange between a message and the can net is done through a mailbox. this is a data area within the hcan device that holds message data and control information. each net message must use a mailbox. the following mailboxes exist in an hcan device mailbox for either transmission or reception (mailboxes 1-15) mailbox only for reception (mailbox 0) mailboxes 1-15 these mailboxes can be used for to net , or from net . multiple messages must not be assigned to the same mailbox. mailbox 0 only messages of type from net may use this mailbox. it is intended to receive a group of messages. during reception processing, reception of two or more messages in the mailbox 0 causes as an error, and is not processed. (2) can id each message has a unique identifier (can id) that is used to identify the message on the can bus. the can id may consist of either 11 or 29 bits. 11 bits mean that 11 standard id bits are used in the can bus frame. 29 bits mean that 18 extended and 11 standard id bits are used. 3.3.2 channel com can treat two separate hcan buses by one ecu. hcan has the following parameters. all configurations are done with the com configurator. please see the hardware manual and the com configurator help file for details. mailbox 0 - bit length of can id (11 or 29 bits) - can id - lafm (local acceptance filter mask for mailbox 0) operation - transmission priority (mailbox order or id order) - bit sample point (1 point or 3 points) bit configuration - baud-rate prescaler (brp) - time segment 1 (tseg1) - time segment 2 (tesg2) 23 - maximum bit synchronisation width (sjw) interrupts - for each hcan interrupt source: enabled/disabled restriction of a setting of a bit configuration is shown below. tseg1 > tseg2 >= sjw (sjw = 1 to 4) 3 + tseg1 + tseg 2= 8 to25 time quanta tseg2 > b'001 (brp = b'000000) tseg2 > b'000 (brp > b'000000) refer to the hardware manual for details. 24 3.4 com architecture the com is divided into two main parts that are termed packages. message package net package the message package provides the com api. the net package transmits and receives the hcan network. to net and from net messages require both packages. figure 3.4 com architecture message package application net package bus hw com 25 3.5 com control the processing procedure of com is shown below. figure 3.5 com processing procedure startcom calling interrupt initialisation startos calling (os in use) message transmission hardware initialisation reset message reception ecu internal and external application (task) ecu internal and external initialisation processing 26 3.5.1 start up the start-up method of com is 1. hw reset 2. hw initialisation with interrupts disabled 3. call startcom communication service 4. interrupt initialisation 5. call startos system service, if os is used the application must provide the code for steps 2 and 4. this product provides those codes as sample (see section 4.2). during start up, no messages may be transmitted or received. 3.5.2 normal operation com runs in normal mode as soon as start up is finished. message transmission and reception can be performed in this state. the flow of transmission and reception is shown below. 3.5.2.1 message transmission 1. application calls sendmessage. 2. sendmessage copies message data from application to data area in com. 3. for a net message, sendmessage starts net transmission. 4. sendmessage returns. 5. the message is sent from the hcan to the can bus. 6. when transmission is finished, a slot empty interrupt occurs. 7. the isr performs a call to the message package and net package of com. this transmission confirmation makes com aware that the transmission operation is finished. 8. the isr returns. 3.5.2.2 message reception in application 1. application calls receivemessage. 2. receivemessage copies message data from data area in com to application. 3. receivemessage returns. 3.5.2.3 message reception from network 1. when message is received from the bus, a received-message interrupt occurs. 2. the isr performs a call to the message package and net package of com. 3. the com copies message data from the hcan to the data area in com. 4. the isr returns. 3.5.3 shut down the com cannot be shut down. when initialising com, issue the startcom communication service again. 27 3.5.4 error handling the following error mechanisms are provided: error codes returned from communication service error interrupts related to the hcan device exceptions 3.5.4.1 error codes the com can operate in one of the following two error modes. standard status mode extended status mode the com with extended status is used in the development and debugging of applications; the com with standard status is used in fully debugged systems. section 7.1 gives a summary of the error codes returned by communication services. 28 3.5.4.2 error interrupt the hcan module may generate interrupts as described below: table 3.3 interrupts from the hcan module interrupt cause default setting configurator setting received message available (reserved for com) impossible unread mail available (reserved for com, user code can be added) impossible transmission mailbox empty available (reserved for com) impossible reset available (can be changed by the user) impossible overload frame unavailable possible bus-off unavailable possible error passive unavailable possible bus receive overload warning unavailable possible bus transmit overload warning unavailable possible remote frame request unavailable possible bus operation request unavailable possible all interrupts that are not reserved by com may be used by the application. the com provides default handlers for all these interrupts. if required, it is possible to add codes. refer to section 5.3 for details. 3.5.4.3 exception com does not include any exception handling features. if os is not used, exceptions must be handled by the application. if os is used, exceptions will be handled by the os. please refer to the operating system manual for details. 29 4 system configuration 4.1 com application building figure 4.1 shows the building process of a com application. figure 4.1 building process of a com application. os configuration files, libraries com confi g urator com configuration files, libraries com configuration files, libraries application program files compiler assembler linkage editor os confi g urator user code addition (see section 5.4) os configuration definition files user input load module :file :tool com configuration definition files 30 the configurator generates the configuration files and the library files determined by the user input or configuration definition file. along with the application program files, these files are compiled, assembled and linked to generate the load module. refer to help files of os and com configurator for information on how to generate configuration files. please refer to the operating system manual on the details of os configuration file. 4.2 com configuration files configuration files are divided into the following file groups: app sample application files. com com libraries, com objects, com configuration files and sample files generated by the com configurator. os sample os configuration files generated by the os configurator. the com group may be further subdivided into: evb sample files related to the target hw set-up. hcan hcan driver files. mcs sample cpu initialisation and section initialisation files. msg message package files. net net package files. 31 if required, rewrite the following files. note that they are overwritten whenever these files generate a com configuration file by com configurator. 4.2.1 evb table 4.1 evb group file description int_hndl.c interrupt handler ma_cpu.c hardware initialisation processing ma_cpu.h hardware initialisation header ma_int.c interrupt initialisation ma_int.h interrupt initialisation header ma_io.c port setting ma_io.h port setting header ma_pfc.c pin function controller (pfc) setting ma_pfc.h pin function controller (pfc) setting header makeapp.h macro 4.2.2 hcan table 4.2 hcan group file description ma_hcan1.c hcan channel 0 processing ma_hcan1.h hcan channel 0 header ma_hcan2.c hcan channel 1 processing ma_hcan2.h hcan channel 1 header mac.h hcan macro macan1.h hcan channel 0 macro macan2.h hcan channel 1 macro 32 4.2.3 mcs table 4.3 mcs group file description dbsct.src section initialisation definition hwsetup.src hardware initialisation initsct.c section initialisation intprg.src common interrupt program resetprg.src reset processing stacksct.src reset stack definition vect.inc vector table include file vecttbl.src vector table definition 4.2.4 msg table 4.4 msg group file description occallb.c call function for message initialisation and mixed transmission ocos.h com interrupt level setting 33 5 programming the programming method of com application is shown below. 5.1 com initialisation for com initialisation, call services and functions according to the procedure shown below. com interrupt level must be maintained until com initialisation is completed. if not using os, startos system service call is not required. /*--- hw init ---*/ ma_init_pfc(); /* pin function controller (pfc) initialisation */ ma_init_cpu(); /* hardware initialisation */ ma_init_io(); /* port initialisation */ /*--- com init ---*/ startcom(); /* com initialisation */ ma_init_int(); /* interrupt initialisation */ /*--- os init ---*/ startos( application mode ); /* os initialisation */ 5.2 include files the program which uses a message must include the ocmsg.h file. 34 5.3 interrupts 5.3.1 hcan interrupts there are four vectors in each hcan as follows, and each interrupt is divided into groups. each isr must be defined in a vector table. in ccc0 with os, register as category 1 interrupt. in ccc1, register as category 2 interrupt. in ccc1, add _isr at the end of isr name because hcan interrupt handler is called via interrupt preamble of os. hcan isr name is shown in table 5.1. ers vector - error passive interrupt - bus off interrupt ovr vector - reset interrupt - remote frame request interrupt - bus transmit overload warning interrupt - bus receive overload warning interrupt - overload frame interrupt - unread mail interrupt - bus operation request interrupt rm vector - received message interrupt sle vector - transmission mailbox empty interrupt table 5.1 hcan isr name vector ccc0 ccc1 ers ma_inthandler_ers_hcan x ma_inthandler_ers_hcan x _isr ovr ma_inthandler_ovr_hcan x ma_inthandler_ovr_hcan x _isr rm ma_inthandler_rm_hcan x ma_inthandler_rm_hcan x _isr sle ma_inthandler_sle_hcan x ma_inthandler_sle_hcan x _isr note: x is 1 (for hcan channel 0) or 2 (for hcan channel 1). 5.3.2 interrupt priority levels com interrupt level the highest interrupt priority level in the program which uses communication service must be set as a com interrupt level. when the os is used by ccc0, the com interrupt level must be set higher than the os interrupt level. in ccc1, the os interrupt level is set to the com interrupt 35 level. communication service must not be issued from a program higher than the com interrupt level. refer to ocos.h for the setting method of com interrupt level. hcan interrupt level both channels 0 and 1 of the hcan module should be set to the same interrupt priority level. the hcan interrupt level should be set to the same com interrupt level. refer to ma_int.c provided as a sample for the setting method. 5.4 user code the com configuration file is generated by the com configurator. however, the user can add some user codes to the following processing: initialisation processing call-back functions hcan interrupts that are not reserved by com 5.4.1 initialisation processing ma_init_pfc() this function exists in ma_pfc.c . this function is called from main.c provided as a sample. ma_init_cpu() this function exists in ma_cpu.c . this function is called from main.c provided as a sample. ma_init_io() this function exists in ma_io.c . this function is called from main.c provided as a sample. ma_init_int() this function exists in ma_int.c . this function is called from main.c provided as a sample. 5.4.2 call-back functions messageinit() this function exists in occallb.c . this function is called from the startcom service. refer to section 6.1.2 for details. oc_mixedtxeval() this function exists in occallb.c . this function is called from within com when a message is transmitted in the mixed transmission mode. refer to section 6.2.2 for details. 36 5.4.3 hcan isr the user can add codes that handle interrupts from the hcan. for details on interrupt causes, refer to the hardware manual. table 5.2 user code placement for hcan interrupts. interrupt cause add user code in unread mail int_hndl.c: my_unreadmailhandler1() (for hcan channel 0) my_unreadmailhandler2() (for hcan channel 1) reset int_hndl.c: my_poweruphandler1() (for hcan channel 0) my_poweruphandler2() (for hcan channel 1) overload frame macan1.h: ma_overload_frame_usercode1 macro (for hcan channel 0) macan2.h: ma_overload_frame_usercode2 macro (for hcan channel 1) bus-off macan1.h: ma_bus_off_usercode1 macro (for hcan channel 0) macan2.h: ma_bus_off_usercode2 macro (for hcan channel 1) error passive macan1.h: ma_error_passive_usercode1 macro (for hcan channel 0) macan2.h: ma_error_passive_usercode2 macro (for hcan channel 1) bus receive overload warning macan1.h: ma_rec_warning_usercode1 macro (for hcan channel 0) macan2.h: ma_rec_warning_usercode2 macro (for hcan channel 1) bus transmit overload warning macan1.h: ma_tec_warning_usercode1 macro (for hcan channel 0) macan2.h: ma_tec_warning_usercode2 macro (for hcan channel 1) bus operation request macan1.h: ma_wu_bus_actif_usercode1 macro (for hcan channel 0) macan2.h: ma_wu_bus_actif_usercode2 macro (for hcan channel 1) 37 5.5 interface to os 5.5.1 interrupt according to the following category rule, interrupt which uses com (communication service) must be registered into os configurator. table 5.3 category rule interrupt ccc0 ccc1 hcan interrupt category 1 category 2 other interrupts category 1 or 2 category 1 or 2 5.5.2 alarm and task cyclic alarm and task for a periodic and the mixed transmission modes must be prepared by user application. the task needs to be registered into os configurator. 5.6 registers the values of general registers r0-r7, fr0-fr11, fpul, and fpscr 1 cannot be guaranteed in the communication service. if you use these registers after a communication service call, they must be saved beforehand. 5.7 stack the com never changes the stack. therefore, add stack size of each service to the stack of the program which calls communication service. moreover, add the interrupt stack size of each interrupt to the interrupt stack. refer to section 7.6 for details on stack size. 1 the fr0-fr11, fpul, and fpscr registers are only valid for the processor with floating point unit (fpu). 38 5.8 calling a communication service from an assembler routine communication services may be called from assembler routines. in this case, the application programmer must branch to the start address of each communication service by the jsr command. follow the rules governing parameter area allocation. for the type of a parameter, refer to table 7.4 data types, and c-language header file of msg group of configuration files. table 5.4 argument convention register argument number r4 first argument r5 second argument r6 third argument r7 fourth argument general register r0 is used for the return value. the values of general registers r0-r7, pr, fr0-fr11, fpul, and fpscr cannot be guaranteed before and after calling the communication service. if you use these registers, they must be saved before the call, and restored after the call. 5.9 notes on assembler use when the com is initialised from an assembler routine, call each initialisation processing of a ma_init_pfc() function, etc. by jsr. although assembly language can describe evb and mcs groups of a configuration file, be sure to describe hcan, msg, and net groups in the c language. 39 6 api description the interface of the communication service is described below. refer to section 5.8 on an assembler interface. 6.1 standard interface 6.1.1 startcom syntax: statustype startcom(void) parameter (in): none parameter (out): none description: com is initialised. in the end, this service calls call-back function messageinit(). error status: standard no error: e_ok extended (code added as extended status) none 40 6.1.2 messageinit syntax: statustype messageinit(void) parameter (in): none parameter (out): none description: com calls this function automatically by startcom service. this function is provided by the occallb.c file. rewrite if needed. error status: standard no error: e_ok initialise failed: e_com_sys_msg_init_failed extended (code added as extended status) none 41 6.1.3 sendmessage syntax: statustype sendmessage(oc_symbolicnamet 42 6.1.4 receivemessage syntax: statustype receivemessage(oc_symbolicnamet 43 6.2 original interface functions in addition to the communication services defined by the osek com specification, the original interface is provided. 6.2.1 oc_sendmsgtonetper syntax: enum oc_ilopresulte oc_sendmsgtonetper(oc_symbolicnamet 44 6.2.2 oc_mixedtxeval syntax: oc_callbstatust oc_mixedtxeval(oc_symbolicnamet 45 7 appendix 7.1 communication service return codes table 7.1 communication service return codes communication service standard error status code added in extended error status startcom e_ok --- messageinit e_ok e_com_sys_msg_init_failed* --- sendmessage e_ok e_com_locked e_com_sys_event_setting_denied* e_com_sys_task_activation_denied* e_com_sys_alarm_start_denied* e_com_sys_net_tx_denied* e_com_id receivemessage e_ok e_com_nomsg e_com_id getmessagestatus e_ok e_com_nomsg e_com_locked e_com_id oc_sendmsgtonetper* oc_ilopresok * oc_ilopresmsgdsinuse * oc_ilopreserror * oc_ilopresnettxdenied * oc_ilopreserror * oc_mixedtxeval* oc_txcondissendd * oc_txcondisnosendd * --- note: *: original function 46 7.2 return code ids table 7.2 return code ids return code description id e_ok no error 0 (h0) e_com_id invalid message 1 (h1) e_com_limit reserved (not used) 2 (h2) e_com_nomsg after initialising message data, it has not updated 3 (h3) e_com_locked message is locked 4 (h4) e_com_sys_net_tx_denied* transmission was denied by the net package 64 (h40) e_com_sys_event_setting_denied* an event could not be set as notification 65 (h41) e_com_sys_task_activation_denied* a task could not be started as notification 66 (h42) e_com_sys_alarm_start_denied* an alarm for deadline monitoring could not be started 67 (h43) e_com_sys_unexpected_state* reserved (not used) 68 (h44) e_com_sys_msg_init_failed* initialise failed 69 (h45) oc_ilopresok* no error 256(h100) oc_ilopreserror* invalid message alarm for deadline monitoring could not be started 257 (h101) oc_ilopresmsgdsinuse* message is locked 258 (h102) oc_ilopresnettxdenied* transmission was denied by the net package 259 (h103) oc_ilopresmsgunexpectedstate* reserved (not used) 260 (h104) oc_iloprestonetmsgnotsupported* reserved (not used) 261 (h105) oc_ilopresfrnetmsgnotsupported* reserved (not used) 262 (h106) oc_txcondissendd* initiate a transmission to net 1 (h1) oc_txcondisnosendd* do not initiate a transmission to net 2 (h2) note: *: original function 47 7.3 communication service calls in calling a program, yes shows communication service which can be issued. "---" means that operation is not guaranteed. table 7.3 communication service calls ccc1 communication service before com initial- isation (indispens- able) ccc0/ ccc1 ccc0 task isr error hook pretask hook posttas k hook startu p hook shutdown hook startcom yes --- --- --- --- --- --- --- --- sendmessage --- yes yes yes --- --- --- --- --- receivemessage --- yes yes yes yes --- --- --- --- getmessagestatus --- yes yes yes yes --- --- --- --- oc_sendmsgtonetper* --- --- yes --- --- --- --- --- --- note: *: original function 7.4 data types table 7.4 data types name type(size) description statustype unsigned long (4 bytes) return value oc_symbolicnamet struct oc_msghandles * (4 bytes) message name oc_datareft void * (4 bytes) address or pointer for message data oc_ilopresulte enum (4 bytes) return value oc_callbstatust unsigned char (1 byte) return value 7.5 maximum parameters table 7.5 maximum parameters item limit max number of nets per com * 2 max number of local messages 1000 max number of to net messages per net * 15 max number of from net messages per net * 31 max number of messages for mailbox 0 * 16 max number of messages for mailboxes 1-15 * 1 max number of messages per net * 31 note: *: they are based on hardware specification. 48 7.6 stack requirements table 7.6 stack requirements service, isr stack usage [byte] startcom 72 + stack used with messageinit() function (default is 0) local message 32 direct 104 periodical 32 sendmessage to net message mixed 104 + stack used with oc_mixedtxeval() function (default is 0) receivemessage 0 getmessagestatus 0 oc_sendmsgtonetper to net message periodical 88 isr of receive message interrupt from hcan 192 isr of transmit mailbox empty interrupt from hcan 176 49 hitachi vehicle operating system for SH-2 communication manual publication date: 1 st edition, may 2001 copyright (c) hitachi, ltd., 1999. all rights reserved. printed in japan. |
Price & Availability of SH-2
 |
|
|
|
|
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] |