From 4a9d5b865c9341c1d641ce499f5141a50b109c37 Mon Sep 17 00:00:00 2001 From: Michal Sojka Date: Wed, 15 Aug 2012 11:23:37 +0200 Subject: [PATCH] Add documentation from 0.3.2 release tarball --- doc/Makefile | 39 + doc/orte/orte_api.xml | 20 + doc/orte/orte_examples.xml | 315 +++++++ doc/orte/orte_internals.xml | 250 +++++ doc/orte/orte_intro.xml | 11 + doc/orte/orte_ps_model.xml | 269 ++++++ doc/orte/orte_rtps_model.xml | 150 +++ doc/orte/orte_summary.xml | 106 +++ doc/orte/orte_tests.xml | 12 + doc/orte/orte_usage.xml | 303 ++++++ doc/orte/ortemanager.xml | 167 ++++ doc/orte/orteping.xml | 203 ++++ doc/orte/ortespy.xml | 144 +++ doc/orte_incl.ent | 33 + doc/ortedoc.xml | 34 + doc/orteman.ent | 7 + doc/orteman.xml | 111 +++ doc/scripts/kernel-doc | 1729 ++++++++++++++++++++++++++++++++++ doc/scripts/tmpl2sgml | 23 + 19 files changed, 3926 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/orte/orte_api.xml create mode 100644 doc/orte/orte_examples.xml create mode 100644 doc/orte/orte_internals.xml create mode 100644 doc/orte/orte_intro.xml create mode 100644 doc/orte/orte_ps_model.xml create mode 100644 doc/orte/orte_rtps_model.xml create mode 100644 doc/orte/orte_summary.xml create mode 100644 doc/orte/orte_tests.xml create mode 100644 doc/orte/orte_usage.xml create mode 100644 doc/orte/ortemanager.xml create mode 100644 doc/orte/orteping.xml create mode 100644 doc/orte/ortespy.xml create mode 100644 doc/orte_incl.ent create mode 100644 doc/ortedoc.xml create mode 100644 doc/orteman.ent create mode 100644 doc/orteman.xml create mode 100755 doc/scripts/kernel-doc create mode 100755 doc/scripts/tmpl2sgml diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..7f4fdd9 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,39 @@ +KERNELDOC=scripts/kernel-doc +export KERNELDOC + +XML_BASENAMES = ortedoc + +DSL_DIR = ../../../dsl + +XML_SRC = ${XML_BASENAMES:%=%.xml} + +#DSL_DEF = -d $(DSL_DIR)/ocera-print.dsl + +ORTE_DOC_SOURCES = \ +orte/typedefs_api.xml \ +orte/protos_api.xml \ +orte/defines_api.xml + +default: all + +all: $(ORTE_DOC_SOURCES) orteman.pdf + +XML_ENT_INCS = $(wildcard *.ent) +XML_ENTITIES = $(shell cat $(XML_ENT_INCS) | \ + sed -n -e 's/^ * *$$/\1/p' | \ + sed -e 's/^\([^.]*\)$$/\1.*/p' ) + +%.pdf: %.xml $(XML_ENTITIES) $(XML_ENT_INCS) + #echo "$(XML_ENTITIES) $(XML_ENT_INCS)" + docbook2pdf $(DSL_DEF) $< + +%.xml: ../../orte/include/orte/%.h + $(KERNELDOC) -docbook $< >$@ + + +clean: + @rm -f ${XML_BASENAMES:%=%.html} + @rm -f ${XML_BASENAMES:%=%.pdf} + @rm -f ./*.log + @rm -f ./*.out + @rm -f ./*~ diff --git a/doc/orte/orte_api.xml b/doc/orte/orte_api.xml new file mode 100644 index 0000000..e601347 --- /dev/null +++ b/doc/orte/orte_api.xml @@ -0,0 +1,20 @@ + +
+ ORTE API + +
+ Data types + &orte_typedefs_api; +
+ +
+ Functions + &orte_protos_api; +
+ +
+ Macros + &orte_defines_api; +
+ +
diff --git a/doc/orte/orte_examples.xml b/doc/orte/orte_examples.xml new file mode 100644 index 0000000..28a6b80 --- /dev/null +++ b/doc/orte/orte_examples.xml @@ -0,0 +1,315 @@ + +
+ ORTE Examples + + + This chapter expect that you are familiar with RTPS communication + architecture described in . + + + Publications can offer multiple reliability policies ranging from + best-efforts to strict (blocking) reliability. Subscription can + request multiple policies of desired reliability and specify the + relative precedence of each policy. Publications will automatically + select among the highest precedence requested policy that is + offered by the publication. + + + + + + BestEffort: + This reliability policy is suitable for data that are sending + with a period. There are no message resending when a message is lost. + On other hand, this policy offer maximal predictable behaviour. + For instance, consider a publication which send data from a sensor + (pressure, temperature, ...). + + +
+ Periodic Snapshots of a BestEffort Publisher + + + + + + +
+ + + + + StrictReliable: + The ORTE supports the reliable delivery of issues. This kind of communication + is used where a publication want to be sure that all data will be delivered to + subscriptions. For instance, consider a publication which send commands. + + + Command data flow requires that each instruction in the sequence is + delivered reliably once and only once. Commands are often not time critical. + + + + +
+ BestEffort Communication + + + Before creating a Publication or Subscription is necessary to + create a domain by using function + ORTEDomainAppCreate. + The code should looks like: + + +int main(int argc, char *argv[]) +{ + ORTEDomain *d = NULL; + ORTEBoolean suspended= ORTE_FALSE; + + ORTEInit(); + + d = ORTEDomainAppCreate(ORTE_DEFAUL_DOMAIN, NULL, NULL, suspended); + if (!d) + { + printf("ORTEDomainAppCreate failed\n"); + return -1; + } +} + + + + The ORTEDomainAppCreate allocates and initializes resources that are needed + for communication. The parameter suspended says + if ORTEDomain takes suspend communicating threads. In + positive case you have to start threads manually by using + ORTEDomainStart. + + + + + Next step in creation of a application is registration serialization and + deserialization routines for the specific type. You can't specify this functions, + but the incoming data will be only copied to output buffer. + + +ORTETypeRegisterAdd(d, "HelloMsg", NULL, NULL, 64); + + + + To create a publication in specific domain use the function + ORTEPublicationCreate. + + +char instance2send[64]; +NtpTime persistence, delay; + +NTPTIME_BUILD(persistence, 3); /* this issue is valid for 3 seconds */ +NTPTIME_DELAY(delay, 1); /* a callback function will be called every 1 second */ +p = ORTEPublicationCreate( d, + "Example HelloMsg", + "HelloMsg", + &instance2Send, + &persistence, + 1, + sendCallBack, + NULL, + &delay); + + + + The callback function will be then called when a new issue from + publisher has to be sent. It's the case when you specify callback routine in + ORTEPublicationCreate. When + there isn't a routine you have to send data manually by call function + ORTEPublicationSend. This option + is useful for sending periodic data. + + +void sendCallBack(const ORTESendInfo *info, void *vinstance, void *sendCallBackParam) +{ + char *instance = (char *) vinstance; + switch (info->status) + { + case NEED_DATA: + printf("Sending publication, count %d\n", counter); + sprintf(instance, "Hello world (%d)", counter++); + break; + + case CQL: //criticalQueueLevel has been reached + break; + } +} + + + + Subscribing application needs to create a subscription with + publication's Topic and TypeName. A callback function will be then + called when a new issue from publisher will be received. + + +ORTESubscription *s; +NtpTime deadline, minimumSeparation; + +NTPTIME_BUILD(deadline, 20); +NTPTIME_BUILD(minimumSeparation, 0); +p = ORTESubscriptionCreate( d, + IMMEDIATE, + BEST_EFFORTS, + "Example HelloMsg", + "HelloMsg", + &instance2Recv, + &deadline, + &minimumSeparation, + recvCallBack, + NULL); + + + + The callback function is shown in the following example: + + +void recvCallBack(const ORTERecvInfo *info, void *vinstance, void *recvCallBackParam) +{ + char *instance = (char *) vinstance; + switch (info->status) + { + case NEW_DATA: + printf("%s\n", instance); + break; + + case DEADLINE: //deadline occurred + break; + } +} + + + + Similarly examples are located in ORTE subdirectory + orte/examples/hello. There are + demonstrating programs how to create an application + which will publish some data and another application, which will + subscribe to this publication. + + +
+ +
+ Reliable communication + + + The reliable communication is used especially in situations + where we need guarantee data delivery. The ORTE supports the inorder + delivery of issues with built-in retry mechanism + + + The creation of reliable communication starts like besteffort communication. + Difference is in creation a subscription. Third parameter is just only changed + to STRICT_RELIABLE. + + + +ORTESubscription *s; +NtpTime deadline, minimumSeparation; + +NTPTIME_BUILD(deadline, 20); +NTPTIME_BUILD(minimumSeparation, 0); +p = ORTESubscriptionCreate( d, + IMMEDIATE, + STRICT_RELIABLE, + "Example HelloMsg", + "HelloMsg", + &instance2Recv, + &deadline, + &minimumSeparation, + recvCallBack, + NULL); + + + Note: + + Strict reliable subscription must set minimumSeparation to zero! The middleware + can't guarantee that the data will be delivered on first attempt (retry mechanism). + + + + Sending of a data is blocking operation. It's strongly recommended to + setup sending queue to higher value. Default value is 1. + + +ORTEPublProp *pp; + +ORTEPublicationPropertiesGet(publisher,pp); +pp->sendQueueSize=10; +pp->criticalQueueLevel=8; +ORTEPublicationPropertiesSet(publisher,pp); + + + + An example of reliable communication is in ORTE subdirectory + orte/examples/reliable. There are located + a strictreliable subscription and publication. + + +
+ +
+ Serialization/Deserialization + + + Actually the ORTE doesn't support any automatic creation of + serialization/deserializaction routines. + This routines have to be designed manually by the user. In next is + shown, how should looks both for the structure BoxType. + + +typedef struct BoxType { + int32_t color; + int32_t shape; +} BoxType; + +void +BoxTypeSerialize(CDR_Codec *cdrCodec, void *instance) { + BoxType *boxType=(BoxType*)instance; + + CDR_put_long(cdrCodec,boxType->color); + CDR_put_long(cdrCodec,boxType->shape); +} + +void +BoxTypeDeserialize(CDR_Codec *cdrCodec, void *instance) { + BoxType *boxType=(BoxType*)instance; + + CDR_get_long(cdrCodec,&boxType->color); + CDR_get_long(cdrCodec,&boxType->shape); +} + + + + When we have written a serialization/deserialization routine we need to + register this routines to midleware by function + ORTETypeRegisterAdd + + + + ORTETypeRegisterAdd( + domain, + "BoxType", + BoxTypeSerialize, + BoxTypeDeserialize, + sizeof(BoxType)); + + + + The registration must be called before creation a publication or subscription. + Normally is ORTETypeRegisterAdd called immediately after + creation of a domain (ORTEDomainCreate). + + + + All of codes are part of the Shapedemo located in subdirectory + orte/contrib/shape. + +
+ +
diff --git a/doc/orte/orte_internals.xml b/doc/orte/orte_internals.xml new file mode 100644 index 0000000..68f5bf3 --- /dev/null +++ b/doc/orte/orte_internals.xml @@ -0,0 +1,250 @@ + +
+ ORTE Implementation Issues + + + ORTE is network middleware for distributed, real-time application development + that uses the real-time, publish-subscribe model. The middleware is available + for a variety of platforms including RTAI, RTLinux, Windows, and a several + versions of Unix. The compilation system is mainly based on autoconf. + + + + ORTE is middleware composed of a database, and tasks. + On the top of ORTE architecture is application interface (API). By using API + users should write self application. The tasks perform all of the message + addressing serialization/deserialization, and transporting. The ORTE components + are shown in + +
+ ORTE Architecture + + + + + + +
+ + + + The RTPS protocol defines two kinds of Applications: + + + + + + Manager: + The manager is a special Application that helps applications automatically + discover each other on the Network. + + + + + ManagedApplication: + A ManagedApplication is an Application that is managed by one or more + Managers. Every ManagedApplication is managed by at least one Manager. + + + + + The manager is mostly designed like separate application. In RTPS architecture + is able to create application which contains manager and managedapplication, but + for easy managing is better split both. The ORTE contains a separate instance + of manager located in directory orte/manager. + + + The manager is composed from five kinds of objects: + + + + WriterApplicationSelf: + through which the Manager provides information about its own parameters + to Managers on other nodes. + + + + + ReaderManagers: + CSTReader through which the + Manager obtains information on the state of all other Managers on the + Network. + + + + + ReaderApplications: + CSTReader which is used for the registration of local and remote + managedApplications. + + + + + WriterManagers: + CSTWriter through which the Manager will send the + state of all Managers in the Network to all its managees. + + + + + WriterApplications: + CSTWriter through which the Manager will + send information about its managees to other Managers in the Network. + + + + + + A Manager that discovers a new ManagedApplication + through its readerApplications must decide whether it must manage this + ManagedApplication or not. For this purpose, the attribute + managerKeyList of the Application is used. If one of the + ManagedApplication's keys (in the attribute managerKeyList) is equal + to one of the Manager's keys, the Manager accepts the Application as + a managee. If none of the keys are equal, the managed application is + ignored. At the end of this process all Managers have discovered their + managees and the ManagedApplications know all Managers in the Network. + + + The managedApplication is composed from seven kinds of objects: + + + + WriterApplicationSelf: + a CSTWriter through which the ManagedApplication registers + itself with the local Manager. + + + + + ReaderApplications: + a CSTReader through which the ManagedApplication receives + information about another ManagedApplications in the network. + + + + + ReaderManagers: + a CSTReader through which the ManagedApplication receives + information about Managers. + + + + + WriterPublications: + CSTWriter through which the Manager will send the + state of all Managers in the Network to all its managees. + + + + + ReaderPublications: + a Reader through which the Publication receives information + about Subscriptions. + + + + + WriterSubscriptions: + a Writer that provides information about Subscription to + Publications. + + + + + ReaderSubscriptions: + a Reader that receives issues from one or more instances of + Publication, using the publish-subscribe service. + + + + + + The ManagedApplication has a special CSTWriter writerApplicationSelf. The + Composite State (CS) of the ManagedApplication's writerApplicationSelf + object contains only one NetworkObject - the application itself. The + writerApplicationSelf of the ManagedApplication must be configured to + announce its presence repeatedly and does not request nor expect + acknowledgments. + + + The ManagedApplications now use the CST Protocol between the + writerApplications of the Managers and the readerApplications of the + ManagedApplications in order to discover other ManagedApplications in + the Network. Every ManagedApplication has two special CSTWriters, + writerPublications and writerSubscriptions, and two special CSTReaders, + readerPublications and readerSubscriptions. + + + Once ManagedApplications have discovered each other, they use the + standard CST protocol through these special CSTReaders and CSTWriter to + transfer the attributes of all Publications and Subscriptions in the + Network. + + + The ORTE stores all data in local database per application. There isn't + central store where are data saved. If an application comes into communication, + than will be created local mirror of all applications parameters. + Parts of internal structures are shown in . + +
+ ORTE Internal Attributes + + + + + + +
+ + + Following example shows communication between two nodes (N1, N2). + There are applications running on each node - MA1.2 on node + N1 and MA2.1, MA2.2 on node N2. Each node has it own manager (M1, M2). The + example shows, what's happen when a new application comes into communication + (MA1.1). + + + + + MA1.1 introduces itself to local manager M1 + + + M1 sends back list of remote managers Mx and other local applications MA1.x + + + MA1.1 is introduced to all Mx by M1 + + + All remote MAs are reported now to M1.1 + + + MA1.1 is queried for self services (publishers and subscriberes) from others MAx. + + + MA1.1 asks for services to others MAx. + + + All MAs know information about others. + + + + + The corresponding publishers and subscribers with matching Topic + and Type are connected and starts their data communication. + + +
+ RTPS Communication among Network Objects + + + + + + +
+ +
\ No newline at end of file diff --git a/doc/orte/orte_intro.xml b/doc/orte/orte_intro.xml new file mode 100644 index 0000000..22d3d97 --- /dev/null +++ b/doc/orte/orte_intro.xml @@ -0,0 +1,11 @@ + +
+ Introduction + + + The Open Real-Time Ethernet (ORTE) is + open source implementation of RTPS communication protocol. This protocol + is being to submit to IETF as an informational RFC and has been adopted + by the IDA group. + +
\ No newline at end of file diff --git a/doc/orte/orte_ps_model.xml b/doc/orte/orte_ps_model.xml new file mode 100644 index 0000000..cd32ec0 --- /dev/null +++ b/doc/orte/orte_ps_model.xml @@ -0,0 +1,269 @@ + +
+ The Publish-Subscribe Architecture + + + The publish-subscribe architecture is designed to + simplify one-to-many data-distribution requirements. + In this model, an application publishes data and + subscribes to data. Publishers and subscribers are + decoupled from each other too. That is: + + + + Publishers simply send data anonymously, they + do not need any knowledge of the number or + network location of subscribers. + + + + Subscribers simply receive data anonymously, + they do not need any knowledge of the number or + network location of the publisher. + + + + + An application can be a publisher, subscriber, or both a + publisher and a subscriber. + + +
+ Publish-Subscribe Architecture + + + + + + + + Publish-subscribe supports anonymous, event-driven + transfer between many nodes. The developer simply writes + the application to send or receive the data. + + + +
+ + + Publish-subscribe architectures are best-suited to + distributed applications with complex data flows. The + primary advantages of publish-subscribe to + applications developers are: + + + + + Publish-subscribe applications are modular and + scalable. The data flow is easy to manage + regardless of the number of publishers and subscribers. + + + + The application subscribes to the data by name + rather than to a specific publisher or publisher + location. It can thus accommodate configuration + changes without disrupting the data flow. + + + + Redundant publishers and subscribers can be + supported, allowing programs to be replicated + (e.g. multiple control stations) and moved transparently. + + + + Publish-subscribe is much more efficient, + especially over client-server, with bandwidth utilization. + + + + + + Publish-subscribe architectures are not good at + sporadic request/response traffic, such as file transfers. + However, this architecture offers practical advantages + for applications with repetitive, time-critical data + flows. + + +
+ The Publish-Subscribe Model + + + Publish-subscribe (PS) data distribution is gaining popularity in many + distributed applications, such as financial communications, command + and control systems. PS popularity can be attributed to the dramatically + reduced system development, deployment and maintenance effort and the + performance advantages for applications with one-to-many and + many-to-many data flows. + + + + Several main features characterize all publish-subscribe architectures: + + + Distinct declaration and delivery. + Communications occur in three simple steps: + + + + Publisher declares intent to publish a publication. + + + Subscriber declares interest in a publication. + + + Publisher sends a publication issue. + + + + + The publish-subscribe services are typically made available to + applications through middleware that sits on top of the operating + system s network interface and presents an application programming + interface. + + +
+ Generic Publish-Subscribe Architecture + + + + + + + + Publish-subscribe is typically implemented through middleware that + sits on top of the operating system s network interface. The + middleware presents a publishsubscribe API so that applications + make just a few simple calls to send and receive publications. The + middleware performs the many and complex network functions that + physically distribute the data. + + + +
+ + + The middleware handles three basic programming chores: + + + + + Maintain the database that maps publishers to subscribers + resulting in logical data channels for each publication + between publishers and subscribers. + + + + + Serialize (also called marshal) and deserialize (demarshal) the data + on its way to and from the network to reconcile publisher + and subscriber platform differences. + + + + + Deliver the data when it is published. + + + +
+ +
+ Publish-Subscribe in Real Time + + + Publish-subscribe offers some clear advantages for real-time applications: + + + + + Because it is very efficient in both bandwidth and + latency for periodic data exchange, PS offers the + best transport for distributing data quickly. + + + + + Because it provides many-to-many connectivity, + PS is ideal for applications in which publishers + and subscribers are added and removed + dynamically. + + + + + + Real-time applications require more functionality than what is provided + by desktop and Internet publish-subscribe semantics. For instance, real-time + applications often require: + + + + + Delivery timing control: + Real-time subscribers are concerned with timing; for example, when the + data is delivered and how long it remains valid. + + + + + Reliability control: + Reliable delivery conflicts with deterministic timing. Each subscriber + typically requires the ability to specify its own reliability + characteristics. + + + + + Request-reply semantics: + Complex real-time applications often have one-time requests for + actions or data. These do not fit well into the PS semantics. + + + + + Flexible delivery bandwidth: + Typical real-time applications include both real-time and + non-realtime subscribers. Each subscriber s bandwidth requirements - even + for the same publication - can be different. + + + + + Fault tolerance: + Real-time applications often require hot standby publishers + and/or subscribers. + + + + + Thread priority awareness: + Real-time communications often must work without + affecting publisher or subscriber threads. + + + + + Robustness: + The communications layer should not introduce any single-node + points-of-failure to the application. + + + + + Efficiency: + Real-time systems require efficient data collection and delivery. + Only minimal delays should be introduced into the critical + data-transfer path. + + + + +
+ +
diff --git a/doc/orte/orte_rtps_model.xml b/doc/orte/orte_rtps_model.xml new file mode 100644 index 0000000..f12f9ab --- /dev/null +++ b/doc/orte/orte_rtps_model.xml @@ -0,0 +1,150 @@ + +
+ The Real-Time Publish-Subscribe Model + + + The Real-Time Publish-Subscribe (RTPS) communications model was developed + to address these limitations of PS. RTPS adds publication and subscription timing + parameters and properties so the developer can control the different types + of data flows and achieve their application s performance and + reliability goals. + + +
+ Publication Parameters + + + Each publication is characterized by four + parameters: topic, type, strength and persistence. The topic is the label + that identifies each data flow. The type describes the data format. + The strength indicates a publisher s weight relative to other publishers + of the same topic. The persistence indicates how long each publication + issue is valid. Next figure illustrates how a subscriber arbitrates + among publications using the strength and persistence properties. + + +
+ Publication Arbitration + + + + + + + + Fault tolerant applications use redundant publishers sending + publications with the same topic to ensure continuous + operation. Subscribers arbitrate among the publications + on an issue-by-issue basis based on the strength and persistence + of each issue. + + + +
+ + + When there are multiple publishers sending the same + publication, the subscriber accepts the issue if its strength + is greater than the last-received issue or if the last issue s + persistence has expired. Typically, a publisher that sends issues + with a period of length T will set its persistence to some + time Tp where Tp > T. Thus, while the strongest publisher is + functional, its issues will take precedence over publication + issues of lesser strength. Should the strongest publisher stop + sending issues (willingly or due to a failure), other publisher(s) + sending issues for the same publication will take over after Tp elapses. This + mechanism establishes an inherently robust, quasi-stateless communications + channel between the then-strongest publisher of a publication + and all its subscribers. + +
+ +
+ Subscription Paramters + + + Subscriptions are identified by four + parameters: topic, type, minimum separation and deadline. The topic + the label that identifies the data flow, and type describes the + data format (same as the publication properties). Minimum separation + defines a period during which no new issues are accepted for + that subscription. The deadline specifies how long the subscriber is + willing to wait for the next issue. Next figure illustrates the use + of these parameters. + + +
+ Subscription Issue Separation + + + + + + + + Once the subscriber has received an issue, it will not receive + another issue for at least the minimum separation time. If a + new issue does not arrive by the deadline, the application + is notified. + + + +
+ + + The minimum separation protects a slow subscriber against publishers + that are publishing too fast. The deadline provides a guaranteed wait + time that can be used to take appropriate action in case of + communication delays. + +
+ +
+ Reliability and Time-Determinism + + + Publish-subscribe can support a variety of message delivery reliability + models, not all of which are suitable to real-time applications. The + RTPS reliability model recognizes that the optimal balance between + time determinism and data-delivery reliability varies between real-time + applications, and often among different subscriptions within the + same application. For example, signal subscribers will want only + the most up-to-date issues and will not care about missed issues. Command + subscribers, on the other hand, must get every issue in + sequence. Therefore, RTPS provides a mechanism for the application to + customize the determinism versus reliability trade-off on a per subscription + basis. + + + The RTPS determinism vs. reliability model is subscriber-driven. Publishers + simply send publication issues. However, to provide message delivery + reliability, publishers must be prepared to resend missed issues to subscriptions + that require reliable delivery. + + + The RTPS reliability model uses publication buffers publisher and subscriber and + retries to ensure that subscribers who need each issue receive them in the proper + sequence. In addition, the publisher applies sequence number to each + publication issue. + + + The publisher uses the publication buffer to store history of the most + recently sent issues. The subscriber uses its publication buffer to cache the + most recently received issues. The subscriber acknowledges issues received in + order and sends a request for the missing issue when the most recent + issue s sequence number out of order. The publisher responds by sending the + missed update again. + + + Publishers remove an issue from their history buffers in two cases: the issue has been + acknowledged by all reliable subscribers or the publisher overflows the history buffer + space. Flow control can be implemented by setting high and low watermarks for + the buffer. These publication-specific parameters let the publisher balance + the subscribers need for issues against its need to + maintain a set publication rate. + +
+ +
diff --git a/doc/orte/orte_summary.xml b/doc/orte/orte_summary.xml new file mode 100644 index 0000000..0d4c353 --- /dev/null +++ b/doc/orte/orte_summary.xml @@ -0,0 +1,106 @@ + +
+ Summary + + + + Name of the component + + + Open Real-Time Ethernet (ORTE) + + + + + Author + + + Petr Smolik + + + + + ORTE Internet resources + + + OCERA project home page + + + OCERA SourceForge project page. The OCERA CVS relative path to ORTE + driver sources is + + ocera/components/comm/eth/orte. + + Real-Time Innovation home page + + + + + Reviewer + + + not validated + + + + + Layer + + + High-level + + + + + Version + + + orte-0.3.1 + + + + + Status + + + Beta + + + + + Dependencies + + + Ethernet adapter with a UDP stack. + Multi-threaded operating system OS + Memory allocator (functions malloc, free) + + + + + Supported OS + + + + + Unix - Linux, FreeBSD, Solaris, MacOS, PharLap + + + Windows + + + RTAI with RTNet + + + + + + + Release date + + + September 2004 + + + +
diff --git a/doc/orte/orte_tests.xml b/doc/orte/orte_tests.xml new file mode 100644 index 0000000..0110ff9 --- /dev/null +++ b/doc/orte/orte_tests.xml @@ -0,0 +1,12 @@ + +
+ ORTE Tests + + + There were not any serious tests performed yet. Current version + has been intensively tested against reference implementation of the + protocol. Results of these test indicate that ORTE is fully + interoperable with implementation provided by another vendor. + +
+ diff --git a/doc/orte/orte_usage.xml b/doc/orte/orte_usage.xml new file mode 100644 index 0000000..5145302 --- /dev/null +++ b/doc/orte/orte_usage.xml @@ -0,0 +1,303 @@ + +
+ ORTE Usage Information + +
+ Installation and Setup + + + In this chapter is described basic steps how to makes installation + and setup process of the ORTE. The process includes next steps: + + + + + Downloading the ORTE distribution + Compilation + Installing the ORTE library and utilities + Testing the installation + + + + Note: + + On windows systems we are recommend to use Mingw or Cygwin systems. The + ORTE support also MSVC compilation, but this kind of installation is not + described here. + +
+ Downloading + + + The ORTE component can be obtained from OCERA SourceForge web page + (). Here is the component + located also in self distribution branch as well as in OCERA distribution. + Before developing any application check if there is a new file release. + + + The CVS version of ORTE repository can be checked out be anonymous (pserver) + CVS with the following commands. + +cvs -d:pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera login +cvs -z3 -d:pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera co ocera/components/comm/eth/orte/ + + Attention, there is developing version and can't be stable! + +
+ +
+ Compilation + + Before the compilation process is necessary to prepare the source. + Create a new directory for ORTE distribution. We will assume name of this + directory /orte for Linux case. Copy or move downloaded + ORTE sources to /orte (assume the name of sources + orte-0.2.3.tar.gz). Untar and unzip this files by using + next commands: + +gunzip orte-0.2.3.tar.gz +tar xvf orte-0.2.3.tar + + Now is the source prepared for compilation. Infrastructure of the ORTE is + designed to support GNU make (needs version 3.81) as well as autoconf compilation. In + next we will continue with description of autoconf compilation, which is more + general. The compilation can follows with commands: + +mkdir build +cd build +../configure +make + + This is the case of outside autoconf compilation. In directory build + are all changes made over ORTE project. The source can be easy move to original + state be removing of directory build. + +
+ +
+ Installing + + + The result of compilation process are binary programs and ORTE library. For the + next developing is necessary to install this result. It can be easy done be typing: + +make install + + All developing support is transferred into directories with direct access of + design tools. + + + + + + + + name + target path + + + + ortemanager, orteping, ortespy + /usr/local/bin + library + /usr/local/lib + include + /usr/local/include + + + + + The installation prefix /usr/local/ can be changed + during configuration. Use command ../configure --help for + check more autoconf options. + +
+ +
+ Testing the Installation + + + To check of correct installation of ORTE open three shells. + + + + + + In first shell type + ortemanager + + + In second shell type + orteping -s + + This command will invoked creation of a subscription. You should see: + + +deadline occurred +deadline occurred +... + + + + In third shell type + orteping -p + + This command will invoked creation of a publication. You should see: + + +sent issue 1 +sent issue 2 +sent issue 3 +sent issue 4 +... + + + If the ORTE installation is properly, you will see incoming messages + in second shell (orteping -s). + + +received fresh issue 1 +received fresh issue 2 +received fresh issue 3 +received fresh issue 4 +... + + + It's sign, that communication is working correctly. + + + + + +
+
+ +
+ The ORTE Manager + + + A manager is special application that helps + applications automatically discover each other on the Network. + Each time an object is created or destroyed, the manager + propagate new information to the objects that are internally + registered. + + + Every application precipitate in communication is managed by least + one manager. The manager should be designed like separated application + as well as part of designed application. + + +
+ Position of Managers in RTPS communication + + + + + + +
+ + + The ORTE provides one instance of a manager. Name of this utility + is ortemanager and is located + in directory orte/ortemanager. Normally is necessary to + start ortemanager manually or use a script on + UNIX systems. For Mandrake and Red-hat distribution is this script created + in subdirectory rc. Windows + users can install ortemanager like service by + using option /install_service. + + Note: + + Don't forget to run a manager (ortemanager) on each RTPS participate node. + During live of applications is necessary to be running this manager. + + +
+ Example of Usage ortemanager + + + Each manager has to know where are other managers in the network. + Their IP addresses are therefore specified as IPAddressX parameters of + ortemanager. All managers participate in one kind of communication use + the same domain number. The domain number is transferred to port number by + equation defined in RTPS specification (normally domain 0 is transferred to + 7400 port). + + + Let's want to distribute the RTPS communication of nodes with IP addresses + 192.168.0.2 and 192.168.0.3. Private IP address is 192.168.0.1. + The ortemanager can be execute with parameters: + + +ortemanager -p 192.168.0.2:192.168.0.3 + + + To communicate in different domain use (parameter -d): + + +ortemanager -d 1 -p 192.168.0.2:192.168.0.3 + + + Very nice feature of ortemanager is use event system to inform + of creation/destruction objects (parameter -e). + + +ortemanager -e -p 192.168.0.2:192.168.0.3 + + + Now, you can see messages: + + +[smolik@localhost smolik]$ortemanager -e -p 192.168.0.2:192.168.0.3 +manager 0xc0a80001-0x123402 was accepted +application 0xc0a80002-0x800301 was accepted +application 0xc0a80002-0x800501 was accepted +application 0xc0a80002-0x800501 was deleted +manager 0xc0a80001-0x123402 was deleted + + + &orte_ortemanager; +
+
+ +
+ Simple Utilities + + The simple utilities can be found in the orte/examples + subdirectory of the ORTE source subtree. These utilities are useful + for testing and monitoring RTPS communication. + + + + The utilities provided directly by ORTE are: + + + + + orteping + + + the utility for easy creating of publications and subscriptions. + + + + + + ortespy + + + monitors issues produced by other application in specific domain. + + + + + + + &orte_orteping; + &orte_ortespy; + +
+
diff --git a/doc/orte/ortemanager.xml b/doc/orte/ortemanager.xml new file mode 100644 index 0000000..0fd691b --- /dev/null +++ b/doc/orte/ortemanager.xml @@ -0,0 +1,167 @@ + + + + + ortemanager + 1 + + + ortemanager + the utility for discovery others applications and managers on the network + + + + ortemanager + + + + + + + + + + + + + + + + + Description + + Main purpose of the utility ortemanager is debug and + test ORTE communication. + + + + OPTIONS + + + + + + The number of working ORTE domain. Default is 0. + + + + + + + + The IP addresses parsipiates in RTPS communication. + See for example of usage. + + + + + + + + The refresh time in manager. Default 60 seconds. + + + + + + + + The searching time in local database for finding expired application. + Default 60 seconds. + + + + + + + + Expiration time in other applications. + + + + + + + + The minimum time between two issues. + + + + + + + + Set verbosity level. + + + + + + + + All debug messages can be redirect into specific file. + + + + + + + + + Print the version of ortemanager. + + + + + + + + + Print usage screen. + + + + + + + + diff --git a/doc/orte/orteping.xml b/doc/orte/orteping.xml new file mode 100644 index 0000000..7851ca1 --- /dev/null +++ b/doc/orte/orteping.xml @@ -0,0 +1,203 @@ + + + + + orteping + 1 + + + orteping + the utility for debugging and testing of ORTE communication + + + + orteping + + + + + + + + + + + + + + + + + + + Description + + Main purpose of the utility orteping is debug and + test ORTE communication. + + + + OPTIONS + + + + + + The number of working ORTE domain. Default is 0. + + + + + + + + Create a publisher with Topic - Ping and Type - PingData. + The publisher will publish a issue with period by + parameter delay. + + + + + + + + Setups relative weight against other publishers. Default is 1. + + + + + + + + The time between two issues. Default 1 second. + + + + + + + + Create a subscriber with Topic - Ping and Type - PingData. + + + + + + + + The refresh time in manager. Default 60 seconds. + + + + + + + + The searching time in local database for finding expired application. + Default 60 seconds. + + + + + + + + Expiration time in other applications. + + + + + + + + The minimum time between two issues. + + + + + + + + Set verbosity level. + + + + + + + + Nothing messages will be printed on screen. It can be useful + for testing maximal throughput. + + + + + + + + All debug messages can be redirect into specific file. + + + + + + + + + Print the version of orteping. + + + + + + + + + Print usage screen. + + + + + + + + diff --git a/doc/orte/ortespy.xml b/doc/orte/ortespy.xml new file mode 100644 index 0000000..6362705 --- /dev/null +++ b/doc/orte/ortespy.xml @@ -0,0 +1,144 @@ + + + + + ortespy + 1 + + + ortespy + the utility for monitoring of ORTE issues + + + + orteping + + + + + + + + + + + + + Description + + Main purpose of the utility ortespy is monitoring data + traffic between publications and subscriptions. + + + + OPTIONS + + + + + + The number of working ORTE domain. Default is 0. + + + + + + + + Set verbosity level. + + + + + + + + The refresh time in manager. Default 60 seconds. + + + + + + + + Create publisher + + + + + + + + Expiration time in other applications. + + + + + + + + All debug messages can be redirect into specific file. + + + + + + + + Print the version of orteping. + + + + + + + + + Print usage screen. + + + + + + + + diff --git a/doc/orte_incl.ent b/doc/orte_incl.ent new file mode 100644 index 0000000..7f54e6e --- /dev/null +++ b/doc/orte_incl.ent @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/ortedoc.xml b/doc/ortedoc.xml new file mode 100644 index 0000000..21cdeb0 --- /dev/null +++ b/doc/ortedoc.xml @@ -0,0 +1,34 @@ + + + Open Real-Time Ethernet + + The Open Real-Time Ethernet (ORTE) is open source implementation of + RTPS communication protocol. RTPS is new application layer protocol + targeted to real-time communication area, which is build on the top of + standard UDP stack. Since there are many TCP/IP stack implementations + under many operating systems and RTPS protocol does not have any other + special HW/SW requirements, it should be easily ported to many HW/SW + target platforms. Because it uses only UDP protocol, it retains control of + timing and reliability. + +
+ ORTE Summary + + &orte_summary; +
+ +
+ ORTE Description + + &orte_intro; + &orte_ps_model; + &orte_rtps_model; +
+ + &orte_api; + &orte_internals; + &orte_examples; + &orte_tests; + &orte_usage; + + diff --git a/doc/orteman.ent b/doc/orteman.ent new file mode 100644 index 0000000..6ed4fbe --- /dev/null +++ b/doc/orteman.ent @@ -0,0 +1,7 @@ + + + + +%orte_entities + + diff --git a/doc/orteman.xml b/doc/orteman.xml new file mode 100644 index 0000000..096195d --- /dev/null +++ b/doc/orteman.xml @@ -0,0 +1,111 @@ + + + %entities; + + ] +> + + + + + ORTE - Open Real-Time Ethernet + + + +&orte; + + + diff --git a/doc/scripts/kernel-doc b/doc/scripts/kernel-doc new file mode 100755 index 0000000..6ee1db1 --- /dev/null +++ b/doc/scripts/kernel-doc @@ -0,0 +1,1729 @@ +#!/usr/bin/perl -w + +use strict; + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## Copyright (C) 2000, 1 Tim Waugh ## +## Copyright (C) 2001 Simon Huggins ## +## ## +## #define enhancements by Armin Kuster ## +## Copyright (c) 2000 MontaVista Software, Inc. ## +## ## +## This software falls under the GNU General Public License. ## +## Please read the COPYING file for more information ## + +# w.o. 03-11-2000: added the '-filelist' option. + +# 18/01/2001 - Cleanups +# Functions prototyped as foo(void) same as foo() +# Stop eval'ing where we don't need to. +# -- huggie@earth.li + +# 27/06/2001 - Allowed whitespace after initial "/**" and +# allowed comments before function declarations. +# -- Christian Kreibich + +# Still to do: +# - add perldoc documentation +# - Look more closely at some of the scarier bits :) + +# 26/05/2001 - Support for separate source and object trees. +# Return error code. +# Keith Owens + +# 23/09/2001 - Added support for typedefs, structs, enums and unions +# Support for Context section; can be terminated using empty line +# Small fixes (like spaces vs. \s in regex) +# -- Tim Jansen + + +# +# This will read a 'c' file and scan for embedded comments in the +# style of gnome comments (+minor extensions - see below). +# + +# Note: This only supports 'c'. + +# usage: +# kerneldoc [ -docbook | -html | -text | -man ] +# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile +# or +# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile +# +# Set output format using one of -docbook -html -text or -man. Default is man. +# +# -function funcname +# If set, then only generate documentation for the given function(s). All +# other functions are ignored. +# +# -nofunction funcname +# If set, then only generate documentation for the other function(s). All +# other functions are ignored. Cannot be used with -function together +# (yes thats a bug - perl hackers can fix it 8)) +# +# c files - list of 'c' files to process +# +# All output goes to stdout, with errors to stderr. + +# +# format of comments. +# In the following table, (...)? signifies optional structure. +# (...)* signifies 0 or more structure elements +# /** +# * function_name(:)? (- short description)? +# (* @parameterx: (description of parameter x)?)* +# (* a blank line)? +# * (Description:)? (Description of function)? +# * (section header: (section description)? )* +# (*)?*/ +# +# So .. the trivial example would be: +# +# /** +# * my_function +# **/ +# +# If the Description: header tag is ommitted, then there must be a blank line +# after the last parameter specification. +# e.g. +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * +# * Does my stuff explained. +# */ +# +# or, could also use: +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * Description: Does my stuff explained. +# */ +# etc. +# +# Beside functions you can also write documentation for structs, unions, +# enums and typedefs. Instead of the function name you must write the name +# of the declaration; the struct/union/enum/typedef must always precede +# the name. Nesting of declarations is not supported. +# Use the argument mechanism to document members or constants. In +# structs and unions you must declare one member per declaration +# (comma-separated members are not allowed - the parser does not support +# this). +# e.g. +# /** +# * struct my_struct - short description +# * @a: first member +# * @b: second member +# * +# * Longer description +# */ +# struct my_struct { +# int a; +# int b; +# }; +# +# All descriptions can be multiline, except the short function description. +# +# You can also add additional sections. When documenting kernel functions you +# should document the "Context:" of the function, e.g. whether the functions +# can be called form interrupts. Unlike other sections you can end it with an +# empty line. +# Example-sections should contain the string EXAMPLE so that they are marked +# appropriately in DocBook. +# +# Example: +# /** +# * user_function - function that can only be called in user context +# * @a: some argument +# * Context: !in_interrupt() +# * +# * Some description +# * Example: +# * user_function(22); +# */ +# ... +# +# +# All descriptive text is further processed, scanning for the following special +# patterns, which are highlighted appropriately. +# +# 'funcname()' - function +# '$ENVVAR' - environmental variable +# '&struct_name' - name of a structure (up to two words including 'struct') +# '@parameter' - name of a parameter +# '%CONST' - name of a constant. + +my $errors = 0; +my $warnings = 0; + +# match expressions used to find embedded type information +my $type_constant = '\%([-_\w]+)'; +my $type_func = '(\w+)\(\)'; +my $type_param = '\@(\w+)'; +my $type_struct = '\&((struct\s*)?[_\w]+)'; +my $type_env = '(\$\w+)'; + +# Output conversion substitutions. +# One for each output format + +# these work fairly well +my %highlights_html = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +my $blankline_html = "

"; + +# sgml, docbook format +my %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", + $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_sgml = "\n"; + +# gnome, docbook format +my %highlights_gnome = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_gnome = "\n"; + +# these are pretty rough +my %highlights_man = ( $type_constant, "\$1", + $type_func, "\\\\fB\$1\\\\fP", + $type_struct, "\\\\fI\$1\\\\fP", + $type_param, "\\\\fI\$1\\\\fP" ); +my $blankline_man = ""; + +# text-mode +my %highlights_text = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +my $blankline_text = ""; + + +sub usage { + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; + print " c source file(s) > outputfile\n"; + exit 1; +} + +# read arguments +if ($#ARGV==-1) { + usage(); +} + +my $verbose = 0; +my $output_mode = "man"; +my %highlights = %highlights_man; +my $blankline = $blankline_man; +my $modulename = "Kernel API"; +my $function_only = 0; +my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', + 'July', 'August', 'September', 'October', + 'November', 'December')[(localtime)[4]] . + " " . ((localtime)[5]+1900); + +# Essentially these are globals +# They probably want to be tidied up made more localised or summat. +# CAVEAT EMPTOR! Some of the others I localised may not want to be which +# could cause "use of undefined value" or other bugs. +my ($function, %function_table,%parametertypes,$declaration_purpose); +my ($type,$declaration_name,$return_type); +my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map); + +# Generated docbook code is inserted in a template at a point where +# docbook v3.1 requires a non-zero sequence of RefEntry's; see: +# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html +# We keep track of number of generated entries and generate a dummy +# if needs be to ensure the expanded template can be postprocessed +# into html. +my $section_counter = 0; + +my $lineprefix=""; + +# states +# 0 - normal code +# 1 - looking for function name +# 2 - scanning field start. +# 3 - scanning prototype. +# 4 - documentation block +my $state; + +#declaration types: can be +# 'function', 'struct', 'union', 'enum', 'typedef' +my $decl_type; + +my $doc_special = "\@\%\$\&"; + +my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. +my $doc_end = '\*/'; +my $doc_com = '\s*\*\s*'; +my $doc_decl = $doc_com.'(\w+)'; +my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)'; +my $doc_content = $doc_com.'(.*)'; +my $doc_block = $doc_com.'DOC:\s*(.*)?'; + +my %constants; +my %parameterdescs; +my @parameterlist; +my %sections; +my @sectionlist; + +my $contents = ""; +my $section_default = "Description"; # default section +my $section_intro = "Introduction"; +my $section = $section_default; +my $section_context = "Context"; + +my $undescribed = "-- undescribed --"; + +reset_state(); + +while ($ARGV[0] =~ m/^-(.*)/) { + my $cmd = shift @ARGV; + if ($cmd eq "-html") { + $output_mode = "html"; + %highlights = %highlights_html; + $blankline = $blankline_html; + } elsif ($cmd eq "-man") { + $output_mode = "man"; + %highlights = %highlights_man; + $blankline = $blankline_man; + } elsif ($cmd eq "-text") { + $output_mode = "text"; + %highlights = %highlights_text; + $blankline = $blankline_text; + } elsif ($cmd eq "-docbook") { + $output_mode = "sgml"; + %highlights = %highlights_sgml; + $blankline = $blankline_sgml; + } elsif ($cmd eq "-gnome") { + $output_mode = "gnome"; + %highlights = %highlights_gnome; + $blankline = $blankline_gnome; + } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document + $modulename = shift @ARGV; + } elsif ($cmd eq "-function") { # to only output specific functions + $function_only = 1; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-nofunction") { # to only output specific functions + $function_only = 2; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-v") { + $verbose = 1; + } elsif (($cmd eq "-h") || ($cmd eq "--help")) { + usage(); + } elsif ($cmd eq '-filelist') { + $filelist = shift @ARGV; + } +} + + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +my $dohighlight = ""; +foreach my $pattern (keys %highlights) { +# print "scanning pattern $pattern ($highlights{$pattern})\n"; + $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; +} + +## +# dumps section contents to arrays/hashes intended for that purpose. +# +sub dump_section { + my $name = shift; + my $contents = join "\n", @_; + + if ($name =~ m/$type_constant/) { + $name = $1; +# print STDERR "constant section '$1' = '$contents'\n"; + $constants{$name} = $contents; + } elsif ($name =~ m/$type_param/) { +# print STDERR "parameter def '$1' = '$contents'\n"; + $name = $1; + $parameterdescs{$name} = $contents; + } else { +# print STDERR "other section '$name' = '$contents'\n"; + $sections{$name} = $contents; + push @sectionlist, $name; + } +} + +## +# output function +# +# parameterdescs, a hash. +# function => "function name" +# parameterlist => @list of parameters +# parameterdescs => %parameter descriptions +# sectionlist => @list of sections +# sections => %descriont descriptions +# + +sub output_highlight { + my $contents = join "\n",@_; + my $line; + +# DEBUG +# if (!defined $contents) { +# use Carp; +# confess "output_highlight got called with no args?\n"; +# } + + eval $dohighlight; + die $@ if $@; + foreach $line (split "\n", $contents) { + if ($line eq ""){ + print $lineprefix, $blankline; + } else { + $line =~ s/\\\\\\/\&/g; + print $lineprefix, $line; + } + print "\n"; + } +} + +#output sections in html +sub output_section_html(%) { + my %args = %{$_[0]}; + my $section; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
\n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } +} + +# output enum in html +sub output_enum_html(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "

