The seL4 API has three common error codes

• seL4_IllegalOperation
• seL4_InvalidCapability
• seL4_TruncatedMessage
  as described inSeparate documentation for common error codes in kernel object API #622

I've replaced the text in the descriptions in the xml files, E.g.

<error name="seL4_IllegalOperation">    <description>        The <texttt text='_service'/> is a CPtr to a capability of the wrong type    </description></error>

is now

<error name="seL4_IllegalOperation">    <description>        &illegal_operation;    </description></error>

There are a few problems with this approach.

1. Global variable declaration is done at the top of each api xml file. I'm too new to xml and python to place the global variable declaration into a single file (e.g. py code) such that it can be called or added to each api xml file.

2. The text strings that describe error messages are too long. I aimed to include a useful error message + a link to a table with common error codes, e.g.

illegal_operation = "The_service is a CPtr to a capability of the wrong type (seeerror:illegal_operation in common error codes)"
whereerror:illegal_operation links to a common error codes table

The long strings are particularly unreadable when there are multiple error codes
E.g.
10.3.3 seL4_IRQControl
10.3.3.1 Get
seL4_IllegalOperation On x86, an IOAPIC is being used. Or, the _service is a CPtr to a capability of the wrong type (see seL4_IllegalOperation in common error codes)

This could be made readable by listing the error codes
E.g.
10.3.3 seL4_IRQControl
10.3.3.1 Get
seL4_IllegalOperation

• On x86, an IOAPIC is being used.
• Or, the _service is a CPtr to a capability of the wrong type (see seL4_IllegalOperation in common error codes)

But I'm struggling with the xml and python, can can't figure out how to include lists in the descriptions of errors.

@Indanz@lsf37 Any suggestions/hints?