MARS - Multicore Application Runtime System

Generated on Tue Nov 11 11:44:00 2008 for MARS by 1.5.6

        #include <mars/mars.h>  /* include header */

        libmars.a               /* static library */
        libmars.so              /* dynamic library */

        /* Example host 32-bit compile on Cell B.E. platform */
        HOST_CC =       ppu-gcc
        HOST_CFLAGS =   -m32

        $(HOST_CC) $(HOST_CFLAGS) host_prog.c -lspe2 -lmars

        /* Example host 64-bit compile on Cell B.E. platform */
        HOST_CC =       ppu-gcc
        HOST_CFLAGS =   -m64

        $(HOST_CC) $(HOST_CFLAGS) host_prog.c -lspe2 -lmars

        #include <mars/mars.h>

        libmars.a               /* static library */

        /* Example MPU compile on Cell B.E. platform */
        MPU_CC =        spu-gcc
        MPU_LD_FLAGS =  -Wl,-N -Wl,-gc-sections \
                        -Wl,--section-start,.init=0x10000 \
                        -Wl,--entry,mars_entry \
                        -Wl,-u,mars_entry

        $(MPU_CC) $(MPU_LD_FLAGS) mpu_prog.c -lmars

        /* sample host processor side host_prog.c */

        struct mars_context *mars_ctx;          /* mars context pointer */

        /* Create a MARS context */
        int ret = mars_context_create(&mars_ctx, 0, 0);
        if (ret != MARS_SUCCESS)                /* error checking */
                return USER_DEFINED_ERROR;      /* create failed */

int mars_context_create(
        struct mars_context **mars,
        uint32_t num_mpus,
        uint8_t shared);

        /* Destroy the MARS context previously created */
        ret = mars_context_destroy(mars_ctx);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* destroy failed */

        /* sample host processor side host_prog.c */

        struct mars_mutex *mutex;               /* mars mutex pointer */

        /* Create a MARS mutex */
        int ret = mars_mutex_create(&mutex);
        if (ret != MARS_SUCCESS)                /* error checking */
                return USER_DEFINED_ERROR;      /* create failed */

        /* Lock the MARS mutex previously created */
        ret = mars_mutex_lock(mutex);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* destroy failed */

        /* critical code section */

        /* Unlock the MARS mutex previously locked */
        ret = mars_mutex_unlock(mutex);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* destroy failed */

        /* Destroy the MARS mutex previously created */
        ret = mars_mutex_destroy(mutex);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* destroy failed */

        /* sample MPU side mpu_prog.c */

        #include <stdio.h>
        #include <mars/mars.h>

        int mars_task_main(const struct mars_task_args *task_args)
        {
                (void)task_args;

                printf("Hello World!\n");

                return 0;
        }

        /* sample host processor side host_prog.c */

        struct mars_context *mars_ctx;          /* MARS context pointer */
        struct mars_task_id task_id;            /* MARS task id instance */
        ...

        /* Assume MARS context is created as shown above */
        ...

        /* Create the task instance */
        int ret = mars_task_create(mars_ctx, &task_id, "Task", elf_image, NULL);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* create failed */

int mars_task_create(
        struct mars_context *mars,
        struct mars_task_id *id,
        const char *name,
        const void *elf_image,
        const struct mars_task_context_save_unit *save_units);

        /* sample host processor side host_prog.c */

        struct mars_task_args task_args;                /* MARS task args */
        uint8_t task_priority = 0;                      /* priority (0 to 255) */

        /* Sets the task to a schedulable state */
        ret = mars_task_schedule(&task_id, &task_args, task_priority);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* schedule failed */

        /* Host processor can process something while the MPUs execute the tasks asynchronously. */
        ...

        /* Blocks until the scheduled task has finished execution */
        ret = mars_task_wait(&task_id, NULL);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* wait failed */

int mars_task_schedule(
        struct mars_task_id *id,
        struct mars_task_args *args,
        uint8_t priority);

const struct mars_task_context_save_unit MARS_TASK_CONTEXT_SAVE_ALL[] =
{
        { .addr = 0, .size = MARS_TASK_CONTEXT_SAVE_SIZE_MAX },
        { .addr = 0, .size = 0 },
};