enum ".$args{'enum'}."

\n"; + + print "enum ".$args{'enum'}." {
\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print " ".$parameter.""; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + print "
"; + } + print "};
\n"; + + print "

Constants

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output tyepdef in html +sub output_typedef_html(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "

typedef ".$args{'typedef'}."

\n"; + + print "typedef ".$args{'typedef'}."\n"; + output_section_html(@_); + print "
\n"; +} + +# output struct in html +sub output_struct_html(%) { + my %args = %{$_[0]}; + my ($parameter); + + print "

".$args{'type'}." ".$args{'struct'}."

\n"; + print "".$args{'type'}." ".$args{'struct'}." {
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter) ($2);
\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print " $1 $parameter$2;
\n"; + } else { + print " $type $parameter;
\n"; + } + } + print "};
\n"; + + print "

Members

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output function in html +sub output_function_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + print "

Function

\n"; + + print "".$args{'functiontype'}."\n"; + print "".$args{'function'}."\n"; + print "("; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "$1$parameter) ($2)"; + } else { + print "".$type." ".$parameter.""; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + } + print ")\n"; + + print "

Arguments

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output intro in html +sub output_intro_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
    \n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + +sub output_section_sgml(%) { + my %args = %{$_[0]}; + my $section; + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } +} + +# output function in sgml DocBook +sub output_function_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print "".$args{'function'}."\n"; + print "\n"; + print "\n"; + print " ".$args{'function'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." \n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + print "\n"; + + # print parameters + print "\n Arguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + output_section_sgml(@_); + print "\n\n"; +} + +# output struct in sgml DocBook +sub output_struct_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $id; + + $id = "API-struct-".$args{'struct'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print "".$args{'type'}." ".$args{'struct'}."\n"; + print "\n"; + print "\n"; + print " ".$args{'type'}." ".$args{'struct'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + defined($args{'parameterdescs'}{$parameter}) || next; + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print " $1 $parameter$2;\n"; + } else { + print " ".$type." ".$parameter.";\n"; + } + } + print "};"; + print " \n"; + print "\n"; + + print " \n"; + print " Members\n"; + + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + defined($args{'parameterdescs'}{$parameter}) || next; + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + print " "; + print " $parameter\n"; + print " \n"; + output_highlight($args{'parameterdescs'}{$parameter}); + print " \n"; + print " \n"; + } + print " \n"; + print " \n"; + + output_section_sgml(@_); + + print "\n\n"; +} + +# output enum in sgml DocBook +sub output_enum_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-enum-".$args{'enum'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print "enum ".$args{'enum'}."\n"; + print "\n"; + print "\n"; + print " enum ".$args{'enum'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print " $parameter"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ","; + } + print "\n"; + } + print "};"; + print " \n"; + print "\n"; + + print "\n"; + print " Constants\n"; + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " "; + print " $parameter\n"; + print " \n"; + output_highlight($args{'parameterdescs'}{$parameter}); + print " \n"; + print " \n"; + } + print " \n"; + print "\n"; + + output_section_sgml(@_); + + print "\n\n"; +} + +# output typedef in sgml DocBook +sub output_typedef_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $id; + + $id = "API-typedef-".$args{'typedef'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print "typedef ".$args{'typedef'}."\n"; + print "\n"; + print "\n"; + print " typedef ".$args{'typedef'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " typedef ".$args{'typedef'}.";\n"; + print "\n"; + + output_section_sgml(@_); + + print "\n\n"; +} + +# output in sgml DocBook +sub output_intro_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + my $id = $args{'module'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } + + print "\n\n"; +} + +# output in sgml DocBook +sub output_function_gnome { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}."-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print " ".$args{'function'}."\n"; + + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + print "\n"; + print "\n"; + print "\n"; + print "\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " $parameter\n"; + print " \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter}); + print " \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print "\n"; + output_highlight($args{'sections'}{$section}); + print "\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print " \n"; + } + + print "\n\n"; +} + +## +# output function in man +sub output_function_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'function'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + $count = 0; + my $parenth = "("; + my $post = ","; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count == $#{$args{'parameterlist'}}) { + $post = ");"; + } + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n"; + } + $count++; + $parenth = ""; + } + + print ".SH ARGUMENTS\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"", uc $section, "\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output enum in man +sub output_enum_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + print ".br\n.BI \" $parameter\"\n"; + if ($count == $#{$args{'parameterlist'}}) { + print "\n};\n"; + last; + } + else { + print ", \n.br\n"; + } + $count++; + } + + print ".SH Constants\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output struct in man +sub output_struct_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + + foreach my $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + print "\n.br\n"; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print ".BI \" ".$1."\" ".$parameter.$2." \""."\"\n;\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n"; + } + print "\n.br\n"; + } + print "};\n.br\n"; + + print ".SH Arguments\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output typedef in man +sub output_typedef_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +sub output_intro_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output in text +sub output_function_text(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print "Function:\n\n"; + my $start=$args{'functiontype'}." ".$args{'function'}." ("; + print $start; + my $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1.$parameter.") (".$2; + } else { + print $type." ".$parameter; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + print " " x length($start); + } else { + print ");\n\n"; + } + } + + print "Arguments:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print $parameter."\n\t".$args{'parameterdescs'}{$parameter}."\n"; + } + output_section_text(@_); +} + +#output sections in text +sub output_section_text(%) { + my %args = %{$_[0]}; + my $section; + + print "\n"; + foreach $section (@{$args{'sectionlist'}}) { + print "$section:\n\n"; + output_highlight($args{'sections'}{$section}); + } + print "\n\n"; +} + +# output enum in text +sub output_enum_text(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "Enum:\n\n"; + + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print "\t$parameter"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ","; + } + print "\n"; + } + print "};\n\n"; + + print "Constants:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "$parameter\n\t"; + print $args{'parameterdescs'}{$parameter}."\n"; + } + + output_section_text(@_); +} + +# output typedef in text +sub output_typedef_text(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "Typedef:\n\n"; + + print "typedef ".$args{'typedef'}."\n"; + output_section_text(@_); +} + +# output struct as text +sub output_struct_text(%) { + my %args = %{$_[0]}; + my ($parameter); + + print $args{'type'}." ".$args{'struct'}.":\n\n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "\t$1 $parameter) ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print "\t$1 $parameter$2;\n"; + } else { + print "\t".$type." ".$parameter.";\n"; + } + } + print "};\n\n"; + + print "Members:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($args{'parameterdescs'}{$parameter} ne $undescribed) || next; + print "$parameter\n\t"; + print $args{'parameterdescs'}{$parameter}."\n"; + } + print "\n"; + output_section_text(@_); +} + +sub output_intro_text(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + print " $section:\n"; + print " -> "; + output_highlight($args{'sections'}{$section}); + } +} + +## +# generic output function for typedefs +sub output_declaration { + no strict 'refs'; + my $name = shift; + my $functype = shift; + my $func = "output_${functype}_$output_mode"; + if (($function_only==0) || + ( $function_only == 1 && defined($function_table{$name})) || + ( $function_only == 2 && !defined($function_table{$name}))) + { + &$func(@_); + $section_counter++; + } +} + +## +# generic output function - calls the right one based +# on current output mode. +sub output_intro { + no strict 'refs'; + my $func = "output_intro_".$output_mode; + &$func(@_); + $section_counter++; +} + +## +# takes a declaration (struct, union, enum, typedef) and +# invokes the right handler. NOT called for functions. +sub dump_declaration($$) { + no strict 'refs'; + my ($prototype, $file) = @_; + my $func = "dump_".$decl_type; + &$func(@_); +} + +sub dump_union($$) { + dump_struct(@_); +} + +sub dump_struct($$) { + my $x = shift; + my $file = shift; + + if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) { + $declaration_name = $2; + my $members = $3; + + # ignore embedded structs or unions + $members =~ s/{.*}//g; + + create_parameterlist($members, ';', $file); + + output_declaration($declaration_name, + 'struct', + {'struct' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose, + 'type' => $decl_type + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse struct or union!\n"; + ++$errors; + } +} + +sub dump_enum($$) { + my $x = shift; + my $file = shift; + + if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { + $declaration_name = $1; + my $members = $2; + + foreach my $arg (split ',', $members) { + $arg =~ s/^\s*(\w+).*/$1/; + push @parameterlist, $arg; + if (!$parameterdescs{$arg}) { + $parameterdescs{$arg} = $undescribed; + print STDERR "Warning(${file}:$.): Enum value '$arg' ". + "not described in enum '$declaration_name'\n"; + } + + } + + output_declaration($declaration_name, + 'enum', + {'enum' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse enum!\n"; + ++$errors; + } +} + +sub dump_typedef($$) { + my $x = shift; + my $file = shift; + + while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { + $x =~ s/\(*.\)\s*;$/;/; + $x =~ s/\[*.\]\s*;$/;/; + } + + if ($x =~ /typedef.*\s+(\w+)\s*;/) { + $declaration_name = $1; + + output_declaration($declaration_name, + 'typedef', + {'typedef' => $declaration_name, + 'module' => $modulename, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; + ++$errors; + } +} + +sub create_parameterlist($$$) { + my $args = shift; + my $splitter = shift; + my $file = shift; + my $type; + my $param; + + while ($args =~ /(\([^\),]+),/) { + $args =~ s/(\([^\),]+),/$1#/g; + } + + foreach my $arg (split($splitter, $args)) { + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; + $arg =~ s/\s+/ /; + + if ($arg =~ m/\(/) { + # pointer-to-function + $arg =~ tr/#/,/; + $arg =~ m/[^\(]+\(\*([^\)]+)\)/; + $param = $1; + $type = $arg; + $type =~ s/([^\(]+\(\*)$param/$1/; + } else { + # evil magic to get fixed array parameters to work + $arg =~ s/(.+\s+)(.+)\[.*/$1* $2/; + my @args = split('\s', $arg); + + $param = pop @args; + if ($param =~ m/^(\*+)(.*)/) { + $param = $2; + push @args, $1; + } + elsif ($param =~ m/(.*?)\s*:\s*(\d+)/) { + $param = $1; + push @args, ":$2"; + } + $type = join " ", @args; + } + + if ($type eq "" && $param eq "...") + { + $type="..."; + $param="..."; + $parameterdescs{"..."} = "variable arguments"; + } + elsif ($type eq "" && ($param eq "" or $param eq "void")) + { + $type=""; + $param="void"; + $parameterdescs{void} = "no arguments"; + } + if (defined $type && $type && !defined $parameterdescs{$param}) { + $parameterdescs{$param} = $undescribed; + + if (($type eq 'function') || ($type eq 'enum')) { + print STDERR "Warning(${file}:$.): Function parameter ". + "or member '$param' not " . + "described in '$declaration_name'\n"; + } + print STDERR "Warning(${file}:$.): omitted parameter '$param'\n"; + ++$warnings; + } + + push @parameterlist, $param; + $parametertypes{$param} = $type; + } +} + +## +# takes a function prototype and the name of the current file being +# processed and spits out all the details stored in the global +# arrays/hashes. +sub dump_function($$) { + my $prototype = shift; + my $file = shift; + + $prototype =~ s/^static +//; + $prototype =~ s/^extern +//; + $prototype =~ s/^inline +//; + $prototype =~ s/^__inline__ +//; + $prototype =~ s/^#define +//; #ak added + + # Yes, this truly is vile. We are looking for: + # 1. Return type (may be nothing if we're looking at a macro) + # 2. Function name + # 3. Function parameters. + # + # All the while we have to watch out for function pointer parameters + # (which IIRC is what the two sections are for), C types (these + # regexps don't even start to express all the possibilities), and + # so on. + # + # If you mess with these regexps, it's a good idea to check that + # the following functions' documentation still comes out right: + # - parport_register_device (function pointer parameters) + # - atomic_set (macro) + # - pci_match_device (long return type) + + if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $return_type = $1; + $declaration_name = $2; + my $args = $3; + + create_parameterlist($args, ',', $file); + } else { + print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; + ++$errors; + return; + } + + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); +} + +sub process_file($); + +# Read the file that maps relative names to absolute names for +# separate source and object directories and for shadow trees. +if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { + my ($relname, $absname); + while() { + chop(); + ($relname, $absname) = (split())[0..1]; + $relname =~ s:^/+::; + $source_map{$relname} = $absname; + } + close(SOURCE_MAP); +} + +if ($filelist) { + open(FLIST,"<$filelist") or die "Can't open file list $filelist"; + while() { + chop; + process_file($_); + } +} + +foreach (@ARGV) { + chomp; + process_file($_); +} + +print STDERR "Warnings: $warnings\n"; +print STDERR "Errors: $errors\n"; +exit($errors); + +sub reset_state { + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + + $state = 0; +} + +sub process_state3_function($$) { + my $x = shift; + my $file = shift; + + if ($x =~ m#\s*/\*\s+MACDOC\s*#io) { + # do nothing + } + elsif ($x =~ /([^\{]*)/) { + $prototype .= $1; + } + if (($x =~ /\{/) || ($x =~ /\#/) || ($x =~ /;/)) { + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^\s+@@gos; # strip leading spaces + dump_function($prototype,$file); + reset_state(); + } +} + +sub process_state3_type($$) { + my $x = shift; + my $file = shift; + + $x =~ s@/\*.*?\*/@@gos; # strip comments. + $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $x =~ s@^\s+@@gos; # strip leading spaces + $x =~ s@\s+$@@gos; # strip trailing spaces + + while (1) { + if ( $x =~ /([^{};]*)([{};])(.*)/ ) { + $prototype .= $1 . $2; + ($2 eq '{') && $brcount++; + ($2 eq '}') && $brcount--; + if (($2 eq ';') && ($brcount == 0)) { + dump_declaration($prototype,$file); + reset_state(); + last; + } + $x = $3; + } else { + $prototype .= $x; + last; + } + } +} + +sub process_file($) { + my ($file) = @_; + my $identifier; + my $func; + my $initial_section_counter = $section_counter; + + if (defined($source_map{$file})) { + $file = $source_map{$file}; + } + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + $section_counter = 0; + while () { + if ($state == 0) { + if (/$doc_start/o) { + $state = 1; # next line is always the function name + } + } elsif ($state == 1) { # this line is the function name (always) + if (/$doc_block/o) { + $state = 4; + $contents = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_decl/o) { + $identifier = $1; + if (/\s*([\w\s]+?)\s*-/) { + $identifier = $1; + } + + $state = 2; + if (/-(.*)/) { + $declaration_purpose = $1; + } else { + $declaration_purpose = ""; + } + if ($identifier =~ m/^struct/) { + $decl_type = 'struct'; + } elsif ($identifier =~ m/^union/) { + $decl_type = 'union'; + } elsif ($identifier =~ m/^enum/) { + $decl_type = 'enum'; + } elsif ($identifier =~ m/^typedef/) { + $decl_type = 'typedef'; + } else { + $decl_type = 'function'; + } + + if ($verbose) { + print STDERR "Info(${file}:$.): Scanning doc for $identifier\n"; + } + } else { + print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.", + " - I thought it was a doc line\n"; + ++$warnings; + $state = 0; + } + } elsif ($state == 2) { # look for head: lines, and include content + if (/$doc_sect/o) { + $newsection = $1; + $newcontents = $2; + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + } + + $contents = $newcontents; + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + } elsif (/$doc_end/) { + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } + + $prototype = ""; + $state = 3; + $brcount = 0; +# print STDERR "end of doc comment, looking for prototype\n"; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "" && + ($section =~ m/^@/ || $section eq $section_context)) { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } else { + $contents .= $1."\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "Warning(${file}:$.): bad line: $_"; + ++$warnings; + } + } elsif ($state == 3) { # scanning for function { (end of prototype) + if ($decl_type eq 'function') { + process_state3_function($_, $file); + } else { + process_state3_type($_, $file); + } + } elsif ($state == 4) { + # Documentation block + if (/$doc_block/) { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_end/) + { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = 0; + } + elsif (/$doc_content/) + { + if ( $1 eq "" ) + { + $contents .= $blankline; + } + else + { + $contents .= $1 . "\n"; + } + } + } + } + if ($initial_section_counter == $section_counter) { + print STDERR "Warning(${file}): no structured comments found\n"; + if ($output_mode eq "sgml") { + # The template wants at least one RefEntry here; make one. + print "\n"; + print " \n"; + print " \n"; + print " ${file}\n"; + print " \n"; + print " \n"; + print " Document generation inconsistency\n"; + print " \n"; + print " \n"; + print " \n"; + print " \n"; + print " Oops\n"; + print " \n"; + print " \n"; + print " \n"; + print " The template for this document tried to insert\n"; + print " the structured comment from the file\n"; + print " ${file} at this point,\n"; + print " but none was found.\n"; + print " This dummy section is inserted to allow\n"; + print " generation to continue.\n"; + print " \n"; + print " \n"; + print " \n"; + print "\n"; + } + } +} diff --git a/doc/scripts/tmpl2sgml b/doc/scripts/tmpl2sgml new file mode 100755 index 0000000..9c0424f --- /dev/null +++ b/doc/scripts/tmpl2sgml @@ -0,0 +1,23 @@ +#!/usr/bin/perl +#warn "No digit found.\n"; + +use Env qw(PATH TMPL2SGML KERNELDOC); + +warn "Processing $ARGV[0]\n" ; +#warn "PATH=$PATH\n" ; +warn "KERNELDOC=$KERNELDOC\n" ; + +open (TMPLFILE, "$ARGV[0]"); + +while () { + $line=$_; + if($line=~m/^![EIF]/){ + ($srctype,$srcfile)= $line =~ /^!([EIF])(.*)$/ ; + warn "Found $srctype : $srcfile\n" ; + system "$KERNELDOC -docbook $srcfile"; + }else{ + print $line + } +} + +close TMPLFILE; -- 2.39.2