Renesas V.1.00 User manual

Revision Date: Mar. 17, 2008

Renesas Microcomputer Development Environment System

Rev.1.01

REJ10J1822-0101

Stub Generator

V.1.00

User’s Manual

1. This document is provided for reference purposes only so that Renesas customers may select the appropriate

Renesas products for their use. Renesas neither makes warranties or representations with respect to the

accuracy or completeness of the information contained in this document nor grants any license to any

intellectual property rights or any other rights of Renesas or any third party with respect to the information in

this document.

2. Renesas shall have no liability for damages or infringement of any intellectual property or other rights arising

out of the use of any information in this document, including, but not limited to, product data, diagrams, charts,

programs, algorithms, and application circuit examples.

3. You should not use the products or the technology described in this document for the purpose of military

applications such as the development of weapons of mass destruction or for the purpose of any other military

use. When exporting the products or technology described herein, you should follow the applicable export

control laws and regulations, and procedures required by such laws and regulations.

4. All information included in this document such as product data, diagrams, charts, programs, algorithms, and

application circuit examples, is current as of the date this document is issued. Such information, however, is

subject to change without any prior notice. Before purchasing or using any Renesas products listed in this

document, please confirm the latest product information with a Renesas sales office. Also, please pay regular

and careful attention to additional and different information to be disclosed by Renesas such as that disclosed

