object.h

开放源码的嵌入式开发环境

 */
#define OBJECTS_WHO_AM_I           0

/**
 *  This macros calculates the lowest ID for the specified api, class,
 *  and node.
 */
#define OBJECTS_ID_INITIAL(_api, _class, _node) \
  _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )

/**
 *  This macro specifies the highest object ID value
 */
#define OBJECTS_ID_FINAL           ((Objects_Id)~0)

/**
 *  This function performs the initialization necessary for this handler.
 *
 *  @param[in] node indicates the identifying number of this node.
 *  @param[in] maximum_nodes is the maximum number of nodes in this system.
 *  @param[in] maximum_global_objects is maximum number of global objects
 *             concurrently offered in the system.
 */
void _Objects_Handler_initialization(
  uint32_t   node,
  uint32_t   maximum_nodes,
  uint32_t   maximum_global_objects
);

/**
 *  This function extends an object class information record.
 *
 *  @param[in] information points to an object class information block.
 */
void _Objects_Extend_information(
  Objects_Information *information
);

/**
 *  This function shrink an object class information record.
 *
 *  @param[in] information points to an object class information block.
 */
void _Objects_Shrink_information(
  Objects_Information *information
);

/**
 *  This function initializes an object class information record.
 *  SUPPORTS_GLOBAL is TRUE if the object class supports global
 *  objects, and FALSE otherwise.  Maximum indicates the number
 *  of objects required in this class and size indicates the size
 *  in bytes of each control block for this object class.  The
 *  name length and string designator are also set.  In addition,
 *  the class may be a task, therefore this information is also included.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] the_api indicates the API associated with this information block.
 *  @param[in] the_class indicates the class of object being managed
 *             by this information block.  It is specific to @a the_api.
 *  @param[in] maximum is the maximum number of instances of this object
 *             class which may be concurrently active.
 *  @param[in] size is the size of the data structure for this class.
 *  @param[in] is_string is TRUE if this object uses string style names.
 *  @param[in] maximum_name_length is the maximum length of object names.
 */
void _Objects_Initialize_information (
  Objects_Information *information,
  Objects_APIs         the_api,
  uint32_t             the_class,
  uint32_t             maximum,
  uint16_t             size,
  boolean              is_string,
  uint32_t             maximum_name_length
#if defined(RTEMS_MULTIPROCESSING)
  ,
  boolean              supports_global,
  Objects_Thread_queue_Extract_callout extract
#endif
);

/**
 *  This function allocates a object control block from
 *  the inactive chain of free object control blocks.
 *
 *  @param[in] information points to an object class information block.
 */
Objects_Control *_Objects_Allocate(
  Objects_Information *information
);

/**
 *  This function allocates the object control block
 *  specified by the index from the inactive chain of
 *  free object control blocks.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] index is the index of the object to allocate.
 *  @param[in] sizeof_control is the size of the object control block.
 */
Objects_Control *_Objects_Allocate_by_index(
  Objects_Information *information,
  uint16_t             index,
  uint16_t             sizeof_control
);

/**
 *
 *  This function frees a object control block to the
 *  inactive chain of free object control blocks.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] the_object points to the object to deallocate.
 */
void _Objects_Free(
  Objects_Information *information,
  Objects_Control     *the_object
);

/**
 *  This method zeroes out the name.
 *
 *  @param[in] name points to the name to be zeroed out.
 *  @param[in] length is the length of the object name field.
 */
void _Objects_Clear_name(
  void       *name,
  uint16_t    length
);

/**
 *  This method copies a string style object name from source to destination.
 *
 *  @param[in] source is the source name to copy.
 *  @param[in] destination is the destination of the copy.
 *  @param[in] length is the number of bytes to copy.
 */
void _Objects_Copy_name_string(
  void       *source,
  void       *destination,
  uint16_t    length
);

/**
 *  This method copies a raw style object name from source to destination.
 *
 *  @param[in] source is the source name to copy.
 *  @param[in] destination is the destination of the copy.
 *  @param[in] length is the number of bytes to copy.
 */
void _Objects_Copy_name_raw(
  void       *source,
  void       *destination,
  uint16_t    length
);

/**
 *  This method compares two string style object names.
 *
 *  @param[in] name_1 is the left hand name to compare.
 *  @param[in] name_2 is the right hand name to compare.
 *  @param[in] length is the length of the names to compare.
 */
boolean _Objects_Compare_name_string(
  void       *name_1,
  void       *name_2,
  uint16_t    length
);

/**
 *  This method compares two raw style object names.
 *
 *  @param[in] name_1 is the left hand name to compare.
 *  @param[in] name_2 is the right hand name to compare.
 *  @param[in] length is the length of the names to compare.
 */
boolean _Objects_Compare_name_raw(
  void       *name_1,
  void       *name_2,
  uint16_t    length
);

/**
 *  This function implements the common portion of the object
 *  identification directives.  This directive returns the object
 *  id associated with name.  If more than one object of this class
 *  is named name, then the object to which the id belongs is
 *  arbitrary.  Node indicates the extent of the search for the
 *  id of the object named name.  If the object class supports global
 *  objects, then the search can be limited to a particular node
 *  or allowed to encompass all nodes.
 */
typedef enum {
  OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL,
  OBJECTS_INVALID_NAME,
  OBJECTS_INVALID_ADDRESS,
  OBJECTS_INVALID_ID,
  OBJECTS_INVALID_NODE
} Objects_Name_or_id_lookup_errors;

/** This macro defines the first entry in the
 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
 */
#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL

/** This macro defines the last entry in the
 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
 */
#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE

