VHDL Handbook XML Schema language specification...VHDL Handbook XML Schema language specification MOTS CLES : VHDL, XML, HANDBOOK, RULES, GUIDELINES RÉSUMÉ : This document defines

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]


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


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.


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


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


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.


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" …


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


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.


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


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).


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

Documents

VHDL Handbook XML Schema language specification...VHDL Handbook XML Schema language specification MOTS CLES : VHDL, XML, HANDBOOK, RULES, GUIDELINES RÉSUMÉ : This document defines