<commit_before>/* microkernel/task.h */

/*
 * Copyright (c) 1997-2014 Wind River Systems, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef TASK_H
#define TASK_H
/**
 * @brief Microkernel Tasks
 * @defgroup microkernel_task Microkernel Tasks
 * @ingroup microkernel_services
 * @{
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <sections.h>

/*
 * The following task groups are reserved for system use.
 * sysgen automatically generates corresponding TASKGROUPs with reserved
 * GROUPIDs
 * sysgen must be updated if any changes are made to the reserved groups.
 */

#define EXE_GROUP 1 /* TASKGROUP EXE */
#define USR_GROUP 2 /* TASKGROUP SYS */
#define FPU_GROUP 4 /* TASKGROUP FPU */

/**
 * @cond internal
 */

/**
 * @brief Initialize a struct k_task given parameters.
 *
 * @param ident Numeric identifier of this task object.
 * @param priority Priority of task.
 * @param state State of task.
 * @param groups Groups this task belong to.
 * @param fn_start Entry function.
 * @param workspace Pointer to workspace (aka, stack).
 * @param worksize Size of workspace.
 * @param fn_abort Abort function.
 */
#define __K_TASK_INITIALIZER(ident, priority, state, groups, \
			     fn_start, workspace, worksize, fn_abort) \
	{ \
	  NULL, NULL, priority, ident, state, ((groups) ^ SYS), \
	  fn_start, workspace, worksize, fn_abort, NULL, \
	}
extern struct k_task _k_task_list[];

extern void _task_ioctl(ktask_t, int);
extern void _task_group_ioctl(ktask_group_t, int);

/**
 * @endcond
 */

/**
 * @brief Yield the CPU to another task
 *
 * This routine yields the processor to the next equal priority task that is
 * runnable. Using task_yield(), it is possible to achieve the effect of round
 * robin scheduling. If no task with the same priority is runnable then no task
 * switch occurs and the calling task resumes execution.
 *
 * @return N/A
 */
extern void task_yield(void);

/**
 * @brief Set the priority of a task
 *
 * This routine changes the priority of the specified task.
 *
 * The call has immediate effect. If the calling task is no longer the highest
 * priority runnable task, a task switch occurs.
 *
 * The priority should be specified in the range 0 to 62. 0 is the highest
 * priority.
 *
 * @param task Task whose priority is to be set
 * @param prio New priority
 *
 * @return N/A
 */
extern void task_priority_set(ktask_t task, kpriority_t prio);

/**
 * @brief Set the entry point of a task
 *
 * This routine sets the entry point of a task to a given routine. It is only
 * needed if the entry point is different from that specified in the project
 * file. It must be called before task_start() to have any effect, so it
 * cannot work with members of the EXE group or of any group that automatically
 * starts when the application is loaded.
 *
 * The routine is executed when the task is started
 *
 * @param task Task to operate on.
 * @param func Entry point
 *
 * @return N/A
 */
extern void task_entry_set(ktask_t task, void (*func)(void));

/**
 * @brief Install an abort handler
 *
 * This routine installs an abort handler for the calling task.
 *
 * The abort handler is run when the calling task is aborted by a _TaskAbort()
 * or task_group_abort() call.
 *
 * Each call to task_abort_handler_set() replaces the previously installed
 * handler.
 *
 * To remove an abort handler, set the parameter to NULL as below:
 *      task_abort_handler_set (NULL)
 *
 * @param func Abort handler
 *
 * @return N/A
 */
extern void task_abort_handler_set(void (*func)(void));

/**
 * @brief Issue a custom call from within the microkernel server fiber
 *
 * This routine issues a request to execute a function from within the context
 * of the microkernel server fiber.
 *
 * @param func function to call from within the microkernel server fiber
 * @param argp argument to pass to custom function
 *
 * @return return value from custom @a func call
 */
extern int task_offload_to_fiber(int (*)(), void *);

/*<commit_msg>doc: Fix microkernel task.h doc build warnings<commit_after>/* microkernel/task.h */

