spec: Specify message storage free handler

1 files changed, 102 insertions, 30 deletions

diff --git a/spec/rtems/message/req/construct-errors.yml b/spec/rtems/message/req/construct.yml
index 56e94948..d259cfc3 100644
--- a/spec/rtems/message/req/construct-errors.yml
+++ b/spec/rtems/message/req/construct.yml
@@ -60,7 +60,7 @@ post-conditions:
       id = 0;
       sc = rtems_message_queue_ident( NAME, RTEMS_SEARCH_LOCAL_NODE, &id );
       T_rsc_success( sc );
-      T_eq_u32( id, ctx->id_value );
+      T_eq_u32( id, ctx->id_obj );
     text: |
       The unique object name shall identify the message queue constructed by
       the ${../if/construct:/name} call.
@@ -74,12 +74,12 @@ post-conditions:
   test-prologue: |
     rtems_status_code sc;
     rtems_id          id;
-- name: IdVar
+- name: IdObj
   states:
   - name: Set
     test-code: |
-      T_eq_ptr( ctx->id, &ctx->id_value );
-      T_ne_u32( ctx->id_value, INVALID_ID );
+      T_eq_ptr( ctx->id, &ctx->id_obj );
+      T_ne_u32( ctx->id_obj, INVALID_ID );
     text: |
       The value of the object referenced by the
       ${../if/construct:/params[1]/name} parameter shall be set to the object
@@ -87,19 +87,35 @@ post-conditions:
       ${../if/construct:/name} call.
   - name: Nop
     test-code: |
-      T_eq_u32( ctx->id_value, INVALID_ID );
+      T_eq_u32( ctx->id_obj, INVALID_ID );
     text: |
       Objects referenced by the ${../if/construct:/params[1]/name} parameter in
       past calls to ${../if/construct:/name} shall not be accessed by the
       ${../if/construct:/name} call.
   test-epilogue: null
   test-prologue: null
+- name: StorageFree
+  states:
+  - name: Free
+    test-code: |
+      ctx->expected_storage_free_counter = 1;
+    text: |
+      The storage free handler of the message queue configuration specified by
+      the ${../if/construct:/params[0]/name} parameter shall be used to free
+      the message queue storage area.
+  - name: Nop
+    test-code: |
+      ctx->expected_storage_free_counter = 0;
+    text: |
+      No operation shall be performed to free the message queue storage area.
+  test-epilogue: null
+  test-prologue: null
 pre-conditions:
 - name: Config
   states:
   - name: Valid
     test-code: |
-      ctx->config = &ctx->config_value;
+      ctx->config = &ctx->config_obj;
     text: |
       While the ${../if/construct:/params[0]/name} parameter references an
       object of type ${../if/config:/name}.
@@ -115,12 +131,12 @@ pre-conditions:
   states:
   - name: Valid
     test-code: |
-      ctx->config_value.name = NAME;
+      ctx->config_obj.name = NAME;
     text: |
       While the name of the message queue configuration is valid.
   - name: Invalid
     test-code: |
-      ctx->config_value.name = 0;
+      ctx->config_obj.name = 0;
     text: |
       While the name of the message queue configuration is invalid.
   test-epilogue: null
@@ -129,7 +145,7 @@ pre-conditions:
   states:
   - name: Id
     test-code: |
-      ctx->id = &ctx->id_value;
+      ctx->id = &ctx->id_obj;
     text: |
       While the ${../if/construct:/params[1]/name} parameter references an
       object of type ${../../type/if/id:/name}.
@@ -145,19 +161,19 @@ pre-conditions:
   states:
   - name: Valid
     test-code: |
-      ctx->config_value.maximum_pending_messages = MAX_PENDING_MESSAGES;
+      ctx->config_obj.maximum_pending_messages = MAX_PENDING_MESSAGES;
     text: |
       While the maximum number of pending messages of the message queue
       configuration is valid.
   - name: Zero
     test-code: |
-      ctx->config_value.maximum_pending_messages = 0;
+      ctx->config_obj.maximum_pending_messages = 0;
     text: |
       While the maximum number of pending messages of the message queue
       configuration is zero.
   - name: Big
     test-code: |
-      ctx->config_value.maximum_pending_messages = UINT32_MAX;
+      ctx->config_obj.maximum_pending_messages = UINT32_MAX;
     text: |
       While the maximum number of pending messages of the message queue
       configuration is big enough so that a calculation to get the message
@@ -168,30 +184,30 @@ pre-conditions:
   states:
   - name: Valid
     test-code: |
