spec: Specify APBUART support functions

12 files changed, 289 insertions, 21 deletions

diff --git a/spec/dev/grlib/if/apbuart-inbyte-polled.yml b/spec/dev/grlib/if/apbuart-inbyte-nonblocking.yml
index 408825d7..408825d7 100644
--- a/spec/dev/grlib/if/apbuart-inbyte-polled.yml
+++ b/spec/dev/grlib/if/apbuart-inbyte-nonblocking.yml
diff --git a/spec/dev/grlib/if/load-08.yml b/spec/dev/grlib/if/load-08.yml
new file mode 100644
index 00000000..c781ba99
--- /dev/null
+++ b/spec/dev/grlib/if/load-08.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_8
+references: {}
+type: interface
diff --git a/spec/dev/grlib/if/load-16.yml b/spec/dev/grlib/if/load-16.yml
new file mode 100644
index 00000000..b06bf7ad
--- /dev/null
+++ b/spec/dev/grlib/if/load-16.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_16
+references: {}
+type: interface
diff --git a/spec/dev/grlib/if/load-64.yml b/spec/dev/grlib/if/load-64.yml
new file mode 100644
index 00000000..a51ac6aa
--- /dev/null
+++ b/spec/dev/grlib/if/load-64.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_64
+references: {}
+type: interface
diff --git a/spec/dev/grlib/if/store-08.yml b/spec/dev/grlib/if/store-08.yml
new file mode 100644
index 00000000..c781ba99
--- /dev/null
+++ b/spec/dev/grlib/if/store-08.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_8
+references: {}
+type: interface
diff --git a/spec/dev/grlib/if/store-16.yml b/spec/dev/grlib/if/store-16.yml
new file mode 100644
index 00000000..b06bf7ad
--- /dev/null
+++ b/spec/dev/grlib/if/store-16.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_16
+references: {}
+type: interface
diff --git a/spec/dev/grlib/if/store-32.yml b/spec/dev/grlib/if/store-32.yml
new file mode 100644
index 00000000..5627eb28
--- /dev/null
+++ b/spec/dev/grlib/if/store-32.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_32
+references: {}
+type: interface
diff --git a/spec/dev/grlib/if/store-64.yml b/spec/dev/grlib/if/store-64.yml
new file mode 100644
index 00000000..a51ac6aa
--- /dev/null
+++ b/spec/dev/grlib/if/store-64.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: io-header
+name: grlib_load_64
+references: {}
+type: interface
diff --git a/spec/dev/grlib/req/apbuart-inbyte-nonblocking.yml b/spec/dev/grlib/req/apbuart-inbyte-nonblocking.yml
new file mode 100644
index 00000000..bfc24430
--- /dev/null
+++ b/spec/dev/grlib/req/apbuart-inbyte-nonblocking.yml
@@ -0,0 +1,109 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+functional-type: action
+links:
+- role: interface-function
+  uid: ../if/apbuart-inbyte-nonblocking
+post-conditions:
+- name: Result
+  states:
+  - name: Data
+    test-code: |
+      T_eq_int( ctx->result, 0xff );
+    text: |
+      The return value of ${../if/apbuart-inbyte-nonblocking:/name} shall be
+      the data read from the data register of the register block specified by
+      ${../if/apbuart-inbyte-nonblocking:/params[0]/name}.
+  - name: MinusOne
+    test-code: |
+      T_eq_int( ctx->result, -1 );
+    text: |
+      The return value of ${../if/apbuart-inbyte-nonblocking:/name} shall be
+      minus one.
+  test-epilogue: null
+  test-prologue: null
+- name: ErrorFlags
+  states:
+  - name: Cleared
+    test-code: |
+      T_eq_u32( ctx->regs.status & 0x78, 0 );
+    text: |
+      The framing error, parity error, overrun, and break received flags in the
+      status register of the register block specified by
+      ${../if/apbuart-inbyte-nonblocking:/params[0]/name} shall be cleared.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: DataReady
+  states:
+  - name: 'Yes'
+    test-code: |
+      ctx->regs.status |= APBUART_STATUS_DR;
+    text: |
+      While the data ready flag is set in the status register of the register
+      block specified by ${../if/apbuart-inbyte-nonblocking:/params[0]/name}
+      parameter.
+  - name: 'No'
+    test-code: |
+      ctx->regs.status &= ~APBUART_STATUS_DR;
+    text: |
+      While the data ready flag is cleared in the status register of the
+      register block specified by
+      ${../if/apbuart-inbyte-nonblocking:/params[0]/name} parameter.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons: {}
+test-action: |
+  ctx->result = apbuart_inbyte_nonblocking( &ctx->regs );
+test-brief: null
+test-cleanup: null
+test-context:
+- brief: |
+    This member provides the APBUART register block.
+  description: null
+  member: |
+    apbuart regs
+- brief: |
+    This member contains the return value of the
+    ${../if/apbuart-inbyte-nonblocking:/name} call.
+  description: null
+  member: |
+    int result
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- grlib/apbuart.h
+- string.h
+test-local-includes: []
+test-prepare: |
+  memset( &ctx->regs, 0, sizeof( ctx->regs ) );
+  ctx->regs.status = 0x78;
+  ctx->regs.data = 0xff;
+test-setup: null
+test-stop: null
+test-support: null
+test-target: testsuites/validation/tc-dev-grlib-apbuart-inbyte-nonblocking.c
+test-teardown: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Result: Data
+    ErrorFlags: Cleared
+  pre-conditions:
+    DataReady:
+    - 'Yes'
+- enabled-by: true
+  post-conditions:
+    Result: MinusOne
+    ErrorFlags: Cleared
+  pre-conditions:
+    DataReady:
+    - 'No'
+type: requirement
diff --git a/spec/dev/grlib/req/apbuart-outbyte-polled.yml b/spec/dev/grlib/req/apbuart-outbyte-polled.yml
new file mode 100644
index 00000000..78c4ff22
--- /dev/null
+++ b/spec/dev/grlib/req/apbuart-outbyte-polled.yml
@@ -0,0 +1,18 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/apbuart-outbyte-polled
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/apbuart-outbyte-polled:/name} directive shall wait until the
+  transmitter FIFO is empty and then write the characters specified by
+  ${../if/apbuart-outbyte-polled:/params[1]/name} as an unsigned 8-bit value to
+  the data register of the register block specified by
+  ${../if/apbuart-outbyte-polled:/params[0]/name}.
+type: requirement
diff --git a/spec/dev/grlib/req/apbuart-outbyte-wait.yml b/spec/dev/grlib/req/apbuart-outbyte-wait.yml
new file mode 100644
index 00000000..12adde89
--- /dev/null
+++ b/spec/dev/grlib/req/apbuart-outbyte-wait.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/apbuart-outbyte-wait
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/apbuart-outbyte-wait:/name} directive shall wait until the
+  transmitter FIFO is empty indicated by the status register of the register
+  block specified by ${../if/apbuart-outbyte-wait:/params[0]/name}.
+type: requirement
diff --git a/spec/bsp/sparc/val/grlib-io.yml b/spec/dev/grlib/val/io.yml
index 411c2524..bfa41313 100644
--- a/spec/bsp/sparc/val/grlib-io.yml
+++ b/spec/dev/grlib/val/io.yml
@@ -5,7 +5,7 @@ enabled-by: true
 links: []
 test-actions:
 - action-brief: |