/*
 * Copyright (c) 1997-2014 Wind River Systems, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef TASK_H
#define TASK_H
/**
 * @brief Microkernel Tasks
 * @defgroup microkernel_task Microkernel Tasks
 * @ingroup microkernel_services
 * @{
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <sections.h>

/*
 * The following task groups are reserved for system use.
 * sysgen automatically generates corresponding TASKGROUPs with reserved
 * GROUPIDs
 * sysgen must be updated if any changes are made to the reserved groups.
 */

#define EXE_GROUP 1 /* TASKGROUP EXE */
#define USR_GROUP 2 /* TASKGROUP SYS */
#define FPU_GROUP 4 /* TASKGROUP FPU */

/**
 * @cond internal
 */

/**
 * @brief Initialize a struct k_task given parameters.
 *
 * @param ident Numeric identifier of this task object.
 * @param priority Priority of task.
 * @param state State of task.
 * @param groups Groups this task belong to.
 * @param fn_start Entry function.
 * @param workspace Pointer to workspace (aka, stack).
 * @param worksize Size of workspace.
 * @param fn_abort Abort function.
 */
#define __K_TASK_INITIALIZER(ident, priority, state, groups, \
			     fn_start, workspace, worksize, fn_abort) \
	{ \
	  NULL, NULL, priority, ident, state, ((groups) ^ SYS), \
	  fn_start, workspace, worksize, fn_abort, NULL, \
	}
extern struct k_task _k_task_list[];

extern void _task_ioctl(ktask_t, int);
extern void _task_group_ioctl(ktask_group_t, int);

/**
 * @endcond
 */

/**
 * @brief Yield the CPU to another task
 *
 * This routine yields the processor to the next equal priority task that is
 * runnable. Using task_yield(), it is possible to achieve the effect of round
 * robin scheduling. If no task with the same priority is runnable then no task
 * switch occurs and the calling task resumes execution.
 *
 * @return N/A
 */
extern void task_yield(void);

/**
 * @brief Set the priority of a task
 *
 * This routine changes the priority of the specified task.
 *
 * The call has immediate effect. If the calling task is no longer the highest
 * priority runnable task, a task switch occurs.
 *
 * The priority should be specified in the range 0 to 62. 0 is the highest
 * priority.
 *
 * @param task Task whose priority is to be set
 * @param prio New priority
 *
 * @return N/A
 */
extern void task_priority_set(ktask_t task, kpriority_t prio);

/**
 * @brief Set the entry point of a task
 *
 * This routine sets the entry point of a task to a given routine. It is only
 * needed if the entry point is different from that specified in the project
 * file. It must be called before task_start() to have any effect, so it
 * cannot work with members of the EXE group or of any group that automatically
 * starts when the application is loaded.
 *
 * The routine is executed when the task is started
 *
 * @param task Task to operate on.
 * @param func Entry point
 *
 * @return N/A
 */
extern void task_entry_set(ktask_t task, void (*func)(void));

/**
 * @brief Install an abort handler
 *
 * This routine installs an abort handler for the calling task.
 *
 * The abort handler is run when the calling task is aborted by a _TaskAbort()
 * or task_group_abort() call.
 *
 * Each call to task_abort_handler_set() replaces the previously installed
 * handler.
 *
 * To remove an abort handler, set the parameter to NULL as below:
 *      task_abort_handler_set (NULL)
 *
 * @param func Abort handler
 *
 * @return N/A
 */
extern void task_abort_handler_set(void (*func)(void));

/**
 * @brief Issue a custom call from within the microkernel server fiber
 *
 * This routine issues a request to execute a function from within the context
 * of the microkernel server fiber.
 *
 * @param func function to call from within the microkernel server fiber
 * @param argp argument to pass to custom function
 *
 * @return return value from custom @a func call
 */
extern int task_offload_to_fiber(int (*func)(), void *argp);

/*
{'fraction_non_alphanumeric': 0.0836198292114894, 'fraction_numerical': 0.00421426194965066, 'mean_word_length': 3.6773858921161824, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3277698', 'n_tokens_mistral': 2622, 'n_tokens_neox': 2568, 'n_words': 1200}