static struct mars_task_context_save_unit MARS_TASK_CONTEXT_SAVE_PARTIAL[] =
{
        { .addr = 0, .size = 0x1000 },
        { .addr = MARS_TASK_CONTEXT_SAVE_SIZE_MAX - 0x1000, .size = 0x1000 },
        { .addr = 0, .size = 0 },
};

        /* sample host processor side host_prog.c */

        /* Destroy the task previously created */
        ret = mars_task_destroy(task_id);
        if (ret != MARS_SUCCESS)                        /* error checking */
                return USER_DEFINED_ERROR;              /* destroy failed */

 1      #include <mars/mars.h>
 2
 3      static void *task_program_elf_image;
 4
 5      int main(void)
 6      {
 7              struct mars_context *mars_ctx;
 8              struct mars_task_id task_id;
 9              int task_exit_code;
10
11              mars_context_create(&mars_ctx, 0, 0);
12              mars_task_create(mars_ctx, &task_id, "Task", task_program_elf_image, 0);
13              mars_task_schedule(&task_id, NULL, 0);
14              mars_task_wait(&task_id, &task_exit_code);
15              mars_task_destroy(&task_id);
16              mars_context_destroy(mars_ctx);
17
18              return 0;
19      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              (void)task_args;
 7
 8              printf("MPU(%d): %s - Hello!\n",
 9                      mars_task_get_kernel_id(), mars_task_get_name());
10
11              return 0;
12      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      #define NUM_SUB_TASKS   2
 5
 6      static void *task1_program_elf_image;
 7      static void *task2_program_elf_image;
 8
 9      int main(void)
10      {
11              struct mars_context *mars_ctx;
12              struct mars_task_id task1_id;
13              struct mars_task_id task2_id[NUM_SUB_TASKS];
14              struct mars_task_args task_args;
15              int i;
16
17              mars_context_create(&mars_ctx, 0, 0);
18
19              mars_task_create(mars_ctx, &task1_id, "Task 1", task1_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
20
21              for (i = 0; i < NUM_SUB_TASKS; i++) {
22                      char name[16];
23                      sprintf(name, "Task 2.%d", i);
24                      mars_task_create(mars_ctx, &task2_id[i], name, task2_program_elf_image, 0);
25              }
26
27              task_args.type.u64[0] = mars_ptr_to_ea(&task2_id[0]);
28              task_args.type.u64[1] = mars_ptr_to_ea(&task2_id[1]);
29
30              mars_task_schedule(&task1_id, &task_args, 0);
31              mars_task_wait(&task1_id, NULL);
32              mars_task_destroy(&task1_id);
33
34              for (i = 0; i < NUM_SUB_TASKS; i++)
35                      mars_task_destroy(&task2_id[i]);
36
37              mars_context_destroy(mars_ctx);
38
39              return 0;
40      }

 1      #include <mars/mars.h>
 2
 3      int mars_task_main(const struct mars_task_args *task_args)
 4      {
 5              struct mars_task_id task2_0_id;
 6              struct mars_task_id task2_1_id;
 7              struct mars_task_args args;
 8
 9              get(&task2_0_id, task_args->type.u64[0], sizeof(task2_0_id));
10              get(&task2_1_id, task_args->type.u64[1], sizeof(task2_1_id));
11
12              args.type.u32[0] = 123;
13              mars_task_schedule(&task2_0_id, &args, 0);
14
15              args.type.u32[0] = 321;
16              mars_task_schedule(&task2_1_id, &args, 0);
17
18              mars_task_wait(&task2_0_id, NULL);
19              mars_task_wait(&task2_1_id, NULL);
20
21              return 0;
22      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              printf("MPU(%d): %s - Hello! (%d)\n",
 7                      mars_task_get_kernel_id(), mars_task_get_name(),
 8                      task_args->type.u32[0]);
 9
10              return 0;
11      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      #define NUM_TASKS       10
 5
 6      static void *task1_program_elf_image;
 7      static void *task2_program_elf_image;
 8
 9      int main(void)
10      {
11              struct mars_context *mars_ctx;
12              struct mars_task_id task1_id[NUM_TASKS];
13              struct mars_task_id task2_id;
14              struct mars_task_args task_args;
15              struct mars_task_barrier *barrier;
16              int i;
17
18              mars_context_create(&mars_ctx, 0, 0);
19
20              mars_task_barrier_create(mars_ctx, &barrier, NUM_TASKS);
21
22              for (i = 0; i < NUM_TASKS; i++) {
23                      char name[16];
24                      sprintf(name, "Task %d", i);
25
26                      mars_task_create(mars_ctx, &task1_id[i], name, task1_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
27
28                      task_args.type.u64[0] = mars_ptr_to_ea(barrier);
29                      mars_task_schedule(&task1_id[i], &task_args, 0);
30              }
31
32              mars_task_create(mars_ctx, &task2_id, "Task Final", task2_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
33
34              task_args.type.u64[0] = mars_ptr_to_ea(barrier);
35              mars_task_schedule(&task2_id, &task_args, 0);
36
37              for (i = 0; i < NUM_TASKS; i++) {
38                      mars_task_wait(&task1_id[i], NULL);
39                      mars_task_destroy(&task1_id[i]);
40              }
41
42              mars_task_wait(&task2_id, NULL);
43              mars_task_destroy(&task2_id);
44
45              mars_task_barrier_destroy(barrier);
46
47              mars_context_destroy(mars_ctx);
48
49              return 0;
50      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              uint64_t barrier_ea = task_args->type.u64[0];
 7
 8              printf("MPU(%d): %s - Hello!\n",
 9                      mars_task_get_kernel_id(), mars_task_get_name());
10
11              mars_task_barrier_notify(barrier_ea);
12
13              return 0;
14      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              uint64_t barrier_ea = task_args->type.u64[0];
 7
 8              mars_task_barrier_wait(barrier_ea);
 9
10              printf("MPU(%d): %s - Hello!\n",
11                      mars_task_get_kernel_id(), mars_task_get_name());
12
13              return 0;
14      }

 1      #include <unistd.h>
 2      #include <mars/mars.h>
 3
 4      static void *task1_program_elf_image;
 5      static void *task2_program_elf_image;
 6
 7      int main(void)
 8      {
 9              struct mars_context *mars_ctx;
10              struct mars_task_id task1_id;
11              struct mars_task_id task2_id;
12              struct mars_task_args task_args;
13              struct mars_task_event_flag *host_to_mpu;
14              struct mars_task_event_flag *mpu_to_host;
15              struct mars_task_event_flag *mpu_to_mpu;
16
17              mars_context_create(&mars_ctx, 0, 0);
18
19              mars_task_event_flag_create(mars_ctx, &host_to_mpu,
20                                              MARS_TASK_EVENT_FLAG_HOST_TO_MPU,
21                                              MARS_TASK_EVENT_FLAG_CLEAR_AUTO);
22
23              mars_task_event_flag_create(mars_ctx, &mpu_to_host,
24                                              MARS_TASK_EVENT_FLAG_MPU_TO_HOST,
25                                              MARS_TASK_EVENT_FLAG_CLEAR_AUTO);
26
27              mars_task_event_flag_create(mars_ctx, &mpu_to_mpu,
28                                              MARS_TASK_EVENT_FLAG_MPU_TO_MPU,
29                                              MARS_TASK_EVENT_FLAG_CLEAR_AUTO);
30
31              mars_task_create(mars_ctx, &task1_id, "Task 1", task1_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
32              mars_task_create(mars_ctx, &task2_id, "Task 2", task2_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
33
34              task_args.type.u64[0] = mars_ptr_to_ea(host_to_mpu);
35              task_args.type.u64[1] = mars_ptr_to_ea(mpu_to_mpu);
36              mars_task_schedule(&task1_id, &task_args, 0);
37
38              task_args.type.u64[0] = mars_ptr_to_ea(mpu_to_mpu);
39              task_args.type.u64[1] = mars_ptr_to_ea(mpu_to_host);
40              mars_task_schedule(&task2_id, &task_args, 0);
41
42              sleep(1);
43
44              mars_task_event_flag_set(host_to_mpu, 0x1);
45              mars_task_event_flag_wait(mpu_to_host, 0x1, MARS_TASK_EVENT_FLAG_MASK_AND, NULL);
46
47              mars_task_wait(&task1_id, NULL);
48              mars_task_wait(&task2_id, NULL);
49
50              mars_task_destroy(&task1_id);
51              mars_task_destroy(&task2_id);
52
53              mars_task_event_flag_destroy(host_to_mpu);
54              mars_task_event_flag_destroy(mpu_to_host);
55              mars_task_event_flag_destroy(mpu_to_mpu);
56
57              mars_context_destroy(mars_ctx);
58
59              return 0;
60      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              uint64_t host_to_mpu_ea = task_args->type.u64[0];
 7              uint64_t mpu_to_mpu_ea = task_args->type.u64[1];
 8
 9              mars_task_event_flag_wait(host_to_mpu_ea, 0x1,
10                                      MARS_TASK_EVENT_FLAG_MASK_AND, NULL);
11
12              printf("MPU(%d): %s - Hello!\n",
13                      mars_task_get_kernel_id(), mars_task_get_name());
14
15              mars_task_event_flag_set(mpu_to_mpu_ea, 0x1);
16
17              return 0;
18      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              uint64_t mpu_to_mpu_ea = task_args->type.u64[0];
 7              uint64_t mpu_to_host_ea = task_args->type.u64[1];
 8
 9              mars_task_event_flag_wait(mpu_to_mpu_ea, 0x1,
10                                      MARS_TASK_EVENT_FLAG_MASK_AND, NULL);
11
12              printf("MPU(%d): %s - Hello!\n",
13                      mars_task_get_kernel_id(), mars_task_get_name());
14
15              mars_task_event_flag_set(mpu_to_host_ea, 0x1);
16
17              return 0;
18      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      #define NUM_TASKS       3
 5      #define NUM_ENTRIES     10
 6      #define QUEUE_DEPTH     (NUM_TASKS * NUM_ENTRIES)
 7
 8      struct queue_entry {
 9              char text[64];
10      };
11
12      static void *task1_program_elf_image;
13      static void *task2_program_elf_image;
14
15      int main(void)
16      {
17              struct mars_context *mars_ctx;
18              struct mars_task_id task1_id[NUM_TASKS];
19              struct mars_task_id task2_id[NUM_TASKS];
20              struct mars_task_args task_args;
21              struct mars_task_queue *host_to_mpu;
22              struct mars_task_queue *mpu_to_host;
23              struct mars_task_queue *mpu_to_mpu;
24              struct queue_entry data;
25              int i;
26
27              mars_context_create(&mars_ctx, 0, 0);
28
29              mars_task_queue_create(mars_ctx, &host_to_mpu,
30                                      sizeof(struct queue_entry), QUEUE_DEPTH,
31                                      MARS_TASK_QUEUE_HOST_TO_MPU);
32
33              mars_task_queue_create(mars_ctx, &mpu_to_host,
34                                      sizeof(struct queue_entry), QUEUE_DEPTH,
35                                      MARS_TASK_QUEUE_MPU_TO_HOST);
36
37              mars_task_queue_create(mars_ctx, &mpu_to_mpu,
38                                      sizeof(struct queue_entry), QUEUE_DEPTH,
39                                      MARS_TASK_QUEUE_MPU_TO_MPU);
40
41              for (i = 0; i < NUM_TASKS; i++) {
42                      char name[MARS_TASK_NAME_LEN_MAX];
43
44                      snprintf(name, MARS_TASK_NAME_LEN_MAX, "Task 1.%d", i + 1);
45                      mars_task_create(mars_ctx, &task1_id[i], name, task1_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
46
47                      snprintf(name, MARS_TASK_NAME_LEN_MAX, "Task 2.%d", i + 1);
48                      mars_task_create(mars_ctx, &task2_id[i], name, task2_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
49
50                      task_args.type.u64[0] = mars_ptr_to_ea(host_to_mpu);
51                      task_args.type.u64[1] = mars_ptr_to_ea(mpu_to_mpu);
52                      task_args.type.u32[4] = NUM_ENTRIES;
53                      mars_task_schedule(&task1_id[i], &task_args, 0);
54
55                      task_args.type.u64[0] = mars_ptr_to_ea(mpu_to_mpu);
56                      task_args.type.u64[1] = mars_ptr_to_ea(mpu_to_host);
57                      task_args.type.u32[4] = NUM_ENTRIES;
58                      mars_task_schedule(&task2_id[i], &task_args, 0);
59              }
60
61              for (i = 0; i < QUEUE_DEPTH; i++) {
62                      sprintf(data.text, "Host Data %d", i + 1);
63                      mars_task_queue_push(host_to_mpu, &data);
64              }
65
66              for (i = 0; i < QUEUE_DEPTH; i++) {
67                      mars_task_queue_pop(mpu_to_host, &data);
68                      printf("%s\n", data.text);
69              }
70
71              for (i = 0; i < NUM_TASKS; i++) {
72                      mars_task_wait(&task1_id[i], NULL);
73                      mars_task_wait(&task2_id[i], NULL);
74
75                      mars_task_destroy(&task1_id[i]);
76                      mars_task_destroy(&task2_id[i]);
77              }
78
79              mars_task_queue_destroy(host_to_mpu);
80              mars_task_queue_destroy(mpu_to_host);
81              mars_task_queue_destroy(mpu_to_mpu);
82
83              mars_context_destroy(mars_ctx);
84
85              return 0;
86      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      struct queue_entry {
 5              char text[64];
 6      };
 7
 8      int mars_task_main(const struct mars_task_args *task_args)
 9      {
10              int i;
11              uint64_t host_to_mpu_ea = task_args->type.u64[0];
12              uint64_t mpu_to_mpu_ea = task_args->type.u64[1];
13              uint32_t num_entries = task_args->type.u32[4];
14              struct queue_entry data;
15
16              for (i = 0; i < num_entries; i++) {
17                      mars_task_queue_pop(host_to_mpu_ea, &data);
18
19                      sprintf(&data.text[strlen(data.text)], " -> %s Data %d",
20                              mars_task_get_name(), i + 1);
21
22                      mars_task_queue_push(mpu_to_mpu_ea, &data);
23              }
24
25              return 0;
26      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      struct queue_entry {
 5              char text[64];
 6      };
 7
 8      int mars_task_main(const struct mars_task_args *task_args)
 9      {
10              int i;
11              uint64_t mpu_to_mpu_ea = task_args->type.u64[0];
12              uint64_t mpu_to_host_ea = task_args->type.u64[1];
13              uint32_t num_entries = task_args->type.u32[4];
14              struct queue_entry data;
15
16              for (i = 0; i < num_entries; i++) {
17                      mars_task_queue_pop(mpu_to_mpu_ea, &data);
18
19                      sprintf(&data.text[strlen(data.text)], " -> %s Data %d",
20                              mars_task_get_name(), i + 1);
21
22                      mars_task_queue_push(mpu_to_host_ea, &data);
23              }
24
25              return 0;
26      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      #define NUM_TASKS       10
 5
 6      static void *task_program_elf_image;
 7
 8      int main(void)
 9      {
10              struct mars_context *mars_ctx;
11              struct mars_task_id task_id[NUM_TASKS];
12              struct mars_task_args task_args;
13              struct mars_task_semaphore *semaphore;
14              uint32_t shared_resource __attribute__((aligned(16)));
15              int i;
16
17              mars_context_create(&mars_ctx, 0, 0);
18
19              mars_task_semaphore_create(mars_ctx, &semaphore, 1);
20
21              shared_resource = 0;
22
23              printf("HOST  : Main() - Shared Resource Counter = %d\n", shared_resource);
24
25              for (i = 0; i < NUM_TASKS; i++) {
26                      char name[16];
27                      sprintf(name, "Task %d", i);
28
29                      mars_task_create(mars_ctx, &task_id[i], name, task_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
30
31                      task_args.type.u64[0] = mars_ptr_to_ea(semaphore);
32                      task_args.type.u64[1] = mars_ptr_to_ea(&shared_resource);
33                      mars_task_schedule(&task_id[i], &task_args, 0);
34              }
35
36              for (i = 0; i < NUM_TASKS; i++) {
37                      mars_task_wait(&task_id[i], NULL);
38                      mars_task_destroy(&task_id[i]);
39              }
40
41              printf("HOST  : Main() - Shared Resource Counter = %d\n", shared_resource);
42
43              mars_task_semaphore_destroy(semaphore);
44
45              mars_context_destroy(mars_ctx);
46
47              return 0;
48      }

 1      #include <mars/mars.h>
 2
 3      int mars_task_main(const struct mars_task_args *task_args)
 4      {
 5              uint64_t semaphore_ea = task_args->type.u64[0];
 6              uint64_t shared_resource_ea = task_args->type.u64[1];
 7              uint32_t shared_resource __attribute__((aligned(16)));
 8
 9              mars_task_semaphore_acquire(semaphore_ea);
10
11              get(&shared_resource, shared_resource_ea, sizeof(uint32_t));
12
13              shared_resource++;
14
15              put(&shared_resource, shared_resource_ea, sizeof(uint32_t));
16
17              mars_task_semaphore_release(semaphore_ea);
18
19              return 0;
20      }

 1      #include <unistd.h>
 2      #include <mars/mars.h>
 3
 4      static void *task1_program_elf_image;
 5      static void *task2_program_elf_image;
 6
 7      int main(void)
 8      {
 9              struct mars_context *mars_ctx;
10              struct mars_task_id task1_id;
11              struct mars_task_id task2_id;
12              struct mars_task_args task_args;
13
14              mars_context_create(&mars_ctx, 0, 0);
15
16              mars_task_create(mars_ctx, &task1_id, "Task 1", task1_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
17              mars_task_create(mars_ctx, &task2_id, "Task 2", task2_program_elf_image, MARS_TASK_CONTEXT_SAVE_ALL);
18
19              task_args.type.u64[0] = mars_ptr_to_ea(&task2_id);
20              mars_task_schedule(&task1_id, &task_args, 0);
21
22              task_args.type.u64[0] = mars_ptr_to_ea(&task1_id);
23              mars_task_schedule(&task2_id, &task_args, 0);
24
25              sleep(1);
26
27              mars_task_signal_send(&task1_id);
28
29              mars_task_wait(&task1_id, NULL);
30              mars_task_wait(&task2_id, NULL);
31
32              mars_task_destroy(&task1_id);
33              mars_task_destroy(&task2_id);
34
35              mars_context_destroy(mars_ctx);
36
37              return 0;
38      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              struct mars_task_id task2_id;
 7
 8              get(&task2_id, task_args->type.u64[0], sizeof(struct mars_task_id));
 9
10              mars_task_signal_wait();
11
12              printf("MPU(%d): %s - Hello!\n",
13                      mars_task_get_kernel_id(), mars_task_get_name());
14
15              mars_task_signal_send(&task2_id);
16
17              mars_task_signal_wait();
18
19              return 0;
20      }

 1      #include <stdio.h>
 2      #include <mars/mars.h>
 3
 4      int mars_task_main(const struct mars_task_args *task_args)
 5      {
 6              struct mars_task_id task1_id;
 7
 8              get(&task1_id, task_args->type.u64[0], sizeof(struct mars_task_id));
 9
10              mars_task_signal_wait();
11
12              printf("MPU(%d): %s - Hello!\n",
13                      mars_task_get_kernel_id(), mars_task_get_name());
14
15              mars_task_signal_send(&task1_id);
16
17              return 0;
18      }

  1     #include <stdio.h>
  2     #include <stdlib.h>
  3     #include <string.h>
  4     #include <malloc.h>
  5     #include <sys/stat.h>
  6     #include <libspe2.h>
  7     #include <mars/mars.h>
  8
  9     #define IN_FILENAME     "in.ppm"
 10     #define OUT_FILENAME    "out.ppm"
 11     #define PPM_MAGIC       "P6"
 12
 13     #define NUM_TASKS       4
 14     #define QUEUE_DEPTH     4
 15
 16     typedef struct _image_t {
 17             int width;
 18             int height;
 19             unsigned char *src;
 20             unsigned char *dst;
 21     } image_t;
 22
 23     typedef struct {
 24             uint64_t ea_task_id;
 25             uint64_t ea_event;
 26             uint64_t ea_queue;
 27             uint64_t ea_src;
 28             uint64_t ea_dst;
 29             uint32_t num;
 30             uint32_t pad;
 31     } grayscale_params_t;
 32
 33     typedef struct {
 34             uint64_t ea_event;
 35             uint64_t ea_src;
 36             uint64_t ea_dst;
 37             uint32_t num;
 38             uint32_t id;
 39     } grayscale_queue_elem_t;
 40
 41     extern struct spe_program_handle task1_spe_prog;
 42     extern struct spe_program_handle task2_spe_prog;
 43
 44     static struct mars_context *mars_ctx;
 45     static struct mars_task_id task1_id;
 46     static struct mars_task_id task2_id[NUM_TASKS];
 47     static struct mars_task_args task_args;
 48     static struct mars_task_event_flag *event;
 49     static struct mars_task_queue *queue;
 50
 51     static grayscale_params_t grayscale_params __attribute__((aligned(16)));
 52
 53     /* initialize MARS execution environment for rgb2y processing */
 54     void rgb2y(unsigned char *src, unsigned char *dst, int num)
 55     {
 56             int ret, i;
 57
 58             ret = mars_context_create(&mars_ctx, 0, 0);
 59             if (ret) {
 60                     printf("Could not create MARS context! (%d)\n", ret);
 61                     exit(1);
 62             }
 63
 64             ret = mars_task_event_flag_create(mars_ctx, &event,
 65                                             MARS_TASK_EVENT_FLAG_MPU_TO_MPU,
 66                                             MARS_TASK_EVENT_FLAG_CLEAR_AUTO);
 67             if (ret) {
 68                     printf("Could not create MARS task event flag! (%d)\n", ret);
 69                     exit(1);
 70             }
 71
 72             ret = mars_task_queue_create(mars_ctx, &queue,
 73                                             sizeof(grayscale_queue_elem_t),
 74                                             QUEUE_DEPTH,
 75                                             MARS_TASK_QUEUE_MPU_TO_MPU);
 76             if (ret) {
 77                     printf("Could not create MARS task queue! (%d)\n", ret);
 78                     exit(1);
 79             }
 80
 81             ret = mars_task_create(mars_ctx, &task1_id,
 82                                     "Grayscale Main Task",
 83                                     task1_spe_prog.elf_image,
 84                                     MARS_TASK_CONTEXT_SAVE_ALL);
 85             if (ret) {
 86                     printf("Could not create MARS main task! (%d)\n", ret);
 87                     exit(1);
 88             }
 89
 90             for (i = 0; i < NUM_TASKS; i++) {
 91                     ret = mars_task_create(mars_ctx, &task2_id[i],
 92                                             "Grayscale Sub Task",
 93                                             task2_spe_prog.elf_image,
 94                                             MARS_TASK_CONTEXT_SAVE_ALL);
 95                     if (ret) {
 96                             printf("Could not create MARS sub task! (%d)\n", ret);
 97                             exit(1);
 98                     }
 99             }
100
101             /* initialize grayscale params */
102             grayscale_params.ea_task_id = mars_ptr_to_ea(&task2_id);
103             grayscale_params.ea_event   = mars_ptr_to_ea(event);
104             grayscale_params.ea_queue   = mars_ptr_to_ea(queue);
105             grayscale_params.ea_src     = mars_ptr_to_ea(src);
106             grayscale_params.ea_dst     = mars_ptr_to_ea(dst);
107             grayscale_params.num        = num;
108
109             /* initialize task args */
110             task_args.type.u64[0] = mars_ptr_to_ea(&grayscale_params);
111
112             ret = mars_task_schedule(&task1_id, &task_args, 0);
113             if (ret) {
114                     printf("Could not schedule MARS main task! (%d)\n", ret);
115                     exit(1);
116             }
117
118             ret = mars_task_wait(&task1_id, NULL);
119             if (ret) {
120                     printf("Could not wait for MARS main task! (%d)\n", ret);
121                     exit(1);
122             }
123
124             ret = mars_task_destroy(&task1_id);
125             if (ret) {
126                     printf("Could not destroy MARS main task! (%d)\n", ret);
127                     exit(1);
128             }
129
130             for (i = 0; i < NUM_TASKS; i++) {
131                     ret = mars_task_destroy(&task2_id[i]);
132                     if (ret) {
133                             printf("Could not destroy MARS sub task! (%d)\n", ret);
134                             exit(1);
135                     }
136             }
137
138             ret = mars_context_destroy(mars_ctx);
139             if (ret) {
140                     printf("Could not destroy MARS context! (%d)\n", ret);
141                     exit(1);
142             }
143     }
144
145     /* read ppm data from input file */
146     void read_ppm(image_t *img, char *fname)
147     {
148             char *token, *pc, *buf, *del = " \t\n";
149             int i, w, h, luma, pixs, filesize;
150             struct stat st;
151             unsigned char *dot;
152             FILE *fp;
153
154             /* read raw data */
155             stat(fname, &st);
156             filesize = (int) st.st_size;
157             buf = (char *) malloc(filesize * sizeof(char));
158
159             if ((fp = fopen(fname, "r")) == NULL) {
160                     fprintf(stderr, "error: failed to open file %s\n", fname);
161                     exit(1);
162             }
163
164             fseek(fp, 0, SEEK_SET);
165             fread(buf, filesize * sizeof(char), 1, fp);
166             fclose(fp);
167
168             /* validate file format */
169             token = (char *) (unsigned long) strtok(buf, del);
170             if (strncmp(token, PPM_MAGIC, 2) != 0) {
171                     fprintf(stderr, "error: invalid file format\n");
172                     exit(1);
173             }
174
175             /* skip comments */
176             token = (char *) (unsigned long) strtok(NULL, del);
177             if (token[0] == '#') {
178                     token = (char *) (unsigned long) strtok(NULL, "\n");
179                     token = (char *) (unsigned long) strtok(NULL, del);
180             }
181
182             /* read picture size (and luma) */
183             w = strtoul(token, &pc, 10);
184             token = (char *) (unsigned long) strtok(NULL, del);
185             h = strtoul(token, &pc, 10);
186             token = (char *) (unsigned long) strtok(NULL, del);
187             luma = strtoul(token, &pc, 10);
188
189             img->width = w;
190             img->height = h;
191
192             /* allocate an aligned memory */
193             pixs = w * h;
194             img->src = (unsigned char *)memalign(16, pixs*4);
195             img->dst = (unsigned char *)memalign(16, pixs*4);
196
197             /* read rgb data with 'r,g,b,0' formatted */
198             dot = img->src;
199             pc++;
200             for (i = 0; i < pixs*4; i++) {
201                     if (i % 4 == 3) {
202                             *dot++ = 0;
203                     } else {
204                             *dot++ = *pc++;
205                     }
206             }
207
208             return;
209     }
210
211     /* write ppm data to output file */
212     void write_ppm(image_t *img, char *fname)
213     {
214             int i;
215             int w = img->width;
216             int h = img->height;
217             unsigned char *dot = img->dst;
218             FILE *fp;
219
220             if ((fp = fopen(fname, "wb+")) == NULL) {
221                     fprintf(stderr, "failed to open file %s\n", fname);
222                     exit(1);
223             }
224
225             fprintf(fp, "%s\n", PPM_MAGIC);
226             fprintf(fp, "%d %d\n", w, h);
227             fprintf(fp, "255\n");
228
229             for (i = 0; i < (w * h * 4); i++) {
230                     if (i % 4 == 3) {
231                             dot++;
232                     } else {
233                             putc((int) *dot++, fp);
234                     }
235             }
236
237             fclose(fp);
238
239             return;
240     }
241
242     void delete_image(image_t *img)
243     {
244             free(img->src);
245             free(img->dst);
246
247             return;
248     }
249
250     int main(int argc, char **argv)
251     {
252             image_t image;
253
254             printf(INFO);
255
256             read_ppm(&image, IN_FILENAME);
257
258             rgb2y(image.src, image.dst, image.width * image.height);
259
260             write_ppm(&image, OUT_FILENAME);
261
262             delete_image(&image);
263
264             return 0;
265     }

  1     #include <stdio.h>
  2     #include <stdint.h>
  3     #include <spu_intrinsics.h>
  4     #include <spu_mfcio.h>
  5     #include <mars/mars.h>
  6
  7     #define NUM_TASKS       4
  8
  9     #define ALIGN4_UP(x)    (((x) + 0x3) & ~0x3)
 10
 11     typedef struct {
 12             uint64_t ea_task_id;
 13             uint64_t ea_event;
 14             uint64_t ea_queue;
 15             uint64_t ea_src;
 16             uint64_t ea_dst;
 17             uint32_t num;
 18             uint32_t pad;
 19     } grayscale_params_t;
 20
 21     typedef struct {
 22             uint64_t ea_event;
 23             uint64_t ea_src;
 24             uint64_t ea_dst;
 25             uint32_t num;
 26             uint32_t id;
 27     } grayscale_queue_elem_t;
 28
 29     static struct mars_task_id task2_id[NUM_TASKS];
 30     static struct mars_task_args task2_args;
 31
 32     static grayscale_params_t grayscale_params __attribute__((aligned(16)));
 33     static grayscale_queue_elem_t data __attribute__((aligned(16)));
 34
 35     int mars_task_main(const struct mars_task_args *task_args)
 36     {
 37             int ret, i, tag = 0;
 38             int num, remain, chunk;
 39             uint64_t ea_task_id, ea_event, ea_queue;
 40             uint64_t ea_src, ea_dst;
 41             uint16_t mask = 0;
 42
 43             /* Get application parameters */
 44             mfc_get(&grayscale_params, task_args->type.u64[0], sizeof(grayscale_params_t), tag, 0, 0);
 45             mfc_write_tag_mask(1 << tag);
 46             mfc_read_tag_status_all();
 47
 48             ea_task_id = grayscale_params.ea_task_id;
 49             ea_event   = grayscale_params.ea_event;
 50             ea_queue   = grayscale_params.ea_queue;
 51             ea_src     = grayscale_params.ea_src;
 52             ea_dst     = grayscale_params.ea_dst;
 53             num        = grayscale_params.num;
 54
 55             /* Get sub task ids */
 56             mfc_get(&task2_id, ea_task_id, sizeof(struct mars_task_id) * NUM_TASKS, tag, 0, 0);
 57             mfc_write_tag_mask(1 << tag);
 58             mfc_read_tag_status_all();
 59
 60             /* Pass queue ea to sub task args */
 61             task2_args.type.u64[0] = ea_queue;
 62
 63             /* Schedule sub tasks for execution */
 64             for (i = 0; i < NUM_TASKS; i++) {
 65                     ret = mars_task_schedule(&task2_id[i], &task2_args, 0);
 66                     if (ret) {
 67                             printf("Could not schedule MARS sub task! (%d)\n", ret);
 68                             return 1;
 69                     }
 70             }
 71
 72             remain = num;
 73             chunk = num/NUM_TASKS;
 74             for (i = 0; i < NUM_TASKS; i++) {
 75                     data.ea_event = ea_event;
 76                     data.ea_src   = ea_src;
 77                     data.ea_dst   = ea_dst;
 78                     data.id       = i;
 79                     if (remain > chunk) {
 80                             data.num = ALIGN4_UP(chunk);
 81                     } else {
 82                             data.num = ALIGN4_UP(remain);
 83                     }
 84
 85                     /* Push data to queue */
 86                     ret = mars_task_queue_push_begin(ea_queue, &data, tag);
 87                     if (ret) {
 88                             printf("Could not push data to MARS task queue! (%d)\n", ret);
 89                             return 1;
 90                     }
 91                     ret = mars_task_queue_push_end(ea_queue, tag);
 92                     if (ret) {
 93                             printf("Could not complete data push to MARS task queue! (%d)\n", ret);
 94                             return 1;
 95                     }
 96
 97                     remain -= chunk;
 98                     ea_src += (chunk * 4);
 99                     ea_dst += (chunk * 4);
100
101                     /* Create event mask */
102                     mask |= 1 << i;
103             }
104
105             /* Wait until specified bits are set to event flag */
106             ret = mars_task_event_flag_wait(ea_event, mask, MARS_TASK_EVENT_FLAG_MASK_AND, NULL);
107             if (ret) {
108                     printf("Could not wait for MARS task event flag! (%d)\n", ret);
109                     return 1;
110             }
111
112             /* Wait for all scheduled sub tasks to complete */
113             for (i = 0; i < NUM_TASKS; i++) {
114                     ret = mars_task_wait(&task2_id[i], NULL);
115                     if (ret) {
116                             printf("Could not wait for MARS sub task! (%d)\n", ret);
117                             return 1;
118                     }
119             }
120
121             return 0;
122     }

  1     #include <stdio.h>
  2     #include <stdint.h>
  3     #include <spu_intrinsics.h>
  4     #include <spu_mfcio.h>
  5     #include <mars/mars.h>
  6
  7     #define MAX_BUFSIZE     (16 << 10)
  8
  9     typedef struct {
 10             uint64_t ea_event;
 11             uint64_t ea_src;
 12             uint64_t ea_dst;
 13             uint32_t num;
 14             uint32_t id;
 15     } grayscale_queue_elem_t;
 16
 17     static unsigned char src_spe[MAX_BUFSIZE] __attribute__((aligned(128)));
 18     static unsigned char dst_spe[MAX_BUFSIZE] __attribute__((aligned(128)));
 19
 20     static grayscale_queue_elem_t data __attribute__((aligned(16)));
 21
 22     void rgb2y(unsigned char *src, unsigned char *dst, int num)
 23     {
 24             int i;
 25
 26             __vector unsigned char *vsrc = (__vector unsigned char *) src;
 27             __vector unsigned char *vdst = (__vector unsigned char *) dst;
 28
 29             __vector unsigned int vr, vg, vb, vy, vpat;
 30             __vector float vfr, vfg, vfb, vfy;
 31
 32             __vector float vrconst = spu_splats(0.29891f);
 33             __vector float vgconst = spu_splats(0.58661f);
 34             __vector float vbconst = spu_splats(0.11448f);
 35             __vector float vfzero = spu_splats(0.0f);
 36             __vector unsigned int vmax = spu_splats((unsigned int) 255);
 37
 38             __vector unsigned char vpatr = (__vector unsigned char) { 0x10, 0x10, 0x10, 0x00,
 39                                                                     0x10, 0x10, 0x10, 0x04,
 40                                                                     0x10, 0x10, 0x10, 0x08,
 41                                                                     0x10, 0x10, 0x10, 0x0c };
 42             __vector unsigned char vpatg = (__vector unsigned char) { 0x10, 0x10, 0x10, 0x01,
 43                                                                     0x10, 0x10, 0x10, 0x05,
 44                                                                     0x10, 0x10, 0x10, 0x09,
 45                                                                     0x10, 0x10, 0x10, 0x0d };
 46             __vector unsigned char vpatb = (__vector unsigned char) { 0x10, 0x10, 0x10, 0x02,
 47                                                                     0x10, 0x10, 0x10, 0x06,
 48                                                                     0x10, 0x10, 0x10, 0x0a,
 49                                                                     0x10, 0x10, 0x10, 0x0e };
 50             __vector unsigned char vpaty = (__vector unsigned char) { 0x03, 0x03, 0x03, 0x10,
 51                                                                     0x07, 0x07, 0x07, 0x10,
 52                                                                     0x0b, 0x0b, 0x0b, 0x10,
 53                                                                     0x0f, 0x0f, 0x0f, 0x10 };
 54             __vector unsigned char vzero = spu_splats((unsigned char) 0);
 55
 56             for (i = 0; i < num/4; i++) {
 57                     vr = (__vector unsigned int) spu_shuffle(vsrc[i], vzero, vpatr);
 58                     vg = (__vector unsigned int) spu_shuffle(vsrc[i], vzero, vpatg);
 59                     vb = (__vector unsigned int) spu_shuffle(vsrc[i], vzero, vpatb);
 60
 61                     vfr = spu_convtf(vr, 0);
 62                     vfg = spu_convtf(vg, 0);
 63                     vfb = spu_convtf(vb, 0);
 64
 65                     vfy = spu_madd(vfr, vrconst, vfzero);
 66                     vfy = spu_madd(vfg, vgconst, vfy);
 67                     vfy = spu_madd(vfb, vbconst, vfy);
 68             
 69                     vy = spu_convtu(vfy, 0);
 70
 71                     vpat = spu_cmpgt(vy, vmax);
 72                     vy = spu_sel(vy, vmax, vpat);
 73
 74                     vdst[i] = (__vector unsigned char) spu_shuffle(vy, (__vector unsigned int) vzero, vpaty);
 75             }
 76
 77             return;
 78     }
 79
 80     int mars_task_main(const struct mars_task_args *task_args)
 81     {
 82             int ret, tag = 0;
 83             int my_id;
 84             uint64_t ea_event, ea_queue;
 85             uint16_t bits;
 86             uint64_t ea_src, ea_dst;
 87             unsigned int remain, num;
 88
 89             ea_queue = task_args->type.u64[0];
 90
 91             /* Pop data from queue */
 92             ret = mars_task_queue_pop_begin(ea_queue, &data, tag);
 93             if (ret) {
 94                     printf("Could not pop data from MARS task queue! (%d)\n", ret);
 95                     return 1;
 96             }
 97             ret = mars_task_queue_pop_end(ea_queue, tag);
 98             if (ret) {
 99                     printf("Could not complete data pop from MARS task queue! (%d)\n", ret);
100                     return 1;
101             }
102
103             my_id    = data.id;
104             ea_event = data.ea_event;
105             ea_src   = data.ea_src;
106             ea_dst   = data.ea_dst;
107             remain   = data.num;
108
109             /* main loop */
110             while (remain > 0) {
111                     if (remain > MAX_BUFSIZE/4) {
112                             num = MAX_BUFSIZE/4;
113                     } else {
114                             num = remain;
115                     }
116
117                     /* DMA Transfer : GET input data */
118                     mfc_get(src_spe, ea_src, num * 4, tag, 0, 0);
119                     mfc_write_tag_mask(1 << tag);
120                     mfc_read_tag_status_all();
121
122                     /* convert to grayscale data */
123                     rgb2y(src_spe, dst_spe, num);
124
125                     /* DMA Transfer : PUT output data */
126                     mfc_put(dst_spe, ea_dst, num * 4, tag, 0, 0);
127                     mfc_write_tag_mask(1 << tag);
128                     mfc_read_tag_status_all();
129
130                     remain -= num;
131                     ea_src += num * 4;
132                     ea_dst += num * 4;
133             }
134
135             /* Set bit to SPURS event flag */
136             bits = 1 << my_id;
137             ret = mars_task_event_flag_set(ea_event, bits);
138             if (ret) {
139                     printf("Could not set MARS task event flag! (%d)\n", ret);
140                     return 1;
141             }
142
143             return 0;
144     }

Line:1	Include the header file "mars/mars.h" necessary for utilizing the MARS library.
Line:3	Pointer to the task program's ELF image in host storage. The procedure to load the task program into host storage is platform specific. Therefore, the code to do so is not shown anywhere in this sample code.
Line:7	Declare the MARS context pointer.
Line:8	Declare the structure for storing the MARS task id.
Line:9	Declare the instance to store the task exit code.
Line:11	Create the MARS context instance. int mars_context_create ( arg1: This is the address of the pointer to MARS context declared at Line:7. A MARS context will be created and its address stored in this pointer. arg2: This is the number of MPUs you want utilized by this MARS context. The number of MPUs specified must be available by the system or an error is returned. Here 0 is specifified to have MARS utilize all the available MPUs for the context. arg3: This specifies if you are requesting a shared context. Here 0 is specified since we do not require sharing the MARS context for this sample. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Line:12	Create the MARS task instance. int mars_task_create ( arg1: Pass in the MARS context pointer. arg2: Pass in the pointer to MARS task id structure declared at Line:8. Upon successful completion, the task id will be initialized as required. arg3: Specify the NULL terminated string name of the task you want to create. arg4: Specify the address of the task program's ELF image that is loaded into host storage. The task program specified here is what will be loaded into MPU storage for execution when this task is scheduled to run by the MARS kernel. arg5: Specify the context save area size for this task. Since this task will not be yielding execution or entering a wait state, we do not need to initialize a context save area so specify 0 for context save area size. Otherwise, to initialize a context save area, specify MARS_TASK_CONTEXT_SAVE_ALL. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Line:13	Schedule the task for execution. int mars_task_schedule ( arg1: Pass in the pointer to the task id initialized at Line:12. arg2: Pass in the pointer to the task arg structure we want to pass into the task program's mars_task_main function. For this sample we do not need to pass any args into the task program so specify NULL. arg3: Pass in the value for the scheduling priority this task. Since we only schedule 1 task for execution, the scheduling priority has no effect in this example. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Line:14	Wait for the completion of the task. int mars_task_wait ( arg1: Pass in the pointer to the task id we want to wait for. arg2: Pass in the address of the variable to store the task exit code declared at Line:9. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) This call will block until the task previously scheduled in Line:13 completes execution. If we want to process some other tasks in the host program while waiting for the task to complete, we can do so before calling wait. Similarly, a non-blocking wait function mars_task_try_wait is also provided to poll for task completion.
Line:15	Destroy the completed task. int mars_task_destroy ( arg1: Pass in the pointer to the task id we want to destroy. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) We can only call this function when we are sure the task has finished. In this example we are sure of completion because we properly waited for task completion in Line:18. After the task is destroyed, we can no longer schedule this task for execution.
Line:16	Destroy the MARS context. int mars_context_destroy ( arg1: Pass in the pointer to the MARS context we want to finalize. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) This unloads all running MARS kernels from the MPUs and handles any necessary cleanup for the MARS library. No more MARS API calls can be made after this function until the MARS context is created once again.

Lines:1-2	Include the header file "stdio.h" for printf and "mars/mars.h" necessary for utilizing the MARS library.
Line:6	Since we specified NULL for the task args in Line:13 of the host program above, the state of task_args is undefined. In this program we do not and should not access the task_args.
Lines:8-9	Print out message to stdout. The calls to mars_task_get_kernel_id returns the id of the kernel that the current task is running on. The calls to mars_task_get_name return the string name of the current running task specified during task creation at Line:12 of the host program above.
Line:11	Returning from mars_task_main completes execution of the task. This will signal anything waiting for this task's completion to resume execution. In this example, the host program's call to mars_task_wait in Line:14 will return. Equivalent to returning from mars_task_main, we can also call mars_task_exit. The return value will be returned to the host program in the variable passed into mars_task_wait.

Line:13	Declare an instance of the task id structure for each sub task we want to create and schedule.
Lines:19	Create the main task instance with the ELF image of task program 1. The main task needs to provide a context save area in order to allow for context switching while waiting for sub task completion. Specify MARS_TASK_CONTEXT_SAVE_ALL for the context save area size so a context save area is initialized for the main task context.
Lines:21-25	Create the 2 sub task instances with the ELF image of task program 2. The sub task does not need to do a context switch so no context save area size needs to specified.
Lines:27-28	The main task needs to know the addresses of the task ids it plans to schedule for execution. Store each sub task id address into the task args passed into the main task's mars_task_main function.
Line:30	Schedule the main task for execution. Pass in the task args we initialized with the sub task id addresses at Lines:27-28. Since we only schedule 1 main task for execution, and the main task is waiting when any one of its sub task's is being executed, the scheduling priority specified has no effect in this example.
Line:31	Wait for the completion of the main task.
Line:32	Destroy the completed main task.
Line:34-35	Destroy the completed sub tasks also.

Line:3	Since the task args were passed into mars_task_schedule at Line:30 of the host program, task_args is pointing to an initialized mars_task_args structure.
Line:5	Declare an instance to store the task id of the first sub task to execute.
Line:6	Declare an instance to store the task id of the second sub task to execute.
Line:7	Declare an instance or the task arg structure we want to initialize with unique IDs to pass into the sub tasks.
Lines:9-10	Memory transfer from host storage to MPU storage the task id structures of the initialized sub tasks. The host storage addresses of these task id structures were specified at Lines:27-28 of the host program. The function "get" shown here is a generic place holder for the platform specific function to do the memory transfer. Please refer to your platform specific API to learn how to do the memory transfer from host storage to MPU storage on your specific platform.
Lines:12-13	Initialize the task args structure with a unique value. Schedule the first sub task instance using the task id obtained at Line:9. Pass in the task args and priority of 0.
Lines:15-16	Initialize the task args structure with a unique value. Schedule the second sub task instance using the task id obtained at Line:10. Pass in the task args and priority of 0.
Lines:18-19	Wait for the completion of both sub tasks. If the first sub task has not finished execution by the time of the call to mars_task_wait at Line:18, this main task will enter a wait state and its context will be switched out. When the first sub task completes execution, this main task will resume execution and continue on to wait for the second sub task to complete. Similarly, at the time of the call to mars_task_wait at Line:19, if the second sub task has not yet completed it will enter a wait state once again until completion of the second sub task.

Line:4	Since the task args were passed into mars_task_schedule at Line:13 and Line:16 of the main task 1 program, task_args is pointing to an initialized mars_task_args structure. This structure contains the unique value specified by the main task 1 program.
Lines:6-8	Print out message to stdout. Print out the unique value specified by the main task 1 program. This value should be unique for each sub task program.

Line:12	Declare an array of 10 task ids for each instance of task 1 program we plan to create and schedule.
Line:13	Declare one instance of the task id structure for the final task 2 program we plan to create and schedule.
Line:15	Declare an instance of the task barrier structure pointer.
Line:20	Create the task barrier instance. int mars_task_barrier_create ( arg1: Pass in the MARS context pointer. arg2: Pass in the address to the barrier pointer we declared at Line:15. arg3: Pass in the total number of task notifications to wait for before the barrier is released. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Line:26	Create each of the 10 task 1 instances. Specify the task 1 program ELF image for these task instances and a context save area size of MARS_TASK_CONTEXT_SAVE_ALL to allow these tasks to context switch.
Lines:28-29	Initialize the task args we want passed into task 1 program's mars_task_main function. Store the barrier address in the task args. Schedule the task instance for execution, passing in the task args.
Lines:32	Create a single task 2 instance. Specify the task 2 program ELF image for these task instances and a context save area size of MARS_TASK_CONTEXT_SAVE_ALL to allow these tasks to context switch.
Lines:34-35	Create the task args we want passed into task 2 program's mars_task_main function. Store the barrier address in the task args. Schedule the task instance for execution, passing in the task args.
Lines:37-47	Wait for completion and destroy all 10 task 1 instances. Wait for completion and destroy the final task instance. Finally destroy the barrier instance and the MARS context.

Lines:13-15	Declare 3 instances of the task event flag structure we plan to create.
Lines:19-29	Create the 3 task event flag instances. int mars_task_event_flag_create ( arg1: Pass in the MARS context pointer. arg2: Pass in the address of the event flag pointer we declared at Lines:13-15. arg3: Pass in the direction of events for each instance. The direction must be MARS_TASK_EVENT_FLAG_HOST_TO_MPU, MARS_TASK_EVENT_FLAG_MPU_TO_HOST, or MARS_TASK_EVENT_FLAG_MPU_TO_MPU. arg4: Pass in the clear mode for each instance. Specify MARS_TASK_EVENT_FLAG_CLEAR_AUTO so the event flag bit is automatically cleared when the first task waiting on the event receives the event. To specify not clearing the event bits automatically so that the event flag bits are set until some task manually clears it, specify MARS_TASK_EVENT_FLAG_CLEAR_MANUAL. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) The first event flag is created for host program to task program events. The second event flag is created for task program to host program events. The third event flag is created for task program to task program events.
Lines:31-32	Create the task instance for both the task 1 program and task 2 program. Specify a context save area size of MARS_TASK_CONTEXT_SAVE_ALL to allow these tasks to context switch.
Lines:34-36	Initialize the task args we want passed into task 1 program's mars_task_main function. Store the event flag addresses for both host to mpu and mpu to mpu communication. These event flags will be used to receive events from the host program and also to send events to task 2 program. Schedule the task instance for execution, passing in the task args.
Lines:38-40	Initialize the task args we want passed into task 2 program's mars_task_main function. Store the event flag addresses for both mpu to mpu and mpu to host communication. These event flags will be used to receive events from the task 1 program and also to send events to the host program. Schedule the task instance for execution, passing in the task args.
Line:42	Sleep for 1 second before continuing. This allows enough time for the tasks to be scheduled and begin execution. This is only to demonstrate the task entering the wait state when waiting for a specific event.
Line:44	Set the event that task 1 is waiting for to allow task 1 to continue execution. int mars_task_event_flag_set ( arg1: Pass in the pointer to the event flag instance we created for host to MPU communication. arg2: Pass in the value specifying which bits to set in the event flag. These bits are logically OR'ed with the bits already set in the event flag. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Line:45	Wait for an event from task 2 before continuing execution. int mars_task_event_flag_wait ( arg1: Pass in the pointer to the task instance we created for MPU to host communication. arg2: Pass in the value specifying which bits to check in the event flag. Specify MARS_TASK_EVENT_FLAG_MASK_OR to wait for any of the specified bits to be set. Specify MARS_TASK_EVENT_FLAG_MASK_AND to wait for all of the specified bits to be set. arg3: Pass in NULL because it is not necessary to know the bits status upon returning from the event wait in this sample. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) If the event flag has not been set by the time of this call, this call will block until the specific event flag bit is set.
Lines:47-57	Wait for completion and destroy the 2 task instances and all event flag instances and finally destroy the MARS context.

Line:6	Grab the host storage address of the event flag initialized in the host program for host to MPU communication from the task arg structure.
Line:7	Grab the host storage address of the event flag initialized in the host program for MPU to MPU communication from the task arg structure.
Lines:9-10	Wait for an event from the host program before continuing execution. Make sure to check for the proper bit set from the host program. If the event flag has not been set by the time of this call, this task will enter a wait state and its context will be switched out. When the event flag bit this task is checking for is set, this task will resume execution and continue.
Line:15	Set the event that task 2 is waiting for to allow task 2 execution to resume.

Lines:8-10	Define the data entry structure. For this sample this is a 64-byte char array.
Lines:21-23	Declare 3 instances of the task queue pointer.
Line:24	Declare a local instance of the task queue data entry structure.
Lines:29-39	Create the 3 task queue instances. int mars_task_queue_create ( arg1: Pass in the MARS context pointer. arg2: Pass in the addresses of the queue pointer instances. arg3: Pass in size of each queue data entry. The size must be a multiple of 16 and not greater than MARS_TASK_QUEUE_ENTRY_SIZE_MAX. arg4: Pass in depth of queue which is the maximum number of data entries allowed in the queue at any time. arg5: Pass in the direction of queue for each instance. The direction must be MARS_TASK_QUEUE_HOST_TO_MPU, MARS_TASK_QUEUE_MPU_TO_HOST, or MARS_TASK_QUEUE_MPU_TO_MPU. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) The first queue is created for host program to task program data passing. The second queue is created for task program to host program data passing. The third queue is created for task program to task program data passing.
Lines:44-48	Create multiple task instances for both the task 1 program and task 2 program. Specify a context save area size of MARS_TASK_CONTEXT_SAVE_ALL to allow these tasks to context switch when there is no data available to be popped from the queues.
Lines:50-53	Initialize the task args we want passed into task 1 program's mars_task_main function. Store the host storage addresses of the queue instances for both host to mpu and mpu to mpu communication. These queues will be used to receive data from the host program and also to send data to task 2 program. Also store the number of data entries task 1 program should expect to process. Schedule the task instance for execution, passing in the task args.
Lines:55-58	Initialize the task args we want passed into task 2 program's mars_task_main function. Store the host storage addresses of the queue instances for both mpu to mpu and mpu to host communication. These queues will be used to receive data from the task 1 program and also to send data to the host program. Also store the number of data entries task 2 program should expect to process. Schedule the task instance for execution, passing in the task args.
Lines:61-64	Loop to push data into the queue for task 1 program to receive. The data is a string identifying the data id number. Initialize the data queue entry structure with some string identifying the data id. int mars_task_queue_push ( arg1: Pass in the pointer to the task queue instance we created for host to MPU communication. arg2: Pass in the pointer to the data queue entry instance we initialized. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Lines:66-69	Loop to pop data from the queue that task 2 program populates with the final result data. int mars_task_queue_pop ( arg1: Pass in the pointer to the task queue instance we created for host to MPU communication. arg2: Pass in the pointer to the data queue entry to store the data from the queue. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) On Line:68 print the resulting data that has been processed by task 1 program and task 2 program. The final data should be a string identifying the processing path of the data from host program, to task 1 program, to task 2 program.
Lines:71-83	Wait for task completion and destroy all task instances and queue instances and finally destroy the MARS context.

Lines:4-6	Define the data entry structure. For this sample this is a 64-byte char array. This is a redefinition of host program Lines:8-10.
Line:11	Grab the host storage address of the queue created in the host program for host to MPU communication from the task arg structure.
Line:12	Grab the host storage address of the queue created in the host program for MPU to MPU communication from the task arg structure.
Line:13	Grab the number of entries this task needs to pop from the queue and process.
Line:14	Declare a local instance of the task queue data entry structure.
Line:16	Loop the number of data entries this task needs to processed specified by the task_args specified at Line:12.
Line:17	Pop data from the queue being sent from the host program to be processed. If the queue is empty by the time of this call, this task will enter a wait state and its context will be switched out. When the host program pushes new data into the queue and is available to be popped by this task, this task will resume execution and continue.
Lines:19-20	Take the data string received from the host program and append a string identifier for this task.
Line:22	Push the processed data into the queue for the task 2 program to receive.

Line:5	Grab the host storage address of the semaphore initialized in the host program from the task arg structure.
Line:6	Grab the host storage address of the shared resource counter declared in the host program.
Line:7	Declare a local instance of the shared resource counter.
Line:9	Attempt to acquire access to the semaphore. int mars_task_semaphore_acquire ( arg1: Pass in the host storage address of the sempahore instance initialized at Line:5. return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) If the semaphore cannot be acquired at the time of this call, this task will enter a wait state and its context will be switched out. When the semaphore is released by another task and available for this task to acquire, this task will resume execution and continue.
Line:11	Memory transfer from host storage to MPU storage the shared resource counter instance. The function "get" shown here is a generic place holder for the platform specific function to do the memory transfer. Please refer to your platform specific API to learn how to do the memory transfer from host storage to MPU storage on your specific platform.
Line:13	Increment the shared resource counter. Since the shared resource is proteced by the semaphore, it is guaranteed that no other tasks have access to the same shared resource during the time this task holds the semaphore.
Line:15	Memory transfer from MPU storage to host storage the modified shared resource counter instance. The function "put" shown here is a generic place holder for the platform specific function to do the memory transfer. Please refer to your platform specific API to learn how to do the memory transfer from MPU storage to host storage on your specific platform.
Line:17	Release the access to the semaphore. int mars_task_semaphore_release ( arg1: Pass in the host storage address of the sempahore instance. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )

Lines:16-17	Create task instances for task 1 program and task 2 program each with context save areas.
Lines:19-20	Initialize the task args we want passed into task 1 program's mars_task_main function. Store the host storage address of the task id structure of task 2. Schedule task 1 for execution.
Lines:22-23	Initialize the task args we want passed into task 2 program's mars_task_main function. Store the host storage address of the task id structure of task 1. Schedule task 2 for execution.
Line:25	Sleep for 1 second before continuing. This allows enough time for the tasks to be scheduled and begin execution. This is only to demonstrate the task entering the wait state when waiting for a signal.
Line:34	Send a signal to task 1 that is waiting for a signal to allow it to continue execution. int mars_task_signal_send ( arg1: Pass in the pointer to the task id instance of the created task we want to signal. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Lines:29-35	Wait for completion and destroy the 2 task instances and finally finalize the MARS context.

Line:6	Declare a local task id instance to store the task 2's id.
Line:8	Memory transfer from host storage to MPU storage the task id instance of task 2. The host storage address of the task id for task 2 is obtained from the task_args passed in from the host program. The function "get" shown here is a generic place holder for the platform specific function to do the memory transfer. Please refer to your platform specific API to learn how to do the memory transfer from host storage to MPU storage on your specific platform.
Line:10	Wait for a signal from the host program before continuing execution. int mars_task_signal_wait ( return: MARS_SUCCESS is returned on success and a negative error value otherwise. ) If a signal has not been set by the time of this call, this task will enter a wait state and its context will be switched out. When the task receives a signal, this task will resume execution and continue.
Line:15	Send a signal to task 2 that is waiting for a signal to allow task 2 execution to resume. int mars_task_signal_send ( arg1:: Address of the local task id instance of task 2. return: MARS_SUCCESS is returned on success and a negative error value otherwise. )
Lines:9-10	Wait for a signal from the task 2 program before continuing execution.

Line:9	Filename of input source image.
Line:10	Filename of output source image.
Line:13	Define the number of the sub task 2 programs as a constant NUM_TASKS. In this tutorial, 4 instances of the sub task are created to allocate the grayscale conversion processing to each.
Line:14	Define the depth of the task queue as a constant QUEUE_DEPTH. In this tutorial, the depth of the task queue is set to 4 in accordance with the number of the sub task instances.
Lines:16-21	Define the structure to store the image information.
Lines:23-31	Define the structure of the parameter set for storing the information to be passed into the main task 1 program.
Lines:33-39	Define the structure for the task queue data element. Each entry in the task queue will be an instance of this structure. The size of this structure must be a multiple of 16 bytes.
Line:51	Declare an instance of the structure we defined at Lines:23-31 for passing parameters to the main task.
Line:54	This function handles the gray scale processing of input image data buffer and outputs the results to the destination buffer.
Lines:58-62	Create the MARS context.
Lines:64-70	Create the task event flag instance for MPU to MPU communication. This will be used by the sub tasks instances to notify the main task that their portion of grayscale processing is completed.
Lines:72-79	Create the task queue instance for MPU to MPU communication. This will be used by the main task to send grayscale processing requests to the sub tasks.
Lines:81-88	Create the task for the main task 1 program. Specify a context save area size of MARS_TASK_CONTEXT_SAVE_ALL to allow the main task to context switch.
Lines:90-99	Create multiple instances for the sub task 2 program. Specify a context save area size of MARS_TASK_CONTEXT_SAVE_ALL to allow the sub tasks to context switch.
Lines:101-107	Initialize the parameters for grayscale conversion processing in the parameter structure declared at Line:51. The parameters stored in this structure are the host addresses of the task ids of the created sub tasks, task event flag and task queue, storage areas for input/output image data, and total number of pixels of image data. The host address of this structure is passed to the main task using the task argument for the main task.
Lines:112-116	Schedule the main task for execution.
Lines:118-122	Wait for the main task to complete execution.
Lines:124-128	Destroy the main task instance.
Lines:130-136	Destroy the sub task instances.
Lines:138-143	Destroy the MARS context.
Lines:146-209	This function reads the input source image file from Line:9 and stores the image data into the structure defined at Lines:16-21.
Lines:212-240	This function writes the output grayscaled image data to the output image file from Line:10.
Lines:242-248	This function cleans up an instance of the image data structure.
Lines:250-263	This is the entry function of the host program that does the following: 1. Read the input image data from input image file. 2. Process the grayscale conversion of input image data. 3. Write the output image data to output image file. 4. Cleanup the image data instance.

Line:7	Define the number of the sub task 2 programs that need to be scheduled for execution. This number should be the same as the one specified in the host program at Line:13.
Lines:11-19	Define the structure for the parameters passed in from the host program. This is a redefinition of the same structure defined in the host program at Lines:23-31.
Lines:21-27	Define the structure for the task queue entry data. This is a redefinition of the same structure defined in the host program at Lines:33-38.
Lines:29-30	Declare an array of task ids and an instance of a task arg structure that will be passed into the sub task.
Lines:32-33	Declare an instance of the parameter structure to be passed in from the host program and an instance of the task queue data entry structure.
Lines:44-46	Memory transfer the grayscale parameter structure from the host storage address specified in the task args sent from the host program.
Lines:48-53	Initialize the local variables with the parameters from the host program.
Lines:56-58	Memory transfer the array of sub task ids from the host storage address specified in the task args sent from the host program.
Line:61	Initialize the task args to pass into the sub task and give it the host address of the task queue.
Lines:64-70	Schedule all the instances of the sub tasks for execution.
Lines:72-103	Partition the source image data evenly to each of the multiple sub task instances. Push the partitioned data into the task queue so that each sub task can pop it and begin processing. The parameters for the partitioned data indicate the host addresses and the number of pixels of the partitioned input/output data and the host addresses of task event flag and the identification numbers of each sub task.
Lines:106-110	Wait for the task event flag event that notifies when all sub tasks have completed their processing. The main task will enter a wait state until the event is received. Note: In this tutorial, the task event flag is used only for example purposes. In this tutorial, the task event flag is only used to notify the main task of sub task completion. Since the main task waits for completion of all sub tasks immediately after waiting for the task event flag, the waiting of the task event flag is not actually necessary.
Lines:113-119	Wait for completion of all sub tasks.

Lines:9-15	Define the structure for the task queue entry data. This is a redefinition of the same structure defined in the host program at Lines:33-38 as well as in the task 1 program at Lines:11-19.
Lines:17-18	Declare instances of the source and destination buffer to store the processing input/output data.
Lines:22-78	This function handles the grayscale processing of the partitioned input image data in the source buffer and stores the output to the destination buffer.
Line:89	Get the host address of the task queue passed in from the main task.
Lines:92-101	Pop the data from the task queue. If the main task has not pushed data into the task queue by the time of this call, this task will enter a wait state and its context will be switched out. When the task is able to pop data from the task queue, this task will resume execution and continue.
Lines:103-107	Initialize the local variables with the parameters from the data popped from the task queue.
Line:110	Loop until all the input data has been processed. Processing of data in each loop iteration is limited by the size of the local buffer sizes specified at Line:7.
Lines:118-120	Memory transfer the input data from host storage to the source buffer declared at Line:17.
Line:123	Do the actual grayscale processing of image data from source buffer to destination buffer.
Lines:126-128	Memory transfer the output data from the destination buffer declared at Line:18 to host storage.
Lines:136-141	Set the task event flag bits specified by this sub task's identification number.