[PATCH 2/2] c-user: Generate message manager documentation

[Sebastian Huber]

On 22/04/2021 17:44, Gedare Bloom wrote:

>> +.. index:: RTEMS_MESSAGE_QUEUE_BUFFER()
>> +
>> +.. _InterfaceRTEMSMESSAGEQUEUEBUFFER:
>> +
>> +RTEMS_MESSAGE_QUEUE_BUFFER()
> Before now, this was not well documented. It is good to add, but I
> wonder if this is also a good time to make it more like other
> macro-based declarations?
I would like to document what we have first and then in a second step 
change the API if necessary.
> RTEMS_MESSAGE_QUEUE_BUFFER_DECLARE()?
>
> This is not strictly related to this patch, but it could be an
> opportunity to provide a uniform API for variable declarations. I
> guess it could be made more clear that  this defines a type.

One problem is that RTEMS_MESSAGE_QUEUE_ is already quite long. We have 
to balance precision and the name length.

An RTEMS_MESSAGE_QUEUE_BUFFER_TYPE( maximum_message_size ) could be an 
option. I think the current use in the code is quite readable:

#define MESSAGE_SIZE 1

static RTEMS_MESSAGE_QUEUE_BUFFER( MESSAGE_SIZE ) buffers[ 1 ];

static const rtems_message_queue_config config = {
   .name = rtems_build_name( 'M', 'S', 'G', '2' ),
   .maximum_pending_messages = RTEMS_ARRAY_SIZE( buffers ),
   .maximum_message_size = MESSAGE_SIZE,
   .storage_area = buffers,
   .storage_size = sizeof( buffers ),
   .attributes = RTEMS_GLOBAL
};

We could add an

RTEMS_MESSAGE_QUEUE_BUFFER_DEFINE( designator, maximum_message_size, maximum_pending_messages )

convenience macro in addition to RTEMS_MESSAGE_QUEUE_BUFFER().

A declare AND define macro is a bit difficult since you would need exactly one buffer type definition I guess. This is one of the reasons for the type macro. You can embed the message buffers in a custom structure type.

> Maybe,
> the API should have some way to simplify declaring/defining variables
> of this type as well?
>
> RTEMS_MESSAGE_QUEUE_BUFFER_DEFINE( name, maximum_message_size )
> RTEMS_MESSAGE_QUEUE_BUFFER_DEFINE_ARRAY( name, maximum_message_size, array_size)
>
> RTEMS_MESSAGE_QUEUE_CONFIG_DECLARE ( config_name, mq_name,
> maximum_message_size, num_buffers, attributes)
> can even further simplify things to provide an API for these static
> objects. This should be taken up separately from the doco, just
> something came to my mind while reading this, due to the addition of
> this API macro to the documentation.
For the config, we could add a

RTEMS_MESSAGE_QUEUE_CONFIG_INITIALIZER()

macro. However, this is less readable than the C version with designated initializers.

>
-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/