/**
 *  This method converts an object name to an Id.  It performs a look up
 *  using the object information block for this object class.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] name is the name of the object to find.
 *  @param[in] node is the set of nodes to search.
 *  @param[in] id will contain the Id if the search is successful.
 *
 *  @return This method returns one of the values from the 
 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
 *          successful or failure.  On success @a id will contain the Id of
 *          the requested object.
 */
Objects_Name_or_id_lookup_errors _Objects_Name_to_id(
  Objects_Information *information,
  Objects_Name         name,
  uint32_t             node,
  Objects_Id          *id
);

/**
 *  This function implements the common portion of the object Id
 *  to name directives.  This function returns the name
 *  associated with object id.
 *
 *  @param[in] id is the Id of the object whose name we are locating.
 *  @param[in] name will contain the name of the object, if found.
 *
 *  @return This method returns one of the values from the 
 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
 *          successful or failure.  On success @a name will contain the name of
 *          the requested object.
 *
 *  @note This function currently does not support string names.
 */
Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
  Objects_Id      id,
  Objects_Name   *name
);

/**
 *  This function maps object ids to object control blocks.
 *  If id corresponds to a local object, then it returns
 *  the_object control pointer which maps to id and location
 *  is set to OBJECTS_LOCAL.  If the object class supports global
 *  objects and the object id is global and resides on a remote
 *  node, then location is set to OBJECTS_REMOTE, and the_object
 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
 *  and the_object is undefined.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] id is the Id of the object whose name we are locating.
 *  @param[in] location will contain an indication of success or failure.
 *
 *  @return This method returns one of the values from the 
 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
 *          successful or failure.  On success @a id will contain the Id of
 *          the requested object.
 *
 *  @note _Objects_Get returns with dispatching disabled for
 *  local and remote objects.  _Objects_Get_isr_disable returns with
 *  dispatching disabled for remote objects and interrupts for local
 *  objects.
 */
Objects_Control *_Objects_Get (
  Objects_Information *information,
  Objects_Id           id,
  Objects_Locations   *location
);

/**
 *  This function maps object ids to object control blocks.
 *  If id corresponds to a local object, then it returns
 *  the_object control pointer which maps to id and location
 *  is set to OBJECTS_LOCAL.  If the object class supports global
 *  objects and the object id is global and resides on a remote
 *  node, then location is set to OBJECTS_REMOTE, and the_object
 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
 *  and the_object is undefined.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] id is the Id of the object whose name we are locating.
 *  @param[in] location will contain an indication of success or failure.
 *  @param[in] level is the interrupt level being turned.
 *
 *  @return This method returns one of the values from the 
 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
 *          successful or failure.  On success @a name will contain the name of
 *          the requested object.
 *
 *  @note _Objects_Get returns with dispatching disabled for
 *  local and remote objects.  _Objects_Get_isr_disable returns with
 *  dispatching disabled for remote objects and interrupts for local
 *  objects.
 */
Objects_Control *_Objects_Get_isr_disable(
  Objects_Information *information,
  Objects_Id           id,
  Objects_Locations   *location,
  ISR_Level           *level
);

/**
 *  This function maps object index to object control blocks which must.
 *  be local.  The parameter the_object control pointer which maps to id
 *  and location is set to OBJECTS_LOCAL.  Otherwise, location is set to
    OBJECTS_ERROR and the_object is undefined.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] id is the Id of the object whose name we are locating.
 *  @param[in] location will contain an indication of success or failure.
 *
 *  @return This method returns a pointer to the object associated with ID.
 *
 *  @return This method returns one of the values from the 
 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
 *          successful or failure.  On success @a id will contain the id of
 *          the requested object.
 *
 *  @note _Objects_Get returns with dispatching disabled for
 *  local and remote objects.  _Objects_Get_isr_disable returns with
 *  dispatching disabled for remote objects and interrupts for local
 *  objects.
 */
Objects_Control *_Objects_Get_by_index (
  Objects_Information *information,
  Objects_Id           id,
  Objects_Locations   *location
);

/**
 *  This function maps object ids to object control blocks.
 *  If id corresponds to a local object, then it returns
 *  the_object control pointer which maps to id and location
 *  is set to OBJECTS_LOCAL.  If the object class supports global
 *  objects and the object id is global and resides on a remote
 *  node, then location is set to OBJECTS_REMOTE, and the_object
 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
 *  and the_object is undefined.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] id is the Id of the object whose name we are locating.
 *  @param[in] location will contain an indication of success or failure.
 *
 *  @return This method returns one of the values from the 
 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
 *          successful or failure.  On success @a id will contain the Id of
 *          the requested object.
 *
 *  @note _Objects_Get returns with dispatching disabled for
 *  local and remote objects.  _Objects_Get_isr_disable returns with
 *  dispatching disabled for remote objects and interrupts for local
 *  objects.
 */
Objects_Control *_Objects_Get_no_protection(
  Objects_Information *information,
  Objects_Id           id,
  Objects_Locations   *location
);

/**
 *  Like @ref _Objects_Get, but is used to find "next" open object.
 *
 *  @param[in] information points to an object class information block.
 *  @param[in] id is the Id of the object whose name we are locating.
 *  @param[in] location_p will contain an indication of success or failure.
 *  @param[in] next_id_p is the Id of the next object we will look at.
 *
 *  @return This method returns the pointer to the object located or 
 *          NULL on error.
 */
Objects_Control *_Objects_Get_next(
    Objects_Information *information,
    Objects_Id           id,
    Objects_Locations   *location_p,
    Objects_Id          *next_id_p
);

/*
 *  Pieces of object.inl are promoted out to the user
 */

#include <rtems/score/object.inl>
#if defined(RTEMS_MULTIPROCESSING)
#include <rtems/score/objectmp.h>
#endif

#ifdef __cplusplus
}
#endif

#endif
/* end of include file */