-    Call ${../if/grlib-load-08:/name} to load a prepared value.
+    Call ${../if/load-08:/name} to load a prepared value.
   action-code: |
     uint8_t reg_8;
     uint8_t val_8;
@@ -19,10 +19,10 @@ test-actions:
       T_step_eq_u8( ${step}, val_8, 0x81 );
     links:
     - role: validation
-      uid: ../req/grlib-load-08
+      uid: /bsp/sparc/req/grlib-load-08
   links: []
 - action-brief: |
-    Call ${../if/grlib-load-16:/name} to load a prepared value.
+    Call ${../if/load-16:/name} to load a prepared value.
   action-code: |
     uint16_t reg_16;
     uint16_t val_16;
@@ -36,10 +36,10 @@ test-actions:
       T_step_eq_u16( ${step}, val_16, 0x8001 );
     links:
     - role: validation
-      uid: ../req/grlib-load-16
+      uid: /bsp/sparc/req/grlib-load-16
   links: []
 - action-brief: |
-    Call ${../if/grlib-load-32:/name} to load a prepared value.
+    Call ${../if/load-32:/name} to load a prepared value.
   action-code: |
     uint32_t reg_32;
     uint32_t val_32;
@@ -53,10 +53,10 @@ test-actions:
       T_step_eq_u32( ${step}, val_32, 0x80000001 );
     links:
     - role: validation
-      uid: ../req/grlib-load-32
+      uid: /bsp/sparc/req/grlib-load-32
   links: []
 - action-brief: |
