1/*
2 * Copyright 2016, Data61
3 * Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 * ABN 41 687 119 230.
5 *
6 * This software may be distributed and modified according to the terms of
7 * the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 * See "LICENSE_BSD2.txt" for details.
9 *
10 * @TAG(D61_BSD)
11 */
12
13#ifndef _SERVER_COMMON_HELPER_LIBRARY_H_
14#define _SERVER_COMMON_HELPER_LIBRARY_H_
15
16#include <stdio.h>
17#include <stdlib.h>
18#include <stdint.h>
19#include <stdbool.h>
20#include <sel4/sel4.h>
21#include <refos/refos.h>
22#include <refos-util/dprintf.h>
23#include <refos-util/serv_connect.h>
24#include <refos-rpc/data_client.h>
25#include <refos-rpc/data_client_helper.h>
26#include <refos-rpc/proc_common.h>
27
28/*! @file
29    @brief Server common shared helper functions.
30
31    This module implements helper functions to help reduce the work required to get a RefOS server
32    up and running. It handles the most common setup cases for servers, especially dataspace
33    servers, including endpoint creation, registration, and so forth.
34*/
35
36#ifndef CONFIG_REFOS_DEBUG
37    #define printf(x,...)
38#endif /* CONFIG_REFOS_DEBUG */
39
40#define SRV_UNBADGED 0
41#define SRV_DEFAULT_MAX_CLIENTS PROCSERV_MAX_PROCESSES
42#define SRV_DEFAULT_NOTIFICATION_BUFFER_SIZE 0x8000
43#define SRV_DEFAULT_PARAM_BUFFER_SIZE 0x2000
44#define SRV_MAGIC 0x261A2055
45
46#ifndef SET_ERRNO_PTR
47    #define SET_ERRNO_PTR(e, ev) if (e) {(*e) = (ev);}
48#endif
49
50/*! @brief Common server dispatcher message structure.
51
52    Simple structure containing the seL4 message and seL4 badge recieved from the IPC.
53*/
54typedef struct srv_msg {
55    seL4_MessageInfo_t message;
56    seL4_Word badge;
57} srv_msg_t;
58
59
60/*! @brief Enum to keep track of the common server dispatching return values. */
61enum srv_dispatch_return_code_enum {
62    DISPATCH_ERROR = -2,     /*!< A dispatch error has occured. Should not happen. */
63    DISPATCH_PASS,           /*!< Wrong dispatcher. Pass onto another one. */
64    DISPATCH_SUCCESS         /*!< This is the correct dispatcher, or correctly dispatched. */
65};
66
67/*! @brief Common server state configuration.
68
69    This structure stores the server's configuration, including things like name to register under,
70    badge layouts, number of max clients, and so forth. Servers wishing to use this library should
71    fill this config structure with their configuration parameters then pass this into
72    srv_common_init().
73*/
74typedef struct srv_common_config {
75    /*! @brief Maximum number of clients in the client table. Set to 0 to disable. */
76    int maxClients;
77    uint32_t clientBadgeBase; /*!< @brief Client badge number base. */
78    uint32_t clientMagic; /*!< @brief Client structure magic number identifier. */
79
80    /*! @brief Size of death / fault notification buffer. Set to 0 to disable. */
81    int notificationBufferSize;
82    /*! @brief Size of procserv parameter buffer. Set to 0 to disable. */
83    int paramBufferSize;
84
85    /*! @brief Server name, used for debug printing. */
86    char* serverName;
87    /*! @brief Server registration mountpoint. NULL to disable registration. */
88    char* mountPointPath;
89    /*! @brief Server registration parent nameserver, to register under. */
90    seL4_CPtr nameServEP;
91
92    /*! @brief Fault / death async notification badge number. */
93    uint32_t faultDeathNotifyBadge;
94} srv_common_config_t;
95
96struct srv_common;
97typedef struct srv_common srv_common_t;
98
99/*! @brief Common server state structure. */
100struct srv_common {
101    uint32_t magic;
102    srv_common_config_t config;
103
104    /* Endpoints and badges. */
105    seL4_CPtr anonEP;
106    seL4_CPtr notifyAsyncEP;
107    seL4_CPtr notifyClientFaultDeathAsyncEP;
108
109    /* Mapped shared buffers. */
110    data_mapping_t notifyBuffer;
111    size_t notifyBufferStart;
112    data_mapping_t procServParamBuffer;
113
114    /* Client table structure. */
115    struct srv_client_table clientTable;
116
117    /* Default client table handlers. These should provide a simple default implementation for
118       the serv interface defined in the generated <refos-rpc/serv_server.h>. */
119
120    struct srv_client* (*ctable_connect_direct_handler) (srv_common_t *srv, srv_msg_t *m,
121            seL4_CPtr liveness, int* _errno);
122
123    refos_err_t (*ctable_set_param_buffer_handler) (srv_common_t *srv, struct srv_client *c,
124            srv_msg_t *m, seL4_CPtr parambufferDataspace, uint32_t parambufferSize);
125
126    void (*ctable_disconnect_direct_handler) (srv_common_t *srv, struct srv_client *c);
127};
128
129/*! @brief Notification handler callback type. */
130typedef int (*srv_notify_handler_callback_fn_t)(struct proc_notification *notification);
131
132/*! @brief Notification handler callbacks structure. */
133typedef struct srv_common_notify_handler_callbacks {
134    srv_notify_handler_callback_fn_t handle_server_fault;
135    srv_notify_handler_callback_fn_t handle_server_content_init;
136    srv_notify_handler_callback_fn_t handle_server_death_notification;
137} srv_common_notify_handler_callbacks_t;
138
139/*! @brief Initialise server common state.
140    @param s The common server state structure to initialise.
141    @param config The  structure containing info on server configuration.
142    @return ESUCCESS on success, refos_err_t error otherwise.
143*/
144int srv_common_init(srv_common_t *s, srv_common_config_t config);
145
146/*! @brief Helper function to mint a badged server endpoint cap.
147    @param badge The badge ID to mint.
148    @param ep The endpoint to mint from.
149    @return The minted capability (Ownership transferred).
150*/
151seL4_CPtr srv_mint(int badge, seL4_CPtr ep);
152
153/*! @brief Helper function to check recieved caps and unwrapped mask.
154    @param m The recieved message.
155    @param unwrappedMask The expected capability unwrap mask.
156    @param numExtraCaps The expected nubmer of recieved capabilities.
157    @return true if the recieved message capabilities match the unwrapped mask and number, false
158            if there is a mismatck and the recieved caps are invalid.
159*/
160bool srv_check_dispatch_caps(srv_msg_t *m, seL4_Word unwrappedMask, int numExtraCaps);
161
162/*! @brief Server notification dispatcher helper.
163
164    The goal of this helper function is to remove the common shared ringbuffer notification reading
165    and handling routines used by servers wishing to recieve async notifications. When a message
166    is read from the given server state's notification buffer, then the corresponding callback
167    handler function pointer is called.
168
169    @param srv The server common state structure. (No ownership)
170    @param callbacks Struct containing callbacks, one for each possible type of notification.
171                     If the given server does not handle a certain type of notification, simply
172                     set the corresponding callback as NULL.
173    @return ESUCCESS on success, refos_err_t error otherwise.
174*/
175int srv_dispatch_notification(srv_common_t *srv, srv_common_notify_handler_callbacks_t callbacks);
176
177#endif /* _SERVER_COMMON_HELPER_LIBRARY_H_ */