From aa0060f4c15e37b76d0a22be3ba21c9dca70eb87 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 3 Feb 2021 06:08:21 +0100 Subject: rtems: Clarify partition manager documentation Unify the wording across similar directives of other managers. Add "Constraints" paragraph. Update #3993. --- cpukit/include/rtems/rtems/part.h | 168 ++++++++++++++++++++++++++++---------- 1 file changed, 124 insertions(+), 44 deletions(-) (limited to 'cpukit/include/rtems/rtems/part.h') diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h index 4979f8a987..337e28c18b 100644 --- a/cpukit/include/rtems/rtems/part.h +++ b/cpukit/include/rtems/rtems/part.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -99,7 +99,7 @@ extern "C" { * * @brief Creates a partition. * - * @param name is the name of the partition. + * @param name is the object name of the partition. * * @param starting_address is the starting address of the buffer area used by * the partition. @@ -113,34 +113,40 @@ extern "C" { * @param attribute_set is the attribute set of the partition. * * @param[out] id is the pointer to an object identifier variable. The - * identifier of the created partition object will be stored in this - * variable, in case of a successful operation. + * identifier of the created partition will be stored in this variable, in + * case of a successful operation. * * This directive creates a partition of fixed size buffers from a physically * contiguous memory space which starts at ``starting_address`` and is * ``length`` bytes in size. Each allocated buffer is to be of ``buffer_size`` - * in bytes. The assigned object identifier is returned in ``id``. This + * in bytes. The partition has the user-defined object name specified in + * ``name``. The assigned object identifier is returned in ``id``. This * identifier is used to access the partition with other partition related * directives. * * The **attribute set** specified in ``attribute_set`` is built through a - * *bitwise or* of the attribute constants described below. Attributes not - * mentioned below are not evaluated by this directive and have no effect. - * - * The partition can have **local** or **global** scope in a multiprocessing - * network (this attribute does not refer to SMP systems). - * - * * A **local** scope is the default and can be emphasized through the use of + * *bitwise or* of the attribute constants described below. Not all + * combinations of attributes are allowed. Some attributes are mutually + * exclusive. If mutually exclusive attributes are combined, the behaviour is + * undefined. Attributes not mentioned below are not evaluated by this + * directive and have no effect. Default attributes can be selected by using + * the #RTEMS_DEFAULT_ATTRIBUTES constant. + * + * The partition has a local or global **scope** in a multiprocessing network + * (this attribute does not refer to SMP systems). The scope is selected by + * the mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL attributes. + * + * * A **local scope** is the default and can be emphasized through the use of * the #RTEMS_LOCAL attribute. A local partition can be only used by the * node which created it. * - * * A **global** scope is established if the #RTEMS_GLOBAL attribute is set. + * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set. * The memory space used for the partition must reside in shared memory. * Setting the global attribute in a single node system has no effect. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * @retval ::RTEMS_INVALID_NAME The partition name was invalid. + * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid. * * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. * @@ -161,14 +167,17 @@ extern "C" { * on a pointer size boundary. * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a - * new partition. The number of partitions available to the application is - * configured through the #CONFIGURE_MAXIMUM_PARTITIONS configuration option. + * partition. The number of partitions available to the application is + * configured through the #CONFIGURE_MAXIMUM_PARTITIONS application + * configuration option. + * + * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no + * inactive global object available to create a global semaphore. The number + * of global objects available to the application is configured through the + * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @par Notes * @parblock - * This directive may cause the calling task to be preempted due to an obtain - * and release of the object allocator mutex. - * * The partition buffer area specified by the ``starting_address`` must be * properly aligned. It must be possible to directly store target architecture * pointers and also the user data. For example, if the user data contains @@ -193,10 +202,31 @@ extern "C" { * global partition. When a global partition is created, the partition's name * and identifier must be transmitted to every node in the system for insertion * in the local copy of the global object table. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. * - * The total number of global objects, including partitions, is limited by the - * value of the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * * The number of partitions available to the application is configured + * through the #CONFIGURE_MAXIMUM_PARTITIONS application configuration + * option. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may allocate memory from the RTEMS + * Workspace. + * + * * The number of global objects available to the application is configured + * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration + * option. * @endparblock */ rtems_status_code rtems_partition_create( @@ -254,18 +284,30 @@ rtems_status_code rtems_partition_create( * If the partition name is not unique, then the partition identifier will * match the first partition with that name in the search order. However, this * partition identifier is not guaranteed to correspond to the desired - * partition. The partition identifier is used with other partition related - * directives to access the partition. + * partition. * - * If node is #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local - * node being searched first. All other nodes are searched with the lowest - * numbered node searched first. + * The objects are searched from lowest to the highest index. If ``node`` is + * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being + * searched first. All other nodes are searched from lowest to the highest + * node number. * * If node is a valid node number which does not represent the local node, then * only the partitions exported by the designated node are searched. * * This directive does not generate activity on remote nodes. It accesses only * the local copy of the global object table. + * + * The partition identifier is used with other partition related directives to + * access the partition. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. * @endparblock */ rtems_status_code rtems_partition_ident( @@ -283,8 +325,7 @@ rtems_status_code rtems_partition_ident( * * @param id is the partition identifier. * - * This directive deletes the partition specified by the ``id`` parameter. The - * partition cannot be deleted if any of its buffers are still allocated. + * This directive deletes the partition specified by ``id``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -299,14 +340,10 @@ rtems_status_code rtems_partition_ident( * * @par Notes * @parblock - * This directive may cause the calling task to be preempted due to an obtain - * and release of the object allocator mutex. + * The partition cannot be deleted if any of its buffers are still allocated. * * The PTCB for the deleted partition is reclaimed by RTEMS. * - * The calling task does not have to be the task that created the partition. - * Any local task that knows the partition identifier can delete the partition. - * * When a global partition is deleted, the partition identifier must be * transmitted to every node in the system for deletion from the local copy of * the global object table. @@ -314,6 +351,25 @@ rtems_status_code rtems_partition_ident( * The partition must reside on the local node, even if the partition was * created with the #RTEMS_GLOBAL attribute. * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The calling task does not have to be the task that created the object. + * Any local task that knows the object identifier can delete the object. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may free memory to the RTEMS Workspace. + * @endparblock */ rtems_status_code rtems_partition_delete( rtems_id id ); @@ -331,8 +387,8 @@ rtems_status_code rtems_partition_delete( rtems_id id ); * successful operation. * * This directive allows a buffer to be obtained from the partition specified - * in the ``id`` parameter. The address of the allocated buffer is returned - * through the ``buffer`` parameter. + * by ``id``. The address of the allocated buffer is returned through the + * ``buffer`` parameter. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -346,8 +402,6 @@ rtems_status_code rtems_partition_delete( rtems_id id ); * * @par Notes * @parblock - * This directive will not cause the running task to be preempted. - * * The buffer start alignment is determined by the memory area and buffer size * used to create the partition. * @@ -357,6 +411,23 @@ rtems_status_code rtems_partition_delete( rtems_id id ); * node will generate a request telling the remote node to allocate a buffer * from the partition. * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * When the directive operates on a local object, the directive may be called + * from within interrupt context. + * + * * The directive may be called from within task context. + * + * * When the directive operates on a local object, the directive will not + * cause the calling task to be preempted. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer ); @@ -383,15 +454,24 @@ rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer ); * in the partition. * * @par Notes + * Returning a buffer multiple times is an error. It will corrupt the internal + * state of the partition. + * + * @par Constraints * @parblock - * This directive will not cause the running task to be preempted. + * The following constraints apply to this directive: * - * Returning a buffer to a global partition which does not reside on the local - * node will generate a request telling the remote node to return the buffer to - * the partition. + * * When the directive operates on a local object, the directive may be called + * from within interrupt context. * - * Returning a buffer multiple times is an error. It will corrupt the internal - * state of the partition. + * * The directive may be called from within task context. + * + * * When the directive operates on a local object, the directive will not + * cause the calling task to be preempted. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. * @endparblock */ rtems_status_code rtems_partition_return_buffer( rtems_id id, void *buffer ); -- cgit v1.2.3