-    Call ${../if/grlib-load-64:/name} to load a prepared value.
+    Call ${../if/load-64:/name} to load a prepared value.
   action-code: |
     uint64_t reg_64;
     uint64_t val_64;
@@ -70,10 +70,10 @@ test-actions:
       T_step_eq_u64( ${step}, val_64, 0x8000000000000001 );
     links:
     - role: validation
-      uid: ../req/grlib-load-64
+      uid: /bsp/sparc/req/grlib-load-64
   links: []
 - action-brief: |
-    Call ${../if/grlib-store-08:/name} to store a value to an object.
+    Call ${../if/store-08:/name} to store a value to an object.
   action-code: |
     uint8_t reg_8;
 
@@ -85,10 +85,10 @@ test-actions:
       T_step_eq_u8( ${step}, reg_8, 0x81 );
     links:
     - role: validation
-      uid: ../req/grlib-store-08
+      uid: /bsp/sparc/req/grlib-store-08
   links: []
 - action-brief: |
-    Call ${../if/grlib-store-16:/name} to store a value to an object.
+    Call ${../if/store-16:/name} to store a value to an object.
   action-code: |
     uint16_t reg_16;
 
@@ -100,10 +100,10 @@ test-actions:
       T_step_eq_u16( ${step}, reg_16, 0x8001 );
     links:
     - role: validation
-      uid: ../req/grlib-store-16
+      uid: /bsp/sparc/req/grlib-store-16
   links: []
 - action-brief: |
-    Call ${../if/grlib-store-32:/name} to store a value to an object.
+    Call ${../if/store-32:/name} to store a value to an object.
   action-code: |
     uint32_t reg_32;
 
@@ -115,10 +115,10 @@ test-actions:
       T_step_eq_u32( ${step}, reg_32, 0x80000001 );
     links:
     - role: validation
-      uid: ../req/grlib-store-32
+      uid: /bsp/sparc/req/grlib-store-32
   links: []
 - action-brief: |
-    Call ${../if/grlib-store-64:/name} to store a value to an object.
+    Call ${../if/store-64:/name} to store a value to an object.
   action-code: |
     uint64_t reg_64;
 
@@ -130,20 +130,61 @@ test-actions:
       T_step_eq_u64( ${step}, reg_64, 0x8000000000000001 );
     links:
     - role: validation
-      uid: ../req/grlib-store-64
+      uid: /bsp/sparc/req/grlib-store-64
+  links: []
+- action-brief: |
+    Call ${../if/apbuart-outbyte-polled:/name} to store a character to the data
+    register.  The transmitter FIFO shall be initially non-empty.  The status
+    is checked by ${../if/apbuart-outbyte-wait:/name}.
+  action-code: |
+    apbuart regs;
+
+    memset( &regs, 0, sizeof( regs ) );
+    SetIORelaxHandler( ApbuartIORelax, &regs );
+    apbuart_outbyte_polled( &regs, (char) 0xff );
+    SetIORelaxHandler( NULL, NULL );
+  checks:
+  - brief: |
+      Check that the transmitter FIFO empty flag was set by ApbuartIORelax().
+    code: |
+      T_step_eq_u32( ${step}, regs.status, APBUART_STATUS_TE );
+    links:
+    - role: validation
+      uid: ../req/apbuart-outbyte-wait
+    - role: validation
+      uid: ../req/apbuart-outbyte-polled
+  - brief: |
+      Check that the data register was written by
+      ${../if/apbuart-outbyte-polled:/name}.
+    code: |
+      T_step_eq_u32( ${step}, regs.data, 0xff );
+    links:
+    - role: validation
+      uid: ../req/apbuart-outbyte-polled
   links: []
 test-brief: |
-  Tests the SPARC-specific GRLIB API.
+  Tests some ${../if/group:/name} directives.
 test-context: []
 test-context-support: null
 test-description: null
 test-header: null
 test-includes:
-- dev/grlib/io.h
-test-local-includes: []
+- grlib/apbuart.h
+- grlib/io.h
+- string.h
+test-local-includes:
+- tx-support.h
 test-setup: null
 test-stop: null
-test-support: null
-test-target: testsuites/validation/tc-bsp-sparc-leon3.c
+test-support: |
+  static void ApbuartIORelax( void *arg )
+  {
+    apbuart *regs;
+
+    regs = arg;
+    regs->status = 0x4;
+    T_quiet_eq_u32( regs->data, 0 );
+  }
+test-target: testsuites/validation/tc-dev-grlib-io.c
 test-teardown: null
 type: test-case