aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJavier Olaechea <pirata@gmail.com>2020-05-15 21:55:19 -0500
committerJavier Olaechea <pirata@gmail.com>2020-05-16 23:20:50 -0500
commit8a917e52d9034d7bdaa5e14a8777eb5e6450273e (patch)
tree7eb6180ce7f4f2ad674d54064159573236c9e660
parentb0fd860da07d197e4cc7084e7643a55be1253aba (diff)
downloadcl-xcb-8a917e52d9034d7bdaa5e14a8777eb5e6450273e.tar.gz
Developer Manual: Document how switch tags work
-rw-r--r--docs/developer-manual.md85
1 files changed, 85 insertions, 0 deletions
diff --git a/docs/developer-manual.md b/docs/developer-manual.md
new file mode 100644
index 0000000..d658a97
--- /dev/null
+++ b/docs/developer-manual.md
@@ -0,0 +1,85 @@
+# XCB Protocol
+## Cookie
+## Setup
+## Switch tags
+
+Some requests have a variable number of fields. The mechanism by which
+this is accomplished is a switch expression and a value mask. The
+value mask is used to determine which fields are included. There are
+two strategies, bitcase and case.
+
+In the case of the `bitcase` tag the nth bit of the value mask is
+compared with the bitcase expression. If the expression is true then
+that field is included in the request. An example definition can be
+found in sync.xml:
+
+```xml
+<request name="CreateAlarm" opcode="8">
+ <field type="ALARM" name="id" />
+ <field type="CARD32" name="value_mask" mask="CA" />
+ <switch name="value_list">
+ <fieldref>value_mask</fieldref>
+ <bitcase>
+ <enumref ref="CA">Counter</enumref>
+ <field type="COUNTER" name="counter" />
+ </bitcase>
+ <bitcase>
+ <enumref ref="CA">ValueType</enumref>
+ <field type="CARD32" name="valueType" enum="VALUETYPE" />
+ </bitcase>
+ <bitcase>
+ <enumref ref="CA">Value</enumref>
+ <field type="sync:INT64" name="value" />
+ </bitcase>
+ <bitcase>
+ <enumref ref="CA">TestType</enumref>
+ <field type="CARD32" name="testType" enum="TESTTYPE" />
+ </bitcase>
+ <bitcase>
+ <enumref ref="CA">Delta</enumref>
+ <field type="sync:INT64" name="delta" />
+ </bitcase>
+ <bitcase>
+ <enumref ref="CA">Events</enumref>
+ <field type="CARD32" name="events" />
+ </bitcase>
+ </switch>
+</request>
+```
+
+In the case of the `case` tag the value mask is compared using
+equality. If true then the group of fields inside the case tag are
+included in the request. An example definition can be found in
+xinput.xml:
+
+```xml
+<struct name="InputInfo">
+ <field type="CARD8" name="class_id" enum="InputClass" />
+ <field type="CARD8" name="len" />
+ <switch name="info">
+ <fieldref>class_id</fieldref>
+ <required_start_align align="4" offset="2" />
+ <case name="key">
+ <enumref ref="InputClass">Key</enumref>
+ <field type="KeyCode" name="min_keycode" />
+ <field type="KeyCode" name="max_keycode" />
+ <field type="CARD16" name="num_keys" />
+ <pad bytes="2" />
+ </case>
+ <case name="button">
+ <enumref ref="InputClass">Button</enumref>
+ <field type="CARD16" name="num_buttons" />
+ </case>
+ <case name="valuator">
+ <enumref ref="InputClass">Valuator</enumref>
+ <required_start_align align="4" offset="2" />
+ <field type="CARD8" name="axes_len" />
+ <field type="CARD8" name="mode" enum="ValuatorMode" />
+ <field type="CARD32" name="motion_size" />
+ <list type="AxisInfo" name="axes">
+ <fieldref>axes_len</fieldref>
+ </list>
+ </case>
+ </switch>
+</struct>
+```