-
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