through our website. (http://www.renesas.com )

5. Renesas has used reasonable care in compiling the information included in this document, but Renesas

assumes no liability whatsoever for any damages incurred as a result of errors or omissions in the information

included in this document.

6. When using or otherwise relying on the information in this document, you should evaluate the information in

light of the total system before deciding about the applicability of such information to the intended application.

Renesas makes no representations, warranties or guaranties regarding the suitability of its products for any

particular application and specifically disclaims any liability arising out of the application and use of the

information in this document or Renesas products.

7. With the exception of products specified by Renesas as suitable for automobile applications, Renesas

products are not designed, manufactured or tested for applications or otherwise in systems the failure or

malfunction of which may cause a direct threat to human life or create a risk of human injury or which require

especially high quality and reliability such as safety systems, or equipment or systems for transportation and

traffic, healthcare, combustion control, aerospace and aeronautics, nuclear power, or undersea communication

transmission. If you are considering the use of our products for such purposes, please contact a Renesas

sales office beforehand. Renesas shall have no liability for damages arising out of the uses set forth above.

8. Notwithstanding the preceding paragraph, you should not use Renesas products for the purposes listed below:

(1) artificial life support devices or systems

(2) surgical implantations

(3) healthcare intervention (e.g., excision, administration of medication, etc.)

(4) any other purposes that pose a direct threat to human life

Renesas shall have no liability for damages arising out of the uses set forth in the above and purchasers who

elect to use Renesas products in any of the foregoing applications shall indemnify and hold harmless Renesas

Technology Corp., its affiliated companies and their officers, directors, and employees against any and all

damages arising out of such applications.

9. You should use the products described herein within the range specified by Renesas, especially with respect

to the maximum rating, operating supply voltage range, movement power voltage range, heat radiation

characteristics, installation and other product characteristics. Renesas shall have no liability for malfunctions or

damages arising out of the use of Renesas products beyond such specified ranges.

10. Although Renesas endeavors to improve the quality and reliability of its products, IC products have specific

characteristics such as the occurrence of failure at a certain rate and malfunctions under certain use

conditions. Please be sure to implement safety measures to guard against the possibility of physical injury, and

injury or damage caused by fire in the event of the failure of a Renesas product, such as safety design for

hardware and software including but not limited to redundancy, fire control and malfunction prevention,

appropriate treatment for aging degradation or any other applicable measures. Among others, since the

evaluation of microcomputer software alone is very difficult, please evaluate the safety of the final products or

system manufactured by you.

11. In case Renesas products listed in this document are detached from the products to which the Renesas

products are attached or affixed, the risk of accident such as swallowing by infants and small children is very

high. You should implement safety measures so that Renesas products may not be easily detached from your

products. Renesas shall have no liability for damages arising out of such detachment.

12. This document may not be reproduced or duplicated, in any form, in whole or in part, without prior written

approval from Renesas.

13. Please contact a Renesas sales office if you have any questions regarding the information contained in this

document, Renesas semiconductor products, or if you have any other inquiries.

Notes regarding these materials

i

Preface

This manual describes how to use the stub generator. Read this manual and understand it well

before using the stub generator.

Notes on Descriptions

RPCGEN Abbreviation for the stub generator

Prefix Prefix 0x indicates a hexadecimal number. Numbers with no prefix are

decimal.

\ ‘\’ is the directory delimiter.

[Menu -> Menu item] ‘->’ leads to the menu item (e.g. File -> Save).

$(xxxx) Custom placeholder in the High-performance Embedded Workshop

ii

Trademarks

All trademarks and registered trademarks belong to their respective owners.

1. TRON is an acronym formed from "The Real Time Operating system Nucleus". ITRON is

short for "Industrial TRON" and µITRON is short for "Micro Industrial TRON".

TRON, ITRON, and µITRON are the names of computer specifications and do not indicate

specific products or groups of products.

The µITRON4.0 specification is an open realtime-kernel specification defined by the TRON

Association. The µITRON4.0 specification can be downloaded from the TRON Association

homepage (

http://www.assoc.tron.org).

The copyright of the µITRON specification belongs to the TRON Association.

2. Microsoft® and Windows® are registered trademarks of Microsoft Corporation in the United

States and/or other countries. The formal name of Windows® is Microsoft Windows Operating

System.

3. All other product names are trademarks or registered trademarks of the respective holders.

Renesas Technology Homepage

Various support information are available on the following Renesas Technology homepage:

http://www.renesas.com/en/tools/

iii

Contents

Section 1 Overview..................................................................................................1

1.1 Overview............................................................................................................................... 1

1.2 Operating Environment......................................................................................................... 2

Section 2 Installation................................................................................................3

2.1 Downloading......................................................................................................................... 3

2.2 Installing RPCGEN...............................................................................................................3

Section 3 Functions and Files Generated by RPCGEN...........................................5

3.1 Functions Generated by RPCGEN........................................................................................ 5

3.1.1 Client..................................................................................................................... 6

3.1.2 Server.................................................................................................................... 6

3.2 Files Generated by RPCGEN................................................................................................ 7

Section 4 Executing RPCGEN ................................................................................9

4.1 Executing RPCGEN ............................................................................................................. 9

4.2 Options................................................................................................................................ 10

4.2.1 PUBI ................................................................................................................... 10

4.2.2 CLNTS................................................................................................................ 10

4.2.3 CLNTI................................................................................................................. 10

4.2.4 SVRS .................................................................................................................. 11

4.2.5 SVRI ................................................................................................................... 11

4.3 Executing RPCGEN as a Build Phase in the High-performance Embedded Workshop..... 12

Section 5 Specifications of a Config File ..............................................................23

5.1 Definition............................................................................................................................ 23

5.2 Comments ........................................................................................................................... 24

5.3 File Locations ..................................................................................................................... 25

5.3.1 PUB_INCPATH ................................................................................................. 25

5.3.2 CLNT_SOURCEPATH...................................................................................... 26

5.3.3 CLNT_INCPATH............................................................................................... 26

5.3.4 SVR_SOURCEPATH......................................................................................... 27

5.3.5 SVR_INCPATH ................................................................................................. 27

5.4 Controlling the Output of #include Directives.................................................................... 28

5.4.1 Order of #Include Directives............................................................................... 29

5.4.2 GLOBAL_INCFILE ........................................................................................... 30

iv

5.4.3 CLNT_INCFILE................................................................................................. 30

5.4.4 SVR_INCFILE ................................................................................................... 31

5.5 Server Information..............................................................................................................32

5.5.1 SVR_NAME....................................................................................................... 32

5.5.2 SVR_ID .............................................................................................................. 33

5.5.3 SVR_VERSION ................................................................................................. 34

5.5.4 SVR_NOINIT..................................................................................................... 34

5.5.5 SVR_NOSTUBTBL ........................................................................................... 35

5.5.6 SVR_NOSHUTDOWN ...................................................................................... 36

5.5.7 SVR_STATIC..................................................................................................... 37

5.5.8 SVR_AUTH ....................................................................................................... 38

5.5.9 SVR_SECTION.................................................................................................. 42

5.6 Client Information ..............................................................................................................43

5.6.1 CLNT_NOINIT .................................................................................................. 43

5.6.2 CLNT_NOSHUTDOWN ................................................................................... 44

5.6.3 CLNT_CALLCHK ............................................................................................. 45

5.6.4 CLNT_SECTION ............................................................................................... 46

5.7 Server Functions ................................................................................................................. 47

5.7.1 RPC_FUNC ........................................................................................................ 47

Section 6 Definitions of Server Functions.............................................................49

6.1 Format................................................................................................................................. 49

6.2 Function-Type Directives ................................................................................................... 52

6.2.1 Function with a Return Value............................................................................. 52

6.2.2 Function without a Return Value........................................................................ 53

6.2.3 When the Return Value is not Representable as a 4-Byte Integer ...................... 54

6.3 Function Names..................................................................................................................55

6.4 Parameters........................................................................................................................... 56

6.5 Keywords for Input/Output................................................................................................. 57

6.5.1 IN (Input)............................................................................................................ 57

6.5.2 OUT (Output) ..................................................................................................... 58

6.5.3 INOUT (Input and Output) ................................................................................. 59

6.5.4 REF (Passing by Reference)............................................................................... 60

6.5.5 DESC (Specified Parameter is not Passed from the Client to the Server) .......... 62

6.6 Keywords for Data Types................................................................................................... 63

6.6.1 DFLT (Default)................................................................................................... 63

6.6.2 STR (String)........................................................................................................ 64

6.6.3 PTR (Pointer)...................................................................................................... 65

6.6.4 ARY (Array)....................................................................................................... 66

6.6.5 COUNT (Number of Elements in an Array)....................................................... 67

v

6.7 Optional Keywords............................................................................................................. 83

6.7.1 SVRSTUB (Server Stub) .................................................................................... 84

6.7.2 SVRFUNC (Server Function Name) .................................................................. 85

6.7.3 CLNTSTUB (Client Stub) .................................................................................. 86

6.7.4 UNACK (Asynchronous Call) ............................................................................ 87

6.7.5 CLNTCOPYCBK (RPC Call by rpc_call_copycbk())........................................ 88

Section 7 Server Functions Not Supported by RPCGEN ......................................89

7.1 Parameter ............................................................................................................................ 89

7.2 Return Value....................................................................................................................... 91

Section 8 Application Interface .............................................................................93

8.1 Client-Stub Functions Generated by RPCGEN .................................................................. 93

8.2 Server-Stub Functions Generated by RPCGEN.................................................................. 95

8.3 Server-Initialization Function ............................................................................................. 96

8.4 Server-Stub Function Table ................................................................................................ 97

8.5 Server-Shutdown Function ................................................................................................. 99

8.6 Client-Initialization Function............................................................................................ 100

8.7 Client-Shutdown Function................................................................................................ 101

8.8 rpc_retval_adr() ................................................................................................................ 102

8.9 <Config file>_public.h...................................................................................................... 104

8.10 Local Variables Used in the Source Code Created by RPCGEN...................................... 104

Section 9 Notes ....................................................................................................105

Section 10 Error Messages...................................................................................107

10.1 Format............................................................................................................................... 107

10.2 General.............................................................................................................................. 108

10.3 Definition Errors (other than RPC_FUNC) ...................................................................... 108

10.4 Definition Errors (RPC_FUNC) ....................................................................................... 108

Section 11 Samples..............................................................................................109

11.1 Config File (sample.x) ...................................................................................................... 110

11.2 sample_clnt.h .................................................................................................................... 112

11.3 sample_private.h............................................................................................................... 113

11.4 sample_clnt.c .................................................................................................................... 114

11.5 sample_svr.h ..................................................................................................................... 120

11.6 sample_svr.c ..................................................................................................................... 122

11.7 sample_public.h................................................................................................................ 127

vi

Section 1 Overview

Rev. 1.01 Mar. 17, 2008 Page 1 of 128

REJ10J1822-0101

Section 1 Overview

1.1 Overview

The stub generator (hereafter referred to as RPCGEN) is a tool used to generate the source code of

the client and server stubs that are required whenever the remote procedure call (RPC) facility of

the HI7200/MP realtime operating system is to be used. A config file is created by using a text

editor and then input to RPCGEN, which creates the source code of the client and server stubs.

RPCGEN

Config file

Source code of the client

and server stubs

Figure 1.1 Overview of RPCGEN

Section 1 Overview

Rev. 1.01 Mar. 17, 2008 Page 2 of 128

REJ10J1822-0101

1.2 Operating Environment

RPCGEN is provided as a Perl script file. Table 1.1 shows the operating environment.

Table 1.1 Operating Environment

Item Operating Environment

Realtime OS HI7200/MP V.1.00 Release 00 or later

Perl environment We have confirmed correct execution of RPCGEN by ActivePerl

5.8.8.820 (for Windows® (x86)) produced by ActiveState Software Inc.

ActivePerl is available for free download from the following Web site:

http://www.activestate.com/Products/activeperl/

Host machine Any machine with Windows® XP (32 bits) or Windows® 2000 as the

operating system

Section 2 Installation

Rev. 1.01 Mar. 17, 2008 Page 3 of 128

REJ10J1822-0101

Section 2 Installation

2.1 Downloading

RPCGEN can be downloaded for free from the Renesas Web site at the following URL.

http://www.renesas.com

2.2 Installing RPCGEN

The file for downloading has been compressed in the zip format. Expanding the zip file generates

the files listed in table 2.1. These files must be stored in a suitable folder.

Table 2.1 Files Provided as RPCGEN

Filename Description

rpcgen.pl Main body of RPCGEN

rpcgen_clnt.pm

rpcgen_svr.pm

rpcgen_info.pm

rpcgen_misc.pm

Package modules for use by the main body of RPCGEN

Section 2 Installation

Rev. 1.01 Mar. 17, 2008 Page 4 of 128

REJ10J1822-0101

Section 3 Functions and Files Generated by RPCGEN

Rev. 1.01 Mar. 17, 2008 Page 5 of 128

REJ10J1822-0101

Section 3 Functions and Files Generated by RPCGEN

3.1 Functions Generated by RPCGEN

Figure 3.1 shows the functions generated by RPCGEN.

Client

Server

Client-

initialization

function

Client-stub

functions

Client-

shutdown

function

Server-

initialization

function

Server-stub

functions

Server-

shutdown

function

Figure 3.1 Functions Generated by RPCGEN

Section 3 Functions and Files Generated by RPCGEN

Rev. 1.01 Mar. 17, 2008 Page 6 of 128

REJ10J1822-0101

3.1.1 Client

(1) Client-initialization function

This function initiates the connection with the server. Specifying CLNT_NOINIT prevents the

creation of the client-initialization function.

(2) Client-shutdown function

This function ends the connection with the server. Specifying CLNT_NOSHUTDOWN prevents

the creation of the client-shutdown function.

(3) Client-stub functions

Each of these functions makes an RPC call and has the same API as or an API similar to the server

function. If SVRAUTH has not been specified, the API will be the same as that of the server

function. Specifying CLNTSTUB prevents the creation of a specific client-stub function.

3.1.2 Server

(1) Server-initialization function

This function starts up the server. Specifying SVR_NOINIT prevents the creation of the server-

initialization function.

(2) Server-shutdown function

This function shuts the server down. Specifying SVR_NOSHUTDOWN prevents the creation of

the server-shutdown function.

(3) Server-stub functions

Each of these functions is called back from the RPC library and then calls a server function.

Specifying SVRSTUB prevents the creation of a specific server-stub function, while specifying

SVRFUNC allows the name of the called server function to be replaced.

Section 3 Functions and Files Generated by RPCGEN

Rev. 1.01 Mar. 17, 2008 Page 7 of 128

REJ10J1822-0101

3.2 Files Generated by RPCGEN

RPCGEN generates the files listed in table 3.1 in accord with the name of the config file.

Table 3.1 Files Generated by RPCGEN

Filename Description Definition of the File Location

<config file>_clnt.c Client-stub source file CLNTS option or

CLNT_SOURCEPATH in the config file

<config file>_clnt.h Client-stub header file

<config file>_private.h Internal header file for the

client stub

CLNTI option or CLNT_INCPATH in

the config file

<config file>_svr.c Server-stub source file SVRS option or SVR_SOURCEPATH

in the config file

<config file>_svr.h Server-stub header file SVRI option or SVR_INCPATH in the

config file

<config file>_public.h Header file for the client and

server stubs

PUBI option or PUB_INCPATH in the

config file

When the config file is “sample.x,” for example, RPCGEN will generate the following files:

sample_clnt.c, sample_clnt.h, sample_svr.c, sample_svr.h, sample_private.h, and sample_public.h.

To temporarily save information during the process of file generation, RPCGEN also generates

intermediate files in the current directory. The names of these intermediate files consist of two

underscores (“__”) appended before the filenames given in the table above.

(1) <config file>_clnt.c (client-stub source file)

This file contains the client-stub functions, client-initialization function, and client-shutdown

function.

(2) <config file>_clnt.h (client-stub header file)

This file contains definitions required for use of the client-stub functions, client-initialization

function, and client-shutdown function. The definitions include prototype declarations of the

client-stub functions, client-initialization function, and client-shutdown function.

Section 3 Functions and Files Generated by RPCGEN

Rev. 1.01 Mar. 17, 2008 Page 8 of 128

REJ10J1822-0101

(3) <config file>_private.h (internal header file for the client stub)

This is a header file included by <config file>_clnt.c only.

(4) <config file>_svr.c (server-stub source file)

This file contains the server-stub functions, server-initialization function, server-shutdown

function, and server-stub function table.

(5) <config file>_svr.h (server-stub header file)

This file contains definitions required for use of the server-initialization function and server-

shutdown function. The definitions include prototype declarations of the server-stub functions,

server-initialization function, and server-shutdown function.

(6) <config file>_public.h (header file for the client and server stubs)

This is a header file for the client and server applications. For details, refer to section 8.9, <config

file>_public.h.

Section 4 Executing RPCGEN

Rev. 1.01 Mar. 17, 2008 Page 9 of 128

REJ10J1822-0101

Section 4 Executing RPCGEN

4.1 Executing RPCGEN

RPCGEN must be executed from the command prompt as follows.

perlΔ-I<rpcgen path>Δ<rpcgen path>\rpcgen.plΔ

<config file>[Δ<option>...](RET)

<rpcgen path> is a path to the directory where RPCGEN has been installed.

<config file> refers to a file describing the specifications of the client and server stubs to be

generated. This file must be created by the user. The standard filename extension for the config

file is “.x”, which must not be omitted when the name is entered in a command line.

After execution of the above command, RPCGEN will generate the C-language source files and

header files for the client and server stubs in accord with the information contained in the config

file.

If <config file> and <option> are omitted, the command syntax will be shown.

Section 4 Executing RPCGEN

Rev. 1.01 Mar. 17, 2008 Page 10 of 128

REJ10J1822-0101

4.2 Options

4.2.1 PUBI

Format:

PUBI="<path>"

Description:

This option is used to specify the path for output of <config file>_public.h. If this option is used, a

definition of PUB_INCPATH in the config file is ignored.

4.2.2 CLNTS

Format:

CLNTS="<path>"

Description:

This option is used to specify the path for output of <config file>_clnt.c. If this option is used, a

definition of CLNT_SOURCEPATH in the config file is ignored.

4.2.3 CLNTI

Format:

CLNTI="<path>"

Description:

This option is used to specify the path for output of <config file>_clnt.h and

<config file>_private.h. If this option is used, a definition of CLNT_INCPATH in the config file

is ignored.

Page is loading ...

Renesas V.1.00, REJ10J1822-0101 User manual

Related papers

Other documents