DIRECTION DU CENTRE SPATIAL DE TOULOUSE
SOUS-DIRECTION TECHNIQUES VEHICULE, ARCHITECTURE & INTEGRATION
SERVICE INFORMATIQUE BORD & EQUIPEMENTS
Edit. : 3
Rév. : 0
Nbre pages : 13
Réf. : DCT/TV/IN/2014-9100 Date : 05/12/2014
Siège : 2 place Maurice Quentin - 75039 Paris cedex 01 - Tél. : 33 (0)1 44 76 75 00 - www.cnes.fr Direction des lanceurs : 52 rue Jacques Hillairet - 75612 Paris cedex - Tél. : 33 (0)1 80 97 71 11 Centre spatial de Toulouse : 18 avenue Edouard Belin - 31401 Toulouse cedex 9 - Tél. : 33 (0)5 61 27 31 31 Centre spatial guyanais : BP 726 - 97387 Kourou cedex - Tél. : 594 (0)5 94 33 51 11
RCS Paris B 775 665 912 Siret 775 665 912 000 82 code APE 731 Z N° d’identification TVA FR 49 775 6 65 912
VHDL Handbook XML Schema language specification
MOTS CLES : VHDL, XML, HANDBOOK, RULES, GUIDELINES
RÉSUMÉ : This document defines the XML architecture of the foreseen VHDL Handbook and its formatted exports documents.
Writers Head of Departments
G. LIABEUF DCT/TV/AV
F. MANNI DCT/TV/IN
C. VINCENDET
DCT/TV/AV
P. LE MEUR DCT/TV/IN
Diffusion : DCT/AQ/SO AT. NGUYEN, A. DUPUIS, G. NAVARRO, M. MAURIN DCT/AQ/CQ J. CARRON DCT/TV/IN All DCT/TV/AV All
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 2
CONFIDENTIALITY – KEY WORDS - SUMMARY
Confidentiality Level Security N° Num of Pages
Yes No 13
Key words VHDL,XML ,HANDBOOK, RULES, GUIDELINES
Summary VHL handbook XML Schema definition
MODIFICATIONS Modifications are listed in the change record section of the document and are identified by a vertical bar in the left margin.
Ed. Rev. Date Modified pages
1 0 16/06/14 Initial release
2 0 18/09/14 Update for handbook flow (XML, PDF…) and exports
3 0 28/11/14 Update for EnumSeverity and EnumTech possibilities and toolchain
ABBRÉVIATIONS
Abbr. Definition
XSLT Extensible Stylesheet Language Transformations
XSD XML Schema Definition
XML eXtensible Markup Language
APPLICABLE AND REFERENCE DOCUMENTS
Reference documents
Title Description
DR1 http://www.w3.org/TR/xmlschema-0/#Intro
XML schema definition
DR2 http://www.w3schools.com/xml/default.asp
XML tutorials
DR3 http://www.w3.org/TR/NOTE-xml-schema-req
XML Schema requirements
EXTERNAL DIFFUSION LIST
Company Name
Altran DANIEL Arnaud [email protected]
http://www.w3.org/TR/xmlschema-0/#Introhttp://www.w3.org/TR/xmlschema-0/#Introhttp://www.w3schools.com/xml/default.asphttp://www.w3schools.com/xml/default.asphttp://www.w3.org/TR/NOTE-xml-schema-reqhttp://www.w3.org/TR/NOTE-xml-schema-reqmailto:[email protected]
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 3
Table of contents
1 INTRODUCTION ............................................................................................................... 4
2 SCHEMA SPECIFICATION ............................................................................................... 5
3 XML EXPORTED DOCUMENTS ...................................................................................... 9 3.1 SPREADSHEET EXPORT ................................................................................................ 9 3.2 PDF EXPORT .................................................................................................................. 10
3.2.1 TOOLCHAIN DESCRIPTION ...................................................................................... 10 3.2.2 VHDL HANDBOOK ..................................................................................................... 10 3.2.2.1 VHDL HANDBOOK STRUCTURE ........................................................................... 11 3.2.2.2 RULE SECTION3 FORMAT ..................................................................................... 12
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 4
1 INTRODUCTION XML is designed to transport and store data.
"The purpose of the XML schema language is to provide an inventory of XML markup constructs with which to write schemas".
The purpose of a schema is to define and describe a class of XML documents by using these constructs to constrain and document the meaning, usage and relationships of their constituent parts: datatypes, elements and their content, attributes and their values, entities and their contents and notations. Schema constructs may also provide for the specification of implicit information such as default values. Schemas document their own meaning, usage, and function.
Thus, the XML schema language can be used to define, describe and catalogue XML vocabularies for classes of XML documents.
Any application of XML can use the Schema formalism to express syntactic, structural and value constraints applicable to its document instances. The Schema formalism will allow a useful level of constraint checking to be described and validated for a wide spectrum of XML applications. For applications which require other, arbitrary or complicated constraints, the application must perform its own additional validations. [DR3].
This document describes the XML schema (that is the backbone) of the foreseen XML VHDL Handbook.
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 5
2 SCHEMA SPECIFICATION The table located below represents the Handbook rule set structure: Gray fields: correspond to complex elements | Italic data : correspond to simple text data field
Hierarchie and element name Description Format Request to fill the text in the XML handbook Instances
RuleSet VHDL handbook document including all the rules Element mandatory 1
|-> Rule One VHDL Rule content Element mandatory *
|-> |-> UID Rule Unique identifier attribute Attribute exactly the same value as RuleUID mandatory 1
| |-> RuleUID Rule unique Identifier Subset of ID which allows only one format: "3 upercase letters" + "_" + "4 digits". Each ID is unique mandatory and unique amongst all rules
1
| |-> RuleHist History of the VHDL Rule Element mandatory 1
| | |-> Status Current status of the rule Text selected amongst EnumRuleStatus possibilities mandatory 1
| | |-> Version Rule current version number Text which contains an Integer mandatory 1
| | |-> Creation Rule date of creation Text which contains a date mandatory 1
| | |-> Modified Rule date of last modification Text which contains a date mandatory 1
| | |-> Revision Rule Revision history Text (paragraph) mandatory 1
| | |-> Origin Original reference of the rule Text (line) Mandatory but can be left empty 1
| | |-> Comment Rule General comment Text (paragraph) Mandatory but can be left empty 1
| |-> RuleContent Group of information relating to the content of the Rule Element mandatory 1
| | |-> Name Name of the Rule Text (one line) mandatory 1
| | |-> IsParent True if the rule is parent of others rules. False otherwise Boolean Mandatory 1
| | |-> IsSon True if the rule is son of a rule. False otherwise Boolean Mandatory 1
| | |-> ParentUID RuleUID of the parent. Must be filled only if IsSon is true IDREF (referring to RuleUID value) Mandatory but can be left empty 1
| | |-> Technology Physical component targetted by the rule Text selected amongst EnumTech possibilities mandatory 1
| | |-> ApplicationFields Specifies fields of application (spatial, avionic, etc.) List of text selected amongst ListAppliFieds possibilities mandatory 1
| | |-> Category Technical field category targetted by the rule Text selected amongst EnumCat possibilities mandatory 1
| | |-> SubCategory General thematic subcategory for the rule Text selected amongst EnumSubCat possibilities mandatory 1
| | |-> Severity Severity of the rule Text selected amongst EnumSeverity possibilities mandatory 1
| | |-> Rationale Justification of the existence of the rule Text (paragraph) mandatory 1
| | |-> ShortDes Rule short description Text (one line) mandatory 1
| | |-> LongDesc Rule long description Text (paragraph) mandatory 1
| |-> RuleDesc explanation regarding the Rule Element optional 0-1
| | |-> GoodExDesc Description in plain text of the example Text (paragraph) Mandatory but can be left empty 1
| | |-> GoodExample Rule Example Text (VHDL paragraph) Mandatory but can be left empty 1
| | |-> BadExDesc Description in plain text of the counter example Text (paragraph) Mandatory but can be left empty 1
| | |-> BadExample Rule Counter Example Text (VHDL paragraph) Mandatory but can be left empty 1
| | |-> FigureDesc Description in plain text of the figure (legend) Text (paragraph) Mandatory but can be left empty 1
| | |-> Figure Figure to illustrate the rule PNG with 3 attributes for the path, height and width of the figure Mandatory but can be left empty 1
|-> RuleSetHist History of the VHDL Rule Set Element Mandatory 1
| |-> Version RuleSet current version number Text which contains an Integer mandatory 1
| |-> Creation RuleSet date of creation Text which contains a date mandatory 1
| |-> Modified RuleSet date of last modification Text which contains a date mandatory 1
| |-> Revision RuleSet Revision history Text (paragraph) mandatory 1
| |-> Origin Original reference of the ruleset Text (line) Mandatory but can be left empty 1
| |-> Comment Rule General comment Text (paragraph) Mandatory but can be left empty 1
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 6
Enumeration name Possibilities Description
EnumRuleStatus
Draft Rule in draft version with name and origin
In progress Rule currently being filled
Release candidate Rule finished: ready for first stage review
To be Discussed Rule needs to be analyzed and discussed
Modified Rule has been modified since the last release
Validated Rule ready for second stage review
Rejected Rule was rejected – needs to be reworked or deleted
Active Rule final version after every reviews
Deleted Rule is no longer part of the handbook
EnumTech
ASIC Selected when the rule targets ASIC components
FPGA Selected when the rule targets FPGA components
VLSI Selected when the rule targets all the previous components (FPGA and ASIC)
ListAppliFields
Avionic Rule is specific to Avionic application field
Defense Rule is specific to Defense application field
General Rule is not specific to an application field
Media Rule is specific to Media application field
Nuclear Rule is specific to Nuclear application field
Railway Rule is specific to Railway application field
Spatial Rule is specific to Spatial application field
Telecom Rule is specific to Telecom application field
EnumCat
Design Selected when the rule targets architectural VHDL design
Formatting Selected when the rule targets on the way of formatting VHDL code
Simulation Selected when the rule targets VHDL Simulation oriented modules only
Traceability Selected when the rule targets on the way of tracing VHDL code
EnumSeverity
Major Selected when the rule is mandatory. Any deviation to a Major rule must be reported in a Non-Conformance Report and must be agreed by customer
Minor Selected when rule might be critical. Non-conformance to a Minor rule can be approved in dedicated meeting, without Non-Conformance Report
Note Selected when rule is for information only. The handbook user is responsible for the application (or not ) of this rule
EnumSubCat
Clocking Selected when the rule targets Clocks generation, domain change, clock tree.
Combinational Selected when the rule targets combinational elements.
FileStructure Selected when the rule targets source file structure (architecture, entity, ports mapping…).
I/O Selected when the rule targets Input and Output component elements
Miscellaneous Selected when the rule does not target any previous SubCat
Naming Selected when the rule targets naming of files, signals or entity names.
Requirement Selected when the rule targets the link between specifications document and VHDL code
Reset Selected when the rule targets Reset mechanism.
Reuse Selected when the rule targets the reuse of any element from a previous development or for a future one.
StateMachine Selected when the rule targets FSM in particular.
Synchronous Selected when the rule targets synchronous process structure and behavior.
Type Selected when the rule targets signals, port and generic typing
Versioning Selected when the rule targets versioning and file management topics
Reliability Selected when the rule targets reliability topics
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 7
Rule->RuleUID field is formatted as follows: LLL_DDDDD with L representing a Letter and D a Digit. Some three letters match is reserved:
Acronym Description
ADS Airbus Defense and Space specific rule
ALT Altran specific rule
CNE CNES specific rule
ERM Erems specific rule
ESA ESA specific rule
SOD Sodern specific rule
STE Steel Electronique specific rule
TAS Thalès Alenia Space specific rule
TSA Thales Système Aeroporté specific rule
STD VHDL handbook global rule
TMP Draft/Temporary rule
Note: Rule->RuleContent->UID rule attribute shall be exactly the same as Rule->RuleContent->RuleUID. It will ease the identification of a rule (by its UID) while using eclipse.
Rule->RuleContent->Category and Rule->RuleContent->SubCategory fields shall be filled as follows (where + indicates match availability and – indicates forbidden match)
EnumCat
Design Formatting Traceability Simulation
EnumsubCat
Clocking + - - -
Combinational + - - -
FileStructure - + - -
I/O + - - -
Miscellaneous + + + +
Naming - + - -
Requirement - - + -
Reset + - - -
Reuse - - + -
StateMachine + - - -
Synchronous + - - -
Type + - - -
Versioning - - + -
Reliability + - - -
Rule->RuleContent->IsParent is selected to true if there is a rule identified as its son which exists inside the Ruleset. A parent shall not be a son of another rule (that is nested parenting is not allowed).
Rule->RuleContent->IsSon field is selected to true if the rule is an additional enhancement to a dedicated parent rule (identified by a unique ParentUID value).
Parent and Son rules shall have the same category/subcategory value.
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 8
RuleSetHist ->Revision and Rule->RuleHist->Revision are used to records changes. Those fields are fulfilled as follow:
- RuleSetHist ->Revision V1: yyyy-mm-dd: Creation V2: yyyy-mm-dd: "Information about the V2 release" …
- Rule->RuleHist->Revision
V1: yyyy-mm-dd: Creation V2: yyyy-mm-dd: "Modified Fields for V2 rule release" …
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 9
3 XML EXPORTED DOCUMENTS Two different types of exports are foreseen for the xml data formatted with this schema: Spreadsheet application (Excel, Openoffice…) and PDF.
3.1 SPREADSHEET EXPORT Recent Spreadsheet software can directly open XML file and convert them to ".xlsx" which is the spreadsheet XML standard format.
The extract below (from Wikipedia) list the minimum version required to deal with such data: "
Microsoft Office 2007 for Windows uses the Office Open XML format as the default.
Older versions of Microsoft Office (2000, XP and 2003) require a free compatibility pack provided
by Microsoft.[24]
It is available for Windows 2000 Service Pack 4 and newer operating systems. The
compatibility pack does not require Microsoft Office, but does require Microsoft Windows. It can be
used as a standalone converter with products that read Office's older binary formats, such
as OpenOffice.org.[26]
OpenOffice.org has built-in support for opening Office Open XML text spreadsheets beginning with
OpenOffice.org version 3.0 (October 2008). It is available for Windows 2000/XP/Vista, Mac OS X
(Intel/PowerPC), Linux, Solaris, FreeBSD (*BSD)[33]
"
Spreadsheet is foreseen to be used with:
Applicability matrix: The minimum required columns, from the XML handbook, for this documents are:
ns1:RuleUID ns1:Version ns1:Name ns1:Category ns1:SubCategory ns1:Severity ns1:ShortDesc Additional columns shall be added and filled by the user: applicability and comments.
Conformance matrix: The minimum required columns are the same as the applicability matrix plus extra columns for conformance status and comments if needed.
Verification matrix: The minimum required columns are the same as the conformance matrix plus extra columns for verification status and comments if needed.
Handbook peer review document: This document will be an enhanced xlsx spreadsheet including:
o All the columns from the original xml file. These columns will be locked for writing. o An extra empty column for each of the previous ones reserved for reviewer to insert
its modification. o An extra column for additional comment.
Note: conditional formatting will be used to improve identification of modified fields.
http://en.wikipedia.org/wiki/List_of_software_that_supports_Office_Open_XMLhttp://en.wikipedia.org/wiki/Microsoft_Office_2007http://en.wikipedia.org/wiki/Microsoft_Office_2000http://en.wikipedia.org/wiki/Microsoft_Office_XPhttp://en.wikipedia.org/wiki/Microsoft_Office_2003http://en.wikipedia.org/wiki/List_of_software_that_supports_Office_Open_XML#cite_note-omso-24http://en.wikipedia.org/wiki/Windows_2000http://en.wikipedia.org/wiki/Microsoft_Windowshttp://en.wikipedia.org/wiki/OpenOffice.orghttp://en.wikipedia.org/wiki/List_of_software_that_supports_Office_Open_XML#cite_note-oooninjaocp-26http://en.wikipedia.org/wiki/OpenOffice.orghttp://en.wikipedia.org/wiki/List_of_software_that_supports_Office_Open_XML#cite_note-OpenOffice.org_3.0_New_Features-33
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 10
3.2 PDF EXPORT Export from XML to PDF file is not straight forward. It needs several transformation steps describes below. The main exported document will be the VHDL Handbook.
3.2.1 TOOLCHAIN DESCRIPTION The toolchain is summarized within the figure below.
1. Handbook xml files are created within the supervision of the handbook.xsd schema.
2. These xml files are merged to obtain one xml file with all rules defined using Saxon processor. The stylesheet used for this merge is merge.xsl.
3. This xml merged file is sorted according to Erreur ! Source du renvoi introuvable. chapter on “Standard Rules” field using Saxon processor. The sorting process is defined inside sort.xsl stylesheet.
4. This xml sorted file is then converted to a standard docbook file using of the Saxon processor. Format of the final docbook is defined inside the stylesheet used for this conversion (convert2docbook.xsl).
5. The docbook is converted to an xml file object using Saxon processor. This conversion use docbook standard stylesheet for processing.
6. The formatted object is then converted to the final pdf using Apache FOP processor.
3.2.2 VHDL HANDBOOK The automatically generated pdf file (from the original XML one) is the VHDL Handbook. This document will be the "official" applicable document. Other documents (like the XML file, spreadsheet exports…) will be addressed as reference document.
This document will self-sufficient (including goals and rule and their description) for an ASIC/FPGA designer to develop its component.
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 11
3.2.2.1 VHDL HANDBOOK STRUCTURE The information within the handbook is structured as follow:
A TITLE: The VHDL Handbook title is “Design & VHDL handbook for VLSI development” in order to address not only VHDL topics but also Design topics.
AN INTRODUCTION: The introduction paragraph includes at least information from the RuleSet-> RuleSetHist field.
A GREETINGS CHAPTER: The greeting is used to thank every partner involved in this handbook project
A GLOSSARY: This chapter introduces convention used inside the handbook.
A VERSION HISTORY CHAPTER: This chapter introduces the version history of the handbook. This chapter is formatted as follow:
Version RuleSetHist=>Version
Modification Date RuleSetHist=> Modified
Revision RuleSetHist=> Revision
A CHAPTER INCLUDING ALL "STANDARD RULES" o A section for each EnumCat possibility. Each section starts at the top of page with a
title including the name of the EnumCat and a section number. A subsection2 for each EnumSubCat possibility. Each section starts with a
title including the name of the EnumSubCat and a section number.
A section3 for each rule of the current EnumCat/EnumSubCat type. Rules are sorted (in this order of importance) by Severity (Rule then Goal, then Hint), RuleUID (increasing number) and parenting (that is child must be written just below its parent). No section number for this section.
CHAPTER INCLUDING ALL "CUSTOM RULES" This chapter is formatted like the standard rule chapter.
A CONCLUSION
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 12
3.2.2.2 RULE SECTION3 FORMAT A rule is formatted in two parts:
A table introducing rule main topics fulfilled with the appropriate XML fields.
A description area Fields are only display on the pdf file if the dedicated XML field is not empty.
The format is described below:
RuleUID RuleContent =>Name RuleContent=> Severity
Revision RuleHist=>Version / RuleHist=> Modified
Classification RuleContent=>Technology / RuleContent=>Category / RuleContent=>SubCategory
Application Field RuleContent=> ApplicationField
Parent Rule RuleContent=> ParentUID
Description RuleContent=> ShortDescription
The "RuleContent=> ParentUID" section is monitored thanks to “Rule->RuleContent->IsSon".
When "Rule->RuleContent->IsSon" is fulfilled with "False", then the handbook tool publishes "N/A" to indicates that this filed is Not Available.
When "Rule->RuleContent->IsSon" is fulfilled with "True", then the handbook tool publishes "RuleContent=> ParentUID" content.
o DETAILED DESCRIPTION
This area concerns the XML LongDescription field. It is always published (the field is never left empty). If no extra information is needed, it is suggested that the user writes written "No additional information".
o FIGURE This area concerns the XML Figure field. It is published only if the @fileref associated to Figure is not empty. The publishing is ordered as followed:
- A paragraph introducing the FigureDesc. If no extra information is available yet, it is suggested that the user writes "To be done for next release".
- A dedicated area for Figure.
o RATIONALE This area concerns the XML Rationale field. It is always published (the field is never left empty).
Réf. CNES : DCT/TV/IN/2014-9100 Edit. : 3 Rév. : 0 Date : 05/12/2014 Page 13
o GOOD EXAMPLE
This area concerns the XML GoodExample field. This area is published only if the GoodExDesc associated to GoodExample is is not empty. The publishing is ordered as followed:
- A paragraph introducing the GoodExDesc. If no extra information is available yet, it is suggested that the user writes "To be done for next release".
- A dedicated area for GoodExample. This area is published framed with a grey bottom.
GoodExample
o BAD EXAMPLE
This area concerns the XML BadExample field. This area is published only if the BadExDesc associated to BadExample is is not empty. The publishing is ordered as followed:
- A paragraph introducing the BadExDesc If no extra information is available yet, ti is suggested that the user writes “To be done for next release”
- A dedicated area for BadExample. This area is published framed with a grey bottom
BadExample