From 68951fb2a4fb98abda6a88750a0b37be129d0a9d Mon Sep 17 00:00:00 2001 From: alessandronardin Date: Sat, 1 Jun 2024 22:29:50 +0200 Subject: [PATCH] cpukit/posix/aio*: Updated aio files documentation Updated the documentation in all aio files. Moved the Doxygen comments to the headers when possible. Fixed some formatting errors. Updates #5027 --- cpukit/include/aio.h | 214 +++++++++++++++++--------- cpukit/include/rtems/posix/aio_misc.h | 169 ++++++++++++++------ cpukit/posix/src/aio_cancel.c | 125 ++++++++------- cpukit/posix/src/aio_error.c | 25 +-- cpukit/posix/src/aio_fsync.c | 52 +++---- cpukit/posix/src/aio_misc.c | 126 +++++++-------- cpukit/posix/src/aio_read.c | 57 +++---- cpukit/posix/src/aio_return.c | 25 ++- cpukit/posix/src/aio_suspend.c | 7 +- cpukit/posix/src/aio_write.c | 54 +++---- 10 files changed, 475 insertions(+), 379 deletions(-) diff --git a/cpukit/include/aio.h b/cpukit/include/aio.h index 0e428ad86c..3c86547ff2 100644 --- a/cpukit/include/aio.h +++ b/cpukit/include/aio.h @@ -3,10 +3,11 @@ /** * @file * - * @brief POSIX Asynchronous Input and Output + * @ingroup POSIX_AIO * - * This file contains the definitions related to POSIX Asynchronous - * Input and Output, + * @brief POSIX Asynchronous I/O Support + * + * This file contains the definitions related to POSIX I/O. */ /* @@ -35,6 +36,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ + #ifndef _AIO_H #define _AIO_H @@ -47,13 +49,10 @@ extern "C" { /** * @defgroup POSIX_AIO POSIX Asynchronous I/O Support - * - * @ingroup POSIXAPI - * - * @brief POSIX Asynchronous Input and Output * + * @ingroup POSIXAPI + * @{ */ -/**@{**/ #if defined(_POSIX_ASYNCHRONOUS_IO) @@ -61,7 +60,6 @@ extern "C" { * 6.7.1 Data Definitions for Asynchronous Input and Output, * P1003.1b-1993, p. 151 */ - #include #include #include @@ -71,69 +69,108 @@ extern "C" { * 6.7.1.2 Manifest Constants, P1003.1b-1993, p. 153 */ -#define AIO_CANCELED 0 /* all requested operations have been canceled */ -#define AIO_NOTCANCELED 1 /* some of the operations could not be canceled */ - /* since they are in progress */ -#define AIO_ALLDONE 2 /* none of the requested operations could be */ - /* canceled since they are already complete */ - -/* lio_listio() options */ - -/* - * LIO modes +/** All requested operations have been canceled */ +#define AIO_CANCELED 0 +/** Some operations could not be canceled since they are in progress */ +#define AIO_NOTCANCELED 1 +/** + * None of the requested operations could be canceled since + * they are already complete */ -#define LIO_WAIT 0 /* calling process is to suspend until the */ - /* operation is complete */ -#define LIO_NOWAIT 1 /* calling process is to continue execution while */ - /* the operation is performed and no notification */ - /* shall be given when the operation is completed */ +#define AIO_ALLDONE 2 -/* - * LIO opcodes +/** Calling process is to be suspendes until the operation is complete */ +#define LIO_WAIT 0 +/** + * Calling process is to continue execution while the operation is performed + * and no notification shall be given when the operation is completed */ -#define LIO_NOP 0 /* no transfer is requested */ -#define LIO_READ 1 /* request a read() */ -#define LIO_WRITE 2 /* request a write() */ -#define LIO_SYNC 3 /* needed by aio_fsync() */ +#define LIO_NOWAIT 1 -/* - * 6.7.1.1 Asynchronous I/O Control Block, P1003.1b-1993, p. 151 +/** No transfer is requested */ +#define LIO_NOP 0 +/** Request a read() */ +#define LIO_READ 1 +/** Request a write() */ +#define LIO_WRITE 2 +/** Needed by aio_fsync() */ +#define LIO_SYNC 3 + + +/** + * @brief Asynchronous I/O Control Block + * + * 6.7.1.1 Asynchronous I/O Control Block, P1003.1b-1993, p. 151 */ - struct aiocb { - /* public */ - int aio_fildes; /* File descriptor */ - off_t aio_offset; /* File offset */ - volatile void *aio_buf; /* Location of buffer */ - size_t aio_nbytes; /* Length of transfer */ - int aio_reqprio; /* Request priority offset */ - struct sigevent aio_sigevent; /* Signal number and value */ - int aio_lio_opcode; /* Operation to be performed */ - /* private */ - int error_code; /* Used for aio_error() */ - ssize_t return_value; /* Used for aio_return() */ + /** @name public */ + + /** @brief File descriptor */ + int aio_fildes; + /** @brief File offset */ + off_t aio_offset; + /** @brief Location of buffer */ + volatile void *aio_buf; + /** @brief Length of transfer */ + size_t aio_nbytes; + /** @brief Request priority offset */ + int aio_reqprio; + /** @brief Signal number and value */ + struct sigevent aio_sigevent; + /** @brief Operation to be performed */ + int aio_lio_opcode; + + /** @name private */ + + /** @brief Field used for aio_error() */ + int error_code; + /** @brief Filed used for aio_return() */ + ssize_t return_value; }; -/* - * 6.7.2 Asynchronous Read, P1003.1b-1993, p. 154 +/** + * @brief Asynchronous Read + * + * 6.7.2 Asynchronous Read, P1003.1b-1993, p. 154 + * + * @param[in,out] aiocbp is a pointer to the asynchronous I/O control block + * + * @retval 0 The request has been successfuly enqueued. + * @retval -1 The request has not been enqueued due to an error. The error is indicated in errno: + * - EBADF FD not opened for read + * - EINVAL invalid aio_reqprio or aio_offset or aio_nbytes + * - EAGAIN not enough memory + * - EINVAL the starting position of the file is past the maximum offset + * for this file. + * */ - int aio_read( struct aiocb *aiocbp ); -/* - * 6.7.3 Asynchronous Write, P1003.1b-1993, p. 155 +/** + * @brief Asynchronous Write + * + * 6.7.3 Asynchronous Write, P1003.1b-1993, p. 155 + * + * @param[in,out] aiocbp is a pointer to the asynchronous I/O control block + * + * @retval 0 The request has been successfuly enqueued. + * @retval -1 The request has not been enqueued due to an error. The error is indicated in errno: + * - EBADF FD not opened for write + * - EINVAL invalid aio_reqprio or aio_offset or aio_nbytes + * - EAGAIN not enough memory + * */ - int aio_write( struct aiocb *aiocbp ); -/* - * 6.7.4 List Directed I/O, P1003.1b-1993, p. 158 +/** + * @brief List Directed I/O - NOT IMPLEMENTED + * + * 6.7.4 List Directed I/O, P1003.1b-1993, p. 158 */ - int lio_listio( int mode, struct aiocb *__restrict const list[__restrict], @@ -141,19 +178,32 @@ int lio_listio( struct sigevent *__restrict sig ); -/* - * 6.7.5 Retrieve Error of Asynchronous I/O Operation, P1003.1b-1993, p. 161 +/** + * @brief Retrieve Error of Asynchronous I/O Operation + * + * 6.7.5 Retrieve Error of Asynchronous I/O Operation, P1003.1b-1993, p. 161 + * + * @param[in] aiocbp is a pointer to the asynchronous I/O control block + * + * @retval 0 The operation has completed succesfully. + * @retval EINPROGRESS The operation has not yet completed. + * @return The error status as described for the various operations. */ - int aio_error( const struct aiocb *aiocbp ); -/* - * 6.7.6 Retrieve Return Status of Asynchronous I/O Operation, - * P1003.1b-1993, p. 162 - */ +/** + * @brief Retrieve Return Status of Asynchronous I/O Operation + * + * 6.7.6 Retrieve Return Status of Asynchronous I/O Operation, + * P1003.1b-1993, p. 162 + * + * @param[in] aiocbp is a pointer to the asynchronous I/O control block + * + * @return The operation return status, stored in aiocbp->return_value + */ ssize_t aio_return( const struct aiocb *aiocbp ); @@ -163,24 +213,27 @@ ssize_t aio_return( * * 6.7.7 Cancel Asynchronous I/O Operation, P1003.1b-1993, p. 163 * - * @param[in] filedes is the file descriptor - * @param[in] aiocbp is a pointer to the asynchronous I/O control block + * @param[in] filedes Is the file descriptor + * @param[in,out] aiocbp Is a pointer to the asynchronous I/O control block * - * @retval AIO_CANCELED The requested operation(s) were canceled. - * @retval AIO_NOTCANCELED Some of the requested operation(s) cannot be - * canceled since they are in progress. - * @retval AIO_ALLDONE None of the requested operation(s) could be canceled - * since they are already complete + * @retval AIO_CANCELED The requested operation(s) were canceled. + * @retval AIO_NOTCANCELED Some of the requested operation(s) cannot be + * canceled since they are in progress. + * @retval AIO_ALLDONE None of the requested operation(s) could be + * canceled since they are already complete. + * @retval -1 An error has occured, errno indicates the error: + * - EBADF fildes is not a valid file descriptor. */ int aio_cancel( int filedes, struct aiocb *aiocbp ); -/* - * 6.7.7 Wait for Asynchronous I/O Request, P1003.1b-1993, p. 164 +/** + * @brief Wait for Asynchronous I/O Request - NOT IMPLEMENTED + * + * 6.7.7 Wait for Asynchronous I/O Request, P1003.1b-1993, p. 164 */ - int aio_suspend( const struct aiocb * const list[], int nent, @@ -189,10 +242,23 @@ int aio_suspend( #if defined(_POSIX_SYNCHRONIZED_IO) -/* - * 6.7.9 Asynchronous File Synchronization, P1003.1b-1993, p. 166 +/** + * @brief Asynchronous File Synchronization + * + * 6.7.9 Asynchronous File Synchronization, P1003.1b-1993, p. 166 + * + * @param[in] op O_SYNC + * @param[in,out] aiocbp is a pointer to the asynchronous I/O control block + * + * @retval 0 The request was correctly enqueued. + * @retval -1 An error occured. errno indicated the error: + * - EAGAIN The requested asynchronous operation was not queued + * due to temporary resource limitations. + * - EBADF The aio_fildes member of the aiocb structure referenced + * by the aiocbp argument is not a valid file descriptor. + * - EINVAL A value of op other than O_SYNC was specified. + * The current implemetation only supports O_SYNC. */ - int aio_fsync( int op, struct aiocb *aiocbp @@ -209,4 +275,6 @@ int aio_fsync( #endif #endif + /* end of include file */ + diff --git a/cpukit/include/rtems/posix/aio_misc.h b/cpukit/include/rtems/posix/aio_misc.h index 8356d3df5a..9af10a5026 100644 --- a/cpukit/include/rtems/posix/aio_misc.h +++ b/cpukit/include/rtems/posix/aio_misc.h @@ -3,14 +3,19 @@ /** * @file * - * @brief POSIX Asynchronous Input and Output Private Support + * @ingroup POSIX_AIO + * + * @brief POSIX Asynchronous I/O Private Support * * This defines private information for the AIO implementation. */ /* - * Copyright 2010, Alin Rus + * Copyright 2010, Alin Rus * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -33,6 +38,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ + #ifndef _AIO_MISC_H #define _AIO_MISC_H @@ -43,47 +49,79 @@ #include #include #include - + #ifdef __cplusplus -extern "C" -{ +extern "C" { #endif - /* Actual request being processed */ - typedef struct - { - rtems_chain_node next_prio; /* chain requests in order of priority */ - int policy; /* If _POSIX_PRIORITIZED_IO and - _POSIX_PRIORITY_SCHEDULING are defined */ - int priority; /* see above */ - pthread_t caller_thread; /* used for notification */ - struct aiocb *aiocbp; /* aio control block */ - } rtems_aio_request; +/** + * @brief The request being processed + */ +typedef struct +{ + /** @brief Chain requests in order of priority */ + rtems_chain_node next_prio; - typedef struct - { - rtems_chain_node next_fd; /* order fd chains in queue */ - rtems_chain_control perfd; /* chain of requests for this fd */ - int fildes; /* file descriptor to be processed */ - int new_fd; /* if this is a newly created chain */ - pthread_mutex_t mutex; - pthread_cond_t cond; + /** @brief If _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING are defined */ + int policy; - } rtems_aio_request_chain; + /** @brief see above */ + int priority; - typedef struct - { - pthread_mutex_t mutex; - pthread_cond_t new_req; - pthread_attr_t attr; + /** @brief Used for notification */ + pthread_t caller_thread; - rtems_chain_control work_req; /* chains being worked by active threads */ - rtems_chain_control idle_req; /* fd chains waiting to be processed */ - unsigned int initialized; /* specific value if queue is initialized */ - int active_threads; /* the number of active threads */ - int idle_threads; /* number of idle threads */ + /** @brief Aio control block */ + struct aiocb *aiocbp; +} rtems_aio_request; - } rtems_aio_queue; +/** + * @brief A chain of requests for the same FD + */ +typedef struct +{ + /** @brief Order fd chains in queue */ + rtems_chain_node next_fd; + + /** @brief Chain of requests for this fd */ + rtems_chain_control perfd; + + /** @brief File descriptor to be processed */ + int fildes; + + /** @brief Indicates if this is a newly created chain */ + int new_fd; + + pthread_mutex_t mutex; + pthread_cond_t cond; + +} rtems_aio_request_chain; + +/** + * @brief The queue of all the requests in progress and waiting to be processed + */ +typedef struct +{ + pthread_mutex_t mutex; + pthread_cond_t new_req; + pthread_attr_t attr; + + /** @brief Chains being worked by active threads */ + rtems_chain_control work_req; + + /** @brief Chains waiting to be processed */ + rtems_chain_control idle_req; + + /** @brief Specific value if queue is initialized */ + unsigned int initialized; + + /** @brief The number of active threads */ + int active_threads; + + /** @brief The number of idle threads */ + int idle_threads; + +} rtems_aio_queue; extern rtems_aio_queue aio_request_queue; @@ -97,17 +135,61 @@ extern rtems_aio_queue aio_request_queue; #define AIO_MAX_QUEUE_SIZE 30 #endif -int rtems_aio_init (void); -int rtems_aio_enqueue (rtems_aio_request *req); -rtems_aio_request_chain *rtems_aio_search_fd -( +/** + * @brief Initialize the request queue for AIO Operations. + * + * @retval 0 The queue has bees succesfully initialized. + */ +int rtems_aio_init( void ); + +/** + * @brief Enqueue requests, and creates threads to process them. + * + * @param[in,out] req A pointer to the request. + * + * @retval 0 if the request was added to the queue, errno otherwise. + */ +int rtems_aio_enqueue( rtems_aio_request *req ); + +/** + * @brief Search for and create a chain of requests for a given file descriptor. + * + * @param[in,out] chain A pointer to a chain of FD chains. + * @param[in] fildes The file descriptor to search for. + * @param[in] create If create == 0, the function just searches for the given FD. + * If create == 1, the function creates a new chain if none is found. + * + * @retval NULL If create == 0 and no chain is found for the given FD. + * @return A pointer to the chain if a chain for the given FD exists. + * @return A pointer to a newly created chain if create == 1 and no chain + * is found for the given FD. + */ +rtems_aio_request_chain *rtems_aio_search_fd( rtems_chain_control *chain, int fildes, int create ); -void rtems_aio_remove_fd (rtems_aio_request_chain *r_chain); -int rtems_aio_remove_req (rtems_chain_control *chain, - struct aiocb *aiocbp); + +/** + * @brief Removes all the requests in a FD chain. + * + * @param[in,out] r_chain A pointer to a chain of requests for a given FD + */ +void rtems_aio_remove_fd( rtems_aio_request_chain *r_chain ); + +/** + * @brief Remove request from given chain + * + * @param[in,out] chain A pointer to the FD chain that may contain the request + * @param[in,out] aiocbp A pointer to the AIO control block of the request. + * + * @retval AIO_CANCELED The request was canceled. + * @retval AIO_NOTCANCELED The request was not canceled. + */ +int rtems_aio_remove_req( + rtems_chain_control *chain, + struct aiocb *aiocbp +); #ifdef RTEMS_DEBUG #include @@ -122,10 +204,11 @@ int rtems_aio_remove_req (rtems_chain_control *chain, #define rtems_aio_set_errno_return_minus_one( _error, _aiocbp ) \ do { (_aiocbp)->error_code = (_error); \ (_aiocbp)->return_value = -1; \ - rtems_set_errno_and_return_minus_one (_error);} while(0) + rtems_set_errno_and_return_minus_one(_error);} while(0) #ifdef __cplusplus } #endif #endif + diff --git a/cpukit/posix/src/aio_cancel.c b/cpukit/posix/src/aio_cancel.c index 21304febb9..b42e3cd4cb 100644 --- a/cpukit/posix/src/aio_cancel.c +++ b/cpukit/posix/src/aio_cancel.c @@ -1,15 +1,19 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /** - * @file + * @file * - * @brief Cancel Asynchronous I/O Operation - * @ingroup POSIX_AIO + * @ingroup POSIX_AIO + * + * @brief Cancel Asynchronous I/O Operation. */ /* - * Copyright 2010, Alin Rus + * Copyright 2010, Alin Rus * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -32,6 +36,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -42,93 +47,95 @@ #include #include -int aio_cancel(int fildes, struct aiocb *aiocbp) +int aio_cancel( int fildes, struct aiocb *aiocbp ) { rtems_chain_control *idle_req_chain = &aio_request_queue.idle_req; rtems_chain_control *work_req_chain = &aio_request_queue.work_req; rtems_aio_request_chain *r_chain; int result; - - pthread_mutex_lock (&aio_request_queue.mutex); - if (fcntl (fildes, F_GETFD) < 0) { - pthread_mutex_unlock(&aio_request_queue.mutex); - rtems_set_errno_and_return_minus_one (EBADF); + pthread_mutex_lock( &aio_request_queue.mutex ); + + if ( fcntl( fildes, F_GETFD ) < 0 ) { + pthread_mutex_unlock( &aio_request_queue.mutex ); + rtems_set_errno_and_return_minus_one( EBADF ); } /* if aiocbp is NULL remove all request for given file descriptor */ - if (aiocbp == NULL) { - AIO_printf ("Cancel all requests\n"); - - r_chain = rtems_aio_search_fd (work_req_chain, fildes, 0); - if (r_chain == NULL) { - AIO_printf ("Request chain not on [WQ]\n"); + if ( aiocbp == NULL ) { + AIO_printf( "Cancel all requests\n" ); - if (!rtems_chain_is_empty (idle_req_chain)) { - r_chain = rtems_aio_search_fd (idle_req_chain, fildes, 0); - if (r_chain == NULL) { - pthread_mutex_unlock(&aio_request_queue.mutex); + r_chain = rtems_aio_search_fd( work_req_chain, fildes, 0 ); + if ( r_chain == NULL ) { + AIO_printf( "Request chain not on [WQ]\n" ); + + if ( !rtems_chain_is_empty( idle_req_chain ) ) { + r_chain = rtems_aio_search_fd( idle_req_chain, fildes, 0 ); + if ( r_chain == NULL ) { + pthread_mutex_unlock( &aio_request_queue.mutex ); return AIO_ALLDONE; } - AIO_printf ("Request chain on [IQ]\n"); + AIO_printf ( "Request chain on [IQ]\n" ); - rtems_chain_extract (&r_chain->next_fd); - rtems_aio_remove_fd (r_chain); - pthread_mutex_destroy (&r_chain->mutex); - pthread_cond_destroy (&r_chain->cond); - free (r_chain); + rtems_chain_extract( &r_chain->next_fd ); + rtems_aio_remove_fd( r_chain ); + pthread_mutex_destroy( &r_chain->mutex ); + pthread_cond_destroy( &r_chain->cond ); + free( r_chain ); - pthread_mutex_unlock (&aio_request_queue.mutex); + pthread_mutex_unlock( &aio_request_queue.mutex ); return AIO_CANCELED; } - pthread_mutex_unlock (&aio_request_queue.mutex); + pthread_mutex_unlock( &aio_request_queue.mutex ); return AIO_ALLDONE; } - AIO_printf ("Request chain on [WQ]\n"); + AIO_printf( "Request chain on [WQ]\n" ); - pthread_mutex_lock (&r_chain->mutex); - rtems_chain_extract (&r_chain->next_fd); - rtems_aio_remove_fd (r_chain); - pthread_mutex_unlock (&r_chain->mutex); - pthread_mutex_unlock (&aio_request_queue.mutex); + pthread_mutex_lock( &r_chain->mutex ); + rtems_chain_extract( &r_chain->next_fd ); + rtems_aio_remove_fd( r_chain ); + pthread_mutex_unlock( &r_chain->mutex ); + pthread_mutex_unlock( &aio_request_queue.mutex ); return AIO_CANCELED; } else { - AIO_printf ("Cancel request\n"); + AIO_printf( "Cancel request\n" ); - if (aiocbp->aio_fildes != fildes) { - pthread_mutex_unlock (&aio_request_queue.mutex); - rtems_set_errno_and_return_minus_one (EINVAL); + if( aiocbp->aio_fildes != fildes ) { + pthread_mutex_unlock( &aio_request_queue.mutex ); + rtems_set_errno_and_return_minus_one( EINVAL ); } - r_chain = rtems_aio_search_fd (work_req_chain, fildes, 0); - if (r_chain == NULL) { - if (!rtems_chain_is_empty (idle_req_chain)) { - r_chain = rtems_aio_search_fd (idle_req_chain, fildes, 0); + r_chain = rtems_aio_search_fd( work_req_chain, fildes, 0 ); + if ( r_chain == NULL ) { + if ( !rtems_chain_is_empty( idle_req_chain ) ) { + r_chain = rtems_aio_search_fd( idle_req_chain, fildes, 0 ); if (r_chain == NULL) { - pthread_mutex_unlock (&aio_request_queue.mutex); - rtems_set_errno_and_return_minus_one (EINVAL); - } - - AIO_printf ("Request on [IQ]\n"); - - result = rtems_aio_remove_req (&r_chain->perfd, aiocbp); - pthread_mutex_unlock (&aio_request_queue.mutex); + pthread_mutex_unlock( &aio_request_queue.mutex ); + rtems_set_errno_and_return_minus_one( EINVAL ); + } + + AIO_printf( "Request on [IQ]\n" ); + + result = rtems_aio_remove_req( &r_chain->perfd, aiocbp ); + pthread_mutex_unlock( &aio_request_queue.mutex ); return result; } else { - pthread_mutex_unlock (&aio_request_queue.mutex); + pthread_mutex_unlock( &aio_request_queue.mutex ); return AIO_ALLDONE; } - } - AIO_printf ("Request on [WQ]\n"); - - pthread_mutex_lock (&r_chain->mutex); - result = rtems_aio_remove_req (&r_chain->perfd, aiocbp); - pthread_mutex_unlock (&r_chain->mutex); - pthread_mutex_unlock (&aio_request_queue.mutex); - return result; + } + + AIO_printf( "Request on [WQ]\n" ); + + pthread_mutex_lock( &r_chain->mutex ); + result = rtems_aio_remove_req( &r_chain->perfd, aiocbp ); + pthread_mutex_unlock( &r_chain->mutex ); + pthread_mutex_unlock( &aio_request_queue.mutex ); + return result; } return AIO_ALLDONE; } + diff --git a/cpukit/posix/src/aio_error.c b/cpukit/posix/src/aio_error.c index f6d8461e7c..e849f89ea0 100644 --- a/cpukit/posix/src/aio_error.c +++ b/cpukit/posix/src/aio_error.c @@ -3,14 +3,17 @@ /** * @file * - * @ingroup POSIXAPI + * @ingroup POSIX_AIO * - * @brief Returns the error status for the Asynchronous I/O request + * @brief Returns the error status for the Asynchronous I/O request. */ /* - * Copyright 2010, Alin Rus + * Copyright 2010, Alin Rus * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -42,21 +45,9 @@ #include -/* - * aio_error - * - * Retrieve errors status for an asynchronous I/O operation - * - * Input parameters: - * aiocbp - asynchronous I/O control block - * - * Output parameters: - * aiocbp->error_code - */ - - int -aio_error (const struct aiocb *aiocbp) +aio_error( const struct aiocb *aiocbp ) { return aiocbp->error_code; } + diff --git a/cpukit/posix/src/aio_fsync.c b/cpukit/posix/src/aio_fsync.c index aa23d51e1e..55ef259469 100644 --- a/cpukit/posix/src/aio_fsync.c +++ b/cpukit/posix/src/aio_fsync.c @@ -3,13 +3,16 @@ /** * @file * - * @ingroup POSIXAPI + * @ingroup POSIX_AIO * - * @brief Syncing of all Outstanding Asynchronous I/O Operations + * @brief Syncing of all Outstanding Asynchronous I/O Operations. */ /* - * Copyright 2010, Alin Rus + * Copyright 2010, Alin Rus + * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -43,22 +46,6 @@ #include #include -/* - * aio_fsync - * - * Asynchronous file synchronization - * - * Input parameters: - * op - O_SYNC - * aiocbp - asynchronous I/O control block - * - * Output parameters: - * -1 - request could not pe enqueued - * - FD not opened for write - * - not enough memory - * - op is not O_SYNC - * 0 - otherwise - */ int aio_fsync( int op, @@ -68,20 +55,25 @@ int aio_fsync( rtems_aio_request *req; int mode; - if (op != O_SYNC) - rtems_aio_set_errno_return_minus_one (EINVAL, aiocbp); + if ( op != O_SYNC ) + rtems_aio_set_errno_return_minus_one( EINVAL, aiocbp ); - mode = fcntl (aiocbp->aio_fildes, F_GETFL); - if (!(((mode & O_ACCMODE) == O_WRONLY) || ((mode & O_ACCMODE) == O_RDWR))) - rtems_aio_set_errno_return_minus_one (EBADF, aiocbp); + mode = fcntl( aiocbp->aio_fildes, F_GETFL ); + if ( + !( + ((mode & O_ACCMODE) == O_WRONLY) || + ((mode & O_ACCMODE) == O_RDWR) + ) + ) + rtems_aio_set_errno_return_minus_one( EBADF, aiocbp ); - req = malloc (sizeof (rtems_aio_request)); - if (req == NULL) - rtems_aio_set_errno_return_minus_one (EAGAIN, aiocbp); + req = malloc( sizeof( rtems_aio_request ) ); + if ( req == NULL ) + rtems_aio_set_errno_return_minus_one( EAGAIN, aiocbp ); req->aiocbp = aiocbp; - req->aiocbp->aio_lio_opcode = LIO_SYNC; + req->aiocbp->aio_lio_opcode = LIO_SYNC; - return rtems_aio_enqueue (req); - + return rtems_aio_enqueue( req ); } + diff --git a/cpukit/posix/src/aio_misc.c b/cpukit/posix/src/aio_misc.c index 9f963075fd..b14605bf6f 100644 --- a/cpukit/posix/src/aio_misc.c +++ b/cpukit/posix/src/aio_misc.c @@ -3,13 +3,19 @@ /** * @file * - * @brief Processing of AIO Requests. * @ingroup POSIX_AIO + * + * @brief Private implementation for Asynchronous I/O. + * + * This file contains the implementation of private methods used for the processing of Asynchronous I/O requests. */ /* - * Copyright 2010-2011, Alin Rus + * Copyright 2010-2011, Alin Rus * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -32,6 +38,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ + #include #include #include @@ -39,16 +46,45 @@ #include #include +/** + * @brief Thread processing AIO requests. + * + * @param[in,out] arg A pointer to the chain for the FD to be worked on. + * + * @retval NULL if an error occurs + */ static void *rtems_aio_handle( void *arg ); + +/** + * @brief Helper function por request processing + * + * @param[in,out] req A pointer to a single request. + * It will store the results of the request. + */ static void rtems_aio_handle_helper( rtems_aio_request *req ); +/** + * @brief Move chain of requests from IQ to WQ + * + * @param[in,out] r_chain the chain of requests to move in WQ + */ +static void rtems_aio_move_to_work( rtems_aio_request_chain *r_chain ); + +/** + * @brief Add request to given FD chain. + * + * Inserts the request in a the fd chain, which is ordered by priority. + * + * @param[in,out] chain A pointer to the chain of requests for a given FD. + * @param[in,out] req A pointer to a request (see aio_misc.h). + */ +static void rtems_aio_insert_prio( + rtems_chain_control *chain, + rtems_aio_request *req +); + rtems_aio_queue aio_request_queue; -/** - * @brief Initialize the request queue for AIO Operations. - * - * @retval 0 The queue has bees succesfully initialized. - */ int rtems_aio_init( void ) { int result = 0; @@ -86,21 +122,11 @@ int rtems_aio_init( void ) return result; } - /** - * @brief Search for and create a chain of requests for a given file descriptor. - * - * @param[in] chain A pointer to a chain of FD chains. - * @param[in] filedes The file descriptor to search for. - * @param[in] create If create == 0, the function just searches for the given FD. - * If create == 1, the function creates a new chain if none is found. - * - * @retval A pointer to the chain if a chain for the given FD exists. - * @retval NULL If create == 0 and no chain is found for the given FD. - * @retval A pointer to a newly created chain if create == 1 and no chain - * is found for the given FD. - */ -rtems_aio_request_chain * -rtems_aio_search_fd( rtems_chain_control *chain, int fildes, int create ) +rtems_aio_request_chain *rtems_aio_search_fd( + rtems_chain_control *chain, + int fildes, + int create +) { rtems_aio_request_chain *r_chain; rtems_chain_node *node; @@ -135,13 +161,7 @@ rtems_aio_search_fd( rtems_chain_control *chain, int fildes, int create ) return r_chain; } - /** - * @brief Move chain of requests from IQ to WQ - * - * @param[in] r_chain the chain of requests to move in WQ - */ -static void -rtems_aio_move_to_work( rtems_aio_request_chain *r_chain ) +static void rtems_aio_move_to_work( rtems_aio_request_chain *r_chain ) { rtems_chain_control *work_req_chain = &aio_request_queue.work_req; rtems_aio_request_chain *temp; @@ -160,15 +180,11 @@ rtems_aio_move_to_work( rtems_aio_request_chain *r_chain ) rtems_chain_insert( rtems_chain_previous( node ), &r_chain->next_fd ); } - - /** - * @brief Add request to given FD chain. The chain is ordered by priority. - * - * @param[in] chain A pointer to the chain of requests for a given FD. - * @param[in] req A pointer to a request (see aio_misc.h). - */ -static void -rtems_aio_insert_prio( rtems_chain_control *chain, rtems_aio_request *req ) + +static void rtems_aio_insert_prio( + rtems_chain_control *chain, + rtems_aio_request *req +) { rtems_chain_node *node; @@ -194,11 +210,6 @@ rtems_aio_insert_prio( rtems_chain_control *chain, rtems_aio_request *req ) } } - /** - * @brief Removes all the requests in a FD chain. - * - * @param[in] r_chain A pointer to a chain of requests for a given FD - */ void rtems_aio_remove_fd( rtems_aio_request_chain *r_chain ) { rtems_chain_control *chain; @@ -216,15 +227,6 @@ void rtems_aio_remove_fd( rtems_aio_request_chain *r_chain ) } } - /** - * @brief Remove request from given chain - * - * @param[in] chain A pointer to the FD chain that may contain the request - * @param[in] aiocbp A pointer to the AIO control block of the request. - * - * @retval AIO_CANCELED The request was canceled. - * @retval AIO_NOTCANCELED The request was not canceled. - */ int rtems_aio_remove_req( rtems_chain_control *chain, struct aiocb *aiocbp ) { if ( rtems_chain_is_empty( chain ) ) @@ -252,13 +254,6 @@ int rtems_aio_remove_req( rtems_chain_control *chain, struct aiocb *aiocbp ) return AIO_CANCELED; } - /** - * @brief Enqueue requests, and creates threads to process them. - * - * @param[in] req A pointer to the request (for more info see aio_misc.h). - * - * @retval 0 if the request was added to the queue, errno otherwise. - */ int rtems_aio_enqueue( rtems_aio_request *req ) { @@ -363,13 +358,6 @@ rtems_aio_enqueue( rtems_aio_request *req ) return 0; } - /** - * @brief Thread processing AIO requests. - * - * @param[in] arg A pointer to the chain for the FD to be worked on. - * - * @retval NULL if an error occurs - */ static void *rtems_aio_handle( void *arg ) { @@ -505,12 +493,6 @@ static void *rtems_aio_handle( void *arg ) return NULL; } - /** - * @brief Helper function por request processing - * - * @param[in,out] req A pointer to a single request. - * It will store the results of the request. - */ static void rtems_aio_handle_helper( rtems_aio_request *req ) { int result; diff --git a/cpukit/posix/src/aio_read.c b/cpukit/posix/src/aio_read.c index df8a9275c6..7dbb809ee8 100644 --- a/cpukit/posix/src/aio_read.c +++ b/cpukit/posix/src/aio_read.c @@ -3,13 +3,17 @@ /** * @file * - * @brief Asynchronously reads Data from a File * @ingroup POSIX_AIO + * + * @brief Asynchronous read operation. */ /* - * Copyright 2010, Alin Rus + * Copyright 2010, Alin Rus * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -32,7 +36,6 @@ * POSSIBILITY OF SUCH DAMAGE. */ - #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -46,43 +49,33 @@ #include - /** - * @brief Asynchronous read from a file - * - * 6.7.2 Asynchronous Read, P1003.1b-1993, p. 154 - * - * @param[in] aiocbp is a pointer to the asynchronous I/O control block - * - * @retval 0 The request has been successfuly enqueued. - * @retval -1 The request has not been enqueued. The possible errors are: - * - FD not opened for read - * - invalid aio_reqprio or aio_offset or aio_nbytes - * - not enough memory - * - the starting position of the file is past the maximum offset - * for this file. - * - */ -int aio_read(struct aiocb *aiocbp) +int aio_read( struct aiocb *aiocbp ) { rtems_aio_request *req; int mode; - mode = fcntl(aiocbp->aio_fildes, F_GETFL); - if ( !((( mode&O_ACCMODE ) == O_RDONLY ) || (( mode&O_ACCMODE ) == O_RDWR ))) - rtems_aio_set_errno_return_minus_one(EBADF, aiocbp); - - if ( aiocbp->aio_reqprio < 0 || aiocbp->aio_reqprio > AIO_PRIO_DELTA_MAX ) - rtems_aio_set_errno_return_minus_one(EINVAL, aiocbp); - - if ( aiocbp->aio_offset < 0 ) - rtems_aio_set_errno_return_minus_one(EINVAL, aiocbp); + mode = fcntl( aiocbp->aio_fildes, F_GETFL ); + if ( + !( + (( mode&O_ACCMODE ) == O_RDONLY ) || + (( mode&O_ACCMODE ) == O_RDWR ) + ) + ) + rtems_aio_set_errno_return_minus_one( EBADF, aiocbp ); - req = malloc(sizeof(rtems_aio_request)); + if ( aiocbp->aio_reqprio < 0 || aiocbp->aio_reqprio > AIO_PRIO_DELTA_MAX ) + rtems_aio_set_errno_return_minus_one( EINVAL, aiocbp ); + + if ( aiocbp->aio_offset < 0 ) + rtems_aio_set_errno_return_minus_one( EINVAL, aiocbp ); + + req = malloc( sizeof( rtems_aio_request ) ); if ( req == NULL ) - rtems_aio_set_errno_return_minus_one(EAGAIN, aiocbp); + rtems_aio_set_errno_return_minus_one( EAGAIN, aiocbp ); req->aiocbp = aiocbp; req->aiocbp->aio_lio_opcode = LIO_READ; - return rtems_aio_enqueue(req); + return rtems_aio_enqueue( req ); } + diff --git a/cpukit/posix/src/aio_return.c b/cpukit/posix/src/aio_return.c index 2480738c09..356e7d1937 100644 --- a/cpukit/posix/src/aio_return.c +++ b/cpukit/posix/src/aio_return.c @@ -3,13 +3,16 @@ /** * @file * - * @ingroup POSIXAPI + * @ingroup POSIX_AIO * - * @brief Final return status for Asynchronous I/O request pointed to by aiobcp + * @brief Final return status for Asynchronous I/O request. */ /* - * Copyright 2010, Alin Rus + * Copyright 2010, Alin Rus + * + * COPYRIGHT (c) 1989-2011. + * On-Line Applications Research Corporation (OAR). * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -33,6 +36,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -42,20 +46,9 @@ #include -/* - * aio_return - * - * Retrieve return status of an asynchronous I/O operation - * - * Input parameters: - * aiocbp - asynchronous I/O control block - * - * Output parameters: - * aiocbp->return_value - */ - ssize_t -aio_return (const struct aiocb *aiocbp) +aio_return( const struct aiocb *aiocbp ) { return aiocbp->return_value; } + diff --git a/cpukit/posix/src/aio_suspend.c b/cpukit/posix/src/aio_suspend.c index 58379db9d2..d6aec7db75 100644 --- a/cpukit/posix/src/aio_suspend.c +++ b/cpukit/posix/src/aio_suspend.c @@ -3,14 +3,12 @@ /** * @file * - * @ingroup POSIXAPI + * @ingroup POSIX_AIO * - * @brief Suspends Process until Asynchronous I/O Operation completes + * @brief Wait for Asynchronous I/O Request. */ /* - * 6.7.7 Wait for Asynchronous I/O Request, P1003.1b-1993, p. 164 - * * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). * @@ -54,3 +52,4 @@ int aio_suspend( { rtems_set_errno_and_return_minus_one( ENOSYS ); } + diff --git a/cpukit/posix/src/aio_write.c b/cpukit/posix/src/aio_write.c index ebf6515083..aadbb613c8 100644 --- a/cpukit/posix/src/aio_write.c +++ b/cpukit/posix/src/aio_write.c @@ -3,14 +3,14 @@ /** * @file * - * @ingroup POSIXAPI + * @ingroup POSIX_AIO * - * @brief Function queues I/O request described by buffer pointed by aiocb + * @brief Asynchronous write operation. */ /* * Copyright 2010, Alin Rus - * + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -33,7 +33,6 @@ * POSSIBILITY OF SUCH DAMAGE. */ - #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -46,45 +45,34 @@ #include #include -/* - * aio_write - * - * Asynchronous write to a file - * - * Input parameters: - * aiocbp - asynchronous I/O control block - * - * Output parameters: - * -1 - request could not be enqueued - * - FD not opened for write - * - invalid aio_reqprio or aio_offset or - * aio_nbytes - * - not enough memory - * 0 - otherwise - */ - int -aio_write (struct aiocb *aiocbp) +aio_write( struct aiocb *aiocbp ) { rtems_aio_request *req; int mode; - mode = fcntl (aiocbp->aio_fildes, F_GETFL); - if (!(((mode & O_ACCMODE) == O_WRONLY) || ((mode & O_ACCMODE) == O_RDWR))) - rtems_aio_set_errno_return_minus_one (EBADF, aiocbp); + mode = fcntl( aiocbp->aio_fildes, F_GETFL ); + if ( + !( + ( ( mode&O_ACCMODE ) == O_WRONLY ) || + ( ( mode&O_ACCMODE ) == O_RDWR ) + ) + ) + rtems_aio_set_errno_return_minus_one( EBADF, aiocbp ); - if (aiocbp->aio_reqprio < 0 || aiocbp->aio_reqprio > AIO_PRIO_DELTA_MAX) - rtems_aio_set_errno_return_minus_one (EINVAL, aiocbp); + if ( aiocbp->aio_reqprio < 0 || aiocbp->aio_reqprio > AIO_PRIO_DELTA_MAX ) + rtems_aio_set_errno_return_minus_one( EINVAL, aiocbp ); - if (aiocbp->aio_offset < 0) - rtems_aio_set_errno_return_minus_one (EINVAL, aiocbp); + if ( aiocbp->aio_offset < 0 ) + rtems_aio_set_errno_return_minus_one( EINVAL, aiocbp ); - req = malloc (sizeof (rtems_aio_request)); - if (req == NULL) - rtems_aio_set_errno_return_minus_one (EAGAIN, aiocbp); + req = malloc( sizeof( rtems_aio_request ) ); + if ( req == NULL ) + rtems_aio_set_errno_return_minus_one( EAGAIN, aiocbp ); req->aiocbp = aiocbp; req->aiocbp->aio_lio_opcode = LIO_WRITE; - return rtems_aio_enqueue (req); + return rtems_aio_enqueue( req ); } +