-      if ( ctx->config_value.maximum_pending_messages == UINT32_MAX ) {
+      if ( ctx->config_obj.maximum_pending_messages == UINT32_MAX ) {
         /*
          * At least on 64-bit systems we need a bit of help to ensure that we
          * meet the Big state of the MaxPending pre-condition.  The following
          * message size is valid with respect to calculations involving only
          * the message size.
          */
-        ctx->config_value.maximum_message_size = SIZE_MAX - sizeof( uintptr_t ) +
+        ctx->config_obj.maximum_message_size = SIZE_MAX - sizeof( uintptr_t ) +
           1 - sizeof( CORE_message_queue_Buffer );
       } else {
-        ctx->config_value.maximum_message_size = MAX_MESSAGE_SIZE;
+        ctx->config_obj.maximum_message_size = MAX_MESSAGE_SIZE;
       }
     text: |
       While the maximum message size of the message queue configuration is
       valid.
   - name: Zero
     test-code: |
-      ctx->config_value.maximum_message_size = 0;
+      ctx->config_obj.maximum_message_size = 0;
     text: |
       While the maximum message size of the message queue configuration is
       zero.
   - name: Big
     test-code: |
-      ctx->config_value.maximum_message_size = SIZE_MAX;
+      ctx->config_obj.maximum_message_size = SIZE_MAX;
     text: |
       While the maximum message size of the message queue configuration is big
       enough so that a calculation to get the message buffer storage area size
@@ -219,13 +235,13 @@ pre-conditions:
   states:
   - name: Valid
     test-code: |
-      ctx->config_value.storage_area = buffers;
+      ctx->config_obj.storage_area = buffers;
     text: |
       While the message buffer storage area begin pointer of the message queue
       configuration is valid.
   - name: 'Null'
     test-code: |
-      ctx->config_value.storage_area = NULL;
+      ctx->config_obj.storage_area = NULL;
     text: |
       While the message buffer storage area begin pointer of the message queue
       configuration is ${/c/if/null:/name}.
@@ -235,18 +251,34 @@ pre-conditions:
   states:
   - name: Valid
     test-code: |
-      ctx->config_value.storage_size = sizeof( buffers );
+      ctx->config_obj.storage_size = sizeof( buffers );
     text: |
       While the message buffer storage area size of the message queue
       configuration is valid.
   - name: Invalid
     test-code: |
-      ctx->config_value.storage_size = SIZE_MAX;
+      ctx->config_obj.storage_size = SIZE_MAX;
     text: |
       While the message buffer storage area size of the message queue
       configuration is invalid.
   test-epilogue: null
   test-prologue: null
+- name: StorageFree
+  states:
+  - name: 'Null'
+    test-code: |
+      ctx->config_obj.storage_free = NULL;
+    text: |
+      While the storage free member of the message queue configuration is
+      equal to ${/c/if/null:/name}.
+  - name: Handler
+    test-code: |
+      ctx->config_obj.storage_free = StorageFree;
+    text: |
+      While the storage free member of the message queue configuration
+      references a storage free handler.
+  test-epilogue: null
+  test-prologue: null
 rationale: null
 references: []
 requirement-type: functional
@@ -255,13 +287,15 @@ test-action: |
   ctx->status = rtems_message_queue_construct( ctx->config, ctx->id );
 test-brief: null
 test-cleanup: |
-  if ( ctx->id_value != INVALID_ID ) {
+  if ( ctx->id_obj != INVALID_ID ) {
     rtems_status_code sc;
 
-    sc = rtems_message_queue_delete( ctx->id_value );
+    sc = rtems_message_queue_delete( ctx->id_obj );
     T_rsc_success( sc );
 
-    ctx->id_value = INVALID_ID;
+    T_eq_u32( ctx->storage_free_counter, ctx->expected_storage_free_counter );
+  } else {
+    T_eq_u32( ctx->storage_free_counter, 0 );
   }
 
   T_surrender_objects( &ctx->seized_objects, rtems_message_queue_delete );
@@ -277,7 +311,7 @@ test-context:
 - brief: null
   description: null
   member: |
-    rtems_message_queue_config config_value
+    rtems_message_queue_config config_obj
 - brief: null
   description: null
   member: |
@@ -285,11 +319,19 @@ test-context:
 - brief: null
   description: null
   member: |
-    rtems_id id_value
+    rtems_id id_obj
 - brief: null
   description: null
   member: |
     void *seized_objects
+- brief: null
+  description: null
+  member: |
+    uint32_t storage_free_counter
+- brief: null
+  description: null
+  member: |
+    uint32_t expected_storage_free_counter
 test-context-support: null
 test-description: null
 test-header: null
@@ -299,8 +341,10 @@ test-includes:
 test-local-includes:
 - tx-support.h
 test-prepare: |
-  ctx->id_value = INVALID_ID;
-  memset( &ctx->config_value, 0, sizeof( ctx->config_value ) );
+  ctx->id_obj = INVALID_ID;
+  ctx->storage_free_counter = 0;
+  ctx->expected_storage_free_counter = UINT32_MAX;
+  memset( &ctx->config_obj, 0, sizeof( ctx->config_obj ) );
 test-setup: null
 test-stop: null
 test-support: |
@@ -312,6 +356,8 @@ test-support: |
 
   #define MAX_MESSAGE_SIZE 1
 
+  typedef ${.:/test-context-type} Context;
+
   static RTEMS_MESSAGE_QUEUE_BUFFER( MAX_MESSAGE_SIZE )
     buffers_to_seize[ MAX_MESSAGE_QUEUES ][ MAX_PENDING_MESSAGES ];
 
@@ -338,7 +384,16 @@ test-support: |
 
     return rtems_message_queue_construct( &config, id );
   }
-test-target: testsuites/validation/tc-message-construct-errors.c
+
+  static void StorageFree( void *ptr )
+  {
+    Context *ctx;
+
+    ctx = T_fixture_context();
+    T_eq_ptr( ptr, buffers );
+    ++ctx->storage_free_counter;
+  }
+test-target: testsuites/validation/tc-message-construct.c
 test-teardown: null
 text: ${.:text-template}
 transition-map:
@@ -392,12 +447,28 @@ transition-map:
           Status: Ok
       then: Valid
     - else: Invalid
-    IdVar:
+    IdObj:
     - if:
         post-conditions:
           Status: Ok
       then: Set
     - else: Nop
+    StorageFree:
+    - if:
+        and:
+        - post-conditions:
+            Status: Ok
+        - pre-conditions:
+            StorageFree: 'Null'
+      then: Nop
+    - if:
+        and:
+        - post-conditions:
+            Status: Ok
+        - pre-conditions:
+            StorageFree: Handler
+      then: Free
+    - else: N/A
   pre-conditions:
     Area: all
     AreaSize: all
@@ -407,4 +478,5 @@ transition-map:
     MaxSize: all
     Name: all
     Free: all
+    StorageFree: all
 type: requirement